@carllee1983/dbcli 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to dbcli are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.7.0] - 2026-05-04
+
+### Added
+
+- `dbcli q @<name>` 執行已保存的參數化 SELECT 片段
+- `dbcli queries list/show/new/edit/check` 管理片段
+- 兩層片段儲存：`.dbcli-shared/queries/`（共享）+ `.dbcli/queries/`（個人覆蓋）
+- 完整安全 invariants：拒絕非 SELECT/WITH、多語句、`${...}` / `{{...}}` 模板語法
+- 子查詢式 size guard 包裹 (`SELECT * FROM (...) AS _dbcli_guard LIMIT 1000`)
+- 內建 YAML 子集 frontmatter parser（無新增 npm 依賴）
+- `queries list/show --format json` 為未來 MCP server 預留契約
+
 ## [1.6.0] - 2026-04-23
 
 ### Added

package/README.md

@@ -114,6 +114,8 @@ dbcli query '{"status":"active"}' --collection users --use atlas
 
 For MongoDB, `list` and `query` operate on the database configured for the connection, and `query` requires `--collection <name>`.
 
+For a command-by-command support matrix across PostgreSQL, MySQL, MariaDB, and MongoDB, see [docs/feature-matrix.md](./docs/feature-matrix.md).
+
 ---
 
 ## Multi-connection Support (v2)
@@ -769,6 +771,43 @@ dbcli migrate drop-enum status --execute --force
 
 ---
 
+## Query Risk Planning
+
+Use `plan` to inspect SQL safety before execution. It reads local dbcli config, permissions, blacklist rules, and cached schema metadata only; it does not connect to the database.
+
+```bash
+dbcli plan "UPDATE users SET status='inactive'" --format json
+```
+
+Decisions are:
+
+- `ALLOW` — no obvious risk was detected.
+- `WARN` — inspect warnings before executing.
+- `BLOCK` — unsafe, unsupported, or violates configured safety constraints.
+
+Text output is concise for humans:
+
+```text
+Decision: BLOCK
+Operation: UPDATE
+Target tables: users
+
+Risk factors:
+- UPDATE statement has no WHERE clause.
+
+Recommendations:
+- Add a WHERE clause.
+- Use --dry-run on the actual write command.
+```
+
+JSON output includes `suggestedCommands` for agents:
+
+```bash
+dbcli plan "SELECT id FROM users WHERE id = 1 LIMIT 1" --format json
+```
+
+---
+
 ## Global Options
 
 All commands support these global options:
@@ -957,6 +996,22 @@ A Query-only agent cannot write to any table, and also cannot read blacklisted t
 
 ---
 
+## Saved queries
+
+Save parameterised SELECT snippets and re-run them by name:
+
+```bash
+dbcli queries list
+dbcli queries show @dau
+dbcli q @dau --param days=30 --format json
+```
+
+Snippets live in `.dbcli-shared/queries/` (committed) or `.dbcli/queries/`
+(gitignored, personal override). Each `.sql` file declares its frontmatter
+in a `-- ---` block. Read `assets/reference.md` for the full schema.
+
+---
+
 ## AI Integration Guide
 
 dbcli ships AI-consumable skill files (`assets/SKILL.md` and `assets/reference.md`) and can copy them into your favorite AI tool directories.
@@ -1258,12 +1313,15 @@ chmod +x dist/cli.mjs
 
 ```bash
 bun test                  # full test suite (Bun test runner)
+bun run typecheck         # TypeScript compile-time validation
 bun run test:unit         # unit + core tests only
 bun run test:integration  # integration tests
 bun run test:docker       # integration tests with docker-compose.test.yml (MySQL + PostgreSQL)
 bun run build             # bundle CLI to dist/ (used before publish)
 ```
 
+CI treats `bun run typecheck` and `bun test` as the required pass/fail validation gate on every push and pull request. Lint, build, smoke checks, and benchmarks run in addition to that gate.
+
 Live database integration tests use `.dbcli/config.json` by default. If your live
 config lives elsewhere, set `LIVE_DB_CONFIG_PATH=/path/to/.dbcli` before running:
 

package/README.zh-TW.md

@@ -779,6 +779,43 @@ dbcli migrate drop-enum status --execute --force
 
 ---
 
+## 查詢風險規劃
+
+使用 `plan` 在執行前檢查 SQL 安全性。它只讀取本機 dbcli 設定、權限、黑名單規則與已快取的 schema metadata；不會連線到資料庫。
+
+```bash
+dbcli plan "UPDATE users SET status='inactive'" --format json
+```
+
+決策結果：
+
+- `ALLOW` — 未偵測到明顯風險。
+- `WARN` — 執行前應檢查警告。
+- `BLOCK` — 不安全、不支援，或違反安全設定。
+
+文字輸出保持精簡，適合人工閱讀：
+
+```text
+Decision: BLOCK
+Operation: UPDATE
+Target tables: users
+
+Risk factors:
+- UPDATE statement has no WHERE clause.
+
+Recommendations:
+- Add a WHERE clause.
+- Use --dry-run on the actual write command.
+```
+
+JSON 輸出會包含給 AI agent 使用的 `suggestedCommands`：
+
+```bash
+dbcli plan "SELECT id FROM users WHERE id = 1 LIMIT 1" --format json
+```
+
+---
+
 ## 全域選項
 
 所有指令皆支援下列全域選項：
