Docs Home → MongoDB Shell
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.
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.
You can use the MongoDB Shell to connect to MongoDB version 4.0 or greater.
Run mongosh without any command-line options to connect to a MongoDB instance running on your localhost with default port 27017:
This is equivalent to the following command:
mongosh "mongodb://localhost:27017"
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:
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
--hostand--port. If you do not include the--portoption,mongoshuses 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
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
See also:
Enable Access Control to enforce authentication.
Add Database Users to provide authenticated access to a MongoDB instance.
To connect to a replica set:
If you are using the DNS Seedlist Connection Format, you can include the
+srvmodifier in your connection string.Example
mongosh "mongodb+srv://server.example.com/"
Note
Using the
+srvconnection string modifier automatically sets the tls option totruefor the connection. You can override this behavior by explicitly settingtlstofalse.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
replicaSetquery 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.
For tls connections:
If you are using the DNS Seedlist Connection Format, the
+srvconnection string modifier automatically sets thetlsoption totruefor the connection:Example
To connect to a DNS seedlist-defined replica set with
tlsenabled:mongosh "mongodb+srv://server.example.com/"
You can use the tls option to set
tls=truein the connection string:Example
To enable
tlsin the connection string:mongosh "mongodb://mongodb0.example.com:28015/?tls=true"
You can specify the
--tlscommand-line option.Example
To connect to a remote host with
tlsenabled:mongosh "mongodb://mongodb0.example.com:28015" --tls
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"
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.
Use the db.getMongo[] method to verify your current database connection.
The method returns the connection string URI for your current connection.
To disconnect from a deployment and exit mongosh, you can:
Type
.exit,exit, orexit[].Type
quitorquit[].Press
Ctrl+D.Press
Ctrl+Ctwice.
Kerberos authentication does not permit
authMechanismProperties=CANONICALIZE_HOST_NAME:true|falsein the connection string. Use one of:authMechanismProperties=CANONICALIZE_HOST_NAME:forward|forwardAndReverse|noneinstead.mongoshcurrently only supports thezlibcompressor. The following compressors are not supported:zstdsnappy