firstly 0.10.2 → 0.10.3

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

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+const ident = (name) => `"${name}"`;
+const cols = (names) => names.map(ident).join(', ');
+const sameOrder = (a, b) => a.length === b.length && a.every((c, i) => c === b[i]);
+/**
+ * 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 function planPkSync(current, desired) {
+    const byTable = new Map(current.map((c) => [c.table, c]));
+    const seen = new Set();
+    return desired.flatMap(({ table, cols: after }) => {
+        if (seen.has(table))
+            return [];
+        seen.add(table);
+        return [planTable(byTable.get(table), table, after)];
+    });
+}
+function planTable(cur, table, after) {
+    const before = cur?.cols ?? [];
+    const addPk = `ALTER TABLE ${ident(table)} ADD PRIMARY KEY (${cols(after)});`;
+    if (!cur)
+        return { table, before, after, action: 'create', sql: [addPk] };
+    if (sameOrder(cur.cols, after))
+        return { table, before, after, action: 'ok', sql: [] };
+    return {
+        table,
+        before,
+        after,
+        action: 'migrate',
+        sql: [`ALTER TABLE ${ident(table)} DROP CONSTRAINT ${ident(cur.constraintName)};`, addPk],
+    };
+}

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

@@ -0,0 +1,23 @@
+import { type ClassType, type SqlDatabase } from 'remult';
+import { type PkPlan } from './planPkSync';
+/**
+ * Audit - and optionally fix - PRIMARY KEY drift between the live DB and each
+ * entity's `id` config. Default is a dry run: returns the plan, changes nothing.
+ * Pass `{ apply: true }` to run it.
+ *
+ * Why this is needed: Remult only sets a PK on first table creation and never
+ * ALTERs it, so a later `id` change is silently ignored on long-lived DBs.
+ *
+ * Atomic when called inside a BackendMethod: the whole thing shares that method's
+ * transaction, so any failure - e.g. PG 23505 when duplicate keys block a
+ * composite PK - rolls back every ALTER; the DB is never left half-migrated.
+ * That's also why it's plain `ADD PRIMARY KEY`, not `CONCURRENTLY` (which can't
+ * run in a transaction): it briefly locks the touched tables, so treat
+ * `apply: true` as a maintenance-window action.
+ */
+export declare function reindexPrimaryKeys(db: SqlDatabase, entities: ClassType<unknown>[], opts?: {
+    apply?: boolean;
+}): Promise<{
+    applied: boolean;
+    plans: PkPlan[];
+}>;

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

