# rds-dr

Part of **RDS**

# ApsaraDB RDS Disaster Recovery

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| SwitchGuardToMasterInstance | Synchronous | Promote a disaster recovery instance to primary role |
| ReceiveDBInstance | Synchronous | Switch a primary instance to disaster recovery role |
| ModifyHADiagnoseConfig | Synchronous | Modify the availability check method (persistent or short-lived connection) |
| DescribeHADiagnoseConfig | Synchronous | Query the current availability check method of an RDS instance |

## API Calling Patterns

### Authentication
The primary authentication method is Bearer Token authentication.

- Include the header: `Authorization: Bearer <your_api_key>`
- Store your API key in the environment variable: `ALIYUN_API_KEY`
- Note: Some examples reference `DASHSCOPE_API_KEY`, but for RDS APIs, use standard Alibaba Cloud credentials via `ALIYUN_API_KEY`

### Service Endpoint
All APIs use a single global endpoint:

- Base URL: `https://rds.aliyuncs.com/`
- Method: POST
- Region: The endpoint is region-agnostic; specify the target region using the `RegionId` parameter in the request body when required (e.g., for HA configuration operations)

### Synchronous API Pattern
All disaster recovery APIs follow a synchronous request-response pattern:

1. Send a 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 server processes the request immediately and returns a JSON response
4. Parse the response for success fields (`RequestId`, instance IDs) or handle error codes

No polling or async handling is needed—responses are immediate.

## Parameter Reference

### SwitchGuardToMasterInstance

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| Action | string | Yes | — | Must be `SwitchGuardToMasterInstance` | The operation to perform |
| DBInstanceId | string | Yes | — | — | The ID of the disaster recovery instance to promote |

### ReceiveDBInstance

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| Action | string | Yes | — | Must be `ReceiveDBInstance` | The operation to perform |
| DBInstanceId | string | Yes | — | — | The ID of the primary instance |
| GuardDBInstanceId | string | Yes | — | — | The ID of the disaster recovery instance |

### ModifyHADiagnoseConfig

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| Action | string | Yes | — | Must be `ModifyHADiagnoseConfig` | The operation to perform |
| DBInstanceId | string | Yes | — | — | The ID of the RDS instance |
| RegionId | string | Yes | — | Valid Alibaba Cloud region ID | The region where the instance resides |
| TcpConnectionType | string | Yes | — | One of: `SHORT`, `LONG` | Availability check method: `SHORT` for short-lived, `LONG` for persistent connection |

### DescribeHADiagnoseConfig

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| Action | string | Yes | — | Must be `DescribeHADiagnoseConfig` | The operation to perform |
| DBInstanceId | string | Yes | — | — | The ID of the RDS instance |
| RegionId | string | Yes | — | Valid Alibaba Cloud region ID | The region where the instance resides |

## Code Examples

### Promote DR Instance to Primary - Bash - All Regions

```bash
curl -X POST "https://rds.aliyuncs.com/" \
  -H "Authorization: Bearer $ALIYUN_API_KEY" \
  -d "Action=SwitchGuardToMasterInstance" \
  -d "DBInstanceId=rm-uf6wjk5*****" \
  -d "<Common request parameters>"
```

### Switch Primary to DR Instance - Bash - All Regions

```bash
curl -X POST "https://rds.aliyuncs.com/" \
  -H "Authorization: Bearer $ALIYUN_API_KEY" \
  -d "Action=ReceiveDBInstance" \
  -d "DBInstanceId=rm-uf6wjk5*****" \
  -d "GuardDBInstanceId=rm-tr2whku*****" \
  -d "<Common request parameters>"
```

### Modify Availability Check Method - Bash - cn-hangzhou

```bash
curl -X POST "https://rds.aliyuncs.com/" \
  -H "Authorization: Bearer $ALIYUN_API_KEY" \
  -d "Action=ModifyHADiagnoseConfig" \
  -d "DBInstanceId=rm-uf6wjk5xxxxxxxxxx" \
  -d "RegionId=cn-hangzhou" \
  -d "TcpConnectionType=SHORT" \
  -d "<Common request parameters>"
```

### Query Availability Check Method - Bash - cn-hangzhou

```bash
curl -X POST "https://rds.aliyuncs.com/" \
  -H "Authorization: Bearer $ALIYUN_API_KEY" \
  -d "Action=DescribeHADiagnoseConfig" \
  -d "DBInstanceId=rm-uf6wjk5xxxxxxxxxx" \
  -d "RegionId=cn-hangzhou" \
  -d "<Common request parameters>"
```

## Response Format

