@atscript/db 0.1.154 → 0.1.156

package/dist/sync.cjs

@@ -1,6 +1,174 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_db_error = require("./db-error-JcfJqqpk.cjs");
-const require_column_diff = require("./column-diff-qnzx1o3c.cjs");
+const require_column_diff = require("./column-diff-DpeUbhEI.cjs");
+const require_validator = require("./validator-B4YDLUkj.cjs");
+//#region src/schema/json-column-copy.ts
+const NONE = {
+	copies: [],
+	jsonify: [],
+	errors: []
+};
+/** A text column type of the old layout (`TEXT`, `LONGTEXT`, `VARCHAR(n)`, `character varying`). */
+const TEXT_TYPE = /text|char|clob/i;
+/**
+* Design types a stored snapshot gives a field whose column held a whole
+* value as JSON text: the old union layout (`union`), or `@db.json`.
+*/
+const JSON_TEXT_DESIGN_TYPES = new Set([
+	"union",
+	"json",
+	"object"
+]);
+/** How a target column reads its value out of the JSON, or why it cannot. */
+function targetKind(fd) {
+	if (fd.encrypted) return { problem: "it is @db.encrypted" };
+	if (fd.isGeoPoint) return { problem: "it is a db.geoPoint" };
+	if (fd.storage === "json") return "json";
+	return fd.designType === "boolean" ? "boolean" : "text";
+}
+/** Whether `type` is a union one of whose value members is a string. */
+function hasStringMember(type) {
+	if (type?.type.kind !== "union") return false;
+	return require_validator.unionValueMembers(type).members.some((m) => require_column_diff.resolveDesignType(m) === "string");
+}
+/**
+* Plans {@link TJsonColumnMigration} for one table from its live column diff
+* (and its stored snapshot — on SQLite the old text column and a JSON
+* column have the same type).
+*/
+function planJsonColumnMigration(readable, diff, snapshot) {
+	const meta = readable.getMetadata();
+	if (meta.nestedObjects) return NONE;
+	const adapter = readable.dbAdapter;
+	const name = readable.tableName;
+	const removed = new Set(diff.removed.map((c) => c.name));
+	const snapshotFields = new Map(snapshot?.fields.map((f) => [f.physicalName, f]));
+	const out = {
+		copies: [],
+		jsonify: [],
+		errors: []
+	};
+	if (removed.size > 0) for (const parent of meta.flattenedParents) {
+		const source = require_column_diff.relationalColumnName(parent, void 0, parent.includes("."));
+		if (!removed.has(source)) continue;
+		const was = snapshotFields.get(source);
+		if (was && !JSON_TEXT_DESIGN_TYPES.has(was.designType)) continue;
+		const prefix = `${parent}.`;
+		const targets = [];
+		const problems = [];
+		for (const fd of meta.storedDescriptors) {
+			if (!fd.path.startsWith(prefix)) continue;
+			const kind = targetKind(fd);
+			if (typeof kind === "object") {
+				problems.push(`"${fd.physicalName}" (${kind.problem})`);
+				continue;
+			}
+			targets.push({
+				column: fd.physicalName,
+				path: fd.path.slice(prefix.length).split("."),
+				kind,
+				field: fd
+			});
+		}
+		if (targets.length === 0 && problems.length === 0) continue;
+		if (problems.length > 0 || !adapter.copyFromJsonColumn) {
+			const why = problems.length > 0 ? `cannot fill ${problems.join(", ")} from it` : "the adapter cannot copy JSON values into columns";
+			out.errors.push(`Column "${source}" of ${name} holds "${parent}" as JSON text (the layout of atscript-db ≤ 0.1.154) and ${why}. Annotate "${parent}" with @db.json to keep it in one column, or migrate the data and drop "${source}" manually.`);
+			continue;
+		}
+		out.copies.push({
+			source,
+			targets
+		});
+	}
+	const typeChanged = new Map(diff.typeChanged.map((tc) => [tc.field.physicalName, tc]));
+	for (const fd of meta.storedDescriptors) {
+		if (fd.storage !== "json" || !hasStringMember(meta.flatMap.get(fd.path))) continue;
+		const tc = typeChanged.get(fd.physicalName);
+		const old = snapshotFields.get(fd.physicalName);
+		const dotted = `${fd.physicalName}.`;
+		if (!(tc !== void 0 && TEXT_TYPE.test(tc.existingType) || old !== void 0 && old.storage !== "json" && old.designType !== "json" || diff.removed.some((c) => c.name.startsWith(dotted)))) continue;
+		if (!adapter.jsonifyTextColumn) {
+			out.errors.push(`Column "${fd.physicalName}" of ${name} becomes a JSON column but the adapter cannot convert its text values. Migrate them manually.`);
+			continue;
+		}
+		out.jsonify.push(fd.physicalName);
+	}
+	return out.copies.length > 0 || out.jsonify.length > 0 || out.errors.length > 0 ? out : NONE;
+}
+/** The copy targets {@link applyJsonColumnMigration} adds: those not in the table yet. */
+function copyTargetsToAdd(migration, diff) {
+	const targets = new Set(migration.copies.flatMap((c) => c.targets.map((t) => t.column)));
+	return diff.added.filter((fd) => targets.has(fd.physicalName));
+}
+/**
+* The column diff the rest of the table's sync applies after
+* {@link applyJsonColumnMigration}: without the copy targets it added, with
+* their NOT NULL and model default as nullability / default changes. Also
+* what `plan({ safe: true })` reports as skipped — safe mode adds and fills
+* the targets but leaves them nullable and without their default.
+*/
+function diffAfterJsonCopy(migration, diff) {
+	const toAdd = copyTargetsToAdd(migration, diff);
+	if (toAdd.length === 0) return diff;
+	return {
+		...diff,
+		added: diff.added.filter((fd) => !toAdd.includes(fd)),
+		nullableChanged: [...diff.nullableChanged, ...toAdd.filter((fd) => !fd.optional).map((fd) => ({
+			field: fd,
+			wasNullable: true
+		}))],
+		defaultChanged: [...diff.defaultChanged, ...toAdd.filter((fd) => fd.defaultValue !== void 0).map((fd) => ({
+			field: fd,
+			newDefault: require_column_diff.serializeDefaultValue(fd.defaultValue)
+		}))]
+	};
+}
+/**
+* Runs a planned {@link TJsonColumnMigration} — first, before any other
+* column work of the table: text columns become JSON text, the copy targets
+* that do not exist yet are added, and the values are copied. Returns the
+* diff without the columns it added ({@link diffAfterJsonCopy}). Idempotent:
+* a re-run converts nothing twice and copies only into rows whose targets
+* are all NULL.
+*
+* The targets are added nullable and WITHOUT a default — `ADD COLUMN …
+* DEFAULT`, or the type default an adapter gives a required column (a
+* leaf every member of a non-null union of objects declares), fills every
+* existing row, so the copy would skip them all. A model default and NOT
+* NULL are returned as default / nullability changes of the diff, which the
+* rest of the table's sync applies after the copy (`SET DEFAULT` / `SET NOT
+* NULL` / `MODIFY COLUMN`, a table recreation on SQLite). Rows the copy
+* leaves NULL keep NULL in a nullable column; a required one backfills them.
+*/
+async function applyJsonColumnMigration(adapter, migration, diff) {
+	for (const column of migration.jsonify) await adapter.jsonifyTextColumn(column);
+	if (migration.copies.length === 0) return {
+		diff,
+		added: []
+	};
+	const toAdd = copyTargetsToAdd(migration, diff);
+	let added = [];
+	if (toAdd.length > 0) added = (await adapter.syncColumns({
+		added: toAdd.map((fd) => ({
+			...fd,
+			optional: true,
+			defaultValue: void 0
+		})),
+		removed: [],
+		renamed: [],
+		typeChanged: [],
+		nullableChanged: [],
+		defaultChanged: [],
+		conflicts: []
+	})).added;
+	for (const copy of migration.copies) await adapter.copyFromJsonColumn(copy.source, copy.targets);
+	return {
+		diff: diffAfterJsonCopy(migration, diff),
+		added
+	};
+}
+//#endregion
 //#region src/schema/table-option-diff.ts
 /**
 * Computes the difference between desired and existing table options.
@@ -370,6 +538,10 @@ var SyncEntry = class SyncEntry {
 	fkChanged;
 	/** @since 0.1.141 — see {@link TSyncEntryInit.derivedChanges}. */
 	derivedChanges;
