@carllee1983/dbcli 1.6.0 → 1.8.0

package/assets/reference.md

@@ -2,6 +2,8 @@
 
 Companion to [SKILL.md](SKILL.md). Exhaustive flags, copy-paste examples, `shell`, `completion`, `upgrade`, `migrate` DDL, and extended MongoDB examples.
 
+For cross-engine support status, see `docs/feature-matrix.md` in the repository.
+
 ## Commands
 
 ### init
@@ -19,6 +21,14 @@ dbcli init --system mongodb --uri "mongodb://user:pass@host:27017/mydb?authSourc
 dbcli init --system mongodb --host localhost --port 27017 --user admin --password secret --name mydb
 dbcli init --system mongodb --host localhost --port 27017 --name mydb  # No auth
 
+# Redis (database = logical DB index)
+dbcli init --system redis --host localhost --port 6379
+dbcli init --system redis --host localhost --port 6379 --password secret --name 0
+
+# Elasticsearch
+dbcli init --system elasticsearch --host localhost --port 9200 --user elastic --password changeme
+dbcli init --system elasticsearch --cloud-id "myCluster:dXMtZWFzdC0xLmF3..." --api-key "<base64>"
+
 # Multi-connection (v2 format)
 dbcli init --conn-name staging --env-file .env.staging   # Named connection with custom env file
 dbcli init --conn-name prod --env-file .env.production --use-env-refs --skip-test
@@ -30,6 +40,10 @@ dbcli init --rename staging:production                   # Rename a connection
 
 **MongoDB-specific options:** `--uri <uri>` (full connection URI), `--auth-source <db>` (auth database, default: `admin` when user/password set)
 
+**Elasticsearch-specific options:** `--cloud-id <id>` (Elastic Cloud), `--api-key <key>` (ApiKey auth). Other ES fields (`nodes[]`, `protocol`, `caPath`, `rejectUnauthorized`) can be edited directly in `.dbcli`.
+
+**Redis note:** the `database` (or `--name`) field is the logical DB index (`"0"` … `"15"`), not a database name.
+
 **Multi-connection:** Using `--conn-name` or `--env-file` creates a v2 config with named connections. Each connection can have its own env file and permission level. Existing v1 configs are automatically imported as the `default` connection when upgrading.
 
 > **AI agent note on `--use-env-refs`:** If an existing `.dbcli` config contains `{"$env": "DB_HOST"}` style references, the connection values are read from environment variables at runtime. Do NOT re-run `init` to replace these references with actual values — the env-ref format is intentional for CI/CD and multi-environment setups.
@@ -55,16 +69,19 @@ dbcli list --use prod
 
 ### list
 
-List all tables (SQL) or collections (MongoDB).
+List all tables (SQL), collections (MongoDB), keys (Redis), or indices (Elasticsearch).
 
 ```bash
 dbcli list
 dbcli list --format json
+dbcli list --include-system        # Elasticsearch: include `.system` indices
 ```
 
 **Permission:** query-only+
 
-> **MongoDB:** Lists collections with estimated document count instead of tables.
+> **MongoDB:** Lists collections with estimated document count.
+> **Redis:** Returns up to 100 000 keys via `SCAN MATCH * COUNT 1000`. The header reads `Keys in db <n> (redis):` where `<n>` is the logical DB index.
+> **Elasticsearch:** Returns indices with `documentCount` from `/_stats/docs`; aliases are tagged separately. System indices (names starting with `.`) are hidden unless `--include-system` is passed.
 
 ### schema
 
@@ -88,6 +105,9 @@ dbcli schema --use prod             # Scan prod DB; saves to .dbcli/schemas/prod
 
 **Schema storage (v1.4+):** Schema is persisted as layered files under `.dbcli/schemas/`. With v2 multi-connection config each connection gets its own subdirectory (`.dbcli/schemas/<connection>/`). Run `dbcli schema --use <connection>` once per connection before querying it — otherwise `schema <table>` may return data from the wrong connection's cache.
 
+> **Redis:** `schema <key>` is required (no full scan). The output exposes `type`, `ttl`, `size`, and a small `sample` (e.g. first 5 hash keys). `--reset` / `--refresh` are rejected — Redis caches no schema.
+> **Elasticsearch:** `schema [index]` flattens the `_mapping` properties (nested `a.b.c`) and emits each `.fields` multi-field as a separate column (e.g. `text` + `text.keyword`). Full scan iterates all non-system indices and stores per-connection caches alongside SQL engines.
+
 ### query
 
 Execute SQL query (MySQL/PostgreSQL/MariaDB) or JSON filter/pipeline (MongoDB).
