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
--port
command-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
--host
and--port
command-line options. If you omit the--port
option,mongosh
uses 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
replicaSet
query 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
directConnection
parameter.
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
+srv
connection string modifier automatically sets thetls
option totrue
for the connection.For example, to connect to a DNS seedlist-defined replica set with
tls
enabled, run the following command:mongosh "mongodb+srv://server.example.com/" Set the
--tls
option totrue
in the connection string.For example, to enable
tls
with a connection string option, run the following command:mongosh "mongodb://mongodb0.example.com:28015/?tls=true" Specify the
--tls
command-line option.For example, to connect to a remote host with
tls
enabled, 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
quit
orquit()
.Press
Ctrl
+D
.Press
Ctrl
+C
twice.
Limitations
Kerberos authentication does not allow
authMechanismProperties=CANONICALIZE_HOST_NAME:true|false
in the connection string. Instead, use either:authMechanismProperties=CANONICALIZE_HOST_NAME:forward
authMechanismProperties=CANONICALIZE_HOST_NAME:forwardAndReverse
authMechanismProperties=CANONICALIZE_HOST_NAME:none
mongosh
currently only supports thezlib
compressor. The following compressors are not supported:zstd
snappy