Connection Manager

Three ways to connect to MongoDB

Create a new connection (e.g. connect to MongoDB localhost)

If you’ve just downloaded MongoDB and don’t have a MongoDB URI to paste or a URI file to import, then you need to create a new connection.

Let’s try to connect to MongoDB localhost (which runs on default port 27017) as an example.

1. Open Studio 3T.
2. Click on the Connect button either in the global toolbar or under the Recent Connections tab. This will open the Connection Manager.
3. Click on New Connection. This will open the New Connection window. By default, you will land on the Server tab.
4. Name your new connection.
5. The server and port fields should already be prefilled (with localhost and 27017 respectively) which should work as-is with default settings.
6. Click Save.
7. Click Connect.

If you’re connecting to a MongoDB database requiring additional configuration (e.g. SSH, SSL), skip ahead to the Configure your MongoDB connection chapter.

Paste a MongoDB URI

Studio 3T also provides two other convenient ways to enter connection details: by pasting a MongoDB connection string or URI (recommended) or importing a URI file.

Hosters like MongoDB Atlas, Compose, mLab, ObjectRocket, and ScaleGrid provide the MongoDB URI or connection string in an easy format, so all that’s left is to paste it within Studio 3T’s Connection Manager.

1. Click on the Connect button either in the global toolbar or under the Recent Connections tab.
2. Click on New Connection. This will open the New Connection window. By default, you will land on the Server tab.
3. Click on the From URI button.
4. Paste the connection string.
5. Click OK. Studio 3T will then extract the information and automatically fill out the fields in the Server, Authentication, SSL, SSH Tunnel, and Advanced tabs. It will also automatically save the connection in the Connection Manager.

Import a URI file

To import a URI file:

1. Click on the Connect button either in the global toolbar or under the Recent Connections tab.
2. Then, click on the Import button.
3. Click on Open Connection URI File.
4. Choose your .uri file and click Import.

Configure your MongoDB connection

You can configure your MongoDB connection settings further under the Server, Authentication, SSL, SSH Tunnel, Proxy, and Advanced tabs.

Server

1. Enter Connection Name – Name your connection.
2. Add Custom Color – Color-code your connection (e.g. to avoid production and test database mixups).
3. Choose Connection Type – Choose from Direct Connection, or Replica Set or Sharded Cluster.
4. Enter Server Details – Enter server hostnames or IP addresses and port details.

   When choosing Replica Set or Sharded Cluster, you can also set your Read Preference to Primary, Primary Preferred, Secondary, Secondary Preferred, or Nearest:
   

5. Enable/Disable Read Only Lock – Enables/disables read-only mode for the results shown in the connection you’re about to set up.
6. From URI – Import or paste the MongoDB connection string or URI (e.g. from your MongoDB hosting provider) here.
7. To URI – Export your connection details to a MongoDB URI, with the option to include passwords and add a replica set option.
8. Test Connection – Test connection details before saving. This button is accessible across all tabs.

Authentication

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.

1. Authentication Mode – Choose your authentication mode.
2. User Name – Enter your user name.
3. Password – Enter your password.

   Passwords are encrypted for storage. 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.

4. Authentication DB – Enter the database where the user is defined.
5. Manually list visible databases – In most cases, Studio 3T will automatically list the databases that should be visible to non-admin uses. In some cases when this information isn’t available, you can check the box and manually specify them here.

SSL

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.

Section 1 – 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.

Section 2 – Needs to be filled out especially when using the X.509 authentication method. If you’ve chosen X.509 in the Server 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 encrypted by a passphrase.

Section 3

• Allow invalid hostnames – Disables the validation of hostnames in TSL/SSL certificates

Section 4

• 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

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

• SSH Address
• Port
• SSH User Name
• SSH Auth Mode
• SSH Password – Note that passwords are encrypted for storage. If you don’t want to store your password, leave the field blank and you’ll be prompted to enter it later.

Proxy

You can use Studio 3T to connect using:

• Application default proxy
• 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

Advanced

You can also configure advanced settings like:

• 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. Here’s a little tip to prevent a connection timeout. 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.