Navigation

Connect to MongoDB

Connect

1

Enter connection information.

Once you have installed Compass and the program is running, an initial connection dialog appears:

../_images/connect-to-host.png

Tip

Starting with version 1.8.0, MongoDB Compass can detect whether you have a MongoDB URI connection string in your system clipboard and auto-populate the connection dialog from the URI. Open MongoDB Compass with a URI connection string in your clipboard and click Yes when prompted to auto-populate the dialog.

Hostname The hostname of the machine where the mongod instance is running.
Port The port on which mongod is running.
Authentication

The authentication to use if the mongod instance requires authentication. Select your authentication method from the tabs below for specific instructions:

Select Username / Password if the mongod instance uses either MongoDB-CR or SCRAM-SHA-1 as its authentication mechanism. If selected, you must 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 mongod instance 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.

Not Available in Compass Community Edition

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

Not Available in Compass Community Edition

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

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

Not Available in Compass Community Edition

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

For MongoDB permissions required to access Compass, see Required Access.

Replica Set Name The name of the MongoDB replica set to which you want to connect.
Read Preference Specifies how Compass directs read operations. Options are Primary, Primary Preferred, Secondary, Secondary Preferred, and Nearest. See Read Preference.
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. For more information on favorite connections, see the Favorite Connections documentation.

Note

The Create Favorite button only appears once you have entered text into the Favorite Name input.

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 desired connections.

Hostname The hostname of the machine where the mongod instance is running.
Port The port on which mongod is running.
Authentication

The authentication to use if the mongod instance requires authentication. Select your authentication method from the tabs below for specific instructions:

Select Username / Password if the mongod instance uses either MongoDB-CR or SCRAM-SHA-1 as its authentication mechanism. If selected, you must 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 mongod instance 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.

Not Available in Compass Community Edition

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

Not Available in Compass Community Edition

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

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

Not Available in Compass Community Edition

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

For MongoDB permissions required to access Compass, see Required Access.

Replica Set Name The name of the MongoDB replica set to which you want to connect.
Read Preference Specifies how Compass directs read operations. Options are Primary, Primary Preferred, Secondary, Secondary Preferred, and Nearest. See Read Preference.
SSL

Select whether Compass should connect to the target host via TLS/SSL or not. Select:

  • Use System CA/Atlas Deployment to connect to MongoDB Atlas.

  • Server Validation to have Compass validate the identity of the mongod instance. If selected, you must provide

    Certificate Authority File One or more certificate files from trusted Certificate Authorities to validate the certificate provided by the mongod instance.
  • Server and Client Validation if the mongod performs certificate validation from its clients and to have Compass validate the identity of the mongod instance. If selected, you must provide

    Certificate Authority File One or more certificate files from trusted Certificate Authorities to validate the certificate provided by the mongod instance.
    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 to 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.

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. For more information on favorite connections, see the Favorite Connections documentation.

Note

The Create Favorite button only appears once you have entered text into the Favorite Name input.

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 desired connections.

Important

Although MongoDB Compass supports connecting to a MongoDB instance through an SSH tunnel via TLS/SSL, this configuration may lead to unexpected behavior when connecting to a member of a replica set. Using this configuration, 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.

Hostname The hostname of the machine where the mongod instance is running.
Port The port on which mongod is running.
Authentication

The authentication to use if the mongod instance requires authentication. Select your authentication method from the tabs below for specific instructions:

Select Username / Password if the mongod instance uses either MongoDB-CR or SCRAM-SHA-1 as its authentication mechanism. If selected, you must 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 mongod instance 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.

Not Available in Compass Community Edition

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

Not Available in Compass Community Edition

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

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

Not Available in Compass Community Edition

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

For MongoDB permissions required to access Compass, see Required Access.

Replica Set Name The name of the MongoDB replica set to which you want to connect.
Read Preference Specifies how Compass directs read operations. Options are Primary, Primary Preferred, Secondary, Secondary Preferred, and Nearest. See Read Preference.
SSH tunnel

Select whether Compass should connect to a MongoDB cluster via an SSH tunnel, which automatically starts when you connect to MongoDB, and stops when you disconnect. If selected, choose either a password or an identity file to provide authentication.

Enter information for the SSH tunnel.

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 mongod instance running on (internal) 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 mongod instance 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. When you select an SSH Tunnel option in the connection form, Compass hides the Replica Set Name and Read Preference fields in the form.

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. For more information on favorite connections, see the Favorite Connections documentation.

Note

The Create Favorite button only appears once you have entered text into the Favorite Name input.

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 desired connections.

Important

Although MongoDB Compass supports connecting to a MongoDB instance through an SSH tunnel via TLS/SSL, this configuration may lead to unexpected behavior when connecting to a member of a replica set. Using this configuration, 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.

Note

MongoDB Compass securely stores sensitive information entered in the connection form using an operating system-specific credentials API. For more information on how Compass handles sensitive data, refer to the FAQ page.

2

Connect.

When you have finished filling out the connection information, click the Connect button to navigate to the Compass Home Page.

The home page ⌂ provides details regarding the MongoDB instance to which Compass is connected. It shows the hostname and port, the deployment’s MongoDB version, and a list of the deployment’s databases. For more information on this page, see Compass Home.

Favorite Connections

MongoDB Compass allows you to save MongoDB connection configurations to easily reconnect to the same MongoDB deployment using the same specifications. To load a favorite connection into the Connect form, click the desired connection in the Favorites list to the left of the form.

Edit a Favorite Connection

To edit a saved favorite connection:

  1. Load the connection into the Connect form.
  2. Make the desired changes to the connection configuration within the form.
  3. Click Save Favorite at the bottom of the form.

Note

You can use this process to edit the name of a favorite connection.

Delete a Favorite Connection

To delete a saved favorite connection:

  1. Load the connection into the Connect form.
  2. Click Delete Favorite at the bottom of the form.

MongoDB Compass removes the connection from the Favorites list and returns to the New Connection view.

Required Access

With authentication/authorization enforced on the connected MongoDB instance, the user requires appropriate privileges to access various features. The following table lists the privileges required to access the features as well as the built-in roles that can provide these privileges:

Note

The built-in roles may provide more access than required. You can also create a User-Defined Roles to grant specific privileges.

View Feature/Action Privilege(s) MongoDB Built-In Role
Home/MongoDB Instance Performance clusterMonitor
Database Create a Database createCollection readWrite
Database Drop a Database dropDatabase dbAdmin
Collection Create a Collection createCollection readWrite
Collection Drop a Collection dropCollection readWrite
Schema Query/View find read
Documents Query/View find read
Documents Clone, insert, update, delete readWrite
Indexes View listIndexes read
Indexes Create, drop readWrite
Explain Plan Query/View find read
Validation View rules listCollections read
Validation Update rules collMod dbAdmin

Disconnect

To disconnect from a MongoDB instance in Compass:

  • Click Connect in the menu bar, then
  • Select Disconnect from the dropdown menu
../_images/disconnect.png

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