@@ -104,16 +124,158 @@ dbcli query '{"age": {"$gt": 18}}' --collection users --format json
 
 # MongoDB: aggregation pipeline
 dbcli query '[{"$match": {"status": "active"}}, {"$group": {"_id": "$role", "count": {"$sum": 1}}}]' --collection users
+
+# Redis: any whitelisted command (permission-gated by command)
+dbcli query "GET session:abc"
+dbcli query "HGETALL user:42" --format json
+dbcli query "SCAN 0 MATCH user:* COUNT 100"
+dbcli query "SET feature:flag enabled"          # requires read-write+
+dbcli query "DEL stale:key"                      # requires data-admin+
+
+# Elasticsearch: DSL body or Lucene q-string
+dbcli query '{"query":{"match":{"status":"active"}}}' --collection orders
+dbcli query 'status:active AND amount:>100' --index orders --limit 50
 ```
 
-**Options:** `--format <table|json|csv>`, `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB only)
-**Permission:** query-only+
+**Options:** `--format <table|json|csv>`, `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`)
+**Permission:** query-only+ (Redis: per-command; Elasticsearch: per HTTP method/path)
 
 > **MongoDB notes:**
 > - SQL syntax is rejected — use JSON object (filter) or JSON array (pipeline)
 > - `--collection <name>` is required
 > - Auto-limit does not apply; use `$limit` in your pipeline if needed
 
