On this page
- Supported MongoDB Versions
- Connect to a MongoDB Atlas Deployment
- Get your Atlas Connection String
- Set Your Database Credentials
- Connect to MongoDB Atlas with
- 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
- Connect to a Different Deployment
- Verify Current Connection
- Disconnect from a Deployment
- Non-genuine Deployments
This page shows how to use the MongoDB Shell to connect to a MongoDB deployment. You can connect to a MongoDB Atlas cloud-hosted deployment, connect to a local deployment, or connect to another remote host with MongoDB Shell.
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.2 or greater.
These procedures assume you have already installed
mongosh. For more
information about installing
mongosh, refer to
You can connect to your MongoDB Atlas deployment directly from your shell.
You need an Atlas connection string to connect from MongoDB Shell. You can get the Atlas connection string in the Atlas UI.
Refer to the Find Your MongoDB Atlas Connection String guide for details.
If you haven't already created a database user, you must set a username and password. To connect to Atlas, pass your username with the connection string. the connection string to connect to Atlas. After you issue the connect command, the shell prompts for your password.
To establish your connection, run the
mongosh command with your connection string and options
to establish the connection.
The connection string includes the following elements:
Your cluster name
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
You can use other connection security options to connect to Atlas via
mongosh. For information on connecting with a private
IP for peering or a Private Endpoint connection, refer to the
Atlas Connect via mongosh
To connect to a MongoDB deployment running on localhost with
default port 27017, run
mongosh without any options:
This is equivalent to the following command:
To specify a port to connect to on localhost, you can use either:
A connection string with the chosen port
For example, the following commands connect to a deployment running on localhost port 28015:
mongosh --port 28015
To specify a remote host and port, you can use either:
A connection string with the chosen host and port.
--portcommand-line options. If you omit the
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 --host mongodb0.example.com --port 28015
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 different connection options to connect to different types of deployments.
For example, to authenticate as user
alice on the
database, run the following command:
mongosh "mongodb://mongodb0.example.com:28015" --username alice --authenticationDatabase admin
To connect to a deployment using OpenID Connect,
--authenticationMechanism option and set it to
mongosh redirects you to a browser where you enter your identity provider's
For example, the following connects to a local deployment using
mongosh "mongodb://localhost/" --authenticationMechanism MONGODB-OIDC
To connect to a deployment using LDAP:
--passwordto the appropriate password. If you do not specify the password to the
mongoshprompts you for the password.
$externalargument must be placed in single quotes, not double quotes, to prevent the shell from interpreting
$externalas a variable.
When you use one-time passwords with LDAP authentication, adding
the connection string options
maxPoolSize=1&srvMaxHosts=1 to your connection string is
recommended to reduce the potential for connection failures.
For example, the following operation authenticates to a MongoDB deployment running with LDAP authentication and authorization:
mongosh --username firstname.lastname@example.org --password --authenticationDatabase '$external' --authenticationMechanism "PLAIN" --host "mongodb.example.com" --port 27017
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.
To use the DNS seedlist connection format, include the
in your connection string.
For example, to connect to a replica set on
the following command:
+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
You can specify individual replica set members in the connection string.
For example, to connect to a three-member replica set named
run the following command:
directConnection Parameter Added Automatically
When you specify individual replica set members in the connection
mongosh automatically adds the
parameter, unless at least one of the following is true:
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
directConnection=true, all operations are run on the host
specified in the connection URI.
To connect to a deployment using TLS, you can either:
Use the DNS Seedlist Connection Format. The
+srvconnection string modifier automatically sets the
truefor the connection.
For example, to connect to a DNS seedlist-defined replica set with
tlsenabled, run the following command:
truein the connection string.
For example, to enable
tlswith a connection string option, run the following command:
For example, to connect to a remote host with
tlsenabled, run the following command:
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 the
For example, to connect to a database called
qa on localhost, run the
To learn how to connect to a different deployment using these methods, see Open a New Connection.
To verify your current database connection, use the
The method returns the connection string URI for your current connection.
To disconnect from a deployment and exit
mongosh, perform one of the
The shell displays a warning message when you connect to non-genuine MongoDB instances. Non-genuine instances may behave differently from the official MongoDB instances due to missing, inconsistent, or incomplete features.
Kerberos authentication does not allow
authMechanismProperties=CANONICALIZE_HOST_NAME:true|falsein the connection string. Instead, use either:
mongoshcurrently only supports the
zlibcompressor. The following compressors are not supported:
For boolean values in connection strings, you: