Skill: wenbingyu/hologres-cli (version 0.2.0)

--- name: hologres-cli description: | AI-agent-friendly Hologres CLI with safety guardrails and structured JSON output. Use for database operations, schema inspection, SQL execution, data import/export, Dynamic Table lifecycle management (V3.1+ syntax), and GUC parameter management. Triggers: "hologres cli", "hologres command", "hologres database", "dynamic table", "hologres查询", "hologres guc", "GUC parameter" --- # Hologres CLI AI-agent-friendly command-line interface for Hologres with safety guardrails and structured JSON output. ## Installation ```bash # Requires Python 3.11+ pip install hologres-cli # Or install a specific version pip install hologres-cli==0.2.0 ``` ## Configuration Profile-based configuration stored in `~/.hologres/config.json`. ```bash # Interactive setup wizard hologres config # Or set values directly hologres config set region_id cn-hangzhou hologres config set instance_id hgprecn-cn-xxx hologres config set database mydb ``` Profile resolution priority: `--profile <name>` flag > current profile > error (prompts to run `hologres config`). ## Quick Start ```bash pip install hologres-cli hologres config # Interactive setup hologres status # Check connection hologres schema tables # List tables hologres sql run "SELECT * FROM orders LIMIT 10" # Query data hologres --profile prod status # Use specific profile hologres dt list # List Dynamic Tables ``` ## Core Commands | Command | Description | |---------|-------------| | `hologres status` | Check connection status | | `hologres instance <name>` | Query instance version/connections | | `hologres warehouse [name]` | List or query warehouses | | `hologres schema tables` | List all tables | | `hologres schema describe <table>` | Show table structure | | `hologres schema dump <schema.table>` | Export DDL | | `hologres schema size <schema.table>` | Get table storage size | | `hologres table list [--schema S]` | List all tables | | `hologres table create -n TABLE -c COLS [options] [--dry-run]` | Create a table (supports logical partition V3.1+) | | `hologres table dump <schema.table>` | Export DDL for a table | | `hologres table show <table>` | Show table structure (columns, types, nullable, defaults, primary key, comments) | | `hologres table size <schema.table>` | Get table storage size | | `hologres table properties <table>` | Show Hologres-specific table properties (orientation, distribution_key, clustering_key, TTL, etc.) | | `hologres table drop <table> [--if-exists] [--cascade] --confirm` | Drop a table (dry-run by default) | | `hologres table truncate <table> --confirm` | Truncate (empty) a table (dry-run by default) | | `hologres table alter TABLE [options] [--dry-run]` | Alter table properties (add column, rename, TTL, etc.) | | `hologres partition list --table <table>` | List partitions of a logical partition table | | `hologres partition create --table <table>` | Create partition (no-op for logical tables, returns notice) | | `hologres partition drop --table <table> --partition VALUE --confirm` | Drop partition (deletes partition data) | | `hologres partition alter --table <table> --partition <value> --set <key=value> [--dry-run]` | Alter partition properties (keep_alive, storage_mode, generate_binlog) | | `hologres partition alter --table <table> --partition <value> --set <key=value> [--dry-run]` | Alter partition properties (keep_alive, storage_mode, generate_binlog) | | `hologres view list [--schema S]` | List all views | | `hologres view show <view>` | Show view definition and structure | | `hologres extension list` | List installed extensions | | `hologres extension create <name> [--if-not-exists]` | Create (install) a database extension | | `hologres guc show <param>` | Show current value of a GUC parameter | | `hologres guc set <param> <value>` | Set GUC parameter at database level (persistent) | | `hologres sql run "<query>"` | Execute read-only SQL | | `hologres sql run --write "<dml>"` | Execute write SQL | | `hologres sql explain "<query>"` | Show SQL execution plan | | `hologres data export <table> -f out.csv [-q <query>] [-d <delimiter>]` | Export to CSV | | `hologres data import <table> -f in.csv [-d <delimiter>] [--truncate]` | Import from CSV | | `hologres data count <table> [-w <where>]` | Count rows | | `hologres history [-n <count>]` | Show command history | | `hologres ai-guide` | Generate AI agent guide | | `hologres ai gen "<prompt>" [--model]` | Generate text using AI function | | `hologres ai image-gen "<prompt>" -o volume://vol/path [options]` | Generate images to OSS volume using AI function | | `hologres ai t2v "<prompt>" -o volume://vol/path [options]` | Generate video from text (text-to-video) | | `hologres ai i2v "<prompt>" --img-url <url\|local_file> -o volume://vol/path [options]` | Generate video from first-frame image (image-to-video) | | `hologres ai r2v "<prompt>" --reference-url <url\|local_file> -o volume://vol/path [options]` | Generate video from reference images (reference-to-video) | | `hologres ai video-edit "<prompt>" --video <url\|local_file> -o volume://vol/path [options]` | Edit video with text instructions | | `hologres volume create <name> --endpoint <ep> --root <root> --rolearn <arn> --access-key <ak> --access-secret <sk>` | Create a local volume config (also creates OSS directory placeholder) | | `hologres volume list` | List all volumes in current profile | | `hologres volume delete <name>` | Delete a volume config | | `hologres volume list-files --volume <name> [--prefix P] [--max-count N] [--net internet\|intranet]` | List files in volume | | `hologres volume delete-file --volume <name> --file <path> [--confirm] [--net internet\|intranet]` | Delete file from volume (dry-run by default) | | `hologres volume download-file --volume <name> --file <path> -d <dir> [--net internet\|intranet]` | Download file from volume | | `hologres volume upload-file --volume <name> --local-file <path> --target-file <path> [--net internet\|intranet]` | Upload file to volume | | `hologres volume view volume://<name>/path/file [--net internet\|intranet]` | Download file to temp dir and open with system viewer | | `hologres model list [--task T] [--model-type T] [--search S]` | List registered external AI models | | `hologres model catalog [--task T] [--search S]` | List supported AI model types from the bundled catalog (no DB connection) | | `hologres model create --name N --type T --api-key K [--config J] [--dry-run]` | Register an external AI model via `add_external_model()` | | `hologres model delete <model_name> [--confirm]` | Delete a registered external AI model (dry-run by default) | ## Dynamic Table Commands (V3.1+) Full lifecycle management for Hologres Dynamic Tables. | Command | Description | |---------|-------------| | `hologres dt create` | Create a Dynamic Table | | `hologres dt list` | List all Dynamic Tables | | `hologres dt show <table>` | Show Dynamic Table properties | | `hologres dt ddl <table>` | Show DDL (CREATE statement) | | `hologres dt lineage <table>` | Show dependency lineage | | `hologres dt lineage --all` | Show lineage for all DTs | | `hologres dt storage <table>` | Show storage details | | `hologres dt state-size <table>` | Show state table size (incremental) | | `hologres dt refresh <table>` | Trigger manual refresh | | `hologres dt alter <table>` | Alter DT properties | | `hologres dt drop <table>` | Drop DT (dry-run by default) | | `hologres dt convert [table]` | Convert V3.0 → V3.1 syntax | ### dt create ```bash # Minimal hologres dt create -t my_dt --freshness "10 minutes" \ -q "SELECT col1, SUM(col2) FROM src GROUP BY col1" # With partitioning and serverless hologres dt create -t ads_report --freshness "5 minutes" --refresh-mode auto \ --logical-partition-key ds --partition-active-time "2 days" \ --partition-time-format YYYY-MM-DD \ --computing-resource serverless --serverless-cores 32 \ -q "SELECT repo_name, COUNT(*) AS events, ds FROM src GROUP BY repo_name, ds" # Incremental refresh hologres dt create -t tpch_q1 --freshness "3 minutes" --refresh-mode incremental \ -q "SELECT l_returnflag, l_linestatus, COUNT(*) FROM lineitem GROUP BY 1,2" # Dry-run (preview SQL without executing) hologres dt create -t my_dt --freshness "10 minutes" -q "SELECT 1" --dry-run ``` **Key create options:** | Option | Description | |--------|-------------| | `-t, --table` | Table name `[schema.]table` (required) | | `-q, --query` | SQL query for data definition (required) | | `--freshness` | Data freshness target, e.g. `"10 minutes"` (required) | | `--refresh-mode` | `auto` / `full` / `incremental` | | [REDACTED_SECRET] | Enable/disable auto refresh | | `--cdc-format` | `stream` (default) / `binlog` | | `--computing-resource` | `local` / `serverless` / `<warehouse>` | | `--serverless-cores` | Serverless computing cores | | `--logical-partition-key` | Partition column for logical partition | | `--partition-active-time` | Active partition window, e.g. `"2 days"` | | `--partition-time-format` | Partition key format, e.g. `YYYY-MM-DD` | | `--orientation` | `column` / `row` / `row,column` | | `--distribution-key` | Distribution key columns | | `--clustering-key` | Clustering key with sort order | | `--event-time-column` | Event time column (Segment Key) | | `--ttl` | Data TTL in seconds | | `--refresh-guc` | GUC params for refresh (repeatable) | | `--dry-run` | Preview SQL without executing | ### dt list / show / ddl ```bash hologres dt list # List all DTs with refresh info hologres dt show public.my_dt # Show all properties hologres dt ddl public.my_dt # Show CREATE statement hologres dt list -f table # Table format output ``` ### dt lineage ```bash hologres dt lineage public.my_dt # Single table lineage hologres dt lineage --all # All DTs lineage hologres dt lineage my_dt -f table # Table format ``` base_table_type: `r`=table, `v`=view, `m`=materialized view, `f`=foreign table, `d`=Dynamic Table. ### dt storage / state-size ```bash hologres dt storage public.my_dt # Storage breakdown hologres dt state-size public.my_dt # State table size (incremental DTs) ``` ### dt refresh ```bash hologres dt refresh my_dt hologres dt refresh my_dt --overwrite --partition "ds = '2025-04-01'" --mode full hologres dt refresh my_dt --dry-run ``` ### dt alter ```bash hologres dt alter my_dt --freshness "30 minutes" hologres dt alter my_dt --no-auto-refresh hologres dt alter my_dt --refresh-mode full --computing-resource serverless hologres dt alter my_dt --refresh-guc timezone=GMT-8:00 --dry-run ``` ### dt drop ```bash hologres dt drop my_dt # Dry-run by default (safety) hologres dt drop my_dt --confirm # Actually drop hologres dt drop my_dt --if-exists --confirm ``` ### dt convert (V3.0 → V3.1) ```bash hologres dt convert my_old_dt # Convert single table hologres dt convert --all # Convert all V3.0 tables hologres dt convert my_old_dt --dry-run ``` ## Output Formats ### Partition Management ```bash # List partitions hologres partition list -t public.logs # Drop a partition hologres partition drop -t my_table --partition "2025-04-01" --confirm # Alter partition properties hologres partition alter -t public.logs --partition "ds=2025-03-16" --set "keep_alive=TRUE" hologres partition alter -t my_table --partition "ds=2025-03-16" --set "keep_alive=TRUE" --set "storage_mode=hot" --dry-run ``` ## Output Formats ```bash hologres -f json schema tables # JSON (default) hologres -f table schema tables # Human-readable table hologres -f csv schema tables # CSV hologres -f jsonl schema tables # JSON Lines ``` ### Response Structure ```json // Success {"ok": true, "data": {"rows": [...], "count": 10}} // Error {"ok": false, "error": {"code": "ERROR_CODE", "message": "..."}} ``` ## Safety Features ### 0. Default Session GUC Protection All connections automatically set safety GUCs upon creation: - `SET hg_experimental_enable_adaptive_execution = on` — Enables adaptive execution to prevent OOM - `SET hg_computing_resource = 'serverless'` — Routes queries to the serverless computing pool These are applied transparently at the connection layer; no user action needed. ### 1. Row Limit Protection Queries without `LIMIT` returning >100 rows fail with `LIMIT_REQUIRED`. ```bash # Will fail if >100 rows hologres sql run "SELECT * FROM large_table" # Fix: add LIMIT hologres sql run "SELECT * FROM large_table LIMIT 50" # Or disable check hologres sql run --no-limit-check "SELECT * FROM large_table" ``` ### 2. Write Protection Write operations (INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE, GRANT, REVOKE) require `--write` flag. ```bash hologres sql run --write "INSERT INTO logs VALUES (1, 'test')" ``` ### 3. Dangerous Write Blocking DELETE/UPDATE without WHERE clause are blocked. ```bash # Blocked hologres sql run --write "DELETE FROM users" # Must have WHERE hologres sql run --write "DELETE FROM users WHERE status='inactive'" ``` ## Error Codes | Code | Description | |------|-------------| | `CONNECTION_ERROR` | Failed to connect | | `QUERY_ERROR` | SQL execution error | | `LIMIT_REQUIRED` | Need LIMIT clause | | `WRITE_GUARD_ERROR` | Write operation without `--write` flag | | `DANGEROUS_WRITE_BLOCKED` | DELETE/UPDATE without WHERE clause | | `WRITE_BLOCKED` | Write operation not allowed | | `NOT_FOUND` | Table or resource not found | | `INVALID_INPUT` | Invalid identifier or input validation failed | | `INVALID_ARGS` | Invalid or missing arguments | | `NO_CHANGES` | No properties specified to alter | | `EXPORT_ERROR` | Data export failed | | `IMPORT_ERROR` | Data import failed | | `VIEW_NOT_FOUND` | View not found | | `OSS_ERROR` | OSS operation failed (e.g. directory placeholder creation on volume create) | ## Sensitive Data Masking Auto-masks by column name pattern: - phone/mobile/tel → `138****5678` - email → `j***@example.com` - password/secret/token → `********` Disable: `hologres sql run --no-mask "SELECT * FROM users LIMIT 10"` ## References | Document | Content | |----------|--------| | [commands.md](references/commands.md) | Complete command reference with DT commands | | [ai-volume-model.md](references/ai-volume-model.md) | AI generation, volume storage, and model commands | | [safety-features.md](references/safety-features.md) | Safety guardrails details | ## Best Practices 1. Always use `LIMIT` for large result sets 2. Use `--dry-run` to preview DT SQL before executing 3. Use `--confirm` explicitly for destructive operations (table drop, table truncate, dt drop) 4. Include `WHERE` clause in DELETE/UPDATE 5. Use JSON output for automation/scripting 6. Check `hologres status` before batch operations 7. Use `hologres dt lineage` to understand DT dependencies before altering ## SQL Tracking Set `HOLOGRES_SKILL` environment variable before calling CLI to tag queries with skill origin: ```bash export HOLOGRES_SKILL=hologres-query-optimizer hologres sql run "SELECT * FROM orders LIMIT 10" ``` Queries will appear in `hg_query_log` with `application_name = [REDACTED_SECRET]`. This enables per-skill SQL statistics on the Hologres server: ```sql SELECT split_part(application_name, '/', 2) AS skill, COUNT(*) AS query_count, AVG(duration) AS avg_duration_ms FROM hologres.hg_query_log WHERE query_start > now() - interval '1 hour' AND application_name LIKE 'hologres-cli/%' GROUP BY 1 ORDER BY 2 DESC; ```

path: VERSION
content: 0.2.0


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)