Connect to Your MongoDB Deployment

On this page

Considerations

Create a Connection
Connect to Atlas Stream Processing
Activate a Connection
Edit a Connection
Copy a Connection
Rename a Connection
Disconnect from a Deployment
Remove a Connection

This page outlines how to use MongoDB for VS Code Extension 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 VS Code Extension to your deployment.

To create a cluster on the Atlas free tier, run the command MongoDB: Open Overview Page in the Visual Studio Code Command Palette and then click Create free cluster.

To create an Atlas cluster using a Terraform template included with VS Code Extension, see Create an Atlas Cluster from a Template using Terraform.

If you need to install VS Code Extension, see Install MongoDB for VS Code Extension for instructions.

Considerations

When connecting VS Code Extension to a replica set, use either the replica set SRV record or Replica Set Name when filling in your connection information. 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, VS Code Extension may either forcibly close the connection or display stale data.
You can't connect VS Code Extension directly to an analytics node.
VS Code Extension appends the appName connection string option with a value of mongodb-vscode <version> for all deployment connections.

Create a Connection

VS Code Extension provides two options to connect to your deployment:

Connection Method	Description
Connect with Connection String	This method is faster and easier than using the advanced connection settings. Use this option if your deployment is hosted on Atlas or you already have a connection string for a deployment available.
Advanced Connection Settings	This method lets you build a connection string with a form. Use this option if you need to customize the connection string and want to see available connection options.

Note

To specify where VS Code Extension connections are saved, use the Default Connection Saving Location setting.

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

Obtain your connection string.

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.

Open the Visual Studio Code Command Palette.

Open the Visual Studio Code Command Palette to paste your connection string and connect to your cluster. You can open the Command Palette in one of the following ways:

Select the MongoDB icon from the left side menu bar in VSCode.
click to enlarge
Expand the Connections pane in the left navigation if it is collapsed.
click to enlarge
Click the More Actions menu (...) and select Add MongoDB Connection with Connection String....
click to enlarge

Perform the action described in the following table for your operating system and method:
Operating System
Method
Actions
Any
Visual Studio Code Menu
View > Command Palette
MacOS
Keyboard Shortcut
Press Command + Shift + P
Windows and Linux
Keyboard Shortcut
Press Control + Shift + P
From the Command Palette, select MongoDB: Open Overview Page.
Tip
Enter mongodb in the Command Palette to display all of the VS Code Extension commands you can use.
In the Overview page, click Connect under the Connect with Connection String.

Perform the action described in the following table for your operating system and method:
Operating System
Method
Actions
Any
Visual Studio Code Menu
View > Command Palette
MacOS
Keyboard Shortcut
Press Command + Shift + P
Windows and Linux
Keyboard Shortcut
Press Control + Shift + P
From the Command Palette, select MongoDB: Connect with Connection String....
Tip
Enter mongodb in the Command Palette to display all of the VS Code Extension commands you can use.

Paste your connection string into the Command Palette

Important

If your deployment requires authentication, ensure that you update the connection string with credentials of a database user for your deployment. The connection might succeed without these credentials, but you won't be able to interact with data in your deployment.

Press the Enter or Return key

In Visual Studio Code, click the MongoDB icon in the Activity Bar

click to enlarge

Open the VS Code Extension Overview page

You can use the the MongoDB view or the Command Palette to open the overview page:

Expand the Connections pane in the left navigation if it's collapsed.
click to enlarge
Click the More Actions menu (...), then click Add MongoDB Connection to open the VS Code Extension Overview page.
click to enlarge

Perform the action described in the following table for your operating system and method:
Operating System
Method
Actions
Any
Visual Studio Code Menu
View > Command Palette
MacOS
Keyboard Shortcut
Press Command + Shift + P
Windows and Linux
Keyboard Shortcut
Press Control + Shift + P
From the Command Palette, select MongoDB: Open Overview Page.
Tip
Enter mongodb in the Command Palette to display all of the VS Code Extension commands you can use.

Open the Advanced Connection Settings Form

On the Overview page, click Open form under Advanced Connection Settings.

click to enlarge

Enter your connection information

Important

VS Code Extension does not support the following connection options:

CSFLE In-Use Encryption
Kerberos Authentication

The General tab contains the following options:

Option

Description

Connection Type

Type of connection. Select your connection type from the tabs for specific instructions for defining that connection type:

