@happyvertical/smrt-core 0.40.69 → 0.41.0

package/dist/migrations/differ.js

@@ -1,6 +1,7 @@
-import { isJsonPathIndex, renderIndexTarget } from "../schema/index-utils.js";
+import { isJsonPathIndex, isStiSubtypeUniqueIndex, renderIndexTarget } from "../schema/index-utils.js";
 import { detectEngine, getDDLStrategy } from "../schema/ddl/index.js";
 import "../schema/utils.js";
+import { planSqliteTableRebuilds, sqliteRebuildPlaceholderSql } from "./sqlite-rebuild.js";
 import { createLogger } from "@happyvertical/logger";
 //#region src/migrations/differ.ts
 /**
@@ -33,14 +34,56 @@ function isValidSQLDataType(type) {
 * Suffix patterns for indexes that the differ refuses to drop.
 * - `_pkey`: PostgreSQL primary key implicit index.
 * - `_key`: PostgreSQL implicit index for inline `UNIQUE (...)` table
-*   constraints. Dropping these by name does not drop the underlying
-*   constraint, and dropping the constraint requires a separate DDL path
+*   constraints, and the unique index the differ itself creates for a
+*   `unique: true` column added via ADD COLUMN on engines that reject an
+*   inline UNIQUE there (SQLite/DuckDB — see {@link uniqueColumnIndexName}).
+*   Dropping these by name does not drop the underlying constraint on
+*   PostgreSQL, and dropping the constraint requires a separate DDL path
 *   (`ALTER TABLE ... DROP CONSTRAINT`) the differ does not emit today.
+*   Unclaimed `_key` unique indexes are instead *reported* as
+*   `orphan_index` advisories (#2369).
 */
 var PROTECTED_INDEX_SUFFIXES = ["_pkey", "_key"];
 function isProtectedDbIndexName(name) {
 	return PROTECTED_INDEX_SUFFIXES.some((suffix) => name.endsWith(suffix));
 }
