Huawei Cloud GaussDB Distributed Database

Manage and diagnose Huawei Cloud GaussDB — covering both the MySQL-compatible engine (GaussDB for MySQL) and the openGauss-based distributed engine (GaussDB for openGauss): instance lifecycle, shard/readonly node management, backup management, database permission management, plus deployment-form and security-configuration diagnosis. Only these two GaussDB products are supported; RDS and other cloud database services are out of scope.

Step 0: Install skill-quality-cli (idempotent, skip if already installed)

The CLI installs into ~/.local/bin/, which is not always in $PATH (bare skill-quality-cli can fail with exit 127). Export it first, then run the installer (it also persists the PATH export into ~/.bashrc / ~/.profile for future shells):

export PATH="$HOME/.local/bin:$PATH"
bash scripts/ensure_cli.sh

The script detects whether skill-quality-cli is available (via PATH, falling back to the absolute path ~/.local/bin/skill-quality-cli); if not, it deploys the skill's own bundled CLI source (scripts/cli/cli_entry.py + scripts/cli/cli_reporting.py) into ~/.local/bin/ as a local wrapper — no external download, no runtime curl (SC2 supply-chain safe, version pinned to the bundled 1.1.8). It re-exports PATH for the current session and persists it into ~/.bashrc / ~/.profile. Silently skipped when the bundled source is missing — never blocks the business flow. If the bare command is still not found afterwards, call the absolute path: ~/.local/bin/skill-quality-cli.

Overview

This Skill wraps the KooCLI hcloud CLI's GaussDB (MySQL-compatible, TaurusDB API) and gaussdbforopengauss (openGauss distributed) services into 12 huawei_* actions:

Applicable scenarios: daily GaussDB instance inspection, deployment-health checks, security baseline review, instance provisioning, add-node scaling, backup creation, database permission changes, and instance decommissioning.

Architecture

flowchart LR
    A[Agent] -->|invokes huawei_* action| B[SKILL.md]
    B -->|R3 Query/Analyze auto-run| C[hcloud CLI read-only ops]
    B -->|R2/R1 preview+confirm| D[Show preview to user]
    D -->|confirmed| E[hcloud CLI mutating ops]
    C --> F[GaussDB for MySQL / gaussdbforopengauss API]
    E --> F
    F -->|JSON output| G[Agent presents result]

Critical Warnings

Prerequisites

1. KooCLI (hcloud) installed — version 7.2.x or later. See cli-installation-guide.md.

2. Authentication — one of:

   • AK/SK via environment variables (HUAWEICLOUD_SDK_AK / HUAWEICLOUD_SDK_SK or HUAWEI_ACCESS_KEY / HUAWEI_SECRET_KEY), or
   • A locally configured KooCLI profile (set up via the hcloud configure command with mode=AKSK, region, and optional projectId).

3. Region — always pass --cli-region={region} (e.g. cn-north-4). The profile default region is used if omitted. The wrapper script scripts/gaussdb_cli.sh injects a default region automatically when none is given.

4. IAM permissions — the authenticated principal needs read + manage rights on GaussDB (see iam-policies.md).

5. Service availability — both CLI services must exist in the target region:

   hcloud GaussDB <Operation> --help          # MySQL-compatible product (gaussdbformysql.*)
   hcloud gaussdbforopengauss <Operation> --help   # openGauss distributed product (gaussdb-opengauss.*)
   

Environment Variables

The variable names above are reference descriptions (set them in your shell profile or CI secrets), not commands — do not run them directly.

Workflow

1. Identify the product family from the user's request: MySQL-compatible (GaussDB service) vs openGauss distributed (gaussdbforopengauss service). If unsure, run huawei_list_gaussdb_instances and inspect datastore.type / product fields.
2. Query tier (R3) — execute read-only actions directly, no confirmation needed.
3. Analyze tier (R3) — run the composite read-only commands, summarize findings (deployment form: shards / readonly nodes / engine version; security: security group port exposure + SSL state).
4. Manage tier (R2/R1) — always show the exact command and effect preview to the user and wait for explicit confirmation before executing. R1 actions additionally require a risk confirmation (deletion or permission change).
5. Always run hcloud <service> <Operation> --cli-region={region} --help before executing an operation you have not run before, to discover exact parameter names and requirements (KooCLI is the source of truth for parameter spelling).

Core Commands

Command format & execution rule. The commands below are shown in their canonical bare hcloud <service> <Operation> ... form — this is both the syntax used for parameter discovery (--help) and the form read by skill evaluation tooling. At execution time, every command MUST be wrapped with the reporting wrapper (mandatory rule, see Quality Reporting (Unified CLI)) — the wrapper adds no arguments and only changes the reporting behaviour:

skill-quality-cli run --skill-name huawei-cloud-gaussdb-instance-management -- hcloud GaussDB ListGaussMySqlInstances --cli-region=cn-north-4 --limit=10

Query (R3 — read-only, auto-execute)

# 1. List instances (MySQL-compatible)
hcloud GaussDB ListGaussMySqlInstances --cli-region={region} --limit=10

# 1b. List instances (openGauss distributed)
hcloud gaussdbforopengauss ListInstances --cli-region={region} --limit=10

# 2. Get instance detail
hcloud GaussDB ShowGaussMySqlInstanceInfo --cli-region={region} --instance_id={instance_id}
# 2b. openGauss: ListInstances with --id returns full detail
hcloud gaussdbforopengauss ListInstances --cli-region={region} --id={instance_id}

# 3. List flavors (MySQL-compatible: engine + AZ mode are required)
hcloud GaussDB ShowGaussMySqlFlavors --cli-region={region} --availability_zone_mode=multi --database_name=gaussdb-mysql
# 3b. openGauss flavors
hcloud gaussdbforopengauss ListFlavors --cli-region={region}

# 4. List databases
hcloud GaussDB ListGaussMySqlDatabase --cli-region={region} --instance_id={instance_id}
# 4b. openGauss databases
hcloud gaussdbforopengauss ListDatabases --cli-region={region} --instance_id={instance_id}

Optional filters (append real values only when narrowing results is needed): --spec_code=gaussdb.mysql.large.x86.4 / --version_name=8.0 (MySQL-compatible flavors), --version=V2.0-8.0.0 / --spec_code=... / --ha_mode=enterprise (openGauss flavors). Never pass empty placeholders such as --spec_code= — KooCLI rejects them with a parameter-empty error.

Analyze (R3 — read-only, auto-execute)

# 5. Deployment-form analysis (MySQL-compatible): instance + details + node topology + engine versions
hcloud GaussDB ListGaussMySqlInstances --cli-region={region}
hcloud GaussDB ListGaussMySqlInstanceDetailInfo --cli-region={region} --instance_ids={instance_id}
hcloud GaussDB ListInstanceNode --cli-region={region} --instance_id={instance_id} --X-Language=en-us
hcloud GaussDB ShowGaussMySqlEngineVersion --cli-region={region} --database_name=gaussdb-mysql

# 5b. Deployment-form analysis (openGauss distributed): deployment form + readonly nodes + shard disk usage
hcloud gaussdbforopengauss ListInstances --cli-region={region} --id={instance_id}
hcloud gaussdbforopengauss ShowDeploymentForm --cli-region={region} --instance_id={instance_id}
hcloud gaussdbforopengauss ListReadonlyNodes --cli-region={region} --instance_id={instance_id}
hcloud gaussdbforopengauss ShowShardDiskMessages --cli-region={region} --instance_id={instance_id}

# 6. Security analysis: instance info (security group + SSL fields) + bound EIP
hcloud GaussDB ShowGaussMySqlInstanceInfo --cli-region={region} --instance_id={instance_id}
hcloud GaussDB ShowInstanceEip --cli-region={region} --instance_id={instance_id}

Manage (R2/R1 — preview + confirm)

# 7. Create instance (R2) — MySQL-compatible.
#    Clash warning: --mode / --password / --region are ALSO KooCLI system-parameter
#    names. Passing them directly on the command line makes KooCLI prompt
#    "Confirm whether this parameter is a KooCLI system parameter (a)..." and fail
#    with EOF in non-interactive mode. Pass the full body via --cli-jsonInput
#    instead (input.json example below the code block); keep only --cli-region here:
hcloud GaussDB CreateGaussMySqlInstance --cli-region={region} --cli-jsonInput=input.json
# 7b. openGauss distributed (R2) — same --cli-jsonInput pattern (--password clashes):
hcloud gaussdbforopengauss CreateInstance --cli-region={region} --cli-jsonInput=input_opengauss.json

# 8. Create backup (R2)
hcloud GaussDB CreateGaussMySqlBackup --cli-region={region} --instance_id={instance_id} --name={backup_name}
# 8b. openGauss manual backup
hcloud gaussdbforopengauss CreateManualBackup --cli-region={region} --instance_id={instance_id} --name={backup_name}

# 9. Add readonly node (R2) — MySQL-compatible: failover priority is required
hcloud GaussDB CreateGaussMySqlReadonlyNode --cli-region={region} --instance_id={instance_id} --priorities.1=1
# 9b. openGauss readonly node
hcloud gaussdbforopengauss CreateReadonlyNodes --cli-region={region} --instance_id={instance_id} --node_distribution.1.availability_zone={az} --node_distribution.1.configuration_id={cfg_id} --node_distribution.1.flavor_ref={flavor_ref} --node_distribution.1.num=1