@@ -0,0 +1,60 @@
+import { repo } from 'remult';
+import { stripIdent } from './ident';
+import { planPkSync } from './planPkSync';
+/**
+ * Audit - and optionally fix - PRIMARY KEY drift between the live DB and each
+ * entity's `id` config. Default is a dry run: returns the plan, changes nothing.
+ * Pass `{ apply: true }` to run it.
+ *
+ * Why this is needed: Remult only sets a PK on first table creation and never
+ * ALTERs it, so a later `id` change is silently ignored on long-lived DBs.
+ *
+ * Atomic when called inside a BackendMethod: the whole thing shares that method's
+ * transaction, so any failure - e.g. PG 23505 when duplicate keys block a
+ * composite PK - rolls back every ALTER; the DB is never left half-migrated.
+ * That's also why it's plain `ADD PRIMARY KEY`, not `CONCURRENTLY` (which can't
+ * run in a transaction): it briefly locks the touched tables, so treat
+ * `apply: true` as a maintenance-window action.
+ */
+export async function reindexPrimaryKeys(db, entities, opts) {
+    // Live PKs from the catalog, columns kept in constraint order.
+    const res = await db.createCommand().execute(`
+		SELECT tc.table_name, tc.constraint_name, kcu.column_name
+		FROM information_schema.table_constraints tc
+		JOIN information_schema.key_column_usage kcu
+			ON tc.constraint_name = kcu.constraint_name
+			AND tc.table_schema = kcu.table_schema
+		WHERE tc.constraint_type = 'PRIMARY KEY'
+			AND tc.table_schema = 'public'
+		ORDER BY tc.table_name, kcu.ordinal_position;
+	`);
+    const byTable = new Map();
+    for (const row of res.rows) {
+        let cur = byTable.get(row.table_name);
+        if (!cur) {
+            cur = { table: row.table_name, constraintName: row.constraint_name, cols: [] };
+            byTable.set(row.table_name, cur);
+        }
+        cur.cols.push(row.column_name);
+    }
+    // Desired PK per entity, straight from its `id` config.
+    const desired = [];
+    for (const ent of entities) {
+        const meta = repo(ent).metadata;
+        if (meta.options.sqlExpression)
+            continue; // views: no real table
+        const cols = meta.idMetadata.fields.map((f) => stripIdent(f.dbName));
+        if (cols.length === 0)
+            continue;
+        desired.push({ table: stripIdent(meta.dbName), cols });
+    }
+    const plans = planPkSync([...byTable.values()], desired);
+    if (opts?.apply) {
+        for (const plan of plans) {
+            // Fail-fast: any throw aborts the shared transaction -> full rollback.
+            for (const stmt of plan.sql)
+                await db.createCommand().execute(stmt);
+        }
+    }
+    return { applied: opts?.apply ?? false, plans };
+}

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

@@ -0,0 +1,43 @@
+import { type ClassType, type SqlDatabase } from 'remult';
+/** A toOne relation's local FK columns that ideally have a covering index. */
+export type RelIndexDesired = {
+    table: string;
+    columns: string[];
+};
+/** An existing index from the catalog, columns in order. */
+export type ExistingIndex = {
+    name: string;
+    cols: string[];
+};
+export type RelIndexPlan = {
+    table: string;
+    columns: string[];
+    name: string;
+    action: 'ok' | 'create';
+    /** name of the index already covering these columns (when action is 'ok'). */
+    coveredBy: string | null;
+    sql: string | null;
+};
+/**
+ * Pure: for each (deduped) relation FK, decide whether an index is missing.
+ * A relation is already covered if any existing index - including the PRIMARY KEY -
+ * has those columns as its leftmost prefix, so we never propose redundant indexes
+ * (e.g. an `a` index on an `(a, b)` PK table).
+ */
+export declare function planRelationIndexes(desired: RelIndexDesired[], existing: Map<string, ExistingIndex[]>): RelIndexPlan[];
+/**
+ * Find - and optionally create - indexes for `toOne` relation FK columns that
+ * aren't already covered by an existing index. Default is a dry run: returns the
+ * plan, changes nothing. Pass `{ apply: true }` to create the missing ones.
+ *
+ * Postgres does NOT auto-index FK columns, and `toMany` relations are indexed
+ * from their owning `toOne` side, so only `toOne` is considered. Creates use
+ * `CREATE INDEX IF NOT EXISTS` (idempotent), so they join the BackendMethod's
+ * transaction - which is also why they can't be `CONCURRENTLY`.
+ */
+export declare function createRelationIndexes(db: SqlDatabase, entities: ClassType<unknown>[], opts?: {
+    apply?: boolean;
+}): Promise<{
+    applied: boolean;
+    plans: RelIndexPlan[];
+}>;

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

