Docs Menu
Docs Home
/
MongoDB for VS Code

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.

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

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.

1

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

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:

  1. Select the MongoDB icon from the left side menu bar in VSCode.

    Image VSCode side bar menu.
    click to enlarge
  2. Expand the Connections pane in the left navigation if it is collapsed.

    Image showing connections pane
    click to enlarge
  3. Click the More Actions menu (...) and select Add MongoDB Connection with Connection String....

    Select add connection with connection string
    click to enlarge
  1. 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
  2. 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.

  3. In the Overview page, click Connect under the Connect with Connection String.

  1. 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
  2. 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.

3

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.

4
1
Image VSCode side bar menu.
click to enlarge
2

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

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

    Image showing connections pane
    click to enlarge
  2. Click the More Actions menu (...), then click Add MongoDB Connection to open the VS Code Extension Overview page.

    Image showing connections pane dots
    click to enlarge
  1. 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
  2. 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.

3

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

Image showing connections pane screen
click to enlarge
4

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.

5

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

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.

1
  1. Expand the Connections pane in the left navigation if it is collapsed.

  2. Click the More Actions menu (...) and select Add MongoDB Connection with Connection String...

2

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:

Image of a stream connection
click to enlarge
3

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:

Image of a stream processing template
click to enlarge

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:

1
Image VSCode side bar menu.
click to enlarge
2

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

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

To connect the shell to your active deployment:

  1. In the VS Code Extension Connections list, right-click your active deployment.

  2. Select Launch MongoDB Shell.

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

1
Image VSCode side bar menu.
click to enlarge
2

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

Image showing connections pane
click to enlarge
3

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

4

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.

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

1
Image VSCode side bar menu.
click to enlarge
2

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

Image showing connections pane
click to enlarge
3

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

The connection string is copied to your clipboard.

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

1
Image VSCode side bar menu.
click to enlarge
2
3
  1. In the Command Palette, type a new name for the connection.

  2. Press the Enter or Return key to rename the connection.

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.

1
Image VSCode side bar menu.
click to enlarge
2
1
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
2
  1. 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.

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

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.

1
Image VSCode side bar menu.
click to enlarge
2
3
1
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
2

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.

3

Back

Verify Plugin