+> **Redis notes:**
+> - The first token must be an allow-listed command (`GET`/`SET`/`HGET`/`HSET`/`DEL`/...). Unknown commands are refused.
+> - Permission tier is derived from the command (read → `query-only`, write → `read-write`, delete → `data-admin`, `KEYS`/`FLUSHDB`/`CONFIG`/... → `admin`).
+> - Output is always shaped into rows: scalar replies become `{value: ...}`; arrays become indexed rows; `HGETALL` is folded into a single object.
+
+> **Elasticsearch notes:**
+> - `--collection` (or `--index`) is required.
+> - A body that begins with `{` is sent as DSL via `POST /<index>/_search`; otherwise the value is URL-encoded into `?q=...` (Lucene query string) via `GET`.
+> - Hits are flattened: each result row contains `_id` plus dotted-path fields from `_source`. Pass `--format json` to keep nested structures readable.
+> - Query-only mode caps at 1000 hits; `--no-limit` is internally capped at 10 000 (use saved searches / `search_after` for deeper pagination).
+
+### q
+
+Run a saved query snippet by `@name`. Snippets are parameterised SELECT/WITH statements resolved from three layers, with **local > shared > builtin** precedence (a local file always shadows shared and builtin variants of the same key):
+
+- `builtin` — bundled with dbcli (e.g. `@diag/*`); read-only at runtime.
+- `.dbcli-shared/queries/` — committed, team-shared.
+- `.dbcli/queries/` — gitignored, personal override.
+
+Engine variants (`name.postgres.sql` / `name.mysql.sql`) at the same layer are merged; the variant matching the active connection's engine is selected at execution time.
+
+```bash
+dbcli q @dau                                  # run with declared defaults
+dbcli q @dau --param days=30 --format json    # override a param
+dbcli q @analytics/revenue --param-file params.json
+dbcli q @dau --dry-run                        # show final SQL + bind values
+dbcli q @dau --no-limit                       # disable size guard wrap
+```
+
+**Options:**
+- `--format <table|json|csv>` — output format (default: `table`)
+- `--param <key=value>` — pass a parameter (repeatable)
+- `--param-file <path>` — JSON object whose keys are param names
+- `--no-limit` — skip the `SELECT * FROM (…) AS _dbcli_guard LIMIT 1000` wrap
+- `--dry-run` — print the bound SQL + values without executing
+- `--use <name>` — pick a v2 named connection
+
+**Permission:** query-only+
+
+#### Snippet file format
+
+Each `.sql` file is plain SQL with optional YAML frontmatter inside a leading `-- ---` block. Lines outside frontmatter form the SQL body.
+
+```sql
+-- ---
+-- name: DAU
+-- description: Daily Active Users
+-- engine: postgres        # or [postgres, mysql]
+-- params:
+--   days:
+--     type: int           # int | string | float | bool | date | datetime
+--     default: 7
+--     required: false
+--     description: lookback window in days
+--     enum: [7, 30, 90]
+-- tags: [analytics]
+-- ---
+SELECT COUNT(DISTINCT user_id) AS dau
+FROM events
+WHERE created_at > NOW() - (:days || ' days')::interval;
+```
+
+Param placeholders use `:name`. They are rewritten to `$1, $2, …` (Postgres) or `?, ?, …` (MySQL) at execution time and passed as bind values — string interpolation is never used.
+
+#### Param type coercion
+
+| Declared `type` | Accepts |
+|-----------------|---------|
+| `int` | integer literal |
+| `float` | decimal literal |
+| `bool` | `true` / `false` / `1` / `0` / `yes` / `no` |
+| `string` | any value |
+| `date` | `YYYY-MM-DD` |
+| `datetime` | ISO 8601 |
+
+`enum` (optional) restricts the accepted values; mismatch is a hard error. CLI `--param` overrides `--param-file`, which overrides the snippet's `default`.
+
+#### Safety invariants
+
+- Only `SELECT` / `WITH` (CTE) bodies are accepted; `INSERT/UPDATE/DELETE/DDL` are rejected by the parser.
+- Multi-statement bodies (`SELECT 1; DROP TABLE x`) are rejected.
+- Template syntax inside SQL (`${…}`, `{{…}}`) is rejected — use `:name` parameters.
+- Files exceeding 64 KiB are rejected.
+- `--no-limit` is honoured only at the outermost level; nested subqueries are still wrapped by the size guard.
+
+### queries
+
+Manage saved snippets — discover, inspect, scaffold, and edit local copies. Mutating
+subcommands (`delete`, `rename`, `copy`, `import`) only operate on the local layer
+(`.dbcli/queries/`); builtin and shared snippets are never modified in place.
+
+```bash
+# Discovery / inspection
+dbcli queries list                      # all snippets (builtin + shared + local)
+dbcli queries list --tag analytics --engine postgres --format json
+dbcli queries list --source local       # only personal overrides
+dbcli queries show @dau                 # frontmatter + SQL
+dbcli queries show @dau --format json   # MCP-shaped contract
+
+# Authoring
+dbcli queries new @new/sample           # scaffold under .dbcli-shared/queries/
+dbcli queries new @scratch --local      # personal copy under .dbcli/queries/
+dbcli queries edit @dau                 # opens local first, falls back to shared
+dbcli queries edit @dau --shared        # always edit the shared file
+dbcli queries check                     # parse all snippets; exit 1 on errors
+dbcli queries check --strict            # promote warnings (e.g. missing engine) to errors
+
+# Local-layer file management
+dbcli queries delete @scratch                       # remove local file(s); prompts unless --force
+dbcli queries delete @scratch --force
+dbcli queries rename @scratch @analytics/dau        # rename within local layer; preserves engine suffix
+dbcli queries copy @diag/connections @my/connections    # fork builtin/shared into local for editing
+dbcli queries import ./hotfix.sql                   # import an external .sql into .dbcli/queries/
+dbcli queries import ./hotfix.sql --as @diag/custom # override the snippet key
+dbcli queries export @dau --output dau.sql          # write snippet body to a file (stdout if omitted)
+dbcli queries export @diag/connections --engine postgres  # pick a variant when multiple engines exist
+```
+
+**`list` options:** `--format <table|json|csv>`, `--tag <tag>`, `--engine <postgres|mysql>`, `--source <local|shared>`
+**`show` options:** `--format <table|json|csv>`
+**`new` options:** `--local`, `--edit`
+**`edit` options:** `--shared`
+**`check` options:** `--strict`, `--format <table|json|csv>`
+**`delete` options:** `--force` (skip the confirmation prompt). Refuses to run if `@name` has no local copy.
+**`rename` options:** `--force`. Both names must start with `@`. Engine suffix (`.postgres.sql` / `.mysql.sql`) is preserved; frontmatter `name:` is rewritten to the new key.
+**`copy` options:** *(none)*. Copies every variant (all engines) of the source into the local layer; fails if the destination already has a local copy.
+**`import` options:** `--force` (overwrite existing local file), `--as <name>` (override snippet key; defaults to filename without `.postgres` / `.mysql` suffix). Source must be `.sql` and parse cleanly (frontmatter validated, non-SELECT bodies rejected).
+**`export` options:** `--output <path>` (write to file; otherwise stdout), `--engine <postgres|mysql>` (required when the snippet has multiple engine variants).
+
+`--format json` on `list` and `show` emits a stable, machine-readable shape — designed to back a future MCP server without further refactor.
+
 ### insert
 
 Insert data into a table.
