ApsaraDB for MongoDB:Connect to a replica set instance by using the MongoDB Shell

Preparations

• Download and install a shell tool that uses the same engine version as the replica set instance on your on-premises server or ECS instance. For more information, see MongoDB Shell Download and The mongo Shell.

  The mongo shell is a previous command line tool, and the MongoDB Shell is an advanced command line tool. This topic takes the MongoDB Shell as an example.

  If your application is deployed on an ECS instance, make sure that your ApsaraDB for MongoDB replica set instance and the ECS instance meet the following requirements to ensure network connectivity. For more information about how to view the information of ECS instances, see View instance information.

  • Your ApsaraDB for MongoDB instance and ECS instance are deployed in the same region.

  • Your ApsaraDB for MongoDB instance and ECS instance use the same network type.

    Note

    • The same zone is recommended because the same zone reduces network latency.

    • VPC is recommended because VPC provides higher security.

    • If the network type is VPC, you must ensure that they use the same VPC ID.

    • If you want to use the VPC network type, but the network type of the ECS instance is classic network, you can change the network type of the ECS instance to VPC. For more information, see Migrate ECS instances from the classic network to a VPC.

• Add the IP address of the on-premises server or ECS instance to a whitelist of the replica set instance.

• To connect to the replica set instance over the Internet, apply for a public endpoint.

• To connect to read-only nodes in the replica set instance, make sure that it contains read-only nodes. If not, you can add read-only nodes.

Procedure

1. Go the ApsaraDB for MongoDB Replica Set Instances page, select the resource group and region of the desired instance at the top, and then click the instance ID.

2. In the left-side navigation pane of the instance details page, click Database Connections.

