All Products
Search

This Product

    ApsaraDB for MongoDB:Connect to a sharded cluster instance

    Document Center

    ApsaraDB for MongoDB:Connect to a sharded cluster instance

    Last Updated:Sep 17, 2025

    ApsaraDB for MongoDB sharded cluster instances provide separate endpoints for Mongos, shard, and Configserver components. They also provide high-availability ConnectionStringURI and ConnectionStringURI SRV addresses for application connections. This topic describes how to obtain these endpoints and provides instructions on how to connect.

    Obtain a database endpoint

    1. Go to the ApsaraDB for MongoDB Sharded Cluster Instances page. In the top navigation bar, select a resource group and a region. Then, click the ID of the target instance.

    2. On the instance details page, in the navigation pane on the left, click Database Connections. Then, obtain the connection address of the target node.

    Endpoint description

    Network types of endpoints

    Network type

    Description

    Private network

    • VPC: A virtual private cloud (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.

    • Classic network: The classic network is a network environment in which Cloud services are not isolated. The classic network blocks unauthorized access to a cloud service by using security groups or whitelists. New instances do not support the classic network type. For more information, see [Notice] Classic network unavailability for new ApsaraDB for MongoDB instances.

    Internet

    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.

    Endpoint types

    Endpoint type

    Description

    ConnectionStringURI SRV address (Recommended)

    In MongoDB, an SRV is a type of DNS record that simplifies the MongoDB connection string and supports automatic discovery of cluster members.

    When you add or remove Mongos nodes in a sharded cluster instance, using an SRV address lets you interact with the instance seamlessly. This simplifies application design and maintenance.

    Important

    • By default, the console does not display the SRV address. To use it, click Apply For Private SRV Address or Apply For Public SRV Address on the Database Connection page.

    • Before you apply for a public SRV address, you must enable public endpoints for the Mongos nodes. After you connect to the MongoDB instance using the public SRV address, the client automatically sends requests to the Mongos nodes for which public endpoints are enabled.

    • SRV addresses are supported only for instances that use cloud disks.

    • A private SRV address in a VPC can be associated with a maximum of 20 Mongos nodes. Due to the limitations of the DNS parsing protocol in a VPC, if there are more than 20 Mongos nodes, the excess nodes cannot share the request load. Public SRV addresses do not have this limitation.

    • For production environments, connect applications to the database using a ConnectionStringURI SRV address. The client automatically sends requests to multiple nodes of the instance for load balancing. If a node fails, the client automatically performs a failover and sends requests to a healthy node. When you add or remove nodes, you can interact with the cluster seamlessly. This simplifies application design and maintenance.

    • Older driver versions do not support SRV addresses or automatic node discovery. Examples include the following:

      • pymongo versions earlier than 3.9.0.

      • mongo-java-driver versions earlier than 3.10.0.

      • mongodb-go-driver versions earlier than 1.1.0.

      • mongodb node.js versions earlier than 3.3.0.

      • mongo-cxx-driver versions earlier than 3.8.

    ConnectionStringURI address

    ApsaraDB for MongoDB provides ConnectionStringURI addresses for Mongos and shard components.

    Compared to a single-node connection string, it is better to connect applications in a production environment to the database using a ConnectionStringURI. The client automatically sends requests to multiple Mongos nodes for load balancing. If a Mongos node fails, the client automatically performs a failover and sends requests to a healthy Mongos node.

    Note

    • By default, the console displays only the ConnectionStringURI address for Mongos. To get the ConnectionStringURI address for a shard, you must apply for the endpoint of the corresponding node.

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

    • When you add or remove Mongos nodes in a sharded cluster instance, you must modify this connection string to add or remove the corresponding node connection information.

    Mongos address

    The endpoint of a Mongos component, including the endpoint of the primary node.

    Note

    For daily testing, you only need to connect to any node of the Mongos component.

    Shard address

    The endpoint of a shard component, including the endpoints of the primary, secondary, and read-only nodes.

    Note

    • By default, the console displays only the endpoints for Mongos. To get the endpoints for a shard and Configserver, you must apply for the endpoint of the corresponding node.

    • You can see the read-only node endpoint for a shard component only if the shard component contains read-only nodes.

    Configserver address

    The endpoint of a Configserver component, including the endpoints of the primary and secondary nodes.

    Note

    • By default, the console displays only the endpoints for Mongos. To get the endpoints for a shard and Configserver, you must apply for the endpoint of the corresponding node.

    • You can apply for a Configserver endpoint only for sharded cluster instances that use local disks.

    The formats, parameters, and examples for each endpoint type are as follows:

    ConnectionStringURI SRV address

    Format:

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

    Parameters:

    Parameter

    Description

    mongodb+srv://

    The prefix of the connection string. It indicates that a DNS SRV record is used for service discovery.

    <username>

    The name of the database account. The default value is root.

    <password>

    The password of the database account.

    <srv-host>

    The hostname.

    <database>

    The name of the database to access. The default value is admin.

    authSource=<authenticationDatabase> (Optional)

    This parameter specifies the database to which the 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 overwrites the authentication property of <database>. Therefore, to change the authentication database, you must manually specify authSource=<authenticationDatabase> instead of changing the <database> parameter. For more information, see the official MongoDB documentation.

    <other_options>

    Other optional parameters.

    Note

    The SSL option for an SRV connection is true by default. If you do not need to use an SSL-encrypted connection, add the ssl=false parameter to the connection string. For more information about optional parameters, see the official MongoDB documentation.

    Example:

    The database account is test and is in the admin database.

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

    ConnectionStringURI address

    The following sections describe the ConnectionStringURI addresses for the Mongos and shard components.

    Mongos

    Important

    For production environments, connect applications to the database using a ConnectionStringURI. The client automatically sends requests to multiple Mongos nodes for load balancing. If a Mongos node fails, the client automatically performs a failover and sends requests to a healthy Mongos node.

    Format:

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

    Parameter

    Description

    <username>

    The name of the database account. The default value is root.

    <password>

    The password of the database account.

    <host>

    The Domain Name of a node in the Mongos component.

    <port>

    The Port of a node in the Mongos component.

    <database>

    The name of the database to access. The default value is admin.

    authSource=<authenticationDatabase> (Optional)

    This parameter specifies the database to which the database account belongs. <authenticationDatabase> is the name of the authentication database. If you do not configure this parameter, <database> is used as the authentication database.

    Example:

    The database account test belongs to the admin database.

    mongodb://test:****@s-bp1c010266f6****.mongodb.rds.aliyuncs.com:3717,s-bp1773180e38****.mongodb.rds.aliyuncs.com:3717/admin

    Shard

    The ConnectionStringURI address for a shard component is a high-availability endpoint that provides load balancing and contains the addresses of all nodes in the shard. You can connect to this endpoint to perform read and write operations on the database. For production environments, we recommend that you connect applications to the instance using this address.

    Important

    For production environments, connect applications to the instance using a ConnectionStringURI address. This ensures that the client can always find the primary node and that primary/secondary failovers do not affect application read and write operations.

    Format:

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

    Parameters:

    Parameter

    Description

    <username>

    The name of the database account. The default value is root.

    <password>

    The password of the database account.

    <host>

    The Domain Name of the primary, secondary, and read-only nodes.

    <port>

    The Port of the primary, secondary, and read-only nodes.

    <database>

    The name of the database to access. The default value is admin.

    authSource=<authenticationDatabase> (Optional)

    This parameter specifies the database to which the database account belongs. <authenticationDatabase> is the name of the authentication database. If you do not configure this parameter, <database> is used as the authentication database.

    readPreference=[primary | primaryPreferred | secondary | secondaryPreferred] (Optional)

    This parameter implements read/write splitting and load balancing. It sends write requests to the primary node and read requests to the node specified by the parameter. Valid values:

    • readPreference=primary: Read requests are sent only to the primary node.

    • readPreference=primaryPreferred: Read requests are preferentially sent to the primary node. If the primary node fails, read requests are sent to secondary and read-only nodes.

    • readPreference=secondary: Read requests are sent only to secondary and read-only nodes. If both the secondary and read-only nodes fail, the read request fails and is not sent to the primary node.

    • readPreference=secondaryPreferred: Read requests are preferentially sent to secondary and read-only nodes. If both the secondary and read-only nodes fail, this parameter sends read requests to the primary node.

    Note

    When read requests are sent to secondary and read-only nodes, the load may be uneven. To further specify nodes, set the readPreferenceTags parameter.

    readPreferenceTags=<readonly_Tags> (Optional)

    This parameter preferentially sends read requests to the nodes that correspond to the specified tags. It is typically used with the readPreference parameter and is not compatible with the primary mode. <readonly_Tags> is a list of tag key-value pairs for read-only nodes. The following types are supported:

    • readPreferenceTags=role:electable: Prioritizes reading from secondary nodes.

      Note

      This option is effective only for instances that use cloud disks.

    • readPreferenceTags=role:readonly: Prioritizes reading from read-only nodes.

    The readPreference and readPreferenceTags parameters along with different tag combinations can meet various scenario requirements. The following table describes available parameter combinations.

    Response policy of the primary node to receive read requests

    Node to receive read requests

    Parameter combination solution

    Send failed read requests to the primary node

    Preferentially read data from the primary node

    readPreference=primaryPreferred

    Preferentially read data from secondary and read-only nodes

    readPreference=secondaryPreferred

    Preferentially read data from secondary nodes

    Note

    If secondary nodes fail, read requests are sent to the primary node.

    readPreference=secondaryPreferred&readPreferenceTags=role:electable

    Preferentially read data from read-only nodes

    Note

    If read-only nodes fail, read requests are sent to the primary node.

    readPreference=secondaryPreferred&readPreferenceTags=role:readonly

    Do not send failed read requests to the primary node

    Read data only from secondary and read-only nodes

    readPreference=secondary

    Read data only from secondary nodes

    Note

    If secondary nodes fail, read operations fail.

    readPreference=secondary&readPreferenceTags=role:electable

    Read data only from read-only nodes

    Note

    If read-only nodes fail, read operations fail.

    readPreference=secondary&readPreferenceTags=role:readonly

    Example:

    mongodb://test:****@d-bp1586cb62bf53b****.mongodb.rds.aliyuncs.com:3717,d-bp1586cb62bf53b****.mongodb.rds.aliyuncs.com:3717/admin

    Mongos address

    Format:

    <host>:<port>

    Parameters:

    Parameter

    Description

    <host>

    The Domain Name of a node in the Mongos component.

    <port>

    The Port of a node in the Mongos component.

    Example:

    s-bp1c010266f6****.mongodb.rds.aliyuncs.com:3717

    Shard address

    Format:

    <host>:<port>

    Parameters:

    Parameter

    Description

    <host>

    The Domain Name of a node in the shard component.

    <port>

    The Port of a node in the shard component.

    Example:

    d-bp1c010266f6****.mongodb.rds.aliyuncs.com:3717

    Configserver address

    Format:

    <host>:<port>

    Parameters:

    Parameter

    Description

    <host>

    The Domain Name of a node in the Configserver component.

    <port>

    The Port of a node in the Configserver component.

    Example:

    cs-bp1c010266f6****.mongodb.rds.aliyuncs.com:3717

    Log on to a MongoDB database

    1. Obtain the following information:

      • Database endpoint.

      • The database account. The initial account is root.

        Important

        Do not use the root account to connect to the database in a production environment. You can create a database account and assign permissions.

      • The password for the database account. If you have not set a password or have forgotten it, you can set or reset the password.

      • The database to access. If the database account is root, the corresponding database is admin.

    2. Log on to the database using one of the following methods:

    Common connection scenarios

    FAQ

    Why does the client send requests to nodes that are not in the connection string?

    This behavior is normal and is a core feature of the MongoDB client called service discovery, which is designed to ensure high availability. Service discovery allows the client to automatically adapt to changes in the cluster topology, such as when a primary node goes down, to ensure service continuity. To send requests to only a single connection address, append directConnection=true to your connection string. For more information, see directConnection.

    Example:

    If a five-node instance uses the connection string mongodb://root:xxx@dds-xxxxx1-pub.mongodb.rds.aliyuncs.com:3717,dds-xxxxx2-pub.mongodb.rds.aliyuncs.com:3717/admin, the client also sends requests to the other two nodes, dds-xxxxx3-pub.mongodb.rds.aliyuncs.com:3717,dds-xxxxx4-pub.mongodb.rds.aliyuncs.com:3717, and monitors their status.