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

Preparations

• Download and install the mongo shell tool that has the same version as your ApsaraDB for MongoDB instance on your client (local server or ECS instance). For more information, see MongoDB Shell Download and The mongo Shell.

  If your application is deployed on an ECS instance, you must make sure that the ApsaraDB for MongoDB instance and the 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 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 your client to the whitelist of the ApsaraDB for MongoDB instance.

• If you need to connect to the ApsaraDB for MongoDB instance over the Internet, you can apply for a public endpoint.

• If you need to connect to a read-only node, make sure that the ApsaraDB for MongoDB instance contains read-only nodes. If not, you can add read-only nodes.

Procedure

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

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

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

   1. Determine the endpoint type.

      • Private Connection

        A virtual private cloud (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 Connection

        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. If you need to connect to an ApsaraDB for MongoDB instance over the Internet, you can apply for a public endpoint.

   2. Obtain the connection string.

      ConnectionStringURI SRV

      ConnectionStringURI SRV: The high availability endpoint of the instance. You can perform read and write operations on the instance databases. When nodes are added to or removed from the replica set instance, you can use the SRV endpoint to interact with the instance without interruption, which simplifies application design and maintenance.

      Important

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

      • Before you apply for a public SRV HA connection string URI, apply for the public endpoint of the instance.

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

      Format:

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

      Parameter description:

      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 which you want to connect. Default value: admin.
      authSource=<authenticationDatabase> (optional)	This parameter is used to specify the database to which the specified database account belongs. <authenticationDatabase> is the name of the authentication database. Note The TXT record of the SRV connection string for ApsaraDB for MongoDB specifies authSource=admin, which overrides the authentication attribute of <database>. Therefore, when you need to modify the authentication database, you must manually specify authSource=<authenticationDatabase> instead of modifying the <database> parameter. For more information, see MongoDB Documentation.
      <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 encryption for the connection, you must add the ssl=false parameter to the connection string. For more information about optional parameters, see MongoDB Documentation.

      Example:

      In the following sample command, the username is test and the database is admin.

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

      ConnectionStringURI

      ConnectionStringURI: The high availability endpoint of the instance. You can perform read and write operations on the instance databases. You can use this endpoint when low-version drivers do not support SRV endpoints or automatic node discovery.

      Important

      • We recommend that you use the connection string URI to connect your instance from your application in a production environment to the instance. In this case, read/write operations are not affected by a primary/secondary switchover.

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

      Format:

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

      Parameter description:

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

      • <password>: The password of the database account.

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

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

      • <database>: The name of the database to which you want to connect. Default value: admin.

      • replicaSet=<replicaSet_value>: Sends read requests to all nodes of the replica set instance. <replicaSet_value> is the unique ID of the high availability connection address of the instance.

      • authSource=<authenticationDatabase> (optional): Specifies the database to which the database account belongs. <authenticationDatabase> is the name of the authentication database. If this parameter is not specified, <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:

      In the following sample command, the username 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****

      ReadOnly ConnectionStringURI

      ReadOnly ConnectionStringURI: The high availability endpoint of the instance. You can perform read operations on the 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 many read operations must be handled.

      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>]

      Parameter description:

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

      • <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 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 connect to an instance by using the mongo shell, you can use cursor.readPref() or Mongo.setReadPref() to implement read/write splitting.

      • readPreferenceTags=<readonly_Tags> (optional): Sends read requests to the read-only node that corresponds to the tag with the highest priority.

        Important

        • The mongo shell does not support the readPreferenceTags=<readonly_Tags> parameter. Read requests are sent to the primary node.

        • When you connect to an instance by using the mongo shell, you can use cursor.readPref() or Mongo.setReadPref() to send read requests to the read-only node that corresponds to the tag.

      • replicaSet=<replicaSet_value>: Sends read requests to all nodes of the replica set instance. <replicaSet_value> is the unique ID of the high availability connection address of the instance.

      • authSource=<authenticationDatabase> (optional): Specifies the database to which the database account belongs. <authenticationDatabase> is the name of the authentication database. If this parameter is not specified, <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:

      In the following sample command, the username 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****

      Single-node endpoints

      The endpoints of the primary, secondary, and read-only nodes are all single-node endpoints.

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

        Important

        We recommend you do not connect to the primary node in the production environment by using its endpoint. Otherwise, your connection is 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: If you connect to a replica set instance by using the endpoint of a secondary node in the instance, you can perform only read operations on instance databases.

      • Read-only node: If you connect to a replica set instance by using the endpoint of a read-only node in the instance, you can 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>

      Parameter description:

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

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

      Example:

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

4. Based on your business requirements, connect to the ApsaraDB for MongoDB replica set instance from a client (local server or ECS instance) where the mongo shell is installed.

   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.

   Syntax:

   mongo "<connection string>"    

   Parameter description: <connection string> is the high availability endpoint of the instance.

   Important

   • You must replace **** in the high availability endpoint with the password of your database account.

   • The mongo shell does not support the readPreference and readPreferenceTags parameters in the ReadOnly ConnectionStringURI endpoint. Therefore, if you use this endpoint to connect to the instance, read requests are sent to the primary node.

   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:

      Syntax:

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

      Parameter description:

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

      • <port>: The Port of the primary node, secondary node, 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 assign permissions to the account.

      • <authenticationDatabase>: The name of the authentication database, which is used to specify the database to which the database account belongs. If the account is root, enter admin. If you want to specify another database, first create an account in the database by using 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 the following sample command, the username 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 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 press Enter.

Common connection scenarios

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

  Note

  When you connect to an instance over the Internet, we recommend that you use SSL encryption to connect to the database.

• Connect to an ApsaraDB for MongoDB instance from an ECS instance that has different network types

• Connect to an ApsaraDB for MongoDB instance from an ECS instance in a different region

• Connect to an ApsaraDB for MongoDB instance from an ECS instance that belongs to a different account

Additional information

• Troubleshoot connection issues

• Troubleshoot high CPU utilization of an ApsaraDB for MongoDB instance

• How do I query the number of connections?

• How do I limit the number of terminal connections?

• How do I resolve the issue that the maximum number of connections to an instance is reached?

• How do I resolve the issue that a connection fails because the username or password in the connection string contains special characters?