Get replica set instance connection address-ApsaraDB for MongoDB(MongoDB)-阿里云帮助中心

An ApsaraDB for MongoDB replica set instance provides separate endpoints for its primary, secondary, and read-only nodes, as well as high-availability ConnectionStringURI, ConnectionStringURI SRV, and ReadOnly ConnectionStringURI for application connections. This topic explains how to get these endpoints and connect to your instance.

Connection Address Description

Endpoint selection

In a production environment, connect to your instance using the ConnectionStringURI or ConnectionStringURI SRV address for load balancing and high availability. If your instance has read-only nodes, connect read-only applications using the ReadOnly ConnectionStringURI address. Avoid using a single-node connection address, as a failover can change node roles. See the following table for the differences between connection types.

Endpoint type

Address type	Description
ConnectionStringURI SRV address [Recommended]	In MongoDB, SRV is a DNS record type that simplifies the MongoDB connection string and supports automatic discovery of members in a replica set. When nodes are added to or removed from a replica set instance, using an SRV address allows an application to interact with the instance seamlessly. This simplifies application design and maintenance. Important By default, the SRV address is not displayed in the console. To use it, go to the Database Connection page and click Apply for Private SRV Address or Apply for Public SRV Address. To apply for a public SRV address, you must first enable a public address for the instance. SRV addresses are supported only for instances with cloud disks. We recommend that applications in a production environment connect to the database by using the ConnectionStringURI SRV address. The client automatically distributes requests across 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. Older driver versions may not support SRV addresses or automatic node discovery. For example: 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 driver versions earlier than 3.3.0. mongo-cxx-driver versions earlier than 3.8.
ConnectionStringURI address	The ConnectionStringURI address provides load balancing and high availability. It contains the addresses of all nodes in the instance, allowing you to perform read and write operations on the database. Use this address if your driver version does not support SRV addresses or automatic node discovery. Important We recommend that applications in a production environment use the ConnectionStringURI address to connect to the instance. This prevents a failover from affecting your application's read and write operations. If the readPreference and readPreferenceTags parameters are not set, the client sends read requests to the primary node. After you add or remove nodes from a replica set instance, you must update the connection string to reflect these changes.
ReadOnly ConnectionStringURI address	The ReadOnly ConnectionStringURI address contains only the addresses of all read-only nodes in the instance. When you connect to this address, the client sends read requests to read-only nodes and write requests to the primary node. Note If the instance has read-only nodes, we recommend that read-only applications connect to the instance by using this address. The ReadOnly ConnectionStringURI address is visible only if the instance has read-only nodes. If a read-only node in the instance fails, read requests are automatically redirected to the next available read-only node, so the read operations of your application are not affected. If all read-only nodes fail, connections to this address will fail.
Primary address	The connection address of the primary node. You can connect to this address to perform read and write operations on the database. Important We do not recommend that applications in a production environment connect to the instance by using this address. After a failover, the primary node address changes. You must connect to the new primary node to avoid disrupting your read and write operations.
Secondary address	The connection address of a secondary node. You can connect to this address to perform only read operations on the database. Important We do not recommend that applications in a production environment connect to the instance by using this address. After a failover, a secondary node may be promoted to the primary. If your application continues to use this address, it might connect to a primary node, which can lead to permission conflicts or unintended write operations.
ReadOnly address	The connection address 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 if 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>

Parameters:

Parameter	Description
`mongodb+srv://`	The connection string prefix, indicating the use of DNS SRV records for service discovery.
`<username>`	The name of the database account.
`<password>`	The password for the database account.
`<srv-host>`	The hostname.
`<database>`	The database to access. Default: admin.
`authSource=<authenticationDatabase>` (Optional)	This parameter specifies the database to which the database account belongs. `<authenticationDatabase>` is the name of the authentication database. Note For ApsaraDB for MongoDB SRV connection strings, the TXT record specifies `authSource=admin`, which overrides the authentication attribute of `<database>`. If you want to change the authentication database, you must explicitly set `authSource=<authenticationDatabase>` instead of changing the `<database>` parameter. For more information, see the official MongoDB documentation.
`readPreference=[primary \| primaryPreferred \| secondary \| secondaryPreferred]` (Optional)	This parameter enables read/write splitting and load balancing. It routes write requests to the primary node and read requests to the specified node type. Valid values: `readPreference=primary`: Routes read requests only to the primary node. `readPreference=primaryPreferred`: Routes read requests to the primary node first. If the primary node is unavailable, requests are routed to secondary and read-only nodes. `readPreference=secondary`: Routes read requests only to secondary and read-only nodes. If all secondary and read-only nodes are unavailable, the request fails and is not routed to the primary node. `readPreference=secondaryPreferred`: Routes read requests to secondary and read-only nodes first. If all secondary and read-only nodes are unavailable, requests are routed to the primary node. Note When read requests are routed to secondary and read-only nodes, the load may be uneven. To further specify the nodes, set the readPreferenceTags parameter.
`readPreferenceTags=<readonly_Tags>` (Optional)	This parameter routes read requests first 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 pair tags for read-only nodes. Supported types: `readPreferenceTags=role:electable`: Prioritizes secondary nodes for read requests. Note This option is valid only for cloud disk instances. `readPreferenceTags=role:readonly`: Prioritizes read-only nodes for read requests.
`<other_options>`	Other optional parameters. Note The SSL option for SRV connections is true by default. To disable SSL encryption, add the `ssl=false` parameter to the connection string. For more information about optional parameters, see the official MongoDB documentation.

