@carllee1983/dbcli 1.5.2 → 1.7.0

package/assets/reference.md

@@ -0,0 +1,510 @@
+# dbcli — full command reference
+
+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
+
+Initialize `.dbcli` configuration file. Typically run manually by the developer — avoid running on behalf of the user unless explicitly requested.
+
+```bash
+dbcli init                                              # Single connection (v1 format)
+dbcli init --system mysql --host localhost --port 3306 --user root --name mydb
+dbcli init --use-env-refs                               # Store env var references
+dbcli init --no-interactive --force                     # Non-interactive mode
+
+# MongoDB
+dbcli init --system mongodb --uri "mongodb://user:pass@host:27017/mydb?authSource=admin"
+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
+
+# 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
+dbcli init --remove staging                              # Remove a named connection
+dbcli init --rename staging:production                   # Rename a connection
+```
+
+**Key options:** `--system`, `--permission`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`, `--conn-name <name>`, `--env-file <path>`, `--remove <name>`, `--rename <old:new>`
+
+**MongoDB-specific options:** `--uri <uri>` (full connection URI), `--auth-source <db>` (auth database, default: `admin` when user/password set)
+
+**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.
+
+### use
+
+Switch or display the default database connection (v2 multi-connection config).
+
+```bash
+dbcli use                   # Show current default connection
+dbcli use staging           # Switch default to 'staging'
+dbcli use --list            # List all connections (* marks default)
+```
+
+Any command can also use `--use <name>` to temporarily select a connection without changing the default:
+
+```bash
+dbcli query --use staging "SELECT * FROM users LIMIT 10"
+dbcli list --use prod
+```
+
+**Requires v2 config** (created with `dbcli init --conn-name`).
+
+### list
+
+List all tables (SQL) or collections (MongoDB).
+
+```bash
+dbcli list
+dbcli list --format json
+```
+
+**Permission:** query-only+
+
+> **MongoDB:** Lists collections with estimated document count instead of tables.
+
+### schema
+
+Display table schema or scan entire database.
+
+```bash
+dbcli schema                        # Scan all tables, save to .dbcli/schemas/
+dbcli schema users                  # Show single table schema
+dbcli schema users --format json
+dbcli schema --refresh              # Detect and apply schema changes
+dbcli schema --reset                # Clear all schema data and re-fetch
+dbcli schema --reset --force        # Skip confirmation
+
+# Per-connection schema isolation (v2 multi-connection config)
+dbcli schema --use staging          # Scan staging DB; saves to .dbcli/schemas/staging/
+dbcli schema --use prod             # Scan prod DB; saves to .dbcli/schemas/prod/
+```
+
+**Options:** `--format <table|json>`, `--refresh`, `--reset`, `--force`, `--use <connection>`
+**Permission:** query-only+
+
+**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.
+
+### query
+
+Execute SQL query (MySQL/PostgreSQL/MariaDB) or JSON filter/pipeline (MongoDB).
+
+```bash
+# SQL databases
+dbcli query "SELECT * FROM users LIMIT 10"
+dbcli query "SELECT id, email FROM users" --format json
+dbcli query "SELECT * FROM logs" --no-limit
+
+# MongoDB: JSON filter (find)
+dbcli query '{"status": "active"}' --collection users
+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
+```
+
+**Options:** `--format <table|json|csv>`, `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB only)
+**Permission:** query-only+
+
+> **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
+
+### 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.
+
+```bash
+dbcli insert users --data '{"name":"Alice","email":"alice@example.com"}'
+dbcli insert users --data '{"name":"Alice"}' --dry-run
+dbcli insert users --data '{"name":"Alice"}' --force
+```
+
+**Options:** `--data <json>`, `--dry-run`, `--force`
+**Permission:** read-write+
+
+### update
+
+Update existing data.
+
+```bash
+dbcli update users --where "id=1" --set '{"name":"Bob"}'
+dbcli update users --where "id=1" --set '{"name":"Bob"}' --dry-run
+```
+
+**Options:** `--where <condition>` (required), `--set <json>` (required), `--dry-run`, `--force`
+**Permission:** read-write+
+
+### delete
+
+Delete data from a table.
+
+```bash
+dbcli delete users --where "id=1"
+dbcli delete users --where "id=1" --dry-run
+dbcli delete users --where "id=1" --force
+```
+
+**Options:** `--where <condition>` (required), `--dry-run`, `--force`
+**Permission:** data-admin+
+
+### export
+
+Export query results to file or stdout.
+
+```bash
+dbcli export "SELECT * FROM users" --format csv --output users.csv
+dbcli export "SELECT * FROM users" --format csv --output users.csv --force  # Skip overwrite confirmation
+dbcli export "SELECT * FROM users" --format json | jq '.[]'
+```
+
+**Options:** `--format <json|csv>` (required), `--output <path>`, `--force`
+**Permission:** query-only+
+
+### blacklist
+
+Manage sensitive data blacklist to prevent AI access to restricted tables/columns.
+
+```bash
+dbcli blacklist list                        # Show current blacklist
+dbcli blacklist table add payments          # Block entire table
+dbcli blacklist table remove payments       # Unblock table
+dbcli blacklist column add users.password   # Block specific column
+dbcli blacklist column remove users.password
+```
+
+**Subcommands:** `list`, `table add <name>`, `table remove <name>`, `column add <table.column>`, `column remove <table.column>`
+
+### check
+
+Run data health checks on tables.
+
+```bash
+dbcli check users                           # Check single table
+dbcli check users --format json             # JSON output (default)
+dbcli check --all                           # Check all tables (huge tables auto-skipped)
+dbcli check --all --include-large           # Include huge tables
+dbcli check orders --checks nulls,orphans   # Specific checks only
+dbcli check orders --sample 10000           # Sample size for large tables
+```
+
+**Checks:** `nulls`, `duplicates`, `orphans`, `emptyStrings`, `rowCount`, `size`
+**Options:** `--all`, `--include-large`, `--checks <types>`, `--sample <number>`, `--format <json|table>`
+**Permission:** query-only+
+
+### diff
+
+Compare schema snapshots to detect changes.
+
+```bash
+dbcli diff --snapshot before.json           # Save current schema snapshot
+dbcli diff --against before.json            # Compare current vs snapshot
+dbcli diff --against before.json --format json
+```
+
+**Options:** `--snapshot <path>`, `--against <path>`, `--format <json|table>`
+**Permission:** query-only+
+
+### status
+
+Show current configuration status (safe for AI agents, no credentials exposed).
+
+```bash
+dbcli status                    # JSON output (default)
+dbcli status --format text      # Human-readable text output
+```
+
+**Output:** `permission`, `system`, `blacklist` summary, `version`
+**Permission:** query-only+
+
+### doctor
+
+Run diagnostic checks on environment, configuration, connection, and data.
+
+```bash
+dbcli doctor                    # Colored text output
+dbcli doctor --format json      # JSON output for AI agents
+```
+
+**Checks:**
+- Environment: Bun version, dbcli version (compares with npm registry)
+- Configuration: config file exists/valid, permission level, blacklist completeness (detects unprotected sensitive columns)
+- Connection & Data: database connectivity, schema cache freshness (warns if > 7 days), large table warnings (> 1M rows)
+
+> **MongoDB SRV diagnostics:** When the active connection uses `mongodb+srv://`, `doctor` reports whether the current runtime can resolve SRV records directly or only through the DNS-over-HTTPS fallback used by dbcli. This helps spot execution-environment DNS restrictions even when Compass can connect.
+
+**Exit code:** 0 if all pass or warnings only, 1 if any error
+**Options:** `--format <text|json>`
+
+### completion
+
+Generate shell completion scripts for tab auto-complete.
+
+```bash
+dbcli completion bash            # Output bash completion script
+dbcli completion zsh             # Output zsh completion script
+dbcli completion fish            # Output fish completion script
+dbcli completion --install       # Auto-detect shell and install
+dbcli completion --install zsh   # Install for specific shell
+```
+
+**Supported shells:** bash, zsh, fish
+
+### upgrade
+
+Check for updates and self-upgrade dbcli to the latest version from npm.
+
+```bash
+dbcli upgrade                   # Check and upgrade if newer version available
+dbcli upgrade --check           # Only check, do not upgrade
+```
+
+**Options:** `--check`
+
+**Background check:** Every command silently checks the npm registry for a newer version (at most once per 24 hours, cached in `.dbcli/version-check.json`). If a newer version is found, a one-line hint is printed to stderr after the command completes. Pass `-q` / `--quiet` to suppress the hint.
+
+### `dbcli shell`
+
+Start an interactive database shell.
+
+```bash
+dbcli shell          # Interactive mode with SQL + dbcli commands
+dbcli shell --sql    # SQL-only mode
+```
+
+Inside the shell:
+- Type SQL statements ending with `;` to execute
+- Type dbcli commands without the `dbcli` prefix (e.g., `schema users`)
+- Use Tab for auto-completion (SQL keywords, table names, column names)
+- Type `.help` for meta commands (.quit, .clear, .format, .history, .timing)
+- Multi-line SQL: keeps accumulating until `;` is found
+- History persists across sessions (~/.dbcli_history)
+
+### migrate
+
+Schema DDL operations. **All commands default to dry-run** — use `--execute` to actually run the SQL. Destructive operations (DROP) also require `--force`.
+
+```bash
+# Create table
+dbcli migrate create posts \
+  --column "id:serial:pk" \
+  --column "title:varchar(200):not-null" \
+  --column "body:text" \
+  --column "created_at:timestamp:default=now()"
+
+# Drop table (dry-run by default)
+dbcli migrate drop posts
+dbcli migrate drop posts --execute --force   # Actually drop
+
+# Add/drop/alter column
+dbcli migrate add-column users bio text --nullable
+dbcli migrate drop-column users temp_field --execute --force
+dbcli migrate alter-column users name --type "varchar(200)"
+dbcli migrate alter-column users email --rename user_email
+dbcli migrate alter-column users status --set-default "'active'"
+dbcli migrate alter-column users bio --drop-default
+dbcli migrate alter-column users bio --set-nullable
+dbcli migrate alter-column users email --drop-nullable
+
+# Index management
+dbcli migrate add-index users --columns email --unique
+dbcli migrate add-index users --columns "last_name,first_name" --name idx_fullname
+dbcli migrate drop-index idx_fullname --execute --force
+
+# Constraint management
+dbcli migrate add-constraint orders --fk user_id --references users.id --on-delete cascade
+dbcli migrate add-constraint users --unique email
+dbcli migrate add-constraint users --check "age >= 0"
+dbcli migrate drop-constraint orders fk_orders_user_id --execute --force
+
+# Enum (PostgreSQL only — MySQL uses inline ENUM in column type)
+dbcli migrate add-enum status active inactive suspended
+dbcli migrate alter-enum status --add-value archived
+dbcli migrate drop-enum status --execute --force
+```
+
+**Column spec format:** `name:type[:modifier[:modifier...]]`
+- Modifiers: `pk`, `not-null`, `unique`, `auto-increment`, `default=<value>`, `references=<table>.<column>`
+- Serial types: `serial`, `bigserial`, `smallserial` (auto-expand per DB dialect)
+
+**Options (all subcommands):** `--execute`, `--force`, `--config <path>`
+**Permission:** admin
+
+**AI agent note:** Always use dry-run first (no `--execute`) to preview generated SQL. Only add `--execute` after confirming the SQL is correct. For DROP operations, both `--execute` and `--force` are required.
+
+## MongoDB Support
+
+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`, `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):** `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
+
+```bash
+# 1. Initialize (URI or individual params)
+dbcli init --system mongodb --uri "mongodb+srv://user:pass@cluster.example.mongodb.net/mydb"
+
+# 2. List collections
+dbcli list --format json
+
+# 3. Query with JSON filter (find) or pipeline (aggregate)
+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
+
+| Intent | Syntax |
+|--------|--------|
+| All documents | `'{}'` |
+| Field filter | `'{"field": "value"}'` |
+| Comparison | `'{"age": {"$gt": 18}}'` |
+| Aggregation | `'[{"$match": {...}}, {"$group": {...}}]'` |

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;