@blamejs/blamejs-shop 0.4.31 → 0.4.32

package/lib/vendor/blamejs/lib/external-db-migrate.js

@@ -63,17 +63,69 @@ var auditSign = lazyRequire(function () { return require("./audit-sign"); });
 var ExternalDbMigrateError = defineClass("ExternalDbMigrateError", { alwaysPermanent: true });
 
 // Lazy require — external-db imports back into this module via its
-// public `migrate` namespace; load-order would cycle without lazy.
+// public `migrate` namespace; load-order would cycle without lazy. The
+// same cycle (external-db -> external-db-migrate -> cluster-storage ->
+// cluster -> cluster-provider-db -> external-db) means clusterStorage +
+// frameworkSchema must be lazy here too, and the table-name constants
+// resolved on first use rather than at module load (frameworkSchema's
+// tableName export is not yet bound while this module evaluates).
 var externalDb = lazyRequire(function () { return require("./external-db"); });
+var clusterStorage = lazyRequire(function () { return require("./cluster-storage"); });
+var frameworkSchema = lazyRequire(function () { return require("./framework-schema"); });
+var sql = lazyRequire(function () { return require("./sql"); });
+
+// The migration runner's own bookkeeping tables, resolved through
+// frameworkSchema so the configurable framework-table prefix is honored
+// (these names are not in the LOCAL_TO_EXTERNAL map, so the resolve only
+// swaps the leading prefix; default prefix is a no-op). b.sql quotes
+// every identifier by construction in the backend's own dialect
+// (double-quote on Postgres / SQLite, backtick on MySQL), with the
+// placeholder form (`$N` on Postgres, `?` on SQLite / MySQL) selected by
+// the resolved backend dialect — see _backendDialect / _bind below.
+function _trackingTable() { return frameworkSchema().tableName("_blamejs_externaldb_migrations"); }        // allow:hand-rolled-sql — single canonical logical-name reference
+function _lockTable()     { return frameworkSchema().tableName("_blamejs_externaldb_migrations_lock"); }   // allow:hand-rolled-sql — single canonical logical-name reference
+function _historyTable()  { return frameworkSchema().tableName("_blamejs_schema_version_history"); }       // allow:hand-rolled-sql — single canonical logical-name reference
+
+// Resolve the SQL dialect of the backend this migration wave targets.
+// The runner emits Postgres / SQLite / MySQL — they diverge on identifier
+// quoting (double-quote vs backtick), the ON CONFLICT / ON DUPLICATE KEY
+// upsert idiom, and placeholder syntax (`$N` vs `?`). Reading the dialect
+// off the backend itself (set at b.externalDb.init) is what keeps the
+// bookkeeping DDL + tracking statements valid on each. Falls back to
+// "postgres" when the backend can't be resolved (uninitialized externalDb
+// surfaces a clearer error upstream at _resolveBackendName); the bare
+// fallback never reaches a real query.
+function _backendDialect(backendName) {
+  var listed;
+  try { listed = externalDb().listBackends(); }
+  catch (_e) { return "postgres"; }
+  for (var i = 0; i < listed.length; i++) {
+    if (listed[i].name === backendName) {
+      return (listed[i].dialect || "postgres").toLowerCase();
+    }
+  }
+  return "postgres";
+}
+
+// b.sql emits `?` placeholders; the externalDb driver receives SQL
+// verbatim, so translate to the Postgres `$N` form on a Postgres backend
+// (placeholderize is a passthrough for SQLite / MySQL, which keep `?`).
+// dialect is the resolved backend dialect so the placeholder form matches
+// the backend the SQL dispatches to.
+function _bind(builder, dialect) {
+  var built = builder.toSql();
+  return { sql: clusterStorage().placeholderize(built.sql, dialect), params: built.params };
+}
 
