How do I troubleshoot failures in connecting to an ApsaraDB RDS for MySQL instance? - ApsaraDB RDS

Quick reference

Match your situation to find the fix:

Situation	Likely cause	Go to
ECS is in a VPC; RDS is in the classic network	Network type mismatch	Different network types
ECS is in the classic network; RDS is in a VPC	Network type mismatch	Different network types
Both ECS and RDS are in VPCs, but in different ones	VPC isolation	Different VPCs
ECS and RDS are in different regions or Alibaba Cloud accounts	Cross-region or cross-account routing	Different regions
Network type and VPC match, but connection still fails	Whitelist misconfiguration	Incorrect IP address whitelist settings
Connection times out or the hostname cannot be resolved	DNS issue	Domain name resolution failures
RDS instance is stuck mid-switch	Instance state issue	RDS instance in the Creating Network Connection state

Different network types

ApsaraDB RDS for MySQL instances and ECS instances must be in the same network type to communicate over an internal network.

ECS is in a VPC; RDS is in the classic network

Method 1 (recommended): Migrate the RDS instance to the virtual private cloud (VPC) where the ECS instance resides. See Change the network type of an ApsaraDB RDS instance.

Note
If both instances are in VPCs, they must be in the same VPC to communicate over an internal network.
Method 2: Purchase a new ECS instance in the classic network. ECS instances cannot be migrated from a VPC back to the classic network. A VPC is more secure than the classic network.
Method 3: Connect using the public endpoint of the RDS instance. This method does not guarantee optimal performance, security, or stability.

ECS is in the classic network; RDS is in a VPC

Method 1 (recommended): Migrate the ECS instance to the VPC where the RDS instance resides.

Note
If both instances are in VPCs, they must be in the same VPC to communicate over an internal network.
Method 1: Migrate the ECS instance to the VPC to which the RDS instance belongs. This is the recommended method.

Note
If the ECS instance and the RDS instance both reside in VPCs, they must reside in the same VPC to communicate with each other over an internal network.
Method 2: Migrate the RDS instance to the classic network. A VPC is more secure than the classic network.
Method 3: Use ClassicLink Overview of ClassicLink to establish an internal network connection between the ECS instance and the RDS instance.
Method 4: Connect using the public endpoint of the RDS instance. This method does not guarantee optimal performance, security, or stability.

Different VPCs

VPCs are logically isolated from each other. Even if both the ECS instance and the RDS instance are in VPCs, they must be in the same VPC to communicate over an internal network.

Method 1 (recommended): Move both instances into the same VPC. Change the VPC of the RDS instance or the VPC of the ECS instance.
Method 2: Create a Cloud Enterprise Network (CEN) instance to establish a private connection between the two VPCs. See Use CEN to enable intra-region network communication.
Method 3: Connect over the Internet using the public endpoint of the RDS instance. This method does not guarantee optimal performance, security, or stability.

Different regions

When the ECS instance and the RDS instance are in different regions or belong to different Alibaba Cloud accounts, internal network routing is unavailable by default. The following options are available.

Internet-based connection

Apply for and use the public endpoint of the RDS instance. Inbound and outbound Internet traffic generated on the RDS instance is not charged.

Internal network-based connection

Use VPC peering connections or a CEN instance to bridge the VPCs across regions or accounts:

Option	Cost	Configuration complexity	Best for
VPC peering connection	Low	More complex	Simple scenarios with a small number of VPCs
CEN instance	High	Simpler	Complex scenarios with many VPCs

Connect to an RDS instance from an on-premises data center

To connect to an RDS instance from an on-premises data center (IDC) over an internal network, first connect your on-premises network to a VPC on Alibaba Cloud by using one of the following methods:

VPN gateway: Create a VPN gateway and establish an IPsec-VPN site-to-site connection to connect your on-premises network to the VPC.
Smart Access Gateway (SAG): Deploy an SAG device in your on-premises data center to connect your on-premises network to the VPC.
Express Connect (dedicated line): Use a dedicated physical connection to connect your on-premises data center to the VPC on Alibaba Cloud.

After the on-premises network is connected to the VPC, use the internal endpoint of the RDS instance to establish the connection. If you need to connect across regions, use Cloud Enterprise Network (CEN) to enable cross-region VPC interworking. A CEN transit router supports attaching a VPN gateway IPsec connection and an SAG network instance.

