Connect to a Deployment

On this page

Prerequisites

Supported MongoDB Versions
Local MongoDB Instance on Default Port
Local MongoDB Instance on a Non-Default Port
MongoDB Instance on a Remote Host
Connection Options
Connect with Authentication
Connect to a Replica Set
Connect using TLS
Connect to a Specific Database
Connect to a Different Deployment
Verify Current Connection
Disconnect from a Deployment
Limitations

This page shows how to use the MongoDB Shell to connect to a MongoDB deployment.

Prerequisites

To use the MongoDB Shell, you must have a MongoDB deployment to connect to.

For a free cloud-hosted deployment, you can use MongoDB Atlas.
To learn how to run a local MongoDB deployment, see Install MongoDB.

Supported MongoDB Versions

You can use the MongoDB Shell to connect to MongoDB version 4.0 or greater.

Local MongoDB Instance on Default Port

Run mongosh without any command-line options to connect to a MongoDB instance running on your localhost with default port 27017:

mongosh

This is equivalent to the following command:

mongosh "mongodb://localhost:27017"

Local MongoDB Instance on a Non-Default Port

To specify a port to connect to on localhost, you can use:

A connection string.
Example
To connect to a MongoDB instance running on localhost with a non-default port 28015:
mongosh "mongodb://localhost:28015"
The command-line option --port.
Example
To connect to a MongoDB instance running on localhost with a non-default port 28015:
mongosh --port 28015

MongoDB Instance on a Remote Host

To specify a remote host and port, you can use:

A connection string.
Example
To connect to a MongoDB instance running on a remote host on port 28015:
mongosh "mongodb://mongodb0.example.com:28015"
Note
Connecting to Atlas
If your remote host is a MongoDB Atlas cluster, you can copy your connection string from the Atlas UI. To learn more, see Connect to a Cluster.
The command-line options --host and --port. If you do not include the --port option, mongosh uses the default port 27017.
Example
To connect to a MongoDB instance running on a remote host on port 28015:
mongosh --host mongodb0.example.com --port 28015

Connection Options

Connect with Authentication

To connect to a MongoDB instance requires authentication, use the --username and --authenticationDatabase command-line options. mongosh prompts you for a password, which it masks as you type.

Example

To connect to a remote MongoDB instance and authenticate against the admin database as user alice:

mongosh "mongodb://mongodb0.example.com:28015" --username alice --authenticationDatabase admin

Note

To provide a password with the command instead of using the masked prompt, you can use the --password option.

Tip

Connect to a Replica Set

To connect to a replica set:

If you are using the DNS Seedlist Connection Format, you can include the +srv modifier in your connection string.
Example
mongosh "mongodb+srv://server.example.com/"
Note
Using the +srv connection string modifier automatically sets the tls option to true for the connection. You can override this behavior by explicitly setting tls to false.

You can specify the replica set name and members in the connection string.

Example

To connect to a three-member replica set named replA:

mongosh "mongodb://mongodb0.example.com.local:27017,mongodb1.example.com.local:27017,mongodb2.example.com.local:27017/?replicaSet=replA"

Note

mongosh adds the directConnection=true query parameter to the connection string automatically unless at least one of the following is true:

The replicaSet query parameter is present in the connection string.
The connection string uses the mongodb+srv:// scheme.
The connection string contains a seed list with multiple hosts.

Connect using TLS

For tls connections:

If you are using the DNS Seedlist Connection Format, the +srv connection string modifier automatically sets the tls option to true for the connection:
Example
To connect to a DNS seedlist-defined replica set with tls enabled:
mongosh "mongodb+srv://server.example.com/"
You can use the tls option to set tls=true in the connection string:
Example
To enable tls in the connection string:
mongosh "mongodb://mongodb0.example.com:28015/?tls=true"
You can specify the --tls command-line option.
Example
To connect to a remote host with tls enabled:
mongosh "mongodb://mongodb0.example.com:28015" --tls

Connect to a Specific Database

To connect to a specific database, specify a database in your connection string URI path If you do not specify a database in your URI path, you connect to a database named test.

Example

The following connection string URI connects to database db1.

mongosh "mongodb://localhost:27017/db1"

Connect to a Different Deployment

You can use the Mongo() or the connect() methods to connect to a different MongoDB deployment from within the MongoDB Shell.

To learn how to connect to a different deployment using these methods, see Open a New Connection.

Verify Current Connection

Use the db.getMongo() method to verify your current database connection.

The method returns the connection string URI for your current connection.

Disconnect from a Deployment

To disconnect from a deployment and exit mongosh, you can:

Type .exit, exit, or exit().
Type quit or quit().
Press Ctrl + D.
Press Ctrl + C twice.

Limitations

Kerberos authentication does not permit authMechanismProperties=CANONICALIZE_HOST_NAME:true|false in the connection string. Use one of: authMechanismProperties=CANONICALIZE_HOST_NAME:forward|forwardAndReverse|none instead.
mongosh currently only supports the zlib compressor. The following compressors are not supported:
- zstd
- snappy

← Install mongoshConfigure mongosh →