-var TRACKING_TABLE = "_blamejs_externaldb_migrations";
-var LOCK_TABLE     = "_blamejs_externaldb_migrations_lock";
-var HISTORY_TABLE  = "_blamejs_schema_version_history";
-// Identifiers wrapped in `"..."` per project convention so a reserved-word
-// or whitespace-bearing name resolves correctly.
-var Q_TRACKING = '"' + TRACKING_TABLE + '"';
-var Q_LOCK     = '"' + LOCK_TABLE + '"';
-var Q_HISTORY  = '"' + HISTORY_TABLE + '"';
+// The migration tracking / history / lock tables hold framework
+// bookkeeping ("migration X ran at time T"), not region-bound personal
+// data, so their writes carry the residency-neutral "unrestricted" tag
+// — the per-row residency write gate (b.externalDb.query) refuses DML
+// to a residency-tagged backend under a cross-border regulated posture
+// unless a compatible rowResidencyTag is supplied. Operator migration
+// DML (mod.up) stays subject to the gate; only these internal writes
+// are exempt. Passed as the per-statement opts override on the txClient.
+var FRAMEWORK_METADATA_OPTS = Object.freeze({ rowResidencyTag: "unrestricted" });
 
 // Bytes that get signed for one history row. Stable forever — changing
 // it invalidates every prior signature.
