shz-backend/.claude/skills/query-shz-highgo/SKILL.md

---
name: query-shz-highgo
description: Run SQL against the SHZ HighGo Security Enterprise Edition database through its SSH gateway. Use when Claude Code is working in the shz-backend project and needs to inspect schemas, tables, columns, row counts, or application data; diagnose data-related behavior; or execute SELECT/WITH/SHOW/EXPLAIN. Also supports write operations — INSERT, UPDATE, DELETE, MERGE, CREATE, ALTER, DROP, TRUNCATE, GRANT, REVOKE — when the user explicitly asks to add, modify, delete, or otherwise change data or schema.
---

# SHZ HighGo SQL

Two bundled scripts run SQL through the configured SSH gateway:

- `scripts/query.sh` — **read-only**. Default for inspection and diagnostics.
- `scripts/modify.sh` — **write-capable**. Use only when an actual change is intended and the user has asked for it.

Both set `search_path` to `shz,public`, apply a 30-second `statement_timeout`, reject multiple statements in one call, and base64-encode the SQL over the SSH channel. `query.sh` additionally enforces database-level `default_transaction_read_only=on` and accepts only `SELECT/WITH/SHOW/EXPLAIN`.

## Query workflow (read-only)

1. Form the narrowest useful query. Add a small `LIMIT` when inspecting rows.
2. For unfamiliar tables, inspect `information_schema.columns` before selecting business data.
3. Run:

   ```bash
   .claude/skills/query-shz-highgo/scripts/query.sh 'SELECT current_database(), current_user, current_schema()'
   ```

4. Summarize the result and distinguish returned facts from inferences.

## Modify workflow (writes)

⚠️ These statements change data or schema on a production database. Confirm the exact statement with the user before running it, and prefer a `WHERE` clause or scoped target. Read unfamiliar tables with `query.sh` first.

1. Inspect the target with `query.sh` (columns, existing rows) so the statement is well-formed.
2. Run the write:

   ```bash
   .claude/skills/query-shz-highgo/scripts/modify.sh "INSERT INTO shz.some_table (col) VALUES ('val')"
   .claude/skills/query-shz-highgo/scripts/modify.sh "UPDATE shz.some_table SET col = 'val' WHERE id = 1"
   .claude/skills/query-shz-highgo/scripts/modify.sh "DELETE FROM shz.some_table WHERE id = 1"
   .claude/skills/query-shz-highgo/scripts/modify.sh "CREATE TABLE shz.example (id bigint PRIMARY KEY)"
   ```

3. Verify the effect with a follow-up `query.sh` `SELECT` and report rows affected.

Notes:
- Only one statement per call. To run several, invoke the script multiple times.
- Transactions across calls are NOT supported (each call is its own session). psql autocommits each statement.
- `DROP`/`TRUNCATE`/`DELETE` without a `WHERE` are destructive — re-state the impact to the user and wait for explicit go-ahead.

## Schema discovery

List user tables:

```bash
.claude/skills/query-shz-highgo/scripts/query.sh "SELECT table_schema, table_name FROM information_schema.tables WHERE table_schema NOT IN ('pg_catalog', 'information_schema') ORDER BY 1, 2"
```

Inspect columns:

```bash
.claude/skills/query-shz-highgo/scripts/query.sh "SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_schema = 'shz' AND table_name = 'lowercase_table_name' ORDER BY ordinal_position"
```

HighGo may expose unquoted identifiers in lowercase and quoted identifiers with exact case. Query `information_schema` first when the spelling is uncertain.

## Connection details

Read [references/connection.md](references/connection.md) only when troubleshooting connectivity or updating the endpoint. Do not print, quote, or expose the password file.