> ## Documentation Index
> Fetch the complete documentation index at: https://doc.trycapsule.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# MongoDB

> Connect and back up MongoDB databases with Capsule.

## Required tools

Capsule uses `mongodump` (from MongoDB Database Tools) and `mongosh` to connect and restore.

<Tabs>
  <Tab title="Debian / Ubuntu">
    Install MongoDB Database Tools directly from MongoDB's package repo — **not** via `apt` (the `apt` package is outdated and may be missing `mongodump`):

    ```bash theme={null}
    # Import MongoDB public key
    curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | \
      sudo gpg --dearmor -o /usr/share/keyrings/mongodb-server-7.0.gpg

    # Add the repo (Ubuntu 22.04 example)
    echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ] \
      https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | \
      sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list

    sudo apt-get update
    sudo apt-get install -y mongodb-database-tools mongosh
    ```
  </Tab>

  <Tab title="RHEL / CentOS / Amazon Linux">
    ```bash theme={null}
    # Add MongoDB repo
    cat <<EOF | sudo tee /etc/yum.repos.d/mongodb-org-7.0.repo
    [mongodb-org-7.0]
    name=MongoDB Repository
    baseurl=https://repo.mongodb.org/yum/redhat/\$releasever/mongodb-org/7.0/x86_64/
    gpgcheck=1
    enabled=1
    gpgkey=https://www.mongodb.org/static/pgp/server-7.0.asc
    EOF

    sudo yum install -y mongodb-database-tools mongosh
    ```
  </Tab>
</Tabs>

<Warning>
  Do not use `brew tap mongodb/brew` on Linux — it installs macOS binaries that cannot run on Linux and will produce an `exec format error`.
</Warning>

Verify:

```bash theme={null}
capsule doctor
```

***

## Connection details

| Field         | Example                                |
| ------------- | -------------------------------------- |
| Host          | `localhost`                            |
| Port          | `27017`                                |
| Database name | `myapp`                                |
| Username      | `myapp_user` (leave blank if no auth)  |
| Password      | your password (leave blank if no auth) |

***

## Authentication

If your MongoDB instance uses authentication, provide the username and password. Capsule builds a `mongodb://` connection URI (with your credentials embedded and URL-encoded) and passes it to `mongodump` via `--uri`.

<Note>
  Unlike the PostgreSQL and MySQL integrations, this URI is passed as a plain command-line argument — for the duration of the backup, it's visible to anyone on the same server who can run `ps aux` or read `/proc/<pid>/cmdline` on that process. If you're on a server shared with other users you don't fully trust, keep this in mind.
</Note>

***

## Replica sets and Atlas

For a replica set, enter any member's host in the Host field. Capsule does not force a direct, single-node connection — `mongodump` will attempt normal replica set topology discovery from that seed host, the same as connecting with any standard MongoDB client. This means the other replica set members need to be reachable (by whatever hostname the replica set itself advertises them as) from the machine running Capsule, not just the one host you entered.

For MongoDB Atlas, use the connection hostname from your Atlas dashboard (e.g., `cluster0.abcde.mongodb.net`) — Capsule detects the `.mongodb.net` suffix and automatically uses the `mongodb+srv://` scheme instead of a plain host:port, which is what Atlas's DNS-seedlist connection format requires.

***

## Docker

If MongoDB runs in a container, enter the container name when adding the connection. Capsule will exec `mongodump` inside the container via `docker exec`.

***

## Troubleshooting

**`mongodump: command not found`**

The `mongodb-database-tools` package is separate from the MongoDB server. Install it explicitly and run `capsule doctor` to confirm.

**`mongosh: command not found`**

`mongosh` is a separate package from `mongodb-database-tools`. Install it alongside the tools (see installation steps above).

**Auth failed**

Ensure the user has the `backup` built-in role or equivalent read access on the target database.