@carllee1983/dbcli 1.54.0 → 1.54.1

package/.cursor/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/.github/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/CHANGELOG.md

@@ -5,6 +5,16 @@ 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.54.1] - 2026-08-13 - Error classification: a failure now says which layer broke
+
+### Fixed
+
+- **A dropped connection, an exhausted connection pool, an unreachable host, and a TLS failure each say so.** `TRANSPORT_CODES` listed seven keys, so `ECONNRESET`, `EPIPE`, `EHOSTUNREACH`, `ENETUNREACH`, TLS certificate codes, PostgreSQL SQLSTATE class `08` and `53300`, and MySQL `1040` all carried a code, skipped the message-pattern fallback (which only runs when there is none), and landed on `Database error (ECONNRESET): …` with hints about `dbcli schema`. They now map to four new categories — `CONNECTION_LOST`, `TOO_MANY_CONNECTIONS`, `EHOSTUNREACH`, `TLS_ERROR` — each with the remedy that actually applies: retry a transient drop, inspect `pg_stat_activity` / `Threads_connected` against `max_connections`, check routing and VPN rather than DNS, or point `caPath` / `rejectUnauthorized` at the right certificate. PostgreSQL class `57` (`57P01` / `57P02` / `57P03`) and MySQL `1053` / `2006` / `2013` join them: restarting the server under a running query was reported as `Database error (57P01)` with hints about confirming the statement's objects. The codeless wordings drivers use for the same event — `Connection terminated unexpectedly`, `server closed the connection`, `server has gone away` — are recognized too. `57P03` (still starting up) and `08004` (the server answered and refused) get their own categories rather than borrowing a message that says the opposite, and TLS is matched by code prefix because enumerating OpenSSL's verify codes would keep missing some. The envelope states each cause in its own words instead of inheriting the shared recovery code's description — `CONN_HOST_NOT_FOUND` says the name could not be resolved, which is the one thing `EHOSTUNREACH` rules out — and TLS failures no longer route to the credentials plan, whose second step re-runs `init` for a certificate it never asks about. The adapter-code-to-envelope-code and the connection-versus-statement tables are both exhaustive `Record`s over the code union now, so a future code cannot silently inherit a generic category, and the REPL's reconnect decision reads the same table instead of its own list of codes and message substrings (#62).
+
+- **`insert` / `update` / `delete` / `q` no longer report every failure as "failed to connect".** All four branched on `instanceof ConnectionError` and applied one message key, but that class carries every adapter-level error and only four of its nine codes are transport failures — so a missing table, a syntax error, or a statement timeout all arrived as `Failed to connect to database: …` while the connection was fine. The wording is now chosen by code, and rendering goes through the same `formatCliError` the central presenter uses, so these commands print the stable `Code:` line and the error's hints — both previously dropped on this path — exactly as `query` does (#61).
+
+- **A statement the server canceled is no longer reported as a connection failure.** PostgreSQL `57014`, MySQL `3024`, and MariaDB `1969` fell through to `UNKNOWN` / `CONN_UNKNOWN`, so the CLI answered a query that ran out of statement time with connection-troubleshooting hints and a recovery plan that opened with `dbcli doctor` — the one thing that was not broken. They now map to a `STATEMENT_TIMEOUT` adapter code whose hints point at the query (`dbcli lint`, `dbcli explain`, re-run with an explicit `--statement-timeout <ms>`). The `--recovery` envelope keeps `schemaVersion` 1 and reports `CONN_TIMEOUT` with `details.connectionCode: "STATEMENT_TIMEOUT"`; that field selects the query-oriented plan, replaces the network-flavored message with one that states the ceiling that was in force, and suppresses both the `doctor-*` branches — whose `branchFork.after: 1` assumed step 1 was `doctor` — and the `verify` step, since nothing verifies this error except re-running the statement, which only the caller has. PostgreSQL `57014` is `query_canceled`, not only `statement_timeout`, so a `pg_cancel_backend()` or recovery-conflict cancel keeps the verbatim `Database error (57014): …` form rather than asserting a ceiling nobody set.
+
 ## [1.54.0] - 2026-08-13 - Query engine hardening: timeout semantics, load-on-demand, deterministic builds
 
 ### Added

package/assets/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/dist/cli-runtime.mjs

@@ -51,7 +51,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@carllee1983/dbcli",
-    version: "1.54.0",
+    version: "1.54.1",
     description: "Database CLI for AI agents",
     type: "module",
     publishConfig: {
@@ -9674,10 +9674,12 @@ var init_types2 = __esm(() => {
   ConnectionError = 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);
     }
@@ -9836,18 +9838,28 @@ var init_capabilities = __esm(() => {
 });
 
 // src/adapters/error-mapper.ts
-function categorize(errCode, errno, errMsg) {
+function isTransportDriverCode(code) {
+  return TLS_CODE_PREFIX.test(code) || TRANSPORT_CODES[code] !== undefined;
+}
+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))
@@ -9870,7 +9882,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":
@@ -9879,6 +9891,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}`,
@@ -9909,6 +9957,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",
@@ -9929,7 +9985,7 @@ function mapError(error, system, options) {
     `Try connecting directly with the ${SYSTEM_FACTS[system].client} command-line tool`
   ]);
 }
-var TRANSPORT_CODES, MYSQL_CODES, MYSQL_ERRNOS, SQLSTATES, REDIS_PREFIXES, FALLBACK_PATTERNS, SYSTEM_FACTS;
+var TRANSPORT_CODES, TLS_CODE_PREFIX, MYSQL_CODES, MYSQL_ERRNOS, SQLSTATES, REDIS_PREFIXES, FALLBACK_PATTERNS, PG_CANCEL_BY_TIMEOUT, SYSTEM_FACTS;
 var init_error_mapper = __esm(() => {
   init_types2();
   TRANSPORT_CODES = {
@@ -9938,9 +9994,16 @@ var init_error_mapper = __esm(() => {
     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"
+  };
+  TLS_CODE_PREFIX = /^(CERT_|SELF_SIGNED_|DEPTH_ZERO_|UNABLE_TO_(?:GET|VERIFY)_|ERR_TLS_|ERR_SSL_)/;
   MYSQL_CODES = {
     ER_NO_SUCH_TABLE: "TABLE_NOT_FOUND",
     ER_BAD_FIELD_ERROR: "COLUMN_NOT_FOUND",
@@ -9948,7 +10011,11 @@ var init_error_mapper = __esm(() => {
     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"
   };
   MYSQL_ERRNOS = {
     1045: "AUTH_FAILED",
@@ -9957,14 +10024,30 @@ var init_error_mapper = __esm(() => {
     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"
   };
   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"
   };
   REDIS_PREFIXES = {
     NOAUTH: "AUTH_FAILED",
@@ -9976,6 +10059,10 @@ var init_error_mapper = __esm(() => {
     [/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"],
@@ -9983,6 +10070,7 @@ var init_error_mapper = __esm(() => {
     [/role\s+".*?"\s+does not exist/i, "AUTH_FAILED"],
     [/password supplied/i, "AUTH_FAILED"]
   ];
+  PG_CANCEL_BY_TIMEOUT = /statement timeout/i;
   SYSTEM_FACTS = {
     postgresql: {
       serviceCheck: "systemctl status postgresql",
@@ -17956,7 +18044,7 @@ async function mapWithConcurrency(items, limit, worker) {
 }
 
 // src/core/recovery/types.ts
-var RECOVERY_SCHEMA_VERSION = 1, RECOVERY_CODES, MAX_BRANCH_STEPS = 6, MAX_BRANCH_COUNT = 8, SchemaCacheMissingError, RECOVERY_CODE_METADATA;
+var RECOVERY_SCHEMA_VERSION = 1, RECOVERY_CODES, MAX_BRANCH_STEPS = 6, MAX_BRANCH_COUNT = 8, STATEMENT_TIMEOUT_CODE = "STATEMENT_TIMEOUT", SchemaCacheMissingError, RECOVERY_CODE_METADATA;
 var init_types4 = __esm(() => {
   RECOVERY_CODES = [
     "CONFIG_MISSING",
@@ -18081,6 +18169,64 @@ function dryRunStepForWrite(ctx, quotedTable, placeholders) {
   };
   return draft;
 }
+function statementTimeoutSteps() {
+  return [
+    {
+      command: 'dbcli lint "<sql>"',
+      rationale: "Static anti-pattern read of the statement; needs no connection, so it cannot time out in turn.",
+      risk: "readonly",
+      expects: "Findings with rewrite drafts, or an empty list when nothing is flagged.",
+      placeholders: ["<sql>"]
+    },
+    {
+      command: 'dbcli explain "<sql>"',
+      rationale: "Read the query plan to find the scan or join that exceeded the statement limit.",
+      risk: "readonly",
+      expects: "Annotated query plan; look for sequential scans and unindexed joins.",
+      placeholders: ["<sql>"]
+    },
+    {
+      command: 'dbcli --statement-timeout <ms> query "<sql>"',
+      rationale: "Re-run with an explicit ceiling once the cost is understood; 0 removes the limit entirely.",
+      risk: "readonly",
+      expects: "Query result, or the same timeout if <ms> is still below what the plan costs.",
+      placeholders: ["<ms>", "<sql>"]
+    }
+  ];
+}
+function tlsErrorSteps() {
+  return [
+    {
+      command: "dbcli status --format json",
+      rationale: "Read back the active connection without a live probe to confirm which host and TLS settings are in force.",
+      risk: "readonly",
+      expects: "JSON status with system / permission; no credentials."
+    },
+    {
+      command: "dbcli doctor --format json",
+      rationale: "Doctor reports the handshake failure verbatim, which names the certificate problem (expired, self-signed, altname mismatch).",
+      risk: "readonly",
+      expects: "JSON report whose connection check fails with the TLS error text."
+    }
+  ];
+}
+function connectionsExhaustedSteps(ctx) {
+  const inspectSql = ctx.system === "postgresql" ? "SELECT count(*) FROM pg_stat_activity" : 'SHOW STATUS LIKE "Threads_connected"';
+  return [
+    {
+      command: `dbcli query ${shellQuote(inspectSql)} --format json`,
+      rationale: "Count the connections currently held so the limit can be compared against real usage; needs one free slot, so it may have to wait.",
+      risk: "readonly",
+      expects: "A single row with the current connection count."
+    },
+    {
+      command: "dbcli doctor --format json",
+      rationale: "Once a slot frees up, confirm the connection itself is healthy \u2014 the config was never the problem.",
+      risk: "readonly",
+      expects: "JSON report with the connection check passing."
+    }
+  ];
+}
 function stepsForCode(code, ctx) {
   const drafts = draftsForCode(code, ctx);
   return drafts.slice(0, MAX_RECOVERY_STEPS).map((d, i) => ({ ...d, order: i + 1 }));
@@ -18106,6 +18252,13 @@ function draftsForCode(code, ctx) {
     case "CONN_REFUSED":
     case "CONN_TIMEOUT":
     case "CONN_UNKNOWN": {
+      if (code === "CONN_TIMEOUT" && ctx.connectionCode === STATEMENT_TIMEOUT_CODE) {
+        return statementTimeoutSteps();
+      }
+      if (ctx.connectionCode === "TLS_ERROR")
+        return tlsErrorSteps();
+      if (ctx.connectionCode === "TOO_MANY_CONNECTIONS")
+        return connectionsExhaustedSteps(ctx);
       const out = [
         {
           command: "dbcli doctor --format json",
@@ -18329,7 +18482,9 @@ function draftsForCode(code, ctx) {
   }
 }
 var MAX_RECOVERY_STEPS = 6;
-var init_recovery_steps = () => {};
+var init_recovery_steps = __esm(() => {
+  init_types4();
+});
 
 // src/utils/sql-lexical.ts
 function dollarQuoteDelimiterAt(sql, index) {
@@ -19055,7 +19210,9 @@ var init_types5 = __esm(() => {
 });
 
 // src/core/recovery/verify-steps.ts
-function verifyForCode(code, _ctx) {
+function verifyForCode(code, ctx) {
+  if (ctx.connectionCode === STATEMENT_TIMEOUT_CODE)
+    return null;
   const command = VERIFY_COMMAND_BY_CODE[code];
   if (!command)
     return null;
@@ -19069,6 +19226,7 @@ function verifyForCode(code, _ctx) {
 }
 var VERIFY_COMMAND_BY_CODE, VERIFY_RATIONALE_BY_CODE, VERIFY_EXPECTS_BY_CODE;
 var init_verify_steps = __esm(() => {
+  init_types4();
   VERIFY_COMMAND_BY_CODE = {
     CONFIG_MISSING: "dbcli inspect --no-connect --format json",
     CONN_REFUSED: "dbcli doctor --format json",
@@ -19326,7 +19484,7 @@ function classifyError(error, ctx) {
   const ctxWithDetails = applyDetailsToContext(ctx, recoveryError);
   const recovery = stepsForCode(recoveryError.code, ctxWithDetails);
   const verify = verifyForCode(recoveryError.code, ctxWithDetails);
-  const branchExtras = recoveryError.category === "connection" ? buildConnectionBranches(ctxWithDetails) : null;
+  const branchExtras = recoveryError.category === "connection" && ctxWithDetails.connectionCode !== STATEMENT_TIMEOUT_CODE ? buildConnectionBranches(ctxWithDetails) : null;
   return {
     schemaVersion: RECOVERY_SCHEMA_VERSION,
     generatedAt: new Date().toISOString(),
@@ -19365,8 +19523,19 @@ function errorToRecoveryError(error, ctx) {
   return baseError("UNKNOWN");
 }
 function classifyConnection(err) {
-  const code = err.code === "ECONNREFUSED" ? "CONN_REFUSED" : err.code === "ETIMEDOUT" ? "CONN_TIMEOUT" : err.code === "AUTH_FAILED" ? "CONN_AUTH_FAILED" : err.code === "ENOTFOUND" ? "CONN_HOST_NOT_FOUND" : "CONN_UNKNOWN";
-  return baseError(code, { connectionCode: err.code });
+  const code = RECOVERY_CODE_BY_CONNECTION_CODE[err.code];
+  const base = baseError(code, { connectionCode: err.code });
+  const override = MESSAGE_BY_CONNECTION_CODE[err.code];
+  if (override)
+    return { ...base, message: override };
+  if (err.code === STATEMENT_TIMEOUT_CODE) {
+    const ceiling = err.limitMs !== undefined ? ` The ceiling in force was ${err.limitMs}ms.` : "";
+    return {
+      ...base,
+      message: `The server canceled the statement for exceeding the statement timeout.${ceiling}`
+    };
+  }
+  return base;
 }
 function classifyBlacklist(err) {
   if (/touches blacklisted columns:/i.test(err.message)) {
@@ -19417,9 +19586,11 @@ function applyDetailsToContext(ctx, err) {
     ...ctx,
     table: err.details?.table ?? ctx.table,
     snippet: err.details?.snippet ?? ctx.snippet,
-    hint: err.details?.paramName ?? ctx.hint
+    hint: err.details?.paramName ?? ctx.hint,
+    connectionCode: err.details?.connectionCode ?? ctx.connectionCode
   };
 }
+var RECOVERY_CODE_BY_CONNECTION_CODE, MESSAGE_BY_CONNECTION_CODE;
 var init_classify = __esm(() => {
   init_types2();
   init_permission_guard();
@@ -19429,6 +19600,31 @@ var init_classify = __esm(() => {
   init_verify_steps();
   init_connection_branches();
   init_types4();
+  RECOVERY_CODE_BY_CONNECTION_CODE = {
+    ECONNREFUSED: "CONN_REFUSED",
+    CONNECTION_LOST: "CONN_REFUSED",
+    TOO_MANY_CONNECTIONS: "CONN_REFUSED",
+    SERVER_NOT_READY: "CONN_REFUSED",
+    CONNECTION_REJECTED: "CONN_REFUSED",
+    ETIMEDOUT: "CONN_TIMEOUT",
+    STATEMENT_TIMEOUT: "CONN_TIMEOUT",
+    AUTH_FAILED: "CONN_AUTH_FAILED",
+    TLS_ERROR: "CONN_UNKNOWN",
+    ENOTFOUND: "CONN_HOST_NOT_FOUND",
+    EHOSTUNREACH: "CONN_HOST_NOT_FOUND",
+    SQL_SYNTAX_ERROR: "CONN_UNKNOWN",
+    TABLE_NOT_FOUND: "CONN_UNKNOWN",
+    COLUMN_NOT_FOUND: "CONN_UNKNOWN",
+    UNKNOWN: "CONN_UNKNOWN"
+  };
+  MESSAGE_BY_CONNECTION_CODE = {
+    EHOSTUNREACH: "The host name resolved, but the host or network is unreachable (routing or VPN).",
+    TOO_MANY_CONNECTIONS: "The server has no connection slots left; the limit is on concurrent connections, not on this caller.",
+    CONNECTION_LOST: "The connection was established and then dropped mid-session.",
+    TLS_ERROR: "The TLS handshake failed (certificate or trust chain).",
+    SERVER_NOT_READY: "The server is starting up or recovering and is not accepting connections yet.",
+    CONNECTION_REJECTED: "The server answered and rejected the connection attempt (access rules, pooler, or a per-user limit)."
+  };
 });
 
 // src/core/recovery/render-json.ts
@@ -20579,6 +20775,7 @@ __export(exports_recovery, {
   __resetExecutorForTests: () => __resetExecutorForTests,
   SchemaCacheMissingError: () => SchemaCacheMissingError,
   STEP_RESULT_SUMMARY_FIELD_CAP: () => STEP_RESULT_SUMMARY_FIELD_CAP,
+  STATEMENT_TIMEOUT_CODE: () => STATEMENT_TIMEOUT_CODE,
   RECOVERY_SCHEMA_VERSION: () => RECOVERY_SCHEMA_VERSION,
   RECOVERY_CODE_METADATA: () => RECOVERY_CODE_METADATA,
   RECOVERY_CODES: () => RECOVERY_CODES,
@@ -24498,6 +24695,45 @@ var init_saved_queries = __esm(() => {
   init_snippet_paths();
 });
 
+// src/utils/connection-error-message.ts
+function isTransportFailure(error) {
+  if (error instanceof ConnectionError)
+    return IS_TRANSPORT_FAILURE[error.code];
+  const raw = error?.code;
+  return typeof raw === "string" && isTransportDriverCode(raw);
+}
+function presentConnectionError(error) {
+  const key = IS_TRANSPORT_FAILURE[error.code] ? "errors.connection_failed" : "errors.message";
+  return {
+    message: t_vars(key, { message: error.message }),
+    code: error.code,
+    hints: error.hints
+  };
+}
+var IS_TRANSPORT_FAILURE;
+var init_connection_error_message = __esm(() => {
+  init_types2();
+  init_error_mapper();
+  init_message_loader();
+  IS_TRANSPORT_FAILURE = {
+    ECONNREFUSED: true,
+    ETIMEDOUT: true,
+    AUTH_FAILED: true,
+    ENOTFOUND: true,
+    EHOSTUNREACH: true,
+    CONNECTION_LOST: true,
+    TOO_MANY_CONNECTIONS: true,
+    TLS_ERROR: true,
+    SERVER_NOT_READY: true,
+    CONNECTION_REJECTED: true,
+    STATEMENT_TIMEOUT: false,
+    SQL_SYNTAX_ERROR: false,
+    TABLE_NOT_FOUND: false,
+    COLUMN_NOT_FOUND: false,
+    UNKNOWN: false
+  };
+});
+
 // src/commands/q-mongo.ts
 var exports_q_mongo = {};
 __export(exports_q_mongo, {
@@ -24834,7 +25070,7 @@ async function handleQError(error, snippetName, options, config) {
     process.exit(1);
   }
   if (error instanceof ConnectionError) {
-    printLocalizedCliError(t_vars("errors.connection_failed", { message: error.message }), error);
+    printLocalizedCliError(formatCliError(presentConnectionError(error)), error);
     process.exit(1);
   }
   printLocalizedCliError(t_vars("errors.message", { message: error.message }), error);
@@ -24952,6 +25188,7 @@ var init_q = __esm(() => {
   init_colors();
   init_applied_limit();
   init_cli_error();
+  init_connection_error_message();
   init_strategies();
   init_slow_query_advisory();
 });
@@ -26197,7 +26434,7 @@ async function insertCommand(table, options, command) {
       process.exit(1);
     }
     if (error instanceof ConnectionError) {
-      printLocalizedCliError(t_vars("errors.connection_failed", { message: error.message }), error);
+      printLocalizedCliError(formatCliError(presentConnectionError(error)), error);
       process.exit(1);
     }
     const output = {
@@ -26213,6 +26450,7 @@ async function insertCommand(table, options, command) {
 var init_insert = __esm(() => {
   init_message_loader();
   init_cli_error();
+  init_connection_error_message();
   init_adapters();
   init_data_executor();
   init_config();
@@ -26504,7 +26742,7 @@ async function updateCommand(table, options, command) {
       process.exit(1);
     }
     if (error instanceof ConnectionError) {
-      printLocalizedCliError(t_vars("errors.connection_failed", { message: error.message }), error);
+      printLocalizedCliError(formatCliError(presentConnectionError(error)), error);
       process.exit(1);
     }
     const output = {
@@ -26520,6 +26758,7 @@ async function updateCommand(table, options, command) {
 var init_update = __esm(() => {
   init_message_loader();
   init_cli_error();
+  init_connection_error_message();
   init_adapters();
   init_data_executor();
   init_config();
@@ -26795,7 +27034,7 @@ async function deleteCommand(table, options, command) {
       process.exit(1);
     }
     if (error instanceof ConnectionError) {
-      printLocalizedCliError(t_vars("errors.connection_failed", { message: error.message }), error);
+      printLocalizedCliError(formatCliError(presentConnectionError(error)), error);
       process.exit(1);
     }
     const output = {
@@ -26811,6 +27050,7 @@ async function deleteCommand(table, options, command) {
 var init_delete = __esm(() => {
   init_message_loader();
   init_cli_error();
+  init_connection_error_message();
   init_adapters();
   init_data_executor();
   init_config();
@@ -43842,13 +44082,12 @@ class ReplEngine {
     return null;
   }
   isConnectionError(error) {
-    const e = error;
-    const msg = (e.message ?? "").toLowerCase();
-    return e.code === "ECONNREFUSED" || e.code === "ECONNRESET" || e.code === "ETIMEDOUT" || msg.includes("connection") || msg.includes("terminated") || msg.includes("socket");
+    return isTransportFailure(error);
   }
 }
 var import_picocolors3;
 var init_repl_engine = __esm(() => {
+  init_connection_error_message();
   init_input_classifier();
   init_meta_commands();
   init_history_manager();

package/dist/cli.mjs

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@carllee1983/dbcli",
-  version: "1.54.0",
+  version: "1.54.1",
   description: "Database CLI for AI agents",
   type: "module",
   publishConfig: {

package/dist/core.d.ts

@@ -129,21 +129,31 @@ export interface TableSchema {
 	/** Type of table (table or view) */
 	tableType?: "table" | "view";
 }
-/**
- * Connection error with categorized error code and troubleshooting hints
- */
+type ConnectionErrorCode = "ECONNREFUSED" | "ETIMEDOUT" | "AUTH_FAILED" | "ENOTFOUND" | "EHOSTUNREACH" | "CONNECTION_LOST" | "TOO_MANY_CONNECTIONS" | "TLS_ERROR" | "SERVER_NOT_READY" | "CONNECTION_REJECTED" | "SQL_SYNTAX_ERROR" | "STATEMENT_TIMEOUT" | "TABLE_NOT_FOUND" | "COLUMN_NOT_FOUND" | "UNKNOWN";
 export declare class ConnectionError extends Error {
 	/** Error category code */
-	code: "ECONNREFUSED" | "ETIMEDOUT" | "AUTH_FAILED" | "ENOTFOUND" | "SQL_SYNTAX_ERROR" | "TABLE_NOT_FOUND" | "COLUMN_NOT_FOUND" | "UNKNOWN";
+	code: ConnectionErrorCode;
 	/** Array of actionable troubleshooting hints */
 	hints: string[];
+	/**
+	 * The ceiling that was in force, in milliseconds. Set on STATEMENT_TIMEOUT so
+	 * consumers can state it without parsing `message`; the recovery envelope needs
+	 * it to tell an agent what `--statement-timeout <ms>` it was already up against.
+	 */
+	limitMs?: number | undefined;
 	constructor(
 	/** Error category code */
-	code: "ECONNREFUSED" | "ETIMEDOUT" | "AUTH_FAILED" | "ENOTFOUND" | "SQL_SYNTAX_ERROR" | "TABLE_NOT_FOUND" | "COLUMN_NOT_FOUND" | "UNKNOWN", 
+	code: ConnectionErrorCode, 
 	/** User-friendly error message */
 	message: string, 
 	/** Array of actionable troubleshooting hints */
-	hints: string[]);
+	hints: string[], 
+	/**
+	 * The ceiling that was in force, in milliseconds. Set on STATEMENT_TIMEOUT so
+	 * consumers can state it without parsing `message`; the recovery envelope needs
+	 * it to tell an agent what `--statement-timeout <ms>` it was already up against.
+	 */
+	limitMs?: number | undefined);
 }
 /**
  * Result of a database query or command execution

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.54.1",
   "description": "Database CLI for AI agents",
   "type": "module",
   "publishConfig": {

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/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.