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

Preparations

• The mongo shell that uses the same engine version as the replica set instance is downloaded and installed on your on-premises server or ECS instance. For more information, visit MongoDB Shell Download and The mongo Shell.

  If your application is deployed on an Elastic Compute Service (ECS) instance, make sure that your ApsaraDB for MongoDB instance and ECS instance meet the following requirements to ensure network connectivity: For more information about how to view ECS instance information, 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 VPC, 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.

• The IP address of the on-premises server or ECS instance is added to a whitelist of the instance. For more information, see Configure a whitelist for an ApsaraDB for MongoDB instance.

• If you want to connect to the instance over the Internet, you must apply for a public endpoint. For more information, see (Optional) Apply for a public endpoint for an ApsaraDB for MongoDB instance.

• If you want to connect to a read-only node in the instance, make sure that the instance contains at least one read-only node. If the instance has no read-only nodes, add one or more read-only nodes to the instance. For more information, see Change the configurations of a replica set instance.

Procedure

1. Log on to the ApsaraDB for MongoDB console.

2. In the left-side navigation pane, click Replica Set Instances.

3. In the upper-left corner of the page, select the resource group and region to which the instance belongs.

4. Click the ID of an instance, or click in the Actions column corresponding to the instance and select Manage.

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

6. Obtain the endpoints required to connect to the instance.

   Item	Description
   Endpoint type	Private endpoint: VPC: Virtual Private Cloud (VPC) endpoints are used for communication over VPCs. A VPC is an isolated network that provides higher security and performance than the classic network. By default, ApsaraDB for MongoDB provides VPC endpoints for instances to ensure high security and performance. Classic network: Cloud services in the classic network are not isolated. Unauthorized access to a cloud service is blocked by using security groups or whitelists. Public endpoint: Public endpoints are used for communication over the Internet. If you connect to an ApsaraDB for MongoDB instance over the Internet, the instance may be exposed to security risks. By default, no public endpoints are provided for ApsaraDB for MongoDB instances. If you want to connect to the instance over the Internet, you must apply for a public endpoint. For more information, see (Optional) Apply for a public endpoint for an ApsaraDB for MongoDB instance.
   Role	Primary node: The primary node of a replica set instance can perform both read and write operations on instance databases. Important We recommend you do not connect to the primary node in the production environment by using its connection string. Otherwise, your connection will be interrupted if a primary/secondary switchover triggers a connection string change for the node. In this case, you must connect to the new connection string to ensure that the read and write operations are not affected. Secondary node: The secondary node of a replica set instance can perform only read operations on instance databases. Read-only node: The read-only node of a replica set instance can perform only read operations on instance databases. Note The connection string of a read-only node is displayed only if the replica set instance contains the read-only node. Read-only connection string URI: an HA connection string URI that ensures load balancing and HA. If you use this URI to connect to a replica set instance, you can perform read and write operations on instance databases. This URI allows you to connect to a read-only node in the instance. If your instance contains multiple read-only nodes, we recommend that you connect to this URI in scenarios where a large number of read operations must be handled. Note This URI can be viewed only if the instance contains at least one read-only node. If you use this URI, read requests are preferentially sent to read-only nodes. If one read-only node fails, read requests are switched to the next read-only node to ensure connectivity. If all read-only nodes fail, read requests are switched to a secondary node. Connection string URI: an HA connection string URI that ensures load balancing and HA. If you use this URI to connect to a replica set instance, you can perform read and write operations on instance databases. This URI allows you to connect to a node in the instance. We recommend that you connect to this URI in the production environment. Important If you connect to this URI, all requests are processed by the primary node. Read and write operations are not affected by primary/secondary switchover.
   Connection string of a primary, secondary, or read-only node	Format: <host>:<port> Parameters: <host>: the domain name information used to connect to the primary, secondary, or read-only node. <port>: the port number used to connect to the primary, secondary, or read-only node. Example: dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717
   Read-only connection string URI	Format: mongodb://<username>:<password>@<host1>:<port1>,<host2>:<port2>,...,<hostN>:<portN>/<database>?readPreference=[secondary | secondaryPreferred][&readPreferenceTags=<readonly_Tags>]&replicaSet=<replicaSet_value>[&authSource=<authenticationDatabase>] Parameters: <username>: the name of the database account. Default value: root. <password>: the password of the database account. <host>: the domain name information used to connect to the read-only node. <port>: the port number used to connect to the read-only node. <database>: the name of the database to which you want to connect. Default value: admin. readPreference=[secondary | secondaryPreferred]: implements read/write splitting. Important The mongo shell does not support the readPreference=[secondary | secondaryPreferred] parameter. Read requests are sent to the primary node. When you use the mongo shell to connect to an instance, you can use cursor.readPref() or Mongo.setReadPref() to implement read/write splitting. For more information, see cursor.readPref() or Mongo.setReadPref(). readPreferenceTags=<readonly_Tags> (Optional): The read request is preferentially sent to the read-only node corresponding to the label. Important The mongo shell does not support the readPreferenceTags=<readonly_Tags> parameter. Read requests are sent to the primary node. When you use the mongo shell to connect to an instance, you can use cursor.readPref() or Mongo.setReadPref() to send read requests to the read-only node corresponding to the tag. For more information, see cursor.readPref() or Mongo.setReadPref(). replicaSet=<replicaSet_value>: sends read requests to all nodes of the instance. <replicaSet_value>: the unique URI ID used to connect to the instance. authSource=<authenticationDatabase>: specifies the database to which the specified database account belongs. This parameter is optional. <authenticationDatabase>: the name of the database used for authentication. If you do not specify the authentication database, the database specified by <database> is used as the authentication database. Important For the authentication to succeed, the specified database account must belong to the specified authentication database. Example: The database account is test and the database is admin. mongodb://test:****@dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717/admin?readPreference=secondary&readPreferenceTags=role:readonly&replicaSet=mgset-6108****
   Connection string URI	Format: mongodb://<username>:<password>@<host1>:<port1>,<host2>:<port2>,...,<hostN>:<portN>/<database>?replicaSet=<replicaSet_value>[&authSource=<authenticationDatabase>] Parameters: <username>: the name of the database account. Default value: root. <password>: the password of the database account. <host>: the domain name information used to connect to the primary, secondary, or read-only node. <port>: the port number used to connect to the primary, secondary, or read-only node. <database>: the name of the database to which you want to connect. replicaSet=<replicaSet_value>: sends read requests to all nodes of the instance. <replicaSet_value>: the unique URI ID used to connect to the instance. authSource=<authenticationDatabase>: specifies the database to which the specified database account belongs. This parameter is optional. <authenticationDatabase>: the name of the database used for authentication. If you do not specify the authentication database, the database specified by <database> is used as the authentication database. Important For the authentication to succeed, the specified database account must belong to the specified authentication database. Example: The database account is test and the database is admin. mongodb://test:****@dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717,dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717/admin?replicaSet=mgset-6108****

