# rds-migration

Part of **RDS**

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

> 💡 **Path Selection**: This skill is one implementation path for [Migrate database data to or between RDS instances](../../intent/rds-migrate-data/SKILL.md). If you're unsure which path to take, check the routing skill first.

# ApsaraDB RDS Data Migration

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Migrate Data Between Instances | Synchronous | Migrate data directly between different RDS SQL Server instances. |
| Cloud Migration | Synchronous | Perform cloud migration tasks including assessment, creation, querying details, and switching workloads for RDS PostgreSQL instances. |

## API Calling Patterns

### Authentication
Use **Bearer Token** authentication as the primary method.

- Include the header: `Authorization: Bearer <your_api_key>`
- Store your credential in the environment variable: `ALIBABA_CLOUD_ACCESS_KEY_ID` (or `DASHSCOPE_API_KEY` depending on context; both are accepted)
- While Alibaba Cloud also supports signature-based authentication (AccessKey ID/Secret), the Bearer token method is simpler for direct API testing and is consistently shown in examples.

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

- Base URL: `https://rds.aliyuncs.com/`
- Region: The endpoint is region-agnostic (`region=all`); no region-specific URLs are required.

### Synchronous Request Pattern
All data migration APIs follow a **synchronous** pattern:
1. Send an HTTP GET or POST request to `https://rds.aliyuncs.com/` with query parameters.
2. Include common request parameters (e.g., `Version`, `Timestamp`, `Signature` if using signature auth) or use Bearer token auth.
3. Receive an immediate JSON or XML response with results or error codes.
4. No polling or async handling is needed—each call completes in one round trip.

## Parameter Reference

### Migrate Data Between Instances

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| Action | String | Yes | — | Must be `ImportDatabaseBetweenInstances` | The operation to perform. |
| DBInfo | String | Yes | — | Must be a valid JSON string with `DBNames` array or source-to-destination mapping | Names of source and destination databases. |
| DBInstanceId | String | Yes | — | — | ID of the destination RDS instance. |
| SourceDBInstanceId | String | Yes | — | Must differ from `DBInstanceId` | ID of the source RDS instance. |

### Cloud Migration Assessment & Task Creation

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| Action | String | Yes | — | One of: `CreateCloudMigrationPrecheckTask`, `CreateCloudMigrationTask` | The operation to perform. |
| DBInstanceName | String | Yes | — | — | ID of the target RDS PostgreSQL instance. |
| SourceIpAddress | String | Yes | — | — | Private or public IP of the self-managed PostgreSQL instance. |
| SourcePort | Long | Yes | — | — | Port number of the source PostgreSQL instance. |
| SourceAccount | String | Yes | — | — | Username for connecting to the source instance. |
| SourcePassword | String | Yes | — | — | Password for the source account. |
| TaskName | String | No | Auto-generated | — | Custom name for the migration task. |
| SourceCategory | String | Yes | — | One of: `ecsOnVpc`, `idcOnVpc`, `internet` | Environment of the source instance. |

### Query Migration Details

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| Action | String | Yes | — | One of: `DescribeCloudMigrationResult`, `DescribeCloudMigrationPrecheckResult` | Operation to retrieve task details or assessment report. |
| DBInstanceName | String | Yes | — | — | Target RDS instance ID. |
| TaskId | Long | No | — | — | ID of the migration task (optional if `TaskName` provided). |
| TaskName | String | No | — | — | Name of the migration task (optional if `TaskId` provided). |
| SourceIpAddress | String | No | — | — | Source IP (optional for filtering). |
| SourcePort | Long | No | — | — | Source port (optional for filtering). |
| PageNumber | Long | Yes | — | — | Page number for pagination. |
| PageSize | Long | Yes | — | — | Number of entries per page. |

### Switch Workloads & Cancel Tasks

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| Action | String | Yes | — | One of: `ActivateMigrationTargetInstance`, `CancelImport` | Operation to switch or cancel. |
| DBInstanceName / DBInstanceId | String | Yes | — | — | Target RDS instance ID. |
| SwitchTimeMode | String | No | `0` | Must be `0` | Immediate switchover. |
| ForceSwitch | String | No | `1` | Must be `1` | Forceful switchover. |
| ImportId | Integer | Yes (for CancelImport) | — | — | ID of the migration task to cancel. |

## Code Examples

### Migrate Data Between SQL Server Instances - Bash - All Regions

```bash
https://rds.aliyuncs.com/?Action=ImportDatabaseBetweenInstances\
&DBInstanceId=rm-uf6wjk5xxxxxxx\
&SourceDBInstanceId=rm-g4a1jk8xxxxxxx\
&DBInfo={"DBNames":["mydb","mydb2"]}\
&<Common request parameters>
```

### Create Cloud Migration Assessment Task - Bash - All Regions

```bash
https://rds.aliyuncs.com/?Action=CreateCloudMigrationPrecheckTask\
&DBInstanceName=pgm-bp102g323jd4****\
&SourceIpAddress=172.2.XX.XX\
&SourcePort=5432\
&SourceAccount=migratetest\
&SourcePassword=123456\
&TaskName=slf7w7wj3g\
&SourceCategory=ecsOnVpc\
&<Common request parameters>
```

