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

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. For more information, see Get ready to use ApsaraDB RDS for MySQL.
  2. View the region and network type of the RDS instance.
    Log on to the ApsaraDB RDS console and go to the Instances page. 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, you can 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 for communication over an internal network:
    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 labeled 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 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. Log on to the ECS console and go to the Instances page.
    2. In the top navigation bar, select the region where the ECS instance resides.
    3. View the public IP address and private IP address of the ECS instance. The public IP address and private IP address 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 in total 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 the RDS instance runs in standard whitelist mode, you do not need to take note of special considerations when you configure IP address whitelists. If the 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 IP address whitelists of the classic network type.
      • Add the private IP addresses of VPC-hosted ECS instances to IP address whitelists 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 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 connection errors occur, you can resolve the errors by following the instructions provided in 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 can be used with your operating system, and then click Download.
  2. Install MySQL Workbench.
  3. Start MySQL Workbench and choose Database > Connect to Database.
  4. 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 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 Cause and solution
mysql command not found 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.
SSL connection error: SSL is required but the server doesn't support it You are using the latest version of MySQL Workbench. In this version, standard TCP/IP connections require SSL encryption. However, the connected server does not support SSL encryption. In this case, you can download an earlier version of MySQL Workbench to establish regular connections.
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, this error occurs 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 a few cases, this error occurs 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) This error occurs 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) This error occurs because the endpoint that you enter is invalid. Valid endpoints are in the rm-xxxxxx.mysql.rds.aliyuncs.com format.

References