All Products
Search

This Product

    ApsaraDB for MongoDB:Connect to an instance

    Document Center

    ApsaraDB for MongoDB:Connect to an instance

    Last Updated:Aug 25, 2026

    Connect to your ApsaraDB for MongoDB instance using DMS, MongoDB Shell (mongosh), or application code.

    Prerequisites

    Procedure

    DMS

    1. Go to the ApsaraDB for MongoDB replica set instances or ApsaraDB for MongoDB sharded cluster instances page. At the top of the page, select a resource group and a region, and then click the ID of the target instance.

    2. In the upper-right corner, click Log on to Database.

      • For a replica set instance: Select Primary from the drop-down list.

        Note

        Secondary nodes are read-only. To write data, select Primary.

      • For a sharded cluster instance: Select any node from the drop-down list.

      • For a standalone instance: DMS opens directly.

    3. In the Log on to Database Instance dialog box, enter the Database Account and Database Password. Leave other fields at their defaults.

      Note

      If you forgot or haven't set a password, reset the password.

    4. Click Test Connectivity. In the success dialog box, click Confirm.

    5. Click Login.

    Note

    When you query data using DMS, the maximum size of a single document is 512 KB. This limit cannot be adjusted. To query larger documents, you can use the MongoDB Shell.

    MongoDB Shell

    Install MongoDB Shell

    MongoDB provides two CLI tools: MongoDB Shell (mongosh) and the legacy mongo shell. This guide uses mongosh.

    1. On your client, download MongoDB Shell.

    2. Install mongosh.

    Obtain a connection string

    1. Go to the ApsaraDB for MongoDB replica set instances or ApsaraDB for MongoDB sharded cluster instances page. At the top of the page, select a resource group and a region, and then click the ID of the target instance.

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

    3. On the Database Connections page, copy the connection string.

      This example uses the High-availability Connection String URI from Private Connection - VPC. To connect over the internet, apply for a public endpoint first:

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

      Replace root:**** with your actual credentials. If you forgot your password, reset your password.

    Connect to the database

    Run this command on your client to connect:

    Note

    If using the legacy mongo shell, replace mongosh with mongo.

    mongosh "<your_connection_string_uri>"

    Example with account root, password PassWord123!, and authentication database admin:

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

    URL-encode special characters in credentials. For example, ! becomes %21. How to resolve connection failures caused by special characters in a username or password?

    Code

    Next steps

    Write data

    Related documents

    Avoid using the root account in production. Create dedicated accounts with appropriate permissions. Accounts with insufficient permissions return errors such as Exception authenticating....