firstly 0.10.1 → 0.10.3

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # firstly
 
+## 0.10.3
+
+### Patch Changes
+
+- [#372](https://github.com/jycouet/firstly/pull/372) [`09cf999`](https://github.com/jycouet/firstly/commit/09cf999c92fde427c013e4bfc24136f512abd3f3) Thanks [@jycouet](https://github.com/jycouet)! - sqlAdmin: opt-in schema drift checks (`drift: { relationIndexes, primaryKeys, nullable, orphanColumns }`) with a `<SqlDrift />` UI to dry-run and apply, plus `sqlCreateIndex` / `collectEntities` helpers.
+
+## 0.10.2
+
+### Patch Changes
+
+- [#366](https://github.com/jycouet/firstly/pull/366) [`2c661f6`](https://github.com/jycouet/firstly/commit/2c661f6474b8614733e5494e7deda3cd069aed9c) Thanks [@jycouet](https://github.com/jycouet)! - `ff` handles: read failed writes through `errorMessage()`. Remult rejects with a plain object, not
+  an `Error`, so `handle.error` used to end up as the string `[object Object]` on a 403.
+
 ## 0.10.1
 
 ### Patch Changes

package/esm/sqlAdmin/SqlDriftController.d.ts

@@ -0,0 +1,54 @@
+import { SqlDatabase, type ClassType } from 'remult';
+export type SqlDriftFlag = 'relationIndexes' | 'primaryKeys' | 'nullable' | 'orphanColumns';
+export type SqlDriftOptions = {
+    /** Every registered entity. A getter, since the module list usually holds `sqlAdmin()` itself. */
+    entities: () => ClassType<unknown>[];
+    /** Index `toOne` FK columns not already covered by an index (the PK counts). */
+    relationIndexes?: boolean;
+    /** Re-align live PRIMARY KEYs with each entity `id` config. */
+    primaryKeys?: boolean;
+    /** Relax `not null default ''` columns whose field is now `allowNull` (text: `''` -> NULL). */
+    nullable?: boolean;
+    /** Drop live columns no entity field declares. */
+    orphanColumns?: boolean;
+};
+type Column = {
+    table: string;
+    column: string;
+};
+export declare class SqlDriftController {
+    /** Set by the `sqlAdmin()` module's `initApi`. */
+    static options?: SqlDriftOptions;
+    static dp?: SqlDatabase;
+    private static ctx;
+    static driftFlags(): Promise<Record<SqlDriftFlag, boolean>>;
+    static relationIndexes(opts?: {
+        apply?: boolean;
+    }): Promise<{
+        applied: boolean;
+        plans: import("./server/drift/relationIndexes").RelIndexPlan[];
+    }>;
+    static primaryKeys(opts?: {
+        apply?: boolean;
+    }): Promise<{
+        applied: boolean;
+        plans: import("./server/drift/planPkSync").PkPlan[];
+    }>;
+    static nullable(opts?: {
+        apply?: boolean;
+        columns?: Column[];
+    }): Promise<{
+        applied: boolean;
+        plans: import("./server/drift/planNullableDrift").NullablePlan[];
+        fixed: import("./server/drift/planNullableDrift").NullablePlan[];
+    }>;
+    static orphanColumns(opts?: {
+        apply?: boolean;
+        columns?: Column[];
+    }): Promise<{
+        applied: boolean;
+        plans: import("./server/drift/planDropColumns").DropPlan[];
+        dropped: import("./server/drift/planDropColumns").DropPlan[];
+    }>;
+}
+export {};

package/esm/sqlAdmin/SqlDriftController.js

@@ -0,0 +1,64 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BackendMethod, remult, SqlDatabase } from 'remult';
+import { SQL_ADMINS } from './SqlAdminController';
+export class SqlDriftController {
+    /** Set by the `sqlAdmin()` module's `initApi`. */
+    static options;
+    static dp;
+    static ctx(flag) {
+        const o = SqlDriftController.options;
+        if (!o?.[flag])
+            throw new Error(`sqlAdmin({ drift: { ${flag}: true } }) is not enabled`);
+        return { db: SqlDriftController.dp ?? SqlDatabase.getDb(), entities: o.entities() };
+    }
+    static async driftFlags() {
+        const o = SqlDriftController.options;
+        return {
+            relationIndexes: !!o?.relationIndexes,
+            primaryKeys: !!o?.primaryKeys,
+            nullable: !!o?.nullable,
+            orphanColumns: !!o?.orphanColumns,
+        };
+    }
+    // Each apply shares the BackendMethod transaction: any failure rolls every statement back.
+    static async relationIndexes(opts) {
+        const { db, entities } = SqlDriftController.ctx('relationIndexes');
+        const { createRelationIndexes } = await import('./server/drift/relationIndexes');
+        return createRelationIndexes(db, entities, opts);
+    }
+    static async primaryKeys(opts) {
+        const { db, entities } = SqlDriftController.ctx('primaryKeys');
+        const { reindexPrimaryKeys } = await import('./server/drift/primaryKeys');
+        return reindexPrimaryKeys(db, entities, opts);
+    }
+    static async nullable(opts) {
+        const { db, entities } = SqlDriftController.ctx('nullable');
+        const { syncNullable } = await import('./server/drift/nullable');
+        return syncNullable(db, entities, opts);
+    }
+    static async orphanColumns(opts) {
+        const { db, entities } = SqlDriftController.ctx('orphanColumns');
+        const { dropColumns } = await import('./server/drift/orphanColumns');
+        return dropColumns(db, entities, opts);
+    }
+}
+__decorate([
+    BackendMethod({ allowed: () => remult.isAllowed(SQL_ADMINS), apiPrefix: 'ff/sqlAdmin' })
+], SqlDriftController, "driftFlags", null);
+__decorate([
+    BackendMethod({ allowed: () => remult.isAllowed(SQL_ADMINS), apiPrefix: 'ff/sqlAdmin' })
+], SqlDriftController, "relationIndexes", null);
+__decorate([
+    BackendMethod({ allowed: () => remult.isAllowed(SQL_ADMINS), apiPrefix: 'ff/sqlAdmin' })
+], SqlDriftController, "primaryKeys", null);
+__decorate([
+    BackendMethod({ allowed: () => remult.isAllowed(SQL_ADMINS), apiPrefix: 'ff/sqlAdmin' })
+], SqlDriftController, "nullable", null);
+__decorate([
+    BackendMethod({ allowed: () => remult.isAllowed(SQL_ADMINS), apiPrefix: 'ff/sqlAdmin' })
+], SqlDriftController, "orphanColumns", null);

package/esm/sqlAdmin/index.d.ts

@@ -1,8 +1,10 @@
 import { Log } from '@kitql/helpers';
 export { Roles_SqlAdmin } from './Roles_SqlAdmin';
 export { SqlAdminController, type SqlResult, type SqlTokensOptions } from './SqlAdminController';
+export { SqlDriftController, type SqlDriftFlag } from './SqlDriftController';
 export { SQL_CAPABILITIES, SQL_TOKEN_TTLS, SqlToken, SqlTokenCall, type SqlCapability, type SqlTokenTtl, } from './sqlTokenEntities';
 export { default as SqlAdmin } from './ui/SqlAdmin.svelte';
+export { default as SqlDrift } from './ui/SqlDrift.svelte';
 export { default as SqlTokens } from './ui/SqlTokens.svelte';
 export declare const key = "sqlAdmin";
 export declare const log: Log;

package/esm/sqlAdmin/index.js

@@ -1,8 +1,10 @@
 import { Log } from '@kitql/helpers';
 export { Roles_SqlAdmin } from './Roles_SqlAdmin';
 export { SqlAdminController } from './SqlAdminController';
+export { SqlDriftController } from './SqlDriftController';
 export { SQL_CAPABILITIES, SQL_TOKEN_TTLS, SqlToken, SqlTokenCall, } from './sqlTokenEntities';
 export { default as SqlAdmin } from './ui/SqlAdmin.svelte';
+export { default as SqlDrift } from './ui/SqlDrift.svelte';
 export { default as SqlTokens } from './ui/SqlTokens.svelte';
 export const key = 'sqlAdmin';
 export const log = new Log(key);

package/esm/sqlAdmin/server/drift/createIndex.d.ts

@@ -0,0 +1,29 @@
+import { type ClassType, type MembersOnly } from 'remult';
+export type IndexOptions = {
+    unique?: boolean;
+    /** Cannot be combined with a transaction (BackendMethod default). */
+    concurrently?: boolean;
+    ifNotExists?: boolean;
+    /** Override the derived `FF_IX_<table>_<cols>` / `FF_UX_...` name. */
+    name?: string;
+};
+/**
+ * Pure `CREATE INDEX` string builder. `name` / `table` / `columns` are raw
+ * identifiers; all are wrapped with `wrap` (defaults to PG double-quoting).
+ */
+export declare function formatCreateIndex(o: {
+    name: string;
+    table: string;
+    columns: string[];
+    unique?: boolean;
+    concurrently?: boolean;
+    ifNotExists?: boolean;
+    wrap?: (name: string) => string;
+}): string;
+/**
+ * Build a `CREATE INDEX` for an entity + a typed list of its fields. Resolves
+ * the real table / column db-names (and the provider's identifier quoting) via
+ * `dbNamesOf`, so it stays refactor-safe when a field's `dbName` is overridden.
+ * Returns the SQL only - the caller runs it.
+ */
+export declare function sqlCreateIndex<T>(entity: ClassType<T>, fields: (keyof MembersOnly<T> & string)[], opts?: IndexOptions): Promise<string>;

package/esm/sqlAdmin/server/drift/createIndex.js

@@ -0,0 +1,32 @@
+import { dbNamesOf } from 'remult';
+import { stripIdent } from './ident';
+/**
+ * Pure `CREATE INDEX` string builder. `name` / `table` / `columns` are raw
+ * identifiers; all are wrapped with `wrap` (defaults to PG double-quoting).
+ */
+export function formatCreateIndex(o) {
+    const wrap = o.wrap ?? ((s) => `"${s}"`);
+    const parts = ['CREATE'];
+    if (o.unique)
+        parts.push('UNIQUE');
+    parts.push('INDEX');
+    if (o.concurrently)
+        parts.push('CONCURRENTLY');
+    if (o.ifNotExists)
+        parts.push('IF NOT EXISTS');
+    parts.push(wrap(o.name), 'ON', wrap(o.table), `(${o.columns.map(wrap).join(', ')})`);
+    return parts.join(' ') + ';';
+}
+/**
+ * Build a `CREATE INDEX` for an entity + a typed list of its fields. Resolves
+ * the real table / column db-names (and the provider's identifier quoting) via
+ * `dbNamesOf`, so it stays refactor-safe when a field's `dbName` is overridden.
+ * Returns the SQL only - the caller runs it.
+ */
+export async function sqlCreateIndex(entity, fields, opts = {}) {
+    const db = await dbNamesOf(entity);
+    const table = stripIdent(db.$entityName);
+    const columns = fields.map((f) => stripIdent(db.$dbNameOf(f)));
+    const name = opts.name ?? `${opts.unique ? 'FF_UX' : 'FF_IX'}_${table}_${columns.join('_')}`;
+    return formatCreateIndex({ name, table, columns, ...opts, wrap: db.wrapIdentifier });
+}

package/esm/sqlAdmin/server/drift/ident.d.ts

@@ -0,0 +1,2 @@
+/** pg catalog / metadata names can come back quoted or schema-qualified. */
+export declare const stripIdent: (name: string) => string;

package/esm/sqlAdmin/server/drift/ident.js

@@ -0,0 +1,2 @@
+/** pg catalog / metadata names can come back quoted or schema-qualified. */
+export const stripIdent = (name) => name.replaceAll('"', '').split('.').pop();

package/esm/sqlAdmin/server/drift/nullable.d.ts

@@ -0,0 +1,31 @@
+import { type ClassType, type SqlDatabase } from 'remult';
+import { type NullablePlan } from './planNullableDrift';
+/**
+ * Audit - and optionally fix a selected subset of - nullability drift: columns whose
+ * entity field says `allowNull` while the live column is still `not null` and/or
+ * carries the schema builder's empty default. Default is a dry run.
+ *
+ * Why this is needed: `ensureSchema` writes `default '' not null` for a non-nullable
+ * field and never revisits it, so a column created before its field learned `allowNull`
+ * keeps feeding every pre-existing row an empty string the entity now types as null.
+ *
+ * Applying does up to three things per column, in this order: DROP DEFAULT, DROP NOT
+ * NULL, then (text only) rewrite the empty rows to NULL. The rewrite is the destructive
+ * part - it cannot distinguish a row that was never written from one deliberately set
+ * to '' - which is why the UI ticks nothing by default and the selection is re-checked
+ * against a freshly computed plan.
+ *
+ * Atomic inside a BackendMethod: every statement shares that method's transaction, so
+ * any failure rolls them all back.
+ */
+export declare function syncNullable(db: SqlDatabase, entities: ClassType<unknown>[], opts?: {
+    apply?: boolean;
+    columns?: {
+        table: string;
+        column: string;
+    }[];
+}): Promise<{
+    applied: boolean;
+    plans: NullablePlan[];
+    fixed: NullablePlan[];
+}>;

package/esm/sqlAdmin/server/drift/nullable.js

@@ -0,0 +1,79 @@
+import { repo } from 'remult';
+import { getRelationFieldInfo } from 'remult/internals';
+import { stripIdent } from './ident';
+import { planNullableDrift, } from './planNullableDrift';
+// Only a text column has an empty value that is unambiguously "unset". A numeric or
+// boolean default (0 / false) may be genuine data, so those columns get their
+// constraint relaxed and their rows left alone.
+const TEXT_TYPES = new Set(['character varying', 'text', 'character']);
+/**
+ * Audit - and optionally fix a selected subset of - nullability drift: columns whose
+ * entity field says `allowNull` while the live column is still `not null` and/or
+ * carries the schema builder's empty default. Default is a dry run.
+ *
+ * Why this is needed: `ensureSchema` writes `default '' not null` for a non-nullable
+ * field and never revisits it, so a column created before its field learned `allowNull`
+ * keeps feeding every pre-existing row an empty string the entity now types as null.
+ *
+ * Applying does up to three things per column, in this order: DROP DEFAULT, DROP NOT
+ * NULL, then (text only) rewrite the empty rows to NULL. The rewrite is the destructive
+ * part - it cannot distinguish a row that was never written from one deliberately set
+ * to '' - which is why the UI ticks nothing by default and the selection is re-checked
+ * against a freshly computed plan.
+ *
+ * Atomic inside a BackendMethod: every statement shares that method's transaction, so
+ * any failure rolls them all back.
+ */
+export async function syncNullable(db, entities, opts) {
+    // What each entity declares about nullability, straight from metadata.
+    const known = [];
+    for (const ent of entities) {
+        const meta = repo(ent).metadata;
+        if (meta.options.sqlExpression)
+            continue; // views: no real table
+        const table = stripIdent(meta.dbName);
+        for (const field of meta.fields.toArray()) {
+            if (getRelationFieldInfo(field))
+                continue; // FK scalars are declared by their own field
+            if (field.options.sqlExpression)
+                continue; // computed, no stored column
+            known.push({ table, column: stripIdent(field.dbName), allowNull: !!field.options.allowNull });
+        }
+    }
+    const res = await db.createCommand().execute(`
+		SELECT table_name, column_name, is_nullable, column_default, data_type
+		FROM information_schema.columns
+		WHERE table_schema = 'public'
+		ORDER BY table_name, ordinal_position;
+	`);
+    const current = res.rows.map((row) => ({
+        table: row.table_name,
+        column: row.column_name,
+        isNullable: row.is_nullable === 'YES',
+        hasDefault: row.column_default != null,
+        emptyLiteral: TEXT_TYPES.has(row.data_type) ? "''" : null,
+    }));
+    const plans = planNullableDrift(current, known);
+    let fixed = [];
+    if (opts?.apply && opts.columns?.length) {
+        const drifted = new Map(plans.map((p) => [`${p.table}.${p.column}`, p]));
+        // Only fix what is still drifted - the names then come from the catalog, not raw
+        // client input, so the interpolated identifiers are trusted.
+        fixed = opts.columns
+            .map((c) => drifted.get(`${c.table}.${c.column}`))
+            .filter((p) => !!p);
+        for (const p of fixed) {
+            const col = `ALTER TABLE "${p.table}" ALTER COLUMN "${p.column}"`;
+            if (p.dropDefault)
+                await db.createCommand().execute(`${col} DROP DEFAULT;`);
+            if (p.dropNotNull)
+                await db.createCommand().execute(`${col} DROP NOT NULL;`);
+            if (p.blankToNull) {
+                await db
+                    .createCommand()
+                    .execute(`UPDATE "${p.table}" SET "${p.column}" = NULL WHERE "${p.column}" = '';`);
+            }
+        }
+    }
+    return { applied: opts?.apply ?? false, plans, fixed };
+}

package/esm/sqlAdmin/server/drift/orphanColumns.d.ts

@@ -0,0 +1,29 @@
+import { type ClassType, type SqlDatabase } from 'remult';
+import { type DropPlan } from './planDropColumns';
+/**
+ * Audit - and optionally drop a selected subset of - orphan columns: live DB
+ * columns on an entity-backed table that no entity field declares. Default is a
+ * dry run: returns every orphan, changes nothing.
+ *
+ * Unlike the PK / relation flows (which apply the whole plan), this one is
+ * destructive, so apply takes the explicit `columns` the user ticked and drops
+ * only those - re-checking each against a freshly computed orphan set so a stale
+ * client can never drop a column that is no longer orphan.
+ *
+ * Why this is needed: Remult's auto-schema only ever ADDs columns, never drops
+ * them, so a field removed from an entity (e.g. a redundant `createdAt` now
+ * covered by the FF_Entity changelog) leaves its column behind forever.
+ *
+ * Atomic inside a BackendMethod: every ALTER shares that method's transaction, so
+ * any failure rolls them all back. Plain `DROP COLUMN` (no CASCADE) - a column
+ * with a dependency errors loudly rather than silently dropping dependents - which
+ * also briefly locks the touched tables, so treat `apply` as a maintenance action.
+ */
+export declare function dropColumns(db: SqlDatabase, entities: ClassType<unknown>[], opts?: {
+    apply?: boolean;
+    columns?: DropPlan[];
+}): Promise<{
+    applied: boolean;
+    plans: DropPlan[];
+    dropped: DropPlan[];
+}>;

package/esm/sqlAdmin/server/drift/orphanColumns.js

@@ -0,0 +1,76 @@
+import { repo } from 'remult';
+import { getRelationFieldInfo } from 'remult/internals';
+import { stripIdent } from './ident';
+import { planDropColumns } from './planDropColumns';
+/**
+ * Audit - and optionally drop a selected subset of - orphan columns: live DB
+ * columns on an entity-backed table that no entity field declares. Default is a
+ * dry run: returns every orphan, changes nothing.
+ *
+ * Unlike the PK / relation flows (which apply the whole plan), this one is
+ * destructive, so apply takes the explicit `columns` the user ticked and drops
+ * only those - re-checking each against a freshly computed orphan set so a stale
+ * client can never drop a column that is no longer orphan.
+ *
+ * Why this is needed: Remult's auto-schema only ever ADDs columns, never drops
+ * them, so a field removed from an entity (e.g. a redundant `createdAt` now
+ * covered by the FF_Entity changelog) leaves its column behind forever.
+ *
+ * Atomic inside a BackendMethod: every ALTER shares that method's transaction, so
+ * any failure rolls them all back. Plain `DROP COLUMN` (no CASCADE) - a column
+ * with a dependency errors loudly rather than silently dropping dependents - which
+ * also briefly locks the touched tables, so treat `apply` as a maintenance action.
+ */
+export async function dropColumns(db, entities, opts) {
+    // Declared columns per entity-backed table, straight from metadata.
+    const known = [];
+    for (const ent of entities) {
+        const meta = repo(ent).metadata;
+        if (meta.options.sqlExpression)
+            continue; // views: no real table
+        const fields = meta.fields.toArray();
+        const dbNameByKey = new Map(fields.map((f) => [f.key, stripIdent(f.dbName)]));
+        const columns = [];
+        for (const field of fields) {
+            const fi = getRelationFieldInfo(field);
+            if (fi) {
+                // A toOne relation's FK columns are real; toMany owns none. The FK keys
+                // are usually separate scalar fields too, but resolve them defensively.
+                if (fi.type === 'toOne')
+                    for (const k of Object.values(fi.getFields().fields))
+                        columns.push(dbNameByKey.get(k) ?? stripIdent(String(k)));
+                continue;
+            }
+            if (field.options.sqlExpression)
+                continue; // computed, no stored column
+            columns.push(stripIdent(field.dbName));
+        }
+        known.push({ table: stripIdent(meta.dbName), columns });
+    }
+    // Live columns per table from the catalog, in ordinal order.
+    const res = await db.createCommand().execute(`
+		SELECT table_name, column_name
+		FROM information_schema.columns
+		WHERE table_schema = 'public'
+		ORDER BY table_name, ordinal_position;
+	`);
+    const liveByTable = new Map();
+    for (const row of res.rows) {
+        const list = liveByTable.get(row.table_name) ?? [];
+        list.push(row.column_name);
+        liveByTable.set(row.table_name, list);
+    }
+    const current = Array.from(liveByTable, ([table, columns]) => ({ table, columns }));
+    const plans = planDropColumns(current, known);
+    let dropped = [];
+    if (opts?.apply && opts.columns?.length) {
+        const orphan = new Set(plans.map((p) => `${p.table}.${p.column}`));
+        // Only drop what is still orphan - the names then come from the catalog, not
+        // raw client input, so the interpolated identifiers are trusted.
+        dropped = opts.columns.filter((c) => orphan.has(`${c.table}.${c.column}`));
+        for (const { table, column } of dropped) {
+            await db.createCommand().execute(`ALTER TABLE "${table}" DROP COLUMN "${column}";`);
+        }
+    }
+    return { applied: opts?.apply ?? false, plans, dropped };
+}

package/esm/sqlAdmin/server/drift/planDropColumns.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Pure planner: diff each entity-backed table's live columns against the columns
+ * its entity actually declares, and list the orphans - live columns with no
+ * matching field. No DB access here; the executor feeds it the catalog snapshot +
+ * the metadata-derived target, and runs the (user-selected subset of) drops.
+ *
+ * Why this exists: Remult's auto-schema only ever ADDs columns, never drops them,
+ * so a field removed from an entity leaves its column behind forever. This is the
+ * inverse of `planPkSync` / `planRelationIndexes` - and it's destructive, so the
+ * UI selects nothing by default and applies only the checked subset.
+ */
+/** A table's columns - live (from the catalog) or declared (from metadata). */
+export type TableColumns = {
+    table: string;
+    columns: string[];
+};
+/** One orphan column to (optionally) drop. */
+export type DropPlan = {
+    table: string;
+    column: string;
+};
+/**
+ * One entry per orphan column. Only tables present in `known` (i.e. backed by an
+ * entity) are considered - DB-only tables (firstly infra, views) are left alone,
+ * same scoping as the other two flows. Sorted by table, then column.
+ */
+export declare function planDropColumns(current: TableColumns[], known: TableColumns[]): DropPlan[];

package/esm/sqlAdmin/server/drift/planDropColumns.js

@@ -0,0 +1,39 @@
+/**
+ * Pure planner: diff each entity-backed table's live columns against the columns
+ * its entity actually declares, and list the orphans - live columns with no
+ * matching field. No DB access here; the executor feeds it the catalog snapshot +
+ * the metadata-derived target, and runs the (user-selected subset of) drops.
+ *
+ * Why this exists: Remult's auto-schema only ever ADDs columns, never drops them,
+ * so a field removed from an entity leaves its column behind forever. This is the
+ * inverse of `planPkSync` / `planRelationIndexes` - and it's destructive, so the
+ * UI selects nothing by default and applies only the checked subset.
+ */
+/**
+ * One entry per orphan column. Only tables present in `known` (i.e. backed by an
+ * entity) are considered - DB-only tables (firstly infra, views) are left alone,
+ * same scoping as the other two flows. Sorted by table, then column.
+ */
+export function planDropColumns(current, known) {
+    // Union, not overwrite: several entities can map to one table (e.g. a light
+    // projection + the full row sharing a `dbName`), and each declares only its
+    // own subset of the columns.
+    const knownByTable = new Map();
+    for (const { table, columns } of known) {
+        let set = knownByTable.get(table);
+        if (!set)
+            knownByTable.set(table, (set = new Set()));
+        for (const c of columns)
+            set.add(c);
+    }
+    const plans = [];
+    for (const { table, columns } of current) {
+        const declared = knownByTable.get(table);
+        if (!declared)
+            continue; // table has no backing entity - not ours to manage
+        for (const column of columns)
+            if (!declared.has(column))
+                plans.push({ table, column });
+    }
+    return plans.sort((a, b) => a.table.localeCompare(b.table) || a.column.localeCompare(b.column));
+}

package/esm/sqlAdmin/server/drift/planNullableDrift.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Pure planner: find columns whose entity says `allowNull` but whose live column is
+ * still `not null default <empty>`. No DB access here; the executor feeds it the
+ * catalog snapshot + the metadata-derived target, and runs the selected subset.
+ *
+ * Why this exists: `ensureSchema` emits `default '' not null` (or `0` / `false`) for a
+ * field that is not `allowNull`, and never relaxes that constraint afterwards. So a
+ * column added before the field learned `allowNull` keeps handing every pre-existing
+ * row a value outside its own domain, forever - and the entity now claims those rows
+ * are null. This is the inverse of `planDropColumns`: nothing is deleted, but rewriting
+ * values is destructive enough that the UI selects nothing by default.
+ */
+/** A live column's constraint state, from the catalog. */
+export type LiveColumn = {
+    table: string;
+    column: string;
+    isNullable: boolean;
+    hasDefault: boolean;
+    /** `''` for text-ish columns, null when the empty value cannot be rewritten safely. */
+    emptyLiteral: string | null;
+};
+/** What an entity field declares about nullability. */
+export type DeclaredColumn = {
+    table: string;
+    column: string;
+    allowNull: boolean;
+};
+/** One column to relax, and whether its empty rows can be blanked to NULL. */
+export type NullablePlan = {
+    table: string;
+    column: string;
+    dropNotNull: boolean;
+    dropDefault: boolean;
+    /**
+     * false when the column's empty value is a real one (`0`, `false`): the constraint
+     * is relaxed so future writes can be null, but existing rows are left alone rather
+     * than guessing that a zero meant "unset".
+     */
+    blankToNull: boolean;
+};
+/**
+ * One entry per drifted column. Only columns declared by an entity are considered -
+ * a live column with no field is the orphan flow's business, not this one. Sorted by
+ * table, then column.
+ */
+export declare function planNullableDrift(current: LiveColumn[], known: DeclaredColumn[]): NullablePlan[];

package/esm/sqlAdmin/server/drift/planNullableDrift.js

@@ -0,0 +1,35 @@
+/**
+ * Pure planner: find columns whose entity says `allowNull` but whose live column is
+ * still `not null default <empty>`. No DB access here; the executor feeds it the
+ * catalog snapshot + the metadata-derived target, and runs the selected subset.
+ *
+ * Why this exists: `ensureSchema` emits `default '' not null` (or `0` / `false`) for a
+ * field that is not `allowNull`, and never relaxes that constraint afterwards. So a
+ * column added before the field learned `allowNull` keeps handing every pre-existing
+ * row a value outside its own domain, forever - and the entity now claims those rows
+ * are null. This is the inverse of `planDropColumns`: nothing is deleted, but rewriting
+ * values is destructive enough that the UI selects nothing by default.
+ */
+/**
+ * One entry per drifted column. Only columns declared by an entity are considered -
+ * a live column with no field is the orphan flow's business, not this one. Sorted by
+ * table, then column.
+ */
+export function planNullableDrift(current, known) {
+    const nullableByKey = new Map(known.filter((k) => k.allowNull).map((k) => [`${k.table}.${k.column}`, true]));
+    const plans = [];
+    for (const col of current) {
+        if (!nullableByKey.has(`${col.table}.${col.column}`))
+            continue;
+        if (col.isNullable && !col.hasDefault)
+            continue; // already clean
+        plans.push({
+            table: col.table,
+            column: col.column,
+            dropNotNull: !col.isNullable,
+            dropDefault: col.hasDefault,
+            blankToNull: col.emptyLiteral !== null,
+        });
+    }
+    return plans.sort((a, b) => a.table.localeCompare(b.table) || a.column.localeCompare(b.column));
+}

package/esm/sqlAdmin/server/drift/planPkSync.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure planner: diff the live PRIMARY KEYs against what the entity `id` config
+ * wants, and emit the minimal ALTER plan. No DB access here - the controller
+ * feeds it the catalog snapshot + the metadata-derived target, runs the SQL.
+ *
+ * Why this exists: Remult only sets a table's PK on first creation and never
+ * ALTERs it, so a later `id` change is silently ignored on long-lived DBs.
+ */
+/** A table's current PK, as read from the pg catalog. */
+export type PkCurrent = {
+    table: string;
+    constraintName: string;
+    cols: string[];
+};
+/** A table's desired PK, derived from `repo(Entity).metadata.idMetadata`. */
+export type PkDesired = {
+    table: string;
+    cols: string[];
+};
+type PkAction = 'ok' | 'create' | 'migrate';
+export type PkPlan = {
+    table: string;
+    before: string[];
+    after: string[];
+    action: PkAction;
+    sql: string[];
+};
+/**
+ * One plan per *desired* (entity-backed) table. Tables present in the DB but not
+ * in `desired` (firstly infra, views, etc.) are left alone - we only manage what
+ * an entity's `id` config describes. Several entities can share one table (a
+ * light projection + the full row on the same `dbName`) - one plan per table,
+ * first declaration wins, so the UI can key rows by table.
+ */
+export declare function planPkSync(current: PkCurrent[], desired: PkDesired[]): PkPlan[];
+export {};