How to obtain the endpoint of an ApsaraDB for MongoDB replica set instance - ApsaraDB for MongoDB

ApsaraDB for MongoDB replica set instances provide separate endpoints for primary, secondary, and read-only nodes. They also provide high-availability connection string URIs, such as ConnectionStringURI, ConnectionStringURI SRV, and ReadOnly ConnectionStringURI, for application connections. This topic describes how to retrieve these endpoints and provides connection instructions.

Endpoint details

Choose an endpoint

In a production environment, connect to your instance using a ConnectionStringURI or ConnectionStringURI SRV address to ensure load balancing and high availability. If your instance has read-only nodes, applications that perform only read operations should connect to the instance using a ReadOnly ConnectionStringURI address. We do not recommend connecting to an instance with a single-node endpoint because a primary/secondary switchover can change the role of a node. The following table describes the differences between endpoint types.

Endpoint types

Address type	Description
ConnectionStringURI SRV address (Recommended)	In MongoDB, SRV is a DNS record type that simplifies the connection string and supports automatic discovery of members in a replica set cluster. When you add or remove nodes from a replica set instance, you can use an SRV address to interact with the instance without any perception of the change. 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 Endpoint or Apply for Public SRV Endpoint on the Database Connections page. Before you request a public SRV address, you must first enable a public endpoint for the instance. SRV addresses are supported only for instances that use disks. Applications in a production environment should connect to the database using a ConnectionStringURI SRV address. The client automatically sends requests to multiple nodes of the instance to implement 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 without any perception of the change. This simplifies application design and maintenance. SRV addresses or node auto-discovery are not supported by earlier driver versions, 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.
ConnectionStringURI address	A ConnectionStringURI address provides load balancing and high availability. This address contains the addresses of all nodes in the instance. You can connect to this address to perform read and write operations on the database. Important Applications in a production environment should connect to the instance using a ConnectionStringURI address. This ensures that read and 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 you add or remove nodes from a replica set instance, you must modify this connection string to add or remove the connection information of the corresponding nodes.
ReadOnly ConnectionStringURI address	A ReadOnly ConnectionStringURI address contains only the addresses of all read-only nodes in the instance. When you connect to this address, read requests are sent to the read-only nodes, and write requests are sent to the primary node. Note If your instance has read-only nodes, applications that perform only read operations should connect to the instance using this address. You can see the ReadOnly ConnectionStringURI address only if the instance has read-only nodes. If a read-only node in the instance fails, read requests are automatically switched to the next read-only node. This does not affect the read operations of your application. If all read-only nodes fail, a connection error occurs if you continue to use this endpoint.
Primary address	The endpoint of the primary node. You can connect to this address to perform read and write operations on the database. Important Do not connect applications in a production environment to the instance using this address. When a primary/secondary switchover is triggered for the instance, the primary node address changes. You must connect to the new primary node to ensure that read and write operations are not affected.
Secondary address	The endpoint of a secondary node. You can connect to this address to perform only read operations on the database. Important Do not connect applications in a production environment to the instance using this address. When a primary/secondary switchover is triggered for the instance, a secondary node may be promoted to the primary node. The primary node address supports write operations, which can cause data and permission security issues.
ReadOnly address	The endpoint of a read-only node. You can connect to this address to perform only read operations on the database. Note This address is displayed only when the instance has read-only nodes.

Connection address format

ConnectionStringURI SRV address

Format:

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

Parameter description:

Parameter	Description
`mongodb+srv://`	The prefix of the connection string. It indicates that DNS SRV records are used for service discovery.
`<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 access. The default value is admin.
`authSource=<authenticationDatabase>` (Optional)	This parameter specifies the database where the database account is located. `<authenticationDatabase>` is the name of the authentication database. Note The TXT record of the SRV connection string for ApsaraDB for MongoDB specifies `authSource=admin`. This 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.
`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 this 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 all 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 all 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 prioritizes sending read requests to nodes that match 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 key-value pairs for the tags of read-only nodes. The following types are supported: `readPreferenceTags=role:electable`: Preferentially read from secondary nodes. Note This option is effective only for instances that use disks. `readPreferenceTags=role:readonly`: Preferentially read from read-only nodes.
`<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.

You can use the readPreference and readPreferenceTags parameters in a MongoDB instance. By combining different tags, you can meet the requirements of various scenarios:

Read request routing policy	Target node for read requests	Parameter combination
Read requests can fall back to the primary node	Read from the primary node first	`readPreference=primaryPreferred`
	Read from secondary and read-only nodes first	`readPreference=secondaryPreferred`
	Read from secondary nodes first Note If a secondary node fails, the read request is sent to the primary node.	`readPreference=secondaryPreferred&readPreferenceTags=role:electable`
	Read from read-only nodes first Note If a read-only node fails, the read request is sent to the primary node.	`readPreference=secondaryPreferred&readPreferenceTags=role:readonly`
Read requests do not fall back to the primary node	Read from secondary and read-only nodes only	`readPreference=secondary`
	Read from secondary nodes only Note If all available secondary nodes fail, the read operation fails.	`readPreference=secondary&readPreferenceTags=role:electable`
	Read from read-only nodes only Note If all available read-only nodes fail, the read operation fails.	`readPreference=secondary&readPreferenceTags=role:readonly`

Example:

The database account is test, and it belongs to the admin database.

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

ConnectionStringURI address

Format:

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

Parameter description:

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.
`replicaSet=<replicaSet_value>`	This parameter sends read requests to all nodes of the replica set instance. `<replicaSet_value>` is the unique ID of the high-availability endpoint of the instance.
`authSource=<authenticationDatabase>` (Optional)	This parameter specifies the database where the database account is located. `<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 this 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 all 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 all 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 prioritizes sending read requests to nodes that match 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 key-value pairs for the tags of read-only nodes. The following types are supported: `readPreferenceTags=role:electable`: Preferentially read from secondary nodes. Note This option is effective only for instances that use disks. `readPreferenceTags=role:readonly`: Preferentially read from read-only nodes.