@@ -338,13 +500,25 @@ dbcli migrate drop-enum status --execute --force
 
 ## MongoDB Support
 
-MongoDB connections use a JSON-based query model instead of SQL.
+MongoDB connections use a JSON-based query model instead of SQL. Treat MongoDB support as a narrower document-database path, not as a full SQL feature equivalent.
 
 Atlas-style `mongodb+srv://` URIs are supported. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
 
-**Supported commands:** `init`, `list`, `query`, `status`, `use`, `shell`, `doctor`, `upgrade`, `completion`
+**Supported commands:** `init`, `use`, `list`, `schema`, `query`, `insert`, `update`, `delete`, `status`, `shell`, `doctor`, `upgrade`, `completion`
+
+**Limited support:**
+
+- `schema` samples collection documents to infer field names/types. It does not provide relational constraints, primary keys, foreign keys, or reliable index metadata.
+- `query` accepts only JSON object filters or aggregation pipeline arrays and always requires `--collection <name>`.
+- `insert` inserts one JSON document into the named collection.
+- `update` accepts a JSON filter in `--where` or simple `key=value` conditions. If `--set` does not use MongoDB update operators such as `$set`, dbcli wraps it in `$set`.
+- `delete` deletes all documents matching the JSON/simple filter.
+- MongoDB write paths do not currently provide the same SQL dry-run, relational schema validation, or column-level blacklist filtering guarantees as SQL writes.
+- `shell` blocks raw SQL for MongoDB; use `query <json> --collection <name>` inside the shell.
 
-**Not supported (exit with error):** `schema`, `insert`, `update`, `delete`, `export`, `diff`, `migrate`, `check`
+**Not supported (exit with error):** `q` saved-query execution, `export`, `diff`, `migrate`
+
+**Not a supported MongoDB target:** `check` is designed for relational health checks and emits SQL-style checks.
 
 ### MongoDB-specific workflow
 
@@ -359,6 +533,11 @@ dbcli list --format json
 dbcli query '{}' --collection orders --format json          # All documents
 dbcli query '{"status": "paid"}' --collection orders        # Filter
 dbcli query '[{"$match": {"status":"paid"}}, {"$count":"total"}]' --collection orders  # Pipeline