@@ -100,12 +152,11 @@ function _historyPayload(row) {
 // default introspect just returns the migration name list as a JSON
 // array, which is enough to detect "someone manually altered the
 // migrations table."
-async function _defaultSchemaIntrospect(xdb) {
-  var res = await xdb.query(
-    "SELECT name, appliedAt FROM " + Q_TRACKING +
-    " ORDER BY appliedAt ASC, name ASC",
-    []
-  );
+async function _defaultSchemaIntrospect(xdb, dialect) {
+  var q = _bind(sql().select(_trackingTable(), { dialect: dialect })
+    .columns(["name", "appliedAt"])
+    .orderBy("appliedAt", "asc").orderBy("name", "asc"), dialect);
+  var res = await xdb.query(q.sql, q.params);
   var rows = (res && res.rows) || [];
   return sha3Hash(Buffer.from(canonicalJson.stringify(rows), "utf8"));
 }
@@ -139,74 +190,73 @@ function _lockHolderId() {
     (require("node:os").hostname() || "unknown") + "@" + _BOOT_TOKEN;
 }
 
-async function _ensureTrackingTable(xdb) {
+async function _ensureTrackingTable(xdb, dialect) {
   // Tracking table holds the migration history. ISO-8601 timestamp
-  // strings (TEXT) keep the framework's tracking table portable across
-  // Postgres/SQLite without dialect-specific type juggling — operators
-  // who want strict TIMESTAMPTZ for their own ad-hoc queries against
-  // the table ALTER it post-creation.
-  await xdb.query(
-    "CREATE TABLE IF NOT EXISTS " + Q_TRACKING + " (" +
-    "  name        TEXT PRIMARY KEY," +
-    "  description TEXT," +
-    "  appliedAt   TEXT NOT NULL" +
-    ")",
-    []
-  );
+  // strings keep the framework's tracking table portable across
+  // Postgres/SQLite/MySQL without dialect-specific type juggling —
+  // operators who want strict TIMESTAMPTZ for their own ad-hoc queries
+  // against the table ALTER it post-creation. The `name` PK is a bounded
+  // VARCHAR, not TEXT: MySQL refuses an unbounded TEXT/BLOB in a key
+  // (ER 1170), and a migration filename is length-capped at FILE_NAME_MAX
+  // so 255 covers every valid value. Postgres / SQLite treat VARCHAR(255)
+  // identically to TEXT for storage.
+  await xdb.query(sql().createTable(_trackingTable(), [
+    { name: "name",        type: "VARCHAR(255)", primaryKey: true },
+    { name: "description", type: "TEXT" },
+    { name: "appliedAt",   type: "TEXT", notNull: true },
+  ], { dialect: dialect }).sql, []);
 }
 
-async function _ensureHistoryTable(xdb) {
+async function _ensureHistoryTable(xdb, dialect) {
   // Schema-version history table: append-only record of every migrate.up
   // wave + signature over (version, ranAt, ranBy, schemaIntrospectionHash).
   // Signature uses ML-DSA-87 / SLH-DSA-SHAKE-256f via b.auditSign — an
   // attacker tampering with rows after-the-fact cannot forge a matching
-  // signature without the audit-signing private key.
-  await xdb.query(
-    "CREATE TABLE IF NOT EXISTS " + Q_HISTORY + " (" +
-    "  version                 TEXT NOT NULL," +
-    "  ranAt                   TEXT NOT NULL," +
-    "  ranBy                   TEXT NOT NULL," +
-    "  schemaIntrospectionHash TEXT NOT NULL," +
-    "  signature               TEXT," +
-    "  publicKeyFingerprint    TEXT," +
-    "  PRIMARY KEY (version, ranAt)" +
-    ")",
-    []
-  );
+  // signature without the audit-signing private key. version + ranAt form
+  // the composite PK, so both are bounded VARCHARs (MySQL refuses an
+  // unbounded TEXT/BLOB in a key, ER 1170); version is a filename
+  // (length-capped) and ranAt an ISO-8601 string, both within bound.
+  await xdb.query(sql().createTable(_historyTable(), [
+    { name: "version",                 type: "VARCHAR(255)", notNull: true },
+    { name: "ranAt",                   type: "VARCHAR(64)", notNull: true },
+    { name: "ranBy",                   type: "TEXT", notNull: true },
+    { name: "schemaIntrospectionHash", type: "TEXT", notNull: true },
+    { name: "signature",               type: "TEXT" },
+    { name: "publicKeyFingerprint",    type: "TEXT" },
+  ], { dialect: dialect, primaryKey: ["version", "ranAt"] }).sql, []);
 }
 
-async function _writeHistoryRow(xdb, row) {
-  await xdb.query(
-    "INSERT INTO " + Q_HISTORY +
-    " (version, ranAt, ranBy, schemaIntrospectionHash, signature, publicKeyFingerprint) " +
-    " VALUES ($1, $2, $3, $4, $5, $6)",
-    [
-      row.version,
-      row.ranAt,
-      row.ranBy,
-      row.schemaIntrospectionHash,
-      row.signature,
-      row.publicKeyFingerprint,
-    ]
-  );
+async function _writeHistoryRow(xdb, row, dialect) {
+  var q = _bind(sql().insert(_historyTable(), { dialect: dialect }).values({
+    version:                 row.version,
+    ranAt:                   row.ranAt,
+    ranBy:                   row.ranBy,
+    schemaIntrospectionHash: row.schemaIntrospectionHash,
+    signature:               row.signature,
+    publicKeyFingerprint:    row.publicKeyFingerprint,
+  }), dialect);
+  await xdb.query(q.sql, q.params, FRAMEWORK_METADATA_OPTS);
 }
 
-async function _ensureLockTable(xdb) {
-  await xdb.query(
-    "CREATE TABLE IF NOT EXISTS " + Q_LOCK + " (" +
-    "  scope     TEXT PRIMARY KEY," +
-    "  lockedAt  INTEGER NOT NULL," +
-    "  lockedBy  TEXT NOT NULL," +
-    "  CHECK (scope = 'lock')" +
-    ")",
-    []
-  );
+async function _ensureLockTable(xdb, dialect) {
+  // The scope CHECK is a static operator-controlled literal, carried as
+  // the last column's verbatim constraint (b.sql guards it via
+  // allowLiterals). lockedAt holds a ms-epoch value, so the framework INT
+  // type (BIGINT on Postgres/MySQL) is required — a 32-bit INTEGER
+  // overflows. The scope PK is a bounded VARCHAR (only ever 'lock'): MySQL
+  // refuses an unbounded TEXT/BLOB in a key (ER 1170).
+  await xdb.query(sql().createTable(_lockTable(), [
+    { name: "scope",    type: "VARCHAR(64)", primaryKey: true },
+    { name: "lockedAt", type: "INTEGER", notNull: true },
+    { name: "lockedBy", type: "TEXT", notNull: true,
+      constraints: ", CHECK (scope = 'lock')" },                                    // allow:hand-rolled-sql — static DDL CHECK literal
+  ], { dialect: dialect }).sql, []);
 }
 
 // ---- Lock acquire / release ----
 
-async function _acquireLock(xdb, opts) {
-  await _ensureLockTable(xdb);
+async function _acquireLock(xdb, opts, dialect) {
+  await _ensureLockTable(xdb, dialect);
   var holder = _lockHolderId();
   var nowMs = Date.now();
   // See migrations.acquireLock for the same fix — Infinity was
@@ -218,27 +268,67 @@ async function _acquireLock(xdb, opts) {
       ExternalDbMigrateError, "externalDb-migrate/bad-opt");
     if (opts.staleAfterMs !== undefined) staleAfterMs = opts.staleAfterMs;
   }
+  // Conflict-safe lock acquire. The INSERT runs inside
+  // externalDb.transaction(_acquireLock); on Postgres a plain INSERT that
+  // hits the PRIMARY KEY conflict raises SQLSTATE 23505 which ABORTS the
+  // surrounding transaction (every later statement then fails with 25P02,
+  // "current transaction is aborted"), so the holder-naming SELECT could
+  // not run and the operator got a raw aborted-transaction error instead of
+  // the documented "migration lock is held by <holder>" message. Emitting
+  // `INSERT ... ON CONFLICT (scope) DO NOTHING` (Postgres/SQLite) /
+  // `INSERT ... ON DUPLICATE KEY UPDATE scope=scope` (MySQL — a no-op)
+  // turns the conflict into a 0-row result rather than a transaction-
+  // aborting error, so the inspect SELECT below runs cleanly and names the
+  // holder. rowCount === 1 means we won the lock; 0 means it is held.
+  function _insertLock() {
+    return _bind(sql().upsert(_lockTable(), { dialect: dialect })
+      .values({ scope: "lock", lockedAt: nowMs, lockedBy: holder })
+      .onConflict(["scope"]).doNothing(), dialect);
+  }
+  var insRes;
   try {
-    await xdb.query(
-      "INSERT INTO " + Q_LOCK + " (scope, lockedAt, lockedBy) VALUES ('lock', $1, $2)",
-      [nowMs, holder]
-    );
+    var ins = _insertLock();
+    insRes = await xdb.query(ins.sql, ins.params, FRAMEWORK_METADATA_OPTS);
+  } catch (e0) {
+    // A genuine driver/connection fault (not a conflict — the conflict is now
+    // a 0-row no-op, never a throw). Surface as lock-busy.
+    throw _err("externaldb-migrate/lock-busy",
+      "could not acquire migration lock: " + ((e0 && e0.message) || String(e0)));
+  }
+  if (insRes && insRes.rowCount >= 1) {
     return { holder: holder, takeoverFrom: null, takeoverAgeMs: 0 };
-  } catch (_e) {
-    // PRIMARY KEY conflict → existing lock. Inspect it.
-    var existingRes = await xdb.query(
-      "SELECT lockedAt, lockedBy FROM " + Q_LOCK + " WHERE scope = 'lock'",
-      []
-    );
+  }
+  {
+    // 0 rows inserted → the lock IS held. Inspect it to name the holder. The
+    // conflict was a clean no-op (DO NOTHING), so the transaction is NOT
+    // aborted and this SELECT runs.
+    var selExisting = _bind(sql().select(_lockTable(), { dialect: dialect })
+      .columns(["lockedAt", "lockedBy"]).where("scope", "lock"), dialect);
+    var existingRes;
+    try {
+      existingRes = await xdb.query(selExisting.sql, selExisting.params);
+    } catch (_inspectErr) {
+      throw _err("externaldb-migrate/lock-held",
+        "migration lock is held — another process is running migrations " +
+        "(the lock row could not be inspected). Wait for it to finish, or " +
+        "pass staleAfterMs to force-replace stale locks.");
+    }
     var existing = existingRes && existingRes.rows && existingRes.rows[0];
     if (!existing) {
+      // Lock row vanished between the no-op insert and the inspect (the
+      // holder released concurrently). Retry the acquire once.
       try {
-        await xdb.query(
-          "INSERT INTO " + Q_LOCK + " (scope, lockedAt, lockedBy) VALUES ('lock', $1, $2)",
-          [nowMs, holder]
-        );
-        return { holder: holder, takeoverFrom: null, takeoverAgeMs: 0 };
+        var insRetry = _insertLock();
+        var retryRes = await xdb.query(insRetry.sql, insRetry.params, FRAMEWORK_METADATA_OPTS);
+        if (retryRes && retryRes.rowCount >= 1) {
+          return { holder: holder, takeoverFrom: null, takeoverAgeMs: 0 };
+        }
+        throw _err("externaldb-migrate/lock-held",
+          "migration lock is held — another process re-acquired it during " +
+          "the acquire race. Wait for it to finish, or pass staleAfterMs to " +
+          "force-replace stale locks.");
       } catch (e2) {
+        if (e2 && e2.isExternalDbMigrateError) throw e2;
         throw _err("externaldb-migrate/lock-busy",
           "could not acquire migration lock: " + ((e2 && e2.message) || String(e2)));
       }
@@ -248,14 +338,19 @@ async function _acquireLock(xdb, opts) {
       // Force-replace the stale lock atomically. Stale-takeover is a
       // SOC2 evidence event — caller emits an audit row.
       var prevHolder = existing.lockedby || existing.lockedBy;
-      await xdb.query(
-        "DELETE FROM " + Q_LOCK + " WHERE scope = 'lock' AND lockedAt = $1",
-        [Number(existing.lockedat || existing.lockedAt)]
-      );
-      await xdb.query(
-        "INSERT INTO " + Q_LOCK + " (scope, lockedAt, lockedBy) VALUES ('lock', $1, $2)",
-        [nowMs, holder]
-      );
+      var delStale = _bind(sql().delete(_lockTable(), { dialect: dialect })
+        .where("scope", "lock")
+        .where("lockedAt", Number(existing.lockedat || existing.lockedAt)), dialect);
+      await xdb.query(delStale.sql, delStale.params, FRAMEWORK_METADATA_OPTS);
+      var insTakeover = _insertLock();
+      var takeoverRes = await xdb.query(insTakeover.sql, insTakeover.params, FRAMEWORK_METADATA_OPTS);
+      if (!takeoverRes || takeoverRes.rowCount < 1) {
+        // Another process slipped a fresh lock in between our DELETE and
+        // INSERT (the conflict is a DO NOTHING no-op, so 0 rows = lost race).
+        throw _err("externaldb-migrate/lock-held",
+          "migration lock was re-acquired by another process during the " +
+          "stale-lock takeover. Wait for it to finish, or retry.");
+      }
       return { holder: holder, takeoverFrom: prevHolder, takeoverAgeMs: ageMs };
     }
     throw _err("externaldb-migrate/lock-held",
@@ -265,12 +360,11 @@ async function _acquireLock(xdb, opts) {
   }
 }
 
-async function _releaseLock(xdb, holder) {
+async function _releaseLock(xdb, holder, dialect) {
   try {
-    await xdb.query(
-      "DELETE FROM " + Q_LOCK + " WHERE scope = 'lock' AND lockedBy = $1",
-      [holder]
-    );
+    var del = _bind(sql().delete(_lockTable(), { dialect: dialect })
+      .where("scope", "lock").where("lockedBy", holder), dialect);
+    await xdb.query(del.sql, del.params, FRAMEWORK_METADATA_OPTS);
   } catch (_e) {
     // best-effort release; operator can DELETE manually.
   }
@@ -370,13 +464,13 @@ function create(opts) {
 
   async function status() {
     var backendName = _resolveBackendName(opts);
+    var dialect = _backendDialect(backendName);
     return await externalDb().transaction(async function (xdb) {
-      await _ensureTrackingTable(xdb);
-      var res = await xdb.query(
-        "SELECT name, description, appliedAt FROM " + Q_TRACKING +
-        " ORDER BY appliedAt ASC, name ASC",
-        []
-      );
+      await _ensureTrackingTable(xdb, dialect);
+      var q = _bind(sql().select(_trackingTable(), { dialect: dialect })
+        .columns(["name", "description", "appliedAt"])
+        .orderBy("appliedAt", "asc").orderBy("name", "asc"), dialect);
+      var res = await xdb.query(q.sql, q.params);
       var applied = (res && res.rows) || [];
       var appliedNames = new Set(applied.map(function (r) { return r.name; }));
       var files = _list(dir);
@@ -392,12 +486,13 @@ function create(opts) {
 
   async function up() {
     var backendName = _resolveBackendName(opts);
+    var dialect = _backendDialect(backendName);
     var ctx = _ctx(backendName);
 
     return await externalDb().transaction(async function (xdb) {
-      await _ensureTrackingTable(xdb);
-      await _ensureLockTable(xdb);
-      await _ensureHistoryTable(xdb);
+      await _ensureTrackingTable(xdb, dialect);
+      await _ensureLockTable(xdb, dialect);
+      await _ensureHistoryTable(xdb, dialect);
     }, { backend: backendName }).then(async function () {
       // Acquire the lock OUTSIDE the per-migration transaction so the
       // lock survives across migration boundaries. We use a separate
@@ -405,7 +500,7 @@ function create(opts) {
       // serializes apply order, so this single-connection lock is
       // sufficient.
       var lockResult = await externalDb().transaction(async function (xdb) {
-        return await _acquireLock(xdb, opts);
+        return await _acquireLock(xdb, opts, dialect);
       }, { backend: backendName });
       var lockHolder = lockResult.holder;
 
@@ -421,9 +516,9 @@ function create(opts) {
       }
 
       try {
-        var appliedRes = await externalDb().query(
-          "SELECT name FROM " + Q_TRACKING, [], { backend: backendName }
-        );
+        var appliedQ = _bind(sql().select(_trackingTable(), { dialect: dialect })
+          .columns(["name"]), dialect);
+        var appliedRes = await externalDb().query(appliedQ.sql, appliedQ.params, { backend: backendName });
         var appliedSet = new Set(((appliedRes && appliedRes.rows) || []).map(function (r) { return r.name; }));
         var files = _list(dir);
         var applied = [];
@@ -438,11 +533,9 @@ function create(opts) {
             await externalDb().transaction(async function (xdb) {
               await mod.up(xdb, ctx);
               var ranAt = new Date().toISOString();
-              await xdb.query(
-                "INSERT INTO " + Q_TRACKING +
-                " (name, description, appliedAt) VALUES ($1, $2, $3)",
-                [file, mod.description || "", ranAt]
-              );
+              var insTrack = _bind(sql().insert(_trackingTable(), { dialect: dialect })
+                .values({ name: file, description: mod.description || "", appliedAt: ranAt }), dialect);
+              await xdb.query(insTrack.sql, insTrack.params, FRAMEWORK_METADATA_OPTS);
               // Schema-version history with signature. Sign post-INSERT
               // so the introspection hash reflects the row that just
               // landed. Sign-failure is non-fatal for the migration but
@@ -451,7 +544,7 @@ function create(opts) {
                 version:                 file,
                 ranAt:                   ranAt,
                 ranBy:                   ranBy,
-                schemaIntrospectionHash: await schemaIntrospect(xdb),
+                schemaIntrospectionHash: await schemaIntrospect(xdb, dialect),
                 signature:               null,
                 publicKeyFingerprint:    null,
               };
@@ -467,7 +560,7 @@ function create(opts) {
                     (sigErr && sigErr.message) || String(sigErr));
                 }
               }
-              await _writeHistoryRow(xdb, historyRow);
+              await _writeHistoryRow(xdb, historyRow, dialect);
               _emit(audit, "migrations.history.appended", "success", {
                 migration: file,
                 schemaIntrospectionHash: historyRow.schemaIntrospectionHash,
@@ -490,7 +583,7 @@ function create(opts) {
       } finally {
         try {
           await externalDb().transaction(async function (xdb) {
-            await _releaseLock(xdb, lockHolder);
+            await _releaseLock(xdb, lockHolder, dialect);
           }, { backend: backendName });
           _emit(audit, "externaldb.migrate.lock.released", "success",
                 { holder: lockHolder, backend: backendName }, null);
@@ -507,15 +600,16 @@ function create(opts) {
     var steps = (typeof downOpts.steps === "number" && downOpts.steps > 0)
                   ? Math.floor(downOpts.steps) : 1;
     var backendName = _resolveBackendName(opts);
+    var dialect = _backendDialect(backendName);
     var ctx = _ctx(backendName);
 
     await externalDb().transaction(async function (xdb) {
-      await _ensureTrackingTable(xdb);
-      await _ensureLockTable(xdb);
+      await _ensureTrackingTable(xdb, dialect);
+      await _ensureLockTable(xdb, dialect);
     }, { backend: backendName });
 
     var lockResultDown = await externalDb().transaction(async function (xdb) {
-      return await _acquireLock(xdb, opts);
+      return await _acquireLock(xdb, opts, dialect);
     }, { backend: backendName });
     var lockHolder = lockResultDown.holder;
 
@@ -528,10 +622,10 @@ function create(opts) {
     }
 
     try {
-      var appliedRes = await externalDb().query(
-        "SELECT name FROM " + Q_TRACKING + " ORDER BY appliedAt DESC, name DESC LIMIT $1",
-        [steps], { backend: backendName }
-      );
+      var downQ = _bind(sql().select(_trackingTable(), { dialect: dialect })
+        .columns(["name"])
+        .orderBy("appliedAt", "desc").orderBy("name", "desc").limit(steps), dialect);
+      var appliedRes = await externalDb().query(downQ.sql, downQ.params, { backend: backendName });
       var rows = (appliedRes && appliedRes.rows) || [];
       var reverted = [];
       for (var i = 0; i < rows.length; i++) {
@@ -545,10 +639,9 @@ function create(opts) {
         try {
           await externalDb().transaction(async function (xdb) {
             await mod.down(xdb, ctx);
-            await xdb.query(
-              "DELETE FROM " + Q_TRACKING + " WHERE name = $1",
-              [file]
-            );
+            var delTrack = _bind(sql().delete(_trackingTable(), { dialect: dialect })
+              .where("name", file), dialect);
+            await xdb.query(delTrack.sql, delTrack.params);
           }, { backend: backendName });
           _emit(audit, "externaldb.migrate.down", "success",
                 { migration: file, durationMs: Date.now() - t0, backend: backendName }, null);
@@ -565,7 +658,7 @@ function create(opts) {
     } finally {
       try {
         await externalDb().transaction(async function (xdb) {
-          await _releaseLock(xdb, lockHolder);
+          await _releaseLock(xdb, lockHolder, dialect);
         }, { backend: backendName });
         _emit(audit, "externaldb.migrate.lock.released", "success",
               { holder: lockHolder, backend: backendName }, null);
@@ -588,13 +681,13 @@ function create(opts) {
   async function history(historyOpts) {
     historyOpts = historyOpts || {};
     var backendName = _resolveBackendName(opts);
+    var dialect = _backendDialect(backendName);
     return await externalDb().transaction(async function (xdb) {
-      await _ensureHistoryTable(xdb);
-      var res = await xdb.query(
-        "SELECT version, ranAt, ranBy, schemaIntrospectionHash, signature, publicKeyFingerprint " +
-        "FROM " + Q_HISTORY + " ORDER BY ranAt ASC, version ASC",
-        []
-      );
+      await _ensureHistoryTable(xdb, dialect);
+      var histQ = _bind(sql().select(_historyTable(), { dialect: dialect })
+        .columns(["version", "ranAt", "ranBy", "schemaIntrospectionHash", "signature", "publicKeyFingerprint"])
+        .orderBy("ranAt", "asc").orderBy("version", "asc"), dialect);
+      var res = await xdb.query(histQ.sql, histQ.params);
       var out = [];
       var rows = (res && res.rows) || [];
       for (var i = 0; i < rows.length; i++) {
@@ -653,7 +746,16 @@ function create(opts) {
 module.exports = {
   create:                  create,
   ExternalDbMigrateError:  ExternalDbMigrateError,
-  TRACKING_TABLE:          TRACKING_TABLE,
-  HISTORY_TABLE:           HISTORY_TABLE,
   HISTORY_SIGNATURE_FORMAT: HISTORY_SIGNATURE_FORMAT,
 };
+
+// The resolved table names are exposed as lazy getters: frameworkSchema's
+// tableName export is not bound while this module evaluates (the
+// external-db require cycle), so resolving at access time gives the
+// configurable-prefix-aware concrete name without a load-order trap.
+Object.defineProperty(module.exports, "TRACKING_TABLE", {
+  enumerable: true, get: function () { return _trackingTable(); },
+});
+Object.defineProperty(module.exports, "HISTORY_TABLE", {
+  enumerable: true, get: function () { return _historyTable(); },
+});