Connect to a sharded cluster instance - ApsaraDB for MongoDB

ApsaraDB for MongoDB provides a connection string for each mongos node, each shard, and the ConfigServer component in a sharded cluster instance. ApsaraDB for MongoDB also provides connection string Uniform Resource Identifiers (URIs) for all mongos nodes or shards in the instance and an SRV high-availability (HA)connection string URI. These URIs of a sharded cluster instance are used to establish HA connections between your application and the instance. This topic describes how to view the connection strings and URIs of a sharded cluster instance and how to log on to a specific database of the instance.

View the connection strings and URIs of the instance

Go to the Sharded Cluster Instances page. In the top navigation bar, select the region in which the desired instance resides. Then, find the instance that you want to manage and click the instance ID.
In the left-side navigation pane of the instance details page, click Database Connections. In the page that appears, view the connection information of a node in the instance.

Connection strings and URIs

Network types of endpoints

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. To connect to an ApsaraDB for MongoDB instance over the Internet, apply for a public endpoint.

Endpoint types

Endpoint type	Description
SRV HA connectionstring URI (recommended)	In ApsaraDB for MongoDB, SRV is a type of Domain Name System (DNS) records that provide a mechanism simplifying connection strings and automatically identify cluster members. When adding or removing mongos nodes for your sharded cluster instance, use an SRV HA connection string URI to seamlessly interact your application with the instance, simplifying the design and maintenance of the application. Important By default, SRV HA connection string URIs are not displayed in the ApsaraDB for MongoDB console. To use an SRV HA connection string URI, click Apply for Private SRV Address or Apply for Public SRV Address on the Database Connections page. Before applying for a public SRV HA connection string URI, activate the public endpoint of a mongos node. After you use a public SRV HA connection string URI to connect to an instance, your client automatically redirect requests to a mongos node whose public endpoint is activated. SRV HA connection string URIs are available only for instances that use cloud disks. The private SRV HA connection string URI of a sharded cluster instance deployed in a VPC can be associated with a maximum of 20 mongos nodes in the instance. If the URI is associated with more than 20 mongos nodes, the excess nodes cannot offload request due to the limits imposed by the DNS resolution protocol in the VPC. The public SRV HA connection string URI of the instance is not subject to this limit. We recommend that you use an SRV HA connection string URI to connect your application in a production environment to your replica set instance. Your client automatically sends requests to multiple nodes for load balancing. If a node fails, the client automatically redirects requests to other healthy nodes. When adding or removing nodes, seamlessly interact your application with the instance, simplifying the design and maintenance of the application. Drivers of earlier versions do not support SRV HA connection string URIs or automatically identify nodes, such as: pymongo of versions earlier than 3.9.0 MongoDB Java Driver of versions earlier than 3.10.0 MongoDB Go Driver of versions earlier than 1.1.0 MongoDB Node.js Driver of versions earlier than 3.3.0 MongoDB Cxx Driver of versions earlier than 3.8
Connection string URI	ApsaraDB for MongoDB provides a connection string URI for all mongos nodes or shards in the instance. We recommend that you use a connection string URI instead of a standalone connection string to connect your application in a production environment to the instance. Your client automatically sends requests to multiple mongos nodes for load balancing. If a mongos node fails, the client sutomatically redirects requests to other healthy nodes. Note By default, only the connection string URI of all mongos nodes in the instance are displayed in the ApsaraDB for MongoDB console. To view the connection string URI of all shards in the instance, apply for an endpoint for a shard node. If the readPreference and readPreferenceTags parameters are not specified, read requests are sent to primary nodes. When adding or removing nodes for the instance, modify the connection string URI and add or remove the corresponding node connection information.
Mongos endpoint	The endpoint of a mongos node in the instance. The endpoint allows you to connect to a mongos node. Note When performing routine testing, you need only to connect to a mongos node.
Shard endpoint	The endpoint of a shard in the instance. The endpoint allows you to connect to the primary node, a secondary node, or a read-only node in the shard. Note By default, only the connection strings of mongos nodes in the instance are displayed in the ApsaraDB for MongoDB console. To view the connection string of a shard or the ConfigServer component in the instance apply for an endpoint for the corresponding component role. You can view the connection strings of read-only nodes in a shard only when the read-only nodes exist in the shard.
ConfigServer endpoint	The endpoint of the ConfigServer component in the instance. The endpoint allows you to connect to the primary node or a secondary node in the component. Note By default, only the connection strings of mongos nodes in the instance are displayed in the ApsaraDB for MongoDB console. To view the connection string of a shard or the ConfigServer component in the instance, apply for an endpoint for the corresponding component role. You can apply only for an endpoint for the ConfigServer component in a sharded cluster instance that uses local disks.

