Connection Manager

Four ways to connect to MongoDB

Studio 3T provides four ways to connect to a MongoDB server. You can:

• Paste a MongoDB connection string or URI
• Import connection details automatically from other clients (e.g. Robo 3T)
• Import a URI file
• Enter connection details manually

Paste a URI or connection string (e.g. from MongoDB Atlas)

Hosters like MongoDB Atlas, Compose, mLab, ObjectRocket, and ScaleGrid provide the MongoDB URI or connection string from their respective interfaces.

Studio 3T supports the two connection string formats: Standard and DNS Seedlist.

The standard connection string format looks like:

mongodb://[username:[email protected]]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]

While the DNS Seedlist connection format uses a different +srv prefix:

mongodb+srv://server.example.com/?connectTimeoutMS=300000&authSource=aDifferentAuthDB

Once you have your connection string ready, click on the Connect button from the global toolbar and choose New Connection.

Or click on Create a new connection from the Quickstart tab.

This will open the New Connection window. By default, you will land on the Server tab.

Name the connection then click on From URI.

Paste the connection string and click OK.

Regardless of the connection type chosen, Studio 3T will automatically extract the information and pre-populate the fields in the Server, Authentication, SSL, SSH Tunnel, and Advanced tabs. It will also save the connection for later use.

Import connections from Robo 3T (Robomongo), NoSQLBooster, and other clients

Studio 3T automatically detects and imports connection details – including SSH credentials – already saved in other clients like Robo 3T and NoSQLBooster.

Simply click on Import in the toolbar and Studio 3T will list the auto-detected connections in the Import Connections window.

Import a URI file

To import a URI file, click on the Connect button in the global toolbar or Open Connection Manager under the Quickstart tab. This will open the Connection Manager.

Click on Import. Then, choose Open Connection URI File.

Choose your .uri file and click Import.

Enter connection details manually

In the following chapters, we’ll walk you through how to connect manually to the four supported connection types: standalone connection, replica set, sharded cluster, and DNS seedlist.

Test MongoDB connection

You can always test a connection by clicking on Test Connection.

Note that in most cases (e.g. connecting to MongoDB Atlas), Detecting MongoDB server feature compatibility version will be N/A, but you will still be able to save and connect successfully.

Connect to a standalone connection (e.g. MongoDB localhost)

Let’s try to connect to localhost (which runs on default port 27017) as an example of a standalone connection.

Open the Connection Manager, name the connection, and choose Standalone from the dropdown.

Fill out the Server and Port fields and click Save.

This saves the connection for later use in the Connection Manager. Finally, click on Connect.

If you require additional configuration (e.g. SSH, SSL), skip ahead to the Configure your MongoDB connection chapter.

Connect to a replica set

Choose Replica set from the dropdown menu. This will display the Members section.

Click on Add to define the additional replica set members, then click OK. Add or remove members as needed.

Next, type the Replica Set Name and choose the Read Preference mode.

Per MongoDB’s documentation:

Configure any additional authentication, SSL, SSH, etc. settings, click Save, then click on Connect.

Connect to a sharded cluster

Select Sharded cluster from the dropdown menu. This will open the Hosts section.

In case you were wondering what the difference is between a replica set and a sharded cluster, here’s a handy StackExchange answer.

Click on Add to add new hosts or Remove to delete them as needed. Then, choose the Read Preference.

Set up any needed configuration under the Authentication, SSL, SSH, Proxy, MongoDB Tools, and Advanced tabs, click Save, then Connect.

Connect to a DNS seedlist

The DNS connection seedlist was introduced in MongoDB 3.6 and is now the default connection string format from hosting providers like MongoDB Atlas.

Choose DNS seedlist from the dropdown and fill out the Server, Replica Set, and Read Preference fields.

Finish setting up your connection under the Authentication, SSL, SSH, Proxy, MongoDB Tools, and Advanced tabs as needed.

Click Save. Then, click Connect.

Configure your MongoDB connection

The Connection Manager has seven tabs – Server, Authentication, SSL, SSH, Proxy, MongoDB Tools, and Advanced tabs – where you can configure the rest of your connection setup.

Server settings

Under the Server tab, you can also enable other settings like read-only lock, color-coding, and grouping connections into folders.

Group MongoDB connections into folders

You can group connections into folders in Connection Manager  to help declutter your view.

To create a group, click on New Group in the Connection Manager, name the group, and click OK.

This saves the connection group, which you could select from the Connection group dropdown in the Server tab.

Color-code connections

Click on the palette icon and choose a color for your connection.

This will color-code your servers, databases, and collections in the Connection Tree, as well as connection tabs – a handy way to avoid production and test database mixups.

Enable/disable read-only mode

Check Read-Only Lock to enable or disable read-only mode for the results shown in the connection you’re about to set up.

Authentication settings

Studio 3T supports these authentication methods:

• None
• Basic (SCRAM-SHA-256)
• Legacy (SCRAM-SHA-1)
• X.509
• Kerberos (GSSAPI) – Enterprise only
• LDAP (Plain) – Enterprise only

Basic and Legacy authentication cover most cases.

• Authentication Mode – Choose your authentication mode.
• User Name – Enter your user name.
• Password – Enter your password. Note that Studio 3T encrypts passwords by default. Alternatively, you can choose to use your own cryptographic key store. Leave the field blank if you prefer not to store your password, you will then be prompted to enter it later when you try to connect to the server.
• Authentication DB – Enter the database where the user is defined.
• Always show the authentication database of the user account – Checking this box will always show the authentication database in the Connection Tree.
• Always show all databases defined in roles of the user – Checking this box will additionally always show any other databases that your user privileges allow, e.g. databases that contain collections your user privileges grant you access to.
• Manually list additional visible databases by their names – In most cases, Studio 3T will automatically list the databases that should be visible to non-admin users. In some cases when this information isn’t available, you can check the box and manually specify them here.

