@quereus/quereus 4.11.0 → 4.12.0

package/dist/src/schema/schema-differ.js

@@ -89,7 +89,7 @@ function duplicateDeclaredNameError(dup, schemaName) {
         return new QuereusError(`'${name}' is declared as both a ${priorKind} and a ${kind} in schema '${schemaName}'`, StatusCode.ERROR);
     }
     if (kind === 'index') {
-        // Pinned wording — documented in docs/sql-ddl.md § 6.3 and SCH-001.
+        // Pinned wording — documented in docs/sql-vtab.md § 6.3 and SCH-001.
         return new QuereusError(`Index '${name}' is declared more than once in schema '${schemaName}'`
             + ` (on '${firstTable}' and '${secondTable}') — index names are unique per schema`, StatusCode.ERROR);
     }
@@ -386,7 +386,7 @@ defaultCollation = 'BINARY') {
                 // two names are identical.
                 const dropName = matchedActual.name.toLowerCase() !== name ? name : matchedActual.name.toLowerCase();
                 dropSet.add(dropName);
-                diff.tablesToCreate.push(renderFreshTableCreate(name, tableStmt, declaredMaterializedViews, targetSchemaName, defaultVtabModule, defaultVtabArgs));
+                diff.tablesToCreate.push(freshTableCreate(name, tableStmt, declaredMaterializedViews, targetSchemaName, defaultVtabModule, defaultVtabArgs));
                 diff.maintainedModuleMigrations.push({
                     name: tableStmt.table.name,
                     fromModule: alterDiff.maintainedModuleMigration.fromModule,
@@ -415,7 +415,7 @@ defaultCollation = 'BINARY') {
             }
         }
         else {
-            diff.tablesToCreate.push(renderFreshTableCreate(name, tableStmt, declaredMaterializedViews, targetSchemaName, defaultVtabModule, defaultVtabArgs));
+            diff.tablesToCreate.push(freshTableCreate(name, tableStmt, declaredMaterializedViews, targetSchemaName, defaultVtabModule, defaultVtabArgs));
         }
     }
     // Tables: drops (skip those consumed by a rename). The module-move drops added
@@ -459,7 +459,7 @@ defaultCollation = 'BINARY') {
     for (const [name, declaredView] of declaredViews) {
         const matchedActual = viewRenames.pairs.get(name);
         if (!matchedActual) {
-            diff.viewsToCreate.push(createViewToString(applyViewSchemaDefault(declaredView.viewStmt, targetSchemaName)));
+            diff.viewsToCreate.push(viewCreate(applyViewSchemaDefault(declaredView.viewStmt, targetSchemaName)));
             continue;
         }
         const stmt = declaredView.viewStmt;
@@ -478,7 +478,7 @@ defaultCollation = 'BINARY') {
         }
         if (definitionDrifted) {
             diff.viewsToDrop.push(matchedActual.name);
-            diff.viewsToCreate.push(createViewToString(applyViewSchemaDefault(stmt, targetSchemaName)));
+            diff.viewsToCreate.push(viewCreate(applyViewSchemaDefault(stmt, targetSchemaName)));
             viewRecreates++;
             continue;
         }
@@ -486,7 +486,7 @@ defaultCollation = 'BINARY') {
             // Hinted rename, definition unchanged → drop(old) + recreate(declared),
             // rendered with in-diff column renames inverse-applied (NEW→OLD).
             diff.viewsToDrop.push(matchedActual.name);
-            diff.viewsToCreate.push(createViewToString(applyViewSchemaDefault(columnReconciledViewStmt(stmt, columnRenamesByTable, targetSchemaName, resolveDeclaredColumn), targetSchemaName)));
+            diff.viewsToCreate.push(viewCreate(applyViewSchemaDefault(columnReconciledViewStmt(stmt, columnRenamesByTable, targetSchemaName, resolveDeclaredColumn), targetSchemaName)));
             viewRecreates++;
             continue;
         }