3. View instance endpoints.

   1. Determine the endpoint type.

      • Private endpoint

        A VPC is an isolated network that provides higher security and higher performance than the classic network. By default, ApsaraDB for MongoDB provides VPC endpoints for instances to ensure high security and performance.

      • Public endpoint

        If you connect to an ApsaraDB for MongoDB instance over the Internet, the instance may be exposed to security risks. Therefore, no public endpoints are provided for ApsaraDB for MongoDB instances by default. To connect to an ApsaraDB for MongoDB instance over the Internet, apply for a public endpoint.

   2. View instance connection strings.

      SRV connection string URI

      An SRV connection string URI is an HA instance endpoint. This URI allows you to perform read/write operations on instance databases. When adding or removing nodes for your replica set instance, use an SRV connection string URI to interact with the instance without service interruptions, simplifying application design and maintenance.

      Important

      • By default, SRV connection string URIs are not displayed in the ApsaraDB for MongoDB console. To use an SRV connection string URI, click Apply for Private SRV Address or Apply for Public SRV Address on the Database Connections page.

      • Before applying for a public SRV connection string URI, activate the public endpoint of the instance.

      • SRV connection string URIs are available only for instances that use cloud disks.

      • We recommend that you use an SRV connection string URI to connect your application in a production environment to your replica set instance. Your client automatically sends requests to multiple nodes for load balancing. If a node fails, the client automatically redirects requests to other healthy nodes. When adding or removing nodes, seamlessly interact your application with the instance, simplifying the design and maintenance of the application.

      • Drivers of earlier versions do not support SRV connection string URIs or automatically identify nodes, such as:

        • pymongo of versions earlier than 3.9.0

        • MongoDB Java Driver of versions earlier than 3.10.0

        • MongoDB Go Driver of versions earlier than 1.1.0

        • MongoDB Node.js Driver of versions earlier than 3.3.0

        • MongoDB Cxx Driver of versions earlier than 3.8

      Format:

      mongodb+srv://<username>:<password>@<srv-host>/<database>?[authSource=<authenticationDatabase>]<other_options>

      Parameters:

      Parameter	Description
      mongodb+srv://	The prefix of the connection string, which indicates that DNS SRV records are used to identify services.
      <username>	The name of the database account.
      <password>	The password of the database account.
      <srv-host>	The hostname.
      <database>	The name of the database to access. Set the value to admin.
      authSource=<authenticationDatabase> (optional)	The database to which the database account belongs. <authenticationDatabase> indicates the name of the authentication database. Note The TXT records of SRV connection string URIs for ApsaraDB for MongoDB specify authSource=admin, which overrides the authentication property of <database>. Therefore, when modifying the authentication database, manually specify authSource=<authenticationDatabase> instead of modifying the <database> parameter. For more information, see Connection Strings.
      <other_options>	Other optional parameters. Note The default value of the SSL option for SRV connections is true. If you do not need to use SSL-encrypted connections, add the ssl=false parameter to a connection string. For more information about optional parameters, see Connection Strings.

      Example:

      In this example, the database account is test, and it belongs to the mydb database.

      mongodb+srv://test:****@dds-bp19215393a0****-srv.mongodb.nosql.aliyuncs.com/mydb?authSource=mydb&ssl=false

      Connection string URI

      A connection string URI is an HA instance endpoint. This URI allows you to perform read/write operations on instance databases. You can use this URI when earlier-versions of drivers do not support SRV endpoints or automatically identify nodes.

      Important

      • We recommend that you use a connection string URI to connect your application in a production environment to the instance without any interruption on read/write operations from the application due to primary/secondary switchovers.

      • If the readPreference and readPreferenceTags parameters are not specified, read requests are sent to the primary node.

      • When adding or removing nodes, modify the connection string URI and add or remove the corresponding node connection information.

      Format:

      mongodb://<username>:<password>@<host1>:<port1>,<host2>:<port2>,...,<hostN>:<portN>/<database>?replicaSet=<replicaSet_value>[&authSource=<authenticationDatabase>]

      Parameters:

      Parameter	Description
      <username>	The name of the database account.
      <password>	The password of the database account.
      <host>	The Domain Name Information of the primary, secondary, or read-only node.
      <port>	The Port of the primary, secondary, or read-only node.
      <database>	The name of the database to access. Set the value to admin.
      replicaSet=<replicaSet_value>	Specifies that read requests are sent to all nodes of the instance. <replicaSet_value> indicates the unique ID of the HA endpoint of the instance.
      authSource=<authenticationDatabase> (optional)	The database to which the database account belongs. <authenticationDatabase> indicates the name of the authentication database. If this parameter is not specified, the database specified by <database> is used as the authentication one. Important For the authentication to succeed, the specified database account must belong to the specified authentication database.

      Example:

      In this example, the database account is test, and it belongs to the mydb database.

      mongodb://test:****@dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717,dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717,dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717/mydb?replicaSet=mgset-6108****

      Read-only connection string URI

      A read-only connection string URI is an HA instance endpoint. This uRI allows you to perform read operations on instance databases and connect to read-only nodes in the instance. If your instance contains multiple read-only nodes, we recommend that you use this URI to connect your application with more read operations to the instance.

      Note

      • If the instance contains read-only nodes, we recommend that you use the read-only connection string URI to connect to the instance from your application that only read data to the instance.

      • You can view the read-only connection string URI only if the instance contains read-only nodes.

      • If one read-only node in the instance fails, read requests are switched to the next read-only node to ensure connectivity. If all read-only nodes in the instance fail, a connection exception occurs when you continue using the read-only connection string URI to connect to the instance.

      Format:

      mongodb://<username>:<password>@<host1>:<port1>,<host2>:<port2>,...,<hostN>:<portN>/<database>?readPreference=[secondary | secondaryPreferred][&readPreferenceTags=<readonly_Tags>]&replicaSet=<replicaSet_value>[&authSource=<authenticationDatabase>]

      Parameters:

      Parameter	Description
      <username>	The name of the database account.
      <password>	The password of the database account.
      <host>	The Domain Name Information of the read-only node.
      <port>	The Port of the read-only node.
      <database>	The name of the database to access. Set the value to admin.
      readPreference=[secondary | secondaryPreferred]	Specifies that read requests are preferentially sent to secondary nodes. This Implements read/write splitting. Important The MongoDB Shell does not support the readPreference=[secondary | secondaryPreferred] parameter. Read requests are sent to the primary node. When connecting to an instance through the MongoDB Shell, use cursor.readPref() or Mongo.setReadPref() to implement read/write splitting.
      readPreferenceTags=<readonly_Tags> (optional)	Specifies that read requests are preferentially sent to the read-only node corresponding to the specified tag. Important The MongoDB Shell does not support the readPreferenceTags=<readonly_Tags> parameter. Read requests are sent to the primary node. When connecting to an instance through the MongoDB Shell, use cursor.readPref() or Mongo.setReadPref() to send read requests to the read-only node corresponding to a specified tag.
      replicaSet=<replicaSet_value>	Specifies that read requests are preferentially sent to all nodes in the instance. <replicaSet_value> indicates the unique ID of the HA endpoint of the instance.
      authSource=<authenticationDatabase> (optional)	The database to which the database account belongs. <authenticationDatabase> indicates the name of the authentication database. If this parameter is not specified, the database specified by <database> is used as the authentication one. Important For the authentication to succeed, the specified database account must belong to the specified authentication database.

      Example:

      In this example, the database account is test, and it belongs to the mydb database.

      mongodb://test:****@dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717/mydb?readPreference=secondary&readPreferenceTags=role:readonly&replicaSet=mgset-6108****

      Single-node endpoint

      A primary, secondary, or read-only endpoint is a single-node one.

      • Primary node: If connecting to a replica set instance by using the endpoint of the primary node in the instance, perform read/write operations on instance databases.

        Important

        We recommend you do not use a primary endpoint to connect your application in a production environment to your replica set instance. Otherwise, your connection is interrupted if a primary/secondary switchover triggers an endpoint change for the failed primary node. In this case, you must connect to a new primary node to ensure that the read/write operations are not affected.

      • Secondary node: If connecting to a replica set instance by using the endpoint of a secondary node in the instance, perform only read operations on instance databases.

      • Read-only node: If connecting to a replica set instance by using the endpoint of a read-only node in the instance, perform only read operations on instance databases.

        Note

        The endpoint of a read-only node is displayed only if the replica set instance contains the read-only node.

      Format:

      <host>:<port>

      Parameters:

      • <host>: The Domain Name Information of the primary, secondary, or read-only node.

      • <port>: The Port of the primary, secondary, or read-only node.

      Example:

      dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717

