# rds-instance

Part of **RDS**

<!-- intent-backlink:auto -->

> 💡 **Path Selection**: This skill is one implementation path for [Manage database instance lifecycle and configuration](../../intent/rds-manage-instance/SKILL.md). If you're unsure which path to take, check the routing skill first.

# ApsaraDB RDS Instance Management Troubleshooting Guide

## Problem Index

| Problem | Symptom | Severity | Solution Summary |
|------|------|---------|------------|
| Locked Instance Due to Storage Exhaustion | Error 1290 (HY000): "The MySQL server is running with the LOCK_WRITE_GROWTH option so it cannot execute this statement." | High | Expand storage capacity or enable automatic storage expansion. |
| Overdue Payment Suspension | Instance status shows "Locked" or "Released"; access denied with 403 error. | High | Top up account balance and clear overdue payments via the billing console. |
| Connection Failure from Local Server | "Connection refused" or "Access denied" when connecting over Internet. | Medium | Add client's public IP to the RDS IP address whitelist. |
| Missing RDS Instance in Console | Instance not visible in instance list despite being created. | Medium | Verify correct region selection and Alibaba Cloud account login. |
| Network Type Change Not Supported | API returns error when changing from VPC to classic network. | Low | Use VPC network type; classic network migration is discontinued. |

## Problem Details

### Problem 1: Locked Instance Due to Storage Exhaustion

**Symptoms**
- Error message: `1290 (HY000): The MySQL server is running with the LOCK_WRITE_GROWTH option so it cannot execute this statement.`
- Behavior: Write operations fail; instance status shows "Locking"
- Context: Occurs when disk space is fully consumed by data, logs, or temporary files

**Root Cause**
- The RDS instance has exhausted its allocated storage capacity
- Common triggers include unmanaged log growth, large data imports, or insufficient initial storage allocation
- The system locks write operations to prevent data corruption

**Solution**
1. Log on to the ApsaraDB RDS console at https://rdsnext.console.aliyun.com
2. Navigate to your instance and click **Monitor & Alarm** in the left navigation pane
3. View storage usage breakdown to identify space consumers (data files, logs, etc.)
4. Click **Upgrade RDS** in the Configuration Info section
5. Increase storage capacity to a value larger than current usage
6. Submit the configuration change request

```bash
# Optional: Check current storage usage via CLI
aliyun rds DescribeDBInstancePerformance --DBInstanceId <your-instance-id> --Key "DiskUsage"
```

**Verification**
- After upgrade completes, verify instance status returns to "Running"
- Confirm write operations succeed by executing an INSERT statement
- Monitor storage metrics to ensure usage is below new capacity

### Problem 2: Overdue Payment Suspension

**Symptoms**
- Error message: `403: Access denied due to insufficient permissions or account restrictions`
- Behavior: Instance becomes inaccessible; status shows "Locked" or "Released"
- Context: Occurs with pay-as-you-go instances after payment arrears

**Root Cause**
- Account has unpaid bills exceeding credit limit
- System suspends service after protection period expires
- Instance may be moved to recycle bin if not recovered promptly

**Solution**
1. Go to the Account Overview page at https://usercenter2-intl.console.alibabacloud.com
2. Click **Pay Now** to proceed to payment methods page
3. Add sufficient funds to cover overdue amount using credit card or PayPal
4. Wait for automatic service restoration (typically within minutes of payment)
5. For released instances, check Recycle Bin to restore within retention period

```bash
# Check instance status after payment
aliyun rds DescribeDBInstances --DBInstanceId <your-instance-id>
```

**Verification**
- Confirm instance status changes from "Locked" to "Running"
- Test database connectivity using standard connection command:
```bash
mysql -h<Endpoint> -u<Username> -p<Password> -P3306
```
- Verify all databases and tables are accessible

### Problem 3: Connection Failure from Local Server

**Symptoms**
- Error message: `Connection refused`
- Behavior: Cannot establish connection from local machine over Internet
- Context: Common when connecting from dynamic IP addresses without proper whitelist configuration

