MongoDB

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.

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.

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, create a user with only readAnyDatabase:

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.

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 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 has its own TLS settings and Extra Parameters. Set them the same way as for the admin connection.

Introduction

Quick Start

Bytebase Essentials

Install

Connect Databases

Onboarding Guides

Supported versions

Create a user for Bytebase

Connection details

Hostname

Port

Connection String Schema

Additional Node Addresses

Replica Set

Direct Connection

Username

Password

Authentication Database

TLS

Extra Parameters

Troubleshooting

Read-only connection

​Supported versions

​Create a user for Bytebase

​Connection details

​Hostname

​Port

​Connection String Schema

​Additional Node Addresses

​Replica Set

​Direct Connection

​Username

​Password

​Authentication Database

​TLS

​Extra Parameters

​Troubleshooting

​Read-only connection

Supported versions

Create a user for Bytebase

Connection details

Hostname

Port

Connection String Schema

Additional Node Addresses

Replica Set

Direct Connection

Username

Password

Authentication Database

TLS

Extra Parameters

Troubleshooting

Read-only connection