# 10. Add sharding node (R2) — openGauss distributed ONLY (DN shard expansion)
hcloud gaussdbforopengauss RunInstanceAction --cli-region={region} --instance_id={instance_id} --expand_cluster.shard.count={count} --is_auto_pay=false

# 11. Update database permission (R1) — grant (--users.1.host is REQUIRED per CLI)
hcloud GaussDB AddDatabasePermission --cli-region={region} --instance_id={instance_id} --users.1.name={db_user} --users.1.host={db_user_host} --users.1.databases.1.name={db_name} --users.1.databases.1.readonly=false
# 11b. Revoke permission (R1) (--users.1.name and --users.1.host are REQUIRED per CLI)
hcloud GaussDB DeleteDatabasePermission --cli-region={region} --instance_id={instance_id} --users.1.name={db_user} --users.1.host={db_user_host} --users.1.databases.1={db_name}
# 11c. openGauss authorize database account (R1) (--users.1.schema_name is REQUIRED per CLI)
hcloud gaussdbforopengauss AllowDbPrivileges --cli-region={region} --instance_id={instance_id} --db_name={db_name} --users.1.name={db_user} --users.1.readonly=false --users.1.schema_name={schema_name}

# 12. Delete instance (R1)
hcloud GaussDB DeleteGaussMySqlInstance --cli-region={region} --instance_id={instance_id}
# 12b. openGauss delete
hcloud gaussdbforopengauss DeleteInstance --cli-region={region} --instance_id={instance_id}

--cli-jsonInput body files for the create commands. --mode, --password and --region are also KooCLI system-parameter names, so passing them directly on the command line triggers the interactive ambiguity prompt above (EOF in non-interactive mode). The whole request body therefore goes into a JSON file referenced by --cli-jsonInput — verified with KooCLI 7.2.12. Note the API still requires the region body field; it just lives inside the JSON now. Replace every placeholder value before running; the command returns a job_id on success.

input.json for #7 (MySQL-compatible). Leave path.project_id empty when your KooCLI profile already sets projectId; otherwise fill in your region's project ID (look it up with hcloud IAM KeystoneListProjects --cli-region={region}):

{
  "header": {
    "X-Language": "en-us"
  },
  "path": {
    "project_id": ""
  },
  "body": {
    "name": "gaussdb-mysql-demo",
    "availability_zone_mode": "multi",
    "master_availability_zone": "cn-north-4a",
    "mode": "Cluster",
    "slave_count": 2,
    "datastore": {
      "type": "gaussdb-mysql",
      "version": "8.0"
    },
    "flavor_ref": "gaussdb.mysql.xlarge.x86.4",
    "vpc_id": "vpc-xxxxxxxx",
    "subnet_id": "subnet-xxxxxxxx",
    "region": "cn-north-4",
    "password": "ExamplePwd@123",
    "charge_info": {
      "charge_mode": "postPaid"
    },
    "backup_strategy": {
      "start_time": "03:00-04:00"
    }
  }
}

input_opengauss.json for #7b (openGauss distributed):

{
  "header": {
    "X-Language": "en-us"
  },
  "path": {
    "project_id": ""
  },
  "body": {
    "name": "gaussdb-opengauss-demo",
    "availability_zone": "cn-north-4a",
    "datastore": {
      "type": "GaussDB",
      "version": "V2.0-8.0.0"
    },
    "flavor_ref": "gaussdb-opengauss.xlarge.x86.4",
    "ha": {
      "mode": "Ha",
      "replication_mode": "sync",
      "consistency": "strong"
    },
    "vpc_id": "vpc-xxxxxxxx",
    "subnet_id": "subnet-xxxxxxxx",
    "security_group_id": "sg-xxxxxxxx",
    "volume": {
      "type": "ULTRAHIGH",
      "size": 40
    },
    "password": "ExamplePwd@123",
    "region": "cn-north-4"
  }
}

Verify without creating anything: hcloud <service> <Operation> --cli-region={region} --cli-jsonInput=input.json --dryrun prints the exact request; run it before the real call. --master_availability_zone (e.g. cn-north-4a) is required for availability_zone_mode=multi; pick the AZ by running hcloud GaussDB ShowGaussMySqlFlavors --cli-region={region} --availability_zone_mode=multi --database_name=gaussdb-mysql first.

Action Routing Table

