Configuration

hwc-dws-cli uses a three-layer configuration architecture. All files reside in ~/.hwc-dws-cli/.

Config Directory Layout

File	Format	Description
`~/.hwc-dws-cli/config.yaml`	YAML	Main configuration: global, regions, clusters. AK plaintext, SK/proxy/conn encrypted.
`~/.hwc-dws-cli/crypto.json`	JSON	Cryptographic component backup: machine fingerprint, PBKDF2 salt, AES-256-GCM metadata.
`~/.hwc-dws-cli/store.db`	JSON KV	CLI state store: active cluster name, active region, session metadata.
`<effective_dir>/semantic.db`	SQLite	Semantic metadata database. Effective dir = `{base}/{cluster_marker}/{database}/` (base = project_path or CWD). Default db_name is "default" (i.e. `{base}/{cluster_marker}/default/semantic.db`). Table profiles, column stats, join inference.
`~/.hwc-dws-cli/regionlist.md`	Markdown	Cached region display names (Chinese) from `GET /v3/regions` API.

keystore.json / kmk.key — Legacy Migration Only

keystore.json and kmk.key are retained only for legacy Go-format migration. New configurations use crypto.py with machine fingerprint + PBKDF2 + AES-256-GCM. GoKeyStore in infra/keystore.py handles migration of old encrypted credentials. The crypter for new configs is stored directly in config.yaml under encrypt.crypter, with crypto.json as backup.

Three-Layer Config Structure

# config.yaml — Three-layer structure
global:
  output_format: json          # Default output format
  permissions:                # Global permissions (shared across all clusters)
    allow_ddl: false
    allow_dml: false
    cost_limit: 10000
  encrypt:
    crypter: "base64..."      # AES-256-GCM encrypted master key material

regions:
  cn-north-4:
    name: "华北-北京四"
    endpoint: dws.cn-north-4.myhuaweicloud.com
    clusters:
      - my-cluster-1
      - my-cluster-2
  cn-east-3:
    name: "华东-上海一"
    endpoint: dws.cn-east-3.myhuaweicloud.com
    clusters:
      - prod-cluster

clusters:
  my-cluster-1:
    region: cn-north-4
    cluster_id: "xxx-xxx-xxx"
    endpoint: "192.168.1.100:25308"
    database: gaussdb
    username: dbadmin
    password: "enc:base64..."    # AES-256-GCM encrypted
    driver: psycopg2              # psycopg2 (default) | pyodbc (reference only)
    deploy_type: HC               # HC | HCS | ESL

active:
  region: cn-north-4             # Active region key (string)
  connections: my-cluster-1     # Active connection name key (string, NOT dict)

Encryption Architecture

The security encryption module (infra/crypto.py) uses a single master key approach:

Machine Fingerprint: SHA256 hash of environment variables (USERNAME, COMPUTERNAME, USERDOMAIN, HOME, USER)
Key Derivation: PBKDF2-HMAC-SHA256, 100,000 iterations, 32-byte key
Encryption: AES-256-GCM with random 96-bit nonce per encryption
Encrypted Fields: sk (Secret Key), proxy password, connection.password
Plaintext Fields: ak (Access Key ID — used only for request signing, not stored server-side)
Backup: crypto.json stores crypt_component (3 Shamir-like key shards) for DEK recovery

# crypto.json structure (backup)
{
  "createTime": "2026-09-16T12:00:00Z",
  "cryptComponent": "base64_shard0;base64_shard1;base64_shard2"
}

Config Commands

# Guided setup wizard (8 steps)
hwc-dws-cli config set

# Display current config (sensitive fields masked)
hwc-dws-cli config show

# Switch active cluster
hwc-dws-cli config switch-cluster use <cluster>

# Switch active region
hwc-dws-cli config switch-region <region>

Active Connection is a Key String

active.connections stores a connection name key (string), not a dict or reference. It is resolved from regions at runtime. A single Active profile is used for ALL DWS SQL — no fallback, hard error on connection failure.

Validation Rules (Library Only)

The infra/validate.py module defines validation rules, but it is a library module only — there is no config validate CLI command. Validation is invoked internally by config set:

V001, V002, V003: Region/port validation (deploy type, region format, port range). V002 (database set without host) is gated by active.cluster_id: a cluster-only config (cluster_id set, no DB connection) is valid API-only usage and does not report V002.
V013, V014: ProcessAuth validation (command whitelist, token config)
V018: Deploy type validation (HC/HCS/ESL)

Cluster-only Config (API-only)

active may contain only region/cluster_id/cluster_name with no DB connections. This cluster-only shape supports API commands (cluster/api/tune/audit + ops Autopilot API subcommands). DB commands (sql/data/meta/ops SQL) report INTERNAL.ERROR ("No database provider configured"). In config set, answer s at Step 5 to skip the DB Connection group (Steps 5-7 cascade).

store.db Format

store.db is a JSON key-value store (NOT SQLite). Go-compatibility required:

{
  "active_region": "cn-north-4",
  "active_cluster": "my-cluster-1",
  "last_query_time": "2026-09-16T10:30:00Z",
  "session_count": 42
}

semantic.db Format

The semantic database IS SQLite. It is stored at the semantic effective directory {base}/{cluster_marker}/{database}/semantic.db (base = project_path or CWD, database defaults to "default"). Stores 8-stage pipeline output:

Table profiles (row count, size, distribution)
Column statistics (NDV, null ratio, min/max, histogram)
Join inference results (foreign key candidates)
Schema hashes for incremental build detection
UDF discovery results