@carllee1983/dbcli 1.6.0 → 1.7.0

package/dist/cli.mjs

@@ -7528,11 +7528,11 @@ var init_schema_index = __esm(() => {
 // src/core/schema-loader.ts
 var exports_schema_loader = {};
 __export(exports_schema_loader, {
-  SchemaLayeredLoader: () => SchemaLayeredLoader2
+  SchemaLayeredLoader: () => SchemaLayeredLoader
 });
 import { join as join6 } from "path";
 
-class SchemaLayeredLoader2 {
+class SchemaLayeredLoader {
   dbcliPath;
   connectionName;
   options;
@@ -77096,6 +77096,49 @@ var init_size_category = __esm(() => {
   ];
 });
 
+// src/utils/levenshtein-distance.ts
+function levenshteinDistance(a, b) {
+  const lenA = a.length;
+  const lenB = b.length;
+  const dp = [];
+  for (let i = 0;i <= lenB; i++) {
+    const row = [];
+    for (let j = 0;j <= lenA; j++) {
+      row[j] = 0;
+    }
+    dp[i] = row;
+  }
+  for (let i = 0;i <= lenB; i++) {
+    const row = dp[i];
+    if (row !== undefined) {
+      row[0] = i;
+    }
+  }
+  for (let j = 0;j <= lenA; j++) {
+    const firstRow = dp[0];
+    if (firstRow !== undefined) {
+      firstRow[j] = j;
+    }
+  }
+  for (let i = 1;i <= lenB; i++) {
+    const currentRow = dp[i];
+    const prevRow = dp[i - 1];
+    if (!currentRow || !prevRow)
+      continue;
+    for (let j = 1;j <= lenA; j++) {
+      if (b.charAt(i - 1) === a.charAt(j - 1)) {
+        currentRow[j] = prevRow[j - 1] ?? 0;
+      } else {
+        const sub = (prevRow[j - 1] ?? 0) + 1;
+        const ins = (currentRow[j - 1] ?? 0) + 1;
+        const del = (prevRow[j] ?? 0) + 1;
+        currentRow[j] = Math.min(sub, ins, del);
+      }
+    }
+  }
+  return dp[lenB]?.[lenA] ?? 0;
+}
+
 // src/commands/query-size-guard.ts
 var exports_query_size_guard = {};
 __export(exports_query_size_guard, {
@@ -77128,6 +77171,819 @@ var init_query_size_guard = __esm(() => {
   init_size_category();
 });
 
+// src/core/saved-queries/types.ts
+var SavedQueryError;
+var init_types2 = __esm(() => {
+  SavedQueryError = class SavedQueryError extends Error {
+    code;
+    file;
+    constructor(message, code, file) {
+      super(message);
+      this.code = code;
+      this.file = file;
+      this.name = "SavedQueryError";
+      Object.setPrototypeOf(this, SavedQueryError.prototype);
+    }
+  };
+});
+
+// src/core/saved-queries/yaml-mini.ts
+function parseYamlMini(text2) {
+  const lines2 = text2.split(`
+`).filter((l) => !/^\s*(#.*)?$/.test(l));
+  const root = {};
+  const stack = [{ indent: -1, node: root }];
+  for (const raw of lines2) {
+    if (raw.includes("\t")) {
+      throw new Error(`YAML mini: tab indentation not supported: "${raw}"`);
+    }
+    const indent = raw.match(/^( *)/)[1].length;
+    const line = raw.slice(indent);
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+      stack.pop();
+    }
+    const parent = stack[stack.length - 1].node;
+    const colon = line.indexOf(":");
+    if (colon === -1) {
+      throw new Error(`YAML mini: expected "key:" at "${raw}"`);
+    }
+    const key2 = line.slice(0, colon).trim();
+    const rest = line.slice(colon + 1).trim();
+    if (/^[&*]\w/.test(rest)) {
+      throw new Error(`YAML mini: anchor/reference unsupported: "${raw}"`);
+    }
+    if (rest === "") {
+      const child = {};
+      parent[key2] = child;
+      stack.push({ indent, node: child });
+    } else {
+      parent[key2] = parseScalarOrInlineList(rest);
+    }
+  }
+  return root;
+}
+function parseScalarOrInlineList(s) {
+  if (s.startsWith("[") && s.endsWith("]")) {
+    const inner = s.slice(1, -1).trim();
+    if (inner === "")
+      return [];
+    return inner.split(",").map((p) => parseScalar(p.trim()));
+  }
+  if (s.startsWith("{") && s.endsWith("}")) {
+    const inner = s.slice(1, -1).trim();
+    if (inner === "")
+      return {};
+    throw new Error(`YAML mini: inline map entries unsupported, use block form: "${s}"`);
+  }
+  return parseScalar(s);
+}
+function parseScalar(s) {
+  if (s === "true")
+    return true;
+  if (s === "false")
+    return false;
+  if (s === "null" || s === "~" || s === "")
+    return null;
+  if (s.startsWith('"') && s.endsWith('"') || s.startsWith("'") && s.endsWith("'")) {
+    return s.slice(1, -1);
+  }
+  if (/^-?\d+$/.test(s))
+    return parseInt(s, 10);
+  if (/^-?\d+\.\d+$/.test(s))
+    return parseFloat(s);
+  return s;
+}
+
+// src/core/saved-queries/parser.ts
+function parseSavedQuery(input) {
+  if (Buffer.byteLength(input.text, "utf8") > MAX_BYTES) {
+    throw new SavedQueryError(`Snippet '${input.key}' exceeds 64 KB size limit`, "FILE_TOO_LARGE", input.file);
+  }
+  const { frontmatter, body } = splitFrontmatter(input.text);
+  const fm = parseFrontmatter(frontmatter, input);
+  validateBody(body, input);
+  const meta = fm.meta;
+  meta.key = input.key;
+  if (!meta.name)
+    meta.name = input.key;
+  return {
+    query: { meta, sqlBody: body, file: input.file, source: input.source },
+    warnings: fm.warnings
+  };
+}
+function splitFrontmatter(text2) {
+  const lines2 = text2.split(`
+`);
+  if (lines2[0]?.trim() !== "-- ---")
+    return { frontmatter: "", body: text2 };
+  const end = lines2.findIndex((l, i) => i > 0 && l.trim() === "-- ---");
+  if (end === -1)
+    return { frontmatter: "", body: text2 };
+  const fmLines = lines2.slice(1, end).map((l) => l.replace(/^--\s?/, ""));
+  const bodyLines = lines2.slice(end + 1);
+  return { frontmatter: fmLines.join(`
+`), body: bodyLines.join(`
+`) };
+}
+function parseFrontmatter(yaml, input) {
+  if (!yaml.trim()) {
+    return {
+      meta: { name: "", key: input.key, params: [], tags: [] },
+      warnings: ["Snippet has no engine declaration; assuming any engine"]
+    };
+  }
+  let rawParsed;
+  try {
+    rawParsed = parseYamlMini(yaml);
+  } catch (e) {
+    throw new SavedQueryError(`Invalid frontmatter in '${input.key}': ${e.message}`, "PARSE_ERROR", input.file);
+  }
+  const warnings = [];
+  const raw = rawParsed ?? {};
+  const engine = normaliseEngine(raw.engine, warnings);
+  const params = normaliseParams(raw.params, input);
+  const tags = Array.isArray(raw.tags) ? raw.tags.map(String) : [];
+  return {
+    meta: {
+      name: typeof raw.name === "string" ? raw.name : "",
+      key: input.key,
+      description: typeof raw.description === "string" ? raw.description : undefined,
+      engine,
+      params,
+      tags
+    },
+    warnings
+  };
+}
+function normaliseEngine(value, warnings) {
+  if (value === undefined || value === null || value === "") {
+    warnings.push("Snippet has no engine declaration; assuming any engine");
+    return;
+  }
+  const list = Array.isArray(value) ? value : [value];
+  const cleaned = [];
+  for (const v of list) {
+    const s = String(v).toLowerCase();
+    if (!VALID_ENGINES.includes(s)) {
+      throw new SavedQueryError(`Unknown engine '${s}' (allowed: postgres, mysql)`, "PARSE_ERROR");
+    }
+    cleaned.push(s);
+  }
+  return cleaned;
+}
+function normaliseParams(value, input) {
+  if (value === undefined || value === null)
+    return [];
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new SavedQueryError(`'params' must be a map`, "PARSE_ERROR", input.file);
+  }
+  return Object.entries(value).map(([name, spec]) => {
+    const type = String(spec?.type ?? "string");
+    if (!VALID_TYPES.includes(type)) {
+      throw new SavedQueryError(`Param '${name}': invalid type '${type}'`, "PARSE_ERROR", input.file);
+    }
+    const hasDefault = spec && Object.prototype.hasOwnProperty.call(spec, "default");
+    return {
+      name,
+      type,
+      required: spec?.required === true ? true : !hasDefault,
+      default: hasDefault ? spec.default : undefined,
+      description: typeof spec?.description === "string" ? spec.description : undefined,
+      enum: Array.isArray(spec?.enum) ? spec.enum : undefined
+    };
+  });
+}
+function validateBody(body, input) {
+  const stripped = stripCommentsAndStrings2(body);
+  const trimmed = stripped.trim();
+  if (!trimmed) {
+    throw new SavedQueryError(`Snippet '${input.key}' has empty SQL body`, "PARSE_ERROR", input.file);
+  }
+  const firstKeyword = trimmed.match(/^[A-Za-z]+/)?.[0]?.toUpperCase() ?? "";
+  if (firstKeyword !== "SELECT" && firstKeyword !== "WITH") {
+    throw new SavedQueryError(`Snippet '${input.key}' must start with SELECT or WITH (got '${firstKeyword || "<empty>"}')`, "NOT_SELECT", input.file);
+  }
+  const semi = trimmed.indexOf(";");
+  if (semi !== -1) {
+    const tail = trimmed.slice(semi + 1);
+    if (/[A-Za-z0-9_]/.test(tail)) {
+      throw new SavedQueryError(`Snippet '${input.key}' contains multiple statements; only one SELECT is allowed`, "MULTI_STATEMENT", input.file);
+    }
+  }
+  if (/\$\{[^}]*\}|\{\{[^}]*\}\}/.test(body)) {
+    throw new SavedQueryError(`Snippet '${input.key}' uses template syntax; use :name bind parameters instead`, "TEMPLATE_SYNTAX", input.file);
+  }
+}
+function stripCommentsAndStrings2(sql) {
+  let out = "";
+  let i = 0;
+  while (i < sql.length) {
+    const c = sql[i];
+    const next = sql[i + 1];
+    if (c === "-" && next === "-") {
+      while (i < sql.length && sql[i] !== `
+`) {
+        out += " ";
+        i++;
+      }
+      continue;
+    }
+    if (c === "/" && next === "*") {
+      out += "  ";
+      i += 2;
+      while (i < sql.length && !(sql[i] === "*" && sql[i + 1] === "/")) {
+        out += sql[i] === `
+` ? `
+` : " ";
+        i++;
+      }
+      if (i < sql.length) {
+        out += "  ";
+        i += 2;
+      }
+      continue;
+    }
+    if (c === "'" || c === '"') {
+      const quote = c;
+      out += " ";
+      i++;
+      while (i < sql.length) {
+        if (sql[i] === "\\" && i + 1 < sql.length) {
+          out += "  ";
+          i += 2;
+          continue;
+        }
+        if (sql[i] === quote) {
+          out += " ";
+          i++;
+          break;
+        }
+        out += sql[i] === `
+` ? `
+` : " ";
+        i++;
+      }
+      continue;
+    }
+    if (c === "$" && next === "$") {
+      out += "  ";
+      i += 2;
+      while (i < sql.length && !(sql[i] === "$" && sql[i + 1] === "$")) {
+        out += sql[i] === `
+` ? `
+` : " ";
+        i++;
+      }
+      if (i < sql.length) {
+        out += "  ";
+        i += 2;
+      }
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+var MAX_BYTES, VALID_TYPES, VALID_ENGINES;
+var init_parser = __esm(() => {
+  init_types2();
+  MAX_BYTES = 64 * 1024;
+  VALID_TYPES = ["int", "string", "float", "bool", "date", "datetime"];
+  VALID_ENGINES = ["postgres", "mysql"];
+});
+
+// src/core/saved-queries/loader.ts
+import { readdir } from "fs/promises";
+import { join as join10, relative, sep } from "path";
+async function loadSnippets(opts) {
+  const builtin = await walkAndParse(opts.builtinDir, "builtin");
+  const shared = await walkAndParse(opts.sharedDir, "shared");
+  const local = await walkAndParse(opts.localDir, "local");
+  const merged = new Map;
+  pushTier(merged, builtin);
+  pushTier(merged, shared);
+  pushTier(merged, local);
+  return merged;
+}
+function pushTier(out, tier) {
+  for (const q of tier) {
+    const list = out.get(q.meta.key) ?? [];
+    const keepers = list.filter((existing) => !sameEngineSet(existing.query, q));
+    const replacedSomething = keepers.length < list.length;
+    keepers.push({ query: q, hasLocalOverride: q.source === "local" && replacedSomething });
+    out.set(q.meta.key, keepers);
+  }
+}
+function sameEngineSet(a, b) {
+  const ae = (a.meta.engine ?? []).slice().sort().join(",");
+  const be = (b.meta.engine ?? []).slice().sort().join(",");
+  return ae === be;
+}
+async function walkAndParse(root, source) {
+  const out = [];
+  let entries;
+  try {
+    entries = await collectFiles(root);
+  } catch {
+    return out;
+  }
+  for (const file of entries) {
+    if (!file.endsWith(".sql"))
+      continue;
+    const rel = relative(root, file).replace(new RegExp(`\\${sep}`, "g"), "/");
+    const { logicalKey, suffixEngine } = parseFilename(rel);
+    const text2 = await Bun.file(file).text();
+    const { query } = parseSavedQuery({ key: logicalKey, file, source, text: text2 });
+    enforceSuffixEngineConsistency(query, suffixEngine);
+    out.push(query);
+  }
+  return out;
+}
+function parseFilename(rel) {
+  const noExt = rel.slice(0, -".sql".length);
+  for (const eng of ENGINE_SUFFIXES) {
+    if (noExt.endsWith("." + eng)) {
+      return { logicalKey: "@" + noExt.slice(0, -("." + eng).length), suffixEngine: eng };
+    }
+  }
+  return { logicalKey: "@" + noExt, suffixEngine: null };
+}
+function enforceSuffixEngineConsistency(q, suffixEngine) {
+  if (!suffixEngine)
+    return;
+  const declared = q.meta.engine ?? [];
+  if (declared.length !== 1 || declared[0] !== suffixEngine) {
+    q.meta.engine = [suffixEngine];
+  }
+}
+async function collectFiles(root) {
+  const out = [];
+  async function walk(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const e of entries) {
+      const full = join10(dir, e.name);
+      if (e.isDirectory())
+        await walk(full);
+      else
+        out.push(full);
+    }
+  }
+  await walk(root);
+  return out;
+}
+var ENGINE_SUFFIXES;
+var init_loader = __esm(() => {
+  init_parser();
+  ENGINE_SUFFIXES = ["postgres", "mysql"];
+});
+
+// src/core/saved-queries/binder.ts
+function mergeParamSources(cli, file) {
+  return { ...file, ...cli };
+}
+function coerceParams(specs, raw) {
+  const out = {};
+  const missing = [];
+  for (const spec of specs) {
+    const provided = Object.prototype.hasOwnProperty.call(raw, spec.name);
+    if (!provided) {
+      if (spec.required) {
+        missing.push(spec.name);
+        continue;
+      }
+      out[spec.name] = spec.default ?? null;
+      continue;
+    }
+    out[spec.name] = coerceValue(spec, raw[spec.name]);
+  }
+  if (missing.length > 0) {
+    throw new SavedQueryError(`Missing required parameters: ${missing.join(", ")}`, "PARAM_MISSING");
+  }
+  return out;
+}
+function coerceValue(spec, value) {
+  const s = value === null || value === undefined ? "" : String(value);
+  let coerced;
+  switch (spec.type) {
+    case "int": {
+      const n = parseInt(s, 10);
+      if (Number.isNaN(n))
+        throw paramErr(spec, s, "int");
+      coerced = n;
+      break;
+    }
+    case "float": {
+      const n = parseFloat(s);
+      if (Number.isNaN(n))
+        throw paramErr(spec, s, "float");
+      coerced = n;
+      break;
+    }
+    case "bool": {
+      const lc = s.toLowerCase();
+      if (["true", "1", "yes"].includes(lc))
+        coerced = true;
+      else if (["false", "0", "no"].includes(lc))
+        coerced = false;
+      else
+        throw paramErr(spec, s, "bool");
+      break;
+    }
+    case "date": {
+      if (!/^\d{4}-\d{2}-\d{2}$/.test(s))
+        throw paramErr(spec, s, "date (YYYY-MM-DD)");
+      coerced = s;
+      break;
+    }
+    case "datetime": {
+      if (Number.isNaN(Date.parse(s)))
+        throw paramErr(spec, s, "datetime (ISO 8601)");
+      coerced = s;
+      break;
+    }
+    case "string":
+    default:
+      coerced = s;
+  }
+  if (spec.enum && !spec.enum.some((v) => String(v) === String(coerced))) {
+    throw new SavedQueryError(`Param '${spec.name}': value '${coerced}' not in enum [${spec.enum.join(", ")}]`, "PARAM_INVALID");
+  }
+  return coerced;
+}
+function paramErr(spec, raw, expected) {
+  return new SavedQueryError(`Param '${spec.name}': cannot coerce '${raw}' to ${expected}`, "PARAM_INVALID");
+}
+function rewriteToBind(sqlBody, params, engine) {
+  const masked = stripCommentsAndStrings2(sqlBody);
+  const order = [];
+  const indexByName = new Map;
+  let m;
+  NAME_RE.lastIndex = 0;
+  while ((m = NAME_RE.exec(masked)) !== null) {
+    const name = m[1];
+    if (!indexByName.has(name)) {
+      indexByName.set(name, order.length + 1);
+      order.push(name);
+    }
+  }
+  let outSql = "";
+  let cursor = 0;
+  NAME_RE.lastIndex = 0;
+  while ((m = NAME_RE.exec(masked)) !== null) {
+    const name = m[1];
+    const start = m.index;
+    const end = start + m[0].length;
+    outSql += sqlBody.slice(cursor, start);
+    const idx = indexByName.get(name);
+    outSql += engine === "postgres" ? `$${idx}` : "?";
+    cursor = end;
+  }
+  outSql += sqlBody.slice(cursor);
+  const undeclared = [];
+  const values = order.map((n) => {
+    if (!Object.prototype.hasOwnProperty.call(params, n)) {
+      undeclared.push(n);
+      return null;
+    }
+    return params[n];
+  });
+  return { sql: outSql, values, undeclared };
+}
+var NAME_RE;
+var init_binder = __esm(() => {
+  init_types2();
+  init_parser();
+  NAME_RE = /(?<![\w:]):([a-zA-Z_][a-zA-Z0-9_]*)/g;
+});
+
+// src/core/saved-queries/resolver.ts
+function resolveByName(map, name, engine) {
+  const variants = map.get(name);
+  if (!variants || variants.length === 0) {
+    const suggestions = suggestSimilar([...map.keys()], name);
+    const hint = suggestions.length > 0 ? `
+  Did you mean: ${suggestions.join(", ")}?` : "";
+    throw new SavedQueryError(`Snippet not found: ${name}${hint}`, "NOT_FOUND");
+  }
+  const matches = variants.filter((v) => engineMatches(v.query.meta.engine, engine));
+  if (matches.length === 0) {
+    const declared = variants.map((v) => v.query.meta.engine?.join(",") ?? "any").join(" | ");
+    throw new SavedQueryError(`Snippet '${name}' does not support engine '${engine}' (declared: ${declared})`, "ENGINE_MISMATCH");
+  }
+  matches.sort((a, b) => SOURCE_RANK[b.query.source] - SOURCE_RANK[a.query.source]);
+  return matches[0];
+}
+function engineMatches(declared, current) {
+  if (!declared || declared.length === 0)
+    return true;
+  return declared.includes(current);
+}
+function suggestSimilar(all, name, limit = 5) {
+  return all.map((k) => ({ k, d: levenshteinDistance(k, name) })).sort((a, b) => a.d - b.d).slice(0, limit).map((x) => x.k);
+}
+var SOURCE_RANK;
+var init_resolver = __esm(() => {
+  init_types2();
+  SOURCE_RANK = {
+    builtin: 0,
+    shared: 1,
+    local: 2
+  };
+});
+
+// src/core/saved-queries/size-guard.ts
+function applySnippetGuard(sqlBody, opts) {
+  const trimmed = sqlBody.trim().replace(/;\s*$/, "");
+  if (opts.noLimit)
+    return trimmed;
+  const masked = stripCommentsAndStrings2(trimmed);
+  const literal = matchOuterLiteralLimit(masked);
+  if (literal !== null && literal < GUARD_LIMIT)
+    return trimmed;
+  return `SELECT * FROM (${trimmed}) AS _dbcli_guard LIMIT ${GUARD_LIMIT}`;
+}
+function matchOuterLiteralLimit(masked) {
+  const m = masked.match(/\bLIMIT\s+(\d+)\s*$/i);
+  return m ? parseInt(m[1], 10) : null;
+}
+var GUARD_LIMIT = 1000;
+var init_size_guard = __esm(() => {
+  init_parser();
+});
+
+// src/core/saved-queries/runner.ts
+function prepareExecution(snippet, opts, cliParams, fileParams) {
+  const warnings = [];
+  if (opts.engine === "mongodb") {
+    throw new SavedQueryError(`Snippet '${snippet.query.meta.key}' targets SQL but current connection is MongoDB`, "ENGINE_MISMATCH", snippet.query.file);
+  }
+  const declared = snippet.query.meta.engine;
+  if (!declared) {
+    warnings.push(`Snippet '${snippet.query.meta.key}' has no engine declaration`);
+  } else if (!declared.includes(opts.engine)) {
+    throw new SavedQueryError(`Engine mismatch for snippet '${snippet.query.meta.key}'
+` + `  Snippet requires: ${declared.join(", ")}
+` + `  Connection is: ${opts.engine}`, "ENGINE_MISMATCH", snippet.query.file);
+  }
+  const merged = mergeParamSources(cliParams, fileParams);
+  const typed = coerceParams(snippet.query.meta.params, merged);
+  const rewritten = rewriteToBind(snippet.query.sqlBody, typed, opts.engine);
+  if (rewritten.undeclared.length > 0) {
+    warnings.push(`SQL references undeclared params: ${rewritten.undeclared.join(", ")}`);
+  }
+  const wrapped = applySnippetGuard(rewritten.sql, { noLimit: opts.noLimit });
+  return {
+    driver: { sql: wrapped, values: rewritten.values },
+    rewrittenSql: rewritten.sql,
+    warnings
+  };
+}
+var init_runner = __esm(() => {
+  init_binder();
+  init_size_guard();
+  init_types2();
+});
+
+// src/core/saved-queries/snippet-paths.ts
+import { join as join11, resolve as resolve2 } from "path";
+function resolveBuiltinDir() {
+  return resolve2(import.meta.dir, "..", "..", "..", "assets", "snippets");
+}
+function resolveSnippetDirs(workspaceRoot) {
+  return {
+    builtinDir: resolveBuiltinDir(),
+    sharedDir: join11(workspaceRoot, ".dbcli-shared", "queries"),
+    localDir: join11(workspaceRoot, ".dbcli", "queries")
+  };
+}
+function snippetKeyToFile(workspaceRoot, key2, source) {
+  const rel = key2.replace(/^@/, "") + ".sql";
+  if (source === "builtin")
+    return join11(resolveBuiltinDir(), rel);
+  const dir = source === "shared" ? ".dbcli-shared/queries" : ".dbcli/queries";
+  return join11(workspaceRoot, dir, rel);
+}
+var init_snippet_paths = () => {};
+
+// src/core/saved-queries/engine-map.ts
+function mapSystemToEngine(system) {
+  if (system === "postgresql")
+    return "postgres";
+  if (system === "mysql" || system === "mariadb")
+    return "mysql";
+  if (system === "mongodb")
+    return "mongodb";
+  throw new Error(`Unsupported connection system for snippets: ${system}`);
+}
+
+// src/core/saved-queries/index.ts
+var init_saved_queries = __esm(() => {
+  init_types2();
+  init_loader();
+  init_parser();
+  init_binder();
+  init_resolver();
+  init_size_guard();
+  init_runner();
+  init_snippet_paths();
+});
+
+// src/commands/queries-delete.ts
+var exports_queries_delete = {};
+__export(exports_queries_delete, {
+  queriesDelete: () => queriesDelete
+});
+import { rm } from "fs/promises";
+async function queriesDelete(name, options = {}) {
+  if (!name.startsWith("@")) {
+    throw new Error(`Snippet name must start with '@' (got '${name}')`);
+  }
+  const cwd = options.cwd ?? process.cwd();
+  const dirs = resolveSnippetDirs(cwd);
+  const map = await loadSnippets(dirs);
+  const variants = map.get(name);
+  if (!variants || variants.length === 0) {
+    throw new Error(`Snippet not found: ${name}`);
+  }
+  const localVariants = variants.filter((v) => v.query.source === "local");
+  if (localVariants.length === 0) {
+    throw new Error(`Refusing to delete: '${name}' has no local copy. Only local snippets can be deleted.`);
+  }
+  if (!options.force) {
+    const ok = await esm_default4({
+      message: `Delete ${localVariants.length} local file(s) for ${name}?`,
+      default: false
+    });
+    if (!ok)
+      return;
+  }
+  for (const v of localVariants) {
+    await rm(v.query.file, { force: true });
+    console.log(`deleted ${v.query.file}`);
+  }
+}
+var init_queries_delete = __esm(() => {
+  init_esm14();
+  init_saved_queries();
+});
+
+// src/commands/queries-rename.ts
+var exports_queries_rename = {};
+__export(exports_queries_rename, {
+  queriesRename: () => queriesRename
+});
+import { rename, mkdir } from "fs/promises";
+import { dirname } from "path";
+async function queriesRename(oldName, newName, options = {}) {
+  if (!oldName.startsWith("@") || !newName.startsWith("@")) {
+    throw new Error(`Both names must start with '@'`);
+  }
+  const cwd = options.cwd ?? process.cwd();
+  const dirs = resolveSnippetDirs(cwd);
+  const map = await loadSnippets(dirs);
+  const variants = map.get(oldName);
+  if (!variants || variants.length === 0)
+    throw new Error(`Snippet not found: ${oldName}`);
+  const local = variants.filter((v) => v.query.source === "local");
+  if (local.length === 0) {
+    throw new Error(`Refusing to rename: '${oldName}' has no local copy.`);
+  }
+  if (map.get(newName)?.some((v) => v.query.source === "local")) {
+    throw new Error(`Target already exists: ${newName}`);
+  }
+  for (const v of local) {
+    const dst = snippetKeyToFile(cwd, newName, "local");
+    const dstWithSuffix = preserveEngineSuffix(v.query.file, dst);
+    await mkdir(dirname(dstWithSuffix), { recursive: true });
+    await rename(v.query.file, dstWithSuffix);
+    await rewriteFrontmatterName(dstWithSuffix, newName.slice(1));
+    console.log(`renamed ${v.query.file} \u2192 ${dstWithSuffix}`);
+  }
+}
+function preserveEngineSuffix(srcFile, dstFile) {
+  const m = srcFile.match(/\.(postgres|mysql)\.sql$/);
+  if (!m)
+    return dstFile;
+  return dstFile.replace(/\.sql$/, `.${m[1]}.sql`);
+}
+async function rewriteFrontmatterName(file, newName) {
+  const text2 = await Bun.file(file).text();
+  const updated = text2.replace(/^-- name:.*$/m, `-- name: ${newName}`);
+  await Bun.write(file, updated);
+}
+var init_queries_rename = __esm(() => {
+  init_saved_queries();
+});
+
+// src/commands/queries-copy.ts
+var exports_queries_copy = {};
+__export(exports_queries_copy, {
+  queriesCopy: () => queriesCopy
+});
+import { mkdir as mkdir2, copyFile } from "fs/promises";
+import { dirname as dirname2, basename as basename2 } from "path";
+async function queriesCopy(src, dst, options = {}) {
+  if (!src.startsWith("@") || !dst.startsWith("@")) {
+    throw new Error(`Both names must start with '@'`);
+  }
+  const cwd = options.cwd ?? process.cwd();
+  const dirs = resolveSnippetDirs(cwd);
+  if (options.builtinDirOverride)
+    dirs.builtinDir = options.builtinDirOverride;
+  const map = await loadSnippets(dirs);
+  const variants = map.get(src);
+  if (!variants || variants.length === 0)
+    throw new Error(`Snippet not found: ${src}`);
+  if (map.get(dst)?.some((v) => v.query.source === "local")) {
+    throw new Error(`Target already exists: ${dst}`);
+  }
+  for (const v of variants) {
+    const dstFile = mapEngineSuffix(v.query.file, snippetKeyToFile(cwd, dst, "local"));
+    await mkdir2(dirname2(dstFile), { recursive: true });
+    await copyFile(v.query.file, dstFile);
+    console.log(`copied ${v.query.file} \u2192 ${dstFile}`);
+  }
+}
+function mapEngineSuffix(srcFile, baseDst) {
+  const m = basename2(srcFile).match(/\.(postgres|mysql)\.sql$/);
+  return m ? baseDst.replace(/\.sql$/, `.${m[1]}.sql`) : baseDst;
+}
+var init_queries_copy = __esm(() => {
+  init_saved_queries();
+});
+
+// src/commands/queries-import.ts
+var exports_queries_import = {};
+__export(exports_queries_import, {
+  queriesImport: () => queriesImport
+});
+import { stat, mkdir as mkdir3, copyFile as copyFile2 } from "fs/promises";
+import { basename as basename3, join as join12, extname } from "path";
+async function queriesImport(filePath, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  if (extname(filePath) !== ".sql") {
+    throw new Error(`Expected .sql file, got ${filePath}`);
+  }
+  await stat(filePath);
+  const text2 = await Bun.file(filePath).text();
+  const baseName = options.as ? options.as.replace(/^@/, "") : basename3(filePath, ".sql").replace(/\.(postgres|mysql)$/, "");
+  const key2 = "@" + baseName;
+  parseSavedQuery({ key: key2, file: filePath, source: "local", text: text2 });
+  const targetDir = join12(cwd, ".dbcli/queries");
+  await mkdir3(targetDir, { recursive: true });
+  const target = join12(targetDir, basename3(filePath));
+  if (await Bun.file(target).exists()) {
+    if (!options.force) {
+      const ok = await esm_default4({ message: `Overwrite ${target}?`, default: false });
+      if (!ok)
+        return;
+    }
+  }
+  await copyFile2(filePath, target);
+  console.log(`imported ${filePath} \u2192 ${target}`);
+}
+var init_queries_import = __esm(() => {
+  init_esm14();
+  init_saved_queries();
+});
+
+// src/commands/queries-export.ts
+var exports_queries_export = {};
+__export(exports_queries_export, {
+  queriesExport: () => queriesExport
+});
+import { writeFile } from "fs/promises";
+async function queriesExport(name, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const dirs = resolveSnippetDirs(cwd);
+  const map = await loadSnippets(dirs);
+  const variants = map.get(name);
+  if (!variants || variants.length === 0)
+    throw new Error(`Snippet not found: ${name}`);
+  let chosen = variants;
+  if (options.engine) {
+    chosen = variants.filter((v) => (v.query.meta.engine ?? []).includes(options.engine));
+    if (chosen.length === 0) {
+      throw new Error(`No variant of ${name} matches engine ${options.engine}`);
+    }
+  }
+  if (chosen.length > 1) {
+    const engines = chosen.flatMap((v) => v.query.meta.engine ?? []).join(", ");
+    throw new Error(`Snippet ${name} has multiple engine variants (${engines}); pass --engine to pick one.`);
+  }
+  const text2 = await Bun.file(chosen[0].query.file).text();
+  if (options.output) {
+    await writeFile(options.output, text2, "utf8");
+    console.log(`wrote ${options.output}`);
+  } else {
+    process.stdout.write(text2);
+  }
+}
+var init_queries_export = __esm(() => {
+  init_saved_queries();
+});
+
 // node_modules/commander/esm.mjs
 var import__ = __toESM(require_commander(), 1);
 var {
@@ -77146,7 +78002,7 @@ var {
 // package.json
 var package_default = {
   name: "@carllee1983/dbcli",
-  version: "1.6.0",
+  version: "1.7.0",
   description: "Database CLI for AI agents",
   type: "module",
   publishConfig: {
@@ -77195,6 +78051,7 @@ var package_default = {
     "test:unit": "bun test tests/unit tests/core",
     "test:integration": "bun test tests/integration",
     "test:docker": "docker compose -f docker-compose.test.yml up -d --wait && bun test tests/integration/adapters; docker compose -f docker-compose.test.yml down",
+    typecheck: "tsc --noEmit --pretty false",
     "test:run": "vitest --run",
     "test:bench": "vitest bench --run",
     bench: "bun run test:bench",
@@ -77205,7 +78062,6 @@ var package_default = {
   dependencies: {
     "cli-table3": "^0.6.3",
     commander: "13.0.0",
-    dotenv: "^16.3.1",
     mongodb: "^7.2.0",
     mysql2: "^3.20.0",
     pg: "^8.20.0",
@@ -77294,6 +78150,31 @@ var messages_default = {
     no_results: "No results returned",
     result_count: "Results: {count} row(s)"
   },
+  q: {
+    description: "Run a saved query snippet by @name",
+    missing_param: "Missing required parameters for snippet '{name}'",
+    engine_mismatch: "Engine mismatch for snippet '{name}'",
+    snippet_not_found: "Snippet not found: {name}",
+    dry_run_header: "Dry-run preview (no execution):"
+  },
+  queries: {
+    description: "Manage saved query snippets",
+    list_description: "List saved snippets",
+    show_description: "Show a snippet (frontmatter + SQL)",
+    new_description: "Create a new snippet file",
+    edit_description: "Open a snippet in $EDITOR",
+    check_description: "Validate all snippets",
+    delete_description: "Delete a local snippet file",
+    rename_description: "Rename a local snippet",
+    copy_description: "Copy a snippet from any tier into local",
+    import_description: "Import an external .sql file into local",
+    export_description: "Export a snippet's raw SQL to stdout or file",
+    created: "Created {file}",
+    first_run_hint: "Tip: commit .dbcli-shared/ to share snippets with your team.",
+    no_snippets: "No snippets found. Create one with: dbcli queries new @<name>",
+    check_ok: "\u2713 {count} snippets parsed successfully",
+    check_failed: "\u2717 {count} snippet(s) have errors"
+  },
   errors: {
     message: "Error: {message}",
     invalid_config: "Invalid configuration: {field}",
@@ -77485,6 +78366,31 @@ var messages_default2 = {
     no_results: "\u672A\u8FD4\u56DE\u4EFB\u4F55\u7D50\u679C",
     result_count: "\u7D50\u679C\uFF1A{count} \u5217"
   },
+  q: {
+    description: "\u4F9D @name \u57F7\u884C\u5DF2\u4FDD\u5B58\u7684\u67E5\u8A62\u7247\u6BB5",
+    missing_param: "\u7247\u6BB5 '{name}' \u7F3A\u5C11\u5FC5\u8981\u53C3\u6578",
+    engine_mismatch: "\u7247\u6BB5 '{name}' \u5F15\u64CE\u4E0D\u7B26",
+    snippet_not_found: "\u627E\u4E0D\u5230\u7247\u6BB5\uFF1A{name}",
+    dry_run_header: "Dry-run \u9810\u89BD\uFF08\u4E0D\u6703\u57F7\u884C\uFF09\uFF1A"
+  },
+  queries: {
+    description: "\u7BA1\u7406\u5DF2\u4FDD\u5B58\u7684\u67E5\u8A62\u7247\u6BB5",
+    list_description: "\u5217\u51FA\u6240\u6709\u7247\u6BB5",
+    show_description: "\u986F\u793A\u7247\u6BB5\u5167\u5BB9\uFF08frontmatter + SQL\uFF09",
+    new_description: "\u5EFA\u7ACB\u65B0\u7684\u7247\u6BB5\u6A94",
+    edit_description: "\u4EE5 $EDITOR \u958B\u555F\u7247\u6BB5",
+    check_description: "\u9A57\u8B49\u6240\u6709\u7247\u6BB5",
+    delete_description: "\u522A\u9664 local snippet \u6A94\u6848",
+    rename_description: "\u91CD\u65B0\u547D\u540D local snippet",
+    copy_description: "\u5C07\u4EFB\u4E00\u5C64\u7D1A\u7684 snippet \u8907\u88FD\u5230 local",
+    import_description: "\u532F\u5165\u5916\u90E8 .sql \u6A94\u6848\u5230 local",
+    export_description: "\u5C07 snippet \u539F\u59CB SQL \u8F38\u51FA\u5230 stdout \u6216\u6A94\u6848",
+    created: "\u5DF2\u5EFA\u7ACB {file}",
+    first_run_hint: "\u63D0\u793A\uFF1A\u5C07 .dbcli-shared/ commit \u9032\u7248\u63A7\u53EF\u8207\u5718\u968A\u5171\u4EAB\u7247\u6BB5\u3002",
+    no_snippets: "\u5C1A\u7121\u4EFB\u4F55\u7247\u6BB5\u3002\u57F7\u884C dbcli queries new @<name> \u5EFA\u7ACB\u3002",
+    check_ok: "\u2713 \u6210\u529F\u89E3\u6790 {count} \u500B\u7247\u6BB5",
+    check_failed: "\u2717 \u6709 {count} \u500B\u7247\u6BB5\u89E3\u6790\u5931\u6557"
+  },
   errors: {
     message: "\u932F\u8AA4\uFF1A{message}",
     invalid_config: "\u914D\u7F6E\u7121\u6548\uFF1A{field}",
@@ -78178,8 +79084,8 @@ var configModule = {
             }
             let schema = (v2Config.schemas ?? {})[resolved.name] ?? v2Config.schema;
             try {
-              const { SchemaLayeredLoader: SchemaLayeredLoader3 } = await Promise.resolve().then(() => (init_schema_loader(), exports_schema_loader));
-              const loader = new SchemaLayeredLoader3(storagePath, { connectionName: resolved.name });
+              const { SchemaLayeredLoader: SchemaLayeredLoader2 } = await Promise.resolve().then(() => (init_schema_loader(), exports_schema_loader));
+              const loader = new SchemaLayeredLoader2(storagePath, { connectionName: resolved.name });
               const { cache, index } = await loader.initialize();
               if (index && Object.keys(index.tables).length > 0) {
                 const layeredSchema = {};
@@ -78192,7 +79098,7 @@ var configModule = {
                   schema = layeredSchema;
                 }
               }
-            } catch (error) {
+            } catch {
               console.warn("Warning: Failed to load layered schema cache, falling back to config.json");
             }
             return DbcliConfigSchema.parse({
@@ -78333,7 +79239,7 @@ async function readLineFromStdin(prompt = "") {
         process.stdin.pause();
         process.stdin.removeListener("data", onData);
         process.stdin.removeListener("end", onEnd);
-        resolve2(lines2[0].trim());
+        resolve2((lines2[0] ?? "").trim());
       }
     };
     const onEnd = () => {
@@ -78352,7 +79258,7 @@ async function text(message, defaultValue) {
     return answer.trim() || defaultValue || "";
   }
   try {
-    const { text: inquirerText } = await Promise.resolve().then(() => (init_esm14(), exports_esm));
+    const { input: inquirerText } = await Promise.resolve().then(() => (init_esm14(), exports_esm));
     return await inquirerText({ message, default: defaultValue });
   } catch {
     const displayMessage = defaultValue ? `${message} [${defaultValue}]: ` : `${message}: `;
@@ -78369,9 +79275,9 @@ async function select(message, choices) {
     const answer = await readLineFromStdin("Select option (number): ");
     const selectedIndex = parseInt(answer, 10) - 1;
     if (selectedIndex >= 0 && selectedIndex < choices.length) {
-      return choices[selectedIndex];
+      return choices[selectedIndex] ?? choices[0] ?? "";
     }
-    return choices[0];
+    return choices[0] ?? "";
   }
   try {
     const { select: inquirerSelect } = await Promise.resolve().then(() => (init_esm14(), exports_esm));
@@ -78384,9 +79290,9 @@ async function select(message, choices) {
     const answer = await readLineFromStdin("Select option (number): ");
     const selectedIndex = parseInt(answer, 10) - 1;
     if (selectedIndex >= 0 && selectedIndex < choices.length) {
-      return choices[selectedIndex];
+      return choices[selectedIndex] ?? choices[0] ?? "";
     }
-    return choices[0];
+    return choices[0] ?? "";
   }
 }
 async function confirm(message) {
@@ -78439,7 +79345,7 @@ function mapError(error, system, options) {
       `Verify network connectivity: ping ${options.host} -c 3`
     ]);
   }
-  if (errMsg.includes("authentication") || errMsg.includes("auth") || errMsg.includes("password") || errMsg.includes("access denied") || errMsg.includes("FATAL")) {
+  if (errMsg.includes("authentication") || errMsg.includes("auth") || errMsg.includes("password") || errMsg.includes("access denied") || errMsg.includes("does not exist") || errMsg.includes("role") || errMsg.includes("user") || errMsg.includes("FATAL")) {
     return new ConnectionError("AUTH_FAILED", `Authentication failed \u2014 check your username or password`, [
       `Verify credentials: ${system === "postgresql" ? `psql -U ${options.user} -h ${options.host}` : `mysql -u ${options.user} -h ${options.host}`}`,
       `Check pg_hba.conf (PostgreSQL) or user privileges (MySQL)`,
@@ -78484,7 +79390,7 @@ function parseVersionSegments(version) {
   const match = version.match(/^(\d+(?:\.\d+)*)/);
   if (!match)
     return [];
-  return match[1].split(".").map(Number);
+  return (match[1] ?? "").split(".").map(Number);
 }
 function isMariaDBVersion(versionString) {
   return /mariadb/i.test(versionString);
@@ -78492,10 +79398,10 @@ function isMariaDBVersion(versionString) {
 function extractMariaDBVersion(versionString) {
   const match = versionString.match(/(\d+\.\d+\.\d+)-MariaDB/i);
   if (match)
-    return match[1];
+    return match[1] ?? versionString;
   const prefixMatch = versionString.match(/^5\.5\.5-(\d+\.\d+\.\d+)/);
   if (prefixMatch)
-    return prefixMatch[1];
+    return prefixMatch[1] ?? versionString;
   return versionString;
 }
 function compareVersions(a, b) {
@@ -78514,8 +79420,8 @@ function checkDbVersion(rawVersion, declaredSystem) {
   const system = isMariaDB ? "mariadb" : declaredSystem;
   const serverVersion = isMariaDB ? extractMariaDBVersion(rawVersion) : rawVersion;
   const minVersion = MIN_SUPPORTED_VERSIONS[system];
-  const supported = compareVersions(serverVersion, minVersion) >= 0;
-  return { serverVersion, system, supported, minVersion };
+  const supported = compareVersions(serverVersion, minVersion ?? "0") >= 0;
+  return { serverVersion, system, supported, minVersion: minVersion ?? "0" };
 }
 function warnIfUnsupported(result) {
   if (result.supported)
@@ -78862,7 +79768,7 @@ function parseEnumValues(columnType) {
   const match = columnType.match(/^enum\((.+)\)$/i);
   if (!match)
     return;
-  return match[1].split(",").map((v) => v.trim().replace(/^'|'$/g, ""));
+  return (match[1] ?? "").split(",").map((v) => v.trim().replace(/^'|'$/g, ""));
 }
 
 class MySQLAdapter {
@@ -79139,7 +80045,7 @@ class MongoDBAdapter {
       });
     } catch (error) {
       const code = error?.code;
-      if (code !== "ECONNREFUSED") {
+      if (!["ECONNREFUSED", "ENOTFOUND", "ETIMEOUT", "ETIMEDOUT"].includes(code ?? "")) {
         throw error;
       }
     }
@@ -79164,7 +80070,7 @@ class MongoDBAdapter {
       return this.parseTxtRecords(records);
     } catch (error) {
       const code = error?.code;
-      if (code !== "ECONNREFUSED") {
+      if (!["ECONNREFUSED", "ENOTFOUND", "ETIMEOUT", "ETIMEDOUT"].includes(code ?? "")) {
         throw error;
       }
     }
@@ -79294,7 +80200,7 @@ class MongoDBAdapter {
       name: collectionName,
       columns,
       estimatedRowCount,
-      tableType: "collection"
+      tableType: "table"
     };
   }
   async testConnection() {
@@ -79358,7 +80264,7 @@ class AdapterFactory {
 }
 // src/utils/config-path.ts
 function resolveConfigPath(command, options, fallback = ".dbcli") {
-  for (let current = command;current; current = current.parent) {
+  for (let current = command;current; current = current.parent ?? undefined) {
     const source = current.getOptionValueSource("config");
     if (source && source !== "default") {
       const currentOptions = current.opts();
@@ -80343,7 +81249,10 @@ class SchemaWriter {
     const mapping = SchemaIndexBuilder.calculateFileMapping(index);
     const hotSchemas = {};
     for (const item of mapping.hot) {
-      hotSchemas[item.table] = schema[item.table];
+      const tableSchema = schema[item.table];
+      if (tableSchema) {
+        hotSchemas[item.table] = tableSchema;
+      }
     }
     await this.writer.writeJSON(join9(schemaRoot, "hot-schemas.json"), hotSchemas);
     const coldGroups = {};
@@ -80351,7 +81260,10 @@ class SchemaWriter {
       if (!coldGroups[item.file]) {
         coldGroups[item.file] = {};
       }
-      coldGroups[item.file][item.table] = schema[item.table];
+      const tableSchema = schema[item.table];
+      if (tableSchema) {
+        coldGroups[item.file][item.table] = tableSchema;
+      }
     }
     const coldDir = join9(schemaRoot, "cold");
     await this.ensureDir(coldDir);
@@ -80425,7 +81337,7 @@ class ColumnIndexBuilder {
   findColumnsMatching(pattern) {
     const regex = typeof pattern === "string" ? new RegExp(pattern, "i") : pattern;
     const results = [];
-    for (const [colName, entry] of this.index.columns.entries()) {
+    for (const [, entry] of this.index.columns.entries()) {
       if (regex.test(entry.name)) {
         results.push({
           columnName: entry.name,
@@ -80670,7 +81582,7 @@ class HealthChecker {
     const blacklisted = options.blacklistedColumns || new Set;
     const visibleColumns = schema.columns.filter((c) => !blacklisted.has(`${schema.name}.${c.name}`));
     const countResult = await this.adapter.execute(`SELECT COUNT(*) as count FROM \`${schema.name}\``);
-    const rowCount = countResult[0]?.count || 0;
+    const rowCount = rowsOf(countResult)[0]?.count || 0;
     const nulls = checks.includes("nulls") ? await this.checkNulls(schema.name, visibleColumns, rowCount, sample2) : [];
     const orphans = checks.includes("orphans") ? await this.checkOrphans(schema.name, visibleColumns) : [];
     const duplicates = checks.includes("duplicates") ? await this.checkDuplicates(schema.name, schema.indexes || []) : [];
@@ -80697,7 +81609,7 @@ class HealthChecker {
         const useSample = totalRows > sample2;
         const sql = useSample ? `SELECT COUNT(*) - COUNT(\`${col.name}\`) as null_count FROM (SELECT \`${col.name}\` FROM \`${tableName}\` LIMIT ${sample2}) sub` : `SELECT COUNT(*) - COUNT(\`${col.name}\`) as null_count FROM \`${tableName}\``;
         const result = await this.adapter.execute(sql);
-        const nullCount = result[0]?.null_count || 0;
+        const nullCount = rowsOf(result)[0]?.null_count || 0;
         if (nullCount > 0) {
           const sampleSize = Math.min(totalRows, sample2);
           results.push({
@@ -80726,7 +81638,7 @@ class HealthChecker {
             AND parent.\`${col.foreignKey.column}\` IS NULL
         `;
         const result = await this.adapter.execute(sql);
-        const orphanCount = result[0]?.orphan_count || 0;
+        const orphanCount = rowsOf(result)[0]?.orphan_count || 0;
         if (orphanCount > 0) {
           results.push({
             column: col.name,
@@ -80753,7 +81665,7 @@ class HealthChecker {
           ) dups
         `;
         const result = await this.adapter.execute(sql);
-        const dupCount = result[0]?.dup_count || 0;
+        const dupCount = rowsOf(result)[0]?.dup_count || 0;
         if (dupCount > 0) {
           results.push({
             columns: idx.columns,
@@ -80772,7 +81684,7 @@ class HealthChecker {
       try {
         const sql = `SELECT COUNT(*) as empty_count FROM \`${tableName}\` WHERE \`${col.name}\` = ''`;
         const result = await this.adapter.execute(sql);
-        const count = result[0]?.empty_count || 0;
+        const count = rowsOf(result)[0]?.empty_count || 0;
         if (count > 0) {
           results.push({ column: col.name, count });
         }
@@ -80781,6 +81693,13 @@ class HealthChecker {
     return results;
   }
 }
+function rowsOf(result) {
+  return Array.isArray(result) ? result : result.rows;
+}
+
+// src/core/index.ts
+init_schema_loader();
+
 // src/commands/schema.ts
 init_validation();
 var ALLOWED_FORMATS2 = ["table", "json"];
@@ -80919,8 +81838,8 @@ async function handleSchemaRefresh(adapter, config, options, connectionName, sto
 }
 async function handleSchemaReset(adapter, config, options, connectionName, existingCount, storagePath) {
   if (existingCount > 0 && !options.force) {
-    const { SchemaLayeredLoader: SchemaLayeredLoader3 } = await Promise.resolve().then(() => (init_schema_loader(), exports_schema_loader));
-    const loader = new SchemaLayeredLoader3(storagePath, { connectionName });
+    const { SchemaLayeredLoader: SchemaLayeredLoader2 } = await Promise.resolve().then(() => (init_schema_loader(), exports_schema_loader));
+    const loader = new SchemaLayeredLoader2(storagePath, { connectionName });
     const { index } = await loader.initialize();
     if (!index || Object.keys(index.tables).length === 0) {
       console.log(`\u26A0 This will clear ${existingCount} existing table schemas and re-fetch from database.`);
@@ -81010,8 +81929,8 @@ async function handleFullDatabaseScan(adapter, config, options, connectionName,
     }
   }
   if (existingSchemaCount > 0 && !options.force) {
-    const { SchemaLayeredLoader: SchemaLayeredLoader3 } = await Promise.resolve().then(() => (init_schema_loader(), exports_schema_loader));
-    const loader = new SchemaLayeredLoader3(storagePath, { connectionName });
+    const { SchemaLayeredLoader: SchemaLayeredLoader2 } = await Promise.resolve().then(() => (init_schema_loader(), exports_schema_loader));
+    const loader = new SchemaLayeredLoader2(storagePath, { connectionName });
     const { index } = await loader.initialize();
     if (!index || Object.keys(index.tables).length === 0) {
       console.log(`
@@ -81222,7 +82141,7 @@ function extractAllKeywords(sql) {
   }
   return Array.from(keywords).sort();
 }
-function determineConfidence(type, keyword, sql) {
+function determineConfidence(type, _keyword, _sql) {
   const highConfidenceTypes = [
     "SELECT",
     "INSERT",
@@ -81329,49 +82248,6 @@ function enforcePermission(sql, permission) {
   return result.classification;
 }
 
-// src/utils/levenshtein-distance.ts
-function levenshteinDistance(a, b) {
-  const lenA = a.length;
-  const lenB = b.length;
-  const dp = [];
-  for (let i = 0;i <= lenB; i++) {
-    const row = [];
-    for (let j = 0;j <= lenA; j++) {
-      row[j] = 0;
-    }
-    dp[i] = row;
-  }
-  for (let i = 0;i <= lenB; i++) {
-    const row = dp[i];
-    if (row !== undefined) {
-      row[0] = i;
-    }
-  }
-  for (let j = 0;j <= lenA; j++) {
-    const firstRow = dp[0];
-    if (firstRow !== undefined) {
-      firstRow[j] = j;
-    }
-  }
-  for (let i = 1;i <= lenB; i++) {
-    const currentRow = dp[i];
-    const prevRow = dp[i - 1];
-    if (!currentRow || !prevRow)
-      continue;
-    for (let j = 1;j <= lenA; j++) {
-      if (b.charAt(i - 1) === a.charAt(j - 1)) {
-        currentRow[j] = prevRow[j - 1] ?? 0;
-      } else {
-        const sub = (prevRow[j - 1] ?? 0) + 1;
-        const ins = (currentRow[j - 1] ?? 0) + 1;
-        const del = (prevRow[j] ?? 0) + 1;
-        currentRow[j] = Math.min(sub, ins, del);
-      }
-    }
-  }
-  return dp[lenB]?.[lenA] ?? 0;
-}
-
 // src/utils/error-suggester.ts
 async function suggestTableName(errorMessage, adapter) {
   try {
@@ -81468,7 +82344,7 @@ class QueryExecutor {
       const executionTimeMs = Math.round(performance.now() - start);
       const rows = resultData.rows;
       const affectedRows = resultData.affectedRows;
-      let columnNames = rows.length > 0 ? Object.keys(rows[0]) : [];
+      let columnNames = rows.length > 0 && rows[0] ? Object.keys(rows[0]) : [];
       const columnTypes = columnNames.map((col) => {
         const value = rows[0]?.[col];
         return inferColumnType(value);
@@ -81513,7 +82389,7 @@ class QueryExecutor {
           const enhancedError = new Error(`${errorMessage}
 ` + (suggestions.length > 0 ? `Did you mean: ${suggestions.join(", ")}?` : `Available tables: ${tables.slice(0, 5).join(", ")}...`));
           throw enhancedError;
-        } catch (suggestionError) {
+        } catch {
           throw error;
         }
       }
@@ -81524,19 +82400,19 @@ class QueryExecutor {
 function extractTableName(sql) {
   const match = sql.match(/\bFROM\s+["'`]?([a-zA-Z_][a-zA-Z0-9_]*)["'`]?/i);
   if (match) {
-    return match[1];
+    return match[1] ?? null;
   }
   const insertMatch = sql.match(/\bINSERT\s+INTO\s+["'`]?([a-zA-Z_][a-zA-Z0-9_]*)["'`]?/i);
   if (insertMatch) {
-    return insertMatch[1];
+    return insertMatch[1] ?? null;
   }
   const updateMatch = sql.match(/\bUPDATE\s+["'`]?([a-zA-Z_][a-zA-Z0-9_]*)["'`]?/i);
   if (updateMatch) {
-    return updateMatch[1];
+    return updateMatch[1] ?? null;
   }
   const deleteMatch = sql.match(/\bDELETE\s+FROM\s+["'`]?([a-zA-Z_][a-zA-Z0-9_]*)["'`]?/i);
   if (deleteMatch) {
-    return deleteMatch[1];
+    return deleteMatch[1] ?? null;
   }
   return null;
 }
@@ -81689,7 +82565,9 @@ async function mongoQueryBranch(queryStr, options, config) {
       columnNames: columnNames.filter((col) => !filterResult.omittedColumns.includes(col))
     };
     const formatter = new QueryResultFormatter;
-    const output = formatter.format(queryResult, { format });
+    const output = formatter.format(queryResult, {
+      format
+    });
     const securityNote = blacklistValidator.buildSecurityNotification(collection, filterResult.omittedColumns);
     console.log(output);
     if (securityNote) {
@@ -81701,6 +82579,794 @@ async function mongoQueryBranch(queryStr, options, config) {
   }
 }
 
+// src/core/query-risk-analyzer.ts
+init_size_category();
+
+// src/types/query-risk.ts
+function mapStatementTypeToRiskOperation(type) {
+  if (type === "DROP" || type === "TRUNCATE" || type === "ALTER" || type === "CREATE") {
+    return "DDL";
+  }
+  if (type === "SELECT" || type === "INSERT" || type === "UPDATE" || type === "DELETE" || type === "SHOW" || type === "DESCRIBE" || type === "EXPLAIN") {
+    return type;
+  }
+  return "UNKNOWN";
+}
+
+// src/core/query-risk-analyzer.ts
+function stripCommentsAndSingleQuotedStrings(sql) {
+  let result = "";
+  let i = 0;
+  while (i < sql.length) {
+    const char = sql[i];
+    if (char === "-" && sql[i + 1] === "-") {
+      while (i < sql.length && sql[i] !== `
+`)
+        i++;
+      if (i < sql.length) {
+        result += `
+`;
+        i++;
+      }
+      continue;
+    }
+    if (char === "/" && sql[i + 1] === "*") {
+      i += 2;
+      while (i < sql.length) {
+        if (sql[i] === "*" && sql[i + 1] === "/") {
+          i += 2;
+          break;
+        }
+        i++;
+      }
+      result += " ";
+      continue;
+    }
+    if (char === "'") {
+      i++;
+      while (i < sql.length && sql[i] !== "'") {
+        if (sql[i] === "\\")
+          i++;
+        i++;
+      }
+      if (i < sql.length)
+        i++;
+      result += " ";
+      continue;
+    }
+    result += char;
+    i++;
+  }
+  return result;
+}
+var READ_LIKE_WORDS = ["SELECT", "SHOW", "DESCRIBE", "EXPLAIN", "WITH"];
+var WRITE_OR_DDL_LIKE_WORDS = [
+  "INSERT",
+  "UPDATE",
+  "DELETE",
+  "MERGE",
+  "UPSERT",
+  "DROP",
+  "TRUNCATE",
+  "ALTER",
+  "CREATE",
+  "RENAME",
+  "GRANT",
+  "REVOKE"
+];
+function analyzeQueryRisk(input) {
+  const facts = collectSqlFacts(input.sql);
+  const factors = [];
+  applyPermissionRules(input.sql, input.permission, factors);
+  applyWriteWhereRules(facts, factors);
+  applyDdlAndUnknownRules(facts, factors);
+  applySelectPatternRules(facts, factors);
+  applyBlacklistRules(facts, input.blacklist, factors);
+  const schemaGap = applySchemaRules(facts, input.schemaLookup, factors);
+  const recommendations = buildRecommendations(factors, facts);
+  const suggestedCommands = buildSuggestedCommands(facts, schemaGap);
+  return {
+    decision: decide(factors),
+    operation: facts.operation,
+    targetTables: facts.targetTables,
+    riskFactors: factors,
+    recommendations,
+    suggestedCommands
+  };
+}
+function collectSqlFacts(sql) {
+  const normalizedSql = normalizeSql(sql);
+  const analysisSql = normalizeSql(stripCommentsAndSingleQuotedStrings(sql));
+  const classification = classifyStatement(sql);
+  const operation = mapStatementTypeToRiskOperation(classification.type);
+  return {
+    normalizedSql,
+    analysisSql,
+    operation,
+    targetTables: extractTargetTables(analysisSql, operation),
+    referencedColumns: extractReferencedColumns(analysisSql, operation),
+    hasWhere: /\bWHERE\b/i.test(analysisSql),
+    hasLimit: /\bLIMIT\b/i.test(analysisSql),
+    hasSelectStar: /^\s*SELECT\s+(?:DISTINCT\s+)?\*/i.test(analysisSql),
+    appearsReadLike: READ_LIKE_WORDS.some((word) => new RegExp(`\\b${word}\\b`, "i").test(analysisSql)),
+    appearsWriteOrDdlLike: WRITE_OR_DDL_LIKE_WORDS.some((word) => new RegExp(`\\b${word}\\b`, "i").test(analysisSql))
+  };
+}
+function normalizeSql(sql) {
+  return sql.trim().replace(/\s+/g, " ");
+}
+function extractTargetTables(sql, operation) {
+  const cteAliases = extractCteAliases(sql);
+  const tables = new Set;
+  const add = (value) => {
+    const cleaned = cleanIdentifier(value);
+    if (!cleaned)
+      return;
+    if (cteAliases.has(cleaned.toLowerCase()))
+      return;
+    tables.add(cleaned);
+  };
+  if (operation === "UPDATE") {
+    add(sql.match(/\bUPDATE\s+([`"\[]?[\w.]+[`"\]]?)/i)?.[1]);
+  }
+  if (operation === "DELETE") {
+    add(sql.match(/\bDELETE\s+FROM\s+([`"\[]?[\w.]+[`"\]]?)/i)?.[1]);
+  }
+  if (operation === "INSERT") {
+    add(sql.match(/\bINSERT\s+INTO\s+([`"\[]?[\w.]+[`"\]]?)/i)?.[1]);
+  }
+  const fromJoinPattern = /\b(?:FROM|JOIN)\s+([`"\[]?[\w.]+[`"\]]?)/gi;
+  for (const match of sql.matchAll(fromJoinPattern)) {
+    add(match[1]);
+  }
+  return Array.from(tables);
+}
+function extractCteAliases(sql) {
+  const aliases = new Set;
+  const withMatch = sql.match(/\bWITH\b/i);
+  if (!withMatch || withMatch.index === undefined)
+    return aliases;
+  const tail = sql.slice(withMatch.index + withMatch[0].length);
+  const aliasPattern = /([`"\[]?[\w]+[`"\]]?)\s+AS\s*\(/gi;
+  for (const match of tail.matchAll(aliasPattern)) {
+    const cleaned = cleanIdentifier(match[1]);
+    if (cleaned)
+      aliases.add(cleaned.toLowerCase());
+  }
+  return aliases;
+}
+function cleanIdentifier(value) {
+  if (!value)
+    return null;
+  const trimmed = value.trim().replace(/^[`"\[]|[`"\]]$/g, "");
+  const withoutSchema = trimmed.includes(".") ? trimmed.split(".").slice(-1)[0] : trimmed;
+  if (!withoutSchema)
+    return null;
+  if (/^(SELECT|WHERE|JOIN|ON|SET|VALUES)$/i.test(withoutSchema))
+    return null;
+  return withoutSchema;
+}
+function extractReferencedColumns(sql, operation) {
+  const columns = new Set;
+  const add = (value) => {
+    const cleaned = cleanIdentifier(value);
+    if (cleaned && cleaned !== "*")
+      columns.add(cleaned);
+  };
+  if (operation === "SELECT") {
+    const selectList = sql.match(/^\s*SELECT\s+(?:DISTINCT\s+)?(.+?)\s+FROM\s+/i)?.[1];
+    if (selectList && selectList.trim() !== "*") {
+      for (const part of selectList.split(",")) {
+        const expression = part.trim().replace(/\s+AS\s+[`"\[]?[\w]+[`"\]]?$/i, "");
+        const simpleColumn = expression.match(/^(?:[`"\[]?[\w]+[`"\]]?\.)?([`"\[]?[\w]+[`"\]]?)$/)?.[1];
+        add(simpleColumn);
+      }
+    }
+  }
+  if (operation === "UPDATE") {
+    const setList = sql.match(/\bSET\s+(.+?)(?:\s+WHERE\s+|$)/i)?.[1];
+    if (setList) {
+      for (const part of setList.split(",")) {
+        add(part.match(/^\s*([`"\[]?[\w]+[`"\]]?)\s*=/)?.[1]);
+      }
+    }
+  }
+  if (operation === "INSERT") {
+    const insertColumns = sql.match(/\bINSERT\s+INTO\s+[`"\[]?[\w.]+[`"\]]?\s*\(([^)]+)\)/i)?.[1];
+    if (insertColumns) {
+      for (const part of insertColumns.split(","))
+        add(part.trim());
+    }
+  }
+  return Array.from(columns);
+}
+function applyPermissionRules(sql, permission, factors) {
+  const permissionResult = checkPermission(sql, permission);
+  if (!permissionResult.allowed) {
+    pushFactor(factors, "permission_denied", "block", permissionResult.reason);
+  }
+}
+function applyWriteWhereRules(facts, factors) {
+  if ((facts.operation === "UPDATE" || facts.operation === "DELETE") && !facts.hasWhere) {
+    pushFactor(factors, "write_missing_where", "block", `${facts.operation} statement has no WHERE clause.`);
+  }
+}
+function applyDdlAndUnknownRules(facts, factors) {
+  if (/\b(DROP|TRUNCATE)\b/i.test(facts.analysisSql)) {
+    pushFactor(factors, "destructive_ddl", "block", "Statement appears to contain destructive DDL.");
+    return;
+  }
+  if (/\bALTER\b/i.test(facts.analysisSql)) {
+    pushFactor(factors, "destructive_ddl", "block", "ALTER statements are unsupported by plan and may be destructive.");
+    return;
+  }
+  if (facts.operation === "DDL") {
+    pushFactor(factors, "unsupported_ddl", "block", "DDL statements are unsupported by plan.");
+    return;
+  }
+  if (facts.operation === "UNKNOWN" && facts.appearsWriteOrDdlLike) {
+    pushFactor(factors, "unknown_write_or_ddl", "block", "SQL type is unclear and appears write-like or DDL-like.");
+    return;
+  }
+  if (facts.operation === "UNKNOWN" && facts.appearsReadLike) {
+    pushFactor(factors, "unknown_read", "warn", "SQL type is unclear but appears read-like.");
+  }
+}
+function applySelectPatternRules(facts, factors) {
+  if (facts.operation === "SELECT" && facts.hasSelectStar) {
+    pushFactor(factors, "select_star", "warn", "SELECT * may expose unnecessary columns.");
+  }
+}
+function applyBlacklistRules(facts, blacklist, factors) {
+  const blacklistedTables = new Set((blacklist.tables ?? []).map((table) => table.toLowerCase()));
+  for (const table of facts.targetTables) {
+    if (blacklistedTables.has(table.toLowerCase())) {
+      pushFactor(factors, "table_blacklisted", "block", `Target table ${table} is blacklisted.`);
+    }
+  }
+  for (const table of facts.targetTables) {
+    const blacklistedColumns = findBlacklistedColumnsForTable(blacklist, table);
+    for (const column of facts.referencedColumns) {
+      if (blacklistedColumns.has(column)) {
+        pushFactor(factors, "blacklisted_column", "warn", `Query references blacklisted column ${table}.${column}.`);
+      }
+    }
+  }
+}
+function findBlacklistedColumnsForTable(blacklist, table) {
+  const columns = blacklist.columns ?? {};
+  for (const [tableName, columnNames] of Object.entries(columns)) {
+    if (tableName.toLowerCase() === table.toLowerCase()) {
+      return new Set(columnNames);
+    }
+  }
+  return new Set;
+}
+function applySchemaRules(facts, schemaLookup, factors) {
+  const gap = { cacheMissing: false, unknownTables: [] };
+  if (facts.targetTables.length === 0)
+    return gap;
+  if (!schemaLookup.cacheAvailable) {
+    pushFactor(factors, "schema_cache_missing", "warn", "Schema cache is missing for the selected connection.");
+    gap.cacheMissing = true;
+    return gap;
+  }
+  const knownTables = new Set(Object.keys(schemaLookup.tables).map((table) => table.toLowerCase()));
+  let knownCount = 0;
+  for (const table of facts.targetTables) {
+    const schema = getSchemaForTable(schemaLookup.tables, table);
+    if (!schema || !knownTables.has(table.toLowerCase())) {
+      pushFactor(factors, "schema_table_unknown", "warn", `Target table ${table} is missing from schema cache.`);
+      gap.unknownTables.push(table);
+      continue;
+    }
+    knownCount += 1;
+    const category = getSizeCategory(schema.estimatedRowCount ?? schema.rowCount ?? 0);
+    if (facts.operation === "SELECT" && (category === "large" || category === "huge") && !facts.hasWhere && !facts.hasLimit) {
+      pushFactor(factors, "large_table_unfiltered", "warn", `Target table ${table} is ${category} and the query has no WHERE or LIMIT clause.`);
+    }
+  }
+  if (facts.targetTables.length > 1 && knownCount > 0 && knownCount < facts.targetTables.length) {
+    pushFactor(factors, "partial_schema_coverage", "warn", "Multi-table query has partial schema-cache coverage.");
+  }
+  return gap;
+}
+function getSchemaForTable(tables, table) {
+  return Object.entries(tables).find(([name]) => name.toLowerCase() === table.toLowerCase())?.[1];
+}
+function pushFactor(factors, code, severity, message) {
+  if (factors.some((factor) => factor.code === code && factor.message === message))
+    return;
+  factors.push({ code, severity, message });
+}
+function decide(factors) {
+  if (factors.some((factor) => factor.severity === "block"))
+    return "BLOCK";
+  if (factors.some((factor) => factor.severity === "warn"))
+    return "WARN";
+  return "ALLOW";
+}
+function buildRecommendations(factors, facts) {
+  const recommendations = new Set;
+  const codes = new Set(factors.map((factor) => factor.code));
+  if (codes.has("write_missing_where")) {
+    recommendations.add("Add a WHERE clause.");
+    recommendations.add("Run a SELECT count(*) with the same condition before executing.");
+    recommendations.add("Use --dry-run on the actual write command.");
+  }
+  if (codes.has("permission_denied")) {
+    recommendations.add("Switch to a connection with sufficient permission only if the operation is intended.");
+  }
+  if (codes.has("table_blacklisted") || codes.has("blacklisted_column")) {
+    recommendations.add("Review blacklist rules before accessing sensitive data.");
+  }
+  if (codes.has("destructive_ddl") || codes.has("unsupported_ddl") || codes.has("unknown_write_or_ddl")) {
+    recommendations.add("Do not execute this statement through dbcli without manual review.");
+  }
+  if (codes.has("select_star")) {
+    recommendations.add("Select only the columns required for the task.");
+  }
+  if (codes.has("large_table_unfiltered")) {
+    recommendations.add("Add a WHERE clause or LIMIT before querying a large table.");
+  }
+  if (codes.has("schema_cache_missing") || codes.has("schema_table_unknown") || codes.has("partial_schema_coverage")) {
+    recommendations.add("Refresh schema cache for the target table before executing.");
+  }
+  if (facts.operation === "UPDATE" || facts.operation === "DELETE" || facts.operation === "INSERT") {
+    recommendations.add("Use --dry-run on the actual write command.");
+  }
+  return Array.from(recommendations);
+}
+function buildSuggestedCommands(facts, gap) {
+  const commands = new Set;
+  const targets = gap.cacheMissing ? facts.targetTables : gap.unknownTables;
+  for (const table of targets) {
+    commands.add(`dbcli schema ${table} --format json`);
+  }
+  return Array.from(commands);
+}
+
+// src/commands/plan.ts
+init_validation();
+var ALLOWED_FORMATS4 = ["text", "json"];
+async function planCommand(sql, options, command) {
+  try {
+    if (!sql || sql.trim() === "") {
+      throw new Error("SQL statement required");
+    }
+    const format = options.format ?? "text";
+    validateFormat(format, ALLOWED_FORMATS4, "plan");
+    const configPath = resolveConfigPath(command, options);
+    const config = await configModule.read(configPath);
+    if (!config.connection) {
+      throw new Error('Run "dbcli init" first');
+    }
+    const schema = config.schema ?? {};
+    const schemaTableCount = Object.keys(schema).length;
+    const result = analyzeQueryRisk({
+      sql: sql.trim(),
+      permission: config.permission,
+      blacklist: config.blacklist ?? { tables: [], columns: {} },
+      schemaLookup: {
+        tables: schema,
+        cacheAvailable: schemaTableCount > 0
+      }
+    });
+    console.log(formatPlanResult(result, format));
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+function formatPlanResult(result, format) {
+  if (format === "json") {
+    return JSON.stringify(result, null, 2);
+  }
+  return formatPlanText(result);
+}
+function formatPlanText(result) {
+  const lines2 = [
+    `Decision: ${result.decision}`,
+    `Operation: ${result.operation}`,
+    `Target tables: ${result.targetTables.length > 0 ? result.targetTables.join(", ") : "(none)"}`
+  ];
+  if (result.riskFactors.length > 0) {
+    lines2.push("", "Risk factors:");
+    for (const factor of result.riskFactors) {
+      lines2.push(`- ${factor.message}`);
+    }
+  }
+  if (result.recommendations.length > 0) {
+    lines2.push("", "Recommendations:");
+    for (const recommendation of result.recommendations) {
+      lines2.push(`- ${recommendation}`);
+    }
+  }
+  return lines2.join(`
+`);
+}
+
+// src/commands/q.ts
+init_saved_queries();
+async function qCommand(name, options, command) {
+  try {
+    if (!name?.startsWith("@")) {
+      throw new Error(`Snippet name must start with '@' (got '${name}')`);
+    }
+    const configPath = resolveConfigPath(command, options);
+    const config = await configModule.read(configPath);
+    if (!config.connection)
+      throw new Error('Run "dbcli init" first');
+    const engine = mapSystemToEngine(config.connection.system);
+    if (engine === "mongodb") {
+      throw new Error("Saved queries do not support MongoDB connections");
+    }
+    const dirs = resolveSnippetDirs(process.cwd());
+    const map = await loadSnippets(dirs);
+    const snippet = resolveByName(map, name, engine);
+    const cliParams = parseCliParams(options.param ?? []);
+    const fileParams = await readParamFile(options.paramFile);
+    const prepared = prepareExecution(snippet, { engine, noLimit: options.noLimit === true }, cliParams, fileParams);
+    for (const w of prepared.warnings)
+      console.error(`\u26A0 ${w}`);
+    if (options.dryRun) {
+      console.log("Dry-run preview (no execution):");
+      console.log(prepared.driver.sql);
+      console.log("Bind values: " + JSON.stringify(prepared.driver.values));
+      return;
+    }
+    const adapter = AdapterFactory.createAdapter(config.connection);
+    await adapter.connect();
+    try {
+      const blacklistManager = new BlacklistManager(config);
+      const blacklistValidator = new BlacklistValidator(blacklistManager);
+      const start = performance.now();
+      const result = await adapter.execute(prepared.driver.sql, prepared.driver.values);
+      const executionTimeMs = Math.round(performance.now() - start);
+      const columnNames = result.rows[0] ? Object.keys(result.rows[0]) : [];
+      const filtered = blacklistValidator.filterColumns("", result.rows, columnNames);
+      const formatter = new QueryResultFormatter;
+      const out = formatter.format({
+        rows: filtered.filteredRows,
+        rowCount: filtered.filteredRows.length,
+        columnNames: columnNames.filter((c) => !filtered.omittedColumns.includes(c)),
+        columnTypes: [],
+        executionTimeMs,
+        metadata: {
+          statement: "SELECT",
+          affectedRows: 0,
+          ...filtered.omittedColumns.length > 0 ? {
+            securityNotification: blacklistValidator.buildSecurityNotification("", filtered.omittedColumns)
+          } : {}
+        }
+      }, { format: options.format ?? "table" });
+      console.log(out);
+    } finally {
+      await adapter.disconnect();
+    }
+  } catch (error) {
+    handleQError(error);
+  }
+}
+function parseCliParams(list) {
+  const out = {};
+  for (const item of list) {
+    const eq = item.indexOf("=");
+    if (eq === -1)
+      throw new Error(`--param must be key=value (got '${item}')`);
+    out[item.slice(0, eq)] = item.slice(eq + 1);
+  }
+  return out;
+}
+async function readParamFile(path) {
+  if (!path)
+    return {};
+  const text2 = await Bun.file(path).text();
+  const parsed = JSON.parse(text2);
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`--param-file must be a JSON object (got ${typeof parsed})`);
+  }
+  return parsed;
+}
+function handleQError(error) {
+  if (error instanceof SavedQueryError) {
+    console.error(error.message);
+    process.exit(1);
+  }
+  if (error instanceof BlacklistError) {
+    console.error(error.message);
+    process.exit(1);
+  }
+  if (error instanceof PermissionError) {
+    console.error(t_vars("errors.permission_denied", { required: error.requiredPermission }));
+    process.exit(1);
+  }
+  if (error instanceof ConnectionError) {
+    console.error(t_vars("errors.connection_failed", { message: error.message }));
+    process.exit(1);
+  }
+  console.error(t_vars("errors.message", { message: error.message }));
+  process.exit(1);
+}
+
+// src/commands/queries.ts
+import { mkdir as mkdir4, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname3 } from "path";
+import { spawn } from "child_process";
+init_saved_queries();
+async function deriveEngine() {
+  try {
+    const cfg = await configModule.read(resolveConfigPath(undefined, {}));
+    if (cfg.connection) {
+      const engine = mapSystemToEngine(cfg.connection.system);
+      if (engine !== "mongodb")
+        return engine;
+    }
+  } catch {}
+  return "postgres";
+}
+async function queriesList(options) {
+  const map = await loadSnippets(resolveSnippetDirs(process.cwd()));
+  const folded = [...map.entries()].map(([key2, variants]) => foldVariants(key2, variants)).filter((r) => matchesFolded(r, options));
+  if (options.format === "json") {
+    console.log(JSON.stringify(folded, null, 2));
+    return;
+  }
+  if (folded.length === 0) {
+    console.log(t("queries.no_snippets"));
+    return;
+  }
+  const header = ["NAME", "SOURCES", "ENGINES", "PARAMS", "DESCRIPTION"];
+  const cells = folded.map((r) => [
+    r.name + (r.hasLocalOverride ? "*" : ""),
+    r.sources.join(","),
+    r.engines.join(",") || "-",
+    r.params.join(", ") || "-",
+    r.description
+  ]);
+  const widths = header.map((h, i) => Math.max(h.length, ...cells.map((c) => (c[i] ?? "").length)));
+  const fmt = (line) => line.map((c, i) => (c ?? "").padEnd(widths[i] ?? 0)).join("  ");
+  console.log(fmt(header));
+  for (const c of cells)
+    console.log(fmt(c));
+}
+var FOLD_SOURCE_RANK = { builtin: 0, shared: 1, local: 2 };
+function foldVariants(key2, variants) {
+  const sources = unique(variants.map((v) => v.query.source)).sort();
+  const engines = unique(variants.flatMap((v) => v.query.meta.engine ?? [])).sort();
+  const tags = unique(variants.flatMap((v) => v.query.meta.tags ?? []));
+  const top = variants.slice().sort((a, b) => FOLD_SOURCE_RANK[b.query.source] - FOLD_SOURCE_RANK[a.query.source])[0];
+  return {
+    name: key2,
+    sources,
+    engines,
+    params: top.query.meta.params.map((p) => p.name),
+    description: top.query.meta.description ?? "",
+    tags,
+    hasLocalOverride: variants.some((v) => v.hasLocalOverride)
+  };
+}
+function unique(xs) {
+  return [...new Set(xs)];
+}
+function snippetToJson(s) {
+  return {
+    name: s.query.meta.key,
+    source: s.query.source,
+    engine: s.query.meta.engine?.length === 1 ? s.query.meta.engine[0] : s.query.meta.engine,
+    description: s.query.meta.description,
+    params: s.query.meta.params.map((p) => ({
+      name: p.name,
+      type: p.type,
+      ...p.default !== undefined ? { default: p.default } : {},
+      ...p.required ? { required: true } : {},
+      ...p.description ? { description: p.description } : {},
+      ...p.enum ? { enum: p.enum } : {}
+    })),
+    tags: s.query.meta.tags,
+    file: s.query.file,
+    hasLocalOverride: s.hasLocalOverride || undefined
+  };
+}
+function matchesFolded(r, opts) {
+  if (opts.tag && !r.tags.includes(opts.tag))
+    return false;
+  if (opts.engine) {
+    if (r.engines.length > 0 && !r.engines.includes(opts.engine))
+      return false;
+  }
+  if (opts.source && !r.sources.includes(opts.source))
+    return false;
+  return true;
+}
+async function queriesShow(name, options) {
+  const map = await loadSnippets(resolveSnippetDirs(process.cwd()));
+  try {
+    const engine = await deriveEngine();
+    const snippet = resolveByName(map, name, engine);
+    if (options.format === "json") {
+      console.log(JSON.stringify({ ...snippetToJson(snippet), sql: snippet.query.sqlBody.trim() }, null, 2));
+      return;
+    }
+    console.log(`# ${snippet.query.meta.name}  (${snippet.query.source})`);
+    if (snippet.query.meta.description)
+      console.log(`# ${snippet.query.meta.description}`);
+    if (snippet.query.meta.engine)
+      console.log(`# engine: ${snippet.query.meta.engine.join(",")}`);
+    if (snippet.query.meta.params.length > 0) {
+      console.log("# params:");
+      for (const p of snippet.query.meta.params) {
+        const def = p.default !== undefined ? ` (default: ${p.default})` : "";
+        const req = p.required ? " (required)" : "";
+        console.log(`#   ${p.name}: ${p.type}${req}${def}`);
+      }
+    }
+    console.log("");
+    console.log(snippet.query.sqlBody.trim());
+  } catch (e) {
+    console.error(e.message);
+    process.exit(1);
+  }
+}
+async function queriesNew(name, options) {
+  if (!name.startsWith("@")) {
+    console.error(`Snippet name must start with '@' (got '${name}')`);
+    process.exit(1);
+    return;
+  }
+  const source = options.local ? "local" : "shared";
+  const file = snippetKeyToFile(process.cwd(), name, source);
+  if (await Bun.file(file).exists()) {
+    console.error(`Snippet already exists: ${file}`);
+    process.exit(1);
+    return;
+  }
+  await mkdir4(dirname3(file), { recursive: true });
+  await writeFile2(file, scaffold(name), "utf8");
+  console.log(`Created ${file}`);
+  if (source === "shared")
+    console.log(t("queries.first_run_hint"));
+  if (options.edit)
+    await openInEditor(file);
+}
+async function queriesEdit(name, options) {
+  const candidates = options.shared ? [snippetKeyToFile(process.cwd(), name, "shared")] : [
+    snippetKeyToFile(process.cwd(), name, "local"),
+    snippetKeyToFile(process.cwd(), name, "shared")
+  ];
+  for (const f of candidates) {
+    if (await Bun.file(f).exists()) {
+      await openInEditor(f);
+      return;
+    }
+  }
+  console.error(`Snippet not found locally or in shared: ${name}`);
+  process.exit(1);
+}
+async function queriesCheck(options) {
+  const dirs = resolveSnippetDirs(process.cwd());
+  let failed = 0;
+  let total = 0;
+  try {
+    const map = await loadSnippets(dirs);
+    for (const variants of map.values()) {
+      for (const snippet of variants) {
+        total++;
+        try {
+          const text2 = await Bun.file(snippet.query.file).text();
+          const result = parseSavedQuery({
+            key: snippet.query.meta.key,
+            file: snippet.query.file,
+            source: snippet.query.source,
+            text: text2
+          });
+          if (options.strict && result.warnings.length > 0) {
+            console.error(`\u2717 ${snippet.query.meta.key}: ${result.warnings.join("; ")}`);
+            failed++;
+          }
+        } catch (e) {
+          const msg = e instanceof SavedQueryError ? e.message : e.message;
+          console.error(`\u2717 ${snippet.query.meta.key}: ${msg}`);
+          failed++;
+        }
+      }
+    }
+  } catch (e) {
+    const msg = e instanceof SavedQueryError ? e.message : e.message;
+    console.error(`\u2717 ${msg}`);
+    failed++;
+  }
+  if (failed > 0) {
+    console.error(`\u2717 ${failed} snippet(s) have errors`);
+    process.exit(1);
+  } else {
+    console.log(`\u2713 ${total} snippets parsed successfully`);
+  }
+}
+function scaffold(name) {
+  return [
+    "-- ---",
+    `-- name: ${name.replace(/^@/, "")}`,
+    "-- description: TODO",
+    "-- engine: postgres",
+    "-- params: {}",
+    "-- tags: []",
+    "-- ---",
+    "",
+    "SELECT 1;",
+    ""
+  ].join(`
+`);
+}
+async function openInEditor(file) {
+  const editor = process.env.EDITOR || "vi";
+  await new Promise((resolve3, reject) => {
+    const child = spawn(editor, [file], { stdio: "inherit" });
+    child.on("exit", (code) => code === 0 ? resolve3() : reject(new Error(`Editor exited with ${code}`)));
+  });
+}
+var queriesCommand = new Command("queries").description(t("queries.description"));
+queriesCommand.command("list").description(t("queries.list_description")).option("--format <type>", "Output format: table, json, csv", "table").option("--tag <tag>", "Filter by tag").option("--engine <engine>", "Filter by engine: postgres | mysql").option("--source <source>", "Filter by source: local | shared").action(async (options) => {
+  await queriesList(options);
+});
+queriesCommand.command("show <name>").description(t("queries.show_description")).option("--format <type>", "Output format: table, json, csv", "table").action(async (name, options) => {
+  await queriesShow(name, options);
+});
+queriesCommand.command("new <name>").description(t("queries.new_description")).option("--local", "Create under .dbcli/queries (gitignored) instead of .dbcli-shared/").option("--edit", "Open the created file in $EDITOR").action(async (name, options) => {
+  await queriesNew(name, options);
+});
+queriesCommand.command("edit <name>").description(t("queries.edit_description")).option("--shared", "Edit the shared file instead of local").action(async (name, options) => {
+  await queriesEdit(name, options);
+});
+queriesCommand.command("check").description(t("queries.check_description")).option("--strict", "Promote warnings to errors").option("--format <type>", "Output format: table, json, csv", "table").action(async (options) => {
+  await queriesCheck(options);
+});
+queriesCommand.command("delete <name>").description(t("queries.delete_description")).option("--force", "Skip confirmation prompt").action(async (name, options) => {
+  try {
+    const { queriesDelete: queriesDelete2 } = await Promise.resolve().then(() => (init_queries_delete(), exports_queries_delete));
+    await queriesDelete2(name, options);
+  } catch (e) {
+    console.error(e.message);
+    process.exit(1);
+  }
+});
+queriesCommand.command("rename <old> <new>").description(t("queries.rename_description")).option("--force", "Skip confirmation prompt").action(async (oldName, newName, options) => {
+  try {
+    const { queriesRename: queriesRename2 } = await Promise.resolve().then(() => (init_queries_rename(), exports_queries_rename));
+    await queriesRename2(oldName, newName, options);
+  } catch (e) {
+    console.error(e.message);
+    process.exit(1);
+  }
+});
+queriesCommand.command("copy <src> <dst>").description(t("queries.copy_description")).action(async (src, dst) => {
+  try {
+    const { queriesCopy: queriesCopy2 } = await Promise.resolve().then(() => (init_queries_copy(), exports_queries_copy));
+    await queriesCopy2(src, dst);
+  } catch (e) {
+    console.error(e.message);
+    process.exit(1);
+  }
+});
+queriesCommand.command("import <path>").description(t("queries.import_description")).option("--force", "Overwrite existing file without prompting").option("--as <name>", "Override snippet name (defaults to filename)").action(async (path, options) => {
+  try {
+    const { queriesImport: queriesImport2 } = await Promise.resolve().then(() => (init_queries_import(), exports_queries_import));
+    await queriesImport2(path, options);
+  } catch (e) {
+    console.error(e.message);
+    process.exit(1);
+  }
+});
+queriesCommand.command("export <name>").description(t("queries.export_description")).option("--output <path>", "Write to a file instead of stdout").option("--engine <engine>", "Pick a specific variant: postgres | mysql").action(async (name, options) => {
+  try {
+    const { queriesExport: queriesExport2 } = await Promise.resolve().then(() => (init_queries_export(), exports_queries_export));
+    await queriesExport2(name, options);
+  } catch (e) {
+    console.error(e.message);
+    process.exit(1);
+  }
+});
+
 // src/core/data-executor.ts
 class DataExecutor {
   adapter;
@@ -82568,11 +84234,11 @@ async function writeSkillInstall(platform, installPath, skillMarkdown, reference
 async function ensureDir(dirPath) {
   try {
     await $`mkdir -p ${dirPath}`.quiet();
-  } catch (error) {
+  } catch {
     try {
-      const { mkdir } = await import("fs/promises");
-      await mkdir(dirPath, { recursive: true });
-    } catch (fsError) {
+      const { mkdir: mkdir5 } = await import("fs/promises");
+      await mkdir5(dirPath, { recursive: true });
+    } catch {
       throw new Error(`Cannot create directory: ${dirPath}`);
     }
   }
@@ -82657,7 +84323,7 @@ async function blacklistTableRemove(tableName, configPath) {
   }
   const newBlacklist = {
     ...blacklist,
-    tables: blacklist.tables.filter((t6) => t6 !== tableName)
+    tables: blacklist.tables.filter((t2) => t2 !== tableName)
   };
   await configModule.write(configPath, { ...config, blacklist: newBlacklist });
   console.log(t_vars("blacklist.table_removed", { table: tableName }));
@@ -82757,11 +84423,11 @@ columnCmd.command("remove <table.column>").description("Remove column from black
 // src/commands/check.ts
 init_size_category();
 init_validation();
-var ALLOWED_FORMATS4 = ["json", "table"];
+var ALLOWED_FORMATS5 = ["json", "table"];
 var checkCommand = new Command().name("check").description("Run data health checks on tables").argument("[table]", "Table to check (omit for --all)").option("--all", "Check all tables (skips huge tables unless --include-large)", false).option("--include-large", "Include huge tables in --all scan", false).option("--checks <types>", "Comma-separated checks: nulls,duplicates,orphans,emptyStrings", undefined).option("--sample <number>", "Sample size for large tables (default: 10000)", "10000").option("--format <format>", "Output format: json (default) or table", "json").option("--config <path>", "Path to .dbcli config file", ".dbcli").action(checkAction);
 async function checkAction(table, options) {
   try {
-    validateFormat(options.format, ALLOWED_FORMATS4, "check");
+    validateFormat(options.format, ALLOWED_FORMATS5, "check");
     const config = await configModule.read(options.config);
     if (!config.connection) {
       console.error("Database not configured. Run: dbcli init");
@@ -82792,21 +84458,21 @@ async function checkAction(table, options) {
         const tables = await adapter.listTables();
         const reports = [];
         const skipped = [];
-        for (const t6 of tables) {
-          if (blacklistedTables.has(t6.name.toLowerCase())) {
-            skipped.push(`${t6.name} (blacklisted)`);
+        for (const t2 of tables) {
+          if (blacklistedTables.has(t2.name.toLowerCase())) {
+            skipped.push(`${t2.name} (blacklisted)`);
             continue;
           }
-          if (t6.tableType === "view") {
-            skipped.push(`${t6.name} (view)`);
+          if (t2.tableType === "view") {
+            skipped.push(`${t2.name} (view)`);
             continue;
           }
-          const category = getSizeCategory(t6.estimatedRowCount);
+          const category = getSizeCategory(t2.estimatedRowCount);
           if (category === "huge" && !options.includeLarge) {
-            skipped.push(`${t6.name} (~${(t6.estimatedRowCount || 0).toLocaleString()} rows, huge)`);
+            skipped.push(`${t2.name} (~${(t2.estimatedRowCount || 0).toLocaleString()} rows, huge)`);
             continue;
           }
-          const schema = await adapter.getTableSchema(t6.name);
+          const schema = await adapter.getTableSchema(t2.name);
           const report = await checker.check(schema, {
             checks: checkTypes,
             sample: sampleSize,
@@ -82886,12 +84552,12 @@ function getBlacklistedTableSet(manager) {
 
 // src/commands/diff.ts
 init_validation();
-var ALLOWED_FORMATS5 = ["json", "table"];
+var ALLOWED_FORMATS6 = ["json", "table"];
 function compareSnapshots(before, after) {
   const beforeTables = new Set(Object.keys(before.tables));
   const afterTables = new Set(Object.keys(after.tables));
-  const addedTables = Array.from(afterTables).filter((t6) => !beforeTables.has(t6));
-  const removedTables = Array.from(beforeTables).filter((t6) => !afterTables.has(t6));
+  const addedTables = Array.from(afterTables).filter((t2) => !beforeTables.has(t2));
+  const removedTables = Array.from(beforeTables).filter((t2) => !afterTables.has(t2));
   const addedColumns = [];
   const removedColumns = [];
   const modifiedColumns = [];
@@ -82917,7 +84583,7 @@ function compareSnapshots(before, after) {
       removedColumns.push({ table: tableName, column: col.name, type: col.type });
     }
   }
-  const commonTables = Array.from(afterTables).filter((t6) => beforeTables.has(t6));
+  const commonTables = Array.from(afterTables).filter((t2) => beforeTables.has(t2));
   for (const tableName of commonTables) {
     const beforeTable = before.tables[tableName];
     const afterTable = after.tables[tableName];
@@ -82980,7 +84646,7 @@ function compareSnapshots(before, after) {
 var diffCommand = new Command().name("diff").description("Compare schema snapshots to detect changes").option("--snapshot <path>", "Save current schema snapshot to file").option("--against <path>", "Compare current schema against a snapshot file").option("--format <format>", "Output format: json (default) or table", "json").option("--config <path>", "Path to .dbcli config file", ".dbcli").action(diffAction);
 async function diffAction(options) {
   try {
-    validateFormat(options.format, ALLOWED_FORMATS5, "diff");
+    validateFormat(options.format, ALLOWED_FORMATS6, "diff");
     if (!options.snapshot && !options.against) {
       console.error("Specify --snapshot <path> to save, or --against <path> to compare");
       process.exit(1);
@@ -83002,11 +84668,11 @@ async function diffAction(options) {
         tables: {},
         createdAt: new Date().toISOString()
       };
-      for (const t6 of tables) {
-        if (t6.tableType === "view")
+      for (const t2 of tables) {
+        if (t2.tableType === "view")
           continue;
-        const schema = await adapter.getTableSchema(t6.name);
-        currentSnapshot.tables[t6.name] = {
+        const schema = await adapter.getTableSchema(t2.name);
+        currentSnapshot.tables[t2.name] = {
           name: schema.name,
           columns: schema.columns,
           indexes: schema.indexes || []
@@ -83080,10 +84746,10 @@ Schema diff (${beforeSnapshot.createdAt} -> ${currentSnapshot.createdAt}):`);
 
 // src/commands/status.ts
 init_validation();
-var ALLOWED_FORMATS6 = ["text", "json"];
+var ALLOWED_FORMATS7 = ["text", "json"];
 var statusCommand = new Command("status").description("Show current configuration status (safe for AI agents, no credentials exposed)").option("--format <type>", "Output format: text, json", "json").action(async (options) => {
   try {
-    validateFormat(options.format, ALLOWED_FORMATS6, "status");
+    validateFormat(options.format, ALLOWED_FORMATS7, "status");
     const configPath = resolveConfigPath(statusCommand);
     const config = await configModule.read(configPath);
     if (!config.connection) {
@@ -83119,9 +84785,9 @@ var statusCommand = new Command("status").description("Show current configuratio
 // src/commands/doctor.ts
 init_validation();
 init_schema_path();
-import { join as join11 } from "path";
+import { join as join14 } from "path";
 import { resolveSrv as resolveSrv2 } from "dns/promises";
-var ALLOWED_FORMATS7 = ["text", "json"];
+var ALLOWED_FORMATS8 = ["text", "json"];
 var SENSITIVE_PATTERNS = [
   "password",
   "passwd",
@@ -83193,7 +84859,7 @@ var runDoctorChecks = {
     }
   },
   async checkConfigExists(configPath, existsFn) {
-    const exists = existsFn ? await existsFn(configPath) : await Bun.file(configPath).exists() || await Bun.file(join11(configPath, "config.json")).exists();
+    const exists = existsFn ? await existsFn(configPath) : await Bun.file(configPath).exists() || await Bun.file(join14(configPath, "config.json")).exists();
     return {
       group: "Configuration",
       label: "Config exists",
@@ -83330,7 +84996,7 @@ var runDoctorChecks = {
     }
   },
   checkLargeTables(tables) {
-    const large = tables.filter((t6) => (t6.estimatedRowCount ?? 0) > 1e6);
+    const large = tables.filter((t2) => (t2.estimatedRowCount ?? 0) > 1e6);
     if (large.length === 0) {
       return {
         group: "Connection & Data",
@@ -83339,7 +85005,7 @@ var runDoctorChecks = {
         message: "No tables exceed 1M rows"
       };
     }
-    const list = large.map((t6) => `${t6.name} (${((t6.estimatedRowCount ?? 0) / 1e6).toFixed(1)}M rows)`).join(", ");
+    const list = large.map((t2) => `${t2.name} (${((t2.estimatedRowCount ?? 0) / 1e6).toFixed(1)}M rows)`).join(", ");
     return {
       group: "Connection & Data",
       label: "Large tables",
@@ -83350,7 +85016,7 @@ var runDoctorChecks = {
   async checkV2Config(configPath) {
     const results = [];
     const storagePath = await resolveConfigStoragePath(configPath);
-    const configFile = Bun.file(join11(storagePath, "config.json"));
+    const configFile = Bun.file(join14(storagePath, "config.json"));
     if (!await configFile.exists())
       return results;
     let raw;
@@ -83390,7 +85056,7 @@ var runDoctorChecks = {
     }
     for (const [name, conn] of Object.entries(config.connections)) {
       if (conn.envFile) {
-        const envPath = join11(storagePath, conn.envFile);
+        const envPath = join14(storagePath, conn.envFile);
         const exists = await Bun.file(envPath).exists();
         results.push({
           group: "Configuration",
@@ -83453,10 +85119,12 @@ async function collectMongoDoctorResults(config) {
         message: `MongoDB ${version}`
       });
     } catch {}
-    const collections = await adapter.listTables();
+    const collections = adapter.listTables ? await adapter.listTables() : [];
     const tableColumns = new Map;
     for (const coll of collections) {
       try {
+        if (!adapter.getTableSchema)
+          continue;
         const schema = await adapter.getTableSchema(coll.name);
         tableColumns.set(coll.name, schema.columns.map((c) => c.name));
       } catch {}
@@ -83493,7 +85161,7 @@ async function collectMongoDoctorResults(config) {
   return results;
 }
 var doctorCommand = new Command("doctor").description("Run diagnostic checks on dbcli configuration, environment, and connection").option("--format <type>", "Output format: text, json", "text").action(async (options) => {
-  validateFormat(options.format, ALLOWED_FORMATS7, "doctor");
+  validateFormat(options.format, ALLOWED_FORMATS8, "doctor");
   const logger = getLogger();
   const results = [];
   const configPath = resolveConfigPath(doctorCommand);
@@ -83552,8 +85220,8 @@ var doctorCommand = new Command("doctor").description("Run diagnostic checks on
           try {
             const tables = await adapter.listTables();
             const tableColumns = new Map;
-            for (const t6 of tables) {
-              tableColumns.set(t6.name, t6.columns.map((c) => c.name));
+            for (const t2 of tables) {
+              tableColumns.set(t2.name, t2.columns.map((c) => c.name));
             }
             results.push(runDoctorChecks.checkBlacklistCompleteness(tableColumns, blacklistedColumns));
             results.push(runDoctorChecks.checkLargeTables(tables));
@@ -83562,7 +85230,7 @@ var doctorCommand = new Command("doctor").description("Run diagnostic checks on
           }
           try {
             const schemaConnName = await getSchemaIsolationConnectionName(configPath);
-            const indexPath = join11(resolveSchemaPath(storagePath, schemaConnName), "index.json");
+            const indexPath = join14(resolveSchemaPath(storagePath, schemaConnName), "index.json");
             const indexFile = Bun.file(indexPath);
             let indexParsed = null;
             if (await indexFile.exists()) {
@@ -83604,7 +85272,7 @@ var doctorCommand = new Command("doctor").description("Run diagnostic checks on
 });
 
 // src/commands/completion.ts
-import { join as join12 } from "path";
+import { join as join15 } from "path";
 import { homedir as homedir3 } from "os";
 function extractCommands(program2) {
   return program2.commands.map((cmd) => ({
@@ -83706,11 +85374,11 @@ function getInstallPath2(shell) {
   const home = homedir3();
   switch (shell) {
     case "bash":
-      return join12(home, ".bashrc");
+      return join15(home, ".bashrc");
     case "zsh":
-      return join12(home, ".zshrc");
+      return join15(home, ".zshrc");
     case "fish":
-      return join12(home, ".config", "fish", "completions", "dbcli.fish");
+      return join15(home, ".config", "fish", "completions", "dbcli.fish");
     default:
       throw new Error(`Unsupported shell: ${shell}. Supported: bash, zsh, fish`);
   }
@@ -83730,7 +85398,7 @@ var MARKER_END = "# <<< dbcli completion <<<";
 async function installCompletion(shell, script) {
   const targetPath = getInstallPath2(shell);
   if (shell === "fish") {
-    const dir = join12(homedir3(), ".config", "fish", "completions");
+    const dir = join15(homedir3(), ".config", "fish", "completions");
     await Bun.$`mkdir -p ${dir}`.quiet();
     await Bun.file(targetPath).write(script);
     console.log(colors.success(`\u2713 Fish completion installed to ${targetPath}`));
@@ -83957,7 +85625,7 @@ ${t("upgrade.failed")}`));
 
 // src/commands/shell.ts
 import { createInterface as createInterface2 } from "readline";
-import { join as join13 } from "path";
+import { join as join16 } from "path";
 import { homedir as homedir4 } from "os";
 
 // src/core/repl/types.ts
@@ -84083,7 +85751,6 @@ var META_COMMANDS = [
 var META_PREFIX = ".";
 var SQL_TERMINATOR = ";";
 var sqlKeywordSet = new Set(SQL_KEYWORDS_FOR_DETECTION);
-var dbcliCommandSet = new Set(DBCLI_COMMANDS);
 var metaCommandNames = META_COMMANDS.map((m) => m.slice(1));
 function classifyInput(raw) {
   const normalized = raw.trim();
@@ -84091,12 +85758,12 @@ function classifyInput(raw) {
     return { type: "empty", raw, normalized };
   }
   if (normalized.startsWith(META_PREFIX)) {
-    const cmdName = normalized.split(/\s+/)[0].slice(1);
+    const cmdName = (normalized.split(/\s+/)[0] ?? "").slice(1);
     if (metaCommandNames.includes(cmdName)) {
       return { type: "meta", raw, normalized };
     }
   }
-  const firstWord = normalized.split(/\s+/)[0].toUpperCase();
+  const firstWord = (normalized.split(/\s+/)[0] ?? "").toUpperCase();
   if (sqlKeywordSet.has(firstWord)) {
     return { type: "sql", raw, normalized };
   }
@@ -84303,7 +85970,7 @@ function isKnownCommand(name) {
 
 // src/core/repl/history-manager.ts
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
-import { dirname as dirname2 } from "path";
+import { dirname as dirname5 } from "path";
 var DEFAULT_MAX = 1000;
 
 class HistoryManager {
@@ -84331,7 +85998,7 @@ class HistoryManager {
     return this.entries;
   }
   async save() {
-    const dir = dirname2(this.filePath);
+    const dir = dirname5(this.filePath);
     if (!existsSync(dir)) {
       mkdirSync(dir, { recursive: true });
     }
@@ -84478,7 +86145,7 @@ class ReplEngine {
       const tableName = this.extractTableName(sql);
       if (tableName) {
         const blacklistedTables = this.config.blacklist.tables ?? [];
-        const isBlacklisted = blacklistedTables.some((t6) => t6.toLowerCase() === tableName.toLowerCase());
+        const isBlacklisted = blacklistedTables.some((t2) => t2.toLowerCase() === tableName.toLowerCase());
         if (isBlacklisted) {
           return {
             action: "continue",
@@ -84489,9 +86156,10 @@ class ReplEngine {
     }
     const startTime = Date.now();
     try {
-      const rows = await this.adapter.execute(sql);
+      const result = await this.adapter.execute(sql);
       const elapsed = Date.now() - startTime;
-      const columnNames = rows.length > 0 ? Object.keys(rows[0]) : [];
+      const rows = result.rows;
+      const columnNames = rows.length > 0 && rows[0] ? Object.keys(rows[0]) : [];
       const queryResult = {
         rows,
         rowCount: rows.length,
@@ -84535,8 +86203,9 @@ class ReplEngine {
     return match?.[1];
   }
   isConnectionError(error) {
-    const msg = (error.message ?? "").toLowerCase();
-    return error.code === "ECONNREFUSED" || error.code === "ECONNRESET" || error.code === "ETIMEDOUT" || msg.includes("connection") || msg.includes("terminated") || msg.includes("socket");
+    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");
   }
 }
 
@@ -84592,15 +86261,16 @@ function createCompleter(ctx) {
       return [[...cmdHits[0], ...sqlHits[0]], lastWord];
     }
     const cmdName = words[0];
-    if (COMMANDS_TAKING_TABLE_ARG.has(cmdName)) {
+    if (cmdName && COMMANDS_TAKING_TABLE_ARG.has(cmdName)) {
       return matchWithSuffix(allTableNames, lastWord);
     }
     return matchWithSuffix(allTableNames, lastWord);
   };
 }
 function completeMetaCommands(line) {
-  const hits = META_COMMANDS.filter((m) => m.startsWith(line.split(/\s+/)[0].toLowerCase())).map((m) => m + " ");
-  return [hits, line.split(/\s+/)[0]];
+  const first = line.split(/\s+/)[0] ?? "";
+  const hits = META_COMMANDS.filter((m) => m.startsWith(first.toLowerCase())).map((m) => m + " ");
+  return [hits, first];
 }
 function getLastWord(line) {
   const parts = line.split(/\s+/);
@@ -84615,7 +86285,7 @@ function getPreviousWord(line) {
   if (line.endsWith(" ") || line.endsWith("\t")) {
     return parts[parts.length - 1] || "";
   }
-  return parts.length >= 2 ? parts[parts.length - 2] : "";
+  return parts.length >= 2 ? parts[parts.length - 2] ?? "" : "";
 }
 function isColumnPosition(upperLine) {
   const columnKeywords = ["WHERE ", "AND ", "OR ", "ON ", "SET ", "SELECT "];
@@ -84625,9 +86295,9 @@ function extractTableFromLine(line, tableNames) {
   const upper = line.toUpperCase();
   const fromIdx = upper.lastIndexOf("FROM ");
   if (fromIdx >= 0) {
-    const afterFrom = line.slice(fromIdx + 5).trim().split(/\s+/)[0];
+    const afterFrom = line.slice(fromIdx + 5).trim().split(/\s+/)[0] ?? "";
     const candidate = afterFrom.replace(/[;,]/g, "").toLowerCase();
-    return tableNames.find((t6) => t6.toLowerCase() === candidate);
+    return tableNames.find((t2) => t2.toLowerCase() === candidate);
   }
   return;
 }
@@ -84652,7 +86322,7 @@ class MongoShellAdapter {
   async disconnect() {
     await this.adapter.disconnect();
   }
-  async execute() {
+  async execute(_sql, _params) {
     throw new Error("MongoDB shell does not support raw SQL. Use `query <json>` with `--collection`.");
   }
   async listTables() {
@@ -84677,7 +86347,7 @@ class MongoShellAdapter {
 }
 
 // src/commands/shell.ts
-var HISTORY_PATH = join13(homedir4(), ".dbcli_history");
+var HISTORY_PATH = join16(homedir4(), ".dbcli_history");
 var shellCommand = new Command("shell").description("Interactive database shell with auto-completion and syntax highlighting").option("--sql", "SQL-only mode (skip dbcli command parsing)").action(async (options, command) => {
   const configPath = resolveConfigPath(command);
   await runShell(options, configPath);
@@ -84870,25 +86540,25 @@ class PostgreSQLDDLGenerator {
   alterColumn(options) {
     const statements = [];
     const warnings = [];
-    const t6 = q(options.table);
+    const t2 = q(options.table);
     const c = q(options.column);
     if (options.type) {
-      statements.push(`ALTER TABLE ${t6} ALTER COLUMN ${c} TYPE ${options.type.toUpperCase()};`);
+      statements.push(`ALTER TABLE ${t2} ALTER COLUMN ${c} TYPE ${options.type.toUpperCase()};`);
     }
     if (options.rename) {
-      statements.push(`ALTER TABLE ${t6} RENAME COLUMN ${c} TO ${q(options.rename)};`);
+      statements.push(`ALTER TABLE ${t2} RENAME COLUMN ${c} TO ${q(options.rename)};`);
     }
     if (options.setDefault !== undefined) {
-      statements.push(`ALTER TABLE ${t6} ALTER COLUMN ${c} SET DEFAULT ${options.setDefault};`);
+      statements.push(`ALTER TABLE ${t2} ALTER COLUMN ${c} SET DEFAULT ${options.setDefault};`);
     }
     if (options.dropDefault) {
-      statements.push(`ALTER TABLE ${t6} ALTER COLUMN ${c} DROP DEFAULT;`);
+      statements.push(`ALTER TABLE ${t2} ALTER COLUMN ${c} DROP DEFAULT;`);
     }
     if (options.setNullable) {
-      statements.push(`ALTER TABLE ${t6} ALTER COLUMN ${c} DROP NOT NULL;`);
+      statements.push(`ALTER TABLE ${t2} ALTER COLUMN ${c} DROP NOT NULL;`);
     }
     if (options.dropNullable) {
-      statements.push(`ALTER TABLE ${t6} ALTER COLUMN ${c} SET NOT NULL;`);
+      statements.push(`ALTER TABLE ${t2} ALTER COLUMN ${c} SET NOT NULL;`);
     }
     if (statements.length === 0) {
       warnings.push("No alter operations specified");
@@ -84897,12 +86567,12 @@ class PostgreSQLDDLGenerator {
 `), warnings };
   }
   addIndex(index) {
-    const unique = index.unique ? "UNIQUE " : "";
+    const unique2 = index.unique ? "UNIQUE " : "";
     const name = index.name || `idx_${index.table}_${index.columns.join("_")}`;
     const using = index.type ? ` USING ${index.type.toUpperCase()}` : "";
     const cols = index.columns.map(q).join(", ");
     return {
-      sql: `CREATE ${unique}INDEX ${q(name)} ON ${q(index.table)}${using} (${cols});`,
+      sql: `CREATE ${unique2}INDEX ${q(name)} ON ${q(index.table)}${using} (${cols});`,
       warnings: []
     };
   }
@@ -84910,14 +86580,14 @@ class PostgreSQLDDLGenerator {
     return { sql: `DROP INDEX ${q(indexName)};`, warnings: [] };
   }
   addConstraint(constraint) {
-    const t6 = q(constraint.table);
+    const t2 = q(constraint.table);
     const warnings = [];
     switch (constraint.type) {
       case "foreign_key": {
         const name = constraint.name || `fk_${constraint.table}_${constraint.column}`;
         const onDelete = constraint.onDelete ? ` ON DELETE ${constraint.onDelete.toUpperCase().replace("_", " ")}` : "";
         return {
-          sql: `ALTER TABLE ${t6} ADD CONSTRAINT ${q(name)} FOREIGN KEY (${q(constraint.column)}) REFERENCES ${q(constraint.references.table)}(${q(constraint.references.column)})${onDelete};`,
+          sql: `ALTER TABLE ${t2} ADD CONSTRAINT ${q(name)} FOREIGN KEY (${q(constraint.column)}) REFERENCES ${q(constraint.references.table)}(${q(constraint.references.column)})${onDelete};`,
           warnings
         };
       }
@@ -84925,14 +86595,14 @@ class PostgreSQLDDLGenerator {
         const name = constraint.name || `uq_${constraint.table}_${constraint.columns.join("_")}`;
         const cols = constraint.columns.map(q).join(", ");
         return {
-          sql: `ALTER TABLE ${t6} ADD CONSTRAINT ${q(name)} UNIQUE (${cols});`,
+          sql: `ALTER TABLE ${t2} ADD CONSTRAINT ${q(name)} UNIQUE (${cols});`,
           warnings
         };
       }
       case "check": {
         const name = constraint.name || `ck_${constraint.table}`;
         return {
-          sql: `ALTER TABLE ${t6} ADD CONSTRAINT ${q(name)} CHECK (${constraint.expression});`,
+          sql: `ALTER TABLE ${t2} ADD CONSTRAINT ${q(name)} CHECK (${constraint.expression});`,
           warnings
         };
       }
@@ -85035,19 +86705,19 @@ class MySQLDDLGenerator {
   alterColumn(options) {
     const statements = [];
     const warnings = [];
-    const t6 = q2(options.table);
+    const t2 = q2(options.table);
     const c = q2(options.column);
     if (options.type) {
       const nullable = options.dropNullable ? " NOT NULL" : "";
       const def = options.setDefault !== undefined ? ` DEFAULT ${options.setDefault}` : "";
-      statements.push(`ALTER TABLE ${t6} MODIFY COLUMN ${c} ${options.type.toUpperCase()}${nullable}${def};`);
+      statements.push(`ALTER TABLE ${t2} MODIFY COLUMN ${c} ${options.type.toUpperCase()}${nullable}${def};`);
       warnings.push("MySQL MODIFY COLUMN resets column attributes not explicitly specified");
     } else {
       if (options.setDefault !== undefined) {
-        statements.push(`ALTER TABLE ${t6} ALTER COLUMN ${c} SET DEFAULT ${options.setDefault};`);
+        statements.push(`ALTER TABLE ${t2} ALTER COLUMN ${c} SET DEFAULT ${options.setDefault};`);
       }
       if (options.dropDefault) {
-        statements.push(`ALTER TABLE ${t6} ALTER COLUMN ${c} DROP DEFAULT;`);
+        statements.push(`ALTER TABLE ${t2} ALTER COLUMN ${c} DROP DEFAULT;`);
       }
       if (options.setNullable) {
         warnings.push("MySQL requires MODIFY COLUMN with full type to change nullability \u2014 use --type to specify");
@@ -85057,7 +86727,7 @@ class MySQLDDLGenerator {
       }
     }
     if (options.rename) {
-      statements.push(`ALTER TABLE ${t6} RENAME COLUMN ${c} TO ${q2(options.rename)};`);
+      statements.push(`ALTER TABLE ${t2} RENAME COLUMN ${c} TO ${q2(options.rename)};`);
     }
     if (statements.length === 0 && warnings.length === 0) {
       warnings.push("No alter operations specified");
@@ -85066,12 +86736,12 @@ class MySQLDDLGenerator {
 `), warnings };
   }
   addIndex(index) {
-    const unique = index.unique ? "UNIQUE " : "";
+    const unique2 = index.unique ? "UNIQUE " : "";
     const name = index.name || `idx_${index.table}_${index.columns.join("_")}`;
     const using = index.type ? ` USING ${index.type.toUpperCase()}` : "";
     const cols = index.columns.map(q2).join(", ");
     return {
-      sql: `CREATE ${unique}INDEX ${q2(name)} ON ${q2(index.table)} (${cols})${using};`,
+      sql: `CREATE ${unique2}INDEX ${q2(name)} ON ${q2(index.table)} (${cols})${using};`,
       warnings: []
     };
   }
@@ -85083,14 +86753,14 @@ class MySQLDDLGenerator {
     };
   }
   addConstraint(constraint) {
-    const t6 = q2(constraint.table);
+    const t2 = q2(constraint.table);
     const warnings = [];
     switch (constraint.type) {
       case "foreign_key": {
         const name = constraint.name || `fk_${constraint.table}_${constraint.column}`;
         const onDelete = constraint.onDelete ? ` ON DELETE ${constraint.onDelete.toUpperCase().replace("_", " ")}` : "";
         return {
-          sql: `ALTER TABLE ${t6} ADD CONSTRAINT ${q2(name)} FOREIGN KEY (${q2(constraint.column)}) REFERENCES ${q2(constraint.references.table)}(${q2(constraint.references.column)})${onDelete};`,
+          sql: `ALTER TABLE ${t2} ADD CONSTRAINT ${q2(name)} FOREIGN KEY (${q2(constraint.column)}) REFERENCES ${q2(constraint.references.table)}(${q2(constraint.references.column)})${onDelete};`,
           warnings
         };
       }
@@ -85098,14 +86768,14 @@ class MySQLDDLGenerator {
         const name = constraint.name || `uq_${constraint.table}_${constraint.columns.join("_")}`;
         const cols = constraint.columns.map(q2).join(", ");
         return {
-          sql: `ALTER TABLE ${t6} ADD CONSTRAINT ${q2(name)} UNIQUE (${cols});`,
+          sql: `ALTER TABLE ${t2} ADD CONSTRAINT ${q2(name)} UNIQUE (${cols});`,
           warnings
         };
       }
       case "check": {
         const name = constraint.name || `ck_${constraint.table}`;
         return {
-          sql: `ALTER TABLE ${t6} ADD CONSTRAINT ${q2(name)} CHECK (${constraint.expression});`,
+          sql: `ALTER TABLE ${t2} ADD CONSTRAINT ${q2(name)} CHECK (${constraint.expression});`,
           warnings: ["CHECK constraints enforced in MySQL 8.0.16+ and MariaDB 10.2.1+ only"]
         };
       }
@@ -85618,7 +87288,7 @@ addExecOpts(migrateCommand.command("drop-enum <name>").description(t("migrate.dr
 });
 
 // src/commands/use.ts
-import { join as join14 } from "path";
+import { join as join17 } from "path";
 async function switchDefault(configPath, name, config) {
   if (!config.connections[name]) {
     const available = Object.keys(config.connections).join(", ");
@@ -85641,7 +87311,7 @@ function listConnectionsForDisplay(config) {
 }
 async function ensureV2Config(configPath) {
   const storagePath = await resolveConfigStoragePath(configPath);
-  const configFile = Bun.file(join14(storagePath, "config.json"));
+  const configFile = Bun.file(join17(storagePath, "config.json"));
   const legacyFile = Bun.file(configPath);
   if (!await configFile.exists() && !await legacyFile.exists()) {
     throw new ConfigError(t("init.config_not_found"));
@@ -85703,8 +87373,11 @@ var useCommand = new Command("use").description("Switch or display the default d
 });
 
 // src/cli.ts
-import { join as join15 } from "path";
+import { join as join18 } from "path";
 var _bgVersionCheckResult;
+function shouldSkipBackgroundChecks() {
+  return process.env.DBCLI_NO_UPDATE_CHECK === "1" || process.env.DBCLI_NO_UPDATE_CHECK === "true" || false;
+}
 var program2 = new Command().name("dbcli").description("Database CLI for AI agents").version(package_default.version).option("--no-color", "Disable colored output").option("-v, --verbose", "Increase verbosity (-v verbose, -vv debug)", (_, prev) => prev + 1, 0).option("-q, --quiet", "Suppress non-essential output").option("--config <path>", "Path to .dbcli config file", ".dbcli").option("--use <connection>", "Use a specific named connection (v2 config)");
 program2.hook("preAction", (thisCommand, actionCommand) => {
   const opts = thisCommand.opts();
@@ -85723,13 +87396,13 @@ program2.hook("preAction", (thisCommand, actionCommand) => {
   }
   setGlobalLogger(createLogger(level));
   const isUpgradeCommand = actionCommand.name() === "upgrade";
-  if (!opts.quiet && !isUpgradeCommand) {
+  if (!opts.quiet && !isUpgradeCommand && !shouldSkipBackgroundChecks()) {
     const configPath = resolveConfigPath(actionCommand);
     (async () => {
       try {
         let cache = null;
         try {
-          const cacheFile = Bun.file(join15(configPath, "version-check.json"));
+          const cacheFile = Bun.file(join18(configPath, "version-check.json"));
           if (await cacheFile.exists()) {
             cache = await cacheFile.json();
           }
@@ -85748,7 +87421,7 @@ program2.hook("postAction", async (thisCommand, actionCommand) => {
 `);
   }
   const isUpgradeOrSkill = ["upgrade", "skill"].includes(actionCommand.name());
-  if (!thisCommand.opts().quiet && !isUpgradeOrSkill) {
+  if (!thisCommand.opts().quiet && !isUpgradeOrSkill && !shouldSkipBackgroundChecks()) {
     const outdatedSkills = await checkSkillUpdates();
     if (outdatedSkills.length > 0) {
       process.stderr.write(formatSkillUpdateReminder(outdatedSkills) + `
@@ -85767,6 +87440,12 @@ program2.command("query <sql>").description(t("query.description")).option("--fo
     process.exit(1);
   }
 });
+program2.command("plan <sql>").description("Analyze SQL risk without executing").option("--format <type>", "Output format: text, json", "text").action(async (sql, options, command) => {
+  await planCommand(sql, options, command);
+});
+program2.command("q <name>").description(t("q.description")).option("--format <type>", "Output format: table, json, csv", "table").option("--no-limit", "Disable size guard wrap (LIMIT 1000)").option("--dry-run", "Show final SQL + bind values; do not execute").option("--param <kv>", "Pass parameter as key=value (repeatable)", (val, prev = []) => prev.concat([val]), []).option("--param-file <path>", "JSON file containing param values").action(async (name, options, command) => {
+  await qCommand(name, options, command);
+});
 program2.command("insert <table>").description(t("insert.description")).option("--data <json>", "JSON object to insert").option("--dry-run", "Show generated SQL without executing").option("--force", "Skip confirmation prompt").action(async (table, options, command) => {
   try {
     await insertCommand(table, options, command);
@@ -85819,6 +87498,7 @@ program2.addCommand(upgradeCommand);
 program2.addCommand(shellCommand);
 program2.addCommand(migrateCommand);
 program2.addCommand(useCommand);
+program2.addCommand(queriesCommand);
 if (!process.argv.slice(2).length) {
   program2.outputHelp();
 }