# rds-account

Part of **RDS**

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

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

# ApsaraDB RDS Account Management

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Manage Database Account | Synchronous | Create, delete, modify, and query database accounts for RDS instances. |
| Manage Account Permissions | Synchronous | Grant, revoke, and reset permissions for database accounts including service accounts. |

## API Calling Patterns

### Authentication
Use **Bearer Token** authentication with your Alibaba Cloud API key.

- Include the header: `Authorization: Bearer <your_api_key>`
- Store your credential in the environment variable: `ALIYUN_API_KEY`
- While other auth methods exist (e.g., request signing), Bearer Token is recommended for simplicity in development and testing.

### Service Endpoint
All account management APIs use the same global endpoint:

- Base URL: `https://rds.aliyuncs.com/`
- Method: Mostly `GET`, some operations use `POST`
- Region: The endpoint is region-agnostic; specify your instance ID (which encodes region) in the `DBInstanceId` parameter.

### Synchronous API Pattern
All account management operations are synchronous:

1. Send a single HTTP request with all required parameters
2. Wait for an immediate JSON or XML response
3. Parse the `RequestId` field to confirm success
4. Handle errors using standard HTTP status codes (4xx/5xx)

No polling or async task tracking is needed—each call completes in one round trip.

## Parameter Reference

### Manage Database Account

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| Action | String | Yes | — | Must be one of: `CreateAccount`, `DeleteAccount`, `ModifyAccountDescription`, `DescribeAccounts`, `DescribeInstanceKeywords` | The operation to perform |
| DBInstanceId | String | Yes | — | — | The ID of the RDS instance |
| AccountName | String | Conditional | — | Varies by engine: 2–32 chars (MySQL), 2–64 (SQL Server), 2–63 (PostgreSQL cloud disk); must start/end with letter/digit; lowercase letters, digits, underscores only | The name of the database account |
| AccountPassword | String | Conditional | — | 8–32 characters; must contain at least three of: uppercase, lowercase, digits, special chars (`!@#$%^&*()_+-=`) | Password for the account |
| AccountDescription | String | No | — | 2–256 characters; must start with letter or Chinese char; cannot start with `http://` or `https://` | Description of the account |
| AccountType | String | No | `Normal` | One of: `Normal`, `Super` | Account privilege level |
| PageSize | Integer | No | `30` | Range: 30–100 | Number of accounts per page in query results |
| PageNumber | Integer | No | `1` | ≥1 | Page number for pagination |
| Key | String | Conditional | — | One of: `account`, `database` | Type of reserved keyword to query |

### Manage Account Permissions

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| Action | String | Yes | — | Must be one of: `GrantOperatorPermission`, `GrantAccountPrivilege`, `ResetAccount`, `RevokeAccountPrivilege`, `RevokeOperatorPermission`, `ResetAccountPassword`, `LockAccount`, `UnlockAccount` | The permission operation |
| DBInstanceId | String | Yes | — | — | The ID of the RDS instance |
| AccountName | String | Conditional | — | — | Name of the target account |
| DBName | String | Conditional | — | Comma-separated list allowed | Database(s) to grant/revoke access to |
| AccountPrivilege | String | Conditional | — | One of: `ReadWrite`, `ReadOnly`, `DDLOnly`, `DMLOnly`, `DBOwner` | Permission level on the database |
| Privileges | String | Conditional | — | One of: `Control`, `Data` | Service account permission type |
| ExpiredTime | String | Conditional | — | ISO 8601 UTC format: `yyyy-MM-ddTHH:mm:ssZ` | Expiration time for service account permissions |

## Code Examples

### Create a Database Account - Bash - All Regions

```bash
curl "https://rds.aliyuncs.com/?Action=CreateAccount\
&DBInstanceId=rm-uf6wjk5xxxxxxx\
&AccountName=test1\
&AccountPassword=Test123456\
&AccountType=Normal\
&<Common request parameters>"
```

### Grant Database Permissions - Bash - All Regions

```bash
curl "https://rds.aliyuncs.com/?Action=GrantAccountPrivilege\
&DBInstanceId=rm-uf6wjk5xxxxxxxxxx\
&AccountName=test1\
&DBName=testDB1\
&AccountPrivilege=ReadWrite\
&<Common request parameters>"
```

### Query Account Information - Bash - All Regions

```bash
curl "https://rds.aliyuncs.com/?Action=DescribeAccounts\
&DBInstanceId=rm-uf6wjk5xxxxxxx\
&PageSize=50\
&PageNumber=1\
&<Common request parameters>"
```

### Lock a PostgreSQL Account - Bash - All Regions

```bash
curl "https://rds.aliyuncs.com/?Action=LockAccount\
&DBInstanceId=pgm-bpxxxxx\
&AccountName=testaccount\
&<Common request parameters>"
```

### Reset Account Password - Bash - All Regions

```bash
curl "https://rds.aliyuncs.com/?Action=ResetAccountPassword\
&DBInstanceId=rm-uf6wjk5xxxxxxx\
&AccountName=test1\
&AccountPassword=NewSecurePass123!\
&<Common request parameters>"
```

### Revoke Service Account Permissions - Bash - All Regions

