Navigation

Connect to MongoDB

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.

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.

  • If you are using Kerberos as your authentication mechanism, do not specify the Password in the connection form.

  • 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.

Connect

When you open Compass, an initial connection dialog appears:

../_images/paste-connection-string.png

Compass provides two methods to connect to your deployment, either providing your deployment connection string or filling in your deployment information in specific fields.

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 which Compass supports, see the Compass Connection README on GitHub.

1

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.
  • To learn how to format the connection string for a deployment which is not hosted on Atlas, see Connection String URI Format.
2

Connect.

Click the Connect button to navigate to the Compass Home Page.

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.

1

Open the individual connection fields view.

To manually fill in individual connection fields, click Fill in connection fields individually:

../_images/fill-connection-fields.png
2

Enter your connection information.

The Hostname dialog contains the following connection field options:

Option Description
Hostname

Hostname of the machine where the deployment is running.

If you are running your deployment locally, this value is localhost. If you are connecting to an Atlas cluster, you can get your hostname from your cluster detail view in Atlas.

If you are not sure of your hostname, contact your Database Administrator for information.

Port

Port on which the deployment is running. Not required if you are using an SRV Record to connect to your MongoDB deployment.

By default, a standalone deployment operates on port 27017. If you are connecting to a replica set, your port may also be 27018 or 27019. For more information on the default ports MongoDB operates on, see Default MongoDB Port.

If you are not sure of the port where your deployment operates, contact your Database Administrator for information.

SRV Record

Indicates whether the provided Hostname is an SRV Record. If this toggle is enabled, you do not need to specify a port.

Note

You can only use SRV connection strings to connect to deployments running MongoDB 3.6 and later.

SRV connection strings have a prefix of mongodb+srv:. If you are using an SRV connection string, you do not need to include mongodb+srv in your Hostname.

Example

If the following is your SRV connection string for your MongoDB deployment:

mongodb+srv://<username>:<password>@gettingstarted-7q2cs.mongodb.net/test

Then, in Compass, you would specify your Hostname as:

gettingstarted-7q2cs.mongodb.net
Authentication

Authentication to use if the deployment requires authentication. Atlas clusters use Username / Password authentication.

Select your authentication method from the tabs below for specific instructions:

Select Username / Password if the deployment uses either MongoDB-CR or SCRAM-SHA-1 as its authentication mechanism.

Provide the Username, Password, and Authentication Database to authenticate the user.

Note

Starting in MongoDB version 4.0, MongoDB removes support for the deprecated MongoDB Challenge-Response (MONGODB-CR) authentication mechanism.

Select SCRAM-SHA-256 if the deployment uses SCRAM-SHA-256 as its authentication mechanism (New in MongoDB 4.0). If selected, you must provide the Username, Password, and Authentication Database to authenticate the user.

For more information on the SCRAM authentication mechanism, see SCRAM.

Important

Kerberos Authentication is not available in Compass Community Edition.

Select Kerberos if the deployment uses Kerberos as its authentication mechanism. If selected, you must provide the Principal and Service Name to authenticate the user. Leave the Password field blank.

You can also direct MongoDB Compass to Canonicalize the Host Name by setting the corresponding toggle. When you enable this setting, Kerberos uses the canonicalized form of the host name (cname) when constructing the principal for MongoDB Compass.

For more information on principal name canonicalization in Kerberos, see this RFC document.

Important

LDAP Authentication is not available in Compass Community Edition.

Select LDAP if the deployment uses LDAP as its authentication mechanism. If selected, you must provide the Username and Password to authenticate the user.

Important

X.509 Authentication is not available in Compass Community Edition.

Select X.509 if the deployment uses X.509 as its authentication mechanism. If selected, you must provide the Username to authenticate the user.

Note

If you are using Atlas-managed certificates , your username must be prefaced by “CN=” per RFC 2253. For example, the username “X509User” must be provided as “CN=X509User”.

Favorite Name

Optional. A name for the connection. To save the current connection entered as a favorite connection, enter a name in the input and click Create Favorite.

Tip

Although you can save multiple connections with the same Favorite Name, it is recommended to use unique names for each connection to easily find your saved connections.

3

(Optional) Specify replica set and security connection options.

The More Options connection screen allows you to specify the following connection options:

Option Description
Replica Set Name If your MongoDB deployment is a replica set, specify the replica set name. Not required if you specify your replica set Hostname as an SRV Record.
Read Preference

