Connect to an ApsaraDB for MongoDB sharded cluster instance - ApsaraDB for MongoDB

ApsaraDB for MongoDB provides a connection string for each mongos component, each shard component, and the ConfigServer component in a sharded cluster instance. ApsaraDB for MongoDB also provides a Uniform Resource Identifier (URI) for each sharded cluster instance. The URI of a sharded cluster instance is used to establish a highly available connection 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 a sharded cluster instance.

View the connection strings and URIs of a sharded cluster instance

Go to the Sharded Cluster Instances page. In the top navigation bar, select the region in which the instance resides. Then, find the instance and click the ID of the instance.
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 to ensure high security and high performance. Classic network: Cloud services in the classic network are not isolated. Unauthorized access to cloud services is blocked only 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. If you want to connect to an ApsaraDB for MongoDB instance over the Internet, you must apply for a public endpoint. For more information, see (Optional) Apply for a public endpoint for an ApsaraDB for MongoDB replica set instance.

Endpoint types

Endpoint type	Description
Mongos endpoint	The endpoint of a mongos component in a sharded cluster instance, including the endpoint of the primary node. Note When you perform routine testing, you need only to connect to a mongos component.
Shard endpoint	The endpoint of a shard component in a sharded cluster instance, including the endpoints of the primary, secondary, and read-only nodes. Note By default, only the connection strings of mongos components in a sharded cluster instance are displayed in the ApsaraDB for MongoDB console. To view the connection string of a shard component or the ConfigServer component in the instance, apply for the corresponding connection string. For more information, see Apply for an endpoint for a shard node or the ConfigServer node in a sharded cluster instance. You can view the connection strings of read-only nodes in shard components only when the read-only nodes exist in the components.
ConfigServer endpoint	The endpoint of the ConfigServer component in a sharded cluster instance, including the endpoints of the primary and secondary nodes. Note By default, only the connection strings of mongos components in a sharded cluster instance are displayed in the ApsaraDB for MongoDB console. To view the connection string of a shard component or the ConfigServer component in the instance, apply for the corresponding connection string. For more information, see Apply for an endpoint for a shard node or the ConfigServer node in a sharded cluster instance. You can apply only for an endpoint for the ConfigServer component in a sharded cluster instance that uses local disks.
Connection string URI	ApsaraDB for MongoDB provides connection string URIs for mongos and shard components in a sharded cluster instance. If your application is deployed in a production environment, we recommend that you use a URI to connect to the sharded cluster instance. This way, your client can automatically distribute requests to mongos components to balance the loads within the instance. If a mongos component fails, your client can automatically redirect requests to other healthy mongos components. Note By default, only the connection string URIs of mongos components in a sharded cluster instance are displayed in the ApsaraDB for MongoDB console. To view the connection string URI of a shard component in the instance, apply for the corresponding connection string. For more information, see Apply for an endpoint for a shard node or the ConfigServer node in a sharded cluster instance.
SRV HA endpoint	SRV HA endpoints can simplify the maintenance and management of sharded cluster instances. You do not need to modify the endpoints when mongos components are added or removed. Your client can interact with the instances without service interruptions, which simplifies the design and maintenance of applications. If your application is deployed in a production environment, we recommend that you use a URI to connect to the sharded cluster instance. This way, your client can automatically distribute requests to mongos components to balance the loads within the instance. If a mongos component fails, your client can automatically redirect requests to other healthy mongos components. Important By default, SRV HA endpoints are not displayed in the ApsaraDB for MongoDB console. To use an SRV HA endpoint, click Apply for Private SRV Address or Apply for Public SRV Address on the Database Connections page. Before you apply for a public SRV endpoint, activate the public endpoints of the mongos components. After you use a public SRV endpoint to connect to a sharded cluster instance, your client automatically redirect requests to mongos components whose public endpoints are activated. SRV HA endpoints are available only for sharded cluster instances that use cloud disks. The private SRV endpoints of a sharded cluster instance deployed in a virtual private cloud (VPC) can be associated with a maximum of 20 mongos components in the instance. If the endpoints are associated with more than 20 mongos components, the excess components cannot offload request due to the limits imposed by the Domain Name System (DNS) resolution protocol in the VPC. Public SRV endpoints are not subject to this limit.

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

Mongos endpoint

Format:

<host>:<port>

The following table describes the parameters that are included in the preceding command.

Parameter	Description
`<host>`	The domain name of the node in the mongos component.
`<port>`	The port number of the node in the mongos component.

Example:

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

Shard endpoint

Format:

<host>:<port>

The following table describes the parameters that are included in the preceding command.

Parameter	Description
`<host>`	The domain name of the node in the shard component.
`<port>`	The port number of the node in the shard component.

Example:

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

ConfigServer endpoint

Format:

<host>:<port>

The following table describes the parameters that are included in the preceding command.

Parameter	Description
`<host>`	The domain name of the node in the ConfigServer component.
`<port>`	The port number of the node in the ConfigServer component.

Example:

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

Connection string URI

The following section describes the connection string URI of a mongos or shard component.

Mongos

Important

If your application is deployed in a production environment, we recommend that you use a URI to connect to the sharded cluster instance. This way, your client can automatically distribute requests to mongos components to balance the loads within the instance. If a mongos component fails, your client can automatically redirect requests to other healthy mongos components.