+
+# 4. Document writes (permission-gated; no SQL dry-run semantics)
+dbcli insert orders --data '{"status":"paid","total":42}'
+dbcli update orders --where '{"status":"pending"}' --set '{"status":"paid"}'
+dbcli delete orders --where '{"status":"cancelled"}' --force
 ```
 
 ### Query syntax
@@ -369,3 +548,144 @@ dbcli query '[{"$match": {"status":"paid"}}, {"$count":"total"}]' --collection o
 | Field filter | `'{"field": "value"}'` |
 | Comparison | `'{"age": {"$gt": 18}}'` |
 | Aggregation | `'[{"$match": {...}}, {"$group": {...}}]'` |
+
+## Redis Support
+
+Redis connections speak Redis commands rather than SQL. The adapter uses the `ioredis` driver and exposes a narrow, permission-gated surface.
+
+**Supported commands:** `init`, `use`, `list`, `schema`, `query`, `status`, `doctor`, `upgrade`, `completion`
+
+**Not supported (exit with error or unsupported error):** `insert`, `update`, `delete`, `export`, `check`, `diff`, `migrate`, `q` (saved queries), `shell`. For writes, run the equivalent Redis command via `query` — the same permission gate applies.
+
+### Connection and configuration
+
+- Required fields: `system: redis`, `host`, `port`. `password` and `database` are optional.
+- `database` is the **logical DB index** (`"0"` … `"15"`), kept as a string to play nicely with env-ref bindings. `list` and the connection metadata both label it as the active DB.
+- `connection.timeout` (ms, default 5000) maps to ioredis's `connectTimeout`.
+
+### Permission classification
+
+Permission is derived from the command's first token (case-insensitive). Unknown commands are denied even at `admin` tier — they must be added to the allow-list.
+
+| Tier | Commands |
+|------|----------|
+| `query-only` | `GET`, `MGET`, `STRLEN`, `EXISTS`, `TTL`, `PTTL`, `TYPE`, `SCAN`, `HGET`, `HGETALL`, `HKEYS`, `HVALS`, `HLEN`, `HEXISTS`, `HMGET`, `LRANGE`, `LLEN`, `LINDEX`, `SMEMBERS`, `SCARD`, `SISMEMBER`, `ZRANGE`, `ZREVRANGE`, `ZRANGEBYSCORE`, `ZCARD`, `ZSCORE`, `PING`, `ECHO` |
+| `read-write` | `SET`, `SETEX`, `SETNX`, `PSETEX`, `MSET`, `MSETNX`, `APPEND`, `INCR`/`INCRBY`, `DECR`/`DECRBY`, `HSET`/`HSETNX`/`HMSET`/`HINCRBY`, `LPUSH`/`RPUSH`/`LPOP`/`RPOP`/`LSET`, `SADD`/`SREM`, `ZADD`/`ZREM`, `EXPIRE`/`EXPIREAT`/`PEXPIRE`/`PERSIST`, `RENAME` |
+| `data-admin` | `DEL`, `UNLINK`, `HDEL` |
+| `admin` | `FLUSHDB`, `FLUSHALL`, `CONFIG`, `INFO`, `CLIENT`, `DEBUG`, `SHUTDOWN`, `KEYS`, `MONITOR`, `SAVE`, `BGSAVE`, `BGREWRITEAOF`, `REPLICAOF`, `SLAVEOF`, `ACL` |
+
+### Schema inspection
+
+`schema <key>` returns one synthetic row per key with these columns:
+
+| column | meaning |
+|--------|---------|
+| `type` | Redis type (`string` / `hash` / `list` / `set` / `zset` / `stream` / `none`) |
+| `ttl` | `<n>s`, `no expiry`, or `missing` |
+| `size` | `STRLEN` / `HLEN` / `LLEN` / `SCARD` / `ZCARD` / `XLEN` depending on type |
+| `sample` | First 5 hash field names (hash only) |
+
+`schema` (no key) and `--refresh` / `--reset` are rejected — there is no full-database schema cache for Redis.
+
+### Recommended `query` patterns
+
+```bash
+# Read
+dbcli query "GET feature:flag"
+dbcli query "HGETALL user:42" --format json
+dbcli query "LRANGE queue:jobs 0 9"
+
+# Iterate keys (paginated; never use KEYS — admin-only)
+dbcli query "SCAN 0 MATCH session:* COUNT 200"
+
+# Write (requires read-write+)
+dbcli query "SET counter 1"
+dbcli query "EXPIRE session:abc 3600"
+dbcli query "HSET user:42 name Alice"
+
+# Delete (requires data-admin+)
+dbcli query "DEL temp:lock"
+dbcli query "HDEL user:42 lastLogin"
+```
+
+### Limitations
+
+- No `--dry-run` for writes — Redis commands execute immediately. Pair writes with a confirming read (`GET`, `HGETALL`, `EXISTS`).
+- No transaction wrapping (`MULTI`/`EXEC`). Submit one command at a time.
+- `KEYS` requires `admin`. Prefer `SCAN` for routine work.
+- Blacklist rules are not enforced for Redis (there is no concept of "column" / "table" the validator can map). Be careful with sensitive key prefixes.
+
+## Elasticsearch Support
+
+Elasticsearch connections speak the REST API. The adapter is fetch-based (no SDK) and supports HTTPS, custom CA, API key, basic auth, and Cloud ID.
+
+**Supported commands:** `init`, `use`, `list`, `schema`, `query`, `status`, `doctor`, `upgrade`, `completion`
+
+**Not supported (use external tooling):** `insert`, `update`, `delete`, `export`, `check`, `diff`, `migrate`, `q`, `shell`. The permission classifier already understands `_doc` / `_update` / `_bulk` so future write surfaces can be wired in without changing tiers.
+
+### Connection and configuration
+
+- Either `host` + `port` (default `https://localhost:9200`) or `nodes: [...]` (first node is used) or `cloudId`.
+- Auth precedence: `apiKey` → `user`/`password` (HTTP Basic). Leave both unset for an open cluster.
+- `protocol` defaults to `https`. For TLS quirks: `caPath` (path to a PEM bundle) and `rejectUnauthorized: false` (last resort).
+- `connection.timeout` (ms, default 5000) is wired to `AbortController` on every request.
+
+### Permission classification
+
+Each REST request is mapped to a SQL-shaped tier based on method + path:
+
+| ES surface | Mapped to | Permission |
+|------------|-----------|------------|
+| `GET _search` / `_count` / `_mapping` / `_settings` / `_alias` / `GET _doc` / `_source` | `SELECT` | `query-only` |
+| `POST _update` / `POST _doc` | `UPDATE` | `read-write` |
+| `PUT _doc` / `_create` | `INSERT` | `read-write` |
+| `DELETE` (any) | `DELETE` | `data-admin` |
+| `_bulk` | highest tier among the NDJSON actions (`delete` ⇒ `data-admin`) | derived |
+| Anything else | `DROP` | `admin` (deny by default) |
+
+### Schema inspection
+
+`schema [index]` calls `GET /<index>/_mapping` and flattens nested properties into dotted-path columns. Multi-fields under `.fields` (e.g. `text` → `text.keyword`) are emitted as separate columns. All fields are reported as nullable. There is no PK / FK / index info.
+
+`schema` (no argument) iterates all non-system indices through the standard full-scan code path and writes per-connection caches under `.dbcli/schemas/<connection>/`.
+
+### Query semantics
+
+- `--collection <index>` (or `--index <index>`) is required.
+- Body that starts with `{` → sent as JSON DSL via `POST /<index>/_search`. Body otherwise → URL-encoded into `?q=...` (Lucene query string) on `GET`.
+- Hits are flattened: each row carries `_id` plus dotted-path fields lifted from `_source`. Use `--format json` to inspect raw nested structure.
+- Query-only mode caps `size` at 1000. `--no-limit` is internally capped at 10 000; for deeper pagination use the API directly with `search_after` or PIT.
+
+### Recommended `query` patterns
+
+```bash
+# DSL match
+dbcli query '{"query":{"match":{"status":"active"}}}' --collection orders --format json
+
+# DSL with sort + size
+dbcli query '{"query":{"range":{"created_at":{"gte":"2026-01-01"}}},"sort":[{"created_at":"desc"}],"size":50}' \
+  --collection orders
+
+# Aggregation
+dbcli query '{"size":0,"aggs":{"by_status":{"terms":{"field":"status.keyword"}}}}' \
+  --collection orders --format json
+
+# Lucene query string
+dbcli query 'status:active AND amount:>100' --index orders --limit 100
+```
+
+### Doctor and diagnostics
+
+`dbcli doctor` runs a dedicated Elasticsearch path:
+
+- Verifies REST connectivity to `GET /`.
+- Reads `version.number` and runs the standard version freshness check.
+- Walks every index via `listTables()` + `getTableSchema()` to feed the blacklist completeness check and the large-table heuristic (using `documentCount`).
+- Standard schema-cache freshness using `schemaLastUpdated`.
+
+### Limitations
+
+- Writes (`insert`/`update`/`delete`/`export`) are not exposed yet — the adapter implements them, but the CLI currently only routes them for SQL and MongoDB.
+- No `_search/scroll` or PIT pagination at the CLI layer; large pulls need a saved external script.
+- `check`, `diff`, `migrate`, and `q` are SQL-only and exit with errors (or fall through to a generic "unsupported" path).
+- Blacklist column rules are applied to flattened hit rows on `query`; table-level blacklist rejects an index up front.

