@carllee1983/dbcli 1.46.0 → 1.47.1

package/skills/dbcli/reference.md

@@ -19,6 +19,28 @@ command-level option is only valid after the command that declares it.
 | `--config <path>` | Select the `.dbcli` configuration path. |
 | `--global` | Select the user-global registry at `~/.config/dbcli/config.json` instead of the current project's `.dbcli` config. Place it before the command path. |
 | `--use <connection>` | Select a named connection for this invocation; place it before the command path unless that command explicitly lists a command-level `--use`. |
+| `--timeout <ms>` | Connection timeout in milliseconds (integer, 100–600000), overriding the connection config's `timeout` field for this invocation. Applies to every engine adapter. Without either the flag or the config field, adapters fall back to their built-in 5000ms default. |
+
+`--timeout` is applied only when the adapter is constructed for this invocation — it is
+never written back to `config.json`. Set the connection's `timeout` field instead for a
+value that persists across runs. On PostgreSQL, the same value is also used as the
+session's `statement_timeout` (not just the connection timeout), so a low value can cut
+off a long-running query with an error that looks like a connection timeout; the 100ms
+floor exists specifically to keep that failure mode from being too easy to trigger.
+Elasticsearch applies its timeout per request rather than once for the whole connection.
+The `timeout` field itself always takes a literal number — unlike other connection
+fields, it does not accept an `{"$env": "..."}` reference.
+
+### Redirecting output
+
+Results go to stdout; diagnostics (auto-limit notices, warnings, update hints) go to
+stderr. That split is what keeps `--format json` machine-parseable, so do not collapse
+it with `2>&1` — the diagnostic lines land in front of the JSON document and the parse
+fails. Pipe stdout alone, or add `2>/dev/null` when the diagnostics are not wanted:
+
+```bash
+dbcli query '{}' --collection events --format json 2>/dev/null | jq '.rows | length'
+```
 
 ## Commands
 
@@ -118,6 +140,10 @@ agent mode disabled. A host that needs protection from a same-user hostile
 process can set `DBCLI_CONFIG_INTEGRITY_ANCHOR_DIR` to a protected or read-only
 directory; trusted writes publish detached digests there.
 
+When a connection's config fails schema validation, dbcli reports the specific field
+path(s) that are wrong for that connection's declared `system` — not the raw Zod union
+error tree — so a broken `.dbcli` can be fixed without guessing which branch applies.
+
 ### list
 
 List all tables (SQL), collections (MongoDB), keys (Redis), or indices (Elasticsearch).
@@ -197,6 +223,13 @@ dbcli query "SELECT * FROM orders" --format html > orders.html   # pipe to stdou
 **Options:** `--format <table|json|csv|html>`, `--ui` (open the dashboard in the system browser; implies `--format html`), `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`), `--fields <list>`, `--truncate <number>` / `--no-truncate`, `-f, --query-file <path>`, `--use <name[,name]>`, `--recovery`
 **Permission:** query-only+ (Redis: per-command; Elasticsearch: per HTTP method/path)
 
+Below `admin`, SQL holding more than one statement is rejected, because only the
+first statement would decide the permission check while a driver on the simple
+query protocol executes them all. Semicolons inside string literals, backtick
+identifiers, and `#` comments are not separators. A MongoDB pipeline containing
+`$out` or `$merge` requires `data-admin`, and is rejected outright on `export`,
+in snippets, and in multi-connection fan-out.
+
 #### Field projection (`--fields`)
 
 ```bash
@@ -253,7 +286,7 @@ instead of silently running its only connection.
 An explicit comma-separated `--use primary,staging` fans one query out to several named
 connections. `DBCLI_CONNECTION` always names one literal connection and never enables
 fan-out. SQL permits `SELECT`, `SHOW`, `DESCRIBE`, and `EXPLAIN`; MongoDB permits filters and
-read-only pipelines without top-level `$out` / `$merge`; Elasticsearch permits searches.
+read-only pipelines without `$out` / `$merge`; Elasticsearch permits searches.
 Redis, writes, `--recovery`, `--ui`, CSV, and HTML are rejected before execution. Each
 connection keeps its own blacklist, limit metadata, audit entry, and error. Aggregate exit
 codes are `0` when all succeed, `2` for mixed outcomes, and `1` when all fail or preflight
@@ -505,6 +538,13 @@ dbcli q @analytics/revenue --param days=30 --format html > report.html
 
 Each `.sql` file is plain SQL with optional YAML frontmatter inside a leading `-- ---` block. Lines outside frontmatter form the SQL body.
 
+Snippets are read-only by contract, at every permission level including `admin`.
+A body must be a single statement opening with `SELECT` or `WITH` **and** free of
+write or DDL keywords, so a data-modifying CTE (`WITH x AS (DELETE … RETURNING *)
+SELECT * FROM x`) and `SELECT … INTO` are rejected at parse time rather than at
+execution. A MongoDB body may not contain `$out` or `$merge`. The same rule
+applies to `verify.query` in frontmatter, which `q --verify` executes verbatim.
+
 ```sql
 -- ---
 -- name: DAU
@@ -2605,6 +2645,8 @@ MongoDB connections use a JSON-based query model instead of SQL. Treat MongoDB s
 
 `init --system mongodb` defaults to a field-by-field wizard (`host`, `srv`, `port`, `user`, `password` + `authSource`, then optional `replicaSet` / `tls`); a full `uri` is an explicit advanced choice in the interactive flow and the unchanged non-interactive path via `--uri`. Optional fields `authSource`, `replicaSet`, `tls`, and `srv` express what previously required embedding options in the `uri` query string. Atlas-style `mongodb+srv://` URIs are supported both as a full `uri` and via the per-field `srv: true` option. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
 
+The 5000ms default server-selection timeout is often too tight for a connection over a VPN or to Atlas. Set a `timeout` field (ms) in the connection config, or override it per invocation with root-level `--timeout`, e.g. `dbcli --timeout 20000 --use <conn> list`.
+
 **Supported commands:** `init`, `use`, `list`, `schema`, `query`, `q`, `insert`, `update`, `delete`, `export`, `status`, `shell`, `doctor`, `upgrade`, `completion`
 
 **Limited support:**
@@ -2669,7 +2711,7 @@ Redis connections speak Redis commands rather than SQL. The adapter uses Bun's n
 
 - 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 the client's `connectionTimeout`.
+- `connection.timeout` (ms, default 5000) maps to the client's `connectionTimeout`; root-level `--timeout <ms>` overrides it for a single invocation.
 
 ### Permission classification
 
@@ -2799,7 +2841,7 @@ Elasticsearch connections speak the REST API. The adapter is fetch-based (no SDK
 - 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.
+- `connection.timeout` (ms, default 5000) is wired to `AbortController` on every request; root-level `--timeout <ms>` overrides it for a single invocation.
 
 ### Permission classification