For a Standalone, specify the following:

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 on which the deployment is running.
By default, a standalone deployment operates on port 27017. 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.

Click to specify additional hostnames and associated ports.

For a replica set, specify the following:

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 on which the deployment is running.
For 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.
Optional. Replica Set Name as specified in the replica set configuration.

Click to specify additional hostnames and associated ports.

For an SRV Record, specify the Hostname. You do not need to specify a port.

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.

For example:

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

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

Then, in VS Code Extension, 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 for specific instructions:

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

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

Select OIDC if the deployment uses OpenID Connect as its authentication mechanism.

Provide the following information:

Field	Description
Username	Optional. OpenID Connect username.
Auth Code Flow Redirect URI	Optional. Specify a URI where the identity provider redirects you after authentication. The URI must match the configuration of the Identity Provider. The default is `http://localhost:27097/redirect`.
Consider Target Endpoint Trusted	Optional. Allows connecting to a target endpoint that is not in the list of endpoints that are considered trusted by default. Only use this option when connecting to servers that you trust.
Enable Device Authentication Flow	Optional. When the Show Device Auth Flow Checkbox setting is enabled, Visual Studio Code can provide you with a URL and code to finish authentication.

This is a less secure authentication flow that can be used as a fallback when browser-based authentication is unavailable.

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

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

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

Select AWS IAM if the deployment uses AWS IAM as its authentication mechanism.

Field	Necessity	Description
AWS Access Key Id	Required	Unique identifier associated with your AWS account.
AWS Secret Access Key	Optional	Long-term credential associated with the access key ID.
AWS Session Token	Optional	A temporary security credential that is returned by the AWS Security Token Service (STS).

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 VS Code Extension 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