@@ -963,6 +1000,23 @@ Query-only 代理無法寫入任何表，也無法讀取黑名單表或欄位
 
 ---
 
+## 已保存查詢片段（Saved queries）
+
+將參數化的 SELECT 片段保存於版控，並依名稱重複執行：
+
+```bash
+dbcli queries list
+dbcli queries show @dau
+dbcli q @dau --param days=30 --format json
+```
+
+片段位於兩層儲存：`.dbcli-shared/queries/`（commit 進版控、團隊共享）與
+`.dbcli/queries/`（gitignore、個人覆蓋）。每個 `.sql` 檔以 `-- ---` 區塊
+宣告 frontmatter（name、description、engine、params、tags），完整 schema 見
+`assets/reference.md`。
+
+---
+
 ## AI 整合指南
 
 dbcli 內建供 AI 使用的 skill 文件（`assets/SKILL.md` 與 `assets/reference.md`），並可複製到常見 AI 開發工具的目錄。

package/assets/SKILL.md

@@ -74,6 +74,48 @@ dbcli query "SELECT * FROM users"   # Execute SQL (auto LIMIT 1000)
 - No auto-limit on MongoDB queries — use `$limit` in the pipeline if needed.
 - See reference.md MongoDB section for full syntax and examples.
 
+## Saved queries
+
+Run reusable parameterised SELECT snippets stored in your repo.
+
+| Step | Command |
+|------|---------|
+| 1. Discover | `dbcli queries list` |
+| 2. Inspect | `dbcli queries show @<name>` |
+| 3. Run     | `dbcli q @<name> --param k=v` |
+
+Snippets resolve from three layers, **local > shared > builtin** (local wins):
+- `builtin` — bundled with dbcli (e.g. `@diag/*`); read-only at runtime
+- `.dbcli-shared/queries/` — committed, team-shared
+- `.dbcli/queries/` — gitignored, personal override
+
+Manage local snippets with `queries new | edit | delete | rename | copy | import | export`
+(see reference.md). Use `copy` / `import` to fork a builtin or shared snippet into the
+local layer for editing.
+
+Each `.sql` file may declare YAML frontmatter inside `-- ---` blocks
+(name, description, engine, params, tags). See `dbcli queries show @<name> --format json`
+for the machine-readable contract.
+
+### Built-in diagnostic snippets
+
+dbcli ships ready-made diagnostic queries. Run with `dbcli q @diag/<topic>`:
+
+| key                     | purpose                                  |
+|-------------------------|------------------------------------------|
+| `@diag/connections`     | active sessions                          |
+| `@diag/long-running`    | queries above `min_seconds` (default 30) |
+| `@diag/table-sizes`     | table data/index size with row counts    |
+| `@diag/index-usage`     | indexes by scan count                    |
+| `@diag/missing-indexes` | tables dominated by sequential scans     |
+| `@diag/locks`           | lock-wait chains                         |
+| `@diag/db-size`         | database size summary                    |
+| `@diag/cache-hit`       | buffer cache hit ratios                  |
+
+Engine variants are picked automatically based on the active connection.
+Override any of them by placing a same-named file under `.dbcli-shared/queries/`
+or `.dbcli/queries/`.
+
 ## Common workflows
 
 - **Debug odd state:** `schema` → `check` → `query` with tight `WHERE` → follow FKs from schema JSON. Evidence over theory.

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
@@ -114,6 +116,126 @@ dbcli query '[{"$match": {"status": "active"}}, {"$group": {"_id": "$role", "cou
 > - `--collection <name>` is required
 > - Auto-limit does not apply; use `$limit` in your pipeline if needed
 
+### 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 +460,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:**
 
-**Not supported (exit with error):** `schema`, `insert`, `update`, `delete`, `export`, `diff`, `migrate`, `check`
+- `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):** `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 +493,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

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;

package/assets/snippets/diag/table-sizes.mysql.sql

@@ -0,0 +1,14 @@
+-- ---
+-- name: Table sizes (mysql)
+-- description: Data + index size in MB with estimated row count.
+-- engine: mysql
+-- ---
+SELECT table_schema                                              AS `schema`,
+       table_name                                                AS `table`,
+       ROUND((data_length + index_length) / 1024 / 1024, 2)      AS total_mb,
+       ROUND(data_length / 1024 / 1024, 2)                       AS data_mb,
+       ROUND(index_length / 1024 / 1024, 2)                      AS index_mb,
+       table_rows                                                AS estimated_rows
+FROM   information_schema.tables
+WHERE  table_schema NOT IN ('mysql','information_schema','performance_schema','sys')
+ORDER  BY data_length + index_length DESC;