Connect to a Deployment
On this page
- Prerequisites
- Supported MongoDB Versions
- Connect to a Local Deployment on the Default Port
- Connect to a Local Deployment on a Non-Default Port
- Connect to a Deployment on a Remote Host
- Specify 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.2 or greater.
Connect to a Local Deployment on the Default Port
To connect to a MongoDB deployment running on localhost with
default port 27017, run mongosh without any options:
mongosh
This is equivalent to the following command:
mongosh "mongodb://localhost:27017"
Connect to a Local Deployment on a Non-Default Port
To specify a port to connect to on localhost, you can use either:
A connection string with the chosen port
The
--portcommand-line option
For example, the following commands connect to a deployment running on localhost port 28015:
mongosh "mongodb://localhost:28015"
mongosh --port 28015
Connect to a Deployment on a Remote Host
To specify a remote host and port, you can use either:
A connection string with the chosen host and port.
The
--hostand--portcommand-line options. If you omit the--portoption,mongoshuses the default port 27017.
For example, the following commands connect to a MongoDB deployment
running on host mongodb0.example.com and port 28015:
mongosh "mongodb://mongodb0.example.com:28015"
mongosh --host mongodb0.example.com --port 28015
Note
Connect to MongoDB Atlas
If your remote host is an Atlas cluster, you can copy your connection string from the Atlas UI. To learn more, see Connect to a Cluster in the Atlas documentation.
Specify Connection Options
Specify different connection options to connect to different types of deployments.
Connect With Authentication
To connect to a MongoDB deployment that requires authentication, use the
--username and --authenticationDatabase options. mongosh prompts you for a
password, which it hides as you type.
For example, to authenticate as user alice on the admin
database, run the following command:
mongosh "mongodb://mongodb0.example.com:28015" --username alice --authenticationDatabase admin
To provide a password as part of the connection command instead of using
the prompt, use the --password option. Use this
option for programmatic usage of mongosh, like a driver.
Tip
See also:
To enforce authentication on a deployment, see Enable Access Control.
To provision access to a MongoDB deployment, see Database Users.
Connect to a Replica Set
To connect to a replica set, you can either:
Use the DNS Seedlist Connection Format.
Explicitly specify the replica set name and members in the connection string.
Option 1: DNS Seedlist Format
To use the DNS seedlist connection format, include the +srv modifier
in your connection string.
For example, to connect to a replica set on server.example.com, run
the following command:
mongosh "mongodb+srv://server.example.com/"
Note
+srv TLS Behavior
When you use the +srv connection string modifier, MongoDB
automatically sets the --tls connection option to
true. To override this behavior, set --tls to false.
Option 2: Specify Members in Connection String
You can specify individual replica set members in the connection string.
For example, to connect to a three-member replica set named replA,
run the following command:
mongosh "mongodb://mongodb0.example.com.local:27017,mongodb1.example.com.local:27017,mongodb2.example.com.local:27017/?replicaSet=replA"
Note
directConnection Parameter Added Automatically
When you specify individual replica set members in the connection
string, mongosh automatically adds the directConnection=true
parameter, unless at least one of the following is true:
The
replicaSetquery parameter is present in the connection string.The connection string uses the
mongodb+srv://connection string format.The connection string contains a seed list with multiple hosts.
The connection string already contains a
directConnectionparameter.
When directConnection=true, all operations are run on the host
specified in the connection URI.
Connect Using TLS
To connect to a deployment using TLS, you can either:
Use the DNS Seedlist Connection Format. The
+srvconnection string modifier automatically sets thetlsoption totruefor the connection.For example, to connect to a DNS seedlist-defined replica set with
tlsenabled, run the following command:mongosh "mongodb+srv://server.example.com/" Set the
--tlsoption totruein the connection string.For example, to enable
tlswith a connection string option, run the following command:mongosh "mongodb://mongodb0.example.com:28015/?tls=true" Specify the
--tlscommand-line option.For example, to connect to a remote host with
tlsenabled, run the following command: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 the
test database.
For example, to connect to a database called qa on localhost, run the
following command:
mongosh "mongodb://localhost:27017/qa"
Connect to a Different Deployment
If you are already connected to a deployment in the MongoDB Shell, you can
use the Mongo() or connect() method to connect to a different
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
To verify your current database connection, use the
db.getMongo() method.
The method returns the connection string URI for your current connection.
Disconnect from a Deployment
To disconnect from a deployment and exit mongosh, perform one of the
following actions:
Type
.exit,exit, orexit().Type
quitorquit().Press
Ctrl+D.Press
Ctrl+Ctwice.
Limitations
Kerberos authentication does not allow
authMechanismProperties=CANONICALIZE_HOST_NAME:true|falsein the connection string. Instead, use either:authMechanismProperties=CANONICALIZE_HOST_NAME:forwardauthMechanismProperties=CANONICALIZE_HOST_NAME:forwardAndReverseauthMechanismProperties=CANONICALIZE_HOST_NAME:none
mongoshcurrently only supports thezlibcompressor. The following compressors are not supported:zstdsnappy