Specifies how Compass directs read operations. Options are:

  • Primary,
  • Primary Preferred,
  • Secondary,
  • Secondary Preferred, and
  • Nearest.

To learn more about read preferences, see Read Preference.

If you are connecting to your deployment using TLS/SSL or an SSH tunnel, refer to the following tabs for specific instructions:

This option directs Compass to connect to your MongoDB deployment via TLS/SSL. You can select one of the following SSL options:

Option Description
System CA/Atlas Deployment Connect to MongoDB Atlas.
Server Validation

Compass validates the identity of the deployment. If selected, you must provide:

Certificate Authority One or more certificate files from trusted Certificate Authorities to validate the certificate provided by the deployment.
Server and Client Validation

The deployment performs certificate validation from its clients and Compass validates the identity of the deployment. If selected, you must provide:

Certificate Authority File One or more certificate files from trusted Certificate Authorities to validate the certificate provided by the deployment.
Client Certificate A TLS/SSL certificate to present to mongod to verify the identity of the Compass client. Typical file extensions for the certificate are .crt or .pem.
Client Private Key A TLS/SSL key file to mongod to verify the identity of the Compass client. Typical file extensions for the private key are .key or .pem.
Client Key Password If the Client Private Key is protected with a password/passphrase, you must provide the password/passphrase.
Unvalidated (Insecure) Use TLS/SSL without any identity validation.

Tip

For production use, your MongoDB deployment should use valid certificates generated and signed by a single certificate authority. You or your organization can generate and maintain an independent certificate authority, or use certificates generated by a third-party TLS/SSL vendor.

This option directs Compass to connect to your MongoDB deployment via an SSH tunnel. The tunnel automatically starts when you connect to MongoDB and stops when you disconnect.

In the SSH Tunnel dropdown, choose either a password or an identity file to provide authentication. Once you select your identification method, specify the following options:

SSH Hostname Enter the bastion (jumpbox) hostname. This is the unique identifier (Fully Qualified Domain Name, or FQDN) for the machine to be accessed.
SSH Tunnel Port Provide the port used for the SSH connection. This defaults to 22, the standard port for SSH.
SSH Username The username of the profile to log into on the remote system. This will be the user for which you want to establish the SSH connection.
SSH Identity File

Select the file from which the identity (private key) for SSH public key authentication is read.

Unix or OS X: If using OpenSSH, identity files are found in the ~/.ssh directory. By default, the private key files have one of the following file names:

  • id_dsa
  • id_ecdsa
  • id_ed25519
  • id_rsa

On Windows, the location of the identify files depends on your choice of SSH client, such as PuTTY.

SSH Passphrase If your private key is encrypted, provide the passphrase used to decrypt your private key (stored in the specified identity file). A passphrase provides an extra layer of security for an SSH connection.
SSH Password The password used to secure the SSH connection. This is required if you are not using an identity file.

To use an SSH tunnel through a bastion host, the SSH configuration on the bastion host must allow TCP port forwarding; i.e., the AllowTcpForwarding directive in the /etc/ssh/sshd_config file is set to yes. If AllowTcpForwarding is not set to yes, set to yes and restart the SSH daemon (sudo service sshd restart).

Instead of creating the SSH tunnel through the Compass UI, you can also create the tunnel manually from the command line:

ssh -L <local_port>:<mongodb_hostname>:<mongodb_port> \
   <user>@<bastion_hostname> -fN

Example

If you have a deployment running on hostname-a.com on port 27017, and the bastion host is hostname-b.com with user name ec2-user, you can build the tunnel via

ssh -L 27000:hostname-a.com:27017 ec2-user@hostname-b.com -fN

Using this SSH tunnel, you can now connect Compass (or the mongo shell) to localhost:27000 to connect to the deployment running on hostname-a.com.

Note

You cannot connect to a replica set via an SSH tunnel. Compass cannot establish a connection to multiple servers across the same SSH tunnel.

4

Connect.

Click the Connect button to navigate to the Compass Home Page.

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.

Note

MongoDB Compass securely stores sensitive information entered in the connection form using an API that is specific to your operating system.

For more information on how Compass handles sensitive data, refer to the FAQ page.

Disconnect

1

Click Connect in the menu bar.

2

Select Disconnect from the dropdown menu.

Disconnect menu item

Disconnecting from a MongoDB instance closes the Compass connection to the active instance and returns the Compass view to the initial connection dialog.