The mongo shell is a database management tool that comes with MongoDB. You can install the mongo shell on a client which can be an on-premise server or an Elastic Compute Service (ECS) instance.

Prerequisites

A replica set instance is created. For more information, see Create a replica set instance.

Background information

The default database admin allows a replica set instance to store all database accounts and roles. We recommend that you use a database other than admin to implement business requirements and do not perform operations on admin.

Preparations

  • The mongo shell that uses the same engine version as the replica set instance is downloaded and installed on your on-premises server or ECS instance. For more information, visit Index of mongodb-org.
    If your application is deployed on an Elastic Compute Service (ECS) instance, make sure that your ApsaraDB for MongoDB instance and ECS instance meet the following requirements to ensure network connectivity: For more information about how to view ECS instance information, see View instance information.
    • Your ApsaraDB for MongoDB instance and ECS instance are deployed in the same region, and preferably belong to the same zone. This reduces network latency.
    • Your ApsaraDB for MongoDB instance and ECS instance use the same network type.
      Note
      • VPC is recommended because VPC provides higher security.
      • If the network type is VPC, you must ensure that they use the same VPC ID.
      • If you want to use VPC, but the network type of the ECS instance is classic network, you can change the network type of the ECS instance to VPC. For more information, see Migrate ECS instances from the classic network to a VPC.
  • The IP address of the on-premises server or ECS instance is added to a whitelist of the instance. For more information, see Configure a whitelist for an ApsaraDB for MongoDB instance.
  • If you want to connect to the 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 instance.
  • If you want to connect to a read-only node in the instance, make sure that the instance contains at least one read-only node. If the instance has no read-only nodes, add one or more read-only nodes to the instance. For more information, see Change the configurations of a replica set instance.