You can combine the readPreference and readPreferenceTags parameters for different scenarios:

Failover behavior	Preferred nodes	Parameter combination
If reads from preferred nodes fail, route read requests to the primary node	Prefer the primary node	`readPreference=primaryPreferred`
	Prefer secondary and read-only nodes	`readPreference=secondaryPreferred`
	Prefer secondary nodes Note If secondary nodes are unavailable, read requests fail over to the primary node.	`readPreference=secondaryPreferred&readPreferenceTags=role:electable`
	Prefer read-only nodes Note If read-only nodes are unavailable, read requests fail over to the primary node.	`readPreference=secondaryPreferred&readPreferenceTags=role:readonly`
If reads from preferred nodes fail, do not route read requests to the primary node	Read only from secondary and read-only nodes	`readPreference=secondary`
	Read only from secondary nodes Note If a secondary node is unavailable, the read operation fails.	`readPreference=secondary&readPreferenceTags=role:electable`
	Read only from read-only nodes Note If a read-only node is unavailable, the read operation fails.	`readPreference=secondary&readPreferenceTags=role:readonly`

Example:

This example uses the 'test' database account to connect 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>]

Parameters:

Parameter	Description
`<username>`	The name of the database account. Default: root.
`<password>`	The password for the database account.
`<host>`	The domain names of the primary, secondary, and read-only nodes.
`<port>`	The ports of the primary, secondary, and read-only nodes.
`<database>`	The database to access. Default: admin.
`replicaSet=<replicaSet_value>`	Routes read requests to all nodes in the replica set instance. `<replicaSet_value>` is the unique ID of the high-availability endpoint for the instance.
`authSource=<authenticationDatabase>` (Optional)	Specifies the authentication database where the database account is defined. `<authenticationDatabase>` is the name of the authentication database. If omitted, the authentication database defaults to the value of `<database>`.
`readPreference=[primary \| primaryPreferred \| secondary \| secondaryPreferred]` (Optional)	This parameter enables read/write splitting and load balancing. It routes write requests to the primary node and read requests to the specified node type. Valid values: `readPreference=primary`: Routes read requests only to the primary node. `readPreference=primaryPreferred`: Routes read requests to the primary node first. If the primary node is unavailable, requests are routed to secondary and read-only nodes. `readPreference=secondary`: Routes read requests only to secondary and read-only nodes. If all secondary and read-only nodes are unavailable, the request fails and is not routed to the primary node. `readPreference=secondaryPreferred`: Routes read requests to secondary and read-only nodes first. If all secondary and read-only nodes are unavailable, requests are routed to the primary node. Note When read requests are routed to secondary and read-only nodes, the load may be uneven. To further specify the nodes, set the readPreferenceTags parameter.
`readPreferenceTags=<readonly_Tags>` (Optional)	This parameter routes read requests first 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 pair tags for read-only nodes. Supported types: `readPreferenceTags=role:electable`: Prioritizes secondary nodes for read requests. Note This option is valid only for cloud disk instances. `readPreferenceTags=role:readonly`: Prioritizes read-only nodes for read requests.

You can combine the readPreference and readPreferenceTags parameters for different scenarios:

Failover behavior	Preferred nodes	Parameter combination
If reads from preferred nodes fail, route read requests to the primary node	Prefer the primary node	`readPreference=primaryPreferred`
	Prefer secondary and read-only nodes	`readPreference=secondaryPreferred`
	Prefer secondary nodes Note If secondary nodes are unavailable, read requests fail over to the primary node.	`readPreference=secondaryPreferred&readPreferenceTags=role:electable`
	Prefer read-only nodes Note If read-only nodes are unavailable, read requests fail over to the primary node.	`readPreference=secondaryPreferred&readPreferenceTags=role:readonly`