+	/** @since 0.1.155 — see {@link TSyncEntryInit.jsonCopies}. */
+	jsonCopies;
+	/** @since 0.1.155 — see {@link TSyncEntryInit.jsonified}. */
+	jsonified;
 	columnsAdded;
 	columnsRenamed;
 	columnsDropped;
@@ -404,6 +576,8 @@ var SyncEntry = class SyncEntry {
 		this.fkRemoved = init.fkRemoved ?? [];
 		this.fkChanged = init.fkChanged ?? [];
 		this.derivedChanges = init.derivedChanges ?? [];
+		this.jsonCopies = init.jsonCopies ?? [];
+		this.jsonified = init.jsonified ?? [];
 		this.columnsAdded = init.columnsAdded ?? [];
 		this.columnsRenamed = init.columnsRenamed ?? [];
 		this.columnsDropped = init.columnsDropped ?? [];
@@ -477,13 +651,13 @@ var SyncEntry = class SyncEntry {
 		const head = this.refused ? `✖ refused: ${vp}${label}` : `✗ ${vp}${label} — error`;
 		return [`  ${c.red(head)}`, ...this.errors.map((err) => `      ${c.red(err)}`)];
 	}
-	/** `! PK (id) → (code) — rebuild (table is empty)` / `— skipped (safe mode)` */
+	/** `! PK (id) → (code) — rebuild (table is empty)` / `— rebuild (rows satisfy the new key)` / `— skipped (safe mode)` */
 	printPkChange(c, mode) {
 		const pk = this.pkChange;
 		if (!pk) return [];
 		const cols = `PK (${pk.from.join(", ")}) → (${pk.to.join(", ")})`;
 		if (!pk.rebuild) return [`      ${c.yellow(`! ${cols} — skipped (safe mode)`)}`];
-		return mode === "plan" ? [`      ${c.red(`! ${cols} — rebuild (table is empty)`)}`] : [`      ${c.yellow(`~ ${cols} — rebuilt`)}`];
+		return mode === "plan" ? [`      ${c.red(`! ${cols} — rebuild (${pk.populated ? "rows satisfy the new key" : "table is empty"})`)}`] : [`      ${c.yellow(`~ ${cols} — rebuilt`)}`];
 	}
 	/**
 	* `! col: t1 → t2 — drop` (plan), or `! type col (t1 → t2) — skipped (safe
@@ -509,6 +683,11 @@ var SyncEntry = class SyncEntry {
 			return `      ${dc.reason === "kind" ? c.red(line) : c.yellow(line)}`;
 		});
 	}
+	/** `~ addr → addr__street, addr__zip — copy JSON values` / `~ extra — text values as JSON`. */
+	printJsonMigration(c, mode) {
+		const copy = mode === "plan" ? "copy JSON values" : "JSON values copied";
+		return [...this.jsonified.map((col) => `      ${c.yellow(`~ ${col} — text values as JSON`)}`), ...this.jsonCopies.map((jc) => `      ${c.yellow(`~ ${jc.from} → ${jc.to.join(", ")} — ${copy}`)}`)];
+	}
 	/** `~ col — nullable` / `~ col — default a → b`, `— skipped (safe mode)` when pending. */
 	printNullableDefaults(c) {
 		const suffix = this.skipped.includes("nullable-defaults") ? " — skipped (safe mode)" : "";
@@ -566,6 +745,7 @@ var SyncEntry = class SyncEntry {
 				`  ${c.cyan(`~ ${vp}${label} — alter${renameInfo}`)}`,
 				...this.columnsToAdd.map((col) => `      ${c.green(`+ ${col.physicalName} (${col.designType})${col.derived ? " derived" : ""} — add`)}`),
 				...this.columnsToRename.map((r) => `      ${c.yellow(`~ ${r.from} → ${r.to} — rename`)}`),
+				...this.printJsonMigration(c, "plan"),
 				...this.printTypeChanges(c),
 				...this.printNullableDefaults(c),
 				...this.printDerivedChanges(c, "plan"),
@@ -594,13 +774,14 @@ var SyncEntry = class SyncEntry {
 			...this.columnsAdded.map((col) => `      ${c.green(`+ ${col} — added`)}`),
 			""
 		];
-		if (this.columnsAdded.length > 0 || this.columnsRenamed.length > 0 || this.columnsDropped.length > 0 || this.optionChanges.length > 0 || this.pkChange !== void 0 || this.derivedChanges.length > 0 || this.skipped.length > 0 || this.recreated || this.renamedFrom) {
+		if (this.columnsAdded.length > 0 || this.columnsRenamed.length > 0 || this.columnsDropped.length > 0 || this.optionChanges.length > 0 || this.pkChange !== void 0 || this.derivedChanges.length > 0 || this.jsonCopies.length > 0 || this.jsonified.length > 0 || this.skipped.length > 0 || this.recreated || this.renamedFrom) {
 			const rlabel = this.recreated ? "recreated" : "altered";
 			const renameInfo = this.renamedFrom ? ` ${c.yellow(`(renamed from ${this.renamedFrom})`)}` : "";
 			return [
 				`  ${(this.recreated ? (s) => c.yellow(s) : (s) => c.cyan(s))(`~ ${vp}${label} — ${rlabel}${renameInfo}`)}`,
 				...this.columnsAdded.map((col) => `      ${c.green(`+ ${col} — added`)}`),
 				...this.columnsRenamed.map((col) => `      ${c.yellow(`~ ${col} — renamed`)}`),
+				...this.printJsonMigration(c, "result"),
 				...this.printPkChange(c, "result"),
 				...this.printTypeChanges(c),
 				...this.printNullableDefaults(c),
@@ -642,14 +823,19 @@ function planTableInit(facts, safe, dependsOn) {
 	};
 	const skipped = safe ? safeModeSkips(facts) : [];
 	const pk = facts.diff?.primaryKeyChanged;
-	if (pk) init.pkChange = {
-		from: pk.from,
-		to: pk.to,
-		rebuild: !skipped.includes("pk-rebuild")
-	};
+	if (pk) {
+		init.pkChange = {
+			from: pk.from,
+			to: pk.to,
+			rebuild: !skipped.includes("pk-rebuild")
+		};
+		if (facts.populated === true) init.pkChange.populated = true;
+	}
 	if (!safe) return init;
+	const diff = afterJsonCopy(facts);
 	return {
 		...init,
+		...diff && describeNullableDefaults(diff),
 		columnsToDrop: [],
 		typeChanges: skipped.includes("recreate") ? init.typeChanges : [],
 		derivedChanges: skipped.includes("derived") ? init.derivedChanges : [],
@@ -667,6 +853,7 @@ function typeChangeStrategy(readable, diff) {
 	const adapter = readable.dbAdapter;
 	if (willDropRecreate(readable, diff, void 0)) return "drop";
 	if (readable.syncMethod === "recreate" && adapter.recreateTable) return "recreate";
+	if (diff.primaryKeyChanged && !adapter.rebuildPrimaryKey && adapter.recreateTable) return "recreate";
 	if (adapter.supportsColumnModify && adapter.syncColumns) return "modify";
 	return "none";
 }
@@ -734,11 +921,23 @@ async function executeSyncTable(facts, safe, deps, exec) {
 				await adapter.ensureTable(ensureOpts);
 				init.status = "create";
 			} else if (existing.length > 0) {
-				const diff = facts.diff ?? require_column_diff.computeColumnDiff(readable.columnDescriptors, existing, adapter.typeMapper?.bind(adapter), { snapshot: storedSnapshot });
-				if (hasFkChanges && !adapter.syncForeignKeys && adapter.recreateTable) {
-					await adapter.recreateTable();
-					init.recreated = true;
+				let diff = facts.diff ?? require_column_diff.computeColumnDiff(readable.columnDescriptors, existing, adapter.typeMapper?.bind(adapter), {
+					snapshot: storedSnapshot,
+					nativeDefaultFns: adapter.nativeDefaultFns()
+				});
+				const migration = facts.jsonMigration ?? planJsonColumnMigration(readable, diff, storedSnapshot);
+				if (migration.errors.length > 0) throw new Error(migration.errors.join(" "));
+				if (migration.copies.length > 0 || migration.jsonify.length > 0) {
+					phase = "JSON column copy";
+					const applied = await applyJsonColumnMigration(adapter, migration, diff);
+					diff = applied.diff;
+					Object.assign(init, describeJsonMigration(migration));
+					if (applied.added.length > 0) init.columnsAdded = applied.added;
 					init.status = "alter";
+					phase = "Column sync";
+				}
+				if (hasFkChanges && !adapter.syncForeignKeys && adapter.recreateTable) {
+					await recreateKeepingRenames(adapter, diff, init);
 					if (diff.primaryKeyChanged) init.pkChange = {
 						...diff.primaryKeyChanged,
 						rebuild: true
@@ -747,8 +946,11 @@ async function executeSyncTable(facts, safe, deps, exec) {
 					if (hasFkChanges && fkDiff && adapter.dropForeignKeys) {
 						const keysToDrop = [...fkDiff.removed.map((fk) => require_column_diff.fkKey(fk.fields)), ...fkDiff.changed.map((fk) => require_column_diff.fkKey(require_column_diff.fkColumns(fk.desired).fields))];
 						if (keysToDrop.length > 0) {
-							await adapter.dropForeignKeys(keysToDrop);
-							droppedFks.push(...keysToDrop);
+							const fresh = keysToDrop.filter((key) => !droppedFks.includes(key));
+							if (fresh.length > 0) {
+								await adapter.dropForeignKeys(fresh);
+								droppedFks.push(...fresh);
+							}
 							init.status = "alter";
 						}
 					}
@@ -759,7 +961,10 @@ async function executeSyncTable(facts, safe, deps, exec) {
 			const existed = adapter.tableExists ? await adapter.tableExists() : false;
 			await adapter.ensureTable(ensureOpts);
 			if (!existed) init.status = "create";
-		} else await applyColumnDiff(adapter, readable, facts.diff ?? require_column_diff.computeColumnDiff(readable.columnDescriptors, require_column_diff.snapshotToExistingColumns(storedSnapshot, readable), deps.resolveTypeMapper(adapter), { snapshot: storedSnapshot }), init, safe, deps.logger, ensureOpts);
+		} else await applyColumnDiff(adapter, readable, facts.diff ?? require_column_diff.computeColumnDiff(readable.columnDescriptors, require_column_diff.snapshotToExistingColumns(storedSnapshot, readable), deps.resolveTypeMapper(adapter), {
+			snapshot: storedSnapshot,
+			nativeDefaultFns: adapter.nativeDefaultFns()
+		}), init, safe, deps.logger, ensureOpts);
 		else {
 			const existed = adapter.tableExists ? await adapter.tableExists() : true;
 			if (!init.recreated) {
@@ -798,9 +1003,10 @@ async function executeSyncTable(facts, safe, deps, exec) {
 				}
 			}
 		}
+		if (init.pkChange && facts.populated === true) init.pkChange.populated = true;
 		if (init.status === "error") return new SyncEntry(init);
 		phase = "Index/FK sync";
-		await adapter.syncIndexes();
+		await adapter.syncIndexes(keptIndexes(init));
 		if (adapter.syncForeignKeys && !exec.deferForeignKeysTo) await adapter.syncForeignKeys();
 		if (adapter.afterSyncTable) await adapter.afterSyncTable();
 	} catch (error) {
@@ -901,13 +1107,40 @@ function willDropRecreate(readable, diff, optionDiff) {
 	if (readable.syncMethod === "drop" && (diff?.typeChanged.length ?? 0) > 0) return true;
 	return (optionDiff?.changed.some((c) => c.destructive) ?? false) && !(readable.syncMethod === "recreate" && !!adapter.recreateTable);
 }
+/**
+* The column diff the executor applies after the table's JSON column copy —
+* its targets' NOT NULL and defaults deferred (see {@link diffAfterJsonCopy}).
+*/
+function afterJsonCopy(facts) {
+	return facts.diff && facts.jsonMigration ? diffAfterJsonCopy(facts.jsonMigration, facts.diff) : facts.diff;
+}
 /** Records work safe mode skipped on the entry (see `SyncEntry.skipped`). */
 function markSkipped(init, kind) {
 	init.skipped = [...init.skipped ?? [], kind];
 }
-/** Whether nullable/default changes need DDL on this adapter (schema-less ones only update the snapshot). */
+/**
+* Whether nullable/default changes need DDL on this adapter: in-place modify,
+* or a recreate on a live-introspected one (SQLite). Snapshot-based adapters
+* (MongoDB) have no column constraint to change — they only update the
+* snapshot, even with a `recreateTable`.
+*/
 function needsDdlForNullableDefaults(adapter) {
-	return !!adapter.supportsColumnModify && !!adapter.syncColumns || !!adapter.recreateTable;
+	return !!adapter.supportsColumnModify && !!adapter.syncColumns || !!adapter.recreateTable && !!adapter.getExistingColumns;
+}
+/**
+* The indexes `syncIndexes` keeps as they are because safe mode skipped
+* the change they depend on — a skipped key rebuild, the columns of a
+* skipped type-change recreate (see `TSyncIndexesOptions`).
+*/
+function keptIndexes(init) {
+	const skipped = init.skipped ?? [];
+	const keepPrimaryKey = skipped.includes("pk-rebuild");
+	const keepColumns = skipped.includes("recreate") ? (init.typeChanges ?? []).map((tc) => tc.column) : [];
+	if (!keepPrimaryKey && keepColumns.length === 0) return;
+	return {
+		keepPrimaryKey,
+		keepColumns
+	};
 }
 /**
 * The work `run({ safe: true })` skips on this table, in the order the
@@ -918,7 +1151,8 @@ function needsDdlForNullableDefaults(adapter) {
 * DDL either way.
 */
 function safeModeSkips(facts) {
-	const { readable, diff, optionDiff, fkDiff } = facts;
+	const { readable, optionDiff, fkDiff } = facts;
+	const diff = afterJsonCopy(facts);
 	const adapter = readable.dbAdapter;
 	const out = [];
 	if (facts.planEntry.status === "error") return out;
@@ -932,6 +1166,16 @@ function safeModeSkips(facts) {
 	if (optionDiff?.changed.some((c) => c.destructive)) out.push("table-options");
 	return out;
 }
+/** The plan-shaped summary of a {@link TJsonColumnMigration}. */
+function describeJsonMigration(migration) {
+	return {
+		jsonCopies: migration.copies.length > 0 ? migration.copies.map((c) => ({
+			from: c.source,
+			to: c.targets.map((t) => t.column)
+		})) : void 0,
+		jsonified: migration.jsonify.length > 0 ? migration.jsonify : void 0
+	};
+}
 /** The plan-shaped nullable / default change summaries of a diff. */
 function describeNullableDefaults(diff) {
 	return {
@@ -963,6 +1207,28 @@ async function dropAndRecreate(adapter, init, name, ensureOpts) {
 	init.recreated = true;
 	init.status = "alter";
 }
+/**
+* `recreateTable()` before the column diff is applied: it copies the rows by
+* column name, so the columns renamed in this run are renamed first — under
+* the old name their values would not be copied.
+*/
+async function recreateKeepingRenames(adapter, diff, init) {
+	if (diff.renamed.length > 0 && adapter.syncColumns) {
+		const { renamed } = await adapter.syncColumns({
+			added: [],
+			removed: [],
+			renamed: diff.renamed,
+			typeChanged: [],
+			nullableChanged: [],
+			defaultChanged: [],
+			conflicts: []
+		});
+		init.columnsRenamed = renamed;
+	}
+	await adapter.recreateTable();
+	init.recreated = true;
+	init.status = "alter";
+}
 async function applyColumnDiff(adapter, readable, diff, init, safe, logger, ensureOpts) {
 	const name = readable.tableName;
 	if (diff.conflicts.length > 0) {
@@ -981,11 +1247,8 @@ async function applyColumnDiff(adapter, readable, diff, init, safe, logger, ensu
 			const cols = init.typeChanges.map((tc) => `${tc.column}: ${tc.fromType} → ${tc.toType}`).join(", ");
 			logger.warn?.(`[schema-sync] Type change on "${name}" (${cols}) — drop-and-recreate skipped (safe mode)`);
 		} else await dropAndRecreate(adapter, init, name, ensureOpts);
-		else if (strategy === "recreate") {
-			await adapter.recreateTable();
-			init.recreated = true;
-			init.status = "alter";
-		} else if (strategy === "modify") {
+		else if (strategy === "recreate") await recreateKeepingRenames(adapter, diff, init);
+		else if (strategy === "modify") {
 			needsSyncColumns = true;
 			init.status = "alter";
 		} else {
@@ -999,11 +1262,8 @@ async function applyColumnDiff(adapter, readable, diff, init, safe, logger, ensu
 		if (!safe && !init.recreated && init.status !== "error") if (adapter.supportsColumnModify && adapter.syncColumns) {
 			needsSyncColumns = true;
 			init.status = "alter";
-		} else if (adapter.recreateTable) {
-			await adapter.recreateTable();
-			init.recreated = true;
-			init.status = "alter";
-		} else init.status = "alter";
+		} else if (needsDdlForNullableDefaults(adapter)) await recreateKeepingRenames(adapter, diff, init);
+		else init.status = "alter";
 		else if (init.status !== "error") {
 			if (safe && !init.recreated && needsDdlForNullableDefaults(adapter)) {
 				Object.assign(init, describeNullableDefaults(diff));
@@ -1015,7 +1275,7 @@ async function applyColumnDiff(adapter, readable, diff, init, safe, logger, ensu
 	}
 	if (!init.recreated && init.status !== "error" && (diff.added.length > 0 || diff.renamed.length > 0 || needsSyncColumns) && adapter.syncColumns) {
 		const syncResult = await adapter.syncColumns(diff);
-		init.columnsAdded = syncResult.added;
+		init.columnsAdded = [...init.columnsAdded ?? [], ...syncResult.added];
 		init.columnsRenamed = syncResult.renamed;
 		if (syncResult.added.length > 0 || (syncResult.renamed?.length ?? 0) > 0 || needsSyncColumns) init.status = "alter";
 	}
@@ -1580,8 +1840,18 @@ var SchemaSync = class {
 				init.columnsToAdd = [...readable.columnDescriptors];
 			} else if (facts.existing && facts.existing.length > 0) {
 				const typeMapper = adapter.typeMapper?.bind(adapter);
-				facts.diff = require_column_diff.computeColumnDiff(readable.columnDescriptors, facts.existing, typeMapper, { snapshot: storedSnapshot });
+				facts.diff = require_column_diff.computeColumnDiff(readable.columnDescriptors, facts.existing, typeMapper, {
+					snapshot: storedSnapshot,
+					nativeDefaultFns: adapter.nativeDefaultFns()
+				});
 				this.populatePlanFromDiff(facts.diff, init, readable, safe);
+				const migration = planJsonColumnMigration(readable, facts.diff, storedSnapshot);
+				facts.jsonMigration = migration;
+				Object.assign(init, describeJsonMigration(migration));
+				if (migration.errors.length > 0) {
+					init.status = "error";
+					init.errors = [...init.errors ?? [], ...migration.errors];
+				} else if (init.status === "in-sync" && (migration.copies.length > 0 || migration.jsonify.length > 0)) init.status = "alter";
 			}
 		} else if (adapter.syncColumns) if (!storedSnapshot) {
 			if (!pendingRename) {
@@ -1592,7 +1862,10 @@ var SchemaSync = class {
 			}
 		} else {
 			const existing = require_column_diff.snapshotToExistingColumns(storedSnapshot, readable);
-			facts.diff = require_column_diff.computeColumnDiff(readable.columnDescriptors, existing, this.resolveTypeMapper(adapter), { snapshot: storedSnapshot });
+			facts.diff = require_column_diff.computeColumnDiff(readable.columnDescriptors, existing, this.resolveTypeMapper(adapter), {
+				snapshot: storedSnapshot,
+				nativeDefaultFns: adapter.nativeDefaultFns()
+			});
 			this.populatePlanFromDiff(facts.diff, init, readable, safe);
 		}
 		else if (adapter.tableExists) {
@@ -1627,7 +1900,16 @@ var SchemaSync = class {
 				}, fk.existing)
 			}));
 		}
-		if (facts.diff?.primaryKeyChanged) facts.populated = await adapter.hasRows(pendingRename ? dbName : void 0) ?? "unknown";
+		if (facts.diff?.primaryKeyChanged) {
+			const tableName = pendingRename ? dbName : void 0;
+			facts.populated = await adapter.hasRows(tableName) ?? "unknown";
+			const { added, renamed } = facts.diff;
+			const { to } = facts.diff.primaryKeyChanged;
+			if (facts.populated === true && adapter.countKeyViolations && !added.some((f) => to.includes(f.physicalName))) {
+				const liveName = new Map(renamed.map((r) => [r.field.physicalName, r.oldName]));
+				facts.keyViolations = await adapter.countKeyViolations(to.map((c) => liveName.get(c) ?? c), tableName);
+			}
+		}
 		facts.dropsTable = !!facts.diff?.primaryKeyChanged || willDropRecreate(readable, facts.diff, facts.optionDiff);
 		if (facts.diff?.primaryKeyChanged || probeRecreateInbound && facts.dropsTable) facts.inboundFks = await adapter.getReferencingForeignKeys?.(dbName);
 		if (adapter.getObjectKind) facts.objectKind = await adapter.getObjectKind(dbName);
@@ -1644,7 +1926,7 @@ var SchemaSync = class {
 			const pk = t.diff?.primaryKeyChanged;
 			if (pk) {
 				const label = pkLabel(pk);
-				if (t.populated === true) addRefusal(refusals, t.name, `Primary key of "${t.name}" changed ${label} but the table has rows; schema sync cannot rebuild a populated primary key. Migrate manually (or empty the table) and re-run.`);
+				if (t.populated === true && t.keyViolations !== 0) addRefusal(refusals, t.name, t.keyViolations === void 0 ? `Primary key of "${t.name}" changed ${label} but the table has rows; schema sync cannot rebuild a populated primary key. Migrate manually (or empty the table) and re-run.` : `Primary key of "${t.name}" changed ${label} but ${t.keyViolations} row${t.keyViolations === 1 ? " has" : "s have"} a NULL or duplicate (${pk.to.join(", ")}) — fix or remove ${t.keyViolations === 1 ? "it" : "them"} (or migrate manually) and re-run.`);
 				else if (t.populated === "unknown") addRefusal(refusals, t.name, `Primary key of "${t.name}" changed ${label} but the adapter cannot tell whether the table has rows under its old name "${t.dbName}" — implement hasRows(tableName) on the adapter, or rename the table in a separate run first.`);
 				if (!safe) {
 					const liveInbound = (t.inboundFks ?? []).filter((fk) => {

package/dist/sync.d.cts

@@ -1,5 +1,5 @@
-import { $t as DbSpace, At as TReferencingForeignKey, Ft as TTableOptionDiff, Gn as TGenericLogger, U as TDbFieldMeta, et as TDbObjectKind, gt as TEnsureTableOptions, kt as TPrimaryKeyChange, mt as TDerivedChangeReason, vt as TExistingForeignKey, yt as TExistingTableOption } from "./buckets-jy8BfswO.cjs";
-import { _ as computeTableSnapshot, a as hasForeignKeyChanges, b as snapshotToExistingTableOptions, c as TFieldSnapshot, d as TViewColumnSnapshot, f as TViewJoinSnapshot, g as computeTableHash, h as computeSchemaHash, i as fkKey, l as TForeignKeySnapshot, m as canonicalizeQueryNode, n as computeForeignKeyDiff, o as computeColumnDiff, p as TViewSnapshot, t as TForeignKeyDiff, u as TTableSnapshot, v as computeViewSnapshot, y as snapshotToExistingColumns } from "./fk-diff-D1mrLMjU.cjs";
+import { At as TPrimaryKeyChange, Jn as TGenericLogger, Lt as TTableOptionDiff, U as TDbFieldMeta, et as TDbObjectKind, gt as TEnsureTableOptions, jt as TReferencingForeignKey, mt as TDerivedChangeReason, nn as DbSpace, vt as TExistingForeignKey, yt as TExistingTableOption } from "./buckets-B4T_alUe.cjs";
+import { _ as computeTableSnapshot, a as hasForeignKeyChanges, b as snapshotToExistingTableOptions, c as TFieldSnapshot, d as TViewColumnSnapshot, f as TViewJoinSnapshot, g as computeTableHash, h as computeSchemaHash, i as fkKey, l as TForeignKeySnapshot, m as canonicalizeQueryNode, n as computeForeignKeyDiff, o as computeColumnDiff, p as TViewSnapshot, t as TForeignKeyDiff, u as TTableSnapshot, v as computeViewSnapshot, y as snapshotToExistingColumns } from "./fk-diff-BWdQ7kRZ.cjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/schema/sync-entry.d.ts
@@ -77,6 +77,22 @@ interface TSyncEntryInit {
    * @since 0.1.141
    */
   derivedChanges?: TSyncDerivedChange[];
+  /**
+   * Text columns of the atscript-db ≤ 0.1.154 union layout whose JSON values
+   * the run copies into the columns that replace them, before the old
+   * column is dropped (see `planJsonColumnMigration`).
+   * @since 0.1.155
+   */
+  jsonCopies?: Array<{
+    from: string;
+    to: string[];
+  }>;
+  /**
+   * Text columns of that layout becoming JSON columns: their plain-text
+   * values are rewritten as JSON strings first.
+   * @since 0.1.155
+   */
+  jsonified?: string[];
   columnsAdded?: string[];
   columnsRenamed?: string[];
   columnsDropped?: string[];
@@ -85,14 +101,17 @@ interface TSyncEntryInit {
   renamedFrom?: string;
   /**
    * The table's primary-key field set changes. `rebuild: true` when sync
-   * rebuilds the key (empty table); `false` when the rebuild is skipped
-   * (safe mode). A populated table is refused instead (see `refused`).
+   * rebuilds the key; `false` when the rebuild is skipped (safe mode).
+   * `populated: true` (since 0.1.155) when the table has rows — they satisfy
+   * the new key; a populated table whose rows do not is refused instead (see
+   * `refused`).
    * @since 0.1.128
    */
   pkChange?: {
     from: string[];
     to: string[];
     rebuild: boolean;
+    populated?: boolean;
   };
   /**
    * The work safe mode skipped on this table: `"pk-rebuild"` (`pkChange`
@@ -174,6 +193,13 @@ declare class SyncEntry {
   }>;
   /** @since 0.1.141 — see {@link TSyncEntryInit.derivedChanges}. */
   readonly derivedChanges: TSyncDerivedChange[];
+  /** @since 0.1.155 — see {@link TSyncEntryInit.jsonCopies}. */
+  readonly jsonCopies: Array<{
+    from: string;
+    to: string[];
+  }>;
+  /** @since 0.1.155 — see {@link TSyncEntryInit.jsonified}. */
+  readonly jsonified: string[];
   readonly columnsAdded: string[];
   readonly columnsRenamed: string[];
   readonly columnsDropped: string[];
@@ -185,6 +211,7 @@ declare class SyncEntry {
     from: string[];
     to: string[];
     rebuild: boolean;
+    populated?: boolean;
   };
   /** @since 0.1.128 — see {@link TSyncEntryInit.skipped}. */
   readonly skipped: ReadonlyArray<TSyncSkippedWork>;
@@ -229,7 +256,7 @@ declare class SyncEntry {
   print(mode: "plan" | "result", colors?: TSyncColors): string[];
   private labelAndPrefix;
   private printError;
-  /** `! PK (id) → (code) — rebuild (table is empty)` / `— skipped (safe mode)` */
+  /** `! PK (id) → (code) — rebuild (table is empty)` / `— rebuild (rows satisfy the new key)` / `— skipped (safe mode)` */
   private printPkChange;
   /**
    * `! col: t1 → t2 — drop` (plan), or `! type col (t1 → t2) — skipped (safe
@@ -241,6 +268,8 @@ declare class SyncEntry {
    * `— rebuilt` (result), or `! … — skipped (safe mode)` when pending.
    */
   private printDerivedChanges;
+  /** `~ addr → addr__street, addr__zip — copy JSON values` / `~ extra — text values as JSON`. */
+  private printJsonMigration;
   /** `~ col — nullable` / `~ col — default a → b`, `— skipped (safe mode)` when pending. */
   private printNullableDefaults;
   /**