PolarDB-X Instance Management

Manage Alibaba Cloud PolarDB-X instances through the aliyun polardbx CLI: instance lifecycle, scaling, parameter management, monitoring, and logs.

This skill uses intent routing: identify the user's intent, run pre-flight checks, then load the relevant module reference document fully before generating any CLI command.

Architecture

Alibaba Cloud PolarDB-X Instance Management
├── Instance Lifecycle    --> references/instance-lifecycle.md
│   ├── CreateDBInstance
│   ├── DeleteDBInstance
│   ├── RestartDBInstance
│   ├── DescribeDBInstanceAttribute
│   ├── DescribeDBInstances
│   ├── DescribeDBInstanceTopology
│   ├── DescribeTasks
│   ├── ModifyDBInstanceDescription
│   ├── ModifyDBInstanceMaintainTime
│   └── UpgradeDBInstanceKernelVersion
├── Scaling               --> references/scaling.md
│   ├── UpdatePolarDBXInstanceNode
│   ├── ModifyDBInstanceClass
│   └── DescribeScaleOutMigrateTaskList
├── Parameters            --> references/parameters.md
│   ├── DescribeDBInstanceConfig
│   ├── ModifyDBInstanceConfig
│   ├── DescribeParameters
│   ├── ModifyParameter
│   └── DescribeParameterTemplates
├── Instance Specs        --> scripts/spec_lookup.sh (spec code <-> cores/memory)
│   ├── Enterprise CN (CnClass)
│   ├── Enterprise DN (DnClass)
│   ├── Standard DBNodeClass
│   └── Naming Rules
└── Monitoring & Logs     --> references/monitoring-logs.md
    ├── DescribeDBNodePerformance
    ├── DescribeSlowLogRecords
    └── DescribeBinaryLogList

Extended Modules

The following modules cover the full PolarDB-X (2020-02-02) API surface. See each reference file for the complete API spec.

├── Account Management      --> references/account-management.md
├── Database Management     --> references/database-management.md
├── Backup & Restore        --> references/backup-restore.md
├── Security & Access        --> references/security-access.md
├── SQL Audit & Compliance   --> references/sql-audit-compliance.md
├── Operation Tasks & Events --> references/operation-tasks.md
├── HA & Migration           --> references/ha-migration.md
├── Connection & Endpoint    --> references/connection-endpoint.md
├── Tags & Resource Group    --> references/tags-resourcegroup.md
├── Metadata & Query         --> references/metadata-query.md
├── Cold Storage             --> references/cold-storage.md
├── Data Import              --> references/data-import.md
├── Data Evaluate & Migration--> references/data-evaluate-migration.md
├── SQL Flashback            --> references/sql-flashback.md
├── CDC (Log Engine)         --> references/cdc.md
├── Columnar                 --> references/columnar.md
├── GDN                      --> references/gdn.md
└── Mem0                     --> references/mem0.md

Requirement Analysis

Before routing, analyze the user request:

1. Identify intent: create / delete / restart / describe / list / scale / modify parameters / view monitoring / view logs.
2. Extract required parameters: RegionId, instance identifier (DBInstanceName or DBInstanceId), EngineVersion, DBInstanceClass, node counts, time ranges, etc.
3. Determine whether the operation is destructive or mutating. If it falls into any high-risk category, you MUST complete the Mandatory Secondary Confirmation gate below before proceeding.
4. If any required parameter is missing, ask the user. Do NOT guess values or APIs.
5. After intent and parameters are clear, load the matched reference document fully, then construct the CLI command.

Mandatory Secondary Confirmation (High-risk Operations)

[MUST] Every operation category listed below REQUIRES explicit secondary confirmation from the user before ANY CLI command is executed. This is a hard gate — never skip it, never assume approval, and never proceed on a single implicit instruction. In particular, any operation that creates, attaches, or scales billable resources (e.g. instances, cold-data storage volumes, GDN instances / standby members, columnar / Mem0 / sub-CN resources) WILL incur or change fees and MUST be confirmed. Deleting an instance (DeleteDBInstance, DeleteGdnInstance) ALWAYS requires secondary confirmation as well — even though it is not a billing operation — because it permanently and irreversibly destroys the instance and its data.

Confirmation procedure

1. After all required parameters are collected and the target command is constructed, STOP and present a summary to the user containing:
   • The exact operation and target instance (RegionId + DBInstanceName/DBInstanceId).
   • For create / attach / scale / cost-changing operations (including cold-data storage volumes, GDN, columnar, Mem0, sub-CN): the full spec change (before → after), PayType, and an explicit note that this operation will incur or change billing.
   • For delete: an explicit warning that the instance and its data will be permanently removed and cannot be recovered.
