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

# MongoDB

> Connect Bytebase to MongoDB, including replica sets, SRV connection strings, and verified TLS.

To add a MongoDB database, go to **Instances**, click **Connect instance**, and choose **MongoDB**.

Bytebase lists every database on the server except `admin`, `config`, and `local` as a Bytebase database. See [Database](/concepts/database).

## Supported versions

Bytebase supports MongoDB 4.2 and later. It connects through a built-in driver, so there is nothing to install.

## Create a user for Bytebase

On a self-managed deployment, connect with `mongosh` as a user administrator and create a dedicated user. The examples name it `bytebase`.

```javascript theme={null}
use admin
db.createUser({
  user: "bytebase",
  pwd: passwordPrompt(),
  roles: [
    { role: "readWriteAnyDatabase", db: "admin" },
    { role: "dbAdminAnyDatabase", db: "admin" },
    { role: "userAdminAnyDatabase", db: "admin" }
  ]
})
```

The user is defined in `admin`, so leave **Authentication Database** empty.

For a [read-only connection](#read-only-connection), create a user with only `readAnyDatabase`:

```javascript theme={null}
use admin
db.createUser({
  user: "bytebase_readonly",
  pwd: passwordPrompt(),
  roles: [{ role: "readAnyDatabase", db: "admin" }]
})
```

On MongoDB Atlas, create the user in the Atlas UI instead, because Atlas rolls back users created with `db.createUser`. Under **Security**, click **Database & Network Access**, open the **Database Users** tab, and click **Add New Database User**. Choose **Password**, then pick **Atlas admin** under **Built-in Role**, or **Only read any database** for the read-only user.

## Connection details

### Hostname

The host name or IP address of a MongoDB server, such as `db.example.com`. With **mongodb+srv://**, enter the deployment's DNS name instead, such as `cluster0.example.com`. With **Verify server certificate** on, the host name must be one of the names in the server's certificate.

### Port

The server port. MongoDB's default is `27017`. With **mongodb+srv://**, the ports come from DNS, so the field isn't available.

### Connection String Schema

* **mongodb://**: Bytebase connects to the hosts you enter.
* **mongodb+srv://**: Bytebase looks up the hosts in the DNS SRV record for **Hostname**, as MongoDB Atlas connection strings do. Choosing it clears **Port**, **Additional Node Addresses**, **Replica Set**, and **Direct Connection**.

### Additional Node Addresses

Other hosts of the same deployment. Bytebase tries them all, so it can connect while the first host is down.

### Replica Set

The name of the replica set, such as `rs0`. Bytebase finds the members and works with the primary.

### Direct Connection

Connects only to the host you entered, without finding the other members of the replica set. Use it to reach one member on its own.

### Username

The MongoDB user Bytebase connects as.

### Password

The user's password. You can also read it from a [secret manager](/get-started/connect/overview#secret-manager-integration).

### Authentication Database

The database where the user is defined. If you leave it empty, Bytebase uses `admin`. Set it for a user created in another database.

### TLS

**TLS mode** decides whether Bytebase encrypts the connection:

* **Disabled**: the connection is unencrypted.
* **TLS**: Bytebase encrypts the connection.
* **Mutual TLS**: the same as **TLS**, and Bytebase also presents a client certificate, for servers that require one.

Under **Server identity**, turn on **Verify server certificate** so that Bytebase checks the server's certificate and confirms that **Hostname** is one of the names in it. **CA certificate source** sets which certificate authority (CA) the check trusts:

* **System trust**: the CAs that the machine running Bytebase already trusts.
* **Paste PEM**: a CA certificate you paste in PEM format, for a private CA or a self-signed certificate.
* **File path**: a CA certificate file on the Bytebase server. Not available in Bytebase Cloud.

With verification off, the connection is encrypted, but Bytebase doesn't check which server it reached. Use that only for testing.

For **Mutual TLS**, set **Client identity source** to **Paste PEM** or **File path**, and provide the client certificate and its private key.

### Extra Parameters

[Connection string options](https://www.mongodb.com/docs/manual/reference/connection-string-options/) that Bytebase adds to the URI, such as `readPreference`. Set TLS in the **TLS** section instead: `tls` with the value `true` here checks the server only against the CAs that the machine running Bytebase trusts.

## Troubleshooting

**Test Connection** shows the error from the server or the driver:

| Error | Cause | Fix |
| - | - | - |
| `SSL cert failed to verify: x509: certificate signed by unknown authority` | Verification is on, and the CA from **CA certificate source** didn't sign the server's certificate. | Paste the CA that signed the server's certificate, or point to it. |
| `tls: failed to verify certificate: x509: certificate signed by unknown authority` | `tls` in **Extra Parameters** checks the server against the system's trusted CAs only. | Remove `tls` from **Extra Parameters**, and set up TLS in the **TLS** section. |
| `SSL cert failed to verify: x509: certificate is valid for …, not …` | **Hostname** isn't one of the names in the server's certificate. | Use a name from the certificate, or have the certificate reissued. |
| `connection closed unexpectedly by the other side: EOF` | The server requires TLS and **TLS mode** is **Disabled**, or it requires a client certificate and **TLS mode** isn't **Mutual TLS**. | Set **TLS mode** to **TLS**, or to **Mutual TLS** with a client certificate. |
| `(AuthenticationFailed) Authentication failed.` | The password is wrong, or the user is defined in a database other than **Authentication Database**, which defaults to `admin`. | Check the password, and set **Authentication Database** to the user's database. |
| `lookup _mongodb._tcp.… : no such host` | **mongodb+srv://** is selected, and **Hostname** has no DNS SRV record. | Use the SRV host name from your provider, or choose **mongodb://**. |
| `server selection error: … ReplicaSetNoPrimary` | **Replica Set** doesn't match the name of the replica set, or Bytebase can't reach the primary. | Check the replica set name. To reach one member on its own, use **Direct Connection**. |
| `ssl_cert and ssl_key must be both set or unset` | Only one of the client certificate and its private key is set. | Provide both. |

## Read-only connection

A [read-only connection](/get-started/connect/overview#read-only-connections) has its own TLS settings and **Extra Parameters**. Set them the same way as for the admin connection.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.