@@ -0,0 +1,91 @@
+import { dbNamesOf, repo } from 'remult';
+import { getRelationFieldInfo } from 'remult/internals';
+import { formatCreateIndex } from './createIndex';
+import { stripIdent } from './ident';
+/** `want` is covered if it's a leftmost prefix of `have` (so the PK covers its own prefix). */
+const isPrefix = (want, have) => have.length >= want.length && want.every((c, i) => have[i] === c);
+/**
+ * Pure: for each (deduped) relation FK, decide whether an index is missing.
+ * A relation is already covered if any existing index - including the PRIMARY KEY -
+ * has those columns as its leftmost prefix, so we never propose redundant indexes
+ * (e.g. an `a` index on an `(a, b)` PK table).
+ */
+export function planRelationIndexes(desired, existing) {
+    const seen = new Set();
+    const plans = [];
+    for (const d of desired) {
+        const key = `${d.table}(${d.columns.join(',')})`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const name = `FF_IX_${d.table}_${d.columns.join('_')}`;
+        const cover = (existing.get(d.table) ?? []).find((e) => isPrefix(d.columns, e.cols));
+        plans.push(cover
+            ? { table: d.table, columns: d.columns, name, action: 'ok', coveredBy: cover.name, sql: null }
+            : {
+                table: d.table,
+                columns: d.columns,
+                name,
+                action: 'create',
+                coveredBy: null,
+                sql: formatCreateIndex({ name, table: d.table, columns: d.columns, ifNotExists: true }),
+            });
+    }
+    return plans;
+}
+/**
+ * Find - and optionally create - indexes for `toOne` relation FK columns that
+ * aren't already covered by an existing index. Default is a dry run: returns the
+ * plan, changes nothing. Pass `{ apply: true }` to create the missing ones.
+ *
+ * Postgres does NOT auto-index FK columns, and `toMany` relations are indexed
+ * from their owning `toOne` side, so only `toOne` is considered. Creates use
+ * `CREATE INDEX IF NOT EXISTS` (idempotent), so they join the BackendMethod's
+ * transaction - which is also why they can't be `CONCURRENTLY`.
+ */
+export async function createRelationIndexes(db, entities, opts) {
+    // Desired FK indexes from each entity's toOne relations.
+    const desired = [];
+    for (const ent of entities) {
+        const meta = repo(ent).metadata;
+        if (meta.options.sqlExpression)
+            continue; // views: no real table
+        const names = await dbNamesOf(ent);
+        const table = stripIdent(names.$entityName);
+        for (const field of meta.fields.toArray()) {
+            const fi = getRelationFieldInfo(field);
+            if (!fi || fi.type !== 'toOne')
+                continue; // toMany is indexed from the toOne side
+            const localKeys = Object.values(fi.getFields().fields); // FK columns on THIS entity
+            if (localKeys.length === 0)
+                continue;
+            desired.push({ table, columns: localKeys.map((k) => stripIdent(names.$dbNameOf(k))) });
+        }
+    }
+    // Every existing index (incl. PK), columns in order, per table.
+    const res = await db.createCommand().execute(`
+		SELECT c.relname AS table_name, i.relname AS index_name,
+			array_agg(a.attname::text ORDER BY k.ord) AS cols
+		FROM pg_class c
+		JOIN pg_namespace ns ON ns.oid = c.relnamespace AND ns.nspname = 'public'
+		JOIN pg_index ix ON ix.indrelid = c.oid
+		JOIN pg_class i ON i.oid = ix.indexrelid
+		JOIN unnest(ix.indkey) WITH ORDINALITY AS k(attnum, ord) ON true
+		JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum = k.attnum
+		WHERE c.relkind = 'r' AND k.attnum > 0
+		GROUP BY c.relname, i.relname;
+	`);
+    const existing = new Map();
+    for (const row of res.rows) {
+        const list = existing.get(row.table_name) ?? [];
+        list.push({ name: row.index_name, cols: row.cols });
+        existing.set(row.table_name, list);
+    }
+    const plans = planRelationIndexes(desired, existing);
+    if (opts?.apply) {
+        for (const plan of plans)
+            if (plan.sql)
+                await db.createCommand().execute(plan.sql);
+    }
+    return { applied: opts?.apply ?? false, plans };
+}

package/esm/sqlAdmin/server/index.d.ts

