# rds-proxy

Part of **RDS**

# ApsaraDB RDS Database Proxy Troubleshooting Guide

## Problem Index

| Problem | Symptom | Severity | Solution Summary |
|--------|--------|---------|------------------|
| Proxy endpoint deployment zone mismatch | Error: `All connection endpoints' vSwitchId must be in the destination availability zone` | High | Delete proxy endpoint in source availability zone before changing deployment topology |
| Uncertain connection routing (direct vs. proxy) | Session ID < 16777215 when proxy is expected | Medium | Use session ID check to confirm connection method; verify proxy endpoint usage |
| Read/write splitting not working as expected | Read queries routed to primary instance despite read-only intent | Medium | Verify consistency level settings and use appropriate hints or transaction boundaries |

## Problem Details

### Problem 1: Proxy Endpoint Deployment Zone Mismatch During Topology Change

**Symptoms**
- Error message: `All connection endpoints' vSwitchId must be in the destination availability zone`
- Behavior: Fails to change from dual-zone to single-zone deployment
- Context: Occurs when modifying instance deployment topology while a proxy endpoint exists in the source availability zone

**Root Cause**
This error occurs because the system requires all proxy endpoints to reside within the target availability zone during a topology change. If a proxy endpoint remains in the original (source) zone, the operation is blocked to prevent network misconfiguration.

**Solution**
1. Navigate to the RDS console at https://rds.console.aliyun.com
2. Go to **RDS > Instances > [Your Instance] > Database Proxy**
3. In the **Connection information** section, identify and delete any proxy endpoint associated with the source availability zone
4. After deletion, retry the deployment topology change operation

**Verification**
- The topology change operation completes successfully without error
- New proxy endpoints (if recreated) appear only in the destination availability zone
- Connection tests using the proxy endpoint succeed

### Problem 2: Unable to Confirm Whether Connection Uses Database Proxy

**Symptoms**
- Uncertainty whether application traffic is going through the proxy or directly to the database instance
- Behavior: Performance or routing behavior inconsistent with proxy expectations
- Context: After enabling Database Proxy, user needs to validate actual connection path

**Root Cause**
ApsaraDB RDS uses session IDs to distinguish between direct instance connections and proxy-mediated connections. Without checking this identifier, users cannot reliably determine the connection method.

**Solution**
1. Connect to the RDS instance using your client
2. Run the following SQL command to retrieve the current session ID:
   ```sql
   SELECT CONNECTION_ID();
   ```
3. Interpret the result:
   - If the returned value is **less than 16777215**, the connection is **direct to the instance**
   - If the returned value is **16777215 or greater**, the connection is **via the Database Proxy**

**Verification**
- Reconnect using the **proxy endpoint** (not the instance endpoint)
- Run `SELECT CONNECTION_ID();` again
- Confirm the session ID is ≥ 16777215

### Problem 3: Read Queries Not Routed to Read Replicas Despite Read/Write Splitting

**Symptoms**
- Read-only queries (e.g., `SELECT`) are executed on the primary instance
- Behavior: Increased load on primary, no offloading to read replicas
- Context: Database Proxy with read/write splitting enabled, but reads not distributed

**Root Cause**
Read/write splitting behavior depends on **consistency level**, **transaction context**, and **SQL patterns**. By default:
- Strong consistency routes all requests to primary
- Within transactions, all statements go to primary
- Certain SQL statements (e.g., those with `FOR UPDATE`) bypass read splitting

**Solution**
1. Check current consistency level in the Database Proxy settings (console path: **Database Proxy > Modify proxy endpoint**)
2. To enable read replica usage:
   - Set consistency level to **Eventual Consistency** for non-critical reads
   - Avoid wrapping read queries in transactions unless necessary
   - Use explicit hints if supported (e.g., `/*FORCE_SLAVE*/ SELECT ...`)
3. Ensure the query does not contain write-intent clauses (`LOCK IN SHARE MODE`, `FOR UPDATE`, etc.)

**Verification**
- Enable slow query log or audit log on read replicas
- Execute a read query known to be eligible for splitting
- Confirm the query appears in the read replica logs
- Alternatively, monitor replica CPU/network metrics during read load

## FAQ

**Q: How do I check if my RDS instance is using the Database Proxy?**  
A: Connect using the proxy endpoint and run `SELECT CONNECTION_ID();`. If the result is 16777215 or higher, you are connected via the proxy. Direct connections return values below 16777215.

**Q: What permissions are required to manage Database Proxy settings?**  
A: You need the `AliyunRDSFullAccess` policy or custom permissions that include `rds:ModifyDBProxy`, `rds:DescribeDBProxy`, and `rds:ModifyDBProxyEndpoint` actions on the target instance.

**Q: Why can't I change my instance from dual-zone to single-zone after enabling Database Proxy?**  
A: The proxy endpoint must exist only in the destination availability zone. Delete any proxy endpoint in the source zone first via the RDS console under **Database Proxy > Connection information** before proceeding with the topology change.

**Q: Does the general-purpose proxy support the same features as the dedicated proxy?**  
A: Both support core features like read/write splitting and connection pooling. However, dedicated proxies offer higher specifications (up to 64 CPU cores) and are billed pay-as-you-go, while general-purpose proxies are free but limited to 16 CPU cores.

**Q: How can I verify that read/write splitting is working correctly?**  
A: Monitor read replica metrics (CPU, connections, queries) during read-heavy workloads. Additionally, use the `SHOW PROCESSLIST` command on replicas to observe active read queries, or enable SQL audit logs to trace query routing.