Procedure

  1. Log on to the ApsaraDB for MongoDB console.
  2. In the left-side navigation pane, click Replica Set Instances.
  3. In the upper-left corner of the page, select the resource group and region to which the instance belongs.
  4. Click the ID of an instance, or click More icon in the Actions column corresponding to the instance and select Manage.
  5. In the left-side navigation pane of the instance details page, click Database Connections.
  6. Obtain the endpoints required to connect to the instance.
    Item Description
    Connection address type
    • Private endpoint:
      • VPC: Virtual Private Cloud (VPC) endpoints are used for communication over VPCs. A 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 performance.
      • Classic network: Cloud services in the classic network are not isolated. Unauthorized access to a cloud service is blocked by using security groups or whitelists.
    • Public endpoint: Public endpoints are used for communication over the Internet. If you connect to an ApsaraDB for MongoDB instance over the Internet, the instance may be exposed to security risks. By default, no public endpoints are provided for ApsaraDB for MongoDB instances. If you want to connect to the 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 instance.
    Primary The primary node. You can connect to the primary node to perform read and write operations on a database. When the primary node fails, a primary/secondary switchover occurs. You must connect to the new primary node to ensure that read and write operations are not affected.
    Format:
    <host>:<port>
    Parameters:
    • <host>: the domain name information used to connect to the primary node.
    • <port>: the port used to connect to the primary node.
    Example:
    dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717
    Secondary The secondary node. If you connect to a secondary node, only read operations can be performed on a database.
    Format:
    <host>:<port>
    Parameters:
    • <host>: the domain name information used to connect to the secondary node.
    • <port>: the port used to connect to the secondary node.
    Example:
    dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717
    ReadOnly The read-only node. If you connect to a read-only node, only read operations can be performed on a database.
    Note The connection string of a read-only node is displayed only if the replica set instance contains the read-only node.
    Format:
    <host>:<port>
    Parameters:
    • <host>: the domain name information used to connect to the read-only node.
    • <port>: the port number used to connect to the read-only node.
    Example:
    dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717
    ReadOnly ConnectionStringURI The HA read-only connection string URI. This URI helps implement load balancing and ensure HA. If you use this URI, read and write operations can be performed on a database. If your instance has multiple read-only nodes, we recommend that you use this URI to connect to the instance.
    Note
    • This URI can be viewed only if the instance contains at least one read-only node.
    • If you use this URI, read requests are preferentially sent to read-only nodes.
    • If a read-only node fails, read requests are automatically sent to the next read-only node. This ensures that read operations are not affected. If all read-only nodes fail, read requests are sent to a secondary node.
    Format:
    mongodb://<username>:<password>@<host1>:<port1>,<host2>:<port2>,...,<hostN>:<portN>/<database>?readPreference=secondary&readPreferenceTags=<readonly_Tags>&replicaSet=<replicaSet_value>
    Parameters:
    • <username>: the name of the database account. Default value: root.
    • <password>: the password of the database account.
    • <host>: the domain name information used to connect to the read-only nodes.
    • <port>: the port used to connect to the read-only nodes.
    • <database>: the name of the database to which the database account belongs. Default value: admin.

      If you need to use another database, add &authSource=admin to the end of the endpoint.

    • readPreference=secondary: specifies to send write requests to the primary node and read requests to a random secondary node and read-only node. This ensures read/write splitting and load balancing.
    • readPreferenceTags=<readonly_Tags>: specifies to preferentially send read requests to read-only nodes that have the tags specified by using<readonly_Tags>. <readonly_Tags> indicates a list of tags in the form of key-value pairs and cannot be changed.
      Note For more information about readPreferenceTags, see Connection String URI Format.
    • replicaSet=<replicaSet_value>: specifies to send read requests to all nodes in a replica set instance. <replicaSet_value> indicates the unique ID of this URI.
    Example:
    mongodb://root:****@dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717/admin?readPreference=secondary&readPreferenceTags=role:readonly&replicaSet=mgset-6108****
    ConnectionStringURI The HA connection string URI. This URI helps implement load balancing and ensure HA. If you use this URI, read and write operations can be performed on a database. We recommend that use this URI to connect your application in the production environment to the instance.
    Note If you use this URI, the primary node is always connected and the read and write operations of your application are not affected by primary/secondary switchover.
    Format:
    mongodb://<username>:<password>@<host1>:<port1>,<host2>:<port2>,...,<hostN>:<portN>/<database>?replicaSet=<replicaSet_value>
    Parameters:
    • <username>: the name of the database account. Default value: root.
    • <password>: the password of the database account.
    • <host>: the domain name information used to connect to the primary, secondary, and read-only nodes.
    • <port>: the port used to connect to the primary, secondary, and read-only nodes.
    • <database>: the name of the database to which the database account belongs. Default value: admin.

      If you need to use another database, add &authSource=admin to the end of the endpoint.

    • replicaSet=<replicaSet_value>: specifies to send read requests to all nodes in a replica set instance. <replicaSet_value> indicates the unique ID of this URI.
    Example:
    mongodb://root:****@dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717,dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717,dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717/admin?replicaSet=mgset-61081718-bp1366caac83d****.mongodb.rds.aliyuncs.com:3717,dds-bp1366caac83d****.mongodb.rds.aliyuncs.com:3717,dds-bp1366caac83d****.mongodb.rds.aliyuncs.com:3717/admin?replicaSet=mgset-4581****
  7. Connect your on-premises server or ECS instance to the instance.
    • Use an HA connection string URI to connect to the instance

      If you use this URI, all instance nodes can be connected. If a node fails, the instance can still be connected.

      Syntax:
      mongo "<Connection string URI>"    
      Parameters: <Connection string URI> specifies the read-only connection string URI or connection string URI.
      Note
      • You must replace **** in the URI with the password of the root account. If you forget the password of the root account, you can reset the password. For more information, see (Optional) Reset a password.
      • The mongo shell cannot identify the readPreference and readPreferenceTags parameters in a read-only connection string URI. If you use this URI, the primary node is automatically connected.
      Run the following command to use the connection string URI:
      mongo "mongodb://root:****@dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717,dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717,dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717/admin?replicaSet=mgset-6108****"    
    • Use the connection string of a node to connect to the instance

      If you use this method, only a single node is connected. If the node fails, the instance cannot be connected.

      1. Run the following command.
        Syntax:
        mongo --host <host>:<port> -u <username> -p --authenticationDatabase <database>
        Parameters:
        • <host>: the domain name information 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.
        • <username>: the name of the database account. Default value: root.
          Note We recommend that you do not use the root account for database logon. You can create a database account and grant the permissions to the account. For more information, see Manage user permissions on MongoDB databases.
        • <database>: the name of the database to which the database account belongs. Default value: admin.
        Example:
        mongo --host dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717 -u root -p --authenticationDatabase admin
      2. Enter the password used to log on to the database.

        When Enter password: is displayed, enter the password of the database account and press the Enter key. If you forget the password of the root account, you can reset the password. For more information, see (Optional) Reset a password.

Common connection scenarios

FAQ