@blamejs/core 0.14.27 → 0.15.1

package/lib/cluster-provider-db.js

@@ -48,15 +48,35 @@
 var C = require("./constants");
 var { generateToken } = require("./crypto");
 var externalDb = require("./external-db");
+var frameworkSchema = require("./framework-schema");
+var lazyRequire = require("./lazy-require");
 var { ClusterProviderError } = require("./framework-error");
 
 var _err = ClusterProviderError.factory;
 
+// Lazy requires — cluster.js requires this module while cluster-storage /
+// sql are still mid-load (cluster -> cluster-provider-db -> external-db ->
+// external-db-migrate -> cluster-storage -> cluster), so a top-of-file
+// require would resolve to an unfinished module. clusterStorage.placeholderize
+// translates the b.sql `?` output to Postgres `$N`; sql is the b.sql builder.
+// Both are resolved at first SQL emission, by which point the cycle has settled.
+var clusterStorage = lazyRequire(function () { return require("./cluster-storage"); });
+var sql = lazyRequire(function () { return require("./sql"); });
+
 function create(config) {
   if (!config || !config.externalDbBackend) {
     throw _err("INVALID_CONFIG",
       "cluster-provider-db requires { externalDbBackend: <name> }", true);
   }
+
+  // The coordination tables, resolved through frameworkSchema so the
+  // configurable framework-table prefix is honored. These names are
+  // already `_blamejs_`-prefixed; the resolve is a no-op under the default
+  // prefix and namespaces them under a custom one. Resolved here (not at
+  // module load) because cluster.js requires this module while
+  // framework-schema is mid-load — its tableName export is not yet bound.
+  var LEADER_TABLE = frameworkSchema.tableName("_blamejs_leader");          // allow:hand-rolled-sql — single canonical logical-name reference
+  var STATE_TABLE  = frameworkSchema.tableName("_blamejs_cluster_state");   // allow:hand-rolled-sql — single canonical logical-name reference
   var backendName = config.externalDbBackend;
   var dialect = (config.dialect || "postgres").toLowerCase();
   if (dialect !== "postgres" && dialect !== "sqlite" && dialect !== "mysql") {
@@ -65,16 +85,45 @@ function create(config) {
       true);
   }
 
-  // Postgres + SQLite use $1/$2 placeholders; MySQL uses ?. Keeping a
-  // single helper means the SQL builder doesn't have to care.
-  function _placeholder(n) {
-    return dialect === "mysql" ? "?" : "$" + n;
+  // The backtick / double-quote identifier-quote char b.sql raw fragments
+  // (the upsert fencing increment + conflict guard) must use so a fragment
+  // composes into the dialect-final statement with consistent quoting.
+  var qchar = dialect === "mysql" ? "`" : "\"";
+  function _qraw(col) { return qchar + col + qchar; }
+
+  // Existing-row self-reference inside an upsert's DO UPDATE / conflict guard.
+  // Postgres' ON CONFLICT DO UPDATE puts BOTH the target row and the `excluded`
+  // proposed row in scope with identical columns, so a bare column is ambiguous
+  // (SQLSTATE 42702) — the existing-row reference must be table-qualified.
+  // SQLite resolves a bare column to the target (no `excluded` ambiguity); MySQL
+  // uses the ON DUPLICATE KEY IF()-fold (no `excluded` table) and b.sql reads the
+  // bare column for that fold — so both keep the unqualified form.
+  function _selfCol(col) {
+    return dialect === "postgres" ? (LEADER_TABLE + "." + _qraw(col)) : _qraw(col);
+  }
+
+  // Emit a b.sql builder to dialect-final { sql, params }: b.sql always
+  // emits `?` placeholders, so translate them to `$N` for Postgres (the
+  // externalDb driver receives the SQL verbatim and never renumbers).
+  // SQLite + MySQL both accept `?`.
+  function _emit(builder) {
+    var built = builder.toSql();
+    return {
+      sql:    clusterStorage().placeholderize(built.sql, dialect),
+      params: built.params,
+    };
   }
 
   function _q(sql, params) {
     return externalDb.query(sql, params || [], { backend: backendName });
   }
 
+  // Run a b.sql builder against the backend.
+  function _run(builder) {
+    var e = _emit(builder);
+    return _q(e.sql, e.params);
+  }
+
   async function ensureSchema() {
     // Postgres + MySQL: BIGINT for ms-precision timestamps. SQLite:
     // INTEGER (which is wide enough to hold a 64-bit value).
@@ -90,38 +139,38 @@ function create(config) {
     // belt-and-braces — application code only ever writes 'leader' /
     // 'state' so the check is informational. Skip on MySQL to avoid
     // CREATE TABLE failures on installations where CHECK is parsed
-    // but then dropped silently (which would cause version drift).
-    var leaderCheck = dialect === "mysql" ? "" : ", CHECK (scope = 'leader')";
-    var stateCheck  = dialect === "mysql" ? "" : ", CHECK (scope = 'state')";
+    // but then dropped silently (which would cause version drift). The
+    // scope CHECK is a static, operator-controlled literal carried as the
+    // last column's verbatim constraint (b.sql guards it with allowLiterals
+    // since it is not operator input).
+    var leaderCheck = dialect === "mysql" ? "" : ", CHECK (scope = 'leader')";   // allow:hand-rolled-sql — static DDL CHECK literal
+    var stateCheck  = dialect === "mysql" ? "" : ", CHECK (scope = 'state')";    // allow:hand-rolled-sql — static DDL CHECK literal
 
-    await _q(
-      "CREATE TABLE IF NOT EXISTS _blamejs_leader (" +
-      "  scope         " + pkText + " PRIMARY KEY," +
-      "  nodeId        " + bodyText + " NOT NULL," +
-      "  leaseId       " + bodyText + " NOT NULL," +
-      "  acquiredAt    " + intType + " NOT NULL," +
-      "  expiresAt     " + intType + " NOT NULL," +
-      "  fencingToken  " + intType + " NOT NULL," +
-      "  endpoint      " + bodyText + leaderCheck +
-      ")"
-    );
+    await _q(sql().createTable(LEADER_TABLE, [
+      { name: "scope",        type: pkText,   primaryKey: true },
+      { name: "nodeId",       type: bodyText, notNull: true },
+      { name: "leaseId",      type: bodyText, notNull: true },
+      { name: "acquiredAt",   type: intType,  notNull: true },
+      { name: "expiresAt",    type: intType,  notNull: true },
+      { name: "fencingToken", type: intType,  notNull: true },
+      { name: "endpoint",     type: bodyText, constraints: leaderCheck },
+    ], { dialect: dialect }).sql);
     // Migration for installs that pre-date the endpoint column. Both
     // Postgres (≥9.6) and SQLite (≥3.35, March 2021) support ADD COLUMN
     // IF NOT EXISTS; MySQL 8.0.29+ does as well. We go through try/catch
     // to keep the path version-agnostic — the only "expected" failure
     // here is "column already exists," which we swallow.
     try {
-      await _q("ALTER TABLE _blamejs_leader ADD COLUMN endpoint " + bodyText);
+      await _q(sql().alterTable(LEADER_TABLE,
+        { addColumn: { name: "endpoint", type: bodyText } }, { dialect: dialect }).sql);
     } catch (_e) { /* column already exists — fine */ }
 
-    await _q(
-      "CREATE TABLE IF NOT EXISTS _blamejs_cluster_state (" +
-      "  scope           " + pkText + " PRIMARY KEY," +
-      "  vaultKeyFp      " + bodyText + " NOT NULL," +
-      "  recordedAt      " + intType + " NOT NULL," +
-      "  recordedByNode  " + bodyText + " NOT NULL" + stateCheck +
-      ")"
-    );
+    await _q(sql().createTable(STATE_TABLE, [
+      { name: "scope",          type: pkText,   primaryKey: true },
+      { name: "vaultKeyFp",     type: bodyText, notNull: true },
+      { name: "recordedAt",     type: intType,  notNull: true },
+      { name: "recordedByNode", type: bodyText, notNull: true, constraints: stateCheck },
+    ], { dialect: dialect }).sql);
   }
 
   async function acquireLease(nodeId, leaseTtlMs, opts) {
@@ -134,60 +183,45 @@ function create(config) {
     var nowMs = Date.now();
     var expiresAt = nowMs + leaseTtlMs;
 
+    // One upsert builder serves every dialect. Postgres / SQLite emit
+    // `INSERT ... ON CONFLICT (scope) DO UPDATE SET ... WHERE expiresAt < ?
+    // RETURNING ...` (atomic acquire-or-steal in one statement). MySQL has
+    // no `ON CONFLICT ... WHERE` / `RETURNING`, so b.sql folds the conflict
+    // guard into `IF(expiresAt < ?, <new>, <old>)` per column (the still-
+    // valid lease is preserved, the expired one overwritten) and emits a
+    // readback SELECT keyed on scope='leader'. The fencing-token bump
+    // (`fencingToken + 1`) is the only non-proposed-value assignment; every
+    // other column re-binds the proposed value (equivalent to EXCLUDED.col /
+    // VALUES(col)). guardColumn names expiresAt so the MySQL fold assigns it
+    // LAST — IF() evaluates each column against the PRE-update row state, so
+    // expiresAt must change after the columns whose guard reads it.
+    var acquire = sql().upsert(LEADER_TABLE, { dialect: dialect })
+      .columns(["scope", "nodeId", "leaseId", "acquiredAt", "expiresAt", "fencingToken", "endpoint"])
+      .values({
+        scope: "leader", nodeId: nodeId, leaseId: leaseId,
+        acquiredAt: nowMs, expiresAt: expiresAt, fencingToken: 1, endpoint: endpoint,
+      })
+      .doUpdate({
+        nodeId: "?", leaseId: "?", acquiredAt: "?", expiresAt: "?",
+        fencingToken: _selfCol("fencingToken") + " + 1",
+        endpoint: "?",
+      }, [nodeId, leaseId, nowMs, expiresAt, endpoint])
+      .conflictWhere(_selfCol("expiresAt") + " < ?", [nowMs], { guardColumn: "expiresAt" })
+      .returning(["nodeId", "leaseId", "acquiredAt", "expiresAt", "fencingToken", "endpoint"]);
+
     var row;
     if (dialect === "mysql") {
-      // MySQL has no `ON CONFLICT ... DO UPDATE WHERE` and no
-      // `RETURNING`. Atomicity comes from `INSERT ... ON DUPLICATE
-      // KEY UPDATE` evaluated as one statement; the WHERE-clause
-      // semantics are implemented per-column with `IF(expiresAt <
-      // nowMs, VALUES(col), col)` so a still-valid lease is preserved
-      // and an expired one is overwritten. The follow-up SELECT
-      // reveals who currently holds the row — same as Postgres'
-      // RETURNING but as a separate statement.
-      var insertSql =
-        "INSERT INTO _blamejs_leader " +
-        "  (scope, nodeId, leaseId, acquiredAt, expiresAt, fencingToken, endpoint) " +
-        "VALUES " +
-        "  ('leader', ?, ?, ?, ?, 1, ?) " +
-        "ON DUPLICATE KEY UPDATE " +
-        "  nodeId       = IF(expiresAt < ?, VALUES(nodeId), nodeId)," +
-        "  leaseId      = IF(expiresAt < ?, VALUES(leaseId), leaseId)," +
-        "  acquiredAt   = IF(expiresAt < ?, VALUES(acquiredAt), acquiredAt)," +
-        "  fencingToken = IF(expiresAt < ?, fencingToken + 1, fencingToken)," +
-        "  endpoint     = IF(expiresAt < ?, VALUES(endpoint), endpoint)," +
-        // expiresAt MUST be the last assignment — IF() evaluates each
-        // column against the row state BEFORE that column's update is
-        // applied, so checking expiresAt for the other columns first
-        // and overwriting it last keeps the predicate consistent.
-        "  expiresAt    = IF(expiresAt < ?, VALUES(expiresAt), expiresAt)";
-      await _q(insertSql, [
-        nodeId, leaseId, nowMs, expiresAt, endpoint,
-        nowMs, nowMs, nowMs, nowMs, nowMs, nowMs,
-      ]);
-      var sel = await _q(
-        "SELECT nodeId, leaseId, acquiredAt, expiresAt, fencingToken, endpoint " +
-        "FROM _blamejs_leader WHERE scope = 'leader'"
-      );
+      var mBuilt = acquire.toSql();
+      await _q(clusterStorage().placeholderize(mBuilt.sql, dialect), mBuilt.params);
+      // b.sql's MySQL upsert returns the readback SELECT alongside (the
+      // RETURNING-equivalent); run it to learn who currently holds the row.
+      var rb = mBuilt.readbackSql;
+      var sel = await _q(clusterStorage().placeholderize(rb.sql, dialect), rb.params);
       if (!sel.rows || sel.rows.length === 0) return null;
       row = sel.rows[0];
     } else {
-      // Postgres / SQLite — single-statement RETURNING.
-      var sql =
-        "INSERT INTO _blamejs_leader " +
-        "  (scope, nodeId, leaseId, acquiredAt, expiresAt, fencingToken, endpoint) " +
-        "VALUES " +
-        "  ('leader', " + _placeholder(1) + ", " + _placeholder(2) + ", " +
-        "   " + _placeholder(3) + ", " + _placeholder(4) + ", 1, " + _placeholder(5) + ") " +
-        "ON CONFLICT (scope) DO UPDATE SET " +
-        "  nodeId       = EXCLUDED.nodeId," +
-        "  leaseId      = EXCLUDED.leaseId," +
-        "  acquiredAt   = EXCLUDED.acquiredAt," +
-        "  expiresAt    = EXCLUDED.expiresAt," +
-        "  fencingToken = _blamejs_leader.fencingToken + 1," +
-        "  endpoint     = EXCLUDED.endpoint " +
-        "WHERE _blamejs_leader.expiresAt < " + _placeholder(6) + " " +
-        "RETURNING nodeId, leaseId, acquiredAt, expiresAt, fencingToken, endpoint";
-      var result = await _q(sql, [nodeId, leaseId, nowMs, expiresAt, endpoint, nowMs]);
+      acquire.onConflict(["scope"]);
+      var result = await _run(acquire);
       if (!result.rows || result.rows.length === 0) return null;
       row = result.rows[0];
     }
@@ -219,24 +253,24 @@ function create(config) {
     // returns either no row OR a row with a different leaseId, and
     // we throw LEASE_LOST. Don't bump fencingToken on renewal — only
     // on a fresh acquire.
+    var renewCols = ["nodeId", "leaseId", "acquiredAt", "expiresAt", "fencingToken", "endpoint"];
     var row;
     if (dialect === "mysql") {
-      var rv = await _q(
-        "UPDATE _blamejs_leader SET " +
-        "  expiresAt = ?, endpoint = ? " +
-        "WHERE scope = 'leader' AND nodeId = ? AND leaseId = ?",
-        [newExpiresAt, endpoint, lease.nodeId, lease.leaseId]
-      );
+      // MySQL has no RETURNING — UPDATE then read back, with a takeover
+      // detected when the read-back row no longer carries our leaseId.
+      var rvBuilt = sql().update(LEADER_TABLE, { dialect: dialect })
+        .set({ expiresAt: newExpiresAt, endpoint: endpoint })
+        .where("scope", "leader").where("nodeId", lease.nodeId).where("leaseId", lease.leaseId)
+        .toSql();
+      var rv = await _q(clusterStorage().placeholderize(rvBuilt.sql, dialect), rvBuilt.params);
       var affected = rv && (rv.affectedRows || rv.rowCount || 0);
       if (!affected) {
         throw _err("LEASE_LOST",
           "lease for node '" + lease.nodeId + "' was taken over (renewal rejected)",
           false);
       }
-      var sel = await _q(
-        "SELECT nodeId, leaseId, acquiredAt, expiresAt, fencingToken, endpoint " +
-        "FROM _blamejs_leader WHERE scope = 'leader'"
-      );
+      var sel = await _run(sql().select(LEADER_TABLE, { dialect: dialect })
+        .columns(renewCols).where("scope", "leader"));
       if (!sel.rows || sel.rows.length === 0 ||
           sel.rows[0].nodeId !== lease.nodeId ||
           sel.rows[0].leaseId !== lease.leaseId) {
@@ -246,14 +280,10 @@ function create(config) {
       }
       row = sel.rows[0];
     } else {
-      var sql =
-        "UPDATE _blamejs_leader SET " +
-        "  expiresAt = " + _placeholder(1) + "," +
-        "  endpoint  = " + _placeholder(2) + " " +
-        "WHERE scope = 'leader' AND nodeId = " + _placeholder(3) +
-        "  AND leaseId = " + _placeholder(4) + " " +
-        "RETURNING nodeId, leaseId, acquiredAt, expiresAt, fencingToken, endpoint";
-      var result = await _q(sql, [newExpiresAt, endpoint, lease.nodeId, lease.leaseId]);
+      var result = await _run(sql().update(LEADER_TABLE, { dialect: dialect })
+        .set({ expiresAt: newExpiresAt, endpoint: endpoint })
+        .where("scope", "leader").where("nodeId", lease.nodeId).where("leaseId", lease.leaseId)
+        .returning(renewCols));
       if (!result.rows || result.rows.length === 0) {
         throw _err("LEASE_LOST",
           "lease for node '" + lease.nodeId + "' was taken over (renewal rejected)",
@@ -276,19 +306,15 @@ function create(config) {
     // Clear our row so the next acquire wins immediately. Match on
     // leaseId so a takeover-then-release race doesn't clear someone
     // else's lease.
-    var sql =
-      "UPDATE _blamejs_leader SET " +
-      "  expiresAt = 0 " +
-      "WHERE scope = 'leader' AND nodeId = " + _placeholder(1) +
-      "  AND leaseId = " + _placeholder(2);
-    await _q(sql, [lease.nodeId, lease.leaseId]);
+    await _run(sql().update(LEADER_TABLE, { dialect: dialect })
+      .set({ expiresAt: 0 })
+      .where("scope", "leader").where("nodeId", lease.nodeId).where("leaseId", lease.leaseId));
   }
 
   async function currentLeader() {
-    var result = await _q(
-      "SELECT nodeId, expiresAt, fencingToken, endpoint FROM _blamejs_leader " +
-      "WHERE scope = 'leader'"
-    );
+    var result = await _run(sql().select(LEADER_TABLE, { dialect: dialect })
+      .columns(["nodeId", "expiresAt", "fencingToken", "endpoint"])
+      .where("scope", "leader"));
     if (!result.rows || result.rows.length === 0) return null;
     var row = result.rows[0];
     if (Number(row.expiresAt) < Date.now()) return null;

package/lib/cluster-storage.js

@@ -74,6 +74,38 @@ function tableName(local) {
   return local;
 }
 
+/**
+ * @primitive b.clusterStorage.dialect
+ * @signature b.clusterStorage.dialect()
+ * @since     0.15.0
+ * @status    stable
+ * @related   b.clusterStorage.execute, b.cluster.dialect, b.frameworkSchema.ensureSchema
+ *
+ * Resolve the SQL dialect every framework-table data-layer file must pass
+ * to `b.sql` so the emitted SQL matches the active backend. In cluster
+ * mode it returns the operator-configured backend dialect (`"postgres"` |
+ * `"mysql"` | `"sqlite"`, set at `b.cluster.init`); in single-node mode
+ * the framework state lives in local node:sqlite, so it returns
+ * `"sqlite"`. This is the canonical dialect source for framework-state
+ * SQL — `b.sql` defaults to `"sqlite"` when no dialect is passed, which is
+ * correct only on the single-node path and on Postgres by accident (both
+ * double-quote identifiers); on MySQL the default would emit double-quoted
+ * identifiers MySQL reads as string literals, so framework-table SQL must
+ * thread this value explicitly.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var dialect = b.clusterStorage.dialect();
+ *   // → "sqlite"    (single-node)
+ *   // → "postgres"  (cluster mode, postgres backend)
+ *   // → "mysql"     (cluster mode, mysql backend)
+ *   var built = b.sql.select("_blamejs_cache", { dialect: dialect })
+ *     .where("cacheKey", "k").toSql();
+ */
+function dialect() {
+  return cluster.isClusterMode() ? cluster.dialect() : "sqlite";
+}
+
 // Precomputed rewrite table for resolveTables(). Built once at module
 // load from the static frozen frameworkSchema.LOCAL_TO_EXTERNAL mapping —
 // not from operator/request input. Order longest-first so prefix matches
@@ -127,7 +159,19 @@ function _replaceWordBoundaryAll(haystack, needle, replacement) {
   return out + haystack.slice(cursor);
 }
 
-var _REWRITE_TABLE = (function () {
+// Rewrite table for resolveTables(), derived from the static frozen
+// frameworkSchema.LOCAL_TO_EXTERNAL mapping — never from operator/request
+// input. The external names are PREFIX-AWARE: resolved through
+// frameworkSchema.tableName(local) so a configured framework-table prefix
+// (set config-time via db.init({tablePrefix})) is honored in cluster-mode
+// DML, matching the prefix the DDL builders created the tables under.
+// Order longest-first so prefix matches don't collide (audit_log before
+// audit). Entries that are identity under the CURRENT prefix are filtered
+// so the loop body has no no-op iterations — under the default prefix this
+// is byte-identical to the old local→external map (the already-prefixed
+// `_blamejs_*` names map to themselves and drop out); under a custom prefix
+// those same names rewrite to `<prefix>*` and stay in.
+function _buildRewriteTable() {
   var mapping = frameworkSchema.LOCAL_TO_EXTERNAL;
   var names = Object.keys(mapping).sort(function (a, b) {
     return b.length - a.length;
@@ -135,12 +179,28 @@ var _REWRITE_TABLE = (function () {
   var entries = [];
   for (var i = 0; i < names.length; i++) {
     var local = names[i];
-    var external = mapping[local];
-    if (local === external) continue;
+    var external = frameworkSchema.tableName(local);   // prefix-aware external name
+    if (local === external) continue;                  // no-op under the current prefix
     entries.push({ local: local, external: external });
   }
   return Object.freeze(entries);
-})();
+}
+
+var _REWRITE_TABLE = null;
+var _rewriteTablePrefix = null;
+
+// The rewrite table for the current framework-table prefix, rebuilt if the
+// prefix changed since the last build. db.init({tablePrefix}) sets the prefix
+// once at boot (config-time), so the rebuild fires at most once; the prefix
+// read is a cheap module-var getter, not request input.
+function _rewriteTable() {
+  var prefix = frameworkSchema.getTablePrefix();
+  if (_REWRITE_TABLE === null || prefix !== _rewriteTablePrefix) {
+    _REWRITE_TABLE = _buildRewriteTable();
+    _rewriteTablePrefix = prefix;
+  }
+  return _REWRITE_TABLE;
+}
 
 // Rewrite bare table names in SQL when running in cluster mode. We only
 // touch tokens that are exactly one of the framework's known table names
@@ -173,9 +233,10 @@ var _REWRITE_TABLE = (function () {
  */
 function resolveTables(sql) {
   if (!cluster.isClusterMode()) return sql;
+  var rewrite = _rewriteTable();
   var translated = sql;
-  for (var i = 0; i < _REWRITE_TABLE.length; i++) {
-    var entry = _REWRITE_TABLE[i];
+  for (var i = 0; i < rewrite.length; i++) {
+    var entry = rewrite[i];
     translated = _replaceWordBoundaryAll(translated, entry.local, entry.external);
   }
   return translated;
@@ -196,12 +257,16 @@ function resolveTables(sql) {
  * @related   b.clusterStorage.execute, b.cluster.dialect
  *
  * Translate `?` placeholders to numbered `$1`, `$2`, … form for
- * Postgres backends; passthrough for `"sqlite"` and `"mysql"`. The
- * walker skips question marks inside single-quoted string literals so
- * `WHERE s = '?'` is preserved verbatim. Doubled-quote escapes (`''`)
- * inside strings are recognized. The `execute` family calls this on
- * every cluster-mode dispatch; reach for it directly only when
- * shipping raw SQL through a non-`execute` driver path.
+ * Postgres backends; passthrough for `"sqlite"` and `"mysql"`. The walker
+ * skips a `?` inside a single-quoted string literal (`WHERE s = '?'`), a
+ * double-quoted or backtick-quoted identifier (`"c?l"`), and a `--` or
+ * block comment — so only a true bind marker is renumbered. This skip set
+ * is a SUPERSET of `b.safeSql.countPlaceholders`'s, so the count used to
+ * size params and the renumbering done here can never diverge (a `?` one
+ * scanner counts but the other rewrites would mis-align bound values).
+ * Doubled-quote escapes (`''` / `""`) inside their span are recognized.
+ * The `execute` family calls this on every cluster-mode dispatch; reach
+ * for it directly only when shipping raw SQL through a non-`execute` path.
  *
  * @example
  *   var b = require("@blamejs/core");
@@ -213,21 +278,41 @@ function resolveTables(sql) {
  */
 function placeholderize(sql, dialect) {
   if (dialect !== "postgres") return sql;
-  // Walk the SQL and replace `?` with $1, $2, … but skip ones inside
-  // single-quoted string literals.
   var out = "";
   var n = 0;
-  var inStr = false;
-  for (var i = 0; i < sql.length; i++) {
+  var i = 0;
+  var len = sql.length;
+  while (i < len) {
     var c = sql.charAt(i);
-    if (c === "'" && !inStr) { inStr = true;  out += c; continue; }
-    if (c === "'" &&  inStr) {
-      // Handle escaped '' inside string
-      if (sql.charAt(i + 1) === "'") { out += "''"; i += 1; continue; }
-      inStr = false; out += c; continue;
+    var nx = i + 1 < len ? sql.charAt(i + 1) : "";
+    // Quote contexts: ' string literal, " identifier, ` mysql identifier.
+    // A doubled quote escapes itself within the span.
+    if (c === "'" || c === '"' || c === "`") {
+      out += c;
+      i += 1;
+      while (i < len) {
+        var q = sql.charAt(i);
+        if (q === c) {
+          if (sql.charAt(i + 1) === c) { out += c + c; i += 2; continue; }
+          out += c; i += 1; break;
+        }
+        out += q; i += 1;
+      }
+      continue;
+    }
+    if (c === "-" && nx === "-") {                              // line comment
+      while (i < len && sql.charAt(i) !== "\n") { out += sql.charAt(i); i += 1; }
+      continue;
     }
-    if (!inStr && c === "?") { n += 1; out += "$" + n; continue; }
+    if (c === "/" && nx === "*") {                              // block comment
+      out += "/*"; i += 2;
+      while (i < len && !(sql.charAt(i) === "*" && sql.charAt(i + 1) === "/")) { out += sql.charAt(i); i += 1; }
+      if (i < len) { out += "*/"; i += 2; }
+      continue;
+    }
+    if (c === "?") { n += 1; out += "$" + n; i += 1; continue; }
     out += c;
+    i += 1;
   }
   return out;
 }
@@ -299,6 +384,17 @@ async function execute(sql, params) {
     var result = await externalDb.query(translated, params, {
       backend: cluster.externalDbBackend(),
     });
+    // Coerce backend-native types back to the framework's canonical JS shape
+    // for every clusterStorage reader at once: node-postgres returns BIGINT /
+    // int8 as a decimal string and BYTEA as a Buffer, so a framework column
+    // read back from Postgres would otherwise be the wrong JS type (a counter
+    // compared as a string, a hash/nonce mis-typed). coerceRows only touches
+    // columns in the framework's type map; operator columns pass through, and
+    // it is idempotent (already-correct types are left alone), so a reader
+    // that also coerces locally is unaffected.
+    if (result && Array.isArray(result.rows) && result.rows.length > 0) {
+      result.rows = frameworkSchema.coerceRows(result.rows);
+    }
     return result;
   }
 
@@ -449,6 +545,7 @@ module.exports = {
   executeAll:            executeAll,
   transaction:           transaction,
   tableName:             tableName,
+  dialect:               dialect,
   resolveTables:         resolveTables,
   placeholderize:        placeholderize,
   ClusterStorageError:   ClusterStorageError,