package/assets/snippets/README.md

@@ -0,0 +1,18 @@
+# Built-in snippets
+
+Files under this directory are bundled with dbcli and resolved at runtime as
+the `builtin` tier. Every file is a valid `.sql` snippet.
+
+## Naming
+
+- Single-engine variant: `<topic>.<engine>.sql` — loader derives key
+  `@<dir>/<topic>` and engine from the suffix.
+- Cross-engine variant: `<topic>.sql` with explicit
+  `engine: [postgres, mysql]` in frontmatter.
+
+## Override
+
+Users can shadow any built-in snippet by placing a same-key file in
+`.dbcli-shared/queries/` (team) or `.dbcli/queries/` (personal). Override is
+per-engine: a local `connections.postgres.sql` only shadows the postgres
+variant; the mysql variant is still served from builtin.

package/assets/snippets/diag/cache-hit.mysql.sql

@@ -0,0 +1,19 @@
+-- ---
+-- name: InnoDB buffer pool hit ratio (mysql)
+-- description: Reads from disk vs. read requests from the buffer pool.
+-- engine: mysql
+-- ---
+SELECT
+  (SELECT VARIABLE_VALUE FROM performance_schema.global_status
+    WHERE VARIABLE_NAME = 'Innodb_buffer_pool_reads')          AS pool_reads,
+  (SELECT VARIABLE_VALUE FROM performance_schema.global_status
+    WHERE VARIABLE_NAME = 'Innodb_buffer_pool_read_requests')  AS pool_read_requests,
+  ROUND(
+    1 -
+    (SELECT VARIABLE_VALUE FROM performance_schema.global_status
+       WHERE VARIABLE_NAME = 'Innodb_buffer_pool_reads')
+    /
+    NULLIF(
+      (SELECT VARIABLE_VALUE FROM performance_schema.global_status
+         WHERE VARIABLE_NAME = 'Innodb_buffer_pool_read_requests'), 0)
+  , 4) AS hit_ratio;

