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:
- 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
.ExampleTo 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:
- Example
To connect to a MongoDB instance running on a remote host on port 28015:
mongosh "mongodb://mongodb0.example.com:28015" NoteConnecting to AtlasIf 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.ExampleTo 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.
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
To provide a password with the command instead of using the masked
prompt, you can use the --password
option.
- Enable Access Control to enforce authentication.
- Add Database Users to provide authenticated access to a MongoDB instance.
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.Examplemongosh "mongodb+srv://server.example.com/" NoteUsing the
+srv
connection string modifier automatically sets the tls option totrue
for the connection. You can override this behavior by explicitly settingtls
tofalse
.You can specify the replica set name and members in the connection string.
ExampleTo 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"
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 thetls
option totrue
for the connection:ExampleTo 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:ExampleTo enable
tls
in the connection string:mongosh "mongodb://mongodb0.example.com:28015/?tls=true" You can specify the
--tls
command-line option.ExampleTo 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
.
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
, orexit()
. - Type
quit
orquit()
. - 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 thezlib
compressor. The following compressors are not supported:zstd
snappy