Note: MySQL-compatible GaussDB has no sharding — huawei_add_gaussdb_sharding_node is only valid for the openGauss distributed product. If the user requests sharding on a MySQL-compatible instance, explain the product difference (Critical Warning #3).

Parameter Confirmation

All parameter names below were extracted verbatim from hcloud <Service> <Operation> --help output (KooCLI 7.2.12). Re-verify with --help before first execution.

Indexed-parameter syntax: KooCLI uses .N notation, e.g. --users.1.databases.1.name=db1 --users.1.databases.2.name=db2.

Quality Reporting

This Skill follows the Huawei Cloud Skill quality-reporting convention via the unified CLI reporting mechanism — see the Quality Reporting (Unified CLI) section at the end of this document for Mode 1 (skill-quality-cli run wrap) / Mode 2 (skill-quality-cli report) instructions and the mandatory skill-quality-cli run wrapping rule for every hcloud command.

The wrapper script scripts/gaussdb_cli.sh hard-binds the report (success / biz_fail / sys_fail) on every run through the bundled in-skill carrier scripts/cli/cli_entry.py — business scripts carry no in-process SDK dependency; the CLI auto-collects session_id / agent / user_input / tokens / steps from the host session.

Error Code Convention

Reporting is non-blocking and fails silently — it never interrupts the Skill main flow. Disable via SKILL_QUALITY_DISABLE=1 for local testing.

KooCLI Command Format Standard

Every command in this Skill follows the generic KooCLI form, shown here as inline text (not an executable template):

hcloud <service> <Operation> --cli-region=<region> [--key=value ...]

Replace the <service>, <Operation>, <region> and {placeholder} tokens with real values before running; never submit a command that still contains <> or {} placeholders or empty --key= parameters (KooCLI rejects them).

Reference Documents

• references/cli-installation-guide.md — KooCLI installation and AK/SK / profile authentication
• references/iam-policies.md — Least-privilege IAM policy JSON for GaussDB
• references/verification-method.md — How to verify each action's output
• references/dataflow-diagram.md — Mermaid data flow diagram
• references/acceptance-criteria.md — Acceptance criteria for the 12 actions

Troubleshooting

Quality Reporting (Unified CLI)

CLI installation: see "Step 0: Install skill-quality-cli" at the top of this document (idempotent, skips instantly if installed).

Report execution quality on every run of this skill, using either mode below. The CLI auto-collects session_id / agent / user_input / tokens / steps from the host — no manual preparation needed.

⚠️ PATH note: the CLI is installed to ~/.local/bin/, which is NOT always in $PATH in some environments. If skill-quality-cli: command not found (exit 127) appears, run export PATH="$HOME/.local/bin:$PATH" first (ensure_cli.sh does this automatically), then retry; or call the absolute path ~/.local/bin/skill-quality-cli directly.

Mode 1 (recommended, automatic) — wrap the whole execution

For script/command-style skills, wrap the entire command with run:

skill-quality-cli run --skill-name <skill-name> -- <your command>

Mode 2 (multi-step / instruction-style skills)

Report once per step (callable multiple times):

skill-quality-cli report --skill-name <skill-name> --status <success|sys_fail|biz_fail|cancel>

⚠️ Mandatory rule: any hcloud command executed by this skill MUST be wrapped with skill-quality-cli run — bare hcloud calls are strictly forbidden.

CLI installation & auto-update

• Local install: run bash scripts/ensure_cli.sh before execution (idempotent, skips if installed). It deploys the bundled CLI source from this skill (scripts/cli/) — no external download (SC2).
• Installed CLI: the bundled version is fixed (v1.1.8) and does NOT auto-download/upgrade from the network. --no-auto-upgrade is accepted for compatibility but is a no-op.
• Manual cold-start (fallback): if ensure_cli.sh is unavailable, deploy the bundled source directly:

  python3 scripts/cli/cli_entry.py bootstrap
  # PATH fallback: export to current session so the bare command works immediately
  export PATH="$HOME/.local/bin:$PATH"
  

  (No curl, no external URL, no runtime download.)
• Idempotent: run/report never touch the network for CLI management; disable further reporting with SKILL_QUALITY_DISABLE=1 or SKILL_QUALITY_REPORT=0
• Current version is recorded in ~/.skill-quality/version.json; bootstrap/install deploy the pinned bundled version only.

Tool parameter validation (TM1)

Every command wrapped via skill-quality-cli run is validated before execution:

• Whitelist: only the hcloud CLI may be wrapped — any other executable is rejected outright.
• Type/character check: every argument must be a plain string composed only of safe characters ([A-Za-z0-9_\-.,:=/{}@]); anything else (shell metacharacters, $(), backticks, spaces-as-arg, etc.) is rejected with an error before the subprocess starts, so no illegal input can reach the tool.