SSL settings

The SSL tab can be quite overwhelming, so let’s break it down.

MUST – If you want to use SSL to connect to MongoDB, it’s imperative to check the box Use SSL protocol to connect. You then have to fill out the rest of the tab depending on your authentication method and settings.

The following section needs to be filled out regardless of your chosen authentication method. The options, from most secure to least secure, are:

• Use own Root CA file – Likely the option for users in enterprise settings. Here, simply locate the Root CA file provided by your team/company.
• Accept server SSL certificates trusted by the operating system – Reuses the list of OS-trusted server SSL certificates.
• Accept any server SSL certificates – This is the least secure option. Server verification is, of course, highly encouraged.

The next section on setting up a client certificate needs to be filled out especially when using the X.509 authentication method. If you’ve chosen X.509 in the Authentication tab, this will trigger an additional field called X.509 User. 

• Client certificate – Locate the certificate on your computer.
• Passphrase – Enter your passphrase.
• X.509 User – Fill this out to override the default value – the subject – read by the database from the client certificate.
• My client certificate is not protected by a passphrase – Check if your client certificate is not encrypted by a passphrase.

Check the remaining checkboxes as needed.

• Allow invalid hostnames – Disables the validation of hostnames in TSL/SSL certificates.
• Use Server Name Indication (Advanced) – Some servers may require the client to specify the server name it’s trying to connect to. If so, fill out this field so that the server can present one of the many SSL certificates.

SSH Tunnel settings

Check the Use SSH tunnel to connect box, if applicable, and fill out the fields

• SSH Address – Enter the SSH address.
• Port – Enter the Port number.
• SSH User Name – Enter your SSH user name.
• SSH Auth Mode – Choose between Password or Private Key.
• SSH Password –  Enter your password. Note that Studio 3T encrypts passwords by default. Alternatively, you can choose to use your own cryptographic key store. If you don’t want to store your password, leave the field blank and you’ll be prompted to enter it later.
• SSH Private Key and Passphrase – If you’ve chosen Private Key as the Auth Mode, enter the private key and passphrase here.

Proxy settings

Studio 3T offers HTTP and SOCKS proxy connection support.

• Application default proxy – Choosing this option means the Proxy settings defined under Studio 3T > Preferences > Network will be used.
• Custom proxy (HTTP and SOCKS) – These HTTP and SOCKS custom proxy settings are available when connecting to MongoDB databases, connecting to SQL databases for import, and for application-run HTTPS requests (e.g. Telemetry).
• Direct/No proxy

MongoDB Tools settings

The Connection Manager will use global settings by default, which means that the connection will use the mongo executables defined in Preferences (Studio 3T > Preferences > MongoDB Tools). In most cases, it will be the mongo executables bundled with Studio 3T.

However, it also gives you the flexibility to configure the mongo executable version to use for each individual connection.

Uncheck the Use global settings checkbox and choose the mongo executable version (in this case, 3.4.x):

Under the IntelliShell, mongorestore, and mongodump tabs, you can choose to use the mongo executables bundled with Studio 3T for that version, those found on your PATH environment variable, or your own individual files.

Advanced settings

Under the Advanced tab, you can configure other settings related to connection timeouts, idle times, and retry writes.

• Max connection idle time (in ms) – Sets the maximum idle time in milliseconds for a connection. In some cases, the connection could be dropped by a firewall or a load balance. Default value of “0” means unlimited idle time.
• Server selection timeout (in ms) – Defines how long Studio 3T will wait for server selection to succeed before throwing an exception.Default value is 30000. A value of 0 means it will time out immediately if no server is available. A negative value means it will wait indefinitely.
• Socket timeout (in ms) – Sets the socket timeout in milliseconds. It is used for I/O socket read and write operations. Default value is “0” and means no timeout.
• Connect timeout (in ms) – Sets the connection timeout in milliseconds, used solely when establishing a new connection. A value of “0” means no timeout. Default value is 10000.
• Retry writes – Choose to enable retryable writes, which allow MongoDB drivers to automatically retry certain write operations a single time if they encounter network errors, or if they cannot find a healthy primary in the replica sets or sharded cluster.

How to export connection details

Once you’ve entered all connection details under the Server, Authentication, SSL, SSH, Proxy, MongoDB Tools, and Advanced tabs, you can export the connection string in two ways: by exporting to a MongoDB URI or to a URI file.

Export to a MongoDB URI

Choose the connection from the Connection Manager and click on Export in the toolbar.

Or edit the connection and click on To URI on the Server tab.

Edit the settings as needed (e.g. include passwords, SSH configuration, convert DNS seedlist to standard format).

Choose Export to Clipboard to paste and share it with your team, or choose Export to File to export the connection to a .uri file.

Export to a URI file

From the Connection Manager, you can also choose the connection, click on To URI from the toolbar, and follow the steps mentioned above to export to a URI file.

How to (help) prevent a connection timeout

After a relatively short period of inactivity, you might try to run a query from within Studio 3T, but are presented with a server error message box. If you try again, the query will work properly again.

The reason is that in some configurations, the connection can get dropped by a firewall or a load balancer. This issue is common with MongoDBs hosted on Azure.

The folks over at mLab have some interesting details on this matter: http://docs.mlab.com/connecting/#known-issues.

The solution is to manually set the max connection idle time to 60s (60000ms) under the Advanced tab:

After that, your connection should no longer drop 🙂