Format:

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

Parameter	Description
`<username>`	The name of the database account used to log on to the database. Default value: root.
`<password>`	The password of the database account.
`<host>`	The domain name of the node in the mongos component.
`<port>`	The port number of the node in the mongos component.
`<database>`	The name of the database to which you want to connect. Default value: admin.
`authSource=<authenticationDatabase>` (optional)	The database to which the specified database account belongs. `<authenticationDatabase>` indicates the name of the database used for authentication. If you do not specify the authentication database, the database specified by `<database>` is used as the authentication database.

Example:

In the following sample command, the username is test and the database is admin.

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

Shard

The connection string URI of a shard component in a sharded cluster instance is an HA connection string URI that can implement load balancing and ensure high availability. You can use the connection string URI to connect to the instance to perform read/write operations on databases in the instance. The endpoint includes the endpoints of all nodes in the component. If your application is deployed in a production environment, we recommend that you use a URI to connect to the sharded cluster instance.

Important

If you connect to this URI, all requests are processed by the primary node. Read/write operations are not affected by primary/secondary switchover.

Format:

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

The following table describes the parameters that are included in the preceding command.

Parameter	Description
`<username>`	The name of the database account used to log on to the database. Default value: root.
`<password>`	The password of the database account.
`<host>`	The domain name used to connect to the primary, secondary, or read-only node.
`<port>`	The port used to connect to the primary, secondary, or read-only node.
`<database>`	The name of the database to which you want to connect. Default value: admin.
`replicaSet=<replicaSet_value>`	Specifies that read requests are sent to all nodes of the replica set instance. `<replicaSet_value>` indicates the unique ID of the HA endpoint of the instance.
`authSource=<authenticationDatabase>` (optional)	The database to which the specified database account belongs. `<authenticationDatabase>` indicates the name of the database used for authentication. If you do not specify the authentication database, the database specified by `<database>` is used as the authentication database.
`readPreference=[primary\|primaryPreferred\|secondary \| secondaryPreferred]` (optional)	Specifies that write requests are sent to the primary nodes and read requests are randomly sent to secondary and read-only nodes. This parameter ensures read and write splitting and load balancing. Valid values: `readPreference=primary`: Read requests are sent only to the primary nodes. `readPreference=primaryPreferred`: Read requests are preferentially sent to the primary node. `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 This parameter is available only for instances that use cloud disks.
`readPreferenceTags=<readonly_Tags>` (optional)	Specifies that read requests are preferentially sent to the node corresponding to the specified tag. `<readonly_Tags>` indicates the tag keys and tag values of the read-only node and supports the `role:electable` and `role:readonly` types. Valid values: `readPreferenceTags=role:electable`: Data is preferentially read from the secondary node. `readPreferenceTags=role:readonly`: Data is preferentially read from the read-only node. Note This parameter is available only for instances that use cloud disks.

The readPreference and readPreferenceTags parameters are available for instances that use cloud disks. The combinations of different tags can meet the requirements of various scenarios. The following table describes parameter combinations in different scenarios.

Method used to process failed 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	`readPreference=secondaryPreferred&readPreferenceTags=role:electable`
	Preferentially read data from read-only nodes	`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	`readPreference=secondary&readPreferenceTags=role:electable`
	Read data only from read-only nodes	`readPreference=secondary&readPreferenceTags=role:readonly`

Example:

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

SRV HA endpoint

Format:

mongodb+srv://<username>:<password>@<srv-host>/<database>?<options>

The following table describes the parameters that are included in the preceding command.

Parameter	Description
`mongodb+srv://`	The prefix of the connection string, which indicates that DNS SRV records are used to identify services.
`<username>`	The name of the database account used to log on to the database. Default value: root.
`<password>`	The password of the database account.
`<srv-host>`	The hostname.
`<database>`	The name of the database to which you want to connect. Default value: admin.
`<option>`	Other optional parameters. Note The default value of the ssl parameter in an SVR HA endpoint is true. To establish a successful connection to a sharded cluster instance, add the `ssl` parameter that is set to false to the connection string of the instance because the instance does not support SSL. For more information about the optional parameters, see MongoDB documentation.

Example:

In the following sample command, the username is test and the database is admin.

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

Log on to a specific database of a sharded cluster instance

Obtain the following information:
- The connection strings or URIs of the sharded cluster instance. For more information, see View the connection strings and URIs of a sharded cluster instance.
- The database account that is used to connect to the sharded cluster 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 database accounts and grant permissions to the accounts based on your business requirements. For more information, see Manage the permissions of MongoDB database users.
- The password of the database account that is used to connect to the sharded cluster instance. If you do not specify a password for the database account or you forget the password of the account, you can set or change the password of the account. For more information, see (Optional) 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 database For more information, see the following topics:

ApsaraDB for MongoDB:Connect to an ApsaraDB for MongoDB sharded cluster instance

View the connection strings and URIs of a sharded cluster instance

Connection strings and URIs

Network types of endpoints

Endpoint types

Mongos endpoint

Shard endpoint

ConfigServer endpoint

Connection string URI

Mongos

Shard

SRV HA endpoint

Log on to a specific database of a sharded cluster instance

Common connection scenarios

FAQ