Incorrect IP address whitelist settings

The most common whitelist issues are listed below.

Default whitelist allows no connections

The default whitelist contains only 127.0.0.1, which blocks all external access. Add the IP addresses that need access to the RDS instance. See Configure an IP address whitelist for an ApsaraDB RDS for MySQL instance.

Whitelist contains 0.0.0.0/0

Important

Adding 0.0.0.0/0 to the whitelist allows access from all IP addresses. Proceed with caution.

Enhanced whitelist mode is enabled

If the enhanced whitelist mode is enabled, the whitelist type must match the connection path:

Connection path	IP to add	Whitelist type
RDS in a VPC, connected via internal endpoint	Private IP address of the ECS instance	VPC type
RDS in the classic network, connected via internal endpoint	Private IP address of the ECS instance	Classic network type
RDS in the classic network, connected via the Internet	Public IP address of the ECS instance	Classic network type

Whitelisted public IP address is not working

Two common causes:

The public IP address is dynamic and has changed since you added it.
The tool or website used to look up the public IP address returned an inaccurate result.

For help getting the correct public IP address, see:

Domain name resolution failures

If the Domain Name System (DNS) servers are faulty or the network interface controller (NIC) configuration has changed, the RDS hostname may fail to resolve or resolve to the wrong IP address.

Test connectivity

Run the following commands from the ECS instance, replacing <Domain name> with the RDS internal or public endpoint and <Port number> with the database port:

ping <Domain name>
telnet <Domain name> <Port number>

Note

macOS does not include Telnet by default. To test port connectivity on macOS, run nc -vz <Domain name> <Port number>.

If connectivity fails, the issue is likely with DNS resolution or network configuration. Proceed to fix the NIC DNS settings below.

Fix NIC DNS settings

Open the NIC configuration file in edit mode:

Note
Run ifconfig to find the NIC configuration file name. The default is ifcfg-eth0.
```
vi /etc/sysconfig/network-scripts/<NIC configuration file name>
```
Add the following DNS settings at the end of the file. If DNS1 and DNS2 already exist, update their values:
```
DNS1=100.100.XX.XX
DNS2=100.100.XX.XX
```
Restart the network service:
```
sudo systemctl restart network
```
Verify the change took effect:
```
cat /etc/resolv.conf
```

The endpoint cannot be resolved after an instance restart, restoration, or DNS change

After an RDS instance is restarted or restored, or after its DNS settings change, a client might report that the public endpoint cannot be resolved or show other abnormal DNS resolution behavior. Ping or Telnet tests against the IP address might still succeed.

DNS propagation can take several minutes to tens of minutes. During this period, a stale local DNS cache or global DNS propagation delay can prevent the client from resolving the latest address.

Wait for DNS propagation to complete, and then retry the connection by using the public endpoint.
To isolate the DNS issue, temporarily use the IP address in a client such as Navicat. If the IP address works but the public endpoint does not, continue troubleshooting DNS resolution and caching.
Refresh the DNS configuration or cache on the client or server. Follow the steps in Fix NIC DNS settings, resolve the public endpoint again, and retest the connection.

RDS instance in the Creating Network Connection state

Go to the Tasks page in the ApsaraDB RDS console, find the task in the Creating Network Connection state, and click Retry or Modify switching time. See Use Task Center.

FAQ

Why do Ping and Telnet tests succeed while the application cannot connect?

A successful Ping test shows that the host responds to ICMP requests, and a successful Telnet test shows that the database port is reachable. If the application still cannot connect, complete the following checks:

Rule out abnormal behavior or configuration issues in graphical tools such as Navicat. Use the MySQL command line interface for a low-level connection test: mysql -h <endpoint> -P <port> -u <username> -p.
If the command succeeds, the network connection and the permissions of the tested account are working. Check the database driver version, connection string format, endpoint, port, database name, username, and password in the Java application or other application code.
Do not use system accounts whose names start with dms for business connection tests. Create a privileged account or a standard business account in the console, test the connection with it, and verify that the account has access to the destination database.

If the command also fails, continue with the network, whitelist, port, and account troubleshooting in this document.