VS Code Extension 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 VS Code Extension 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 the deployment to verify the identity of the connecting client. Typical file extensions for the certificate are `.crt` or `.pem`.
Client Private Key	A TLS/SSL key file to the deployment to verify the identity of the connecting 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 VS Code Extension 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 using VS Code Extension, 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 VS Code Extension (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. VS Code Extension cannot establish a connection to multiple servers across the same SSH tunnel.

Optional: Specify additional options in the Advanced tab

You can select the Read Preference, which specifies how VS Code Extension directs read operations:

Read Preference Mode	Description
Primary	Default mode. All operations read from the current replica set primary.
Primary Preferred	In most situations, operations read from the primary but if it is unavailable, operations read from secondary members.
Secondary	All operations read from the secondary members of the replica set.
Secondary Preferred	In most situations, operations read from secondary members but if no secondary members are available, operations read from the primary.
Nearest	Operations read from member of the replica set with the least network latency, irrespective of the member's type.

If omitted, defaults to Primary. To learn more about read preferences, see Read Preference.

You can specify additional MongoDB connection behavior with the following options:

Field	Description
Replica Set Name	(Optional) Name of replica set.
Default Authentication Database	(Optional) Authentication database used when authSource is not specified. For more information, see Authentication Options.
URI Options	Additional options to customize your connection. You specify these options as key-value pairs, and Visual Studio Code automatically adds the key-value pairs to the connection string. For more information, see Connection String Options.

Click Connect

Connect to Atlas Stream Processing

New in version 1.50.

You can use VS Code Extension to connect to Atlas Stream Processing by providing a Stream Processing Interface (SPI) connection string.

For details on how to configure Atlas Stream Processing, see Manage Stream Processing Instances.

Open the connections pane

Expand the Connections pane in the left navigation if it is collapsed.
Click the More Actions menu (...) and select Add MongoDB Connection with Connection String...

Paste in an SPI connection string

To obtain an SPI connection string login to your Atlas account. Click Stream Processing from the left-hand navigation and then select a Stream Processing Instance. Click Connect and choose MongoDB for VSCode from the Choose a Connection Method page of the connect dialog.

Tip

For full details on using and configuring Atlas Stream Processing, see Atlas Stream Processing Overview.

The following code block is an example of SPI connection string:

mongodb://user1:password1@atlas-stream-xxxxxxxxxxxxxxxxxxxxxxxx-yyyyy.virginia-usa.a.query.mongodb.net/?authSource=admin&readPreference=primary&ssl=true&directConnection=true

Once you are connected, the stream connection displays under the Connections pane:

click to enlarge

Open a new VS Code Extension playground

After successfully connecting to your Atlas Stream, click Create New Playground on the Playgrounds pane. A stream processing playground template displays with pre-populated code that allows you to list stream connections and process stream data:

click to enlarge

Activate a Connection

You can connect VS Code Extension to only one deployment at a time. To change the active connection to a different deployment, or to connect to a deployment from which you were disconnected:

In Visual Studio Code, click the MongoDB icon in the Activity Bar

click to enlarge

Right-click the connection you want to activate, then click Connect

Launch MongoDB Shell

You can connect the MongoDB Shell or legacy mongo shell to your active deployment.

Considerations

The shell that VS Code Extension uses to connect to your deployment is determined by the Shell setting in your extension settings. You can choose either the MongoDB Shell or the legacy mongo shell.
The path to your selected shell must exist in your system's PATH. If it does not exist in your PATH, the operation errors.

Procedure

To connect the shell to your active deployment:

In the VS Code Extension Connections list, right-click your active deployment.
Select Launch MongoDB Shell.

VS Code Extension opens the Terminal window in VS Code and launches the shell connected to your selected deployment.

Edit a Connection

In Visual Studio Code, click the MongoDB icon in the Activity Bar

click to enlarge

Expand the Connections pane

Expand the Connections pane in the left navigation if it's collapsed.

click to enlarge

Select a connection

From the Connections menu, right-click the connection and select Edit Connection...

Make changes and save

Click Advanced Connection Options to display the advanced connection form.

Tip

You can also click the Edit Connection String toggle in the top-right of the form to edit the connection string URI directly.

Once you are done editing the connection options click Save & Connect.

Copy a Connection

You can copy a connection string from an existing Visual Studio Code connection.

In Visual Studio Code, click the MongoDB icon in the Activity Bar

click to enlarge

Expand the Connections pane

Expand the Connections pane in the left navigation if it's collapsed.

click to enlarge

Select a connection

From the Connections menu, right-click the connection and select Copy Connection String.

The connection string is copied to your clipboard.

Rename a Connection

To rename a connection to a deployment in VS Code Extension:

In Visual Studio Code, click the MongoDB icon in the Activity Bar

click to enlarge

Right-click the connection you want to activate, then click Rename Connection.

Rename the connection.

In the Command Palette, type a new name for the connection.
Press the Enter or Return key to rename the connection.

Disconnect from a Deployment

VS Code Extension provides two methods to disconnect from a deployment. You can:

Disconnect with the Command Palette.
Disconnect from the MongoDB view in the Activity Bar.

In Visual Studio Code, click the MongoDB icon in the Activity Bar

click to enlarge

Right-click the deployment from which you want to disconnect, then click Disconnect.

Open the Command Palette

Operating System	Method	Actions
Any	Visual Studio Code Menu	View > Command Palette
MacOS	Keyboard Shortcut	Press `Command` + `Shift` + `P`
Windows and Linux	Keyboard Shortcut	Press `Control` + `Shift` + `P`

Disconnect

From the Command Palette, select MongoDB: Disconnect.
Tip
Enter mongodb in the Command Palette to display all of the VS Code Extension commands you can use.
Press Enter.

Disconnecting from a MongoDB instance closes the VS Code Extension connection to the active instance. You must reconnect to interact with data in your deployment again.

Remove a Connection

VS Code Extension provides two methods to remove a connection to a deployment from Visual Studio Code. You can:

Remove a connection from the MongoDB view in the Activity Bar.
Remove a connection with the Command Palette.

Important

Removing a connection from Visual Studio Code removes it both from the current workspace and from Visual Studio Code globally.

In Visual Studio Code, click the MongoDB icon in the Activity Bar

click to enlarge

Right-click the connection you want to remove, then click Remove Connection.

Click Yes to remove the connection.

Open the Command Palette

Operating System	Method	Actions
Any	Visual Studio Code Menu	View > Command Palette
MacOS	Keyboard Shortcut	Press `Command` + `Shift` + `P`
Windows and Linux	Keyboard Shortcut	Press `Control` + `Shift` + `P`

From the Command Palette, select MongoDB: Remove Connection....

Tip

Enter mongodb in the Command Palette to display all of the VS Code Extension commands you can use.

If you have more than one connection, select the connection you want to remove from the Command Palette.