All Products
Search

This Product

    ApsaraDB for MongoDB:Overview of replica set instance connections

    Document Center

    ApsaraDB for MongoDB:Overview of replica set instance connections

    Last Updated:Apr 27, 2025

    ApsaraDB for MongoDB replica set instances provide separate connection strings for primary nodes, secondary nodes, and read-only nodes, along with high availability (HA) connection string URIs, connection string SRV URIs, and read-only connection string URIs for application connections. This topic describes how to view the connection strings and URIs of a replica set instance and how to log on to a specific database of the instance.

    Connection strings and URIs

    How to choose connection strings

    In the production environment, we recommend that you use the connection string URI or connection string SRV URI to connect to the instance to achieve load balancing and high availability. If the instance contains read-only nodes, we recommend that you use the read-only connection string URI to connect your application that only reads data to the instance. A primary/secondary switchover may cause node roles to change. We recommend that you do not use the connection string of a node to connect to the instance. For differences between connection types, see the following table.

    Connection string types

    Type

    Description

    Connection string SRV URI [Recommended]

    In MongoDB, SRV is a type of DNS record that provides a mechanism to simplify MongoDB connection strings and supports automatic discovery of replica set cluster members.

    When nodes are added to or removed from a replica set instance, using the SRV URI allows seamless interaction with the instance, simplifying application design and maintenance.

    Important

    • By default, the SRV URI is not displayed in the console. To use it, click Apply For Private SRV Endpoint or Apply For Public SRV Endpoint on the Database Connection page.

    • Before you apply for a public SRV endpoint, apply for the public endpoint of the instance.

    • SRV HA endpoints are available only for instances that use cloud disks.

    • We recommend that you use the connection string SRV URI to connect your application in the production environment to the database. The client automatically sends requests to multiple nodes of the instance to achieve load balancing. If a node fails, your client can automatically redirect requests to other healthy nodes. When nodes are added or removed, you can interact with the cluster seamlessly, simplifying application design and maintenance.

    • Low-version drivers do not support SRV URIs or automatic node discovery, such as:

      • 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.

    Connection string URI

    The HA connection string URI of the instance that ensures load balancing and HA. The connection string URI can be used to read data from and write data to databases in the instance. The connection string URI allows you to connect to a node in the instance. You can use this URI when low-version drivers do not support SRV URIs or automatic node discovery.

    Important

    • We recommend that you use the connection string URI to connect your application in the 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 set, read requests are sent to the primary node.

    • When nodes are added to or removed from a replica set instance, you need to modify this connection string to add or remove the corresponding node connection information.

    Read-only connection string URI

    The read-only connection string URI of the instance. The read-only connection string URI allows you to connect to a read-only node in the instance. If you use the read-only connection string URI to connect to the node in the instance, read requests are sent to the node.

    Note

    • If the instance contains read-only nodes, we recommend that you use the read-only connection string URI to connect your application that only read data to the instance.

    • You can view the read-only connection string URI only if your instance contains one or more 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.

    Primary endpoint

    The endpoint of the primary node in the instance. The primary endpoint can be used to read data from and write data to databases in the instance.

    Important

    We recommend that you do not use the primary endpoint to connect your application in the production environment to the instance. When a primary/secondary switchover is triggered for the instance, the primary endpoint changes. In this case, you must connect to the new primary node to ensure that read/write operations are not affected.

    Secondary endpoint

    The endpoint of a secondary node in the instance. A secondary endpoint can be used only to read data from databases in the instance.

    Important

    We recommend that you do not use a secondary endpoint to connect your application in the production environment to the instance. When a primary/secondary switchover is triggered for the instance, a secondary node may become the primary node. The primary endpoint supports write operations, which causes the security issues of data and permissions.

    Read-only endpoint

    The endpoint of a read-only node in the instance. A read-only endpoint can be used only to read data from databases in the instance.

    Note

    The read-only endpoint is displayed only when the instance contains a read-only node.

    Connection string format description

    Connection string SRV URI

    Format:

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

    Field:

    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)

    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 property 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-encrypted connections, you must add the ssl=false parameter to the connection string. For more information about optional parameters, see MongoDB Documentation.

    Example:

    The database account is test and the database is admin.

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

    Connection string URI

    Format:

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

    Field:

    Parameter

    Description

    <username>

    The name of the database account used to log on to the database. 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>

    Specifies that read requests are sent to all nodes of the replica set instance. <replicaSet_value> is the unique ID of the HA connection string of the instance.

    authSource=<authenticationDatabase> (Optional)

    The database to which the specified database account belongs. <authenticationDatabase> is the name of the authentication database. If this parameter is not specified, <database> is used as the authentication database.

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

    Specifies that write requests are sent to the primary node and read requests are sent to nodes specified by the parameter. This parameter ensures read/write splitting and load balancing. 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 secondary and read-only nodes fail, read requests fail and are not sent to the primary node.

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

    Note

    When read requests are sent to secondary and read-only nodes, uneven load may occur. If you need to further specify nodes, set the readPreferenceTags parameter.

    readPreferenceTags=<readonly_Tags> (Optional)

    Specifies that read requests are preferentially sent to the node corresponding to the specified tag. This parameter is typically used with the readPreference parameter and is incompatible with the primary mode. <readonly_Tags> is the list of key-value pairs for read-only node tags. The following types are supported:

    • readPreferenceTags=role:electable: Preferentially read data from secondary nodes.

      Note

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

    • readPreferenceTags=role:readonly: Preferentially read data from read-only nodes.

    MongoDB instances can flexibly use the readPreference and readPreferenceTags parameters. Different tag combinations can meet different scenario requirements:

    Primary node response strategy for read requests

    Nodes to which read requests are sent

    Parameter combination

    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://root:****@dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717,dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717/admin?replicaSet=mgset-6108****

    Read-only connection string URI

    Format:

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

    Field:

    Parameter

    Description

    <username>

    The name of the database account used to log on to the database. 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&readPreferenceTags=role:readonly

    Specifies that read requests are sent to the read-only node. readPreferenceTags represents the list of key-value pairs for read-only node tags, with a fixed value of role:readonly. You cannot change the parameter.

    replicaSet=<replicaSet_value>

    Specifies that read requests are sent to all nodes of the replica set instance. <replicaSet_value> is the unique ID of the HA connection string of the instance.

    authSource=<authenticationDatabase> (Optional)

    The database to which the specified database account belongs. <authenticationDatabase> is the name of the authentication database. If this parameter is not specified, <database> is used as the authentication database.

    Example:

    mongodb://root:****@dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717/admin?readPreference=secondary&readPreferenceTags=role:readonly&replicaSet=mgset-6108****

    Primary endpoint

    Format:

    <host>:<port>

    Field:

    Parameter

    Description

    <host>

    The Domain Name Information of the primary node.

    <port>

    The Port of the primary node.

    Example:

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

    Secondary endpoint

    Format:

    <host>:<port>

    Field:

    Parameter

    Description

    <host>

    The Domain Name Information of the secondary node.

    <port>

    The Port of the secondary node.

    Example:

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

    Read-only endpoint

    Format:

    <host>:<port>

    Field:

    Parameter

    Description

    <host>

    The Domain Name Information of the read-only node.

    <port>

    The Port of the read-only node.

    Example:

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

    Network types of connection strings

    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 no longer support the classic network. For more information, see [Notice] New ApsaraDB for MongoDB instances no longer support the classic network.

    Public network

    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 over the public network, you can manually apply for a public endpoint.

    View the connection strings and URIs of a replica set instance

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

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

    Log on to a specific database of the instance

    1. Obtain the following information:

      • Connection strings and URIs.

      • The account that is used to connect to the replica set instance. The initial account is the root account.

        Note

        We recommend that you do not connect to a database in the production environment by using the root account. You can create a database account and assign permissions.

      • The password of the account that is used to connect to the replica set instance. If you have not set a password or forget the password, you can set or reset the password.

      • The name of the database to which you want to connect. If the username is root, enter admin.

    2. Log on to the database. You can use any of the following methods:

    Common connection scenarios

    FAQ