### Query Cloud Migration Task Details - Bash - All Regions

```bash
https://rds.aliyuncs.com/?Action=DescribeCloudMigrationResult\
&DBInstanceName=pgm-bp102g323jd4****\
&TaskId=440437220\
&PageNumber=1\
&PageSize=10\
&<Common request parameters>
```

### Cancel Migration Task - Bash - All Regions

```bash
https://rds.aliyuncs.com/?Action=CancelImport\
&DBInstanceId=rm-uf6wjk5xxxxxxx\
&ImportId=8562584\
&<Common request parameters>
```

### Switch Workloads to Destination Instance - JSON Response Example

```json
{
  "DBInstanceName": "pgm-bp102g323jd4****",
  "RequestId": "76364A52-E0AB-5CC8-9818-CF1DC482C092",
  "TaskId": 440913675,
  "SourceIpAddress": "172.16.XX.XX",
  "SourcePort": 5432
}
```

### Assessment Report Response - JSON

```json
{
  "TotalSize": 1,
  "RequestId": "7E4A6E1B-789B-5F16-9736-39AA57FC7374",
  "Items": {
    "GmtCreated": "2022-02-25T06:57:41Z",
    "TaskId": 440420798,
    "TaskName": "lxbv6rtxno8",
    "SourceCategory": "ecsonvpc",
    "SourceIpAddress": "172.2.XX.XX",
    "SourcePort": 5432,
    "Detail": "[Check rds empty]\nCheck rds databases: success\n[Check source connectivity]\nCheck ip connectable: success\n..."
  },
  "PageNumber": 1,
  "PageSize": 10
}
```

## Response Format

```json
{
  "ImportId": 2122321,
  "RequestId": "5A77D650-27A1-4E08-AD9E-59008EDB6927"
}
```

**Key Fields**:
- `ImportId` — Unique identifier for the cross-instance migration task.
- `RequestId` — Unique ID for the API request (useful for troubleshooting).
- `TaskId` — ID of a cloud migration task (for PostgreSQL workflows).
- `Items.Detail` — Human-readable log of assessment or migration steps.
- `Items.MigrateStage` — Current phase of migration (e.g., `increment` for incremental sync).

## Error Handling

| Error Code | Description | Recommended Action |
|------------|-------------|---------------------|
| 400 | Bad Request: Invalid or missing parameters. | Verify all required parameters (e.g., `DBInstanceId`, `SourceDBInstanceId`) and their formats. |
| 403 | Forbidden: Operation not supported by instance type or state. | Ensure the RDS instance engine (SQL Server/PostgreSQL) and status (Running) support migration. |
| 404 | Not Found: Instance or task does not exist. | Double-check instance IDs and task IDs; confirm they belong to your account. |
| 500 | Internal Server Error. | Retry the request after a short delay. |
| 503 | Service Unavailable. | Wait and retry later; check Alibaba Cloud status dashboard. |

## Pricing & Billing

### Billing Model
All operations are billed **per request**, regardless of success or failure.

### Price Reference

| Tier | Input Price | Output Price | Other Fees |
|------|-------------|--------------|-----------|
| standard | 0.001 / | 0.001 / | — |
| default | 0.002 / | — | — |

### Free Tier
- **Migrate Data / Query Tasks**: 100 free requests per month.
- **Assessment Task Creation**: No free tier.

### Usage Limits
- **Query APIs**: Up to 100 QPS or 10 requests/second (depending on operation).
- **Migration Tasks**: Up to 1000 tasks per day per account (for cancellation).
- **Request Size**: Max 10 MB per request.

### Billing Notes
- Failed API calls still count toward billing and quotas.
- Cancellation does not refund the original migration cost.
- Prices shown are in Chinese Yuan (CNY).

## FAQ

Q: Can I migrate data between RDS instances in different regions?
A: The `ImportDatabaseBetweenInstances` API requires both instances to be in the same region and network environment. Cross-region migration typically requires Data Transmission Service (DTS).

Q: What PostgreSQL versions are supported for cloud migration?
A: The source and target must have compatible major versions. The assessment task checks version consistency automatically.

Q: Why do I get a 403 error when creating a migration task?
A: Ensure your RDS instance runs PostgreSQL (not MySQL/SQL Server) and is in the "Running" state. Also verify your account has sufficient permissions.

Q: Is there a way to monitor migration progress programmatically?
A: Yes—call `DescribeCloudMigrationResult` periodically to check `MigrateStage` and `ReplicationState`.

Q: Do I need to stop my source database during migration?
A: No—Alibaba Cloud uses logical replication for PostgreSQL, allowing zero-downtime migration. For SQL Server cross-instance migration, brief locking may occur.

## Environment Requirements

- Use standard HTTP clients (curl, Python requests, etc.)—no special SDK is required.
- Set your API key via environment variable:  
  ```bash
  export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
  ```
- Common request parameters (e.g., `Version=2014-08-15`, `Timestamp`, `SignatureMethod`) are required if not using Bearer token auth.