Docs Menu

Docs Home → MongoDB Shell

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.

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:

  • A connection string.

    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.

    Example

    To 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:

  • A connection string.

    Example

    To connect to a MongoDB instance running on a remote host on port 28015:

    mongosh "mongodb://mongodb0.example.com:28015"

    Note

    Connecting to Atlas

    If 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.

    Example

    To 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.

Example

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

Note

To provide a password with the command instead of using the masked prompt, you can use the --password option.

Tip

See also:

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.

    Example

    mongosh "mongodb+srv://server.example.com/"

    Note

    Using the +srv connection string modifier automatically sets the tls option to true for the connection. You can override this behavior by explicitly setting tls to false.

  • You can specify the replica set name and members in the connection string.

    Example

    To 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"

Note

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 the tls option to true for the connection:

    Example

    To 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:

    Example

    To enable tls in the connection string:

    mongosh "mongodb://mongodb0.example.com:28015/?tls=true"

  • You can specify the --tls command-line option.

    Example

    To 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.

Example

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, or exit().

  • Type quit or quit().

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

    • zstd

    • snappy

←  Install mongoshConfigure mongosh →

On this page

Give Feedback
MongoDB logo
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center

Support

Social

© 2022 MongoDB, Inc.