This topic describes how to connect to an ApsaraDB RDS for MySQL instance by using a database client or the CLI.

Note If the ApsaraDB RDS console prompts you to refresh the page because your token has expired, you must upgrade the version of your browser or install Google Chrome. Then, you can try again.

Prerequisites

The operations that are described in the following topics are complete:

Step 1: Check whether your application can connect to the RDS instance over an internal network

  1. View the region of the Elastic Compute Service (ECS) instance on which your application is deployed. Also, view the network type of the ECS instance.
  2. View the region and network type of the RDS instance.
    Go to the Instances page in the ApsaraDB RDS console. In the top navigation bar, select the region where the RDS instance resides. Then, find the RDS instance and click the instance ID. On the page that appears, view the region, network type, and virtual private cloud (VPC) ID of the RDS instance. View the region and network type of an RDS instance
  3. Check whether the ECS instance and the RDS instance meet the following conditions:
    1. The ECS instance and the RDS instance reside in the same region.
    2. The ECS instance and the RDS instance reside in the same type of network. If the ECS instance and the RDS instance both reside in VPCs, these instances must reside in the same VPC.
    Note If one of the preceding conditions is not met, the ECS instance cannot communicate with the RDS instance over an internal network.

Step 2: Configure IP address whitelists for the RDS instance

  1. Visit the RDS instance list, select a region above, and click the target instance ID.
  2. In the left-side navigation pane, click Data Security.
  3. View the network isolation mode of the RDS instance.
    Note Existing RDS instances may run in enhanced whitelist mode. All new RDS instances run in standard whitelist mode.
    Figure 1. Standard whitelist mode
    Standard whitelist mode
    Figure 2. Enhanced whitelist mode
    Enhanced whitelist mode
  4. Click Modify to the right of the IP address whitelist named default.
    Note You can also click Create Whitelist to create an IP address whitelist.
    Modify button
  5. Add the IP address of the server on which your application is deployed to the default IP address whitelist.

    The server can communicate with the RDS instance only after you add the IP address of the server to the default IP address whitelist.

    IP address whitelist
    Table 1. IP addresses to be obtained
    Use scenario The IP address to be obtained How to obtain the IP address
    You want to connect to the RDS instance from an ECS instance, and the ECS instance and the RDS instance meet the conditions for communication over an internal network. For more information, see the "Step 1: Check whether your application can connect to the RDS instance over an internal network" section of this topic. The private IP address of the ECS instance
    1. Go to the Instances page in the ECS console.
    2. In the top navigation bar, select the region where the ECS instance resides.
    3. View the public and private IP addresses of the ECS instance. The public and private IP addresses of an ECS instance
    You want to connect to the RDS instance from an ECS instance. However, the ECS instance and the RDS instance do not meet the conditions for communication over an internal network. The public IP address of the ECS instance
    You want to connect to the RDS instance from an on-premises device. The public IP address of the on-premises device On the on-premises device, use a search engine such as Google to search for IP.
    Note The IP address that you obtain by using this method may be inaccurate. For more information about how to obtain the accurate IP address of an on-premises device, see Why am I unable to connect to my ApsaraDB RDS for MySQL or ApsaraDB RDS for MariaDB instance from a local server over the Internet?
    Note
    • If you add multiple IP addresses and CIDR blocks to an IP address whitelist, you must separate the IP addresses and CIDR blocks with commas (,) and leave no spaces before and after each comma.
    • You can add a maximum of 1,000 IP addresses and CIDR blocks for each RDS instance. If you want to add a large number of IP addresses, we recommend that you merge the IP addresses into CIDR blocks, such as 10.10.10.0/24.
    • If an RDS instance runs in standard whitelist mode, you do not need to take note of special considerations when you configure IP address whitelists. If an RDS instance runs in enhanced whitelist mode, you must take note of the following considerations when you configure IP address whitelists:
      • Add public IP addresses or the private IP addresses of classic network-hosted ECS instances to an IP address whitelist of the classic network type.
      • Add the private IP addresses of VPC-hosted ECS instances to an IP address whitelist of the VPC network type.
  6. Click OK.

Step 3: Connect to the RDS instance