7. Connect your on-premises server or ECS instance to the instance.

   • Use an HA connection string URI to connect to the instance

     If you use this URI, all instance nodes can be connected. If a node fails, the instance can still be connected.

     Format:

     mongo "<Connection string URI>"    

     Parameter: <Connection string URI> specifies the read-only connection string URI or connection string URI.

     Important

     • Replace **** for the read-only connection string URI or connection string URI with the actual password of the database account.

     • The mongo shell cannot identify the readPreference and readPreferenceTags parameters in a read-only connection string URI. If you use this URI, the primary node is automatically connected.

     Example:

     The connection string URI is used. The database account is test and the database is admin.

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

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

     If you use this method, only a single node is connected. If the node fails, the instance cannot be connected.

     1. Run the following command.

        Format:

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

        Parameters:

        • <host>: the domain name information used to connect to the primary, secondary, or read-only node.

        • <port>: the port number used to connect to the primary, secondary, or read-only node.

        • <username>: the name of the database account. Default value: root.

          Note

          We recommend that you do not use the root account for database logon. You can create a database account and grant the permissions to the account. For more information, see Manage the permissions of MongoDB database users.

        • <database>: the name of the authentication database to which the database account belongs. If the account is root, enter admin. If you want to specify a database other than the authentication database, run the db.createUser() command to create an account 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:

        The database account is test and the database is admin.

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

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

        When Enter password: is displayed, enter the password of the database account and press the Enter key.

Common connection scenarios

• Connect to an ApsaraDB for MongoDB instance over the Internet

  Note

  Before you connect to an instance over the Internet, we recommend that you enable SSL encryption. For more information, see Use the mongo shell to connect to an ApsaraDB for MongoDB database in SSL encryption mode.

• 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 logon issues for the mongo shell?

• How do I troubleshoot failed database connections after the number of connections reaches the upper limit?

• How do I troubleshoot the high CPU utilization of ApsaraDB for MongoDB?

• How do I query and limit the number of connections?