# rds-proxy

Part of **RDS**

# ApsaraDB RDS Database Proxy

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Manage Database Proxy | Synchronous | Create, modify, delete, and query database proxy endpoints and settings including SSL encryption. |

## API Calling Patterns

### Authentication
Use **Bearer Token** authentication via the `Authorization` header.

- Header format: `Authorization: Bearer <your_api_key>`
- Environment variable: `ALIYUN_API_KEY` (or `DASHSCOPE_API_KEY` in some examples — use `ALIYUN_API_KEY` for consistency with Alibaba Cloud RDS)
- While other auth methods may exist, Bearer Token is used consistently across all documented RDS Proxy API examples and is recommended.

### Service Endpoint (Endpoint)
All Database Proxy APIs use the same global base URL:

- Base URL: `https://rds.aliyuncs.com`
- The endpoint is **not region-specific** — a single endpoint serves all regions.
- Common regions referenced in parameters include `cn-hangzhou`, `cn-shanghai`, and `cn-beijing`, but these are passed as values in the `RegionId` parameter, not in the URL.

### Synchronous API Pattern
All Database Proxy operations follow a **synchronous** calling pattern:

1. Send an HTTP GET or POST request to `https://rds.aliyuncs.com/` with required parameters.
2. Include common request parameters (e.g., `Version`, `Timestamp`, `Signature`, etc.) as per Alibaba Cloud API standards.
3. The API processes the request immediately and returns a JSON or XML response.
4. On success, the response includes a `RequestId` field.
5. On failure, an error code and message are returned (see Error Handling).
6. No polling or async task tracking is required — the operation completes before the response is sent.

> **Note**: Although some operations (like proxy creation or version upgrade) may trigger backend changes that take time to fully apply, the API itself responds synchronously with a `RequestId` upon acceptance of the request.

## Parameter Reference

### Manage Database Proxy

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| Action | String | Yes | — | — | The operation to perform (e.g., `ModifyDbProxyInstanceSsl`, `CreateDBProxyEndpointAddress`). |
| DBInstanceId | String | Yes | — | — | The ID of the RDS instance. |
| RegionId | String | Conditional | — | — | The region ID (required for most operations). |
| DBProxyEndpointId | String | Conditional | — | — | The ID of the proxy endpoint (required when managing endpoints). |
| DbProxySslEnabled | String | Yes (for SSL config) | — | One of: `0`, `1`, `2` | SSL setting: `0`=disable, `1`=enable/modify, `2`=update cert validity. |
| ConnectionStringPrefix | String | Yes (create) | — | — | Custom prefix for the proxy endpoint (5–40 chars). |
| DBProxyConnectStringNetType | String | Yes | `Classic` | One of: `Public`, `VPC`, `Classic` | Network type of the proxy endpoint. |
| ConfigDBProxyService | String | Yes (enable/disable) | — | One of: `Startup`, `Shutdown` | Enable or disable the database proxy feature. |
| DBProxyInstanceNum | String | No | `1` | Range: 1–60 | Number of proxy instances to enable. |
| ConfigDBProxyFeatures | String | No | — | Format: `Feature:State;...`<br>Features: `ReadWriteSpliting`, `ConnectionPersist`, `TransactionReadSqlRouteOptimizeStatus`<br>State: `1`=enabled, `0`=disabled | Features to enable on the proxy endpoint. |
| ReadOnlyInstanceMaxDelayTime | String | No | `30` | Range: 0–3600 | Max replication lag (seconds) for read/write splitting. |
| ReadOnlyInstanceDistributionType | String | No | — | One of: `Standard`, `Custom` | Read weight allocation policy. |
| EffectiveTime | String | No | `MaintainTime` | One of: `Immediate`, `MaintainTime`, `SpecificTime` | When to apply proxy setting changes. |
| StartTime | String | Yes (performance query) | — | ISO 8601 UTC (`yyyy-MM-ddTHH:mm:ssZ`) | Start of time range for performance metrics. |
| EndTime | String | Yes (performance query) | — | ISO 8601 UTC, > `StartTime` | End of time range for performance metrics. |
| MetricsName | String | Yes (performance query) | — | Comma-separated list of up to 6 metrics:<br>MySQL: `Maxscale_CpuUsage`<br>PostgreSQL: `Maxscale_CpuUsage`, `Maxscale_TotalConns`, `Maxscale_CurrentConns`, `Maxscale_DownFlows`, `Maxscale_UpFlows`, `Maxscale_QPS`, `Maxscale_MemUsage` | Performance metrics to retrieve. |
| UpgradeTime | String | No | `MaintainTime` | One of: `MaintainTime`, `Immediate`, `SpecificTime` | When to upgrade proxy version. |

## Code Examples

### Create a Proxy Endpoint - curl - all

```bash
http(s)://rds.aliyuncs.com/?Action=CreateDBProxyEndpointAddress
&RegionId=cn-hangzhou
&DBInstanceId=m-t4n3axxxxx
&DBProxyEndpointId=ta9um4xxxxx
&DBProxyConnectStringNetType=Public
&ConnectionStringPrefix=test1234
<&lt;Common request parameters&gt;
```