@@ -1,7 +1,17 @@
-import { type SqlDatabase } from 'remult';
+import { type ClassType, type SqlDatabase } from 'remult';
 import { Module } from 'remult/server';
 import { type SqlTokensOptions } from '../SqlAdminController';
+import { type SqlDriftOptions } from '../SqlDriftController';
 export type { SqlTokensOptions, SqlTokenPool } from '../SqlAdminController';
+export type { SqlDriftFlag, SqlDriftOptions } from '../SqlDriftController';
+export { formatCreateIndex, sqlCreateIndex, type IndexOptions } from './drift/createIndex';
+/** Minimal shape of a remult `Module`, so any module list passes without a cast. */
+type ModuleTree = {
+    entities?: ClassType<unknown>[];
+    modules?: ModuleTree[];
+};
+/** Every entity of a module list, incl. nested submodules - feed it to `drift.entities`. */
+export declare const collectEntities: (mods: ModuleTree[]) => ClassType<unknown>[];
 export type SqlAdminOptions = {
     /**
      * Override the SqlDatabase used to execute queries.
@@ -29,6 +39,13 @@ export type SqlAdminOptions = {
      * no mint endpoint, no request hook. Needs `sqlAdmin: true`. See `<SqlTokens />`.
      */
     tokens?: SqlTokensOptions | false;
+    /**
+     * Schema drift checks for `<SqlDrift />`: each one dry-runs first, then applies on demand.
+     * Every flag is opt-in, nothing is registered without at least one.
+     *
+     * @example drift: { entities: () => collectEntities(modules), relationIndexes: true }
+     */
+    drift?: SqlDriftOptions;
 };
 /**
  * Drop-in SQL admin endpoint + companion `<SqlAdmin />` component (`firstly/sqlAdmin`).

package/esm/sqlAdmin/server/index.js

@@ -3,8 +3,12 @@ import { Module } from 'remult/server';
 import { yellow } from '@kitql/helpers';
 import { log } from '..';
 import { SqlAdminController } from '../SqlAdminController';
+import { SqlDriftController } from '../SqlDriftController';
 import { isSqlTokenLive, SqlToken, sqlTokenEntities } from '../sqlTokenEntities';
 import { hashToken } from './token';
+export { formatCreateIndex, sqlCreateIndex } from './drift/createIndex';
+/** Every entity of a module list, incl. nested submodules - feed it to `drift.entities`. */
+export const collectEntities = (mods) => mods.flatMap((m) => [...(m.entities ?? []), ...collectEntities(m.modules ?? [])]);
 // Framework-agnostic: remult hands initRequest the native request (SvelteKit
 // RequestEvent, express req, a fetch Request...).
 function readAuthorization(req) {
@@ -59,17 +63,21 @@ export const sqlAdmin = (opts) => {
     }
     const prefix = tokens?.prefix ?? 'ffsql_';
     const execPath = `${tokens?.apiPath ?? '/api'}/ff/sqlAdmin/exec`;
+    const drift = opts?.drift;
+    const driftOn = !!drift && !!(drift.relationIndexes || drift.primaryKeys || drift.nullable || drift.orphanColumns);
     return new Module({
         key: 'sqlAdmin',
         // Before the app's own initRequest, so a bearer is resolved before cookies would be.
         priority: -900,
         entities: tokens ? Object.values(sqlTokenEntities) : [],
-        controllers: enabled ? [SqlAdminController] : [],
+        controllers: [...(enabled ? [SqlAdminController] : []), ...(driftOn ? [SqlDriftController] : [])],
         initApi: async () => {
             if (opts?.dp) {
                 SqlAdminController.dp = await opts.dp();
+                SqlDriftController.dp = SqlAdminController.dp;
             }
             SqlAdminController.options = { tokens };
+            SqlDriftController.options = driftOn ? drift : undefined;
             if (enabled)
                 log.info(`AI Hint: visit ${yellow(path)} to query raw SQL.`);
         },