MongoDB

MongoDB is a document database that stores JSON-like (BSON) documents in collections. This sheet covers mongosh, users and roles, indexes, everyday queries, and backup with mongodump and mongorestore from the MongoDB Database Tools.

Documentation: MongoDB Manual · mongosh · Database Tools Project: MongoDB

Verification: the mongodump, mongorestore, mongoexport and mongoimport options were checked against --help from Database Tools 100.20.1. The mongosh options, db.createUser, createIndex and find syntax and the mongo Docker image variables were checked against the MongoDB docs and Docker Hub. mongosh itself was not run. Not verified against the docs: the update, delete, aggregation, getIndexes, dropIndex, explain, db.getUsers and db.changeUserPassword examples (standard shell API, written from knowledge), and the Compose healthcheck. drop, deleteMany and dropDatabase destroy data.

See also: Docker · Docker-Compose · Database Dumps · borgmatic · Redis · PostgreSQL Cheat-Sheet

Run in Docker #

The official mongo image creates a root user in the admin database only when both MONGO_INITDB_ROOT_* variables are set, and then starts with authentication enabled. The variables are ignored if the data directory already holds a database.

services:
  mongo:
    image: mongo:8
    restart: unless-stopped
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD_FILE: /run/secrets/mongo_root_password
    secrets: [mongo_root_password]
    volumes:
      - mongo-data:/data/db
      - mongo-config:/data/configdb
    ports:
      - 127.0.0.1:27017:27017

secrets:
  mongo_root_password:
    file: ./mongo-root-password

volumes:
  mongo-data:
  mongo-config:

docker compose exec mongo mongosh -u root --authenticationDatabase admin

Connect with mongosh #

Avoid --password PASS on the command line (it shows in the process list). Omit the value and mongosh prompts for it.

Shell Helpers #

Queries #

// Insert
db.users.insertOne({ name: "Ada", role: "admin", logins: 3 })
db.users.insertMany([{ name: "Bob" }, { name: "Cy" }])

// Find, filter, project, sort, page
db.users.find()
db.users.find({ role: "admin" })
db.users.find({ logins: { $gt: 1 } }, { name: 1, _id: 0 })
db.users.find().sort({ name: 1 }).skip(10).limit(5)
db.users.findOne({ name: "Ada" })

// Update
db.users.updateOne({ name: "Ada" }, { $set: { role: "owner" }, $inc: { logins: 1 } })
db.users.updateMany({ role: "guest" }, { $set: { active: false } })

// Delete (destroys data)
db.users.deleteOne({ name: "Bob" })
db.users.deleteMany({ active: false })

// Aggregate
db.users.aggregate([
  { $match: { active: true } },
  { $group: { _id: "$role", total: { $sum: 1 } } },
  { $sort: { total: -1 } }
])

A projection cannot mix include and exclude, except for _id.

Users and Roles #

Create users in the database they authenticate against, usually admin for administrators. passwordPrompt() asks for the password instead of putting it in history.

use admin
db.createUser({
  user: "appadmin",
  pwd: passwordPrompt(),
  roles: [{ role: "userAdminAnyDatabase", db: "admin" }]
})

use appdb
db.createUser({
  user: "appuser",
  pwd: passwordPrompt(),
  roles: [{ role: "readWrite", db: "appdb" }]
})

Give applications readWrite on their own database only, and use the backup role for dump jobs. db.createUser is not supported on Atlas clusters.

Indexes #

Syntax is createIndex(<keys>, <options>). Put every option in one document.

db.users.createIndex({ email: 1 }, { unique: true })
db.users.createIndex({ role: 1, logins: -1 })
db.sessions.createIndex({ createdAt: 1 }, { expireAfterSeconds: 3600 })
db.users.createIndex({ email: 1 }, { partialFilterExpression: { active: true }, name: "active_email" })

Backup: mongodump and mongorestore #

mongodump writes BSON and metadata (indexes included). It needs the backup role, and mongorestore needs restore.

In Docker, dump from the host with the tools in a throwaway container, or run them inside the server container:

docker compose exec -T mongo mongodump --username root --authenticationDatabase admin \
  --password "$(cat mongo-root-password)" --archive --gzip > mongo-$(date +%F).archive.gz
docker compose exec -T mongo mongorestore --username root --authenticationDatabase admin \
  --password "$(cat mongo-root-password)" --archive --gzip < mongo-2026-01-01.archive.gz

--archive with no file name writes to stdout (and reads from stdin for mongorestore), which is what makes the redirection work (unverified; the --help text lists --archive=<file-path> only). Test restores into a scratch instance (Restore-Test a Backup).

Export and Import #

mongoexport and mongoimport move JSON or CSV. They lose some BSON types, so use mongodump for backups.

Install the Tools #

The database tools are separate from the server and mongosh. On Ubuntu, download the .deb or .tgz for your release from the Database Tools download page and check the published SHA-256 before installing.

Troubleshooting #

See Also #

• Docker
• Docker-Compose
• Database Dumps
• borgmatic
• Redis
• PostgreSQL Cheat-Sheet