Quickstart

5-minute guide to get started with hwc-dws-cli. Assumes you have completed installation.

1. Configure Connection (config set wizard)

Run the 8-step guided setup wizard. Each step supports list + manual + keep-current modes:

hwc-dws-cli config set

# Step 1: AK/SK — Enter Access Key ID and Secret Key
# Step 2: Proxy — Configure corporate proxy (optional)
# Step 3: Region — Select from API-fetched region list
# Step 4: Cluster — Select DWS cluster from API list
# Step 5: Endpoint — Auto-filled from API, manually editable (s=skip DB connection)
# Step 6: Credentials — Enter DB username and password
# Step 7: DB Connectivity Test — Verify database connection works
# Step 8: API Connectivity Test — Verify API access works
# Note: Steps 5-7 form the DB Connection group. Answer 's' at Step 5 to skip
# all DB connection config (API-only usage; cluster-only config saved).

Verify configuration:

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

2. Execute Your First SQL Query

Default output is JSON Envelope format:

hwc-dws-cli sql --exec "SELECT * FROM pg_tables LIMIT 3"
{
  "success": true,
  "data": {
    "columns": ["schemaname","tablename","tableowner","tablespace","hasindexes"],
    "rows": [...]
  }
}

Switch to table output (using --format at any position):

hwc-dws-cli sql --exec "SELECT * FROM pg_tables LIMIT 3" --format table

# Or at the beginning
hwc-dws-cli --format table sql --exec "SELECT * FROM pg_tables LIMIT 3"

DML/DDL requires explicit --write flag; DROP/TRUNCATE additionally requires --confirm-dangerous (SQL Guard protection):

hwc-dws-cli sql --exec "CREATE TABLE demo(id int, name text)" --write
hwc-dws-cli sql --exec "INSERT INTO demo VALUES (1,'alice')" --write
hwc-dws-cli sql --exec "DROP TABLE demo" --write --confirm-dangerous

EXPLAIN dry-run (does not execute the query):

hwc-dws-cli sql --exec "SELECT * FROM demo WHERE id=1" --dry-run
SQL Guard
PermissionGate classifies SQL: SELECT allowed by default; INSERT/UPDATE/DELETE require --write; DROP/TRUNCATE require --write + --confirm-dangerous. --dry-run outputs EXPLAIN VERBOSE without executing.

3. Query Metadata

# List all schemas
hwc-dws-cli meta list-schemas

# List tables in a schema
hwc-dws-cli meta list-tables --schema public

# Describe a table (full metadata)
hwc-dws-cli meta describe demo --schema public

4. List Clusters via API

API commands use HTTPS (HMAC-SHA256 signing), no DB driver needed:

# List all clusters in the configured region
hwc-dws-cli api GET /v1.0/{project_id}/clusters

# Show cluster details
hwc-dws-cli cluster show info --cluster-id xxx-xxx-xxx

# Show connection endpoints
hwc-dws-cli cluster show endpoints --cluster-id xxx

5. Semantic Metadata Build

Run the 8-stage semantic build pipeline for a schema:

# Build (first run scans all tables)
hwc-dws-cli meta semantic build --schema public

# Show build results for a specific table
hwc-dws-cli meta semantic show demo --schema public

Build artifacts stored in SQLite under the semantic effective directory ({project_path|CWD}/{cluster_marker}/{database}/semantic.db). Supports incremental builds via schema hash.

6. Operations and Monitoring

# Check connection status
hwc-dws-cli check-con

# Monitor active sessions
hwc-dws-cli ops session

# View workload queue
hwc-dws-cli ops queue

Next Steps