The following section describes the format, parameters, and examples of each endpoint:

SRV HA connection string URI

Format:

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

Parameters:

Parameter	Description
`mongodb+srv://`	The prefix of the connection string, which indicates that DNS SRV records are used to identify services.
`<username>`	The database account. Set the value to root.
`<password>`	The password of the database account.
`<srv-host>`	The hostname.
`<database>`	The name of the database to access. Set the value to admin.
`authSource=<authenticationDatabase>` (Optional)	The database to which the specified database account belongs. `<authenticationDatabase>` indicates the name of the authentication database. Note The TXT records of SRV HA connection string URIs for ApsaraDB for MongoDB specify `authSource=admin`, which overrides the authentication property of `<database>`. Therefore, when modifying the authentication database, 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 option for SRV connections is true. If you do not need to use SSL-encrypted connections, add the `ssl=false` parameter to a connection string. For more information about optional parameters, see Connection Strings.

Example:

In this 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

Connection string URI

The following sections describe the connection string URIs of mongos nodes and shards respectively.

Mongos nodes

Important

We recommend that you use a connection string URI to connection your application in a production environment to your sharded cluster instance. Your client automatically sends requests to multiple mongos nodes for load balancing. If a mongos node fails, the client automatically redirects requests too other healthy nodes.

Format:

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

Parameters:

Parameter	Description
`<username>`	The database account. Set the value to root.
`<password>`	The password of the database account.
`<host>`	The Domain Name Information of the mongos node.
`<port>`	The Port of the mongos node.
`<database>`	The name of the database to access. Set the value to admin.
`authSource=<authenticationDatabase>` (Optional)	The database to which the database account belongs. `<authenticationDatabase>` indicates the name of the authentication database. If this parameter is not specified, the database specified by `<database>` is used as the authentication one.

Example:

In this 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

Shards

The connection string URI of shards is an HA endpoint that implements load balancing. You can access this URI to read/write operations on your databases. This URI allows you to access all shards in your sharded cluster instance. We recommend that you use a connection string URI to connect your application in a production environment to your instance.

Important

This ensures that primary nodes are constantly connected without any interruption on read/wite operations from the application due to primary/secondary switchovers.

Format:

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

Parameters:

Parameter	Description
`<username>`	The database account. Set the value to root.
`<password>`	The password of the database account.
`<host>`	The Domain Name Information of the primary, secondary, or read-only node.
`<port>`	The Port of the primary, secondary, or read-only node.
`<database>`	The name of the database to access. Set the value to admin.
`authSource=<authenticationDatabase>` (Optional)	The database to which the database account belongs. `<authenticationDatabase>` indicates the name of the authentication database. If this parameter is not specified, the database specified by `<database>` is used as the authentication one.
`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 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 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`: Read requests are preferentially sent to a secondary node. Note This option is available only for instances that use cloud disks. `readPreferenceTags=role:readonly`: Read requests are preferentially sent to a read-only node.

The readPreference and readPreferenceTags parameters along with different tag combinations can meet various scenario requirements. The following table describes available parameter combinations.

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:

In this example, the database account is test, and it belongs to the admin database.

mongodb://test:****@dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717,dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717/admin?replicaSet=mgset-6108****

Mongos endpoint

Format:

<host>:<port>

Parameters:

Parameter	Description
`<host>`	The Domain Name Information of the mongos node.
`<port>`	The Port of the mongos node.

Example:

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

Shard endpoint

Format:

<host>:<port>

Parameters:

Parameter	Description
`<host>`	The Domain Name Information of the shard node.
`<port>`	The Port of the shard node.

Example:

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

ConfigServer endpoint

Format:

<host>:<port>

Parameters:

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

Example:

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

Log on to a specific database of the instance

Obtain the following information:
- The connection strings and URIs of the instance.
- The database account that is used to connect to the instance. The initial account is the root account.
  Important
  We recommend that you do not connect to a database in the production environment by using the root account. You can create a database account and grant it permissions based on your business requirements.
- The password of the database account that is used to connect to the instance. If you do not specify a password for the database account or have forgotten the password, specify or reset a password.
- The name of the database to which you want to connect. If the username is root, enter admin.
Log on to a specific database. For more information, see the following topics:

ApsaraDB for MongoDB:Connect to a sharded cluster instance

View the connection strings and URIs of the instance

Connection strings and URIs

Network types of endpoints

Endpoint types

SRV HA connection string URI

Connection string URI

Mongos nodes

Shards

Mongos endpoint

Shard endpoint

ConfigServer endpoint

Log on to a specific database of the instance

Common connection scenarios

FAQ