Docs Home
/
MongoDB Shell
On this page
- Prerequisites
- Supported MongoDB Versions
- Install mongosh
- Connect to a MongoDB Atlas Deployment
- Get your Atlas Connection String
- Set Your Database Credentials
- Connect to MongoDB Atlas with mongosh
- 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 with OpenID Connect
- Connect with LDAP
- Connect to a Replica Set
- Connect Using TLS
- Connect to a Specific Database
- Proxy Settings
- Connect to a Different Deployment
- Verify Current Connection
- Disconnect from a Deployment
- Non-genuine Deployments
- Limitations
This page shows how to use the MongoDB Shell to connect to a MongoDBdeployment. You can connect to aMongoDB Atlas cloud-hosted deployment,connect to a local deployment, or connect to another remote host withMongoDB Shell.
Prerequisites
To use the MongoDB Shell, you must have a MongoDB deployment to connectto.
For a free cloud-hosted deployment, you can useMongoDB Atlas.
To learn how to run a local MongoDB deployment, seeInstall MongoDB.
Supported MongoDB Versions
You can use the MongoDB Shell to connect to MongoDB version 4.2 orgreater.
Install mongosh
These procedures assume you have already installed mongosh. For moreinformation about installing mongosh, refer toInstall mongosh.
Connect to a MongoDB Atlas Deployment
You can connect to your MongoDB Atlas deployment directly from your shell.
1
Get your Atlas Connection String
You need an Atlas connection string to connect from MongoDB Shell.You can get the Atlas connection string in the Atlas UI.
Refer to theFind Your MongoDB Atlas Connection Stringguide for details.
2
Set Your Database Credentials
If you haven't alreadycreated a database user,you must set a username and password. To connect to Atlas, pass your username withthe Atlas connection string. After you issue the connect command, theshell prompts for your password.
3
Connect to MongoDB Atlas with mongosh
To establish your connection, run the mongosh command with yourconnection string and options to establish the connection.
The connection string includes the following elements:
Your cluster name
A hash
A flag for the API version
A flag for the username you want to use to connect
It resembles the following string:
mongosh "mongodb+srv://YOUR_CLUSTER_NAME.YOUR_HASH.mongodb.net/" --apiVersion YOUR_API_VERSION --username YOUR_USERNAME
Note
Learn More
You can use other connection security options to connect to Atlas viamongosh. For information on connecting with a privateIP for peering or a Private Endpoint connection, refer to theAtlas Connect via mongoshdocumentation.
Connect to a Local Deployment on the Default Port
To connect to a MongoDB deployment running on localhost withdefault port 27017, run mongosh without any options:
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 thechosen port
The
--portcommand-line option
For example, the following commands connect to a deployment running onlocalhost 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 thechosen 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 deploymentrunning 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 yourconnection string from the Atlas UI. To learn more, seeConnect to a Clusterin the Atlas documentation.
Specify Connection Options
Specify different connection options to connect to different types ofdeployments.
Connect With Authentication
To connect to a MongoDB deployment that requires authentication, use the--username and --authenticationDatabase options. mongosh prompts you for apassword, which it hides as you type.
For example, to authenticate as user alice on the admindatabase, 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 usingthe prompt, use the --password option. Use thisoption for programmatic usage of mongosh, like a driver.
Tip
See also:
To enforce authentication on a deployment, seeEnable Access Control.
To provision access to a MongoDB deployment, see DatabaseUsers.
Connect with OpenID Connect
To connect to a deployment using OpenID Connect,use the --authenticationMechanism option and set it to MONGODB-OIDC.mongosh redirects you to a browser where you enter your identity provider'slog-in information.
For example, the following connects to a local deployment using MONGODB-OIDC:
mongosh "mongodb://localhost/" --authenticationMechanism MONGODB-OIDC
Connect with LDAP
To connect to a deployment using LDAP:
Set --username to a username thatrespects the security.ldap.authz.queryTemplate, or anyconfigured security.ldap.userToDNMapping template.
Set --password to the appropriatepassword. If you do not specify the password to the
--passwordcommand-line option,mongoshprompts you forthe password.Set --authenticationDatabaseto
$external.The$externalargument must be placed in single quotes, notdouble quotes, to prevent the shell from interpreting$externalas a variable.Set --authenticationMechanismto
PLAIN.
Warning
When you use one-time passwords with LDAP authentication, addingthe connection string optionsmaxPoolSize=1&srvMaxHosts=1 to your connection string isrecommended to reduce the potential for connection failures.
Include the --host and--port of the MongoDB deployment, along withany other options relevant to your deployment.
For example, the following operation authenticates to a MongoDBdeployment running with LDAP authentication and authorization:
mongosh --username alice@dba.example.com --password --authenticationDatabase '$external' --authenticationMechanism "PLAIN" --host "mongodb.example.com" --port 27017
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 connectionstring.
Option 1: DNS Seedlist Format
To use the DNS seedlist connection format, include the +srv modifierin your connection string.
For example, to connect to a replica set on server.example.com, runthe following command:
mongosh "mongodb+srv://server.example.com/"
Note
+srv TLS Behavior
When you use the +srv connection string modifier, MongoDBautomatically sets the --tls connection option totrue. To override this behavior, set --tls to false.
Option 2: Specify Members in Connection String
You can specify individual replica set members in theconnection 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 connectionstring, mongosh automatically adds the directConnection=trueparameter, 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 stringformat.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 hostspecified 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 --tls option to
truein the connectionstring.For example, to enable
tlswith a connection string option, runthe 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 thefollowing command:mongosh "mongodb://mongodb0.example.com:28015" --tls
Connect to a Specific Database
To connect to a specific database, specify a database in yourconnection string URI path. Ifyou do not specify a database in your URI path, you connect to thetest database.
For example, to connect to a database called qa on localhost, run thefollowing command:
mongosh "mongodb://localhost:27017/qa"
Proxy Settings
To establish a connection with proxy configurations, you can use thefollowing environment variables:
Variable | Description | Example |
|---|---|---|
| Proxy connections to | The following example sets the |
| Proxy connections to If you also set | The following example sets the |
| Proxy connections to If you also set | The following example sets the |
| Proxy all connections to the specified URL. | The following example sets the |
| Comma-separated list of hostnames that should be excluded fromproxying. | The following example sets the |
Note
mongosh supports the following proxy types:
Socks5 proxies
HTTP proxies
CONNECT proxies
PAC URLs that resolve to one of the previouslylisted proxies
Connect to a Different Deployment
If you are already connected to a deployment in the MongoDB Shell, you canuse the Mongo() or connect() method to connect to a differentdeployment 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 thedb.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 thefollowing actions:
Type
.exit,exit, orexit().Type
quitorquit().Press
Ctrl+D.Press
Ctrl+Ctwice.
Non-genuine Deployments
The shell displays a warning message when you connect to non-genuineMongoDB instances. Non-genuine instances may behave differently from theofficial MongoDB instances due to missing, inconsistent, or incompletefeatures.
Limitations
Kerberos authentication does not allow
authMechanismProperties=CANONICALIZE_HOST_NAME:true|falsein theconnection string. Instead, use either:authMechanismProperties=CANONICALIZE_HOST_NAME:forwardauthMechanismProperties=CANONICALIZE_HOST_NAME:forwardAndReverseauthMechanismProperties=CANONICALIZE_HOST_NAME:none
mongoshcurrently only supports thezlibcompressor. The followingcompressors are not supported:zstdsnappy
Starting in
mongosh2.0.0:For boolean values in connection strings, you:
must use
trueorfalse.cannot use
1,y,yes, ortinstead oftrue.cannot use
-1,0,n,no, orfinstead offalse.
