@carllee1983/dbcli 1.46.0 → 1.47.1

package/dist/core.mjs

@@ -16725,9 +16725,22 @@ class ElasticsearchAdapter {
   }
 }
 
+// src/utils/connection-timeout.ts
+var _globalConnectionTimeout;
+function resolveConnectionTimeout(configured) {
+  return _globalConnectionTimeout ?? configured;
+}
+function withResolvedTimeout(options) {
+  const timeout = resolveConnectionTimeout(options.timeout);
+  if (timeout === options.timeout)
+    return options;
+  return { ...options, timeout };
+}
+
 // src/adapters/factory.ts
 class AdapterFactory {
-  static createSqlAdapter(options) {
+  static createSqlAdapter(rawOptions) {
+    const options = withResolvedTimeout(rawOptions);
     switch (options.system) {
       case "postgresql":
         return new PostgreSQLAdapter(options);
@@ -16738,7 +16751,8 @@ class AdapterFactory {
         throw new Error(`createSqlAdapter requires a SQL system, got: ${options.system}`);
     }
   }
-  static createQueryableAdapter(options) {
+  static createQueryableAdapter(rawOptions) {
+    const options = withResolvedTimeout(rawOptions);
     switch (options.system) {
       case "mongodb":
         return new MongoDBAdapter(options);
@@ -16770,10 +16784,11 @@ class AdapterFactory {
     }
     return AdapterFactory.createQueryableAdapter(options);
   }
-  static createRedisAdapter(options, blacklistRules = [], maskRules = []) {
-    if (options.system !== "redis") {
+  static createRedisAdapter(rawOptions, blacklistRules = [], maskRules = []) {
+    if (rawOptions.system !== "redis") {
       throw new Error("createRedisAdapter requires system: redis");
     }
+    const options = withResolvedTimeout(rawOptions);
     const adapter = new RedisAdapter(options);
     adapter.setBlacklistRules(blacklistRules);
     adapter.setMaskRules(maskRules);
@@ -16802,6 +16817,7 @@ function normalizeSQL(sql) {
   return sql.replace(/--[^\n]*\n/g, `
 `).replace(/\/\*[\s\S]*?\*\//g, " ").trim().replace(/\s+/g, " ");
 }
+var IDENTIFIER_CONTINUATION = /[A-Za-z0-9_$]|[\u0080-\uFFFF]/;
 function stripCommentsAndStrings(sql, options = {}) {
   let result = "";
   let i = 0;
@@ -16844,11 +16860,19 @@ function stripCommentsAndStrings(sql, options = {}) {
         i = closingIndex === -1 ? sql.length : closingIndex + 2;
         continue;
       }
+      const nests = options.dialect === "postgresql";
+      let depth = 1;
       i += 2;
-      while (i < sql.length) {
+      while (i < sql.length && depth > 0) {
+        if (nests && sql[i] === "/" && sql[i + 1] === "*") {
+          depth++;
+          i += 2;
+          continue;
+        }
         if (sql[i] === "*" && sql[i + 1] === "/") {
+          depth--;
           i += 2;
-          break;
+          continue;
         }
         i++;
       }
@@ -16856,7 +16880,8 @@ function stripCommentsAndStrings(sql, options = {}) {
       continue;
     }
     if (options.dialect === "postgresql" && char === "$") {
-      const delimiter = sql.slice(i).match(/^\$(?:[A-Za-z_][A-Za-z0-9_]*)?\$/)?.[0];
+      const opensToken = !IDENTIFIER_CONTINUATION.test(sql[i - 1] ?? "");
+      const delimiter = opensToken ? sql.slice(i).match(/^\$(?:[A-Za-z_][A-Za-z0-9_]*)?\$/)?.[0] : undefined;
       if (delimiter) {
         i += delimiter.length;
         const closingIndex = sql.indexOf(delimiter, i);
@@ -16884,7 +16909,7 @@ function stripCommentsAndStrings(sql, options = {}) {
     if (char === "'" || char === '"') {
       const quote = char;
       const quoteIndex = i;
-      const postgresEscapeString = options.dialect === "postgresql" && quote === "'" && /[eE]/.test(sql[quoteIndex - 1] ?? "") && !/[A-Za-z0-9_$]/.test(sql[quoteIndex - 2] ?? "");
+      const postgresEscapeString = options.dialect === "postgresql" && quote === "'" && /[eE]/.test(sql[quoteIndex - 1] ?? "") && !IDENTIFIER_CONTINUATION.test(sql[quoteIndex - 2] ?? "");
       const backslashEscapes = options.dialect === undefined || postgresEscapeString;
       i++;
       while (i < sql.length) {
@@ -17060,8 +17085,59 @@ function classifyStatement(sql) {
     confidence: determineConfidence(type, firstKeyword, upper)
   };
 }
-function checkPermission(sql, permission) {
-  const classification = classifyStatement(sql);
+var SQL_DIALECTS = ["postgresql", "mysql", "mariadb"];
+var SQL_WRITE_OR_DDL_KEYWORDS = /(?<![.\w])(INSERT|UPDATE|DELETE|MERGE|UPSERT|REPLACE|TRUNCATE|DROP|ALTER|CREATE|GRANT|REVOKE|RENAME|INTO)\b(?!\s*\()/i;
+var SQL_LOCK_CLAUSE = /\bFOR\s+(?:NO\s+KEY\s+)?UPDATE\b|\bFOR\s+(?:KEY\s+)?SHARE\b/gi;
+function findWriteKeyword(sql, dialects) {
+  const candidates = dialects && dialects.length > 0 ? dialects : SQL_DIALECTS;
+  for (const dialect of candidates) {
+    const executable = stripCommentsAndStrings(sql, { dialect }).replace(SQL_LOCK_CLAUSE, " ");
+    const match = executable.match(SQL_WRITE_OR_DDL_KEYWORDS);
+    if (match?.[1])
+      return match[1].toUpperCase();
+  }
+  return;
+}
+function containsMultipleStatements(sql, dialect) {
+  const statementCount = (candidate) => stripCommentsAndStrings(sql, { dialect: candidate }).split(";").filter((part) => part.trim().length > 0).length;
+  if (dialect)
+    return statementCount(dialect) > 1;
+  return SQL_DIALECTS.some((candidate) => statementCount(candidate) > 1);
+}
+var ESCALATABLE_READ_TYPES = new Set(["SELECT", "EXPLAIN", "DESCRIBE"]);
+function escalateHiddenWrite(sql, classification, dialect) {
+  if (!ESCALATABLE_READ_TYPES.has(classification.type))
+    return classification;
+  const plansOnly = classification.type === "EXPLAIN" || classification.type === "DESCRIBE";
+  if (plansOnly && !/\bANALYZE\b/i.test(sql))
+    return classification;
+  const hidden = findWriteKeyword(sql, dialect ? [dialect] : undefined);
+  if (!hidden)
+    return classification;
+  return {
+    ...classification,
+    type: "UNKNOWN",
+    isDangerous: true,
+    confidence: "HIGH",
+    escalatedFrom: hidden
+  };
+}
+function checkPermission(sql, permission, dialect) {
+  const classification = escalateHiddenWrite(sql, classifyStatement(sql), dialect);
+  if (permission !== "admin" && containsMultipleStatements(sql, dialect)) {
+    return {
+      allowed: false,
+      reason: "SQL containing multiple statements is refused below admin permission, because only " + "the first statement determines the permission check. Run each statement separately.",
+      classification
+    };
+  }
+  if (permission !== "admin" && classification.escalatedFrom) {
+    return {
+      allowed: false,
+      reason: `This statement opens as a read but contains an executable ` + `${classification.escalatedFrom}. A write hidden inside a read statement ` + `requires admin permission (current level: ${permission}).`,
+      classification
+    };
+  }
   if (permission === "admin") {
     return {
       allowed: true,
@@ -17121,8 +17197,8 @@ function checkPermission(sql, permission) {
     classification
   };
 }
-function enforcePermission(sql, permission) {
-  const result = checkPermission(sql, permission);
+function enforcePermission(sql, permission, dialect) {
+  const result = checkPermission(sql, permission, dialect);
   if (!result.allowed) {
     throw new PermissionError(result.reason, result.classification, permission);
   }
@@ -21851,6 +21927,11 @@ var StringOrEnvRef = exports_external.union([exports_external.string().min(1), E
 var NumberOrEnvRef = exports_external.union([exports_external.number().int().min(1).max(65535), EnvRefSchema]);
 var OptStringOrEnvRef = exports_external.union([exports_external.string(), EnvRefSchema]).optional().default("");
 var OptNumberOrEnvRef = exports_external.union([exports_external.number().int(), EnvRefSchema]).optional().default(27017);
+var MIN_CONNECTION_TIMEOUT_MS = 100;
+var MAX_CONNECTION_TIMEOUT_MS = 600000;
+var TimeoutField = {
+  timeout: exports_external.number().int().min(MIN_CONNECTION_TIMEOUT_MS).max(MAX_CONNECTION_TIMEOUT_MS).optional()
+};
 var MongoDBConnectionConfigSchema = exports_external.object({
   system: exports_external.literal("mongodb"),
   uri: exports_external.union([exports_external.string(), EnvRefSchema]).optional(),
@@ -21862,7 +21943,8 @@ var MongoDBConnectionConfigSchema = exports_external.object({
   authSource: exports_external.union([exports_external.string(), EnvRefSchema]).optional(),
   replicaSet: exports_external.union([exports_external.string(), EnvRefSchema]).optional(),
   tls: exports_external.boolean().optional(),
-  srv: exports_external.boolean().optional().default(false)
+  srv: exports_external.boolean().optional().default(false),
+  ...TimeoutField
 });
 var SqlConnectionConfigSchema = exports_external.object({
   system: exports_external.enum(["postgresql", "mysql", "mariadb"]),
@@ -21870,7 +21952,8 @@ var SqlConnectionConfigSchema = exports_external.object({
   port: NumberOrEnvRef,
   user: StringOrEnvRef,
   password: exports_external.union([exports_external.string(), EnvRefSchema]).default(""),
-  database: StringOrEnvRef
+  database: StringOrEnvRef,
+  ...TimeoutField
 });
 var RedisConnectionConfigSchema = exports_external.object({
   system: exports_external.literal("redis"),
@@ -21878,7 +21961,8 @@ var RedisConnectionConfigSchema = exports_external.object({
   port: NumberOrEnvRef,
   user: OptStringOrEnvRef,
   password: exports_external.union([exports_external.string(), EnvRefSchema]).optional().default(""),
-  database: OptStringOrEnvRef
+  database: OptStringOrEnvRef,
+  ...TimeoutField
 });
 var ElasticsearchConnectionConfigSchema = exports_external.object({
   system: exports_external.literal("elasticsearch"),
@@ -21892,7 +21976,8 @@ var ElasticsearchConnectionConfigSchema = exports_external.object({
   cloudId: exports_external.union([exports_external.string(), EnvRefSchema]).optional(),
   apiKey: exports_external.union([exports_external.string(), EnvRefSchema]).optional(),
   caPath: exports_external.string().optional(),
-  rejectUnauthorized: exports_external.boolean().optional().default(true)
+  rejectUnauthorized: exports_external.boolean().optional().default(true),
+  ...TimeoutField
 });
 var ConnectionConfigSchema = exports_external.union([
   SqlConnectionConfigSchema,
@@ -21982,6 +22067,89 @@ var DbcliConfigV2Schema = exports_external.object({
   path: ["default"]
 });
 
+// src/utils/config-error-format.ts
+var SUPPORTED_SYSTEMS = [
+  "postgresql",
+  "mysql",
+  "mariadb",
+  "mongodb",
+  "redis",
+  "elasticsearch"
+];
+function isConnectionNode(raw, path) {
+  const last = path[path.length - 1];
+  const parent = path[path.length - 2];
+  if (last !== "connection" && parent !== "connections")
+    return false;
+  const node = valueAtPath(raw, path);
+  return typeof node === "object" && node !== null && !Array.isArray(node);
+}
+function valueAtPath(raw, path) {
+  let current = raw;
+  for (const key of path) {
+    if (current == null || typeof current !== "object")
+      return;
+    current = current[key];
+  }
+  return current;
+}
+function declaredSystem(raw, path) {
+  const node = valueAtPath(raw, path);
+  if (node == null || typeof node !== "object")
+    return;
+  const system = node.system;
+  return typeof system === "string" ? system : undefined;
+}
+function branchMatchesSystem(issues) {
+  return !issues.some((issue) => issue.path[issue.path.length - 1] === "system" && (issue.code === "invalid_literal" || issue.code === "invalid_enum_value" || issue.code === "invalid_type"));
+}
+function formatPath(path) {
+  return path.length > 0 ? path.join(".") : "(root)";
+}
+function flattenIssues(issues, raw, basePath = []) {
+  const flat = [];
+  for (const issue of issues) {
+    const fullPath = [...basePath, ...issue.path];
+    if (issue.code === "invalid_union") {
+      const system = declaredSystem(raw, fullPath);
+      const branches = issue.unionErrors.map((error) => error.issues);
+      const candidates = system ? branches.filter((branchIssues) => branchMatchesSystem(branchIssues)) : [];
+      if (isConnectionNode(raw, fullPath) && candidates.length === 0) {
+        flat.push({
+          path: formatPath([...fullPath, "system"]),
+          message: `must be one of ${SUPPORTED_SYSTEMS.join(" | ")}` + (system === undefined ? " (missing)" : ` (received '${system}')`)
+        });
+        continue;
+      }
+      const chosen = candidates[0] ?? branches.reduce((best, current) => current.length < best.length ? current : best, branches[0] ?? []);
+      flat.push(...flattenIssues(chosen, raw, basePath));
+      continue;
+    }
+    flat.push({ path: formatPath(fullPath), message: issue.message });
+  }
+  return flat;
+}
+function dedupe(issues) {
+  const seen = new Set;
+  return issues.filter((issue) => {
+    const key = `${issue.path}\x00${issue.message}`;
+    if (seen.has(key))
+      return false;
+    seen.add(key);
+    return true;
+  });
+}
+function formatConfigValidationError(error, raw) {
+  const issues = dedupe(flattenIssues(error.issues, raw));
+  if (issues.length === 0)
+    return error.message;
+  return issues.map((issue) => `  - ${issue.path}: ${issue.message}`).join(`
+`);
+}
+function isZodError(error) {
+  return error instanceof Error && error.name === "ZodError" && Array.isArray(error.issues);
+}
+
 // src/agent-core/env-loader.ts
 import { readFile as readFile3 } from "fs/promises";
 function parseEnvContent(content) {
@@ -22188,6 +22356,7 @@ function parseEnvPassword(content) {
 var configModule = {
   async read(path, connectionName, options = {}) {
     const effectiveConnectionName = connectionName ?? _globalConnectionName;
+    let rawForDiagnostics;
     try {
       const binding = await readProjectBinding(path);
       const storagePath = await resolveConfigStoragePath(path);
@@ -22213,6 +22382,7 @@ var configModule = {
           const content = await configFile.text();
           await assertConfigIntegrity(storagePath, content, { requireRecord: true });
           const config = JSON.parse(content);
+          rawForDiagnostics = config;
           if (detectConfigVersion(config) === 2) {
             const v2Config = DbcliConfigV2Schema.parse(config);
             const resolved = resolveConnection(v2Config, effectiveConnectionName);
@@ -22293,6 +22463,7 @@ var configModule = {
         assertNoConnectionSelectorOnV1(effectiveConnectionName);
         const content = await file.text();
         const raw = JSON.parse(content);
+        rawForDiagnostics = raw;
         const resolved = resolveEnvReferences(raw, process.env);
         return DbcliConfigSchema.parse(resolved);
       }
@@ -22303,6 +22474,10 @@ var configModule = {
     } catch (error) {
       if (error instanceof ConfigError)
         throw error;
+      if (isZodError(error)) {
+        throw new ConfigError(`Failed to read .dbcli config: \u8A2D\u5B9A\u5167\u5BB9\u4E0D\u7B26\u5408\u7D50\u69CB
+${formatConfigValidationError(error, rawForDiagnostics)}`);
+      }
       if (error instanceof Error && error.message.includes("JSON")) {
         throw new ConfigError(`Failed to parse .dbcli file: ${error.message}`);
       }
@@ -22313,6 +22488,10 @@ var configModule = {
     try {
       return DbcliConfigSchema.parse(raw);
     } catch (error) {
+      if (isZodError(error)) {
+        throw new ConfigError(`Invalid .dbcli config structure:
+${formatConfigValidationError(error, raw)}`);
+      }
       const errorMessage = error instanceof Error ? error.message : String(error);
       throw new ConfigError(`Invalid .dbcli config structure: ${errorMessage}`);
     }
@@ -22413,6 +22592,7 @@ var KEEP_VALUE_FLAGS = new Set([
   "--min-severity",
   "--output",
   "--limit",
+  "--timeout",
   "--collection",
   "--index",
   "--fields",
@@ -22766,6 +22946,12 @@ class QueryExecutor {
     this.config = config;
     this.options = options;
   }
+  resolveDialect() {
+    if (this.options.dialect)
+      return this.options.dialect;
+    const system = this.config?.connection?.system;
+    return SQL_DIALECTS.find((dialect) => dialect === system);
+  }
   takeDiagnostics() {
     const diagnostics = this.pendingDiagnostics;
     this.pendingDiagnostics = [];
@@ -22775,7 +22961,7 @@ class QueryExecutor {
     const start = performance.now();
     this.pendingDiagnostics = [];
     try {
-      const classification = enforcePermission(sql, this.permission);
+      const classification = enforcePermission(sql, this.permission, this.resolveDialect());
       const dangerousOperationWarning = classification.isDangerous && this.permission === "admin" ? `\u26A0 Warning: executing ${classification.type} operation (admin mode)` : undefined;
       const AUTO_LIMIT_TYPES = new Set(["SELECT"]);
       let executeSql = sql;

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.46.0",
+  "version": "1.47.1",
   "description": "Database CLI skill and command reference for AI agents.",
   "contextFileName": "AGENTS.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carllee1983/dbcli",
-  "version": "1.46.0",
+  "version": "1.47.1",
   "description": "Database CLI for AI agents",
   "type": "module",
   "publishConfig": {

package/plugins/dbcli-agent/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.46.0",
+  "version": "1.47.1",
   "description": "Database CLI skill and command reference for AI agents",
   "author": {
     "name": "Carl Lee",

package/plugins/dbcli-agent/skills/dbcli/SKILL.md

@@ -77,7 +77,10 @@ When reporting a check's outcome use the vocabulary `verified` (evidence matched
 `not_verified` (check ran and contradicted) / `indeterminate` (ran but ambiguous) /
 `blocked` (could not run due to config, permission, schema, placeholder, or safety gate).
 
-Prefer `--format json` for agent-friendly output.
+Prefer `--format json` for agent-friendly output. Diagnostics (auto-limit notices,
+warnings) go to stderr so stdout stays parseable — when piping JSON into a parser,
+use `2>/dev/null` or leave stderr alone. **Never `2>&1`**: it merges those lines back
+into stdout and the parse fails.
 
 ## Agent Task Packs
 
@@ -214,7 +217,10 @@ or `doctor` / `status` reports a missing or invalid config, follow this flow.
      `--password` / `--name` (and `--system`).
 3. **What permission tier?** Default to the **lowest** that satisfies the task:
    `query-only` → `read-write` → `data-admin` → `admin`. Set with `--permission`
-   (defaults to `query-only`).
+   (defaults to `query-only`). Tiers judge what a statement does, not how it
+   opens: below `admin`, multi-statement SQL is rejected; snippets must be free
+   of write and DDL keywords; MongoDB `$out` / `$merge` need `data-admin` and are
+   refused entirely in snippets and `export`.
 4. **Verify, never assume.** After init: `dbcli status` (system + permission +
    blacklist summary, no creds) and `dbcli doctor --format json` (env, config
    shape, connectivity, schema-cache age, Mongo SRV path).
@@ -553,4 +559,4 @@ schema. Raw `query` / `export` invocations render a sortable table only.
 - Blacklisted tables and columns are redacted from query output.
 - `schema` reports `estimatedRowCount` and `sizeCategory` (small / medium / large / huge). For large/huge tables add `WHERE` or `LIMIT` — bands in reference.md.
 - `doctor` on `mongodb+srv://` reports whether SRV resolves natively or through the DoH fallback — useful when the runtime restricts DNS.
-- **Global flags:** `--version`, `--config <path>`, `--global`, `--use <name>`, `-v` / `--verbose` / `-vv`, `-q` / `--quiet`, `--no-color` (also honours `NO_COLOR`). Root-level flags must precede the command unless the command explicitly declares a command-level option.
+- **Global flags:** `--version`, `--config <path>`, `--global`, `--use <name>`, `--timeout <ms>`, `-v` / `--verbose` / `-vv`, `-q` / `--quiet`, `--no-color` (also honours `NO_COLOR`). Root-level flags must precede the command unless the command explicitly declares a command-level option.

package/plugins/dbcli-agent/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
 

package/skills/dbcli/SKILL.md

@@ -77,7 +77,10 @@ When reporting a check's outcome use the vocabulary `verified` (evidence matched
 `not_verified` (check ran and contradicted) / `indeterminate` (ran but ambiguous) /
 `blocked` (could not run due to config, permission, schema, placeholder, or safety gate).
 
-Prefer `--format json` for agent-friendly output.
+Prefer `--format json` for agent-friendly output. Diagnostics (auto-limit notices,
+warnings) go to stderr so stdout stays parseable — when piping JSON into a parser,
+use `2>/dev/null` or leave stderr alone. **Never `2>&1`**: it merges those lines back
+into stdout and the parse fails.
 
 ## Agent Task Packs
 
@@ -214,7 +217,10 @@ or `doctor` / `status` reports a missing or invalid config, follow this flow.
      `--password` / `--name` (and `--system`).
 3. **What permission tier?** Default to the **lowest** that satisfies the task:
    `query-only` → `read-write` → `data-admin` → `admin`. Set with `--permission`
-   (defaults to `query-only`).
+   (defaults to `query-only`). Tiers judge what a statement does, not how it
+   opens: below `admin`, multi-statement SQL is rejected; snippets must be free
+   of write and DDL keywords; MongoDB `$out` / `$merge` need `data-admin` and are
+   refused entirely in snippets and `export`.
 4. **Verify, never assume.** After init: `dbcli status` (system + permission +
    blacklist summary, no creds) and `dbcli doctor --format json` (env, config
    shape, connectivity, schema-cache age, Mongo SRV path).
@@ -553,4 +559,4 @@ schema. Raw `query` / `export` invocations render a sortable table only.
 - Blacklisted tables and columns are redacted from query output.
 - `schema` reports `estimatedRowCount` and `sizeCategory` (small / medium / large / huge). For large/huge tables add `WHERE` or `LIMIT` — bands in reference.md.
 - `doctor` on `mongodb+srv://` reports whether SRV resolves natively or through the DoH fallback — useful when the runtime restricts DNS.
-- **Global flags:** `--version`, `--config <path>`, `--global`, `--use <name>`, `-v` / `--verbose` / `-vv`, `-q` / `--quiet`, `--no-color` (also honours `NO_COLOR`). Root-level flags must precede the command unless the command explicitly declares a command-level option.
+- **Global flags:** `--version`, `--config <path>`, `--global`, `--use <name>`, `--timeout <ms>`, `-v` / `--verbose` / `-vv`, `-q` / `--quiet`, `--no-color` (also honours `NO_COLOR`). Root-level flags must precede the command unless the command explicitly declares a command-level option.