@quereus/quereus 4.4.1 → 4.5.0

package/dist/src/vtab/memory/layer/manager.js

@@ -8,7 +8,7 @@ import { MemoryTableConnection } from './connection.js';
 import { MemoryVirtualTableConnection } from '../connection.js';
 import { QuereusError } from '../../../common/errors.js';
 import { ConflictResolution } from '../../../common/constants.js';
-import { buildUniqueConstraintSchema, buildForeignKeyConstraintSchema, buildCheckConstraintSchema, validateForeignKeyOverExistingRows, maintainedTableUniqueViolationError } from '../../../schema/constraint-builder.js';
+import { buildUniqueConstraintSchema, buildForeignKeyConstraintSchema, buildCheckConstraintSchema, validateForeignKeyOverExistingRows, maintainedTableUniqueViolationError, formatKeyValue } from '../../../schema/constraint-builder.js';
 import { indexEnforcesUnique, uniqueEnforcementCollations, uniqueEnforcementComparators } from '../../../schema/unique-enforcement.js';
 import { generateIndexDDL, generateDropIndexDDL } from '../../../schema/ddl-generator.js';
 import { compareSqlValues, rowsValueIdentical, normalizeCollationName, comparisonSemanticsDiffer } from '../../../util/comparison.js';
@@ -1974,8 +1974,15 @@ export class MemoryTableManager {
      * Apply a single-attribute ALTER COLUMN change (NOT NULL, DEFAULT, DATA TYPE).
      * The caller supplies exactly one populated change; multi-attribute combinations
      * are rejected by the runtime before reaching this method.
+     *
+     * `validateOnly` runs everything up to (and including) the pre-mutation validation
+     * passes — the effective-row NULL / conversion scans, the re-keyed UNIQUE probe, and
+     * the primary-key re-key legality/representability passes — and returns before the
+     * first mutation, throwing exactly what the real application would throw. The
+     * isolation layer uses it to pre-flight an overlay's migration before the shared
+     * underlying table mutates irreversibly (see `VirtualTable.alterSchema`).
      */
-    async alterColumn(change, rows) {
+    async alterColumn(change, rows, validateOnly = false) {
         if (this.isReadOnly)
             throw new QuereusError(`Table '${this._tableName}' is read-only`, StatusCode.READONLY);
         const lockKey = `MemoryTable.SchemaChange:${this.schemaName}.${this._tableName}`;
@@ -2246,17 +2253,19 @@ export class MemoryTableManager {
             }
             else if (structuresRekeyed) {
                 await this.validateRekeyedUniqueStructures(finalNewTableSchema, colIndex, rows);
-                // NOTE: `validateRekeyedPrimaryKey` deliberately ignores `rows`. It asserts that no
-                // LAYER of this manager's own chain holds a PK collision under the new comparator —
-                // a physical property of the structures it is about to re-key, which a wrapper's
-                // merged row stream cannot speak to. A wrapper's staged rows live in the wrapper's
-                // own overlay, which enforces the PK itself, so the pair "one staged row + one
-                // committed row that collide only under the new collation" is checked by neither
-                // side. Rejecting it here would need the wrapper to expose its overlay's PK set, not
-                // just its merged rows.
+                // Unlike the secondary-structure pass above — which only ever judges the effective
+                // rows — the PK pass judges TWO row sets: the effective rows (`rows` when a wrapper
+                // supplies them) decide whether the change is LEGAL, and this manager's own layer
+                // chain decides whether the re-keyed trees can PHYSICALLY carry it. See
+                // `validateRekeyedPrimaryKey` for why the sets differ and which status each raises.
                 if (pkColumnRekeyed)
-                    this.validateRekeyedPrimaryKey(finalNewTableSchema);
+                    await this.validateRekeyedPrimaryKey(finalNewTableSchema, rows);
             }
+            // Dry run ends here: everything above validates without mutating (the one earlier
+            // side effect, ensureSchemaChangeSafety's committed-layer drain, is semantically
+            // neutral bookkeeping), and everything below mutates. See the method doc.
+            if (validateOnly)
+                return;
             this.baseLayer.updateSchema(finalNewTableSchema);
             // Both arms rebuild the base's structures under the schema `updateSchema` above just
             // swapped in — each MemoryIndex rebuilds its comparator from the CURRENT schema's
@@ -3116,21 +3125,35 @@ export class MemoryTableManager {
      * PRIMARY KEY arm of the `alter column … set collate` pre-pass. Runs before anything is
      * mutated, so a rejection leaves the table, the schema and the transaction untouched.
      *
-     * The primary tree is a map, not a multi-map, so — unlike a secondary index — it cannot
-     * physically hold two rows whose keys collapse under the new comparator. Every layer the
-     * DDL connection still reads through therefore has to be collision-free, not just the
-     * transaction's effective view:
+     * Asks two questions, in order, over two DIFFERENT row sets:
+     *
+     *  1. **Is the change legal at all?** — probes the rows the DDL transaction can SEE: the
+     *     wrapper-supplied `rows` when a wrapper module (the isolation layer) holds the
+     *     transaction's pending rows outside this manager, otherwise this manager's own
+     *     layered view ({@link effectiveDdlRows}). A duplicate here is visible to a `select`
+     *     in this transaction, so the change is simply illegal → `CONSTRAINT`, naming the
+     *     colliding key.
+     *  2. **Can the structures physically carry it?** — probes every layer of this manager's
+     *     own chain. The primary tree is a map, not a multi-map, so — unlike a secondary
+     *     index — no tree that a `rollback` / `rollback to savepoint` could restore may hold
+     *     two rows whose keys collapse under the new comparator. A collision confined to
+     *     committed rows the transaction has DELETED is therefore refused by physical
+     *     necessity, not because the data is invalid: the base must keep both rows for a
+     *     rollback, and a base re-keyed under the new collation could not represent the pair
+     *     at all → `BUSY` with the same "commit/rollback and retry" posture as
+     *     {@link ensureSchemaChangeSafety}. The persistent store backend refuses the same
+     *     shape for the same reason (its committed rows equally survive a rollback — see
+     *     `backlog/bug-store-pk-collate-rejects-deleted-row-collision`); accepting it would
+     *     take transaction-scoped DDL (`backlog/feat-transactional-ddl-native-backends`),
+     *     which Quereus does not have.
      *
-     *  1. **The effective view collides** → `CONSTRAINT`. The duplicate is visible to a `select`
-     *     in this transaction; the change is simply illegal.
-     *  2. **A layer beneath it collides** → `BUSY`. Those rows are not visible now, but every
-     *     such layer is the copy-on-write base the view reads through, and one of them may be a
-     *     savepoint snapshot a `rollback to savepoint` must restore. A re-keyed tree could not
-     *     represent the pair at all. Committing (or rolling back) settles the transaction and
-     *     the ALTER can be retried — the same "commit/rollback and retry" posture as
-     *     {@link ensureSchemaChangeSafety}.
+     * The passes judge different sets because a wrapper's effective stream and this manager's
+     * layers genuinely diverge: staged inserts exist only in the stream, deleted committed
+     * rows only in the layers. When `rows` is supplied, the view layer holds the COMMITTED
+     * rows — not a subset of what pass 1 judged — so pass 2 starts AT the view; when `rows`
+     * is absent, pass 1 judged exactly the view's rows and pass 2 starts at its parent.
      *
-     * Case 2 is deliberately conservative. The chain holds one immutable layer per statement
+     * Pass 2 is deliberately conservative. The chain holds one immutable layer per statement
      * boundary (see `MemoryTableConnection.createSavepoint`'s eager path), so it rejects any
      * transaction that has held a colliding pair at ANY statement boundary — even one whose
      * final view is clean and whose intermediate layer no savepoint can reach. Narrowing that
@@ -3142,40 +3165,78 @@ export class MemoryTableManager {
      * with no collisions anywhere in the chain, every primary key resolves to at most one row
      * in each layer under the new comparator.
      */
-    validateRekeyedPrimaryKey(newSchema) {
+    async validateRekeyedPrimaryKey(newSchema, rows) {
         const newPkFunctions = createPrimaryKeyFunctions(newSchema, this.collationResolver);
         const connection = this.ddlConnection();
         const view = connection
             ? (connection.pendingTransactionLayer ?? connection.readLayer)
             : this.baseLayer;
-        this.assertNoPrimaryKeyCollision(view, newPkFunctions, StatusCode.CONSTRAINT, `UNIQUE constraint failed: ${this._tableName} primary key collides under new collation`);
+        await this.assertNoPrimaryKeyCollisionInRows(rows ? rows() : this.effectiveDdlRows(), newPkFunctions, primaryKeyArity(newSchema) !== 1);
         // `ensureSchemaChangeSafety` has already drained every committed layer into the base and
-        // rejected sibling connections with open work, so the chain below the view holds only
-        // this transaction's own layers.
-        for (let layer = view.getParent(); layer; layer = layer.getParent()) {
-            this.assertNoPrimaryKeyCollision(layer, newPkFunctions, StatusCode.BUSY, `Cannot change the collation of a primary key column of table ${this._tableName}: `
-                + `rows this transaction has removed still collide under the new collation and must survive a rollback. `
-                + `Commit/rollback and retry.`);
+        // rejected sibling connections with open work, so this walk covers the transaction's own
+        // layers plus the base — every tree a rollback could restore.
+        for (let layer = rows ? view : view.getParent(); layer; layer = layer.getParent()) {
+            this.assertNoPrimaryKeyCollisionInLayer(layer, newPkFunctions);
         }
     }
     /**
-     * Raises `code` when two of `layer`'s rows share a primary key under `pkFunctions`.
+     * A duplicate-key detector over the new primary key functions: feed it rows, and it returns
+     * the key the moment one repeats. Shared by both arms of {@link validateRekeyedPrimaryKey}
+     * so the async (effective-row) arm and the sync (layer-tree) arm cannot disagree about what
+     * counts as a collision.
+     *
+     * NOTE: the probe holds every row it has seen, because the BTree derives its key from the
+     * stored value — so an ALTER over a large table transiently doubles that table's row
+     * references. If a wide table ever makes this the memory peak, key the probe by the PK
+     * encoding (`primaryKeyFunctions.encode`) into a `Set` instead of by the row.
+     */
+    makePrimaryKeyProbe(pkFunctions) {
+        const probe = new BTree((row) => pkFunctions.extractFromRow(row), pkFunctions.compare);
+        return (row) => {
+            const key = pkFunctions.extractFromRow(row);
+            if (probe.get(key) !== undefined)
+                return key;
+            probe.insert(row);
+            return undefined;
+        };
+    }
+    /**
+     * Legality arm of {@link validateRekeyedPrimaryKey}: raises `CONSTRAINT`, naming the key,
+     * when two of the rows the DDL transaction can SEE share a primary key under `pkFunctions`.
+     * Takes a wrapper's merged async stream or this manager's own synchronous layered view.
+     */
+    async assertNoPrimaryKeyCollisionInRows(rows, pkFunctions, keyIsTuple) {
+        const seen = this.makePrimaryKeyProbe(pkFunctions);
+        for await (const row of rows) {
+            const key = seen(row);
+            if (key === undefined)
+                continue;
+            const keyDesc = keyParts(key, keyIsTuple).map(formatKeyValue).join(', ');
+            throw new QuereusError(`UNIQUE constraint failed: ${this._tableName} primary key collides under new collation (key: ${keyDesc})`, StatusCode.CONSTRAINT);
+        }
+    }
+    /**
+     * Representability arm of {@link validateRekeyedPrimaryKey}: raises `BUSY` when two of
+     * `layer`'s physical rows share a primary key under `pkFunctions`. Its rows are ones a
+     * rollback could restore, not ones the transaction can see, so this is never a statement
+     * about the data's validity — hence the retryable status and wording.
      *
      * NOTE: O(rows) per layer, so O(layers × rows) for a whole chain — one more full pass than
      * the base rebuild the caller is about to do anyway. Fine for a statement this rare; if a
      * deep savepoint stack over a large table ever makes an ALTER slow, note that a layer's rows
      * differ from its parent's only at the keys it wrote, so the walk can be narrowed to those.
      */
-    assertNoPrimaryKeyCollision(layer, pkFunctions, code, message) {
+    assertNoPrimaryKeyCollisionInLayer(layer, pkFunctions) {
         const tree = layer.getModificationTree('primary');
         if (!tree)
             return;
-        const probe = new BTree((row) => pkFunctions.extractFromRow(row), pkFunctions.compare);
+        const seen = this.makePrimaryKeyProbe(pkFunctions);
         for (const row of iteratePrimaryRows(tree)) {
-            const key = pkFunctions.extractFromRow(row);
-            if (probe.get(key) !== undefined)
-                throw new QuereusError(message, code);
-            probe.insert(row);
+            if (seen(row) !== undefined) {
+                throw new QuereusError(`Cannot change the collation of a primary key column of table ${this._tableName}: `
+                    + `rows this transaction has removed still collide under the new collation and must survive a rollback. `
+                    + `Commit/rollback and retry.`, StatusCode.BUSY);
+            }
         }
     }
     /**