@@ -531,7 +531,7 @@ defaultCollation = 'BINARY') {
         const matchedActual = indexRenames.pairs.get(name);
         if (!matchedActual) {
             const effectiveStmt = applyIndexDefaults(declaredIndex.indexStmt, targetSchemaName);
-            diff.indexesToCreate.push(createIndexToString(effectiveStmt));
+            diff.indexesToCreate.push(indexCreate(effectiveStmt));
             continue;
         }
         // Body comparison (canonical: name / tags excluded; per-column collation
@@ -559,7 +559,7 @@ defaultCollation = 'BINARY') {
         if (declaredBody !== matchedActual.definition) {
             diff.indexesToDrop.push(matchedActual.name);
             const effectiveStmt = applyIndexDefaults(declaredIndex.indexStmt, targetSchemaName);
-            diff.indexesToCreate.push(createIndexToString(effectiveStmt));
+            diff.indexesToCreate.push(indexCreate(effectiveStmt));
             indexRecreates++;
             continue;
         }
@@ -568,7 +568,7 @@ defaultCollation = 'BINARY') {
             // rendered with in-diff column renames inverse-applied (NEW→OLD).
             diff.indexesToDrop.push(matchedActual.name);
             const reconciledStmt = columnReconciledIndexStmt(declaredIndex.indexStmt, indexColRenames, columnRenamesByTable, targetSchemaName);
-            diff.indexesToCreate.push(createIndexToString(applyIndexDefaults(reconciledStmt, targetSchemaName)));
+            diff.indexesToCreate.push(indexCreate(applyIndexDefaults(reconciledStmt, targetSchemaName)));
             indexRecreates++;
             continue;
         }
