Connection methods for a sharded cluster instance-ApsaraDB for MongoDB(MongoDB)-阿里云帮助中心

Obtain an endpoint

Go to the ApsaraDB for MongoDB Sharded Cluster Instances page. In the top navigation bar, select a resource group and a region. Then, click the target instance's ID.
In the left-side navigation pane of the instance details page, click Database Connections to obtain the endpoint of the target node.

Endpoint details

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.

Endpoint types

Endpoint type	Description
ConnectionStringURI SRV address (Recommended)	An SRV record is a DNS record type that simplifies the connection string and enables automatic cluster member discovery. 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 Connection page. Before you apply for a public SRV address, you must enable public endpoints for the Mongos nodes. After you connect to the MongoDB instance by using the public SRV address, the client automatically sends requests to the Mongos nodes with public endpoints enabled. SRV addresses are supported only for instances with cloud disks. A private SRV address in a VPC can be associated with a maximum of 20 Mongos nodes. Due to the limitations of the DNS resolution protocol within a VPC, if the number of Mongos nodes exceeds 20, requests will not be load-balanced to the additional nodes. This limitation does not apply to public SRV addresses. 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	ApsaraDB for MongoDB provides ConnectionStringURI addresses for Mongos and Shard components. For production environments, use a ConnectionStringURI address instead of a single-node connection string. The client automatically distributes requests across multiple Mongos nodes for load balancing, and performs failover to a healthy Mongos node if one becomes unavailable. Note By default, the console displays only the ConnectionStringURI address for Mongos. To obtain the ConnectionStringURI address for a Shard, you must apply for the endpoint of the corresponding node. If the readPreference and readPreferenceTags parameters are not set, read requests are sent to the primary node. After you add or remove Mongos nodes in a sharded cluster instance, you must update the connection string to reflect these changes.
Mongos address	The endpoint of a Mongos component, including the endpoint of the primary node. Note For daily testing, connecting to a single Mongos node is sufficient.
Shard address	The endpoint of a Shard component, including the endpoints of the primary node, secondary node, and read-only node. Note By default, the console displays only the endpoints of Mongos. To obtain the endpoints of a Shard and a Configserver, you must apply for the endpoint of the corresponding node. The endpoint of a read-only node of a Shard component is displayed only if the Shard component contains read-only nodes.
ConfigServer address	The endpoint of a ConfigServer component, including the endpoints of the primary node and secondary node. Note By default, the console displays only the endpoints of Mongos. To obtain the endpoints of a Shard and a ConfigServer, you must apply for the endpoint of the corresponding node. You can apply for ConfigServer endpoints only for sharded cluster instances with local disks.

The following sections list the format, parameters, and examples for each endpoint type.

ConnectionStringURI SRV address

Format:

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

Parameters:

Parameter	Description
`mongodb+srv://`	A prefix indicating that a DNS SRV record is used for service discovery.
`<username>`	The username of the database account. Default value: root.
`<password>`	The password of the database account.
`<srv-host>`	The hostname.
`<database>`	The name of the database that you want to access. Default value: admin.
`authSource=<authenticationDatabase>` (Optional)	The database to which the database account belongs. `<authenticationDatabase>` specifies the name of the authentication database. Note For ApsaraDB for MongoDB SRV connection strings, the TXT record sets `authSource=admin`. This 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.
`<other_options>`	Other optional parameters. Note For SRV connections, the SSL option is enabled by default. If you do not need to use SSL encryption, add the `ssl=false` parameter to the connection string. For more information about optional parameters, see the official MongoDB documentation.

Example:

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

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

ConnectionStringURI address

ConnectionStringURI addresses are available for both the Mongos and Shard components.

Mongos

Format:

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

Parameter	Description
`<username>`	The username of the database account. Default value: root.
`<password>`	The password of the database account.
`<host>`	The Domain Information of a Mongos node.
`<port>`	The Port of a Mongos node.
`<database>`	The name of the database that you want to access. Default value: admin.
`authSource=<authenticationDatabase>` (Optional)	The database to which the database account belongs. `<authenticationDatabase>` specifies the name of the authentication database. If this parameter is omitted, the client uses the `<database>` for authentication.

Example:

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

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

Shard

The ConnectionStringURI address for a Shard component includes the endpoints of all nodes in the replica set, providing high availability. Use this address in production environments.

Important

In production environments, always connect by using the ConnectionStringURI address. This ensures that your client can always discover and connect to the current primary node, preventing read/write issues after a failover.

Format:

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

Parameters:

Parameter	Description
`<username>`	The username of the database account. Default value: root.
`<password>`	The password of the database account.
`<host>`	The Domain Information 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 that you want to access. Default value: admin.
`authSource=<authenticationDatabase>` (Optional)	The database to which the database account belongs. `<authenticationDatabase>` specifies the name of the authentication database. If this parameter is omitted, the client uses the `<database>` for authentication.
`readPreference=[primary \| primaryPreferred \| secondary \| secondaryPreferred]` (Optional)	Controls the read preference for read/write splitting. Write requests are routed to the primary node, and read requests are routed according to the selected mode. Valid values: `readPreference=primary`: Read requests are sent only to the primary node. `readPreference=primaryPreferred`: Read requests are sent to the primary node first. If the primary node fails, read requests are sent to secondary nodes and read-only nodes. `readPreference=secondary`: Read requests are sent only to secondary nodes 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 sent to secondary nodes and read-only nodes first. If all 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, load distribution may be uneven. To further target specific nodes, set the readPreferenceTags parameter.
`readPreferenceTags=<readonly_Tags>` (Optional)	Routes read requests to nodes that match specific tags. Typically used with readPreference and incompatible with the `primary` mode. `<readonly_Tags>` is a list of tag key-value pairs for read-only nodes. The following types are supported: `readPreferenceTags=role:electable`: Prefer to read from secondary nodes. Note This option takes effect only for instances with cloud disks. `readPreferenceTags=role:readonly`: Prefer to read from read-only nodes.

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://test:****@d-bp1586cb62bf53b****.mongodb.rds.aliyuncs.com:3717,d-bp1586cb62bf53b****.mongodb.rds.aliyuncs.com:3717/admin

Mongos address

Format:

<host>:<port>

Parameters:

Parameter	Description
`<host>`	The Domain Information of a Mongos node.
`<port>`	The Port of a Mongos node.

Example:

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

Shard address

Format:

<host>:<port>

Parameters:

Parameter	Description
`<host>`	The Domain Information of a Shard node.
`<port>`	The Port of a Shard node.

Example:

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

ConfigServer address

Format:

<host>:<port>

Parameters:

Parameter	Description
`<host>`	The Domain Information of a ConfigServer node.
`<port>`	The Port of a ConfigServer node.

Example:

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

Connect to a MongoDB database

Gather the following information:
- Database endpoint.
- A database account. The default account is root.
  
  Important
  For security, avoid using the root account in production environments. 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. When the database account is root, 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.