2. Explicitly ask the user to confirm (e.g. "Please reply confirm to proceed").
3. Only execute the command after the user gives an unambiguous affirmative reply. Any ambiguous, negative, or empty response means do NOT execute — ask again or abort.
4. If the user changes any parameter after confirmation, re-run this gate with the updated summary.

This gate applies even when the user's original request already sounds like a direct command (e.g. "delete pxc-xxx"). A single instruction is NOT sufficient authorization for any of these categories.

Pre-flight Checks

Run these checks at the start of every skill invocation. Only load the referenced document if a check fails. If step 1/2/3/5 fails, read references/cli-installation-guide.md; if step 4 fails, read references/ram-policies.md.

1. aliyun CLI version

aliyun --version

Success: Output contains Alibaba Cloud Command Line Interface Version and the version is >= 3.3.3.

Failure: Read references/cli-installation-guide.md section 1.

2. aliyun CLI plugin and configuration

aliyun configure set --auto-plugin-install true
aliyun plugin update
aliyun configure list

Success: aliyun configure list shows at least one valid profile (AK, STS, or OAuth identity).

Failure: Read references/cli-installation-guide.md sections 2 and 3.

3. Caller identity

aliyun sts get-caller-identity

Success: Returns JSON with AccountId, UserId, and Arn.

Failure: Read references/cli-installation-guide.md section 4.

4. RAM permissions

aliyun polardbx describe-db-instances --biz-region-id <RegionId> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-polardbx-ops/{session-id}

Success: Returns an instance list or empty list without permission errors.

Failure: Read references/ram-policies.md.

5. jq availability

jq --version

Success: Output contains a version string such as jq-1.7.1.

Failure: Read references/cli-installation-guide.md section 5.

Observability (MUST follow for every aliyun command)

Upon loading this skill, generate a random session ID (32-char lowercase hex string) once for the entire session. Use it as {session-id} below.

Rule: Every aliyun CLI command that calls a cloud API MUST include the --user-agent flag. Local utility commands (e.g. configure, plugin, version) do not support this flag and should be excluded.

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-polardbx-ops/{session-id}

Example (assuming session-id is a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6):

aliyun polardbx describe-db-instances --biz-region-id cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-polardbx-ops/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Do not skip, alter the format, or omit --user-agent on any aliyun API command invocation.

Script / Terraform execution: When running Python SDK scripts or Terraform commands or bash scripts, inject the session-id via inline environment variable so the code can read it at runtime:

# Python SDK script
SKILL_SESSION_ID={session-id} python3 scripts/deploy.py

# Terraform
SKILL_SESSION_ID={session-id} terraform apply

Scripts and Terraform configs should read SKILL_SESSION_ID from the environment (default to empty string if absent).

Intent Routing

Match the user request to the first matching row, then load the listed reference file and follow its API spec.

If multiple intents are present, handle them sequentially: route -> execute -> verify -> next route. If the intent does not match any row, ask the user to clarify; do NOT guess an API.

Global Conventions

These conventions apply to every aliyun polardbx CLI command produced by this skill.

Command format

aliyun polardbx <action-name> --biz-region-id <RegionId> [other parameters]

• The aliyun CLI returns JSON by default. Do NOT add --output unless the user explicitly asks for table format.
• Read operations append --connect-timeout 3 --read-timeout 10.
• Write operations append --connect-timeout 3 --read-timeout 30 --client-token <token>.

Command style: plugin mode

This skill uses the aliyun CLI plugin mode for PolarDB-X:

• All action names are lowercase words connected with hyphens (describe-db-instances).
• All parameter flags are kebab-case (--db-instance-name, --client-token).
• Do NOT mix plugin mode with the legacy PascalCase API style within a single command.
• If a parameter is rejected, fall back to aliyun polardbx <action-name> --help to verify the exact parameter name.

CN spec naming

PolarDB-X CN node specs follow the pattern polarx.xN.<size>.<suffix>. The <size> field determines the core multiplier:

• large is NOT a small size; it is the base (1x) multiplier.
• xlarge doubles the core count and memory.
• When the user says "4-core 16G", select large; do NOT select xlarge.
• For full spec list, run aliyun polardbx create-db-instance --help.

Output parsing

• Pipe the default JSON output to jq and extract only the fields the user needs.
• Avoid dumping large raw JSON blocks; prefer concise jq filters.
• Example:

aliyun polardbx describe-db-instances \
  --biz-region-id cn-hangzhou \
  --connect-timeout 3 --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-polardbx-ops/{session-id} \
  | jq '.DBInstances[] | {DBInstanceName, Status, Description}'

Table output

If the user explicitly requests table format, use --output with cols and rows:

aliyun polardbx describe-db-instances \
  --biz-region-id cn-hangzhou \
  --output cols=DBInstanceName,Status,Description,rows=DBInstances \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-polardbx-ops/{session-id}

In zsh, quote the --output value to prevent glob expansion: --output 'cols=DBInstanceName,Status,Description,rows=DBInstances'.

Required user input

• RegionId: MUST be explicitly provided by the user. NEVER guess. NEVER use a default region.
• Instance identifier: DBInstanceName or DBInstanceId depending on the API. MUST be explicitly provided.

Idempotency

For write APIs (CreateDBInstance, RestartDBInstance, UpdatePolarDBXInstanceNode, ModifyDBInstanceClass, ModifyDBInstanceMaintainTime, ModifyDBInstanceConfig, ModifyParameter, UpgradeDBInstanceKernelVersion), use --client-token.

DeleteDBInstance does NOT support --client-token; do not append it.

CLIENT_TOKEN=$(uuidgen)   # reuse on retry

On timeout / failure, retry with the same ClientToken.

Pagination

For all paginated read operations (DescribeDBInstances, DescribeTasks, DescribeSlowLogRecords, DescribeBinaryLogList, etc.), use --page-size 100 unless the user explicitly requests a different size.

• PolarDB-X APIs typically enforce a maximum PageSize of 100.
• Use --page-number to iterate through pages when more than 100 results exist.

Security constraints

• NEVER expose the instance to the public internet.
• NEVER recommend AllocateInstancePublicConnection or any public-network command.
• NEVER ask users to provide AK/SK directly in the conversation.
• NEVER echo credential values.

Error & Timeout Handling

When a CLI command fails, handle it according to the following rules.

Network timeout / connect-timeout / read-timeout

• Retry up to 3 times with exponential backoff: 5s / 10s / 20s.
• For idempotent write operations, reuse the same --client-token on retry.
• If all retries fail, prompt the user to check local network and Region availability.

API business errors (Code/Message)

Asynchronous tasks

For operations that return a TaskId or order ID (create / delete / restart / scale / upgrade / class change):

1. Poll task status with DescribeTasks.
2. Poll interval: 10 seconds.
3. Timeout: 30 minutes (configurable).
4. On task failure, output TaskErrorCode and TaskErrorMessage.

Preferred: Use the bundled polling script:

./scripts/poll_task.sh \
  --region <RegionId> \
  --instance-id <DBInstanceId> \
  --start-time <StartDate> \
  --end-time <EndDate> \
  --session-id {session-id}

Manual alternative:

aliyun polardbx describe-tasks \
  --biz-region-id <RegionId> \
  --db-instance-id <DBInstanceId> \
  --start-time <StartTime> \
  --end-time <EndTime> \
  --page-number 1 \
  --page-size 100 \
  --connect-timeout 3 --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-polardbx-ops/{session-id} \
  | jq '.Tasks[] | {TaskId, TaskStatus, TaskErrorCode, TaskErrorMessage}'

Unexpected output

• If the output is empty or fields are missing, first run the command without | jq ... to check whether the default JSON output is valid.
• If jq fails, verify the filter against the raw JSON output.
• Use --cli-query carefully; verify the JMESPath expression against the raw JSON output.
• All fields shown to the user SHOULD be extracted via jq filters.

Reference Links

Scripts

Runtime dependencies (bash >= 4.0, aliyun CLI >= 3.3.3, jq >= 1.6) are declared in each script's header comments. spec_lookup.sh only needs bash + awk (no CLI/jq).

Spec code <-> hardware lookup

To resolve a spec code to cores/memory, or to find spec codes for a target hardware size, call scripts/spec_lookup.sh:

# Spec code -> hardware
./scripts/spec_lookup.sh --code polarx.x4.large.2e

# Hardware -> matching spec code(s) (filter by module / disk / type as needed)
./scripts/spec_lookup.sh --cores 8 --memory 32 --category cn --disk local

# Machine-readable output for the agent
./scripts/spec_lookup.sh --code mysql.n4.medium.25 --json

• --category: cn (enterprise compute) / dn (enterprise storage) / standard.
• --disk: local (custom_local_ssd) / cloud (cloud_auto).
• --type: general / dedicated.
• Exit codes: 0 found, 3 invalid args, 4 no match.