4. Connect to the replica set instance from your on-premises server or ECS instance where the MongoDB Shell is installed based on your business requirements.

   Note

   The MongoDB Shell is used as an example in this topic. To use it, replace mongosh with mongo in the following sample commands.

   Use an HA connection string URI to connect to the instance

   If using an HA connection string URI (SRV connection string URI or connection string URI), you can connect to all instance nodes. If using a read-only connection string URI, you can connect to all read-only nodes. If a node fails, the instance still can be connected.

   Syntax:

   mongosh "<Connection string URI>"

   <connection string URI> indicates the HA connection string URI of the instance.

   Important

   The MongoDB Shell does not support the readPreference and readPreferenceTags parameters in a read-only connection string URI. Therefore, if you use this URI to connect to the instance, read requests are sent to the primary node.

   Examples:

   SRV connection string URI

   In this example, the database account is test, the account password is PassWord123!, and the account belongs to the mydb database.

   mongosh "mongodb+srv://test:PassWord123%21@dds-bp19215393a0****-srv.mongodb.nosql.aliyuncs.com/mydb?authSource=mydb&ssl=false"

   Connection string URI

   In this example, the database account is test, the account password is PassWord123!, and the account belongs to the mydb database.

   mongosh "mongodb://test:PassWord123%21@dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717,dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717,dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717/mydb?replicaSet=mgset-6108****"    

   Read-only connection string URI

   In this example, the database account is test, the account password is PassWord123!, and the account belongs to the mydb database.

   mongosh "mongodb://test:PassWord123%21@dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717/mydb?readPreference=secondary&readPreferenceTags=role:readonly&replicaSet=mgset-6108****"

   Use the connection string of a node to connect to the instance

   If using the connection string of a node, connect to only the node. If the node fails, the instance cannot be connected.

   1. Run the following command:

      Syntax:

      mongosh --host <host> --port <port> -u <username> -p --authenticationDatabase <authenticationDatabase>

      Parameters:

      • <host>: The Domain Name Information of the primary, secondary, or read-only node.

      • <port>: The Port of the primary, secondary, or read-only node.

      • <username>: The name of the database account. Set the value to root.

        Note

        We recommend that you do not use the root account for database logon. Create a database account and grant it permissions instead.

      • <authenticationDatabase>: The name of the authentication database, specifying the database to which the database account belongs. If the account is root, enter admin. To specify another database, first create an account in the database by running the db.createUser() command, and then use the account to connect to the database.

        Important

        For the authentication to succeed, the specified database account must belong to the specified authentication database.

      Example:

      In this example, the database account is test, and it belongs to the mydb database.

      mongosh --host dds-bp19f409d7512****.mongodb.rds.aliyuncs.com --port 3717 -u test -p --authenticationDatabase mydb

   2. Enter the password that is used to log on to the database.

      When Enter password: appears in the command line, enter the password of the database account and then press Enter.

Common connection scenarios

• Connect to an instance over the Internet from a local client

  Note

  Before you connect to an ApsaraDB for MongoDB instance over the Internet, we recommend that you enable Secure Sockets Layer (SSL) encryption.

• Connect an ECS instance to an ApsaraDB for MongoDB instance that uses a different network type over the internal network

• Connect an ECS instance to an ApsaraDB for MongoDB instance in a different region over the internal network

• Connect an ECS instance to an ApsaraDB for MongoDB instance within a different Alibaba Cloud account over the internal network

FAQ

• How do I troubleshoot failed connection issues?

• How do I troubleshoot the high CPU utilization issues on my instance?

• How do I query the number of connections to my instance?

• How do I limit the number of connections from my client?

• What do I do if the number of connections to my instance reaches the upper limit?

• How do I resolve failed connection issues due to special characters in the account name or password in a connection string?