**Root Cause**
- Client's public IP address not included in RDS IP address whitelist
- Dynamic IP changes may invalidate existing whitelist entries
- Security groups or firewalls may block outbound connections

**Solution**
1. Determine your current public IP address:
```bash
curl ipinfo.io/ip
```
2. Log on to RDS console at https://rds.console.aliyun.com
3. Navigate to your instance and click **Security Settings**
4. In **IP Address Whitelist** tab, click **Add**
5. Enter your public IP address or CIDR block (e.g., `203.0.113.0/24`)
6. Save the whitelist rule

**Verification**
- Attempt connection using mysql client:
```bash
mysql -h<Endpoint> -u<Username> -p<Password> -P3306
```
- Confirm successful connection and ability to run queries
- For dynamic IPs, consider using `0.0.0.0/0` temporarily (not recommended for production)

### Problem 4: Missing RDS Instance in Console

**Symptoms**
- Error message: `InstanceNotFound`
- Behavior: Instance not visible in console instance list
- Context: Common after creation or when switching between accounts/regions

**Root Cause**
- Incorrect region selected in console
- Logged into wrong Alibaba Cloud account
- Instance released due to overdue payment or failed purchase

**Solution**
1. Go to RDS Overview page to view regions with instances
2. Switch to correct region using region selector at top of Instance List page
3. If still not found, log out and verify you're using correct account credentials
4. Check Fund Flow page for refund entries indicating failed purchase
5. For released instances, check Recycle Bin for recovery options

```bash
# List instances in specific region via CLI
aliyun rds DescribeDBInstances --RegionId cn-hangzhou
```

**Verification**
- Instance appears in console instance list
- Instance details page loads successfully
- Basic operations (monitoring, connection) function normally

### Problem 5: Network Type Change Not Supported

**Symptoms**
- Error message: `NetworkTypeChangeNotSupported`
- Behavior: API operation fails when changing from VPC to classic network
- Context: Attempting network type change after March 22, 2022

**Root Cause**
- Alibaba Cloud discontinued VPC-to-classic network type changes as of March 22, 2022
- Only classic-to-VPC changes remain supported
- Feature removal affects all RDS database engines

**Solution**
1. Keep instance in VPC network type (recommended for security and performance)
2. If classic network is absolutely required:
   - Create new instance with classic network type
   - Migrate data using DTS or backup/restore
   - Update application connection strings
3. Verify network type compatibility before creating new instances

**Verification**
- Confirm instance network type remains VPC
- Test application connectivity through VPC
- Review security group and whitelist settings for VPC environment

## FAQ

**Q: How do I check if my RDS instance is healthy?**
A: Navigate to the RDS console, select your instance, and view the **Monitoring & Alerts** section. Check key metrics like CPU utilization, memory usage, disk space, and active connections. Green status indicators and values within normal ranges (CPU < 80%, disk < 90%) indicate good health.

**Q: What permissions are needed to manage RDS instances?**
A: RAM users need appropriate policies attached. Minimum required permissions include `rds:DescribeDBInstances`, `rds:ModifyDBInstanceSpec`, and `rds:ModifySecurityIps`. For full management, attach the `AliyunRDSFullAccess` system policy or create custom policies with specific RDS actions.

**Q: How can I enable debug logging for connection issues?**
A: Connection diagnostics are available through the **Diagnosis** feature in the RDS console. Navigate to your instance, click **Diagnostics** in the left panel, and run a connectivity check. This provides detailed analysis of network paths, security settings, and potential blocking rules.

**Q: What are common causes of timeout errors when connecting to RDS?**
A: Common causes include: (1) IP address not in whitelist, (2) Security group blocking port 3306/5432, (3) Network type mismatch between client and instance (VPC vs classic), (4) Instance in locked state due to storage or payment issues, and (5) DNS resolution failures for endpoint addresses.

**Q: How do I roll back a failed configuration change?**
A: Most configuration changes (like storage upgrades) cannot be directly rolled back. However, you can: (1) For storage increases, no rollback is needed as it's safe, (2) For instance type changes, modify again to previous specification, (3) For parameter changes, reset to default values in the Parameters section, (4) Always test changes in non-production environments first.