Docs Menu
Docs Home
/
MongoDB Compass

Connect to MongoDB

On this page

This page outlines how to use MongoDB Compass to connect to a MongoDB host. You can connect to a standalone, replica set, or sharded cluster host.

Note

MongoDB Atlas

If you need to create a MongoDB host, consider using MongoDB Atlas. Atlas is a cloud-hosted database-as-a-service which requires no installation, offers a free tier to get started, and provides a copyable URI to easily connect Compass to your deployment.

If you need to install Compass, see Download and Install Compass for instructions.

Considerations

  • When connecting Compass to a replica set, it is not recommended to connect directly to an individual replica set member. If the member to which you are connected switches from a primary member to a secondary or vice versa as the result of an election, Compass may either forcibly close the connection or display stale data.

    Instead, to connect to a replica set, use either the replica set SRV record or Replica Set Name when filling in your connection information.

  • Starting in MongoDB Compass 1.19, Compass displays a warning message when connected to non-genuine MongoDB instances as these instances may behave differently from the official MongoDB instances; e.g. missing or incomplete features, different feature behaviors, etc.

  • Starting in version 1.39.2, MongoDB Compass no longer supports migrating from legacy connection files that pre-date version 1.31.0. Legacy connections refer to an internal Compass connection-options format that is stored on disk and no longer supported after version 1.39.0.

    If you have legacy connections saved in your favorites, export the connections on version 1.39.0 to convert them into the new format before updating to version 1.39.2 or later.

Connect

If your connection name is already in the Connections Sidebar of your Compass window, click on the connection name to connect.

Otherwise, you can connect your deployments by either:

  • Providing your connection string.

  • Specifying Advanced Connection Options. Advanced connection options allow you to specify authentication, TLS/SSL, and SSH connection options. To learn more, see Advanced Connection Options.

Note

Starting in version 1.44.0, you can connect to multiple MongoDB instances at once through Compass.

Provide your Connection String

When you provide a connection string, Compass supports most Connection String Options supported by MongoDB.

By default, Compass's default socketTimeoutMS value is 60000, or 60 seconds. If you are frequently experiencing timeouts in Compass, consider setting this option to a higher value in your connection string.

For a complete list of the connection string options that Compass supports, see the Compass Connection README on GitHub.

1

Open the New Connection modal.

In the bottom panel of the Connections Sidebar, click Add New Connection to open the New Connection modal.

If you already have connections listed in the Connections Sidebar, click the icon on the top right of the sidebar to open the New Connection modal.

2

Paste your connection string.

If you have the connection string for your deployment available, you can paste the string directly into the dialog box. You can use either the Standard Connection String Format or the DNS Seedlist Connection Format.

To obtain the connection string for an Atlas cluster:

  1. Navigate to your Atlas Clusters view.

  2. Click Connect for your desired cluster.

  3. Click Connect with MongoDB Compass.

  4. Copy the provided connection string.

Warning

If you click into the MongoDB Compass connection form to edit your connection string, Compass shows credentials in plaintext by default.

To edit your connection string credentials without exposing your password, use the Advanced Connection Options > Authentication tab on the Compass connection form.

To learn how to format the connection string for a deployment that is not hosted on Atlas, see Connection String URI Format.

3

(Optional). Name your connection.

Use the name field to enter a name for your connection. If you do not specify a name, Compass uses the cluster's hostname as the connection name.

4

(Optional). Choose a color for your connection.

Use the color drop-down menu to select a label color for your connection. When you connect to a connection, the label color is the background color of tabs that reference your connection.

5

(Optional). Favorite your connection.

If you want to save the connection as a favorite, check the Favorite this connection option in the modal.

6

Connect to your cluster.

To navigate to the Compass Home Page, click Save, Connect, or Save & Connect.

  • The Save button saves your connection and closes the modal without yet connecting to your cluster.

  • The Connect button allows you to connect to your cluster without saving your connection string or credentials.

  • The default Save & Connect button both saves your information and connects you to your cluster.

Important

Required Access

Once you are connected to your MongoDB deployment, you may require specific user roles to access various Compass features. For more information on the required roles for Compass features, see Required Access.

Use Advanced Connection Options

The advanced connection options provide additional ways to connect Compass to MongoDB. Advanced connection options allow you to specify authentication, TLS/SSL, and SSH to securely connect to your deployment.

For details on how to specify connection options using Compass, see Advanced Connection Options.

Connect to Compass from the Command Line

You can start a Compass session from the command line.

In enterprise environments, a scripted start can make it easier to deploy Compass. For example, to limit access to sensitive systems, you can configure a command line start so that Compass can run on a jump host.

To connect to Compass using the command line, you can include your connection options directly in your connection string or as command line arguments.

To specify connection options in your connection string, use the following format:

mongodb-compass 'mongodb://username:password@hostname:port/database?ssl=true&replicaSet=myReplicaSet'

For more connection string options, see Connection String Options.

To specify connection options as command line arguments, use the following format:

<path/to/compass/executable> <connection string> --username <username> --password <password>

For more command line argument connection options, see Start Compass from the Command Line.

See also:

To learn how to disconnect your deployment, see Disconnect from MongoDB

Connection String Examples

The following examples highlight some advanced connection string options. For information on all connection string options, see Connection String Options.

TLS Options

The following connection string enables TLS using the tls URI option. tlsCertificateKeyFile specifies the path to the client certificate and private key. Specifying the tlsCertificateKeyFile in your connection string is optional, unless the server requires client certificates, or if you are using X.509 authentication.

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com/?directConnection=true&tls=true&tlsCAFile=path/to/rootCA.crt&tlsCertificateKeyFile=path/to/server_certificate.pem

To enable SSL, use the equivalent ssl=true option in place of tls=true.

X.509 Authentication

The following example demonstrates how to specify X.509 authentication in your connection string using the authMechanism connection string option:

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db1.example.com/?authMechanism=MONGODB-X509&tls=true&tlsCertificateKeyFile=/path/to/client_certificate.pem

LDAP

The following example specifies LDAP authentication. It sets authMechanism to plain to specify the use of the LDAP authentication mechanism and sets authSource to $external to indicate that the authentication database is $external.

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db2.example.com/?authMechanism=PLAIN&authSource=$external

Kerberos

The following example specifies Kerberos authentication. It sets authMechanism to GSSAPI to use the Kerberos authentication mechanism and sets authSource to $external to indicate that the authentication database is $external.

mongodb://myDatabaseUser@db3.example.com/?authMechanism=GSSAPI&authSource=$external

Read/Write Preferences

To enable read/write preferences in your connection string, you can use the readPreference option for read preferences and the w option for write concerns.

The following connection string sets both read and write preferences. readPreference=secondary specifies that read operations should be directed to secondary members of the replica set and w=majority ensures that write operations are acknowledged by the majority of the replica set members.

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db4.example.com/database?readPreference=secondary&w=majority

Analytic Nodes

To specify an analytics node type in your connection string:

  • Set your readPreference to secondary to specify that the read operations should be directed to secondary nodes.

  • Set readPreferenceTags to nodeType:ANALYTICS to ensure that the read operations are directed specifically to the analytic nodes.

The following connection string demonstrates how to specify an analytics node type in your connection string:

mongodb+srv://myDatabaseUser:D1fficultP%40ssw0rd@db5.example.com/myDatabase?readPreference=secondary&readPreferenceTags=nodeType:ANALYTICS

For more information on using analytics nodes to isolate workloads, see Query using Pre-Defined Replica Set Tags.

Back

Edition Capabilities

Next

Connections Sidebar