+/**
+* Name of the unique index that backs a `unique: true` column. Mirrors the
+* `<table>_<column>_key` name PostgreSQL gives the implicit index of an
+* inline column UNIQUE constraint, so the same column ends up with the same
+* index name on every engine and the orphan-index sweep treats it as
+* constraint-owned.
+*/
+function uniqueColumnIndexName(tableName, columnName) {
+	return `${tableName}_${columnName}_key`;
+}
+/**
+* True when a change is report-only: it carries an advisory and no
+* executable statement. Such changes never reach the migration stream.
+*/
+function isAdvisoryOnlyChange(change) {
+	if (!change.advisory) return false;
+	return (change.sqlStatements ?? (change.sql ? [change.sql] : [])).length === 0;
+}
+/**
+* True for an info-level report-only change: listed in `SchemaDiff.changes`
+* for visibility but not counted by `has_changes` (a harmless orphan column,
+* a live default the manifest no longer declares).
+*/
+function isInfoOnlyChange(change) {
+	return isAdvisoryOnlyChange(change) && change.advisory?.severity === "info";
+}
+/**
+* True when a change has no executable DDL: `type_mismatch`, an advisory-only
+* change, or a change whose only SQL is an advisory comment (e.g. a SQLite
+* `ALTER COLUMN` the engine cannot perform in place).
+*/
+function isManualOrAdvisoryChange(change) {
+	if (change.type === "type_mismatch") return true;
+	if (isAdvisoryOnlyChange(change)) return true;
+	const statements = change.sqlStatements ?? (change.sql ? [change.sql] : []);
+	return statements.length > 0 && statements.every((statement) => statement.trim().startsWith("--"));
+}
 function resolveDatabaseUrl(db) {
 	const dbWithConfig = db;
 	return db.url || dbWithConfig.config?.url || "";
@@ -120,6 +163,125 @@ function extractIndexPredicate(createIndexSql) {
 	return normalizeIndexPredicate(match[1]);
 }
 /**
+* Canonical form of a column default for drift comparison (#2369).
+*
+* The manifest side is the DDL fragment `formatDefaultValue()` would emit
+* (`'anon'`, `0`, `TRUE`, `'{}'`, `current_timestamp`); the database side is
+* whatever the catalog reports, which each engine renders differently:
+* PostgreSQL appends casts (`'anon'::text`, `'{}'::jsonb`, `'-1'::integer`)
+* and upper-cases `CURRENT_TIMESTAMP`, DuckDB wraps booleans
+* (`CAST('t' AS BOOLEAN)`), SQLite echoes the literal verbatim. Both sides
+* are reduced by the *manifest column type* to a `{kind, key}` pair:
+*
+* - `none`   — no default (`undefined`, empty, or the `NULL` keyword)
+* - `now`    — the current-timestamp family (`current_timestamp`, `now()`,
+*              `transaction_timestamp()`, `datetime('now')`)
+* - `number` — numeric columns, compared by numeric value
+* - `bool`   — boolean columns (`true`/`false`/`t`/`f`/`1`/`0`)
+* - `text`   — string literal contents (JSON columns compare the parsed
+*              value when both sides parse)
+* - `func`   — other function calls / keywords, compared lowercase and
+*              whitespace-collapsed
+* - `raw`    — could not be classified; callers must skip the comparison
+*              rather than risk a false positive
+*/
+function canonicalizeDefault(fragment, columnType) {
+	if (fragment === void 0) return {
+		kind: "none",
+		key: ""
+	};
+	let s = fragment.trim();
+	if (s === "") return {
+		kind: "none",
+		key: ""
+	};
+	for (let guard = 0; guard < 8; guard++) {
+		const before = s;
+		const castMatch = s.match(/^CAST\s*\((.*)\s+AS\s+[A-Za-z_][\w\s()]*\)$/is);
+		if (castMatch) s = castMatch[1].trim();
+		if (s.startsWith("(") && s.endsWith(")")) s = s.slice(1, -1).trim();
+		s = s.replace(/::[A-Za-z_][\w ]*(\(\s*\d+(\s*,\s*\d+)?\s*\))?(\[\])?\s*$/i, "").trim();
+		if (s === before) break;
+	}
+	if (/^null$/i.test(s)) return {
+		kind: "none",
+		key: ""
+	};
+	const lower = s.toLowerCase().replace(/\s+/g, " ");
+	if (lower === "current_timestamp" || lower === "current_timestamp()" || lower === "now()" || lower === "transaction_timestamp()" || lower === "datetime('now')" || lower === "localtimestamp") return {
+		kind: "now",
+		key: "now"
+	};
+	const upperType = String(columnType).toUpperCase();
+	const isNumericType = upperType === "INTEGER" || upperType === "REAL" || upperType === "DECIMAL";
+	const isBooleanType = upperType === "BOOLEAN";
+	const isJsonType = upperType === "JSON";
+	const literalMatch = s.match(/^'((?:[^']|'')*)'$/s);
+	const literal = literalMatch !== null ? literalMatch[1].replace(/''/g, "'") : null;
+	if (isBooleanType) {
+		const token = (literal ?? s).trim().toLowerCase();
+		if ([
+			"true",
+			"t",
+			"1",
+			"yes",
+			"on"
+		].includes(token)) return {
+			kind: "bool",
+			key: "true"
+		};
+		if ([
+			"false",
+			"f",
+			"0",
+			"no",
+			"off"
+		].includes(token)) return {
+			kind: "bool",
+			key: "false"
+		};
+		return {
+			kind: "raw",
+			key: lower
+		};
+	}
+	if (isNumericType) {
+		const token = (literal ?? s).trim();
+		if (/^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/.test(token)) return {
+			kind: "number",
+			key: String(Number(token))
+		};
+		if (literal !== null) return {
+			kind: "text",
+			key: literal
+		};
+	}
+	if (literal !== null) {
+		if (isJsonType) try {
+			return {
+				kind: "text",
+				key: JSON.stringify(JSON.parse(literal))
+			};
+		} catch {}
+		return {
+			kind: "text",
+			key: literal
+		};
+	}
+	if (/^[+-]?(\d+\.?\d*|\.\d+)$/.test(s)) return {
+		kind: "text",
+		key: String(Number(s))
+	};
+	if (/^[A-Za-z_][\w.]*\s*\(.*\)$/s.test(s) || /^[A-Za-z_]\w*$/.test(s)) return {
+		kind: "func",
+		key: lower
+	};
+	return {
+		kind: "raw",
+		key: lower
+	};
+}
+/**
 * SchemaComparer class for comparing manifest schemas to database
 */
 var SchemaComparer = class {
@@ -157,15 +319,19 @@ var SchemaComparer = class {
 			const tableChanges = await this.compareTable(tableName, schema);
 			if (tableChanges.length > 0) {
 				diff.changes.push(...tableChanges);
-				diff.has_changes = true;
+				if (tableChanges.some((change) => !isInfoOnlyChange(change))) diff.has_changes = true;
 			}
 		}
-		if (this.options.includeDroppedTables) for (const tableName of existingTables) {
+		const orphanTables = [];
+		for (const tableName of existingTables) {
 			if (tableName.startsWith("_smrt_") || tableName.startsWith("sqlite_")) continue;
-			if (!manifestSchemas[tableName]) {
-				diff.dropped_tables.push(tableName);
-				diff.has_changes = true;
-			}
+			if (!manifestSchemas[tableName]) orphanTables.push(tableName);
+		}
+		orphanTables.sort();
+		diff.orphan_tables = orphanTables;
+		if (this.options.includeDroppedTables && orphanTables.length > 0) {
+			diff.dropped_tables.push(...orphanTables);
+			diff.has_changes = true;
 		}
 		return diff;
 	}
@@ -176,28 +342,40 @@ var SchemaComparer = class {
 		const changes = [];
 		const dbSchema = await this.db.getTableSchema?.(tableName);
 		if (!dbSchema) return changes;
-		const columnChanges = this.compareColumns(tableName, manifest, dbSchema);
-		changes.push(...columnChanges);
+		const columnChanges = await this.compareColumns(tableName, manifest, dbSchema);
+		changes.push(...this.engine === "sqlite" ? await planSqliteTableRebuilds({
+			db: this.db,
+			tableName,
+			changes: columnChanges,
+			mapType: (type) => this.ddlStrategy.mapType(type)
+		}) : columnChanges);
 		const dbIndexPredicates = await this.getDbIndexPredicates(tableName);
 		const indexChanges = this.compareIndexes(tableName, manifest, dbSchema, dbIndexPredicates);
 		changes.push(...indexChanges);
 		return changes;
 	}
 	/**
-	* Compare columns between manifest and database
+	* Compare columns between manifest and database.
+	*
+	* Three families of drift (#2369):
+	*
+	* 1. **Missing column** — emit `add_column` with an executable plan for the
+	*    engine (see {@link generateAddColumnChanges}).
+	* 2. **Existing column** — type drift (as before), then nullability and
+	*    default drift (see {@link compareColumnConstraints}).
+	* 3. **Orphan column** (in DB, not in manifest) — always reported. With
+	*    `includeDroppedColumns` it becomes an executable `drop_column`; a
+	*    NOT NULL orphan without a default is a `warning` advisory because ORM
+	*    inserts never supply it and will fail (`23502`); with `relaxColumns`
+	*    that orphan gets an executable `DROP NOT NULL` where the engine allows.
 	*/
-	compareColumns(tableName, manifest, dbSchema) {
+	async compareColumns(tableName, manifest, dbSchema) {
 		const changes = [];
 		const dbColumnNames = new Set(Object.keys(dbSchema.columns));
-		for (const [colName, colDef] of Object.entries(manifest.columns)) if (!dbColumnNames.has(colName)) changes.push({
-			type: "add_column",
-			table: tableName,
-			name: colName,
-			column: colDef,
-			sql: this.generateAddColumnSQL(tableName, colName, colDef)
-		});
+		for (const [colName, colDef] of Object.entries(manifest.columns)) if (!dbColumnNames.has(colName)) changes.push(...await this.generateAddColumnChanges(tableName, colName, colDef));
 		else {
 			const dbCol = dbSchema.columns[colName];
+			let typeDrifted = false;
 			const manifestType = colDef.type;
 			if (!isValidSQLDataType(manifestType)) logger.warn(`[SchemaComparer] Invalid manifest type "${manifestType}" for ${tableName}.${colName}, treating as TEXT`);
 			const validatedType = isValidSQLDataType(manifestType) ? manifestType : "TEXT";
@@ -206,6 +384,7 @@ var SchemaComparer = class {
 			const normalizedActual = this.normalizeType(dbCol.type);
 			const isUuidTextEquivalent = this.isUuidTextEquivalentColumn(colName, colDef, normalizedExpected, normalizedActual);
 			if (normalizedExpected !== normalizedActual && !isUuidTextEquivalent && !(normalizedExpected === "JSON" && normalizedActual === "TEXT" || normalizedExpected === "TEXT" && normalizedActual === "JSON")) {
+				typeDrifted = true;
 				if (this.isCompatibleTypeUpgrade(colDef.type, dbCol.type)) {
 					const generatedSQL = this.generateTypeUpgradeSQL(tableName, colName, colDef, dbCol.type);
 					changes.push({
@@ -230,18 +409,297 @@ var SchemaComparer = class {
 					}
 				});
 			}
+			if (!typeDrifted) changes.push(...await this.compareColumnConstraints(tableName, colName, colDef, validatedType, dbCol));
 		}
-		if (this.options.includeDroppedColumns) {
-			const manifestColumnNames = new Set(Object.keys(manifest.columns));
-			for (const colName of dbColumnNames) if (!manifestColumnNames.has(colName)) changes.push({
-				type: "drop_column",
+		const manifestColumnNames = new Set(Object.keys(manifest.columns));
+		for (const colName of dbColumnNames) {
+			if (manifestColumnNames.has(colName)) continue;
+			const dbCol = dbSchema.columns[colName];
+			if (this.options.includeDroppedColumns) {
+				changes.push({
+					type: "drop_column",
+					table: tableName,
+					name: colName,
+					mismatch: {
+						expected: "(not in manifest)",
+						actual: this.describeDbColumn(dbCol)
+					},
+					sql: this.generateDropColumnSQL(tableName, colName)
+				});
+				continue;
+			}
+			changes.push(this.describeOrphanColumn(tableName, colName, dbCol));
+		}
+		return changes;
+	}
+	/**
+	* Compare nullability and default between a manifest column and the live
+	* column, emitting `alter_column` changes (#2369).
+	*
+	* Rules:
+	* - Primary-key columns are owned by the PK constraint (SQLite reports a
+	*   `TEXT PRIMARY KEY` as nullable while PostgreSQL/DuckDB imply NOT NULL),
+	*   so they are skipped entirely.
+	* - Strengthening (`SET NOT NULL`, `SET DEFAULT`) is emitted as executable
+	*   SQL on engines with `ALTER COLUMN` (PostgreSQL/DuckDB). A `SET NOT NULL`
+	*   is preceded by a backfill of the manifest default when there is one;
+	*   without a default the live data is probed and, if NULLs exist, the
+	*   change is reported as manual with the suggested backfill instead of
+	*   emitting an ALTER the engine would reject mid-batch.
+	* - Relaxing (`DROP NOT NULL`, `DROP DEFAULT`) is reported as an advisory
+	*   unless `relaxColumns` is set, in which case it is executable.
+	* - SQLite has no `ALTER COLUMN`; every alteration is reported as manual
+	*   (advisory-comment SQL) until the table-rebuild path (#2370) lands.
+	* - Defaults are compared through {@link canonicalizeDefault}; when either
+	*   side cannot be canonicalized the comparison is skipped rather than
+	*   risking a false positive that would churn every run.
+	*/
+	async compareColumnConstraints(tableName, colName, colDef, validatedType, dbCol) {
+		if (colDef.primaryKey || dbCol.primaryKey) return [];
+		const changes = [];
+		const manifestNotNull = colDef.notNull === true;
+		const dbNotNull = dbCol.notNull === true;
+		const manifestDefaultSql = colDef.defaultValue !== void 0 ? this.ddlStrategy.formatDefaultValue(colDef.defaultValue, validatedType) : void 0;
+		const manifestDefaultCanon = canonicalizeDefault(manifestDefaultSql, validatedType);
+		const dbDefaultCanon = canonicalizeDefault(dbCol.defaultValue === null || dbCol.defaultValue === void 0 ? void 0 : String(dbCol.defaultValue), validatedType);
+		const hasManifestDefault = manifestDefaultCanon.kind !== "none";
+		const defaultDrifted = manifestDefaultCanon.kind !== "raw" && dbDefaultCanon.kind !== "raw" && `${manifestDefaultCanon.kind}:${manifestDefaultCanon.key}` !== `${dbDefaultCanon.kind}:${dbDefaultCanon.key}`;
+		const dbHasDefault = dbDefaultCanon.kind !== "none";
+		if (defaultDrifted) {
+			if (hasManifestDefault && manifestDefaultSql !== void 0) changes.push(this.buildAlterColumnChange({
+				tableName,
+				colName,
+				colDef,
+				alteration: "set_default",
+				expected: `DEFAULT ${manifestDefaultSql}`,
+				actual: dbHasDefault ? `DEFAULT ${String(dbCol.defaultValue)}` : "(no default)",
+				statements: this.supportsAlterColumn() ? [this.generateSetDefaultSQL(tableName, colName, manifestDefaultSql, validatedType)] : null
+			}));
+			else if (dbHasDefault) changes.push(this.buildAlterColumnChange({
+				tableName,
+				colName,
+				colDef,
+				alteration: "drop_default",
+				expected: "(no default)",
+				actual: `DEFAULT ${String(dbCol.defaultValue)}`,
+				statements: this.supportsAlterColumn() ? [`ALTER TABLE ${this.quoteIdentifier(tableName)} ALTER COLUMN ${this.quoteIdentifier(colName)} DROP DEFAULT`] : null,
+				relaxation: {
+					severity: "info",
+					message: `${tableName}.${colName} has a live default (${String(dbCol.defaultValue)}) the manifest no longer declares; inserts that omit the column keep receiving it. ${this.relaxHint("drop it")}`
+				}
+			}));
+		}
+		if (manifestNotNull && !dbNotNull) {
+			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({
+				tableName,
+				colName,
+				colDef,
+				alteration: "set_not_null",
+				expected: "NOT NULL",
+				actual: "NULL",
+				statements: null
+			}));
+			else if (hasManifestDefault && manifestDefaultSql !== void 0) changes.push(this.buildAlterColumnChange({
+				tableName,
+				colName,
+				colDef,
+				alteration: "set_not_null",
+				expected: "NOT NULL",
+				actual: "NULL",
+				statements: [`UPDATE ${quotedTable} SET ${quotedCol} = ${manifestDefaultSql} WHERE ${quotedCol} IS NULL`, setNotNull]
+			}));
+			else if (await this.columnHasNulls(tableName, colName)) changes.push({
+				type: "alter_column",
 				table: tableName,
 				name: colName,
-				sql: this.generateDropColumnSQL(tableName, colName)
+				column: colDef,
+				alteration: "set_not_null",
+				mismatch: {
+					expected: "NOT NULL",
+					actual: "NULL"
+				},
+				sql: `-- ${tableName}.${colName} is required by the manifest but live rows hold NULL and the column has no default to backfill; UPDATE those rows, then run: ${setNotNull}`,
+				advisory: {
+					severity: "warning",
+					message: `${tableName}.${colName} is required by the manifest but live rows hold NULL and there is no default to backfill. Backfill the NULLs, then rerun db:migrate (or declare a default on the field).`,
+					suggestedSql: [`UPDATE ${quotedTable} SET ${quotedCol} = <value> WHERE ${quotedCol} IS NULL`, setNotNull]
+				}
 			});
-		}
+			else changes.push(this.buildAlterColumnChange({
+				tableName,
+				colName,
+				colDef,
+				alteration: "set_not_null",
+				expected: "NOT NULL",
+				actual: "NULL",
+				statements: [setNotNull]
+			}));
+		} else if (!manifestNotNull && dbNotNull) changes.push(this.buildAlterColumnChange({
+			tableName,
+			colName,
+			colDef,
+			alteration: "drop_not_null",
+			expected: "NULL",
+			actual: "NOT NULL",
+			statements: this.supportsAlterColumn() ? [`ALTER TABLE ${this.quoteIdentifier(tableName)} ALTER COLUMN ${this.quoteIdentifier(colName)} DROP NOT NULL`] : null,
+			relaxation: {
+				severity: "warning",
+				message: `${tableName}.${colName} is NOT NULL in the database but nullable in the manifest; writes that store NULL will fail. ${this.relaxHint("drop the constraint")}`
+			}
+		}));
 		return changes;
 	}
+	/**
+	* Assemble an `alter_column` change.
+	*
+	* - `statements: null` means the engine cannot alter the column in place
+	*   (SQLite): the change is reported as manual with advisory-comment SQL.
+	* - `relaxation` marks a weakening change: without `relaxColumns` it is
+	*   emitted as a report-only advisory (no SQL); with it, the statements are
+	*   executable.
+	*/
+	buildAlterColumnChange(input) {
+		const { tableName, colName, colDef, alteration, expected, actual, statements, relaxation } = input;
+		const base = {
+			type: "alter_column",
+			table: tableName,
+			name: colName,
+			column: colDef,
+			alteration,
+			mismatch: {
+				expected,
+				actual
+			}
+		};
+		if (relaxation && !this.options.relaxColumns) return {
+			...base,
+			advisory: {
+				severity: relaxation.severity,
+				message: relaxation.message,
+				suggestedSql: statements ?? [`-- SQLite cannot ALTER COLUMN; ${alteration === "drop_not_null" ? "dropping NOT NULL" : "dropping the default"} requires a table rebuild (#2370)`]
+			}
+		};
+		if (statements === null) {
+			const what = alteration === "set_not_null" ? `enforcing NOT NULL on ${colName}` : alteration === "drop_not_null" ? `dropping NOT NULL from ${colName}` : alteration === "set_default" ? `setting the default on ${colName}` : `dropping the default from ${colName}`;
+			return {
+				...base,
+				sql: `-- SQLite: ${what} requires table recreation (expected ${expected}, found ${actual}; #2370)`
+			};
+		}
+		return {
+			...base,
+			sql: statements[statements.length - 1],
+			...statements.length > 1 ? { sqlStatements: statements } : {}
+		};
+	}
+	/**
+	* Describe a DB column that has no manifest counterpart. Blocking when it
+	* is NOT NULL without a default: ORM inserts never supply it, so every
+	* insert fails with a not-null violation while `db:status` would otherwise
+	* say the schema is in sync (#2369).
+	*/
+	describeOrphanColumn(tableName, colName, dbCol) {
+		const dbHasDefault = dbCol.defaultValue !== null && dbCol.defaultValue !== void 0;
+		const blocking = dbCol.notNull === true && !dbHasDefault;
+		const quotedTable = this.quoteIdentifier(tableName);
+		const quotedCol = this.quoteIdentifier(colName);
+		const dropSql = `ALTER TABLE ${quotedTable} DROP COLUMN ${quotedCol}`;
+		const relaxSql = `ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedCol} DROP NOT NULL`;
+		const shape = this.describeDbColumn(dbCol);
+		const base = {
+			type: "orphan_column",
+			table: tableName,
+			name: colName,
+			mismatch: {
+				expected: "(not in manifest)",
+				actual: shape
+			}
+		};
+		if (!blocking) return {
+			...base,
+			advisory: {
+				severity: "info",
+				message: `${tableName}.${colName} exists in the database but not in the manifest (${shape}). Harmless for inserts; pass includeDroppedColumns / --drop-columns to drop it.`,
+				suggestedSql: [dropSql]
+			}
+		};
+		if (this.options.relaxColumns && this.supportsAlterColumn()) return {
+			type: "alter_column",
+			table: tableName,
+			name: colName,
+			alteration: "drop_not_null",
+			mismatch: {
+				expected: "(not in manifest)",
+				actual: shape
+			},
+			sql: relaxSql
+		};
+		const fix = this.supportsAlterColumn() ? `Pass relaxColumns / --relax-columns to drop the NOT NULL (keeps data), or includeDroppedColumns / --drop-columns to drop the column.` : `SQLite cannot drop NOT NULL in place; pass includeDroppedColumns / --drop-columns to drop the column (or rebuild the table, #2370).`;
+		return {
+			...base,
+			advisory: {
+				severity: "warning",
+				message: `${tableName}.${colName} is NOT NULL without a default and is not in the manifest — every ORM insert into ${tableName} will fail (not-null violation). ${fix}`,
+				suggestedSql: this.supportsAlterColumn() ? [relaxSql, dropSql] : [dropSql]
+			}
+		};
+	}
+	/**
+	* Remediation hint for a relaxation advisory. On engines with `ALTER
+	* COLUMN` the flag executes it; SQLite cannot relax in place, so the hint
+	* says so instead of implying the flag will act (#2370).
+	*/
+	relaxHint(action) {
+		return this.supportsAlterColumn() ? `Pass relaxColumns / --relax-columns to ${action}.` : `SQLite cannot ${action} in place (no ALTER COLUMN); it requires a table rebuild (#2370) — relaxColumns / --relax-columns only reports it as manual here.`;
+	}
+	describeDbColumn(dbCol) {
+		const parts = [String(dbCol.type ?? "").toUpperCase() || "UNKNOWN"];
+		if (dbCol.notNull) parts.push("NOT NULL");
+		if (dbCol.defaultValue !== null && dbCol.defaultValue !== void 0) parts.push(`DEFAULT ${String(dbCol.defaultValue)}`);
+		return parts.join(" ");
+	}
+	/**
+	* Whether the engine can alter nullability/defaults of an existing column
+	* in place. SQLite cannot (`ALTER TABLE ... ALTER COLUMN` does not exist);
+	* PostgreSQL, DuckDB and the DuckDB-backed JSON adapter can.
+	*/
+	supportsAlterColumn() {
+		return this.engine !== "sqlite";
+	}
+	generateSetDefaultSQL(tableName, colName, formattedDefault, validatedType) {
+		const defaultSql = this.engine === "postgres" && this.normalizeType(validatedType) === "JSON" ? `${formattedDefault}::${this.ddlStrategy.mapType(validatedType).toLowerCase()}` : formattedDefault;
+		return `ALTER TABLE ${this.quoteIdentifier(tableName)} ALTER COLUMN ${this.quoteIdentifier(colName)} SET DEFAULT ${defaultSql}`;
+	}
+	/**
+	* Live-data probe: does the table hold any row? Used to decide whether an
+	* added required column without a default can be enforced NOT NULL right
+	* away. Errors (adapter without raw query, etc.) resolve to `true` so the
+	* caller takes the conservative path.
+	*/
+	async tableHasRows(tableName) {
+		try {
+			return ((await this.db.query(`SELECT 1 AS present FROM ${this.quoteIdentifier(tableName)} LIMIT 1`)).rows?.length ?? 0) > 0;
+		} catch (err) {
+			logger.debug(`[SchemaComparer] Row probe unavailable for ${tableName}; assuming populated`, { error: err instanceof Error ? err.message : String(err) });
+			return true;
+		}
+	}
+	/**
+	* Live-data probe: does the column hold any NULL? Used before emitting a
+	* `SET NOT NULL` that has no default to backfill with. Errors resolve to
+	* `true` (conservative: report instead of emitting an ALTER that fails).
+	*/
+	async columnHasNulls(tableName, colName) {
+		try {
+			return ((await this.db.query(`SELECT 1 AS present FROM ${this.quoteIdentifier(tableName)} WHERE ${this.quoteIdentifier(colName)} IS NULL LIMIT 1`)).rows?.length ?? 0) > 0;
+		} catch (err) {
+			logger.debug(`[SchemaComparer] NULL probe unavailable for ${tableName}.${colName}; assuming NULLs exist`, { error: err instanceof Error ? err.message : String(err) });
+			return true;
+		}
+	}
 	isUuidTextEquivalentColumn(columnName, colDef, normalizedExpected, normalizedActual) {
 		if (!(normalizedExpected === "UUID" && normalizedActual === "TEXT") && !(normalizedExpected === "TEXT" && normalizedActual === "UUID")) return false;
 		return this.isStructuralUuidCompatibleColumn(columnName, colDef);
@@ -273,7 +731,10 @@ var SchemaComparer = class {
 	*    caller opts in via `includeDroppedIndexes`, and even then never for
 	*    PostgreSQL implicit indexes (`*_pkey`, `*_key`) — those are owned by
 	*    table-level constraints and need a separate `DROP CONSTRAINT` path
-	*    that the differ does not emit yet.
+	*    that the differ does not emit yet. One exception is unconditional: a
+	*    redundant single-column index over the live primary key (the legacy
+	*    `<table>_id_idx`, #2359) is dropped even without the opt-in, because
+	*    the primary-key constraint already serves it.
 	*
 	* 4. **Partial-index predicate drift / collision** — two indexes on the
 	*    same column(s) and uniqueness that differ only by their `WHERE`
@@ -292,6 +753,8 @@ var SchemaComparer = class {
 		const predicateAware = dbIndexPredicates !== null;
 		const dbPredicateFor = (name) => predicateAware ? dbIndexPredicates?.get(name) ?? "" : "";
 		const manifestPredicateFor = (idx) => predicateAware ? normalizeIndexPredicate(idx.where) : "";
+		const manifestIndexes = this.supportsPartialIndexes() ? manifest.indexes : manifest.indexes.filter((idx) => !isStiSubtypeUniqueIndex(idx));
+		const primaryKeyColumns = Object.entries(dbSchema.columns).filter(([, column]) => column.primaryKey === true).map(([name]) => name);
 		const dbIndexesByName = /* @__PURE__ */ new Map();
 		const dbIndexSignatures = /* @__PURE__ */ new Map();
 		for (const idx of dbSchema.indexes) {
@@ -309,9 +772,9 @@ var SchemaComparer = class {
 			bucket.add(idx.name);
 		}
 		const manifestSignatureSet = /* @__PURE__ */ new Set();
-		for (const idx of manifest.indexes) manifestSignatureSet.add(this.getIndexSignature(idx, void 0, manifestPredicateFor(idx)));
+		for (const idx of manifestIndexes) manifestSignatureSet.add(this.getIndexSignature(idx, void 0, manifestPredicateFor(idx)));
 		const claimedDbIndexes = /* @__PURE__ */ new Set();
-		for (const idx of manifest.indexes) {
+		for (const idx of manifestIndexes) {
 			const manifestSignature = this.getIndexSignature(idx, void 0, manifestPredicateFor(idx));
 			const dbByName = dbIndexesByName.get(idx.name);
 			if (dbByName) {
@@ -346,11 +809,31 @@ var SchemaComparer = class {
 				sql: this.generateAddIndexSQL(tableName, idx)
 			});
 		}
-		if (this.options.includeDroppedIndexes) for (const idx of dbSchema.indexes) {
+		for (const idx of dbSchema.indexes) {
 			if (claimedDbIndexes.has(idx.name)) continue;
-			if (isProtectedDbIndexName(idx.name)) continue;
 			const idxSignature = this.getIndexSignature(idx.columns, idx.unique ?? false, dbPredicateFor(idx.name));
 			if (manifestSignatureSet.has(idxSignature)) continue;
+			if (isProtectedDbIndexName(idx.name)) {
+				if (!idx.unique || idx.name.endsWith("_pkey")) continue;
+				if (idx.columns.length === 1 && manifest.columns[idx.columns[0]]?.unique === true) continue;
+				const cols = idx.columns.map((c) => this.quoteIdentifier(c)).join(", ");
+				changes.push({
+					type: "orphan_index",
+					table: tableName,
+					name: idx.name,
+					mismatch: {
+						expected: "(not in manifest)",
+						actual: `UNIQUE (${idx.columns.join(", ")})`
+					},
+					advisory: {
+						severity: "warning",
+						message: `Unique constraint ${idx.name} on ${tableName}(${idx.columns.join(", ")}) is no longer declared by the manifest; duplicate values the model now allows will still be rejected. Drop it manually.`,
+						suggestedSql: this.engine === "postgres" ? [`ALTER TABLE ${this.quoteIdentifier(tableName)} DROP CONSTRAINT IF EXISTS ${this.quoteIdentifier(idx.name)}`, `DROP INDEX IF EXISTS ${this.quoteIdentifier(idx.name)} -- if it is a plain unique index on ${cols} rather than a constraint`] : [this.generateDropIndexSQL(idx.name)]
+					}
+				});
+				continue;
+			}
+			if (!(idx.unique !== true && idx.columns.length === 1 && dbPredicateFor(idx.name) === "" && primaryKeyColumns.length === 1 && primaryKeyColumns[0] === idx.columns[0]) && !this.options.includeDroppedIndexes) continue;
 			changes.push({
 				type: "drop_index",
 				table: tableName,
@@ -529,7 +1012,7 @@ var SchemaComparer = class {
 		switch (this.engine) {
 			case "sqlite":
 				if (this.normalizeType(manifestType) === "JSON" && this.normalizeType(dbType) === "TEXT") return { sql: `-- SQLite: ${quotedCol} already stores JSON as TEXT (no change needed)` };
-				return { sql: `-- SQLite: Type upgrade for ${quotedCol} requires table recreation` };
+				return { sql: sqliteRebuildPlaceholderSql(colName) };
 			case "postgres": {
 				const manifestNormalized = this.normalizeType(manifestType);
 				const dbNormalized = this.normalizeType(dbType);
@@ -593,21 +1076,88 @@ var SchemaComparer = class {
 		return `'${value.replace(/'/g, "''")}'`;
 	}
 	/**
-	* Generate SQL for adding a column
+	* Plan the changes that add a missing column so the emitted DDL is
+	* executable on the active engine (#2369).
+	*
+	* Engines disagree on what `ALTER TABLE ... ADD COLUMN` may carry inline
+	* (probed on SQLite 3.4x/3.5x, DuckDB 1.4.x, PostgreSQL 16/17):
+	*
+	* | clause          | SQLite                         | DuckDB   | PostgreSQL          |
+	* |-----------------|--------------------------------|----------|---------------------|
+	* | NOT NULL + DEF  | ok                             | rejected | ok                  |
+	* | NOT NULL, no DEF| ok on empty, rejected populated| rejected | ok empty, rej. pop. |
+	* | UNIQUE          | rejected                       | rejected | ok                  |
+	* | DEFAULT         | ok                             | ok       | ok                  |
+	* | CHECK           | ok                             | rejected | ok                  |
+	*
+	* so the plan is:
+	* - `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
+	*   (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.
+	* - `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).
+	* - `CHECK`: inline where accepted; DuckDB rejects it in ADD COLUMN, so it
+	*   is dropped there with a warning (SMRT's generators never emit `check`).
+	*
+	* The primary `add_column` change carries the whole plan in
+	* `sqlStatements` (and the last statement in `sql`) so both the CLI and the
+	* orchestrator execute it as one unit.
 	*/
-	generateAddColumnSQL(tableName, colName, colDef) {
+	async generateAddColumnChanges(tableName, colName, colDef) {
 		const validatedType = isValidSQLDataType(colDef.type) ? colDef.type : "TEXT";
 		if (!isValidSQLDataType(colDef.type)) logger.warn(`[SchemaComparer] Invalid manifest type "${colDef.type}" for ${tableName}.${colName}, treating as TEXT`);
-		const parts = [this.quoteIdentifier(colName), this.ddlStrategy.mapType(validatedType)];
-		if (colDef.notNull) parts.push("NOT NULL");
-		if (colDef.unique) parts.push("UNIQUE");
-		if (colDef.defaultValue !== void 0) {
-			const defaultVal = this.ddlStrategy.formatDefaultValue(colDef.defaultValue, validatedType);
-			parts.push(`DEFAULT ${defaultVal}`);
-		}
-		if (colDef.check) parts.push(`CHECK (${colDef.check})`);
-		const columnDefinition = parts.join(" ");
-		return `ALTER TABLE ${this.quoteIdentifier(tableName)} ADD COLUMN ${columnDefinition}`;
+		const quotedTable = this.quoteIdentifier(tableName);
+		const quotedCol = this.quoteIdentifier(colName);
+		const parts = [quotedCol, this.ddlStrategy.mapType(validatedType)];
+		const followUps = [];
+		const extraChanges = [];
+		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`;
+		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)`]
+			}
+		});
+		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 (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})`);
+		const statements = [addColumn, ...followUps];
+		return [{
+			type: "add_column",
+			table: tableName,
+			name: colName,
+			column: colDef,
+			sql: addColumn,
+			...statements.length > 1 ? { sqlStatements: statements } : {}
+		}, ...extraChanges];
 	}
 	/**
 	* Generate SQL for dropping a column
@@ -626,11 +1176,16 @@ var SchemaComparer = class {
 	* reject partial indexes — the predicate is dropped so the emitted DDL stays
 	* executable (a partial index degrades to a full index there). The predicate
 	* is trimmed and a redundant leading `WHERE` stripped for robustness.
+	*
+	* `IF NOT EXISTS` matches the canonical `generateIndexes()` DDL path and
+	* makes a retry after a partially applied batch repair the schema instead of
+	* erroring on the indexes that did land (issue #2362). All three engines
+	* (SQLite, PostgreSQL, DuckDB) accept the clause.
 	*/
 	generateAddIndexSQL(tableName, idx) {
 		const uniqueStr = idx.unique ? "UNIQUE " : "";
 		const target = renderIndexTarget(idx, this.engine);
-		let sql = `CREATE ${uniqueStr}INDEX ${this.quoteIdentifier(idx.name)} ON ${this.quoteIdentifier(tableName)} (${target})`;
+		let sql = `CREATE ${uniqueStr}INDEX IF NOT EXISTS ${this.quoteIdentifier(idx.name)} ON ${this.quoteIdentifier(tableName)} (${target})`;
 		const where = idx.where?.trim().replace(/^WHERE\s+/i, "");
 		if (this.supportsPartialIndexes() && where) sql += ` WHERE ${where}`;
 		return sql;
@@ -660,22 +1215,30 @@ async function generateSchemaDiff(db, manifestSchemas, options = {}) {
 	return new SchemaComparer(db, options).compare(manifestSchemas);
 }
 /**
-* Check if a diff has any actionable changes (excluding type mismatches)
+* Check if a diff has any actionable changes — a table to create or drop, or
+* a change with executable DDL. Incompatible type mismatches, report-only
+* advisories (orphan columns/indexes, relaxations the caller has not opted
+* into) and comment-only changes (SQLite in-place limitations, live data
+* blocking a repair) are not actionable; they surface through
+* `unactionableChanges` / the CLI's manual bucket instead.
 */
 function hasActionableChanges(diff) {
 	if (diff.added_tables.length > 0) return true;
 	if (diff.dropped_tables.length > 0) return true;
-	return diff.changes.some((c) => c.type !== "type_mismatch");
+	return diff.changes.some((c) => !isManualOrAdvisoryChange(c));
 }
 /**
-* Get SQL statements from a diff for execution
+* Get SQL statements from a diff for execution. Advisory-only changes carry
+* no statements and are skipped; comment-only statements (SQLite in-place
+* limitations) pass through unchanged so callers can filter them the way
+* they already do for `type_upgrade`.
 */
 function getSQLFromDiff(diff) {
 	const statements = [];
-	for (const change of diff.changes) if (change.type !== "type_mismatch") statements.push(...change.sqlStatements ?? (change.sql ? [change.sql] : []));
+	for (const change of diff.changes) if (change.type !== "type_mismatch" && !isAdvisoryOnlyChange(change)) statements.push(...change.sqlStatements ?? (change.sql ? [change.sql] : []));
 	return statements;
 }
 //#endregion
-export { SchemaComparer, extractIndexPredicate, generateSchemaDiff, getSQLFromDiff, hasActionableChanges, normalizeIndexPredicate };
+export { SchemaComparer, canonicalizeDefault, extractIndexPredicate, generateSchemaDiff, getSQLFromDiff, hasActionableChanges, isAdvisoryOnlyChange, isInfoOnlyChange, isManualOrAdvisoryChange, normalizeIndexPredicate, uniqueColumnIndexName };
 
 //# sourceMappingURL=differ.js.map