package/assets/snippets/diag/cache-hit.postgres.sql

@@ -0,0 +1,18 @@
+-- ---
+-- name: Cache hit ratio (postgres)
+-- description: Heap and index buffer cache hit ratios across user tables.
+-- engine: postgres
+-- ---
+SELECT SUM(heap_blks_read)                                                       AS heap_read,
+       SUM(heap_blks_hit)                                                        AS heap_hit,
+       ROUND(
+         SUM(heap_blks_hit)::numeric
+         / NULLIF(SUM(heap_blks_hit) + SUM(heap_blks_read), 0)
+       , 4)                                                                      AS heap_hit_ratio,
+       SUM(idx_blks_read)                                                        AS idx_read,
+       SUM(idx_blks_hit)                                                         AS idx_hit,
+       ROUND(
+         SUM(idx_blks_hit)::numeric
+         / NULLIF(SUM(idx_blks_hit) + SUM(idx_blks_read), 0)
+       , 4)                                                                      AS idx_hit_ratio
+FROM   pg_statio_user_tables;

package/assets/snippets/diag/connections.mysql.sql

@@ -0,0 +1,16 @@
+-- ---
+-- name: Active connections (mysql)
+-- description: Non-sleep processes ordered by elapsed time.
+-- engine: mysql
+-- ---
+SELECT id,
+       user,
+       host,
+       db,
+       command,
+       time AS duration_seconds,
+       state,
+       info AS query
+FROM   information_schema.processlist
+WHERE  command <> 'Sleep'
+ORDER  BY time DESC;

package/assets/snippets/diag/connections.postgres.sql

@@ -0,0 +1,16 @@
+-- ---
+-- name: Active connections (postgres)
+-- description: Active sessions excluding idle, ordered by query start.
+-- engine: postgres
+-- ---
+SELECT pid,
+       usename                              AS user,
+       application_name                     AS app,
+       client_addr                          AS client,
+       state,
+       NOW() - query_start                  AS duration,
+       query
+FROM   pg_stat_activity
+WHERE  state IS NOT NULL
+  AND  state <> 'idle'
+ORDER  BY query_start;

package/assets/snippets/diag/db-size.mysql.sql

@@ -0,0 +1,10 @@
+-- ---
+-- name: Database size (mysql)
+-- description: Total data + index size per schema in MB.
+-- engine: mysql
+-- ---
+SELECT table_schema                                          AS `database`,
+       ROUND(SUM(data_length + index_length) / 1024 / 1024, 2) AS size_mb
+FROM   information_schema.tables
+GROUP  BY table_schema
+ORDER  BY size_mb DESC;

package/assets/snippets/diag/db-size.postgres.sql

@@ -0,0 +1,9 @@
+-- ---
+-- name: Database size (postgres)
+-- description: Each database with pretty-printed total size.
+-- engine: postgres
+-- ---
+SELECT datname                                AS database,
+       pg_size_pretty(pg_database_size(datname)) AS size
+FROM   pg_database
+ORDER  BY pg_database_size(datname) DESC;

package/assets/snippets/diag/index-usage.mysql.sql

@@ -0,0 +1,15 @@
+-- ---
+-- name: Index usage (mysql)
+-- description: Index I/O wait counts ordered by total uses.
+-- engine: mysql
+-- ---
+SELECT object_schema  AS `schema`,
+       object_name    AS `table`,
+       index_name,
+       count_star     AS uses,
+       count_read     AS reads,
+       count_write    AS writes
+FROM   performance_schema.table_io_waits_summary_by_index_usage
+WHERE  object_schema NOT IN ('mysql','performance_schema','sys')
+  AND  index_name IS NOT NULL
+ORDER  BY count_star ASC;

package/assets/snippets/diag/index-usage.postgres.sql