### Modify SSL Encryption - bash - all

```bash
http(s)://rds.aliyuncs.com/?Action=ModifyDbProxyInstanceSsl
&DbInstanceId=rm-t4n3axxxxx
&DbProxyEndpointId=ta9um4xxxxx
&DbProxyConnectString=test123456.rwlb.rds.aliyuncs.com
&DbProxySslEnabled=1
<&lt;Common request parameters&gt;
```

### Query Proxy Endpoint Details - bash - all

```bash
http(s)://rds.aliyuncs.com/?Action=DescribeDBProxyEndpoint
&DBInstanceId=rm-bp1ja4f56s7us****
&RegionId=cn-hangzhou
<&lt;Common request parameters&gt;
```

### Modify Proxy Endpoint Settings - bash - all

```bash
http(s)://rds.aliyuncs.com/?Action=ModifyDBProxyEndpoint
&DBInstanceId=rm-bp145737x5bi6****
&DBProxyEndpointId=gos787jog2wk0y****
&ConfigDBProxyFeatures=ReadWriteSpliting:1;ConnectionPersist:1;
&ReadOnlyInstanceMaxDelayTime=30
&ReadOnlyInstanceDistributionType=Standard
<&lt;Common request parameters&gt;
```

### Query Database Proxy Performance - bash - all

```bash
http(s)://rds.aliyuncs.com/?Action=DescribeDBProxyPerformance
&RegionId=cn-hangzhou
&DBInstanceId=rm-t4n3axxxxx
&MetricsName=Maxscale_CpuUsage
&StartTime=2019-09-19T01:00:00Z
&EndTime=2019-09-21T18:00:00Z
<&lt;Common request parameters&gt;
```

### Enable Database Proxy - plaintext - all

```text
http(s)://rds.aliyuncs.com/?Action=ModifyDBProxy
&DBInstanceId=rm-uf6wjk5xxxxxxx
&ConfigDBProxyService=Startup
<&lt;Common request parameters&gt;
```

## Response Format

```json
{
  "RequestId": "BF46A62B-3717-4397-9338-36BB95C898B3"
}
```

**Key Fields**:
- `RequestId` — Unique identifier for the API request; useful for troubleshooting and support.

> **Note**: Some operations (e.g., `DescribeDBProxy`, `GetDbProxyInstanceSsl`, `DescribeDBProxyPerformance`) return additional data beyond `RequestId`. However, the minimal success response across all operations includes only `RequestId`.

## Error Handling

| Error Code (Code) | Description (Description) | Recommended Action (Recommended Action) |
|-------------------|----------------------------|----------------------------------------|
| 400 | The current database minor version does not support the operation. | Upgrade the RDS instance's minor engine version. |
| 400 | The proxy status of the database is abnormal. | Check the proxy status via `DescribeDBProxy` and retry after stabilization. |
| 400 | Specified parameter DBInstanceName is not valid. | Ensure `DBInstanceId` is non-empty and valid. |
| 403 | The specified instance category does not support this operation. | Verify that your RDS edition (e.g., High-availability, Enterprise) supports database proxy. |
| 404 | The specified endpoint is not found. | Confirm the `DBProxyEndpointId` exists using `DescribeDBProxyEndpoint`. |
| 404 | The backend service does not support SSL. | SSL may not be supported for your RDS engine or version; check documentation. |
| 400 | The port number that you specified is invalid. | Use valid port numbers (e.g., 3306 for MySQL, 5432 for PostgreSQL). |
| 400 | A proxy endpoint of the specified network type already exists. | Each network type (`Public`, `VPC`, `Classic`) allows only one endpoint per proxy. |
| 403 | This operation is not supported when the instance is in the current state. | Ensure the RDS instance is in `Running` state before modifying proxy settings. |

## FAQ

Q: How do I enable the database proxy feature for my RDS instance?
A: Use the `ModifyDBProxy` API with `ConfigDBProxyService=Startup`. For MySQL with standard SSDs/ESSDs or PostgreSQL, you must also specify `VPCId` and `VSwitchId`.

Q: Can I have multiple proxy endpoints for the same RDS instance?
A: Yes, but only one endpoint per network type (`Public`, `VPC`, `Classic`). You can create separate endpoints for different network environments.

Q: Why am I getting a "minor version not supported" error when configuring SSL?
A: SSL encryption for dedicated proxy endpoints requires a minimum minor engine version. Upgrade your RDS instance’s kernel version first.

Q: How do I monitor the performance of my database proxy?
A: Use the `DescribeDBProxyPerformance` API with metrics like `Maxscale_CpuUsage` and time ranges in ISO 8601 UTC format.

Q: Is there a delay between API success and actual proxy configuration taking effect?
A: The API returns immediately upon request acceptance, but backend changes (e.g., SSL setup, version upgrades) may take a few minutes to complete. Use `DescribeDBProxy` to check status.

## Pricing & Billing

### Billing Model
All Database Proxy API calls are billed on a **per-request** basis.

> **Note**: The extracted data indicates a per-request billing model, but no specific pricing details (e.g., cost per call) were provided. Actual charges may depend on your Alibaba Cloud account plan.