Home PageApsaraDB for MongoDBUser GuideNetwork connection managementOverview of instance connectionsConnect to a replica set instance
Search for Help Content

Connect to a replica set instance

Updated at: 2025-02-28 08:31
Product
Community

ApsaraDB for MongoDB provides a connection string for the primary node, each secondary node, or each read-only node in a replica set instance. ApsaraDB for MongoDB also provides the following high-availability (HA) Uniform Resource Identifiers (URIs) for application connection: a connection string URI and a read-only connection string URI. This topic describes how to view the connection strings and HA URIs of a replica set instance and how to log on to a specific database of the instance.

Connection strings and URIs

Select endpoints

We recommend that you use a connection string URI to connect to an instance to achieve load balancing and high availability in the production environment. If an instance contains read-only nodes, we recommend that you use a read-only connection string URI to connect to the instance from your application that only read 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.

Endpoint types

Endpoint type

Description

Endpoint type

Description

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.

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 specified, read requests are sent to the primary node.

SRV HA endpoint

SRV HA endpoints can simplify the maintenance and management of instances. You do not need to modify the endpoints when 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 an instance. This way, your client can automatically distribute requests to multiple nodes to balance the loads within the instance. If a node fails, your client can automatically redirect requests to other healthy 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, apply for the public endpoint of the instance.

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

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 to the instance from your application that only read data to the instance.

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

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

Endpoint formats

Connection string URI
SRV HA endpoint
Read-only connection string URI
Primary endpoint
Secondary endpoint
Read-only endpoint

Format:

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

The following table describes the parameters that are included in the preceding format.

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

Format:

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

The following table describes the parameters that are included in the preceding format.

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

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

Note

The TXT record of the SRV connection string of an ApsaraDB for MongoDB instance indicates authSource=admin. This way, the database specified by the <database> parameter is not authenticated. Therefore, when you want to modify the authentication database, you must manually specify authSource=<authenticationDatabase> instead of modifying the <database> parameter. For more information, see Connection Strings.

<other_options>

Other optional parameters.

Note

The default value of the ssl parameter in an SRV HA endpoint is true. If you do not need to use SSL to encrypt connections, add the ssl parameter that is set to false to the endpoint. For more information about the optional parameters, see Connection Strings.

Example:

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

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

Format:

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

The following table describes the parameters that are included in the preceding format.

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 read-only node.

<port>

The port used to connect to 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 indicates the tag keys and tag values corresponding to the read-only node. The value is fixed to role:readonly. You cannot change the parameter.

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.

Example:

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

Format:

<host>:<port>

The following table describes the parameters that are included in the preceding format.

Parameter

Description

<host>

The domain name used to connect to the primary node.

<port>

The port used to connect to the primary node.

Example:

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

Format:

<host>:<port>

The following table describes the parameters that are included in the preceding format.

Parameter

Description

<host>

The domain name used to connect to the secondary node.

<port>

The port used to connect to the secondary node.

Example:

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

Format:

<host>:<port>

The following table describes the parameters that are included in the preceding format.

Parameter

Description

<host>

The domain name used to connect to the read-only node.

<port>

The port used to connect to the read-only node.

Example:

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

Network types of endpoints

Network type

Description

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

View the connection strings and URIs of the instance

  1. Go to the Replica Set Instances page. In the top navigation bar, select the region in which the instance resides. Then, find the standalone instance that you want to manage and click the ID of the instance.

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

Log on to a specific database of the instance

  1. Obtain the following information:

    • The connection strings and HA URIs of the instance. For more information, see View the connection strings and URIs of a replica set instance.

    • The account that is used to connect to a specific database of the 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 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 account that is used to connect to a specific database of the instance. If you did not configure a password for the account or have forgotten the password, configure or reset 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 account is root, enter admin.

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

Common connection scenarios

FAQ

Previous: Overview of instance connectionsNext: Connect to a sharded cluster instance
  • On this page （1, T）
  • Connection strings and URIs
  • Select endpoints
  • Endpoint types
  • Endpoint formats
  • Network types of endpoints
  • View the connection strings and URIs of the instance
  • Log on to a specific database of the instance
  • Common connection scenarios
  • FAQ
Feedback
phone Contact Us

Chat now with Alibaba Cloud Customer Service to assist you in finding the right products and services to meet your needs.

alicare alicarealicarealicare