All Products
Search
Document Center

ApsaraDB for MongoDB:Connect to an instance

Last Updated:Jun 05, 2025

After creating an ApsaraDB for MongoDB instance, you must connect to the instance by using a client tool before you can use the instance.

Prerequisites

  • You have configured a whitelist by following steps mentioned in Getting Started.

  • The instance status is Running.

Procedure

DMS

  1. Go to the Replica Set Instances or Sharded Cluster Instances page. In the top navigation bar, select the resource group and region to which the desired instance belongs. Then, find the instance and click the instance ID.

  2. In the upper-right corner of the instance details page, click Log On.

    • Replica set instance: In the drop-down menu, select Primary. You are redirected to the DMS console.

      Note

      Secondary nodes support only read operations. To write data, select the primary node.

    • Sharded cluster instance: In the drop-down menu, select the ID of any node. You are redirected to the DMS console.

    • Standalone instance: No selection is required. You are directly redirected to the DMS console.

  3. In the Log on to Database Instance dialog box in the DMS console, enter the Database Account and Database Password. Keep other settings as default.

    Note

    If you forget the account password or did not set a password when creating the instance, go to the ApsaraDB for MongoDB console to reset a password.

  4. Click Test Connection. Then, click OK in the dialog box indicating successful connection.

  5. Click Login.

MongoDB shell

Install MongoDB shell on a local device or an ECS instance

MongoDB provides two command-line tools: MongoDB shell (mongosh) and mongo shell. The mongo shell is an earlier version of a client tool, while MongoDB shell is an advanced tool. In the following example, MongoDB shell is used.

  1. Download MongoDB shell on your client.

  2. Install mongosh.

Obtain an instance connection string

  1. Go to the Replica Set Instances or Sharded Cluster Instances page. In the top navigation bar, select the resource group and region to which the desired instance belongs. Then, find the instance and click the instance ID.

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

  3. On the page that appears, obtain the required connection string.

    The following example uses the high-availability connection string URI in the Internal Connections - VPC section. The URI is in the following format. To connect to the instance over a public network, you must first apply for a public endpoint.

    mongodb://root:****@dds-bp1d9a7c2908e****.mongodb.rds.aliyuncs.com:3717,dds-bp1d9a7c2908e****.mongodb.rds.aliyuncs.com:3717/admin?replicaSet=mgset-8970****

    You need to replace root:**** with the actual account and password. If you forget the account password or did not set a password when creating the instance, go to the Apsara FOR MongoDB console to reset a password.

Connect to the instance

Run the following command on your client to connect to the instance.

Note

If you are using mongo shell, replace mongosh with mongo in the command.

mongosh "<ConnectionStringURI high availability connection address>"

If the database account is root, its password is PassWord123!, and the authentication database is admin. Sample code:

mongosh "mongodb://root:PassWord123%21@dds-bp1d9a7c2908e****.mongodb.rds.aliyuncs.com:3717,dds-bp1d9a7c2908e****.mongodb.rds.aliyuncs.com:3717/admin?replicaSet=mgset-8970****"

Special characters in the account password in the connection string need to be escaped. For example, the ! in the password needs to be escaped as %21. For more information, see How do I resolve failed connection issues due to special characters in the account name or password in a connection string?

Program code

Next step

Write data

References

We recommend that you do not use the root account to connect to the instance in a production environment. You can create another database account and grant permissions to connect to the instance. If using another database account to connect to the instance, you must grant the required permissions to the database account. If using a database account without permissions, you cannot perform any database operations after you successfully connect to the instance. Additionally, the system returns an error such as Exception authenticating....