@@ -666,7 +666,7 @@ defaultCollation = 'BINARY') {
         // `generateMigrationDDL`), then recreate from the declaration.
         if (matchedActual)
             diff.assertionsToDrop.push(matchedActual.name);
-        diff.assertionsToCreate.push(createAssertionToString(applyAssertionSchemaDefault(declaredAssertion.assertionStmt, targetSchemaName)));
+        diff.assertionsToCreate.push(assertionCreate(applyAssertionSchemaDefault(declaredAssertion.assertionStmt, targetSchemaName)));
     }
     for (const [name] of actualAssertions) {
         if (!declaredAssertions.has(name)) {
@@ -817,21 +817,43 @@ function enforceRequireHint(kind, creates, drops) {
     }
 }
 /**
- * Renders the fresh-create DDL for a declared table — shared by the create branch
+ * Builds the fresh-create step for a declared table — shared by the create branch
  * and the destructive backing-module move's recreate, so both re-materialize a
  * maintained body into the declared module through one renderer. A maintained
  * table declared via the `materialized view` sugar renders that sugar (its
  * column-less normalized table form has no parseable `create table` DDL); a
  * declared-shape maintained table and a plain table render the `create table …`
  * form (carrying any `maintained as` clause).
+ *
+ * The returned {@link MigrationCreate} pairs the rendered text with the SAME
+ * post-qualification statement it was rendered from, so `apply schema` executes
+ * exactly what `diff schema` previews.
  */
-function renderFreshTableCreate(name, tableStmt, declaredMaterializedViews, targetSchemaName, defaultVtabModule, defaultVtabArgs) {
+function freshTableCreate(name, tableStmt, declaredMaterializedViews, targetSchemaName, defaultVtabModule, defaultVtabArgs) {
     const declaredMv = declaredMaterializedViews.get(name);
     if (declaredMv) {
-        return createMaterializedViewToString(applyViewSchemaDefault(declaredMv.viewStmt, targetSchemaName));
+        const mvStmt = applyViewSchemaDefault(declaredMv.viewStmt, targetSchemaName);
+        return { sql: createMaterializedViewToString(mvStmt), ast: mvStmt };
     }
     const effectiveStmt = applyTableDefaults(tableStmt, targetSchemaName, defaultVtabModule, defaultVtabArgs);
-    return createTableToString(effectiveStmt);
+    return { sql: createTableToString(effectiveStmt), ast: effectiveStmt };
+}
+/**
+ * Pairs a view create's rendered DDL with the exact (already schema-qualified,
+ * already rename-reconciled) statement it was rendered from. Taking one statement
+ * and rendering it here — rather than accepting a pre-rendered string — is what
+ * makes text/AST disagreement unrepresentable.
+ */
+function viewCreate(stmt) {
+    return { sql: createViewToString(stmt), ast: stmt };
+}
+/** The index analogue of {@link viewCreate}. */
+function indexCreate(stmt) {
+    return { sql: createIndexToString(stmt), ast: stmt };
+}
+/** The assertion analogue of {@link viewCreate}. */
+function assertionCreate(stmt) {
+    return { sql: createAssertionToString(stmt), ast: stmt };
 }
 /**
  * Qualifies a view / materialized-view create statement's own name with the
@@ -2227,6 +2249,12 @@ function computeColumnAttributeChange(declared, actual, defaultCollation) {
         change.defaultValue = null;
         any = true;
     }
+    // The retype refuses to carry an unconvertible existing default across; when this
+    // migration replaces that default anyway, clear it ahead of the retype. See
+    // `dropStaleDefaultFirst`.
+    if (change.dataType !== undefined && change.defaultValue !== undefined && actualDefault !== null) {
+        change.dropStaleDefaultFirst = true;
+    }
     // Collation — declared COLLATE (default BINARY) vs actual, case-insensitive.
     // Absent and BINARY are equal, so a column that never mentions COLLATE never
     // churns a diff against an actual BINARY column.
@@ -2284,7 +2312,13 @@ function pkSequencesEqual(declared, actual) {
     return true;
 }
 /**
- * Serializes a schema diff to JSON string
+ * Serializes a schema diff to JSON string.
+ *
+ * NOTE: the four create buckets serialize as `{ sql, ast }` objects (see
+ * {@link MigrationCreate}), so the output embeds a full statement AST per create
+ * and is far more verbose than the old bare-string form. No caller in the repo
+ * consumes this today; a caller that only wants the DDL should read `.sql` (or
+ * call {@link generateMigrationDDL}) rather than this whole-diff dump.
  */
 export function serializeSchemaDiff(diff) {
     return JSON.stringify(diff, null, 2);
@@ -2344,11 +2378,30 @@ function comparisonDomainAlters(quotedTable, quotedCol, change) {
         : [...retype, ...recollate];
 }
 /**
- * Generates migration DDL statements from a schema diff
+ * Generates migration DDL statements from a schema diff.
+ *
+ * Thin wrapper over {@link generateMigrationPlan} — the single ordering authority.
+ * `diff schema` previews exactly this text, and `apply schema` executes the plan
+ * these strings come from, so the two can never disagree.
  */
 export function generateMigrationDDL(diff, schemaName) {
+    return generateMigrationPlan(diff, schemaName).map(s => s.sql);
+}
+/**
+ * Builds the ordered migration plan for a schema diff.
+ *
+ * Every step carries its `sql` (the preview text, and the text an execution error
+ * names). Steps built from a statement AST — the four create buckets and the
+ * `set maintained as` re-attach — also carry that AST, so `apply schema` can run
+ * them without re-lexing the text this function just produced. The remaining steps
+ * are short template-built strings (renames, drops, column/constraint alters,
+ * `SET TAGS`) and stay text-only.
+ */
+export function generateMigrationPlan(diff, schemaName) {
     const statements = [];
     const schemaPrefix = (schemaName && schemaName !== 'main') ? `${quoteIdentifier(schemaName)}.` : '';
+    /** Appends a template-built step — text-only, so the apply path parses it as before. */
+    const pushText = (sql) => { statements.push({ sql }); };
     // Renames first — they free old names for subsequent creates and re-target
     // dependents (handled inside ALTER TABLE ... RENAME by the rename rewriter).
     // Only tables have a rename primitive. The other RenameOp kinds are metadata
@@ -2359,13 +2412,13 @@ export function generateMigrationDDL(diff, schemaName) {
     // the table-alter channel (RENAME CONSTRAINT below).
     for (const r of diff.renames) {
         if (r.kind === 'table') {
-            statements.push(`ALTER TABLE ${schemaPrefix}${quoteIdentifier(r.oldName)} RENAME TO ${quoteIdentifier(r.newName)}`);
+            pushText(`ALTER TABLE ${schemaPrefix}${quoteIdentifier(r.oldName)} RENAME TO ${quoteIdentifier(r.newName)}`);
         }
         // Non-table rename ops emit no DDL here — see the note above.
     }
     // Drop assertions first (they may reference tables)
     for (const name of diff.assertionsToDrop) {
-        statements.push(`DROP ASSERTION IF EXISTS ${schemaPrefix}${quoteIdentifier(name)}`);
+        pushText(`DROP ASSERTION IF EXISTS ${schemaPrefix}${quoteIdentifier(name)}`);
     }
     // Detach maintained tables (`drop maintained`) EARLY — where MV drops ran
     // before — so a detach precedes any column op on that table AND any drop of its
@@ -2374,18 +2427,18 @@ export function generateMigrationDDL(diff, schemaName) {
     // flip's cross-table detach-v2 / attach-v1 pair falls out of this ordering.
     for (const alter of diff.tablesToAlter) {
         if (alter.dropMaintained) {
-            statements.push(`ALTER TABLE ${schemaPrefix}${quoteIdentifier(alter.tableName)} DROP MAINTAINED`);
+            pushText(`ALTER TABLE ${schemaPrefix}${quoteIdentifier(alter.tableName)} DROP MAINTAINED`);
         }
     }
     // Drop items (reverse order)
     for (const tableName of diff.tablesToDrop) {
-        statements.push(`DROP TABLE IF EXISTS ${schemaPrefix}${quoteIdentifier(tableName)}`);
+        pushText(`DROP TABLE IF EXISTS ${schemaPrefix}${quoteIdentifier(tableName)}`);
     }
     for (const viewName of diff.viewsToDrop) {
-        statements.push(`DROP VIEW IF EXISTS ${schemaPrefix}${quoteIdentifier(viewName)}`);
+        pushText(`DROP VIEW IF EXISTS ${schemaPrefix}${quoteIdentifier(viewName)}`);
     }
     for (const indexName of diff.indexesToDrop) {
-        statements.push(`DROP INDEX IF EXISTS ${schemaPrefix}${quoteIdentifier(indexName)}`);
+        pushText(`DROP INDEX IF EXISTS ${schemaPrefix}${quoteIdentifier(indexName)}`);
     }
     // Create new items. A fresh maintained table rides `tablesToCreate` (rendered
     // as the `create materialized view` sugar) and re-materializes as part of its
@@ -2401,7 +2454,9 @@ export function generateMigrationDDL(diff, schemaName) {
     //   → ADD COLUMN
     //   → ALTER COLUMN (comparison domain, then default, then nullability — so SET
     //     NOT NULL can rely on an already-populated DEFAULT for backfill; the
-    //     type/collation pair orders internally, see comparisonDomainAlters)
+    //     type/collation pair orders internally, see comparisonDomainAlters; a
+    //     retype whose replaced default would veto it is preceded by a DROP DEFAULT,
+    //     see dropStaleDefaultFirst)
     //   → RENAME CONSTRAINT, then DROP CONSTRAINT (free / remove a name before any
     //     re-add; a UNIQUE drop precedes the PK change so it can't strand a PK dep)
     //   → ALTER PRIMARY KEY
@@ -2410,26 +2465,35 @@ export function generateMigrationDDL(diff, schemaName) {
     for (const alter of diff.tablesToAlter) {
         const quotedTable = `${schemaPrefix}${quoteIdentifier(alter.tableName)}`;
         for (const r of alter.columnsToRename) {
-            statements.push(`ALTER TABLE ${quotedTable} RENAME COLUMN ${quoteIdentifier(r.oldName)} TO ${quoteIdentifier(r.newName)}`);
+            pushText(`ALTER TABLE ${quotedTable} RENAME COLUMN ${quoteIdentifier(r.oldName)} TO ${quoteIdentifier(r.newName)}`);
         }
         for (const colDef of alter.columnsToAdd) {
-            statements.push(`ALTER TABLE ${quotedTable} ADD COLUMN ${colDef}`);
+            pushText(`ALTER TABLE ${quotedTable} ADD COLUMN ${colDef}`);
         }
         for (const colAlter of alter.columnsToAlter) {
             const quotedCol = quoteIdentifier(colAlter.columnName);
+            // A default the retype would choke on and this migration replaces anyway is
+            // cleared BEFORE the comparison-domain phase (see `dropStaleDefaultFirst`).
+            if (colAlter.dropStaleDefaultFirst) {
+                pushText(`ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedCol} DROP DEFAULT`);
+            }
             // SET DATA TYPE / SET COLLATE lead the per-column phase (both are
             // comparison-domain changes), before DEFAULT / NOT NULL.
-            statements.push(...comparisonDomainAlters(quotedTable, quotedCol, colAlter));
+            for (const s of comparisonDomainAlters(quotedTable, quotedCol, colAlter))
+                pushText(s);
             if (colAlter.defaultValue !== undefined) {
                 if (colAlter.defaultValue === null) {
-                    statements.push(`ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedCol} DROP DEFAULT`);
+                    // Already dropped above when it preceded the retype.
+                    if (!colAlter.dropStaleDefaultFirst) {
+                        pushText(`ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedCol} DROP DEFAULT`);
+                    }
                 }
                 else {
-                    statements.push(`ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedCol} SET DEFAULT ${expressionToString(colAlter.defaultValue)}`);
+                    pushText(`ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedCol} SET DEFAULT ${expressionToString(colAlter.defaultValue)}`);
                 }
             }
             if (colAlter.notNull !== undefined) {
-                statements.push(colAlter.notNull
+                pushText(colAlter.notNull
                     ? `ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedCol} SET NOT NULL`
                     : `ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedCol} DROP NOT NULL`);
             }
@@ -2438,10 +2502,10 @@ export function generateMigrationDDL(diff, schemaName) {
         // conflicting constraint), both BEFORE re-adds and before the PK change so a
         // dropped UNIQUE can't strand a PK dependency.
         for (const r of alter.constraintsToRename ?? []) {
-            statements.push(`ALTER TABLE ${quotedTable} RENAME CONSTRAINT ${quoteIdentifier(r.oldName)} TO ${quoteIdentifier(r.newName)}`);
+            pushText(`ALTER TABLE ${quotedTable} RENAME CONSTRAINT ${quoteIdentifier(r.oldName)} TO ${quoteIdentifier(r.newName)}`);
         }
         for (const name of alter.constraintsToDrop ?? []) {
-            statements.push(`ALTER TABLE ${quotedTable} DROP CONSTRAINT ${quoteIdentifier(name)}`);
+            pushText(`ALTER TABLE ${quotedTable} DROP CONSTRAINT ${quoteIdentifier(name)}`);
         }
         if (alter.primaryKeyChange) {
             const pkCols = alter.primaryKeyChange.newPkColumns
@@ -2452,16 +2516,16 @@ export function generateMigrationDDL(diff, schemaName) {
                 return s;
             })
                 .join(', ');
-            statements.push(`ALTER TABLE ${quotedTable} ALTER PRIMARY KEY (${pkCols})`);
+            pushText(`ALTER TABLE ${quotedTable} ALTER PRIMARY KEY (${pkCols})`);
         }
         // ADD CONSTRAINT after the PK change (a new UNIQUE / FK may align with the new
         // key) and after the column adds it may reference. CHECK adds apply in-place;
         // UNIQUE / FK adds depend on module ADD CONSTRAINT support (see constraintsToAdd).
         for (const frag of alter.constraintsToAdd ?? []) {
-            statements.push(`ALTER TABLE ${quotedTable} ADD ${frag}`);
+            pushText(`ALTER TABLE ${quotedTable} ADD ${frag}`);
         }
         for (const colName of alter.columnsToDrop) {
-            statements.push(`ALTER TABLE ${quotedTable} DROP COLUMN ${quoteIdentifier(colName)}`);
+            pushText(`ALTER TABLE ${quotedTable} DROP COLUMN ${quoteIdentifier(colName)}`);
         }
         // Tags phase — last, so a SET TAGS lands on the post-structural column /
         // constraint set (a tag set emitted alongside a RENAME COLUMN targets the
@@ -2472,23 +2536,25 @@ export function generateMigrationDDL(diff, schemaName) {
             // TABLE handler rejects a tag action on a maintained table). See
             // `TableAlterDiff.maintainedTags`.
             const tagVerb = alter.maintainedTags ? 'ALTER MATERIALIZED VIEW' : 'ALTER TABLE';
-            statements.push(`${tagVerb} ${quotedTable} SET TAGS ${tagsBodyToString(alter.tableTagsChange)}`);
+            pushText(`${tagVerb} ${quotedTable} SET TAGS ${tagsBodyToString(alter.tableTagsChange)}`);
         }
         for (const colAlter of alter.columnsToAlter) {
             if (colAlter.tags === undefined)
                 continue;
-            statements.push(`ALTER TABLE ${quotedTable} ALTER COLUMN ${quoteIdentifier(colAlter.columnName)} SET TAGS ${tagsBodyToString(colAlter.tags)}`);
+            pushText(`ALTER TABLE ${quotedTable} ALTER COLUMN ${quoteIdentifier(colAlter.columnName)} SET TAGS ${tagsBodyToString(colAlter.tags)}`);
         }
         for (const ctc of alter.constraintTagsChanges ?? []) {
-            statements.push(`ALTER TABLE ${quotedTable} ALTER CONSTRAINT ${quoteIdentifier(ctc.constraintName)} SET TAGS ${tagsBodyToString(ctc.tags)}`);
+            pushText(`ALTER TABLE ${quotedTable} ALTER CONSTRAINT ${quoteIdentifier(ctc.constraintName)} SET TAGS ${tagsBodyToString(ctc.tags)}`);
         }
     }
     // Attach / re-attach maintained tables (`set maintained as`) LATE — where MV
     // creates ran — after every table create/alter, so the target's final shape and
     // the body's sources already exist (and any reshape leg's `drop maintained` +
     // column ops have run). A same-shape re-attach reconciles content in place (a
-    // refresh, not a recreate). Rendered via `astToString` over a synthetic
-    // `set maintained as` action so the body QueryExpr round-trips exactly.
+    // refresh, not a recreate). Built as a synthetic `set maintained as` action and
+    // rendered via `astToString`, so the body QueryExpr round-trips exactly — and
+    // carried on the step so `apply schema` executes that statement rather than
+    // re-parsing the render.
     for (const alter of diff.tablesToAlter) {
         if (!alter.setMaintained)
             continue;
@@ -2506,7 +2572,7 @@ export function generateMigrationDDL(diff, schemaName) {
                 select: alter.setMaintained.select,
             },
         };
-        statements.push(astToString(stmt));
+        statements.push({ sql: astToString(stmt), ast: stmt });
     }
     // Assertion creates LAST — after every table alter and maintained re-attach, so
     // a body sees the final shape of every object. `CREATE ASSERTION` plans its
@@ -2523,10 +2589,10 @@ export function generateMigrationDDL(diff, schemaName) {
     // table's tag-only change rides the table-alter block above (`SET TAGS`), not a
     // separate bucket.
     for (const vtc of diff.viewTagsChanges ?? []) {
-        statements.push(`ALTER VIEW ${schemaPrefix}${quoteIdentifier(vtc.name)} SET TAGS ${tagsBodyToString(vtc.tags)}`);
+        pushText(`ALTER VIEW ${schemaPrefix}${quoteIdentifier(vtc.name)} SET TAGS ${tagsBodyToString(vtc.tags)}`);
     }
     for (const itc of diff.indexTagsChanges ?? []) {
-        statements.push(`ALTER INDEX ${schemaPrefix}${quoteIdentifier(itc.name)} SET TAGS ${tagsBodyToString(itc.tags)}`);
+        pushText(`ALTER INDEX ${schemaPrefix}${quoteIdentifier(itc.name)} SET TAGS ${tagsBodyToString(itc.tags)}`);
     }
     return statements;
 }