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:Nov 29, 2024

    ApsaraDB for MongoDB provides a connection string for each mongos component, each shard component, and the ConfigServer component in a sharded cluster instance. ApsaraDB for MongoDB also provides connection string Uniform Resource Identifiers (URIs) for mongos and shard nodes in the instance. The URIs of a sharded cluster instance are used to establish high-availability (HA) connections between your application and the instance. This topic describes how to view the connection strings and URIs of a sharded cluster instance and how to log on to a specific database of the instance.

    View the connection strings and URIs of the instance

    1. Go to the Sharded Cluster Instances page. In the top navigation bar, select the region in which the instance resides. Then, find the instance and click the ID of the instance.

    2. In the left-side navigation pane of the instance details page, click Database Connections. In the page that appears, view the connection information of a node in the instance.

    Connection strings and URIs

    Network types of endpoints

    Network type

    Note

    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. If you want to connect to an ApsaraDB for MongoDB instance over the Internet, you must apply for a public endpoint. For more information, see (Optional) Apply for a public endpoint for an ApsaraDB for MongoDB instance.

    Endpoint types

    Endpoint type

    Description

    Mongos endpoint

    The endpoint of the primary node in a mongos component in the instance. The endpoint allows you to connect to the primary node in the component.

    Note

    When you perform routine testing, you need only to connect to a mongos node.

    Shard endpoint

    The endpoint of a shard node in a shard component in the instance. The endpoint allows you to connect to the primary node, a secondary node, or a read-only node in the component.

    Note

    • By default, only the connection strings of mongos nodes in the instance are displayed in the ApsaraDB for MongoDB console. To view the connection string of a shard or ConfigServer node in the instance, apply for an endpoint for the node. For more information, see Apply for an endpoint for a shard or ConfigServer node in a sharded cluster instance.

    • You can view the connection strings of read-only nodes in a shard component only when the read-only nodes exist in the component.

    ConfigServer endpoint

    The endpoint of a ConfigServer node in the ConfigServer component in the instance. The endpoint allows you to connect to the primary node or a secondary node in the component.

    Note

    • By default, only the connection strings of mongos nodes in the instance are displayed in the ApsaraDB for MongoDB console. To view the connection string of a shard or ConfigServer node in the instance, apply for an endpoint for the node. For more information, see Apply for an endpoint for a shard or ConfigServer node in a sharded cluster instance.

    • You can apply only for an endpoint for a ConfigServer node in a sharded cluster instance that uses local disks.

    Connection string URI

    ApsaraDB for MongoDB provides a connection string URI for mongos or shard nodes in the instance.

    If your application is deployed in a production environment, we recommend that you use a connection string URI to connect to the instance. This way, your client can automatically distribute requests to mongos nodes to balance the loads within the instance. If a mongos node fails, your client can automatically redirect requests to other healthy mongos nodes.

    Note

    By default, only the connection string URI of mongos nodes in the instance are displayed in the ApsaraDB for MongoDB console. To view the connection string URI of shard nodes in the instance, apply for an endpoint for a shard node. For more information, see Apply for an endpoint for a shard or ConfigServer node in a sharded cluster instance.

    SRV HA endpoint

    SRV HA endpoints can simplify the maintenance and management of sharded cluster instances. You do not need to modify the endpoints when mongos nodes are added or removed. Your client can interact with the instances without service interruptions, which simplifies the design and maintenance of your application.

    If your application is deployed in a production environment, we recommend that you use a connection string URI to connect to the instance. This way, your client can automatically distribute requests to mongos nodes to balance the loads within the instance. If a mongos node fails, your client can automatically redirect requests to other healthy mongos nodes.

    Important

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

    • Before you apply for a public SRV endpoint, activate the public endpoint of a mongos node. After you use a public SRV endpoint to connect to an instance, your client automatically redirect requests to a mongos node whose public endpoint is activated.

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

    • The private SRV endpoint of a sharded cluster instance deployed in a virtual private cloud (VPC) can be associated with a maximum of 20 mongos nodes in the instance. If the endpoint is associated with more than 20 mongos nodes, the excess nodes cannot offload request due to the limits imposed by the Domain Name System (DNS) resolution protocol in the VPC. The public SRV endpoint of the instance is not subject to this limit.

    The following section describes the format, parameters, and examples of each endpoint:

    Mongos endpoints

    Format:

    <host>:<port>

    Parameters:

    Parameter

    Description

    <host>

    The domain name of the node in the mongos component.

    <port>

    The port number of the node in the mongos component.

    Example:

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

    Shard endpoints

    Format:

    <host>:<port>

    Parameters:

    Parameter

    Description

    <host>

    The domain name of the node in the shard component.

    <port>

    The port number of the node in the shard component.

    Example:

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

    ConfigServer endpoints

    Format:

    <host>:<port>

    Parameters:

    Parameter

    Description

    <host>

    The domain name of the node in the ConfigServer component.

    <port>

    The port number of the node in the ConfigServer component.

    Example:

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

    Connection string URIs

    The following section describes the connection string URI of mongos or shard shards.

    Mongos nodes

    Important

    If your application is deployed in a production environment, we recommend that you use a connection string URI to connect to the instance. This way, your client can automatically distribute requests to mongos nodes to balance the loads within the instance. If a mongos node fails, your client can automatically redirect requests to other healthy mongos nodes.

    Format: 

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

    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 of the node in the mongos component.

    <port>

    The port number of the node in the mongos component.

    <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> indicates the name of the database used for authentication. If you do not specify the authentication database, the database specified by <database> is used as the authentication database.

    Example:

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

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

    Shard nodes

    The connection string URI of shard nodes in the instance is an HA connection string URI that can implement load balancing and ensure high availability. You can use the connection string URI to connect to the instance to perform read/write operations on databases in the instance. The endpoint allows you to connect to all shard nodes in the instance. If your application is deployed in a production environment, we recommend that you use a connection string URI to connect to the instance.

    Important

    If you use this URI to connect to the instance, all requests are processed by primary nodes in the instance. Read/write operations are not affected by a primary/secondary switchover.

    Format:

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

    Parameters:

    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 used to connect to the primary, secondary, or read-only node.

    <port>

    The port used to connect to the primary, secondary, or 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 instance. <replicaSet_value> indicates the unique ID of the HA endpoint of the instance.

    authSource=<authenticationDatabase> (optional)

    The database to which the specified database account belongs. <authenticationDatabase> indicates the name of the database used for authentication. If you do not specify the authentication database, the database specified by <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 nodes.

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

    If read requests are sent to secondary and read-only nodes, uneven loads may occur. To further specify nodes that receive the read requests, configure the readPreferenceTags parameter.

    readPreferenceTags=<readonly_Tags> (optional)

    Specifies that read requests are preferentially sent to the node corresponding to the specified tag. In most cases, the parameter is specified together with the readPreference parameter and is incompatible with the primary mode. <readonly_Tags> indicates the tag keys and tag values of the read-only node and contains the role:electable and role:readonly options. Valid values:

    • readPreferenceTags=role:electable: Data is preferentially read from the secondary node.

      Note

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

    • readPreferenceTags=role:readonly: Data is preferentially read from the read-only node.

    The readPreference and readPreferenceTags parameters are available for instances. The combinations of different tags can meet the requirements of various scenarios. The following table describes parameter combinations in different scenarios.

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

    SRV HA endpoints

    Format:

    mongodb+srv://<username>:<password>@<srv-host>/<database>?<options>

    Parameters:

    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 used to log on to the database. Default value: root.

    <password>

    The password of the database account.

    <srv-host>

    The hostnames.

    <database>

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

    <option>

    Other optional parameters.

    Note

    The default value of the ssl parameter in an SRV HA endpoint is true. If you no longer use the SSL encryption feature, add the ssl parameter that is set to false to the endpoint of the instance. For more information about the optional parameters, see MongoDB documentation.

    Example:

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

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

    Log on to a specific database of the instance

    1. Obtain the following information:

      • The connection strings or URIs of the instance. For more information, see View the connection strings and URIs of a sharded cluster instance.

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

        Important

        We recommend that you do not connect to a database in the production environment by using the root account. You can create database accounts and grant permissions to the accounts based on your business requirements. For more information, see Manage the permissions of MongoDB database users.

      • The password of the database account that is used to connect to the instance. If you do not specify a password for the database account or you forget the password of the account, you can set or change the password of the account. For more information, see (Optional) Reset a password.

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

    2. Log on to a specific database. For more information, see the following topics:

    Common connection scenarios

    FAQ