```bash
curl "https://rds.aliyuncs.com/?Action=RevokeOperatorPermission\
&DBInstanceId=rm-uf6wjk5xxxxxxx\
&<Common request parameters>"
```

## Response Format

```json
{
  "RequestId": "D4D4BE8A-DD46-440A-BFCD-EE31DA81C9DD"
}
```

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

For `DescribeAccounts`, the response includes detailed account metadata:

```json
{
  "Accounts": {
    "DBInstanceAccount": [
      {
        "AccountName": "testacc02",
        "AccountStatus": "Available",
        "AccountType": "Normal",
        "DatabasePrivileges": {
          "DatabasePrivilege": [
            {
              "DBName": "testdb",
              "AccountPrivilege": "ReadWrite",
              "AccountPrivilegeDetail": "SELECT,INSERT,UPDATE,DELETE,..."
            }
          ]
        }
      }
    ]
  },
  "RequestId": "A2E94301-D07F-4457-9B49-6AA2BB388C85"
}
```

**Key Fields**:
- `Accounts.DBInstanceAccount[].AccountName` — Name of the account
- `Accounts.DBInstanceAccount[].AccountStatus` — Current status (e.g., `Available`, `Locked`)
- `Accounts.DBInstanceAccount[].AccountType` — `Normal` or `Super`
- `Accounts.DBInstanceAccount[].DatabasePrivileges.DatabasePrivilege[].DBName` — Database name
- `Accounts.DBInstanceAccount[].DatabasePrivileges.DatabasePrivilege[].AccountPrivilege` — High-level privilege (e.g., `ReadWrite`)
- `TotalRecordCount`, `PageNumber` — Pagination metadata

## Error Handling

| Error Code | Description | Recommended Action |
|------------|-------------|-------------------|
| 400 | The general instance is creating/maintaining/Switching | Wait and retry after a few minutes |
| 400 | Specified account name already exists | Choose a different `AccountName` |
| 400 | Specified account password is not valid | Ensure password meets complexity rules |
| 400 | Create Account failed... input value not satisfy instance policy | Review instance-specific account policies |
| 403 | Current DB instance state does not support this operation | Ensure instance is in `Running` state |
| 403 | AccountQuotaExceeded: Exceeding the allowed amount of account | Delete unused accounts or request quota increase |
| 404 | The database instance does not exist | Verify `DBInstanceId` is correct |
| InvalidDBInstanceStatus | The instance is not in the Running state | Wait until instance is running before proceeding |
| SomeObjectsDependOnAccount | The account has permissions on specific objects | Revoke all database/table permissions before deletion |

### Rate Limits & Retry
- Most operations: **100 QPS per account**
- Service account operations (`GrantOperatorPermission`, `RevokeOperatorPermission`): **10 requests per second**
- If rate-limited (HTTP 429), implement exponential backoff with jitter
- For transient errors (5xx), retry up to 3 times with 1–5 second delays

## Environment Requirements

- Set your API key: `export ALIYUN_API_KEY=your_access_key_secret`
- For SDK usage, install the Alibaba Cloud SDK: `pip install aliyun-python-sdk-rds`
- Python 3.6+ or Java 8+ recommended for SDK compatibility

## FAQ

Q: Can I use the same account name across different RDS instances?
A: Yes. Account names are scoped to each RDS instance, so `admin` can exist in multiple instances independently.

Q: Why am I getting "AccountQuotaExceeded" when creating a new account?
A: Each RDS instance has a maximum number of accounts (varies by engine and instance class). Check your instance specifications or delete unused accounts.

Q: How do I find out which databases an account has access to?
A: Call `DescribeAccounts` with the `AccountName` parameter. The response includes `DatabasePrivileges` listing all accessible databases and their permission levels.

Q: Are locked accounts automatically unlocked after some time?
A: No. Locked accounts (via `LockAccount`) remain locked until explicitly unlocked using `UnlockAccount`.

Q: Can I grant permissions to multiple databases in one call?
A: Yes. For `GrantAccountPrivilege` and `RevokeAccountPrivilege`, provide a comma-separated list in the `DBName` parameter (e.g., `db1,db2,db3`).

## Pricing & Billing

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

### Price Reference

| Tier | Input Price | Output Price |
|------|-------------|--------------|
| CreateAccount | 0.001 / | — |
| ModifyAccountDescription | 0.001 / | 0.001 / |
| DescribeInstanceKeywords | 0.0001 / | 0.0001 / |
| ResetAccount (privileged) | 0.0001 / | 0.0001 / |
| LockAccount / UnlockAccount | 0.001 / | 0.001 / |
| RevokeAccountPrivilege | 0.001 / | 0.001 / |

### Free Tier
- `ModifyAccountDescription`, `DescribeInstanceKeywords`, `ResetAccount`: **1000 free calls/month**
- `LockAccount`, `UnlockAccount`: **100 free calls/month**
- `Revoke permissions from service account`: No free tier

### Usage Limits
- General account operations: **100 QPS per Alibaba Cloud account**
- Service account operations: **10 requests per second**

### Billing Notes
- Each API call counts as one billable request, even if it fails due to client error (4xx)
- Free tier quotas reset monthly on the first day
- Pricing is in Chinese Yuan (CNY); subject to change without notice