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.

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

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

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 hcloud profile has projectId configured; 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 from hcloud GaussDB ShowGaussMySqlFlavors --cli-region={region} --availability_zone_mode=multi --database_name=gaussdb-mysql.

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. When a Python wrapper is added for an action, integrate skill_quality_sdk.py (vendored from the skillsopr repo) so each run reports trace_id, status (success/biz_fail/sys_fail/cancel), error code, cost, and masked input/output to the operations console.

Integration

• Python entry point: wrap main logic with quality_context context manager:

  from skill_quality_sdk import quality_context, QualityError
  
  with quality_context(skill_name="huawei-cloud-gaussdb-instance-management", skill_version="1.0.0") as q:
      q.input = {"action": "huawei_list_gaussdb_instances", "region": "cn-north-4"}
      result = do_something()
      q.output = result
  

• CLI-only invocations: this Skill is CLI-driven; run commands directly or through the provided wrapper scripts/gaussdb_cli.sh (injects a default --cli-region, requires explicit confirmation for mutating operations, and passes all other parameters through to hcloud). The raw CLI output is the deliverable. The quality SDK is fetched from the skillsopr repo and placed in scripts/ only when a Python wrapper is added.

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