```json
{
  "DBInstanceId": "rm-uf6wjk5*****",
  "RequestId": "EFB6083A-7699-489B-8278-C0CB4793A96E"
}
```

**Key Fields**:
- `RequestId` — Unique identifier for the API request; useful for troubleshooting
- `DBInstanceId` — ID of the affected instance (present in promotion responses)
- `GuardDBInstanceId` — ID of the disaster recovery instance (in switchover responses)
- `TcpConnectionType` — Current availability check method (`SHORT` or `LONG`)

## Error Handling

| Error Code (Code) | Description (Description) | Recommended Action (Recommended Action) |
|-------------------|----------------------------|----------------------------------------|
| 400 | Invalid parameter provided. Check the request parameters and try again. | Validate all parameters against constraints (e.g., correct Action value, valid instance IDs) |
| 404 | The specified instance does not exist. Verify the DBInstanceId and ensure it is correct. | Confirm the instance ID exists using `DescribeDBInstances` |
| 500 | Internal server error. Retry the request after a short delay or contact support. | Implement exponential backoff and retry; contact Alibaba Cloud support if persistent |
| 403 | Permission denied. Ensure the user has the necessary permissions to modify the RDS instance configuration. | Assign appropriate RAM policies (e.g., AliyunRDSFullAccess) |
| AccessDenied | The request is denied due to insufficient permissions. | Verify account permissions and resource access control |
| InvalidDBInstanceId.NotFound | The specified DBInstanceId does not exist. | Double-check instance ID spelling and region |
| InvalidRegionId.NotFound | The specified RegionId does not exist. | Use a valid region ID from `DescribeRegions` |
| Throttling | The request rate exceeds the limit. Wait a moment and try again. | Reduce request frequency; respect QPS limits |

### Rate Limits & Retry
- `DescribeHADiagnoseConfig`: 100 QPS per account
- Other APIs: Up to 10 requests per second
- On `Throttling` errors, wait at least 1 second before retrying. Use exponential backoff (e.g., 1s, 2s, 4s) for repeated failures.

## Environment Requirements

- Set your Alibaba Cloud API key: `export ALIYUN_API_KEY=your_access_key_secret`
- Ensure common request parameters (e.g., `Version=2014-08-15`, `Timestamp`, `SignatureMethod=HMAC-SHA1`) are included as per [Alibaba Cloud API documentation](https://help.aliyun.com/document_detail/25494.html)

## FAQ

Q: Do I need to stop my application during a disaster recovery switch?
A: Yes, it's recommended to pause write operations during the switch to avoid data inconsistency. Read operations may continue depending on your architecture.

Q: Can I switch back to the original primary instance after promoting a DR instance?
A: Yes, once the original primary is restored and synchronized, you can use `ReceiveDBInstance` to re-establish the DR relationship and switch roles again.

Q: What regions support disaster recovery instances?
A: Cross-region DR is supported across most Alibaba Cloud regions. Use `DescribeRegions` to get the latest list. Common pairs include cn-hangzhou ↔ cn-shanghai, cn-beijing ↔ cn-shenzhen.

Q: How long does a switch operation take?
A: Typically under 30 seconds. The exact time depends on instance size and replication lag. Monitor the operation via the returned `RequestId`.

Q: Are there any prerequisites before calling these APIs?
A: Yes: (1) A DR instance must already be created and synchronized, (2) You must have proper RAM permissions, and (3) The instances must be in a stable running state.

## Pricing & Billing

### Billing Model
- `SwitchGuardToMasterInstance` and `ModifyHADiagnoseConfig`: Billed per request
- `ReceiveDBInstance`: Billed per instance-hour (for ongoing DR instance usage)
- `DescribeHADiagnoseConfig`: Billed per request with free tier

### Price Reference

| Tier | Input Price | Output Price | Other Fees |
|------|-------------|--------------|-----------|
| SwitchGuardToMasterInstance | 0.01 CNY/request | — | — |
| ModifyHADiagnoseConfig | 0.001 CNY/request | — | — |
| DescribeHADiagnoseConfig | 0.001 CNY/request | 0.001 CNY/request | — |
| ReceiveDBInstance (Standard) | 0.01 CNY/hour | 0.01 CNY/hour | — |

### Free Tier
- `DescribeHADiagnoseConfig`: 1000 free requests per month

### Usage Limits
- Per-account QPS limits: 10–100 depending on API
- Maximum 10 RDS instances per account (affects `ReceiveDBInstance` usage)

### Billing Notes
- Each API call counts as one request regardless of payload size
- DR instance hourly billing starts upon creation and continues until deletion
- Free tier for `DescribeHADiagnoseConfig` resets monthly on the 1st