Docs Menu

Docs HomeMongoDB Shell

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.

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.

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"

To specify a port to connect to on localhost, you can use either:

For example, the following commands connect to a deployment running on localhost port 28015:

mongosh "mongodb://localhost:28015"
mongosh --port 28015

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 different connection options to connect to different types of deployments.

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 connect to a replica set, you can either:

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.

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.

To connect to a deployment using TLS, you can either:

  • Use the DNS Seedlist Connection Format. The +srv connection string modifier automatically sets the tls option to true 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 to true 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

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"

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.

To verify your current database connection, use the db.getMongo() method.

The method returns the connection string URI for your current connection.

To disconnect from a deployment and exit mongosh, perform one of the following actions:

  • Type .exit, exit, or exit().

  • Type quit or quit().

  • Press Ctrl + D.

  • Press Ctrl + C twice.

  • 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 the zlib compressor. The following compressors are not supported:

    • zstd

    • snappy

←  Install mongoshConfigure mongosh →
Share Feedback
© 2023 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2023 MongoDB, Inc.