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

ApsaraDB for MongoDB sharded cluster instances provide separate endpoints for the Mongos, Shard, and Configserver components, along with high availability ConnectionStringURI and ConnectionStringURI SRV addresses. This topic describes how to obtain and use these endpoints.

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

Network types of endpoints

Network type	Description
Private network	VPC: A Virtual Private Cloud (VPC) is an isolated network that provides enhanced security and performance. ApsaraDB for MongoDB instances provide VPC endpoints by default. Classic network: A non-isolated network protected by security groups or whitelists. 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	Due to security risks, ApsaraDB for MongoDB instances do not provide public endpoints by default. If you need to connect to your instance over a public network, you can manually apply for a public endpoint.

Endpoint types

Endpoint type	Description
ConnectionStringURI SRV address (Recommended)	In MongoDB, an SRV record is a DNS type that simplifies the connection string and supports 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 you connect your application to the database by using a ConnectionStringURI SRV address in production environments. The client automatically sends requests to multiple nodes of the instance for load balancing. If a node fails, the client can automatically perform a failover and send requests to a healthy node. When you add or remove nodes, you can interact with the cluster without any interruptions. This simplifies application design and maintenance. Older driver versions may not support SRV addresses or automatic node discovery. Examples: pymongo earlier than 3.9.0. mongo-java-driver earlier than 3.10.0. mongodb-go-driver earlier than 1.1.0. mongodb Node.js driver earlier than 3.3.0. mongo-cxx-driver earlier than 3.8.
ConnectionStringURI address	ApsaraDB for MongoDB provides ConnectionStringURI addresses for Mongos and Shard components. Compared with single-node connection strings, we recommend that you use a ConnectionStringURI address to connect your application to the database in production environments. The client automatically sends requests to multiple nodes of the Mongos component for load balancing. If a Mongos node fails, the client can automatically perform a failover and send requests to a healthy Mongos node. 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 describe the formats, 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)	This parameter specifies 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

The following sections describe the ConnectionStringURI addresses for 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)	This parameter specifies 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 offers high availability by including the endpoints of all nodes in the replica set. Using this address is recommended for production environments.

Important

In production environments, 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)	This parameter specifies 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. This parameter routes write requests to the primary node and read requests 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. This parameter is typically used with readPreference and is 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 to meet the requirements of different scenarios:

Read failover policy	Read target nodes	Parameter combination
If a read operation fails, 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 fail, read requests are routed to the primary node.	`readPreference=secondaryPreferred&readPreferenceTags=role:electable`
	Prefer read-only nodes. Note If read-only nodes fail, read requests are routed to the primary node.	`readPreference=secondaryPreferred&readPreferenceTags=role:readonly`
If a read operation fails, 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 secondary nodes fail, the read operation fails.	`readPreference=secondary&readPreferenceTags=role:electable`
	Read only from read-only nodes. Note If read-only nodes fail, 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.