botversion-sdk 2.2.3 → 2.3.0

package/undo/lib/capture-mysql.js

@@ -0,0 +1,909 @@
+// lib/capture-mysql.js
+"use strict";
+// MYSQL CAPTURE (Phase 5): saves before/after rows of tagged UPDATE, INSERT and DELETE statements on the host's own connection.
+// DELETE also saves the rows the database removes or changes through foreign keys.
+// Never throws into the host. Logs: table names, counts and reasons only.
+
+const EventEmitter = require("events");
+const log = require("./log");
+const tagger = require("./tagger");
+const store = require("./snapshot-store");
+const guard = require("./capture-guard");
+const gate = require("./gate");
+const { classifyMysql } = require("./sql-classify-mysql");
+const DIALECT = "mysql";
+const OPTS = { database: "MySQL" };
+
+// Statements that start with one of these words are writes, even when the parser cannot read them.
+const WRITE_WORDS = new Set([
+  "INSERT",
+  "UPDATE",
+  "DELETE",
+  "REPLACE",
+  "TRUNCATE",
+  "DROP",
+  "ALTER",
+  "CALL",
+  "LOAD",
+  "RENAME",
+]);
+
+let parser = null;
+try {
+  const { Parser } = require("node-sql-parser");
+  parser = new Parser();
+} catch (_) {
+  /* parser missing: nothing is capturable */
+}
+
+class Skip extends Error {}
+
+const txState = new WeakMap(); // connection -> is the host inside a transaction?
+const pkCache = new Map();
+let template = null;
+
+const q = (s) => "`" + String(s).replace(/`/g, "``") + "`";
+const tableSql = (t) => (t.db ? q(t.db) + "." : "") + q(t.table);
+const labelOf = (t) => (t.db ? t.db + "." : "") + t.table;
+const keyOf = (row, cols) =>
+  cols
+    .map((c) => {
+      const v = row[c];
+      return v instanceof Date ? v.toISOString() : String(v);
+    })
+    .join("\u0001");
+const pickPk = (row, cols) => {
+  const o = {};
+  for (const c of cols) o[c] = row[c];
+  return o;
+};
+
+// Primary key columns of a table, and whether it is a single AUTO_INCREMENT column.
+const PK_SQL =
+  "SELECT k.COLUMN_NAME AS name, c.EXTRA AS extra FROM information_schema.KEY_COLUMN_USAGE k " +
+  "JOIN information_schema.COLUMNS c ON c.TABLE_SCHEMA = k.TABLE_SCHEMA AND c.TABLE_NAME = k.TABLE_NAME AND c.COLUMN_NAME = k.COLUMN_NAME " +
+  "WHERE k.TABLE_SCHEMA = COALESCE(?, DATABASE()) AND k.TABLE_NAME = ? AND k.CONSTRAINT_NAME = 'PRIMARY' ORDER BY k.ORDINAL_POSITION";
+
+// Remembers whether the host's own statements opened a transaction on this connection.
+function trackTransaction(client, text) {
+  if (/^\s*ROLLBACK(\s+WORK)?\s+TO\b/i.test(text)) return;
+  const m = /^\s*([A-Za-z]+)/.exec(text);
+  const w = m ? m[1].toUpperCase() : "";
+  if (w === "BEGIN" || w === "START") txState.set(client, true);
+  else if (w === "COMMIT" || w === "ROLLBACK") txState.set(client, false);
+}
+
+function parseOne(sql) {
+  if (!parser) return null;
+  try {
+    const a = parser.astify(sql, OPTS);
+    const list = Array.isArray(a) ? a : [a];
+    return list.length === 1 ? list[0] : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// A SELECT built from a parsed template, so the shape always matches the installed parser version.
+function selectTemplate() {
+  if (template) return template;
+  const a = parseOne(
+    "SELECT * FROM `botversion_t` LIMIT " + (store.ROW_LIMIT + 1),
+  );
+  if (!a || a.type !== "select") return null;
+  template = a;
+  return a;
+}
+
+function tableRef(stmt) {
+  // An UPDATE keeps its table in `table`; a DELETE keeps it in `from`.
+  const src = stmt.type === "delete" ? stmt.from : stmt.table;
+  const t = Array.isArray(src) ? src : src ? [src] : [];
+  if (t.length !== 1 || !t[0] || typeof t[0].table !== "string")
+    throw new Skip("this statement shape cannot be saved");
+  // The parser copies the FROM table into `table` (tagged addition); only a different entry means a multi-table delete.
+  if (
+    stmt.type === "delete" &&
+    Array.isArray(stmt.table) &&
+    stmt.table.some(
+      (x) =>
+        !(x && x.addition === true && t.some((f) => f && f.table === x.table)),
+    )
+  )
+    throw new Skip("multi-table delete cannot be saved");
+  return { db: t[0].db || null, table: t[0].table, as: t[0].as || null };
+}
+
+// SQL that reads the rows an UPDATE will touch (same WHERE / ORDER BY / LIMIT). Reading too many rows is safe, too few is not.
+function readSql(stmt, ref) {
+  const t = selectTemplate();
+  if (!t) throw new Skip("statement reader not available");
+  const sel = JSON.parse(JSON.stringify(t));
+  sel.from = [{ db: ref.db, table: ref.table, as: ref.as }];
+  sel.where = stmt.where || null;
+  if (stmt.orderby) sel.orderby = stmt.orderby;
+  if (stmt.limit) {
+    const v = stmt.limit.value;
+    if (
+      !Array.isArray(v) ||
+      v.length !== 1 ||
+      typeof v[0].value !== "number" ||
+      v[0].value > store.ROW_LIMIT
+    )
+      throw new Skip("too-many-rows");
+    sel.limit.value[0].value = v[0].value;
+  }
+  return parser.sqlify(sel, OPTS);
+}
+
+async function primaryKeyOf(client, run, ref, inTx) {
+  const key =
+    ((client.config && client.config.database) || "") +
+    "|" +
+    (ref.db || "") +
+    "|" +
+    ref.table;
+  if (pkCache.has(key)) return pkCache.get(key);
+  const res = await store.guarded(run, inTx, () =>
+    run(PK_SQL, [ref.db, ref.table]),
+  );
+  const cols = res.rows.map((r) => r.name);
+  const auto =
+    cols.length === 1 &&
+    /auto_increment/i.test(String(res.rows[0].extra || ""));
+  const info = { cols, auto };
+  if (cols.length) pkCache.set(key, info);
+  return info;
+}
+
+async function readByPk(run, ref, pk, pkObjs, inTx) {
+  if (!pkObjs.length) return [];
+  const params = [];
+  const tuples = pkObjs.map(
+    (o) =>
+      "(" +
+      pk
+        .map((c) => {
+          params.push(o[c]);
+          return "?";
+        })
+        .join(", ") +
+      ")",
+  );
+  const sql = `SELECT * FROM ${tableSql(ref)} WHERE (${pk.map(q).join(", ")}) IN (${tuples.join(", ")})`;
+  return (await store.guarded(run, inTx, () => run(sql, params))).rows;
+}
+
+async function beforeUpdate(run, stmt, ref, pk, st, inTx, notSaved) {
+  let c = store.checkCapturable({ rowCount: 0, primaryKeyColumns: pk.cols });
+  if (!c.ok) {
+    notSaved(c.reason);
+    return null;
+  }
+  const sql = readSql(stmt, ref);
+  const rows = (await store.guarded(run, inTx, () => run(sql, []))).rows;
+  c = store.checkCapturable({
+    rowCount: rows.length,
+    primaryKeyColumns: pk.cols,
+  });
+  if (!c.ok) {
+    notSaved(c.reason);
+    return null;
+  }
+  const saved = [];
+  for (const row of rows) {
+    const r = await store.saveSnapshot(
+      run,
+      st,
+      {
+        table: labelOf(ref),
+        operation: "update",
+        primaryKey: pickPk(row, pk.cols),
+        before: row,
+        after: null,
+        isLinked: false,
+      },
+      { inTransaction: inTx, dialect: DIALECT },
+    );
+    if (!r.ok) {
+      notSaved(r.reason);
+      break;
+    }
+    saved.push({
+      id: r.id,
+      key: keyOf(row, pk.cols),
+      pkObj: pickPk(row, pk.cols),
+    });
+  }
+  return { saved };
+}
+
+async function afterUpdate(run, ref, pk, before, st, inTx) {
+  const rows = await readByPk(
+    run,
+    ref,
+    pk.cols,
+    before.saved.map((s) => s.pkObj),
+    inTx,
+  );
+  const byKey = new Map(before.saved.map((s) => [s.key, s]));
+  let n = 0;
+  for (const row of rows) {
+    const s = byKey.get(keyOf(row, pk.cols));
+    if (!s) continue;
+    const r = await store.saveAfter(run, s.id, row, {
+      inTransaction: inTx,
+      dialect: DIALECT,
+    });
+    if (r.ok) n++;
+  }
+}
+
+// ---- DELETE: the rows the host deletes, plus rows the database removes or changes through foreign keys ----
+
+const MAX_DEPTH = 5; // how many levels of linked rows a delete may reach
+
+// Foreign keys that point AT a table. rule: CASCADE / SET NULL / SET DEFAULT = the database changes the child rows; RESTRICT / NO ACTION = the database refuses the delete.
+const FK_SQL =
+  "SELECT k.TABLE_SCHEMA AS child_schema, k.TABLE_NAME AS child_table, k.CONSTRAINT_NAME AS cname, r.DELETE_RULE AS delete_rule, " +
+  "k.COLUMN_NAME AS child_col, k.REFERENCED_COLUMN_NAME AS parent_col " +
+  "FROM information_schema.KEY_COLUMN_USAGE k " +
+  "JOIN information_schema.REFERENTIAL_CONSTRAINTS r ON r.CONSTRAINT_SCHEMA = k.CONSTRAINT_SCHEMA AND r.CONSTRAINT_NAME = k.CONSTRAINT_NAME AND r.TABLE_NAME = k.TABLE_NAME " +
+  "WHERE k.REFERENCED_TABLE_SCHEMA = ? AND k.REFERENCED_TABLE_NAME = ? " +
+  "ORDER BY k.TABLE_SCHEMA, k.TABLE_NAME, k.CONSTRAINT_NAME, k.ORDINAL_POSITION";
+
+// One entry per foreign key (a key can use several columns).
+async function readLinks(run, schema, table, inTx) {
+  const rows = (
+    await store.guarded(run, inTx, () => run(FK_SQL, [schema, table]))
+  ).rows;
+  const byName = new Map();
+  for (const r of rows) {
+    const k = r.child_schema + "\u0002" + r.child_table + "\u0002" + r.cname;
+    if (!byName.has(k))
+      byName.set(k, {
+        childSchema: r.child_schema,
+        childTable: r.child_table,
+        rule: String(r.delete_rule || "").toUpperCase(),
+        childCols: [],
+        parentCols: [],
+      });
+    const l = byName.get(k);
+    l.childCols.push(r.child_col);
+    l.parentCols.push(r.parent_col);
+  }
+  return [...byName.values()];
+}
+
+// Rows of a child table whose link columns match the given parent rows.
+async function readByCols(run, table, childCols, parentCols, parentRows, inTx) {
+  const params = [];
+  const tuples = parentRows.map(
+    (r) =>
+      "(" +
+      parentCols
+        .map((c) => {
+          params.push(r[c]);
+          return "?";
+        })
+        .join(", ") +
+      ")",
+  );
+  const sql = `SELECT * FROM ${tableSql(table)} WHERE (${childCols.map(q).join(", ")}) IN (${tuples.join(", ")}) LIMIT ${store.ROW_LIMIT + 1}`;
+  return (await store.guarded(run, inTx, () => run(sql, params))).rows;
+}
+
+const tagOf = (schema, table, row, pk) =>
+  schema + "." + table + "\u0002" + keyOf(row, pk);
+
+// Works out every row a DELETE will remove or change (through foreign keys). Saves nothing. Throws Skip when unsafe.
+async function planDelete(client, run, stmt, ref, rootPk, inTx) {
+  const cur = await store.guarded(run, inTx, () =>
+    run("SELECT COALESCE(?, DATABASE()) AS s", [ref.db]),
+  );
+  const rootSchema = cur.rows[0] && cur.rows[0].s;
+  if (!rootSchema) throw new Skip("no database selected");
+  let c = store.checkCapturable({
+    rowCount: 0,
+    primaryKeyColumns: rootPk.cols,
+  });
+  if (!c.ok) throw new Skip(c.reason);
+
+  // 1. The rows the host is deleting.
+  const sql = readSql(stmt, ref);
+  const rootRows = (await store.guarded(run, inTx, () => run(sql, []))).rows;
+  c = store.checkCapturable({
+    rowCount: rootRows.length,
+    primaryKeyColumns: rootPk.cols,
+  });
+  if (!c.ok) throw new Skip(c.reason);
+
+  // 2. Rows reached through foreign keys, level by level.
+  //    kind "delete" = removed by the database (CASCADE); kind "update" = link cleared (SET NULL / SET DEFAULT).
+  const groups = [
+    {
+      table: { db: ref.db, table: ref.table },
+      schema: rootSchema,
+      pk: rootPk.cols,
+      rows: rootRows,
+      depth: 0,
+      kind: "delete",
+    },
+  ];
+  const deletedAt = new Map(); // row -> level it is deleted at
+  const cleared = new Set();
+  for (const r of rootRows)
+    deletedAt.set(tagOf(rootSchema, ref.table, r, rootPk.cols), 0);
+  let frontier = rootRows.length ? [groups[0]] : [];
+  let total = rootRows.length;
+  for (let depth = 1; frontier.length; depth++) {
+    const next = [];
+    for (const parent of frontier) {
+      const links = await readLinks(
+        run,
+        parent.schema,
+        parent.table.table,
+        inTx,
+      );
+      for (const link of links) {
+        const cascades = link.rule === "CASCADE";
+        if (
+          !cascades &&
+          link.rule !== "SET NULL" &&
+          link.rule !== "SET DEFAULT"
+        )
+          continue; // RESTRICT / NO ACTION: the database refuses the delete itself
+        // A child in the same database as the host's table keeps the same naming as the host's statement.
+        const childRef = {
+          db:
+            link.childSchema === rootSchema && !ref.db
+              ? null
+              : link.childSchema,
+          table: link.childTable,
+        };
+        const found = await readByCols(
+          run,
+          childRef,
+          link.childCols,
+          link.parentCols,
+          parent.rows,
+          inTx,
+        );
+        if (!found.length) continue;
+        if (depth > MAX_DEPTH) throw new Skip("links go too deep");
+        const childPk = await primaryKeyOf(client, run, childRef, inTx);
+        const cc = store.checkCapturable({
+          rowCount: found.length,
+          primaryKeyColumns: childPk.cols,
+        });
+        if (!cc.ok) throw new Skip(cc.reason);
+        const fresh = [];
+        for (const r of found) {
+          const k = tagOf(link.childSchema, link.childTable, r, childPk.cols);
+          if (cascades) {
+            if (deletedAt.has(k)) {
+              // Same row reached at another level would be restored in the wrong order: do not guess.
+              if (deletedAt.get(k) !== depth)
+                throw new Skip(
+                  "a row is reached through links of different depth",
+                );
+              continue;
+            }
+            deletedAt.set(k, depth);
+          } else {
+            if (cleared.has(k)) continue;
+            cleared.add(k);
+          }
+          fresh.push(r);
+        }
+        total += fresh.length;
+        if (total > store.ROW_LIMIT) throw new Skip("too-many-rows");
+        if (!fresh.length) continue;
+        const grp = {
+          table: childRef,
+          schema: link.childSchema,
+          pk: childPk.cols,
+          rows: fresh,
+          depth,
+          kind: cascades ? "delete" : "update",
+        };
+        groups.push(grp);
+        if (cascades) next.push(grp);
+      }
+    }
+    frontier = next;
+  }
+  // A row that is deleted does not also need its link cleared.
+  for (const g of groups) {
+    if (g.kind === "update")
+      g.rows = g.rows.filter(
+        (r) => !deletedAt.has(tagOf(g.schema, g.table.table, r, g.pk)),
+      );
+  }
+  return groups.filter((g) => g.rows.length);
+}
+
+// Saves the rows a DELETE will remove or change. Deepest rows first, deleted rows last (Undo goes last to first).
+async function beforeDelete(client, run, stmt, ref, pk, st, inTx, notSaved) {
+  let groups;
+  try {
+    groups = await planDelete(client, run, stmt, ref, pk, inTx);
+  } catch (e) {
+    if (e instanceof Skip) {
+      notSaved(e.message);
+      return null;
+    }
+    throw e;
+  }
+  const ordered = groups.slice().sort((a, b) => b.depth - a.depth);
+  const saved = [];
+  const fills = [];
+  for (const g of ordered) {
+    const ids = new Map();
+    for (const row of g.rows) {
+      const r = await store.saveSnapshot(
+        run,
+        st,
+        {
+          table: labelOf(g.table),
+          operation: g.kind,
+          primaryKey: pickPk(row, g.pk),
+          before: row,
+          after: null,
+          isLinked: g.depth > 0,
+        },
+        { inTransaction: inTx, dialect: DIALECT },
+      );
+      if (!r.ok) {
+        // Do not keep a half-saved set: it could restore only part of the data.
+        await deleteSaved(
+          run,
+          inTx,
+          saved.map((s) => s.id),
+        );
+        notSaved(r.reason);
+        return null;
+      }
+      saved.push({ id: r.id });
+      ids.set(keyOf(row, g.pk), r.id);
+    }
+    if (g.kind === "update") fills.push({ g, ids });
+  }
+  return { saved, fills };
+}
+
+// Rows whose link was cleared: save how they look now (needed for the safety check in Undo).
+async function afterDelete(run, before, st, inTx, name) {
+  for (const { g, ids } of before.fills) {
+    const rows = await readByPk(
+      run,
+      g.table,
+      g.pk,
+      g.rows.map((r) => pickPk(r, g.pk)),
+      inTx,
+    );
+    for (const row of rows) {
+      const id = ids.get(keyOf(row, g.pk));
+      if (!id) continue;
+      await store.saveAfter(run, id, row, {
+        inTransaction: inTx,
+        dialect: DIALECT,
+      });
+    }
+  }
+}
+
+function colName(c) {
+  if (typeof c === "string") return c;
+  if (c && typeof c.column === "string") return c.column;
+  if (c && c.column && c.column.expr && typeof c.column.expr.value === "string")
+    return c.column.expr.value;
+  return null;
+}
+
+// Only plain numbers and plain strings are accepted as a key written in the statement itself.
+function literalOf(e, auto) {
+  if (
+    e &&
+    e.type === "number" &&
+    typeof e.value === "number" &&
+    Number.isSafeInteger(e.value) &&
+    !(auto && e.value === 0)
+  )
+    return e.value;
+  if (
+    e &&
+    typeof e.type === "string" &&
+    /string/.test(e.type) &&
+    typeof e.value === "string" &&
+    !e.value.includes("\\")
+  )
+    return e.value;
+  throw new Skip("the new row key is not a plain value in the statement");
+}
+
+// Decides BEFORE the insert runs whether its new row can be found again afterwards. Throws Skip when not.
+function planInsert(stmt, pk) {
+  if (!pk.cols.length) throw new Skip("no-primary-key");
+  const cols = Array.isArray(stmt.columns) ? stmt.columns.map(colName) : null;
+  if (!cols || !cols.length || cols.some((c) => !c))
+    throw new Skip("insert without a column list cannot be saved");
+  const v = stmt.values;
+  const rows = Array.isArray(v)
+    ? v
+    : v && Array.isArray(v.values)
+      ? v.values
+      : null;
+  if (!rows || rows.length !== 1)
+    throw new Skip("only single-row inserts can be saved");
+  const exprs = rows[0] && Array.isArray(rows[0].value) ? rows[0].value : null;
+  if (!exprs || exprs.length !== cols.length)
+    throw new Skip("this insert shape cannot be saved");
+  const lower = cols.map((c) => c.toLowerCase());
+  const idx = pk.cols.map((c) => lower.indexOf(c.toLowerCase()));
+  if (idx.every((i) => i === -1)) {
+    if (pk.auto) return { mode: "auto" };
+    throw new Skip(
+      "new row key is not an auto-increment column and not in the insert",
+    );
+  }
+  if (idx.some((i) => i === -1))
+    throw new Skip("part of the primary key is not in the insert");
+  const key = {};
+  pk.cols.forEach((c, n) => {
+    key[c] = literalOf(exprs[idx[n]], pk.auto);
+  });
+  return { mode: "explicit", key };
+}
+
+async function afterInsert(run, ref, pk, plan, header, st, inTx, notSaved) {
+  if (!header || header.affectedRows === 0) {
+    return;
+  }
+  if (header.affectedRows !== 1) return notSaved("unexpected row count");
+  let keyObj = plan.key;
+  if (plan.mode === "auto") {
+    if (!header.insertId)
+      return notSaved("new row id not returned by the database");
+    keyObj = { [pk.cols[0]]: header.insertId };
+  }
+  const full = await readByPk(run, ref, pk.cols, [keyObj], inTx);
+  if (!full.length) return notSaved("new row could not be read back");
+  const r = await store.saveSnapshot(
+    run,
+    st,
+    {
+      table: labelOf(ref),
+      operation: "insert",
+      primaryKey: pickPk(full[0], pk.cols),
+      before: null,
+      after: full[0],
+      isLinked: false,
+    },
+    { inTransaction: inTx, dialect: DIALECT },
+  );
+  if (!r.ok) return notSaved(r.reason);
+}
+
+async function deleteSaved(run, inTx, ids) {
+  if (!ids.length) return;
+  try {
+    const d = store.deleteByIds(ids, DIALECT);
+    await store.guarded(run, inTx, () => run(d.sql, d.params));
+  } catch (_) {
+    /* ignore */
+  }
+}
+
+// The whole job for one tagged UPDATE / INSERT. execHost() runs the host's own statement and gives back its answer.
+async function runCapture(client, run, stmt, ref, kind, st, execHost) {
+  const inTx = txState.get(client) === true;
+  const name = labelOf(ref);
+  let phase = "before"; // "before" = the write has not run yet, so it can still be blocked
+  let failedWhy = null;
+  const notSaved = (why) => {
+    log.debug(
+      "mysql notSaved:",
+      "table=" + name,
+      "phase=" + phase,
+      "reason=" + why,
+      "confirmed=" + st.confirmed,
+    );
+    if (phase === "before") failedWhy = failedWhy || why;
+    if (phase !== "before" || st.confirmed) st.unsaved = true; // the write runs (or already ran) without a saved snapshot
+  };
+
+  let pk = null;
+  let before = null;
+  let plan = null;
+  try {
+    pk = await primaryKeyOf(client, run, ref, inTx);
+    if (kind === "update")
+      before = await beforeUpdate(run, stmt, ref, pk, st, inTx, notSaved);
+    else if (kind === "delete")
+      before = await beforeDelete(
+        client,
+        run,
+        stmt,
+        ref,
+        pk,
+        st,
+        inTx,
+        notSaved,
+      );
+    else {
+      const c = store.checkCapturable({
+        rowCount: 0,
+        primaryKeyColumns: pk.cols,
+      });
+      if (!c.ok) notSaved(c.reason);
+      else plan = planInsert(stmt, pk);
+    }
+  } catch (e) {
+    // TEMP DEBUG: real cause behind "capture error"
+    log.debug(
+      "mysql capture threw:",
+      "table=" + name,
+      "kind=" + kind,
+      "code=" + ((e && e.code) || "none"),
+      "name=" + (e && e.name),
+      !(e && e.code)
+        ? "msg=" + String((e && e.message) || "").slice(0, 150)
+        : "",
+    );
+    notSaved(
+      e instanceof Skip
+        ? e.message
+        : "capture error " + ((e && e.code) || "unknown"),
+    );
+  }
+
+  // Cannot be saved: remove what was saved so far (a half-saved set could restore only part of the data), then block unless confirmed.
+  if (failedWhy) {
+    await deleteSaved(
+      run,
+      inTx,
+      before && before.saved ? before.saved.map((s) => s.id) : [],
+    );
+    if (!st.confirmed) await gate.block(st, name, failedWhy);
+  }
+
+  phase = "after";
+  const r = await execHost();
+  if (r.err) {
+    // The host's write failed: remove the snapshots saved for it (inside a transaction they roll back by themselves).
+    if (!inTx && before && before.saved && before.saved.length)
+      await deleteSaved(
+        run,
+        inTx,
+        before.saved.map((s) => s.id),
+      );
+    return r;
+  }
+  try {
+    if (kind === "update" && before && before.saved.length)
+      await afterUpdate(run, ref, pk, before, st, inTx);
+    if (kind === "delete" && before && before.saved.length)
+      await afterDelete(run, before, st, inTx, name);
+    if (kind === "insert" && plan)
+      await afterInsert(run, ref, pk, plan, r.res, st, inTx, notSaved);
+  } catch (e) {
+    notSaved("capture error " + ((e && e.code) || "unknown"));
+  }
+  return r;
+}
+
+// Reads the way mysql2 was called: (sql, cb) / (sql, values, cb) / (options, cb) / mysql2's own query object (used by pools).
+function readCall(args) {
+  const first = args[0];
+  if (
+    first &&
+    typeof first === "object" &&
+    typeof first.once === "function" &&
+    typeof first.sql === "string"
+  ) {
+    return {
+      text: first.sql,
+      values: first.values,
+      cb: typeof first.onResult === "function" ? first.onResult : null,
+      cbIndex: -1,
+      cmd: first,
+    };
+  }
+  let text;
+  let values;
+  if (typeof first === "string") text = first;
+  else if (first && typeof first.sql === "string") {
+    text = first.sql;
+    values = first.values;
+  } else return null;
+  let cb = null;
+  let cbIndex = -1;
+  if (typeof args[1] === "function") {
+    cb = args[1];
+    cbIndex = 1;
+  } else {
+    if (args[1] !== undefined) values = args[1];
+    if (typeof args[2] === "function") {
+      cb = args[2];
+      cbIndex = 2;
+    }
+  }
+  return { text, values, cb, cbIndex, cmd: null };
+}
+
+// Puts the values into the SQL the way mysql2 itself does, so the parser sees no "?" placeholders.
+function formatSql(client, call) {
+  if (call.values === undefined) return call.text;
+  if (!Array.isArray(call.values))
+    throw new Skip("named placeholders cannot be saved");
+  if (typeof client.format !== "function")
+    throw new Skip("statement values cannot be read");
+  return client.format(call.text, call.values);
+}
+
+// Runs `job` instead of the host's call. Hands the host its own answer (or the block error) the way mysql2 would.
+function takeOver(client, args, original, call, job) {
+  const hostCb = call.cb;
+  const out = call.cmd || new EventEmitter();
+  let patched = null;
+
+  const execHost = () =>
+    new Promise((resolve) => {
+      const done = (err, res, fields) => resolve({ err, res, fields });
+      try {
+        if (call.cmd) {
+          // Hold back mysql2's "end" event: a pool frees the connection on it, and we still need the connection.
+          const had = Object.prototype.hasOwnProperty.call(call.cmd, "emit");
+          const realEmit = call.cmd.emit;
+          call.cmd.emit = function (ev) {
+            if (ev === "end") return true;
+            return realEmit.apply(this, arguments);
+          };
+          patched = () => {
+            if (had) call.cmd.emit = realEmit;
+            else delete call.cmd.emit;
+          };
+          call.cmd.onResult = done;
+          original.call(client, call.cmd);
+        } else {
+          const a = Array.prototype.slice.call(args);
+          a[call.cbIndex] = done;
+          original.apply(client, a);
+        }
+      } catch (e) {
+        resolve({ err: e });
+      }
+    });
+
+  const settle = (err, res, fields) => {
+    if (typeof hostCb === "function")
+      process.nextTick(hostCb, err, res, fields);
+    else if (err && out.listenerCount && out.listenerCount("error"))
+      process.nextTick(() => out.emit("error", err));
+    process.nextTick(() => {
+      try {
+        if (patched) patched();
+        out.emit("end");
+      } catch (_) {
+        /* never break the host */
+      }
+    });
+  };
+
+  Promise.resolve()
+    .then(() => job(execHost))
+    .then(
+      (r) => settle(r.err, r.res, r.fields),
+      (e) => settle(e),
+    );
+  return out;
+}
+
+// Returns { value } when capture took over (it runs the host's statement itself, or blocks it), otherwise null.
+// original = the method the host called (query or execute); queryOriginal = mysql2's real query, used for our own reads and saves.
+function maybeCapture(client, args, original, queryOriginal) {
+  const st = tagger.getCurrent();
+  if (!st || guard.isUnhooked() || !parser) return null;
+  const call = readCall(args);
+  if (!call) return null;
+  trackTransaction(client, call.text);
+
+  // A write that cannot be saved: blocked until the user confirms (or runs unsaved if they already did).
+  const refuse = (table, why) => {
+    log.debug(
+      "mysql refuse (statement shape):",
+      "table=" + table,
+      "reason=" + why,
+      "confirmed=" + st.confirmed,
+    );
+    if (st.confirmed) {
+      st.unsaved = true; // runs without a saved snapshot, so Undo will not cover it
+      return null;
+    }
+    return {
+      value: takeOver(client, args, original, call, async () => {
+        await gate.block(st, table, why);
+      }),
+    };
+  };
+
+  let formatted;
+  try {
+    formatted = formatSql(client, call);
+  } catch (e) {
+    const m = /^\s*([A-Za-z]+)/.exec(call.text);
+    const w = m ? m[1].toUpperCase() : "";
+    return WRITE_WORDS.has(w)
+      ? refuse(
+          "?",
+          e instanceof Skip ? e.message : "statement could not be read",
+        )
+      : null;
+  }
+
+  const c = classifyMysql(formatted);
+  if (c.parseFailed)
+    return WRITE_WORDS.has(c.firstWord)
+      ? refuse("?", "statement could not be read")
+      : null;
+  if (c.writes.length === 0) return null; // a read
+  const tbl = c.writes[0].tables.filter(Boolean)[0] || "?";
+  if (c.multi || c.writes.length !== 1)
+    return refuse(tbl, "several writes in one statement");
+  const w = c.writes[0];
+  if (w.kind !== "update" && w.kind !== "insert" && w.kind !== "delete")
+    return refuse(tbl, w.kind + " cannot be saved");
+  const bad = w.notes.find((n) =>
+    [
+      "has-subquery",
+      "upsert",
+      "insert-from-select",
+      "multi-table",
+      "replace",
+      "stored-procedure",
+    ].includes(n),
+  );
+  if (bad) return refuse(tbl, bad + " cannot be saved");
+  const stmt = parseOne(formatted);
+  if (!stmt || stmt.type !== w.kind)
+    return refuse(tbl, "this statement shape cannot be saved");
+  if (!call.cb)
+    return refuse(tbl, "this way of calling mysql2 cannot be saved");
+  let ref;
+  try {
+    ref = tableRef(stmt);
+  } catch (_) {
+    return refuse(tbl, "this statement shape cannot be saved");
+  }
+
+  // Our own reads and saves use mysql2's real query function, so the hook never sees them again.
+  const run = (sql, params) =>
+    new Promise((resolve, reject) => {
+      try {
+        queryOriginal.call(
+          client,
+          {
+            sql,
+            values: params && params.length ? params : undefined,
+            rowsAsArray: false,
+            nestTables: false,
+          },
+          (err, res) =>
+            err
+              ? reject(err)
+              : resolve({ rows: Array.isArray(res) ? res : [], header: res }),
+        );
+      } catch (e) {
+        reject(e);
+      }
+    });
+
+  return {
+    value: takeOver(client, args, original, call, (execHost) =>
+      runCapture(client, run, stmt, ref, w.kind, st, execHost),
+    ),
+  };
+}
+
+module.exports = { maybeCapture };