@@ -0,0 +1,14 @@
+-- ---
+-- name: Index usage (postgres)
+-- description: Indexes ordered by scan count (low scans = candidates to drop).
+-- engine: postgres
+-- ---
+SELECT schemaname                              AS schema,
+       relname                                 AS table,
+       indexrelname                            AS index,
+       idx_scan                                AS scans,
+       idx_tup_read                            AS tuples_read,
+       idx_tup_fetch                           AS tuples_fetched,
+       pg_size_pretty(pg_relation_size(indexrelid)) AS index_size
+FROM   pg_stat_user_indexes
+ORDER  BY idx_scan ASC;

package/assets/snippets/diag/locks.mysql.sql

@@ -0,0 +1,14 @@
+-- ---
+-- name: Lock waits (mysql)
+-- description: InnoDB lock waits with waiting and blocking transactions.
+-- engine: mysql
+-- ---
+SELECT waiting.trx_mysql_thread_id  AS waiting_thread,
+       waiting.trx_query            AS waiting_query,
+       blocking.trx_mysql_thread_id AS blocking_thread,
+       blocking.trx_query           AS blocking_query
+FROM   performance_schema.data_lock_waits AS w
+JOIN   information_schema.innodb_trx AS waiting
+       ON w.requesting_engine_transaction_id = waiting.trx_id
+JOIN   information_schema.innodb_trx AS blocking
+       ON w.blocking_engine_transaction_id = blocking.trx_id;

package/assets/snippets/diag/locks.postgres.sql

@@ -0,0 +1,15 @@
+-- ---
+-- name: Lock waits (postgres)
+-- description: Sessions blocked by other sessions with both queries shown.
+-- engine: postgres
+-- ---
+SELECT blocked.pid       AS blocked_pid,
+       blocked.usename   AS blocked_user,
+       blocked.query     AS blocked_query,
+       blocking.pid      AS blocking_pid,
+       blocking.usename  AS blocking_user,
+       blocking.query    AS blocking_query
+FROM   pg_stat_activity AS blocked
+JOIN   pg_stat_activity AS blocking
+       ON blocking.pid = ANY(pg_blocking_pids(blocked.pid))
+WHERE  blocked.pid <> blocking.pid;

package/assets/snippets/diag/long-running.mysql.sql

@@ -0,0 +1,14 @@
+-- ---
+-- name: Long-running queries (mysql)
+-- description: Non-sleep processes whose elapsed time exceeds min_seconds.
+-- engine: mysql
+-- params:
+--   min_seconds:
+--     type: int
+--     default: 30
+-- ---
+SELECT id, user, host, db, time AS duration_seconds, state, info AS query
+FROM   information_schema.processlist
+WHERE  command <> 'Sleep'
+  AND  time > :min_seconds
+ORDER  BY time DESC;

package/assets/snippets/diag/long-running.postgres.sql

@@ -0,0 +1,19 @@
+-- ---
+-- name: Long-running queries (postgres)
+-- description: Queries running longer than min_seconds.
+-- engine: postgres
+-- params:
+--   min_seconds:
+--     type: int
+--     default: 30
+-- ---
+SELECT pid,
+       usename                              AS user,
+       NOW() - query_start                  AS duration,
+       state,
+       query
+FROM   pg_stat_activity
+WHERE  state IS NOT NULL
+  AND  state <> 'idle'
+  AND  NOW() - query_start > make_interval(secs => :min_seconds)
+ORDER  BY duration DESC;

package/assets/snippets/diag/missing-indexes.mysql.sql

@@ -0,0 +1,13 @@
+-- ---
+-- name: Missing indexes (mysql)
+-- description: Tables with significant full-scan I/O and no index used.
+-- engine: mysql
+-- ---
+SELECT object_schema  AS `schema`,
+       object_name    AS `table`,
+       count_read     AS full_scan_reads
+FROM   performance_schema.table_io_waits_summary_by_index_usage
+WHERE  index_name IS NULL
+  AND  object_schema NOT IN ('mysql','performance_schema','sys')
+  AND  count_read > 1000
+ORDER  BY count_read DESC;

package/assets/snippets/diag/missing-indexes.postgres.sql

@@ -0,0 +1,15 @@
+-- ---
+-- name: Missing indexes (postgres)
+-- description: User tables where seq scans dominate over index scans (>1k rows).
+-- engine: postgres
+-- ---
+SELECT schemaname     AS schema,
+       relname        AS table,
+       seq_scan,
+       seq_tup_read,
+       idx_scan,
+       n_live_tup     AS estimated_rows
+FROM   pg_stat_user_tables
+WHERE  seq_scan > COALESCE(idx_scan, 0)
+  AND  n_live_tup > 1000
+ORDER  BY seq_tup_read DESC;