You can use the readPreference and readPreferenceTags parameters in a MongoDB instance. By combining different tags, you can meet the requirements of various scenarios:

Read request routing policy	Target node for read requests	Parameter combination
Read requests can fall back to the primary node	Read from the primary node first	`readPreference=primaryPreferred`
	Read from secondary and read-only nodes first	`readPreference=secondaryPreferred`
	Read from secondary nodes first Note If a secondary node fails, the read request is sent to the primary node.	`readPreference=secondaryPreferred&readPreferenceTags=role:electable`
	Read from read-only nodes first Note If a read-only node fails, the read request is sent to the primary node.	`readPreference=secondaryPreferred&readPreferenceTags=role:readonly`
Read requests do not fall back to the primary node	Read from secondary and read-only nodes only	`readPreference=secondary`
	Read from secondary nodes only Note If all available secondary nodes fail, the read operation fails.	`readPreference=secondary&readPreferenceTags=role:electable`
	Read from read-only nodes only Note If all available read-only nodes fail, the read operation fails.	`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****

ReadOnly ConnectionStringURI address

Format:

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

Description:

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 read-only node.
`<port>`	The Port of the read-only node.
`<database>`	The name of the database to access. The default value is admin.
`readPreference=secondary&readPreferenceTags=role:readonly`	This parameter sends read requests to read-only nodes. `readPreferenceTags` is a list of key-value pairs for the tags of read-only nodes. The value is fixed at `role:readonly`. This parameter cannot be modified.
`replicaSet=<replicaSet_value>`	This parameter sends read requests to all nodes of the replica set instance. `<replicaSet_value>` is the unique ID of the high-availability endpoint of the instance.
`authSource=<authenticationDatabase>` (Optional)	This parameter specifies the database where the database account is located. `<authenticationDatabase>` is the name of the authentication database. If you do not configure this parameter, `<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 address

Format:

mongodb://<username>:<password>@<host>:<port>/<database>?[directConnection=true]

Description:

Parameter	Description
`<username>`	The name of the database account.
`<password>`	The password of the database account.
`<host>`	The Domain Name of the primary node.
`<port>`	The Port of the primary node.
`<database>`	The name of the database to access. The default value is admin.
`directConnection=true` (Optional)	Specifies that requests are sent only to the current endpoint (primary node). If you specify this parameter and set its value to `true`, both read and write requests are sent to the primary node. If you do not specify this parameter or set its value to `false`, read requests may be forwarded to other nodes.

Example:

mongodb://root:****@dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717/admin?directConnection=true

Secondary address

Format:

mongodb://<username>:<password>@<host>:<port>/<database>?[directConnection=true]

Description:

Parameter	Description
`<username>`	The name of the database account.
`<password>`	The password of the database account.
`<host>`	The Domain Name of the secondary node.
`<port>`	The Port of the secondary node.
`<database>`	The name of the database to access. The default value is admin.
`directConnection=true` (Optional)	Specifies that requests are sent only to the current endpoint (secondary node). If you specify this parameter and set its value to `true`, write requests are rejected. If you do not specify this parameter or set its value to `false`, write requests are forwarded to the primary node.

For example:

mongodb://root:****@dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717/admin?directConnection=true

ReadOnly address

Format:

mongodb://<username>:<password>@<host>:<port>/<database>?[directConnection=true]

Description:

Parameter	Description
`<username>`	The name of the database account.
`<password>`	The password of the database account.
`<host>`	The Domain Name of the read-only node.
`<port>`	The Port of the read-only node.
`<database>`	The name of the database to access. The default value is admin.
`directConnection=true`	Specifies that requests are sent only to the current endpoint (read-only node). If you specify this parameter and set its value to `true`, write requests are rejected. If you do not specify this parameter or set its value to `false`, write requests are forwarded to the primary node.

Example:

mongodb://root:****@dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717/admin?directConnection=true

Network types for connection addresses

Network type	Description
Private network	Virtual private cloud (VPC): A VPC is an isolated network that provides higher security and performance. ApsaraDB for MongoDB instances provide VPC endpoints by default. Classic network: A non-isolated network that relies on security groups or whitelists of Alibaba Cloud services for protection. 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	Connecting to an instance over the Internet poses security risks. ApsaraDB for MongoDB instances do not provide public endpoints by default. To connect over the public network, you can manually apply for a public endpoint.

Obtain a database endpoint

Go to the Replica Set Instances page. At the top of the page, select a resource group and a region, and then click the ID of the target instance.
In the navigation pane on the left of the instance details page, click Database Connections.

Log on to a MongoDB database

Retrieve the following information:
- Database endpoint.
- The database account. The initial account is root.
  Note
  Do not use the root account to connect to the database in a production environment. You can create a database account and grant 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.
Log on to the database. You can use one of the following methods:

Common connection scenarios

FAQ

Why does the client send requests to other nodes in the instance when I connect using a single-node endpoint?

This is normal and expected behavior. It is caused by service discovery, a core feature of the MongoDB client that implements high availability (HA). This feature allows the client to automatically adapt to cluster topology changes, such as a primary node breakdown, to ensure service continuity. You can append directConnection=true to the connection string to specify that requests are sent only to the current endpoint. For more information, see directConnection.