To connect to the RDS instance by using the CLI, perform the following steps:

  1. Log on to the server from which you want to connect to the RDS instance. For example, the server can be an ECS instance or an on-premises device.
    Note For more information about how to log on to an ECS instance, see the "Connect to an instance" section in Create and manage an ECS instance by using the ECS console (express version).
  2. Run the following command:
    mysql -hEndpoint -PPort number -uUsername -p      //Take note that the uppercase letter P precedes the lowercase letter p. 
    • Endpoint and port number: Enter the endpoint and port number that are used to connect to the RDS instance.
      Use scenario The endpoint to be obtained How to obtain the endpoint
      You want to connect to the RDS instance from an ECS instance, and the ECS instance and the RDS instance meet the conditions for communication over an internal network. For more information, see the "Step 1: Check whether your application can connect to the RDS instance over an internal network" section of this topic. The internal endpoint of the RDS instance
      1. Visit the RDS instance list, select a region above, and click the target instance ID.
      2. In the Basic Information section of the page that appears, click See Details to the right of the Network Type parameter to view the endpoint and port number that are used to connect to the RDS instance. View connection details
      Note
      • Before you can view the endpoint and port number that are used to connect to the RDS instance, you must configure IP address whitelists for the RDS instance.
      • A public endpoint is displayed only after you click Apply for Public Endpoint to apply for a public endpoint for the RDS instance. Apply for a public endpoint
      You want to connect to the RDS instance from an ECS instance. However, the ECS instance and the RDS instance do not meet the conditions for communication over an internal network. The public endpoint of the RDS instance
      Connect to the RDS instance from an on-premises device
    • Username and password: Obtain the username and password of the account that is used to connect to the RDS instance from the Accounts page.
    Figure 3. Example
    Example
    Figure 4. Connection successful
    Connection successful
    Note If a connection error occurs, see Common connection errors.
To connect to the RDS instance by using a database client, perform the following steps:

You can use a general MySQL client to connect to the RDS instance. In this topic, MySQL Workbench is used as an example. The operations that you need to perform to connect to the RDS instance by using other database clients are similar.

  1. Go to the MySQL Community Downloads page, select the MySQL Workbench software package that is used with your operating system, and then click Download.
  2. Click No thanks, just start my download to download the MySQL Workbench software package. Download MySQL Workbench
  3. Start MySQL Workbench.
  4. Start MySQL Workbench and choose Database > Connect to Database.
  5. Enter the information that is used to connect to the RDS instance. Enter connection information in MySQL Workbench
    • Hostname and Port: Enter the endpoint and port number that are used to connect to the RDS instance.
      Use scenario The endpoint to be obtained How to obtain the endpoint
      You want to connect to the RDS instance from an ECS instance, and the ECS instance and the RDS instance meet the conditions for communication over an internal network. For more information, see the "Step 1: Check whether your application can connect to the RDS instance over an internal network" section of this topic. The internal endpoint of the RDS instance
      1. Visit the RDS instance list, select a region above, and click the target instance ID.
      2. In the Basic Information section of the page that appears, click See Details to the right of the Network Type parameter to view the endpoint and port number that are used to connect to the RDS instance. View connection details
      Note
      • Before you can view the endpoint and port number that are used to connect to the RDS instance, you must configure IP address whitelists for the RDS instance.
      • A public endpoint is displayed only after you click Apply for Public Endpoint to apply for a public endpoint for the RDS instance. Apply for a public endpoint
      You want to connect to the RDS instance from an ECS instance. However, the ECS instance and the RDS instance do not meet the conditions for communication over an internal network. The public endpoint of the RDS instance
      Connect to the RDS instance from an on-premises device
    • Username and Password: Obtain the username and password of the account that is used to connect to the RDS instance from the Accounts page.

Common connection errors

Error message Description
mysql command not found The error message returned because MySQL is not installed. If you are using a Linux operating system such as CentOS, you can run the yum install mysql command to install MySQL.
Can't connect to MySQL server on 'rm-bp1xxxxxxxxxxxxxx.mysql.rds.aliyuncs.com'(10060)

Cannot Connect to Database Server

Your connection attempt failed for user 'xx" to the MySQL server

  • In most cases, the error message is returned because the IP address whitelists that you configure are inappropriate. For more information, see Use a database client or the CLI to connect to an ApsaraDB RDS for MySQL instance.
  • In some cases, the error message is returned because the RDS instance and the ECS instance do not meet the conditions for communication over an internal network but you attempt to connect to the internal endpoint of the RDS instance.
Access denied for user 'xxxxx'@'xxxxx'(using password:YES) The error message returned because the username and password that you enter are incorrect. You can obtain the correct username and password from the Accounts page.
Unknown MySQL server host 'xxxxxxxxx'(11001) The error message returned because the endpoint that you entered is invalid. Valid endpoints are in the rm-xxxxxx.mysql.rds.aliyuncs.com format.

References