If reads from preferred nodes fail, do not route read requests to the primary node	Read only from secondary and read-only nodes	`readPreference=secondary`
	Read only from secondary nodes Note If a secondary node is unavailable, the read operation fails.	`readPreference=secondary&readPreferenceTags=role:electable`
	Read only from read-only nodes Note If a read-only node is unavailable, 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****

Read-only ConnectionStringURI address

Format:

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

Parameters:

Parameter	Description
`<username>`	The name of the database account. Default: root.
`<password>`	The password for the database account.
`<host>`	The domain name of the read-only node.
`<port>`	The port of the read-only node.
`<database>`	The database to access. Default: admin.
`readPreference=secondary&readPreferenceTags=role:readonly`	This parameter routes read requests to read-only nodes. `readPreferenceTags` specifies the list of key-value pair tags for read-only nodes. For this connection type, the value must be `role:readonly`.
`replicaSet=<replicaSet_value>`	Routes read requests to all nodes in the replica set instance. `<replicaSet_value>` is the unique ID of the high-availability endpoint for the instance.
`authSource=<authenticationDatabase>` (Optional)	Specifies the authentication database where the database account is defined. `<authenticationDatabase>` is the name of the authentication database. If you do not specify 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]

Parameters:

Parameter	Description
`<username>`	The name of the database account.
`<password>`	The password for the database account.
`<host>`	The domain name of the primary node.
`<port>`	The port of the primary node.
`<database>`	The database to access. Default: admin.
`directConnection=true` (Optional)	Sends requests only to the current endpoint (the primary node). If you set this parameter to `true`, all read and write requests are sent to the primary node. If you do not specify this parameter or set it 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]

Parameters:

Parameter	Description
`<username>`	The name of the database account.
`<password>`	The password for the database account.
`<host>`	The domain name of the secondary node.
`<port>`	The port of the secondary node.
`<database>`	The database to access. Default: admin.
`directConnection=true` (Optional)	Sends requests only to the current endpoint (the secondary node). When set to `true`, the node rejects write requests. If this parameter is omitted or set to `false`, write requests are forwarded to the primary node.

Example:

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

Read-only address

Format:

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

Parameters:

Parameter	Description
`<username>`	The name of the database account.
`<password>`	The password for the database account.
`<host>`	The domain name of the read-only node.
`<port>`	The port of the read-only node.
`<database>`	The database to access. Default: admin.
`directConnection=true` (Optional)	Sends requests only to the current endpoint (the read-only node). When set to `true`, the node rejects write requests. If this parameter is omitted or set to `false`, write requests are forwarded to the primary node.

Example:

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

Endpoint network types

Network type	Description
private network	VPC: A VPC is an isolated network that offers enhanced security and performance. By default, ApsaraDB for MongoDB instances provide VPC endpoints. Classic Network: A non-isolated network that relies only on security groups or whitelists for protection. New instances no longer support Classic Network. For more information, see Notice: Classic Network is no longer supported for new ApsaraDB for MongoDB instances.
public network	Connecting to an instance over the public network poses security risks. By default, ApsaraDB for MongoDB instances do not provide public endpoints. If you need to connect over the public network, you can manually apply for a public endpoint.

Database endpoint

Go to the MongoDB Replica Set Instances page, select a resource group and region, and then click the target instance.
In the left navigation pane, click Database Connections.

Connect to a MongoDB database

Get the following information:
- The 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 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. When using the root account, the corresponding database is admin.
Connect to the database by using one of the following methods:

Common connection scenarios

FAQ

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

This behavior is part of the MongoDB client's service discovery feature, which is essential for high availability. This feature allows the client to automatically adapt to changes in the cluster topology, such as a primary node failure, to ensure service continuity. You can append directConnection=true to the connection string to specify that requests are sent only to a single endpoint. For more information, see directConnection.

Example:

When the client endpoint for a five-node instance is configured as 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 and monitors the status of the remaining two nodes, which are not included in the preceding endpoint: dds-xxxxx3-pub.mongodb.rds.aliyuncs.com:3717,dds-xxxxx4-pub.mongodb.rds.aliyuncs.com:3717.

上一篇: Overview of instance connections 下一篇: Connect to a sharded cluster instance