@carllee1983/dbcli 1.54.0 → 1.55.0

package/dist/core.mjs

@@ -1091,10 +1091,12 @@ var init_schema_loader = __esm(() => {
 class ConnectionError extends Error {
   code;
   hints;
-  constructor(code, message, hints) {
+  limitMs;
+  constructor(code, message, hints, limitMs) {
     super(message);
     this.code = code;
     this.hints = hints;
+    this.limitMs = limitMs;
     this.name = "ConnectionError";
     Object.setPrototypeOf(this, ConnectionError.prototype);
   }
@@ -1250,9 +1252,16 @@ var TRANSPORT_CODES = {
   ESOCKETTIMEDOUT: "ETIMEDOUT",
   ENOTFOUND: "ENOTFOUND",
   EAI_AGAIN: "ENOTFOUND",
-  PROTOCOL_CONNECTION_LOST: "ECONNREFUSED",
-  PROTOCOL_SEQUENCE_TIMEOUT: "ETIMEDOUT"
+  PROTOCOL_CONNECTION_LOST: "CONNECTION_LOST",
+  PROTOCOL_SEQUENCE_TIMEOUT: "ETIMEDOUT",
+  ECONNRESET: "CONNECTION_LOST",
+  EPIPE: "CONNECTION_LOST",
+  ECONNABORTED: "CONNECTION_LOST",
+  EHOSTUNREACH: "EHOSTUNREACH",
+  ENETUNREACH: "EHOSTUNREACH",
+  ENETDOWN: "EHOSTUNREACH"
 };
+var TLS_CODE_PREFIX = /^(CERT_|SELF_SIGNED_|DEPTH_ZERO_|UNABLE_TO_(?:GET|VERIFY)_|ERR_TLS_|ERR_SSL_)/;
 var MYSQL_CODES = {
   ER_NO_SUCH_TABLE: "TABLE_NOT_FOUND",
   ER_BAD_FIELD_ERROR: "COLUMN_NOT_FOUND",
@@ -1260,7 +1269,11 @@ var MYSQL_CODES = {
   ER_ACCESS_DENIED_ERROR: "AUTH_FAILED",
   ER_DBACCESS_DENIED_ERROR: "AUTH_FAILED",
   ER_NOT_SUPPORTED_AUTH_MODE: "AUTH_FAILED",
-  ER_MUST_CHANGE_PASSWORD_LOGIN: "AUTH_FAILED"
+  ER_MUST_CHANGE_PASSWORD_LOGIN: "AUTH_FAILED",
+  ER_QUERY_TIMEOUT: "STATEMENT_TIMEOUT",
+  ER_STATEMENT_TIMEOUT: "STATEMENT_TIMEOUT",
+  ER_CON_COUNT_ERROR: "TOO_MANY_CONNECTIONS",
+  ER_SERVER_SHUTDOWN: "CONNECTION_LOST"
 };
 var MYSQL_ERRNOS = {
   1045: "AUTH_FAILED",
@@ -1269,14 +1282,30 @@ var MYSQL_ERRNOS = {
   1064: "SQL_SYNTAX_ERROR",
   1146: "TABLE_NOT_FOUND",
   1251: "AUTH_FAILED",
-  1698: "AUTH_FAILED"
+  1698: "AUTH_FAILED",
+  1040: "TOO_MANY_CONNECTIONS",
+  1053: "CONNECTION_LOST",
+  2006: "CONNECTION_LOST",
+  2013: "CONNECTION_LOST",
+  1969: "STATEMENT_TIMEOUT",
+  3024: "STATEMENT_TIMEOUT"
 };
 var SQLSTATES = {
   "28000": "AUTH_FAILED",
   "28P01": "AUTH_FAILED",
   "42601": "SQL_SYNTAX_ERROR",
   "42P01": "TABLE_NOT_FOUND",
-  "42703": "COLUMN_NOT_FOUND"
+  "42703": "COLUMN_NOT_FOUND",
+  "57014": "STATEMENT_TIMEOUT",
+  "08000": "CONNECTION_LOST",
+  "08003": "CONNECTION_LOST",
+  "08006": "CONNECTION_LOST",
+  "08001": "ECONNREFUSED",
+  "08004": "CONNECTION_REJECTED",
+  "53300": "TOO_MANY_CONNECTIONS",
+  "57P01": "CONNECTION_LOST",
+  "57P02": "CONNECTION_LOST",
+  "57P03": "SERVER_NOT_READY"
 };
 var REDIS_PREFIXES = {
   NOAUTH: "AUTH_FAILED",
@@ -1288,6 +1317,10 @@ var FALLBACK_PATTERNS = [
   [/connect(?:ion)? time(?:d )?out/i, "ETIMEDOUT"],
   [/timeout exceeded/i, "ETIMEDOUT"],
   [/timed out/i, "ETIMEDOUT"],
+  [/connection terminated/i, "CONNECTION_LOST"],
+  [/server closed the connection/i, "CONNECTION_LOST"],
+  [/server has gone away/i, "CONNECTION_LOST"],
+  [/lost connection to \S+ server/i, "CONNECTION_LOST"],
   [/getaddrinfo/i, "ENOTFOUND"],
   [/authentication failed/i, "AUTH_FAILED"],
   [/access denied for user/i, "AUTH_FAILED"],
@@ -1295,18 +1328,26 @@ var FALLBACK_PATTERNS = [
   [/role\s+".*?"\s+does not exist/i, "AUTH_FAILED"],
   [/password supplied/i, "AUTH_FAILED"]
 ];
-function categorize(errCode, errno, errMsg) {
+var PG_CANCEL_BY_TIMEOUT = /statement timeout/i;
+function categorize(errCode, errno, errMsg, system) {
   if (errCode) {
+    if (TLS_CODE_PREFIX.test(errCode))
+      return "TLS_ERROR";
     const known = TRANSPORT_CODES[errCode] ?? MYSQL_CODES[errCode] ?? SQLSTATES[errCode] ?? REDIS_PREFIXES[errCode];
+    if (known === "STATEMENT_TIMEOUT" && errCode === "57014" && !PG_CANCEL_BY_TIMEOUT.test(errMsg)) {
+      return null;
+    }
     if (known)
       return known;
   }
-  if (typeof errno === "number" && MYSQL_ERRNOS[errno])
+  const isMysqlFamily = system === "mysql" || system === "mariadb";
+  if (isMysqlFamily && typeof errno === "number" && MYSQL_ERRNOS[errno]) {
     return MYSQL_ERRNOS[errno];
+  }
   const redisPrefix = errMsg.match(/^([A-Z]+)\s/)?.[1];
   if (redisPrefix && REDIS_PREFIXES[redisPrefix])
     return REDIS_PREFIXES[redisPrefix];
-  if (errCode || typeof errno === "number")
+  if (errCode || isMysqlFamily && typeof errno === "number")
     return null;
   for (const [pattern, category] of FALLBACK_PATTERNS) {
     if (pattern.test(errMsg))
@@ -1359,7 +1400,7 @@ function mapError(error, system, options) {
   const errMsg = String(err?.message || String(error));
   const errCode = String(err?.code || "");
   const errno = err?.errno;
-  switch (categorize(errCode, errno, errMsg)) {
+  switch (categorize(errCode, errno, errMsg, system)) {
     case "ECONNREFUSED":
       return new ConnectionError("ECONNREFUSED", `Cannot connect to ${options.host}:${options.port} \u2014 server is not running or not listening on this port`, serviceHints(system, options));
     case "ETIMEDOUT":
@@ -1368,6 +1409,42 @@ function mapError(error, system, options) {
         `Increase timeout: edit .dbcli and add "timeout": 15000`,
         `Verify network connectivity: ping ${options.host} -c 3`
       ]);
+    case "CONNECTION_LOST":
+      return new ConnectionError("CONNECTION_LOST", `Connection to ${options.host}:${options.port} was lost mid-session \u2014 the server closed it or the network dropped`, [
+        "Re-run the command: a dropped connection is often transient",
+        `Check whether the server restarted or is cycling: ${SYSTEM_FACTS[system].logFile}`,
+        "If it happens on long-running work, look at the server idle/wait timeout"
+      ]);
+    case "SERVER_NOT_READY":
+      return new ConnectionError("SERVER_NOT_READY", `${options.host}:${options.port} is not accepting connections yet \u2014 the server is starting up or recovering`, [
+        "Retry shortly: this clears on its own once startup or recovery finishes",
+        `Watch progress in the server log: ${SYSTEM_FACTS[system].logFile}`,
+        "On a replica, this also appears while it catches up with the primary"
+      ]);
+    case "CONNECTION_REJECTED":
+      return new ConnectionError("CONNECTION_REJECTED", `${options.host}:${options.port} answered but rejected the connection attempt`, [
+        "Check the server access rules (pg_hba.conf) for this user, database, and client address",
+        "If a pooler (pgbouncer / ProxySQL) sits in front, check its own rules and limits",
+        "Check whether the connection limit for this user or database is exhausted"
+      ]);
+    case "TOO_MANY_CONNECTIONS":
+      return new ConnectionError("TOO_MANY_CONNECTIONS", `${options.host}:${options.port} refused the connection \u2014 the server has no connection slots left`, [
+        "Wait and retry: the limit is on concurrent connections, not on you",
+        system === "postgresql" ? "Inspect usage: SELECT count(*) FROM pg_stat_activity \u2014 compare against max_connections" : 'Inspect usage: SHOW STATUS LIKE "Threads_connected" \u2014 compare against max_connections',
+        "Close idle sessions, or raise max_connections if the load is legitimate"
+      ]);
+    case "EHOSTUNREACH":
+      return new ConnectionError("EHOSTUNREACH", `No route to ${options.host} \u2014 the name resolved, but the host or network is unreachable`, [
+        "Check that you are on the right network or VPN",
+        `Check routing and firewall between here and ${options.host}`,
+        `Confirm the address is the one you meant: ${options.host}:${options.port}`
+      ]);
+    case "TLS_ERROR":
+      return new ConnectionError("TLS_ERROR", `TLS handshake failed: ${errMsg}`, [
+        'Point the connection at the right CA bundle: set "caPath" in .dbcli',
+        'For a self-signed certificate in a trusted network, set "rejectUnauthorized": false',
+        `Confirm the certificate covers the host you connected to: ${options.host}`
+      ]);
     case "ENOTFOUND":
       return new ConnectionError("ENOTFOUND", `Host not found: ${options.host}`, [
         `Check the hostname spelling: ${options.host}`,
@@ -1398,6 +1475,14 @@ function mapError(error, system, options) {
         "Column names are case-sensitive on some databases (PostgreSQL with quoted identifiers)"
       ]);
     }
+    case "STATEMENT_TIMEOUT": {
+      const limitMs = options.statementTimeout ?? options.timeout;
+      return new ConnectionError("STATEMENT_TIMEOUT", `Statement timed out${limitMs ? ` (${limitMs}ms)` : ""} \u2014 the server canceled this query before it finished`, [
+        'Inspect the query plan: dbcli explain "<sql>"',
+        "Raise the ceiling for this run: dbcli --statement-timeout <ms> \u2026 (0 removes it)",
+        "Narrow the query: add WHERE filters, reduce the LIMIT, or index the scanned columns"
+      ], limitMs);
+    }
     case "SQL_SYNTAX_ERROR":
       return new ConnectionError("SQL_SYNTAX_ERROR", `SQL syntax error: ${errMsg}`, [
         "Check your SQL syntax near the position reported above",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carllee1983/dbcli",
-  "version": "1.54.0",
+  "version": "1.55.0",
   "description": "Database CLI for AI agents",
   "type": "module",
   "publishConfig": {
@@ -42,11 +42,11 @@
     "blacklist"
   ],
   "engines": {
-    "node": ">=18.0.0",
     "bun": ">=1.3.3"
   },
   "files": [
     "dist/",
+    "scripts/postinstall-check-bun.mjs",
     "!dist/.build-stamp",
     "assets/",
     "plugins/",
@@ -63,6 +63,7 @@
     "LICENSE"
   ],
   "scripts": {
+    "postinstall": "bun scripts/postinstall-check-bun.mjs || node scripts/postinstall-check-bun.mjs || exit 0",
     "dev": "bun run src/cli.ts",
     "build": "bun run scripts/build.ts",
     "build:determinism": "bun run scripts/check-build-determinism.ts",

package/plugins/dbcli-agent/INSTALL.md

@@ -197,17 +197,16 @@ For a persistent `dbcli` executable in `PATH`, run:
 plugins/dbcli-agent/scripts/install-dbcli.sh
 ```
 
-The installer prefers Bun:
+The installer requires Bun:
 
 ```bash
 bun install -g @carllee1983/dbcli
 ```
 
-If Bun is unavailable but npm exists, it falls back to:
-
-```bash
-npm install -g @carllee1983/dbcli
-```
+If Bun is not on `PATH` the script refuses and exits non-zero rather than installing
+through npm: the executable starts with `#!/usr/bin/env bun`, so an npm-only machine would
+end up with a `dbcli` that cannot start. Install Bun first with
+`curl -fsSL https://bun.sh/install | bash`.
 
 ## Verify Installation
 

package/plugins/dbcli-agent/scripts/install-dbcli.sh

@@ -6,10 +6,10 @@ if command -v bun >/dev/null 2>&1; then
   exit 0
 fi
 
-if command -v npm >/dev/null 2>&1; then
-  npm install -g @carllee1983/dbcli
-  exit 0
-fi
-
-echo "Install Bun or npm first, then run: bun install -g @carllee1983/dbcli" >&2
+# npm can fetch the package, but the installed executable runs under Bun
+# (`#!/usr/bin/env bun`), so installing it here would leave a `dbcli` on PATH that
+# cannot start. Refuse instead of half-installing.
+echo "Bun is required: dbcli's executable runs under Bun, whichever package manager installs it." >&2
+echo "Install Bun, then re-run this script:" >&2
+echo "  curl -fsSL https://bun.sh/install | bash" >&2
 exit 1

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

@@ -1660,6 +1660,21 @@ shape (`schemaVersion: 1`):
 Recovery codes (fixed in v1.15.0):
 - `CONFIG_MISSING` — no `.dbcli` config; run `dbcli init`.
 - `CONN_REFUSED` / `CONN_AUTH_FAILED` / `CONN_TIMEOUT` / `CONN_HOST_NOT_FOUND` / `CONN_UNKNOWN` — connection failure variants.
+  `CONN_TIMEOUT` also covers a statement the server canceled for exceeding the statement
+  timeout (PostgreSQL `57014`, MySQL `3024`, MariaDB `1969`); `details.connectionCode` is
+  `STATEMENT_TIMEOUT` there instead of `ETIMEDOUT`, the plan targets the query (`lint` →
+  `explain` → re-run with `--statement-timeout <ms>`) rather than `doctor`, and no
+  `branches` / `branchFork` / `verify` is emitted. PostgreSQL `57014` only counts as a
+  statement timeout when the server says so — a `pg_cancel_backend()` cancel keeps the
+  verbatim `Database error (57014): …` form instead of claiming a ceiling.
+  The same `details.connectionCode` field distinguishes the other causes that share a
+  connection code: `CONNECTION_LOST` (server closed the connection mid-session — PostgreSQL
+  class 08 and `57P01`/`57P02`, MySQL `1053`), `TOO_MANY_CONNECTIONS` (PostgreSQL `53300`,
+  MySQL `1040` — its plan counts current connections instead of running `doctor`, because
+  rewriting host/port cannot create a slot), `SERVER_NOT_READY` (`57P03`, still starting up),
+  `CONNECTION_REJECTED` (`08004` — the server answered and refused), `EHOSTUNREACH` (resolved
+  but unroutable) and `TLS_ERROR` (handshake failure; reported as `CONN_UNKNOWN` rather than
+  `CONN_AUTH_FAILED`, whose plan re-runs `init` for credentials that are not the problem).
 - `PERMISSION_DENIED` — active permission level forbids the operation.
 - `BLACKLIST_TABLE` / `BLACKLIST_COLUMN_WRITE` — blacklist violations.
 - `SNIPPET_NOT_FOUND` / `SNIPPET_AMBIGUOUS` / `SNIPPET_PARAM_MISSING` — saved-query failures.

package/scripts/postinstall-check-bun.mjs

@@ -0,0 +1,49 @@
+/**
+ * Post-install runtime check.
+ *
+ * `engines` declares bun only, but npm ignores engine fields it does not know, so an
+ * `npm install -g @carllee1983/dbcli` on a machine without Bun succeeds and leaves a
+ * `dbcli` on PATH whose `#!/usr/bin/env bun` shebang cannot start. This warns at the
+ * moment that happens, which is closer to the user than any README paragraph.
+ *
+ * Plain Node ESM on purpose: npm runs this with node, not bun. Never fails the install —
+ * a warning is the whole point, and a non-zero exit here would break the package.
+ */
+
+import { spawnSync } from 'node:child_process'
+
+const BUN_INSTALL_HINT =
+  process.platform === 'win32'
+    ? 'powershell -c "irm bun.sh/install.ps1 | iex"'
+    : 'curl -fsSL https://bun.sh/install | bash'
+
+function bunIsAvailable() {
+  if (process.versions.bun) return true
+  try {
+    const result = spawnSync('bun', ['--version'], {
+      encoding: 'utf8',
+      timeout: 10_000,
+      shell: process.platform === 'win32',
+    })
+    return result.status === 0
+  } catch {
+    return false
+  }
+}
+
+if (!bunIsAvailable()) {
+  console.warn(
+    [
+      '',
+      'dbcli: Bun was not found on PATH.',
+      '',
+      "  The package installed, but dbcli's executable runs under Bun (its shebang is",
+      '  `#!/usr/bin/env bun`), so `dbcli` will not start until Bun 1.3.3+ is installed:',
+      '',
+      `    ${BUN_INSTALL_HINT}`,
+      '',
+      '  The ./agent-core subpath export is importable from Node without Bun.',
+      '',
+    ].join('\n')
+  )
+}

package/skills/dbcli/reference.md

@@ -1660,6 +1660,21 @@ shape (`schemaVersion: 1`):
 Recovery codes (fixed in v1.15.0):
 - `CONFIG_MISSING` — no `.dbcli` config; run `dbcli init`.
 - `CONN_REFUSED` / `CONN_AUTH_FAILED` / `CONN_TIMEOUT` / `CONN_HOST_NOT_FOUND` / `CONN_UNKNOWN` — connection failure variants.
+  `CONN_TIMEOUT` also covers a statement the server canceled for exceeding the statement
+  timeout (PostgreSQL `57014`, MySQL `3024`, MariaDB `1969`); `details.connectionCode` is
+  `STATEMENT_TIMEOUT` there instead of `ETIMEDOUT`, the plan targets the query (`lint` →
+  `explain` → re-run with `--statement-timeout <ms>`) rather than `doctor`, and no
+  `branches` / `branchFork` / `verify` is emitted. PostgreSQL `57014` only counts as a
+  statement timeout when the server says so — a `pg_cancel_backend()` cancel keeps the
+  verbatim `Database error (57014): …` form instead of claiming a ceiling.
+  The same `details.connectionCode` field distinguishes the other causes that share a
+  connection code: `CONNECTION_LOST` (server closed the connection mid-session — PostgreSQL
+  class 08 and `57P01`/`57P02`, MySQL `1053`), `TOO_MANY_CONNECTIONS` (PostgreSQL `53300`,
+  MySQL `1040` — its plan counts current connections instead of running `doctor`, because
+  rewriting host/port cannot create a slot), `SERVER_NOT_READY` (`57P03`, still starting up),
+  `CONNECTION_REJECTED` (`08004` — the server answered and refused), `EHOSTUNREACH` (resolved
+  but unroutable) and `TLS_ERROR` (handshake failure; reported as `CONN_UNKNOWN` rather than
+  `CONN_AUTH_FAILED`, whose plan re-runs `init` for credentials that are not the problem).
 - `PERMISSION_DENIED` — active permission level forbids the operation.
 - `BLACKLIST_TABLE` / `BLACKLIST_COLUMN_WRITE` — blacklist violations.
 - `SNIPPET_NOT_FOUND` / `SNIPPET_AMBIGUOUS` / `SNIPPET_PARAM_MISSING` — saved-query failures.