@happyvertical/smrt-core 0.51.11 → 0.51.16

package/dist/migrations/differ.d.ts

@@ -1,5 +1,10 @@
-import { SchemaChange, SchemaDefinition, SchemaDiff, SQLDataType } from '../schema/types.js';
+import { ColumnDefinition, SchemaChange, SchemaDefinition, SchemaDiff, SQLDataType } from '../schema/types.js';
 import { DatabaseInterface } from './types.js';
+/**
+ * `mismatch.actual` of the manual change reported when a required column
+ * could not be added to a populated table (#3008): the column is absent.
+ */
+export declare const REQUIRED_COLUMN_NOT_ADDED = "(column not added)";
 /**
  * Options for schema comparison
  */
@@ -153,6 +158,13 @@ export declare class SchemaComparer {
      * re-reading `getTableSchema` per relationship would multiply catalog
      * round-trips on a wide schema.
      */
+    /**
+     * #3008: indexes planned earlier in this table's batch (DuckDB unique
+     * follow-ups), which a later `SET NOT NULL` must also drop and recreate.
+     */
+    private batchIndexes;
+    /** #3008: per-table single-column unique targets, set by compareTable. */
+    private uniqueTargets;
     private liveSchemas;
     /** Convergence plan for this run; `null` on non-PostgreSQL engines. */
     private uuidConvergence;
@@ -654,11 +666,15 @@ export declare class SchemaComparer {
      * - `NOT NULL` with a default: inline on SQLite/PostgreSQL (existing rows
      *   receive the default); DuckDB adds with `DEFAULT` then a separate
      *   `ALTER COLUMN ... SET NOT NULL`.
-     * - `NOT NULL` without a default: enforced only when the table is empty
+     * - `NOT NULL` without a default: enforced inline when the table is empty
      *   (inline on SQLite/PostgreSQL, `SET NOT NULL` step on DuckDB). On a
-     *   populated table there is nothing to backfill with, so the column is
-     *   added nullable and a manual `alter_column` (`set_not_null`) is reported
-     *   with the exact remediation instead of emitting DDL every engine rejects.
+     *   populated table it needs a declared per-row `backfill` (#3008): add
+     *   nullable, `UPDATE` from the backfill, then `SET NOT NULL` (SQLite: a
+     *   table rebuild). Without one — or when the backfill yields NULL or does
+     *   not evaluate — the column is NOT added and a manual `alter_column`
+     *   (`mismatch.actual === REQUIRED_COLUMN_NOT_ADDED`) names it.
+     * - A backfill also wins over a declared default for existing rows; the
+     *   default is then set after the fill, for future inserts only.
      * - `UNIQUE`: inline on PostgreSQL (a real constraint); SQLite/DuckDB get a
      *   separate `CREATE UNIQUE INDEX <table>_<col>_key` (the PostgreSQL
      *   constraint-index name, so the orphan sweep leaves it alone).
@@ -670,6 +686,49 @@ export declare class SchemaComparer {
      * orchestrator execute it as one unit.
      */
     private generateAddColumnChanges;
+    /**
+     * #3008: fill a column's NULLs from its declared per-row backfill, then
+     * enforce NOT NULL (PostgreSQL/DuckDB; SQLite goes through a table
+     * rebuild). {@link probeBackfill} has already checked, at plan time, that
+     * the expression yields a value for every row; should a row written after
+     * that still produce NULL, `SET NOT NULL` fails and the whole migration
+     * unit rolls back.
+     */
+    private backfillStatements;
+    /**
+     * #3008: evaluate a declared backfill against the live rows before any DDL
+     * is planned. Returns a reason the column cannot be backfilled — the
+     * expression yields NULL for some row, or does not evaluate at all — or
+     * `undefined` when every row that needs a value gets one. `existing` is
+     * true when the column already exists (the tighten path), so only its NULL
+     * rows count.
+     *
+     * Plan-time, so the refusal names the table and column in the report
+     * instead of surfacing later as a bare, redacted engine error.
+     */
+    private isUniqueTarget;
+    private probeBackfill;
+    /**
+     * #3008: the column definition a SQLite backfill rebuild appends — NOT
+     * NULL, plus the declared default (for future inserts) and CHECK.
+     */
+    private sqliteAddedColumnDefinition;
+    /**
+     * `ALTER COLUMN ... SET NOT NULL`, made executable on DuckDB. DuckDB
+     * refuses to alter a table any index depends on ("Cannot alter entry …
+     * because there are entries that depend on it"), so there the table's
+     * explicit indexes are dropped around the ALTER and recreated from their
+     * own DDL, inside the same migration unit.
+     */
+    private setNotNullStatements;
+    /**
+     * #3008: the manual change reported instead of an `add_column` when a
+     * required column without a default or backfill cannot be added to a
+     * populated table (or when a SQLite backfill rebuild is refused). The
+     * column is NOT added; `compareTable` also withholds the indexes and
+     * foreign keys that would target it.
+     */
+    requiredColumnNotAddedChange(tableName: string, colName: string, colDef: ColumnDefinition, reason?: string): SchemaChange;
     /**
      * Generate SQL for dropping a column
      */

package/dist/migrations/differ.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"differ.d.ts","sourceRoot":"","sources":["../../src/migrations/differ.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"differ.d.ts","sourceRoot":"","sources":["../../src/migrations/differ.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAiCH,OAAO,KAAK,EAEV,gBAAgB,EAEhB,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,WAAW,EACZ,MAAM,oBAAoB,CAAC;AAoB5B,OAAO,KAAK,EAAE,iBAAiB,EAAsB,MAAM,YAAY,CAAC;AAIxE;;;GAGG;AACH,eAAO,MAAM,yBAAyB,uBAAuB,CAAC;AA4B9D;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;;;;;;OAYG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,iDAAiD;IACjD,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,0BAA0B,CAAC,EAAE;QAAE,cAAc,EAAE,KAAK,CAAA;KAAE,CAAC;CACxD;AAqBD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,MAAM,CAER;AAgCD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAIlE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAE9D;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAQtE;AASD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAsCrE;AAiBD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAOpE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,UAAU,EAAE,WAAW,GACtB;IACD,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;IACnE,GAAG,EAAE,MAAM,CAAC;CACb,CAyFA;AAED;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,EAAE,CAAoB;IAC9B,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,WAAW,CAAoC;IACvD;;;;;OAKG;IACH;;;OAGG;IACH,OAAO,CAAC,YAAY,CAGhB;IACJ,0EAA0E;IAC1E,OAAO,CAAC,aAAa,CAAkC;IAEvD,OAAO,CAAC,WAAW,CAGf;IACJ,uEAAuE;IACvE,OAAO,CAAC,eAAe,CAAoC;IAE3D;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,sBAAsB,CAA4C;IAE1E;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,6BAA6B,CAAO;gBAEhD,EAAE,EAAE,iBAAiB,EAAE,OAAO,GAAE,WAAgB;IAsB5D;;OAEG;IACG,OAAO,CACX,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAChD,OAAO,CAAC,UAAU,CAAC;IAqGtB;;OAEG;IACG,YAAY,CAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,gBAAgB,EAC1B,eAAe,GAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAM,GACrD,OAAO,CAAC,YAAY,EAAE,CAAC;IAkL1B;;;;OAIG;YACW,aAAa;IAW3B;;;;;;OAMG;YACW,wBAAwB;IA+FtC;;;;OAIG;YACW,cAAc;IAsC5B;;;;;;;;OAQG;YACW,kBAAkB;IAQhC;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAgD9B;;;;OAIG;YACW,2BAA2B;YAqC3B,kBAAkB;YAuPlB,oBAAoB;YA2BpB,0BAA0B;IAwDxC;;;;;;;;;;;;;;OAcG;YACW,cAAc;IAub5B;;;;;;;OAOG;YACW,uBAAuB;IAcrC;;;;;;;;;;;;;;;;;;OAkBG;YACW,kCAAkC;IA8NhD;;;;;;;;;;;;;;;;;;OAkBG;YACW,2BAA2B;IA+OzC;;;;;;;;;;;;;;OAcG;YACW,uCAAuC;IAarD;;;;OAIG;YACW,yCAAyC;IAmBvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;YACW,oBAAoB;IAmGlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,OAAO,CAAC,yBAAyB;IAyFjC;;;;;;;;OAQG;IACH,OAAO,CAAC,kCAAkC;IA6B1C;;;;;;;;;;;;;;;;;;;;;OAqBG;YACW,wBAAwB;IAwPtC;;;;;;;;OAQG;IACH,OAAO,CAAC,sBAAsB;IAgE9B;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IA2D5B;;;;OAIG;IACH,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,gBAAgB;IAWxB;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,qBAAqB;IAe7B;;;;;OAKG;YACW,YAAY;IAe1B;;;;OAIG;YACW,cAAc;IAkB5B,OAAO,CAAC,0BAA0B;IAkBlC,OAAO,CAAC,gCAAgC;IAexC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACH,OAAO,CAAC,cAAc;IAyPtB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,OAAO,CAAC,iBAAiB;IAezB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,sBAAsB;IAI9B;;;;;;;;;;;;;;;;;;;OAmBG;YACW,oBAAoB;IAmDlC;;OAEG;YACW,iBAAiB;IAoB/B;;OAEG;IACH,OAAO,CAAC,aAAa;IAiErB;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,uBAAuB;IA8D/B;;;;;;;OAOG;IACH,OAAO,CAAC,sBAAsB;IAmJ9B;;OAEG;IACH,OAAO,CAAC,eAAe;IAIvB;;;;OAIG;IACH,OAAO,CAAC,mCAAmC;IAgB3C;;;;OAIG;IACH,OAAO,CAAC,qCAAqC;IAU7C,OAAO,CAAC,YAAY;IAIpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;YACW,wBAAwB;IAsKtC;;;;;;;OAOG;YACW,kBAAkB;IAqBhC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,cAAc;YAWR,aAAa;IAuC3B;;;OAGG;IACH,OAAO,CAAC,2BAA2B;IAmBnC;;;;;;OAMG;YACW,oBAAoB;IA2ClC;;;;;;OAMG;IACH,4BAA4B,CAC1B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,gBAAgB,EACxB,MAAM,CAAC,EAAE,MAAM,GACd,YAAY;IA+Bf;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAI7B;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,mBAAmB;IAc3B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,oBAAoB;CAG7B;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,iBAAiB,EACrB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,EACjD,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAI9D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,EAAE,CAIzD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,EAAE,CAU5E"}

package/dist/migrations/differ.js

@@ -7,7 +7,7 @@ import { columnsAllValuesUuidShapedBatch, columnsHaveNonEmptyValueBatch, nonEmpt
 import { maskSampleValue, probeCastSafety, renderJsonbColumnConversion, renderTimestamptzColumnConversion } from "../schema/text-cast-probe.js";
 import { describeForeignKeyTypeConflict, planUuidConvergence, renderUuidConvergenceRepairHint, renderUuidShapeProbe } from "../schema/uuid-convergence.js";
 import "../schema/utils.js";
-import { planSqliteTableRebuilds, sqliteRebuildPlaceholderSql } from "./sqlite-rebuild.js";
+import { planSqliteTableRebuilds, sqliteBackfillPlaceholderSql, sqliteRebuildPlaceholderSql } from "./sqlite-rebuild.js";
 import { createLogger } from "@happyvertical/logger";
 //#region src/migrations/differ.ts
 /**
@@ -18,6 +18,11 @@ import { createLogger } from "@happyvertical/logger";
 */
 var logger = createLogger({ level: "info" });
 /**
+* `mismatch.actual` of the manual change reported when a required column
+* could not be added to a populated table (#3008): the column is absent.
+*/
+var REQUIRED_COLUMN_NOT_ADDED = "(column not added)";
+/**
 * Valid SQLDataType values for validation
 */
 var VALID_SQL_DATA_TYPES = /* @__PURE__ */ new Set([
@@ -313,6 +318,13 @@ var SchemaComparer = class SchemaComparer {
 	* re-reading `getTableSchema` per relationship would multiply catalog
 	* round-trips on a wide schema.
 	*/
+	/**
+	* #3008: indexes planned earlier in this table's batch (DuckDB unique
+	* follow-ups), which a later `SET NOT NULL` must also drop and recreate.
+	*/
+	batchIndexes = /* @__PURE__ */ new Map();
+	/** #3008: per-table single-column unique targets, set by compareTable. */
+	uniqueTargets = /* @__PURE__ */ new Map();
 	liveSchemas = /* @__PURE__ */ new Map();
 	/** Convergence plan for this run; `null` on non-PostgreSQL engines. */
 	uuidConvergence = null;
@@ -413,19 +425,70 @@ var SchemaComparer = class SchemaComparer {
 	*/
 	async compareTable(tableName, manifest, manifestSchemas = {}) {
 		const changes = [];
+		this.batchIndexes.delete(tableName);
+		this.uniqueTargets.set(tableName, new Set((manifest.indexes ?? []).filter((index) => {
+			if (!index.unique || index.columns.length !== 1) return false;
+			if (!index.where) return true;
+			return !this.supportsPartialIndexes() && !isStiSubtypeUniqueIndex(index);
+		}).map((index) => index.columns[0])));
 		const dbSchema = await this.getLiveSchema(tableName);
 		if (!dbSchema) return changes;
 		const columnChanges = await this.compareColumns(tableName, manifest, dbSchema);
-		changes.push(...this.engine === "sqlite" ? await planSqliteTableRebuilds({
+		const plannedColumnChanges = this.engine === "sqlite" ? await planSqliteTableRebuilds({
 			db: this.db,
 			tableName,
 			changes: columnChanges,
-			mapType: (type) => this.ddlStrategy.mapType(type)
-		}) : columnChanges);
+			mapType: (type) => this.ddlStrategy.mapType(type),
+			addedColumnDefinition: (change) => this.sqliteAddedColumnDefinition(change),
+			addedColumnFollowUps: (change) => change.column?.unique && change.name ? [`CREATE UNIQUE INDEX ${this.quoteIdentifier(uniqueColumnIndexName(tableName, change.name))} ON ${this.quoteIdentifier(tableName)} (${this.quoteIdentifier(change.name)})`] : []
+		}) : columnChanges;
+		const notAdded = /* @__PURE__ */ new Set();
+		for (const change of plannedColumnChanges) {
+			if (change.type === "add_column" && change.name && change.column && !change.sqlStatements && change.sql?.trim().startsWith("--")) {
+				const reason = change.sql.replace(/^--\s*/, "");
+				changes.push(this.requiredColumnNotAddedChange(tableName, change.name, change.column, reason));
+				notAdded.add(change.name);
+				continue;
+			}
+			if (change.type === "alter_column" && change.name && change.mismatch?.actual === "(column not added)") notAdded.add(change.name);
+			changes.push(change);
+		}
 		const dbIndexPredicates = await this.getDbIndexPredicates(tableName);
 		const indexChanges = this.compareIndexes(tableName, manifest, dbSchema, dbIndexPredicates);
-		changes.push(...indexChanges);
-		changes.push(...await this.compareForeignKeys(tableName, manifest, dbSchema, manifestSchemas));
+		const foreignKeyChanges = await this.compareForeignKeys(tableName, manifest, dbSchema, manifestSchemas);
+		if (notAdded.size === 0) {
+			changes.push(...indexChanges, ...foreignKeyChanges);
+			return changes;
+		}
+		const withheld = /* @__PURE__ */ new Map();
+		const dependsOnMissing = (change) => {
+			if (change.type === "add_index") return change.index?.columns.find((column) => notAdded.has(column));
+			if (change.type === "add_foreign_key") {
+				const column = change.foreignKey?.column;
+				return column && notAdded.has(column) ? column : void 0;
+			}
+		};
+		const withheldIndexNames = new Set(indexChanges.filter((change) => dependsOnMissing(change)).map((change) => change.index?.name ?? change.name));
+		for (const change of [...indexChanges, ...foreignKeyChanges]) {
+			if (change.type === "drop_index" && withheldIndexNames.has(change.index?.name ?? change.name)) continue;
+			const missing = dependsOnMissing(change);
+			if (!missing) {
+				changes.push(change);
+				continue;
+			}
+			const label = change.type === "add_index" ? `index ${change.index?.name ?? change.name ?? "(unnamed)"}` : `foreign key on ${missing}`;
+			withheld.set(missing, [...withheld.get(missing) ?? [], label]);
+		}
+		for (const change of changes) {
+			const labels = change.name && change.mismatch?.actual === "(column not added)" ? withheld.get(change.name) : void 0;
+			if (!labels || !change.advisory) continue;
+			const note = ` Withheld until it exists: ${labels.join(", ")}.`;
+			change.advisory = {
+				...change.advisory,
+				message: `${change.advisory.message}${note}`
+			};
+			change.sql = `${change.sql}${note}`;
+		}
 		return changes;
 	}
 	/**
@@ -1500,7 +1563,38 @@ var SchemaComparer = class SchemaComparer {
 			const quotedTable = this.quoteIdentifier(tableName);
 			const quotedCol = this.quoteIdentifier(colName);
 			const setNotNull = `ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedCol} SET NOT NULL`;
-			if (!this.supportsAlterColumn()) changes.push(this.buildAlterColumnChange({
+			const backfillNeeded = Boolean(colDef.backfill) && await this.columnHasNulls(tableName, colName);
+			const unusableBackfill = backfillNeeded && colDef.backfill ? await this.probeBackfill(tableName, colName, colDef.backfill, true, this.isUniqueTarget(tableName, colName, colDef)) : void 0;
+			if (backfillNeeded && unusableBackfill) changes.push({
+				type: "alter_column",
+				table: tableName,
+				name: colName,
+				column: colDef,
+				alteration: "set_not_null",
+				mismatch: {
+					expected: "NOT NULL",
+					actual: "NULL"
+				},
+				sql: `-- ${tableName}.${colName} is required but live rows hold NULL and ${unusableBackfill}`,
+				advisory: {
+					severity: "warning",
+					message: `${tableName}.${colName} is required but live rows hold NULL and ${unusableBackfill}.`,
+					suggestedSql: [`UPDATE ${quotedTable} SET ${quotedCol} = <value> WHERE ${quotedCol} IS NULL`, this.supportsAlterColumn() ? setNotNull : "-- SQLite: enforcing NOT NULL afterwards requires a table rebuild (#2370)"]
+				}
+			});
+			else if (this.engine === "sqlite" && backfillNeeded) changes.push({
+				type: "alter_column",
+				table: tableName,
+				name: colName,
+				column: colDef,
+				alteration: "set_not_null",
+				mismatch: {
+					expected: "NOT NULL",
+					actual: "NULL"
+				},
+				sql: sqliteBackfillPlaceholderSql(colName)
+			});
+			else if (!this.supportsAlterColumn()) changes.push(this.buildAlterColumnChange({
 				tableName,
 				colName,
 				colDef,
@@ -1509,6 +1603,15 @@ var SchemaComparer = class SchemaComparer {
 				actual: "NULL",
 				statements: null
 			}));
+			else if (backfillNeeded && colDef.backfill) changes.push(this.buildAlterColumnChange({
+				tableName,
+				colName,
+				colDef,
+				alteration: "set_not_null",
+				expected: "NOT NULL",
+				actual: "NULL",
+				statements: await this.backfillStatements(tableName, colName, colDef.backfill)
+			}));
 			else if (hasManifestDefault && manifestDefaultSql !== void 0) changes.push(this.buildAlterColumnChange({
 				tableName,
 				colName,
@@ -1516,7 +1619,7 @@ var SchemaComparer = class SchemaComparer {
 				alteration: "set_not_null",
 				expected: "NOT NULL",
 				actual: "NULL",
-				statements: [`UPDATE ${quotedTable} SET ${quotedCol} = ${manifestDefaultSql} WHERE ${quotedCol} IS NULL`, setNotNull]
+				statements: [`UPDATE ${quotedTable} SET ${quotedCol} = ${manifestDefaultSql} WHERE ${quotedCol} IS NULL`, ...await this.setNotNullStatements(tableName, colName)]
 			}));
 			else if (await this.columnHasNulls(tableName, colName)) changes.push({
 				type: "alter_column",
@@ -1542,7 +1645,7 @@ var SchemaComparer = class SchemaComparer {
 				alteration: "set_not_null",
 				expected: "NOT NULL",
 				actual: "NULL",
-				statements: [setNotNull]
+				statements: await this.setNotNullStatements(tableName, colName)
 			}));
 		} else if (!manifestNotNull && dbNotNull) changes.push(this.buildAlterColumnChange({
 			tableName,
@@ -2101,11 +2204,15 @@ var SchemaComparer = class SchemaComparer {
 	* - `NOT NULL` with a default: inline on SQLite/PostgreSQL (existing rows
 	*   receive the default); DuckDB adds with `DEFAULT` then a separate
 	*   `ALTER COLUMN ... SET NOT NULL`.
-	* - `NOT NULL` without a default: enforced only when the table is empty
+	* - `NOT NULL` without a default: enforced inline when the table is empty
 	*   (inline on SQLite/PostgreSQL, `SET NOT NULL` step on DuckDB). On a
-	*   populated table there is nothing to backfill with, so the column is
-	*   added nullable and a manual `alter_column` (`set_not_null`) is reported
-	*   with the exact remediation instead of emitting DDL every engine rejects.
+	*   populated table it needs a declared per-row `backfill` (#3008): add
+	*   nullable, `UPDATE` from the backfill, then `SET NOT NULL` (SQLite: a
+	*   table rebuild). Without one — or when the backfill yields NULL or does
+	*   not evaluate — the column is NOT added and a manual `alter_column`
+	*   (`mismatch.actual === REQUIRED_COLUMN_NOT_ADDED`) names it.
+	* - A backfill also wins over a declared default for existing rows; the
+	*   default is then set after the fill, for future inserts only.
 	* - `UNIQUE`: inline on PostgreSQL (a real constraint); SQLite/DuckDB get a
 	*   separate `CREATE UNIQUE INDEX <table>_<col>_key` (the PostgreSQL
 	*   constraint-index name, so the orphan sweep leaves it alone).
@@ -2127,35 +2234,44 @@ var SchemaComparer = class SchemaComparer {
 		const hasDefault = colDef.defaultValue !== void 0 && colDef.defaultValue !== null;
 		const formattedDefault = hasDefault ? this.ddlStrategy.formatDefaultValue(colDef.defaultValue, validatedType) : void 0;
 		const inlineConstraintsAllowed = this.engine !== "duckdb" && this.engine !== "json";
-		const setNotNull = `ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedCol} SET NOT NULL`;
+		`${quotedTable}${quotedCol}`;
 		let enforceNotNull = false;
-		if (colDef.notNull) if (hasDefault) enforceNotNull = true;
-		else if (!await this.tableHasRows(tableName)) enforceNotNull = true;
-		else extraChanges.push({
-			type: "alter_column",
-			table: tableName,
-			name: colName,
-			column: colDef,
-			alteration: "set_not_null",
-			mismatch: {
-				expected: "NOT NULL",
-				actual: "NULL"
-			},
-			sql: `-- ${tableName}.${colName} is required by the manifest but has no default to backfill existing rows; the column is added nullable. Backfill it, then run: ${setNotNull}`,
-			advisory: {
-				severity: "warning",
-				message: `${tableName}.${colName} is required by the manifest but has no default, and ${tableName} already holds rows — no engine can add it NOT NULL. It is added nullable; backfill it, then rerun db:migrate (or declare a default on the field).`,
-				suggestedSql: [`UPDATE ${quotedTable} SET ${quotedCol} = <value> WHERE ${quotedCol} IS NULL`, this.supportsAlterColumn() ? setNotNull : `-- SQLite: enforcing NOT NULL afterwards requires a table rebuild (#2370)`]
-			}
-		});
+		const backfillFollowUps = [];
+		let deferDefault = false;
+		if (colDef.notNull) {
+			const populated = colDef.backfill || !hasDefault ? await this.tableHasRows(tableName) : true;
+			if (colDef.backfill && populated) {
+				const unusable = await this.probeBackfill(tableName, colName, colDef.backfill, false, this.isUniqueTarget(tableName, colName, colDef));
+				if (unusable) return [this.requiredColumnNotAddedChange(tableName, colName, colDef, unusable)];
+				if (this.engine === "sqlite") return [{
+					type: "add_column",
+					table: tableName,
+					name: colName,
+					column: colDef,
+					sql: sqliteBackfillPlaceholderSql(colName)
+				}];
+				deferDefault = formattedDefault !== void 0;
+				backfillFollowUps.push(...await this.backfillStatements(tableName, colName, colDef.backfill, deferDefault ? [this.generateSetDefaultSQL(tableName, colName, formattedDefault, validatedType)] : []));
+			} else if (hasDefault || !populated) enforceNotNull = true;
+			else return [this.requiredColumnNotAddedChange(tableName, colName, colDef)];
+		}
 		if (enforceNotNull && inlineConstraintsAllowed) parts.push("NOT NULL");
 		if (colDef.unique && this.engine === "postgres") parts.push("UNIQUE");
-		if (formattedDefault !== void 0) parts.push(`DEFAULT ${formattedDefault}`);
+		if (formattedDefault !== void 0 && !deferDefault) parts.push(`DEFAULT ${formattedDefault}`);
 		if (colDef.check) if (inlineConstraintsAllowed) parts.push(`CHECK (${colDef.check})`);
 		else logger.warn(`[SchemaComparer] ${this.engine} rejects CHECK constraints in ADD COLUMN; ${tableName}.${colName} is added without CHECK (${colDef.check})`);
 		const addColumn = `ALTER TABLE ${quotedTable} ADD COLUMN ${parts.join(" ")}`;
-		if (enforceNotNull && !inlineConstraintsAllowed) followUps.push(setNotNull);
-		if (colDef.unique && this.engine !== "postgres") followUps.push(`CREATE UNIQUE INDEX ${this.quoteIdentifier(uniqueColumnIndexName(tableName, colName))} ON ${quotedTable} (${quotedCol})`);
+		if (enforceNotNull && !inlineConstraintsAllowed) followUps.push(...await this.setNotNullStatements(tableName, colName));
+		followUps.push(...backfillFollowUps);
+		if (colDef.unique && this.engine !== "postgres") {
+			const indexName = uniqueColumnIndexName(tableName, colName);
+			const createIndex = `CREATE UNIQUE INDEX ${this.quoteIdentifier(indexName)} ON ${quotedTable} (${quotedCol})`;
+			followUps.push(createIndex);
+			this.batchIndexes.set(tableName, [...this.batchIndexes.get(tableName) ?? [], {
+				name: indexName,
+				sql: createIndex
+			}]);
+		}
 		const statements = [addColumn, ...followUps];
 		return [{
 			type: "add_column",
@@ -2167,6 +2283,127 @@ var SchemaComparer = class SchemaComparer {
 		}, ...extraChanges];
 	}
 	/**
+	* #3008: fill a column's NULLs from its declared per-row backfill, then
+	* enforce NOT NULL (PostgreSQL/DuckDB; SQLite goes through a table
+	* rebuild). {@link probeBackfill} has already checked, at plan time, that
+	* the expression yields a value for every row; should a row written after
+	* that still produce NULL, `SET NOT NULL` fails and the whole migration
+	* unit rolls back.
+	*/
+	async backfillStatements(tableName, colName, backfill, alterBeforeNotNull = []) {
+		const quotedTable = this.quoteIdentifier(tableName);
+		const quotedCol = this.quoteIdentifier(colName);
+		const statements = [`UPDATE ${quotedTable} SET ${quotedCol} = (${backfill}) WHERE ${quotedCol} IS NULL`];
+		statements.push(...await this.setNotNullStatements(tableName, colName, alterBeforeNotNull));
+		return statements;
+	}
+	/**
+	* #3008: evaluate a declared backfill against the live rows before any DDL
+	* is planned. Returns a reason the column cannot be backfilled — the
+	* expression yields NULL for some row, or does not evaluate at all — or
+	* `undefined` when every row that needs a value gets one. `existing` is
+	* true when the column already exists (the tighten path), so only its NULL
+	* rows count.
+	*
+	* Plan-time, so the refusal names the table and column in the report
+	* instead of surfacing later as a bare, redacted engine error.
+	*/
+	isUniqueTarget(tableName, colName, colDef) {
+		return Boolean(colDef.unique) || (this.uniqueTargets.get(tableName)?.has(colName) ?? false);
+	}
+	async probeBackfill(tableName, colName, backfill, existing, unique = false) {
+		const quotedCol = this.quoteIdentifier(colName);
+		const where = existing ? `${quotedCol} IS NULL AND (${backfill}) IS NULL` : `(${backfill}) IS NULL`;
+		try {
+			if (((await this.db.query(`SELECT 1 AS present FROM ${this.quoteIdentifier(tableName)} WHERE ${where} LIMIT 1`)).rows?.length ?? 0) > 0) return `its declared backfill (${backfill}) yields NULL for at least one existing row, so NOT NULL cannot be enforced; make the expression non-null for every row (e.g. wrap it in COALESCE)`;
+			if (unique) {
+				const value = existing ? `COALESCE(${quotedCol}, (${backfill}))` : `(${backfill})`;
+				if (((await this.db.query(`SELECT ${value} AS v FROM ${this.quoteIdentifier(tableName)} GROUP BY ${value} HAVING COUNT(*) > 1 LIMIT 1`)).rows?.length ?? 0) > 0) return `its declared backfill (${backfill}) gives two or more existing rows the same value, but the column is unique; derive a per-row value (e.g. from id)`;
+			}
+			return;
+		} catch (err) {
+			logger.debug(`[SchemaComparer] Backfill probe failed for ${tableName}.${colName}`, { error: err instanceof Error ? err.message : String(err) });
+			return `its declared backfill (${backfill}) does not evaluate on this database; check the expression's SQL and column names (snake_case)`;
+		}
+	}
+	/**
+	* #3008: the column definition a SQLite backfill rebuild appends — NOT
+	* NULL, plus the declared default (for future inserts) and CHECK.
+	*/
+	sqliteAddedColumnDefinition(change) {
+		const column = change.column;
+		const type = isValidSQLDataType(column.type) ? column.type : "TEXT";
+		const parts = [
+			this.quoteIdentifier(change.name),
+			this.ddlStrategy.mapType(type),
+			"NOT NULL"
+		];
+		if (column.defaultValue !== void 0 && column.defaultValue !== null) parts.push(`DEFAULT ${this.ddlStrategy.formatDefaultValue(column.defaultValue, type)}`);
+		if (column.check) parts.push(`CHECK (${column.check})`);
+		return parts.join(" ");
+	}
+	/**
+	* `ALTER COLUMN ... SET NOT NULL`, made executable on DuckDB. DuckDB
+	* refuses to alter a table any index depends on ("Cannot alter entry …
+	* because there are entries that depend on it"), so there the table's
+	* explicit indexes are dropped around the ALTER and recreated from their
+	* own DDL, inside the same migration unit.
+	*/
+	async setNotNullStatements(tableName, colName, alterBefore = []) {
+		const setNotNull = `ALTER TABLE ${this.quoteIdentifier(tableName)} ALTER COLUMN ${this.quoteIdentifier(colName)} SET NOT NULL`;
+		if (this.engine !== "duckdb" && this.engine !== "json") return [...alterBefore, setNotNull];
+		let indexes = [];
+		try {
+			indexes = (await this.db.query(`SELECT index_name, sql FROM duckdb_indexes() WHERE table_name = ${this.quoteLiteral(tableName)} AND sql IS NOT NULL`)).rows.flatMap((row) => typeof row.index_name === "string" && typeof row.sql === "string" ? [{
+				name: row.index_name,
+				sql: row.sql.replace(/;\s*$/, "")
+			}] : []);
+		} catch (err) {
+			logger.debug(`[SchemaComparer] DuckDB index probe unavailable for ${tableName}`, { error: err instanceof Error ? err.message : String(err) });
+		}
+		for (const planned of this.batchIndexes.get(tableName) ?? []) if (!indexes.some((index) => index.name === planned.name)) indexes.push(planned);
+		return [
+			...indexes.map((index) => `DROP INDEX ${this.quoteIdentifier(index.name)}`),
+			...alterBefore,
+			setNotNull,
+			...indexes.map((index) => index.sql)
+		];
+	}
+	/**
+	* #3008: the manual change reported instead of an `add_column` when a
+	* required column without a default or backfill cannot be added to a
+	* populated table (or when a SQLite backfill rebuild is refused). The
+	* column is NOT added; `compareTable` also withholds the indexes and
+	* foreign keys that would target it.
+	*/
+	requiredColumnNotAddedChange(tableName, colName, colDef, reason) {
+		const quotedTable = this.quoteIdentifier(tableName);
+		const quotedCol = this.quoteIdentifier(colName);
+		const why = reason ?? `it is required, has no default, and ${tableName} already holds rows`;
+		const fix = reason ? "Fix that, then rerun db:migrate." : "Declare a per-row backfill on the field, e.g. @field({ required: true, backfill: \"'row:' || id\" }), or a default, then rerun db:migrate.";
+		return {
+			type: "alter_column",
+			table: tableName,
+			name: colName,
+			column: colDef,
+			alteration: "set_not_null",
+			mismatch: {
+				expected: "NOT NULL",
+				actual: REQUIRED_COLUMN_NOT_ADDED
+			},
+			sql: `-- ${tableName}.${colName} was not added: ${why}. ${fix}`,
+			advisory: {
+				severity: "warning",
+				message: `${tableName}.${colName} was not added: ${why}. ${fix}`,
+				suggestedSql: [
+					`ALTER TABLE ${quotedTable} ADD COLUMN ${quotedCol} ${this.ddlStrategy.mapType(isValidSQLDataType(colDef.type) ? colDef.type : "TEXT")}`,
+					`UPDATE ${quotedTable} SET ${quotedCol} = <per-row value> WHERE ${quotedCol} IS NULL`,
+					this.supportsAlterColumn() ? `ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedCol} SET NOT NULL` : "-- SQLite: enforcing NOT NULL afterwards requires a table rebuild (#2370)"
+				]
+			}
+		};
+	}
+	/**
 	* Generate SQL for dropping a column
 	*/
 	generateDropColumnSQL(tableName, colName) {
@@ -2257,6 +2494,6 @@ function getSQLFromChanges(changes) {
 	return statements;
 }
 //#endregion
-export { SchemaComparer, canonicalizeDefault, extractIndexPredicate, generateSchemaDiff, getSQLFromChanges, getSQLFromDiff, hasActionableChanges, isAdvisoryOnlyChange, isInfoOnlyChange, isManualOrAdvisoryChange, normalizeIndexPredicate, uniqueColumnIndexName };
+export { REQUIRED_COLUMN_NOT_ADDED, SchemaComparer, canonicalizeDefault, extractIndexPredicate, generateSchemaDiff, getSQLFromChanges, getSQLFromDiff, hasActionableChanges, isAdvisoryOnlyChange, isInfoOnlyChange, isManualOrAdvisoryChange, normalizeIndexPredicate, uniqueColumnIndexName };
 
 //# sourceMappingURL=differ.js.map