@fougere/adapter-sql 0.2.0-alpha.2 → 0.4.0-alpha.0

package/src/ddl.ts

@@ -0,0 +1,242 @@
+/**
+ * DDL — the table description, rendered as SQL.
+ *
+ * Kysely's schema builder is what makes this dialect-agnostic: it owns the
+ * identifier quoting and the per-engine syntax, so this module only decides
+ * *what* to emit. Compilation needs no connection — a `DummyDriver` paired with
+ * a real query compiler renders the statement for any engine, which is why the
+ * whole surface is testable without a database.
+ */
+import {
+  Kysely,
+  DummyDriver,
+  sql,
+  SqliteAdapter, SqliteQueryCompiler, SqliteIntrospector,
+  PostgresAdapter, PostgresQueryCompiler, PostgresIntrospector,
+  MysqlAdapter, MysqlQueryCompiler, MysqlIntrospector,
+  MssqlAdapter, MssqlQueryCompiler, MssqlIntrospector,
+} from 'kysely';
+import {
+  isKeyed,
+  orderTables,
+  toTableName,
+  toTables,
+  type AppLike,
+  type ColumnDef,
+  type TableDef,
+} from './table.js';
+import { columnTypeFor, resolveDialect, type DialectName } from './dialect.js';
+import { checkFor } from './check.js';
+
+// ─── Compile-only engines ──────────────────────────
+
+const parts = {
+  sqlite: [SqliteAdapter, SqliteQueryCompiler, SqliteIntrospector],
+  pg: [PostgresAdapter, PostgresQueryCompiler, PostgresIntrospector],
+  mysql: [MysqlAdapter, MysqlQueryCompiler, MysqlIntrospector],
+  mssql: [MssqlAdapter, MssqlQueryCompiler, MssqlIntrospector],
+} as const;
+
+const engines = new Map<DialectName, Kysely<any>>();
+
+/** A Kysely bound to a dialect's compiler but to no connection — renders SQL only. */
+export function compiler(name: DialectName): Kysely<any> {
+  const cached = engines.get(name);
+  if (cached) return cached;
+  const [Adapter, QueryCompiler, Introspector] = parts[name] as any;
+  const engine = new Kysely<any>({
+    dialect: {
+      createAdapter: () => new Adapter(),
+      createDriver: () => new DummyDriver(),
+      createIntrospector: (db: Kysely<any>) => new Introspector(db),
+      createQueryCompiler: () => new QueryCompiler(),
+    },
+  });
+  engines.set(name, engine);
+  return engine;
+}
+
+// ─── CREATE TABLE ──────────────────────────────────
+
+/**
+ * Render `CREATE TABLE` for one described table.
+ *
+ * `IF NOT EXISTS` is emitted everywhere it exists — SQL Server has no such
+ * clause, so there the statement is bare and the caller must not replay it
+ * blindly (the diff pass, once it lands, answers that properly).
+ *
+ * `skipReferences` names the columns whose FK is rendered WITHOUT the inline
+ * `references()` — the column itself still gets created; `orderTables` sends a
+ * column here when its target is part of a cycle, so the constraint reaches the
+ * table separately, once every table involved exists (`addForeignKeyConstraintSQL`).
+ */
+export function createTableSQL(
+  table: TableDef,
+  dialectName: DialectName,
+  options?: { skipReferences?: Set<string> },
+): string {
+  const dialect = resolveDialect(dialectName);
+  const composite = table.compositePrimary.length > 0;
+  const skip = options?.skipReferences;
+  let builder = compiler(dialectName).schema.createTable(table.name);
+  if (dialectName !== 'mssql') builder = builder.ifNotExists();
+
+  for (const column of table.columns) {
+    const type = columnTypeFor(dialect, column, isKeyed(table, column));
+    builder = builder.addColumn(column.name, sql.raw(type) as any, (col) => {
+      let built = col;
+      // A simple key is inline; a composite one becomes a table constraint.
+      if (column.primary && !composite) built = built.primaryKey();
+      if (!column.nullable) built = built.notNull();
+      if (column.default !== undefined) built = built.defaultTo(column.default);
+      // Uniqueness is the storage's to enforce: no shape can express it, since judging
+      // one value never sees the other rows.
+      if (column.unique) built = built.unique();
+      if (column.references && !skip?.has(column.name)) {
+        built = built.references(`${column.references.table}.${column.references.column}`);
+        if (column.references.onDelete) built = built.onDelete(column.references.onDelete);
+      }
+      return built;
+    });
+  }
+
+  if (composite) {
+    builder = builder.addPrimaryKeyConstraint(`${table.name}_pk`, table.compositePrimary as any);
+  }
+
+  // The pair the entity declared. Named after its columns so a second group on the
+  // same table cannot collide, and so a migration can recognize it later.
+  for (const group of table.uniqueGroups) {
+    builder = builder.addUniqueConstraint(`${table.name}_${group.join('_')}_unique`, group as any);
+  }
+
+  // What the shape says, told to the storage. Table-level rather than inline: a
+  // named constraint is what a later migration can find and replace, and the same
+  // form will hold a cross-field check when one is declared.
+  for (const column of table.columns) {
+    const check = checkFor(column);
+    if (check) builder = builder.addCheckConstraint(`${table.name}_${column.name}_check`, check);
+  }
+
+  return builder.compile().sql;
+}
+
+/**
+ * `CREATE INDEX` for every column that asked for one.
+ *
+ * Separate statements, never part of `CREATE TABLE`: an index is not a constraint, it
+ * changes no answer — only what a read costs. `IF NOT EXISTS` everywhere it exists, so
+ * replaying the batch is safe (SQL Server has no such clause, same rule as the tables).
+ */
+export function indexSQL(table: TableDef, column: ColumnDef, dialectName: DialectName): string {
+  let builder = compiler(dialectName)
+    .schema.createIndex(`${table.name}_${column.name}_idx`)
+    .on(table.name)
+    .column(column.name);
+  if (dialectName !== 'mssql') builder = builder.ifNotExists();
+  return builder.compile().sql;
+}
+
+/** Every index one table asks for — one statement each. */
+export function createIndexSQL(table: TableDef, dialectName: DialectName): string[] {
+  return table.columns
+    .filter((column) => column.index)
+    .map((column) => indexSQL(table, column, dialectName));
+}
+
+/**
+ * `ALTER TABLE ADD CONSTRAINT` for one FK `orderTables` deferred — closes a
+ * relation cycle once every table in it exists. Not available on SQLite (its
+ * `ALTER TABLE` is limited to RENAME/ADD COLUMN/RENAME COLUMN/DROP COLUMN) — a
+ * caller on that dialect never produces a deferred edge to render here.
+ */
+export function addForeignKeyConstraintSQL(table: TableDef, column: ColumnDef, dialectName: DialectName): string {
+  const ref = column.references!;
+  const name = `${table.name}_${column.name}_fk`;
+  let builder = compiler(dialectName)
+    .schema.alterTable(table.name)
+    .addForeignKeyConstraint(name, [column.name], ref.table, [ref.column]);
+  if (ref.onDelete) builder = builder.onDelete(ref.onDelete);
+  return builder.compile().sql;
+}
+
+// ─── App-wide generation ───────────────────────────
+
+export interface GenerateOptions {
+  /** Override table name resolution. Default: camelCase → snake_case + 's'. */
+  tableName?: (entityName: string) => string;
+  /** Target engine. Default: sqlite. */
+  dialect?: DialectName;
+}
+
+/**
+ * `CREATE TABLE` for every entity the app hosts — scanned frond entities plus
+ * auth runtime entities when present.
+ *
+ * SQLite resolves FK targets lazily and accepts any order, and it has no
+ * `ALTER TABLE ADD CONSTRAINT` to close a cycle with — every FK stays inline,
+ * unordered. Every other engine needs a referenced table to exist first:
+ * `orderTables` sorts the batch and reports the edges a cycle forces to defer,
+ * rendered as `ALTER TABLE ADD CONSTRAINT` after every `CREATE TABLE`.
+ *
+ * Caveat for a repeat call (`autoMigrate`): `CREATE TABLE IF NOT EXISTS` is
+ * idempotent, `ADD CONSTRAINT` is not — on pg/mysql/mssql, calling this twice
+ * for an app with a relation cycle re-issues the same constraint and errors.
+ * The introspection-based `migrate()` (`diff.ts`) doesn't have this problem: it
+ * only ever emits a table's constraints once, the run that creates it.
+ */
+export function generateSQL(app: AppLike, options?: GenerateOptions): string[] {
+  const resolve = options?.tableName ?? toTableName;
+  const dialect = options?.dialect ?? 'sqlite';
+  const tables = toTables(app, resolve);
+
+  if (dialect === 'sqlite') {
+    return [
+      ...tables.map((table) => createTableSQL(table, dialect)),
+      ...tables.flatMap((table) => createIndexSQL(table, dialect)),
+    ];
+  }
+
+  const { ordered, deferred } = orderTables(tables);
+  const deferredColumnsOf = new Map<string, Set<string>>();
+  for (const { table, column } of deferred) {
+    const names = deferredColumnsOf.get(table.name) ?? new Set<string>();
+    names.add(column.name);
+    deferredColumnsOf.set(table.name, names);
+  }
+
+  const creates = ordered.map((table) =>
+    createTableSQL(table, dialect, { skipReferences: deferredColumnsOf.get(table.name) }),
+  );
+  const constraints = deferred.map(({ table, column }) => addForeignKeyConstraintSQL(table, column, dialect));
+  // Indexes last: every table exists by then, and an index on a table that does not is
+  // the one ordering mistake this pass can make.
+  const indexes = ordered.flatMap((table) => createIndexSQL(table, dialect));
+  return [...creates, ...constraints, ...indexes];
+}
+
+/**
+ * Anything that can run a statement. `exec` is accepted alongside `execute` so a
+ * raw better-sqlite3 handle drops in unchanged.
+ */
+export type SqlSink =
+  | { execute(sql: string): unknown }
+  | { exec(sql: string): unknown };
+
+function runOn(sink: SqlSink, statement: string): unknown {
+  return 'execute' in sink ? sink.execute(statement) : sink.exec(statement);
+}
+
+/**
+ * Create every missing table. Additive only — an existing table is left alone.
+ *
+ * Stays SYNCHRONOUS when the sink is (a raw better-sqlite3 handle), so a caller
+ * that doesn't await still gets its tables before the next statement. Returns a
+ * promise only when the sink actually returns one.
+ */
+export function autoMigrate(app: AppLike, sink: SqlSink, options?: GenerateOptions): void | Promise<void> {
+  const pending = generateSQL(app, options)
+    .map((statement) => runOn(sink, statement))
+    .filter((result): result is Promise<unknown> => typeof (result as any)?.then === 'function');
+  return pending.length ? Promise.all(pending).then(() => undefined) : undefined;
+}

package/src/dialect.ts

@@ -0,0 +1,204 @@
+/**
+ * Dialect — the only place that speaks SQL.
+ *
+ * A dialect answers two questions and nothing else: which column type carries
+ * this shape, and does this engine support `RETURNING`. Everything structural
+ * (which columns exist, which are keys) is decided upstream in `TableDef`.
+ */
+import type { ColumnDef } from './table.js';
+
+export type DialectName = 'sqlite' | 'pg' | 'mysql' | 'mssql';
+
+export interface Dialect {
+  name: DialectName;
+  /**
+   * SQL type for a column. `keyed` is true when the column belongs to a primary
+   * key — MySQL and SQL Server cannot index an unbounded text column, so they
+   * narrow to a bounded varchar there.
+   */
+  columnType(column: ColumnDef, keyed: boolean): string;
+  /**
+   * Does `INSERT … RETURNING` work? MySQL has no such clause and SQL Server
+   * spells it `OUTPUT`; both take the insert-then-select path instead.
+   */
+  supportsReturning: boolean;
+  /**
+   * How many values one statement may bind — what splits a batch read into several.
+   *
+   * A key set comes from a PAGE, and a page has no ceiling (`list()` with no limit
+   * reads the table), so `where id in (…)` eventually meets the engine's limit.
+   * Measured on SQLite: 32 766 binds, and 32 767 answers `too many SQL variables`.
+   * SQL Server is the low one at 2100, which is why this is per dialect and not one
+   * constant — a batch that works on SQLite and dies on SQL Server is the same value
+   * behaving differently per engine, the thing this file exists to absorb.
+   *
+   * The number below is the limit MINUS a margin for the other values a statement
+   * carries (a filter, a cursor): a batch read is never the only thing in the query.
+   */
+  maxBindings: number;
+  /**
+   * How this engine spells "write it, or replace what is there".
+   *
+   * `'on conflict'` is the standard clause (SQLite, Postgres); MySQL spells the same
+   * thing `ON DUPLICATE KEY UPDATE`; SQL Server has only `MERGE`, a different statement
+   * with different semantics — so it answers `false` and the port refuses by name
+   * rather than emulating a write with a read in front of it, which would be a lie
+   * about atomicity in an engine that has no transaction here either.
+   */
+  upsert: 'on conflict' | 'on duplicate key' | false;
+  /**
+   * Is this the engine refusing a duplicate, rather than failing?
+   *
+   * A driver reports it as a plain `Error` whose wording is the engine's own, so only a
+   * dialect can tell — the same reason `maxBindings` and `upsert` live here. Without it
+   * every engine's phrasing would be matched in one place, and this file exists so no
+   * other one learns a dialect.
+   *
+   * A false negative costs an INTERNAL_ERROR where a CONFLICT was due — which is what
+   * every engine answered before this existed, so nothing is made worse by a gap.
+   */
+  isUniqueViolation(error: unknown): boolean;
+}
+
+/** The message a driver hands up, however it wrapped it. */
+function messageOf(error: unknown): string {
+  const e = error as { message?: unknown; code?: unknown; cause?: unknown } | null;
+  const own = `${typeof e?.message === 'string' ? e.message : ''} ${typeof e?.code === 'string' ? e.code : ''}`;
+  // Kysely wraps a driver error, and D1 wraps it again: the wording is often one level down.
+  return e?.cause ? `${own} ${messageOf(e.cause)}` : own;
+}
+
+/** Bounded length for a key column, when the shape doesn't state its own. */
+const KEY_LENGTH = 255;
+
+function keyLength(column: ColumnDef): number {
+  const declared = column.bounds?.maxLength;
+  return declared !== undefined && declared > 0 && declared <= KEY_LENGTH ? declared : KEY_LENGTH;
+}
+
+export const sqliteDialect: Dialect = {
+  // SQLite: `UNIQUE constraint failed: products.sku` — and D1 relays it verbatim.
+  isUniqueViolation: (error) => /UNIQUE constraint failed/i.test(messageOf(error)),
+  upsert: 'on conflict',
+  // SQLITE_MAX_VARIABLE_NUMBER is 32766 on any build since 3.32 (measured on better-sqlite3).
+  maxBindings: 30000,
+  name: 'sqlite',
+  supportsReturning: true,
+  // SQLite has one integer, one float and one text type — a boolean is an int,
+  // JSON is text. Any column may be a key, so `keyed` changes nothing.
+  columnType(column) {
+    switch (column.shape?.type) {
+      case 'integer':
+      case 'boolean':
+        return 'integer';
+      case 'number':
+        return 'real';
+      default:
+        return 'text';
+    }
+  },
+};
+
+export const pgDialect: Dialect = {
+  // Postgres: SQLSTATE 23505, which `pg` puts on `code` — the one engine that names it
+  // in a way no translation can blur.
+  isUniqueViolation: (error) => /23505/.test(messageOf(error)),
+  upsert: 'on conflict',
+  // the wire protocol counts parameters in an int16 — 65535.
+  maxBindings: 60000,
+  name: 'pg',
+  supportsReturning: true,
+  // Postgres has real types for everything, and `text` is indexable — so a key
+  // needs no narrowing.
+  columnType(column) {
+    switch (column.shape?.type) {
+      case 'integer':
+        return 'integer';
+      case 'number':
+        return 'double precision';
+      case 'boolean':
+        return 'boolean';
+      case 'object':
+      case 'array':
+        return 'jsonb';
+      default:
+        return 'text';
+    }
+  },
+};
+
+export const mysqlDialect: Dialect = {
+  // MySQL: ER_DUP_ENTRY / 1062, `Duplicate entry '…' for key '…'`.
+  isUniqueViolation: (error) => /ER_DUP_ENTRY|Duplicate entry/i.test(messageOf(error)),
+  upsert: 'on duplicate key',
+  // no parameter ceiling of its own; max_allowed_packet is what gives way, and it grows with the VALUES not the count.
+  maxBindings: 60000,
+  name: 'mysql',
+  supportsReturning: false,
+  columnType(column, keyed) {
+    switch (column.shape?.type) {
+      case 'integer':
+        return 'int';
+      case 'number':
+        return 'double';
+      case 'boolean':
+        return 'boolean';
+      case 'object':
+      case 'array':
+        return 'json';
+      default:
+        // TEXT cannot take part in a key without a prefix length.
+        return keyed ? `varchar(${keyLength(column)})` : 'text';
+    }
+  },
+};
+
+export const mssqlDialect: Dialect = {
+  // SQL Server: 2627 for a constraint, 2601 for a unique index — two numbers, one fact.
+  isUniqueViolation: (error) => /\b(2627|2601)\b|Violation of UNIQUE KEY/i.test(messageOf(error)),
+  upsert: false,
+  // 2100 parameters per statement, the lowest of the four by a wide margin.
+  maxBindings: 2000,
+  name: 'mssql',
+  supportsReturning: false,
+  columnType(column, keyed) {
+    switch (column.shape?.type) {
+      case 'integer':
+        return 'int';
+      case 'number':
+        return 'float';
+      case 'boolean':
+        return 'bit';
+      case 'object':
+      case 'array':
+        return 'nvarchar(max)';
+      default:
+        // nvarchar(max) is not indexable — a key narrows to a bounded length.
+        return keyed ? `nvarchar(${keyLength(column)})` : 'nvarchar(max)';
+    }
+  },
+};
+
+export const dialects: Record<DialectName, Dialect> = {
+  sqlite: sqliteDialect,
+  pg: pgDialect,
+  mysql: mysqlDialect,
+  mssql: mssqlDialect,
+};
+
+export function resolveDialect(name: DialectName): Dialect {
+  const dialect = dialects[name];
+  if (!dialect) throw new Error(`Unknown SQL dialect '${name}'. Known: ${Object.keys(dialects).join(', ')}`);
+  return dialect;
+}
+
+/**
+ * The type this column is emitted with — what the entity stated when it named THIS
+ * engine, the shape's own answer otherwise.
+ *
+ * The fallback is what keeps the statement local: `columnType: { pg: 'tsvector' }` leaves
+ * SQLite exactly where it was, so the same entity still boots on every dialect.
+ */
+export function columnTypeFor(dialect: Dialect, column: ColumnDef, keyed: boolean): string {
+  return column.stated?.columnType?.[dialect.name] ?? dialect.columnType(column, keyed);
+}

package/src/diff.ts

@@ -0,0 +1,196 @@
+/**
+ * Diff — what the database is missing, compared to what the entities describe.
+ *
+ * Two states, one comparison, one realisation. The desired state comes from the
+ * entities; the actual one from Kysely's introspection, which is already
+ * engine-agnostic. The comparison itself is pure — no IO, no SQL.
+ *
+ * ADDITIVE ONLY, and that incapacity is the guarantee: a missing table is
+ * created, a missing column is added, and **nothing else ever happens**. Drops,
+ * renames and type changes are human intentions — a rename is not even
+ * detectable from a diff (it reads as a drop plus an add). Those belong in a
+ * written migration, never in an automatic pass.
+ */
+import { sql, type Kysely } from 'kysely';
+import { addForeignKeyConstraintSQL, compiler, createTableSQL, indexSQL, type GenerateOptions } from './ddl.js';
+import { checkFor } from './check.js';
+import { columnTypeFor, resolveDialect, type DialectName } from './dialect.js';
+import {
+  isKeyed,
+  orderTables,
+  toTables,
+  toTableName,
+  type AppLike,
+  type ColumnDef,
+  type TableDef,
+} from './table.js';
+
+/** What the database actually holds: column names per table. */
+export type SchemaState = Map<string, Set<string>>;
+
+/** Read the live schema. Only names are needed — an additive pass never inspects types. */
+export async function actualState(db: Kysely<any>): Promise<SchemaState> {
+  const state: SchemaState = new Map();
+  for (const table of await db.introspection.getTables()) {
+    if (table.isView) continue;
+    state.set(table.name, new Set(table.columns.map((column) => column.name)));
+  }
+  return state;
+}
+
+/** Project the app's entities into the tables they ask for. */
+export function desiredTables(app: AppLike, options?: GenerateOptions): TableDef[] {
+  return toTables(app, options?.tableName ?? toTableName);
+}
+
+export type Change =
+  | { kind: 'createTable'; table: TableDef; deferredColumns?: string[] }
+  | { kind: 'addColumn'; table: TableDef; column: ColumnDef }
+  | { kind: 'addConstraint'; table: TableDef; column: ColumnDef }
+  | { kind: 'createIndex'; table: TableDef; column: ColumnDef };
+
+/** Compare the two states. Pure — the only place that decides what is missing. */
+export function delta(desired: TableDef[], actual: SchemaState): Change[] {
+  const changes: Change[] = [];
+  for (const table of desired) {
+    const existing = actual.get(table.name);
+    if (!existing) {
+      changes.push({ kind: 'createTable', table });
+      continue;
+    }
+    for (const column of table.columns) {
+      if (!existing.has(column.name)) changes.push({ kind: 'addColumn', table, column });
+    }
+  }
+  // Indexes, unconditionally: this pass reads column NAMES from the live schema, so it
+  // cannot see whether an index exists. `CREATE INDEX IF NOT EXISTS` is idempotent, so
+  // proposing it every time is cheaper and more honest than introspecting to guess —
+  // the alternative would be an index that a `unique()` added later never gets.
+  for (const table of desired) {
+    for (const column of table.columns) {
+      if (column.index) changes.push({ kind: 'createIndex', table, column });
+    }
+  }
+  return changes;
+}
+
+/**
+ * Order the changes `delta` found, dialect-aware — `delta` itself stays pure and
+ * unordered, this is the one place that adds engine knowledge to the plan.
+ *
+ * SQLite resolves FK targets lazily and accepts any order, with no `ALTER TABLE
+ * ADD CONSTRAINT` to defer to — changes pass through unchanged. Every other
+ * engine needs a `createTable`'s FK targets to already exist: `orderTables`
+ * sorts the NEW tables among themselves and reports the edges a cycle forces to
+ * defer as `addConstraint` changes. An `addColumn` always lands last — its
+ * table already exists (that's why it's `addColumn` and not `createTable`), but
+ * its FK target might be one of THIS batch's new tables, so it waits until
+ * every `createTable`/`addConstraint` above it has run.
+ */
+export function orderChanges(changes: Change[], dialectName: DialectName): Change[] {
+  if (dialectName === 'sqlite') return changes;
+
+  const creates = changes.filter((c): c is Extract<Change, { kind: 'createTable' }> => c.kind === 'createTable');
+  const addColumns = changes.filter((c) => c.kind === 'addColumn');
+  const indexes = changes.filter((c) => c.kind === 'createIndex');
+
+  const { ordered, deferred } = orderTables(creates.map((c) => c.table));
+  const deferredColumnsOf = new Map<string, Set<string>>();
+  for (const { table, column } of deferred) {
+    const names = deferredColumnsOf.get(table.name) ?? new Set<string>();
+    names.add(column.name);
+    deferredColumnsOf.set(table.name, names);
+  }
+
+  const createChanges: Change[] = ordered.map((table) => {
+    const names = deferredColumnsOf.get(table.name);
+    return names ? { kind: 'createTable', table, deferredColumns: [...names] } : { kind: 'createTable', table };
+  });
+  const constraintChanges: Change[] = deferred.map(({ table, column }) => ({ kind: 'addConstraint', table, column }));
+
+  // Indexes last: the column they stand on may be one this very batch added.
+  return [...createChanges, ...constraintChanges, ...addColumns, ...indexes];
+}
+
+/**
+ * Render one change.
+ *
+ * A column added to a populated table cannot be `NOT NULL` without a default —
+ * every engine refuses it. So an added column keeps its `NOT NULL` only when a
+ * default answers the existing rows; otherwise it lands nullable, and tightening
+ * it is a written migration.
+ */
+export function changeSQL(change: Change, dialectName: DialectName): string {
+  const dialect = resolveDialect(dialectName);
+  if (change.kind === 'createTable') {
+    // Reuse the same renderer as a fresh install — one builder, no drift.
+    const skip = change.deferredColumns ? new Set(change.deferredColumns) : undefined;
+    return createTableSQL(change.table, dialectName, { skipReferences: skip });
+  }
+  if (change.kind === 'addConstraint') {
+    return addForeignKeyConstraintSQL(change.table, change.column, dialectName);
+  }
+  if (change.kind === 'createIndex') {
+    // One statement per change — `migrate` runs them one by one, and no driver here
+    // accepts a batch.
+    return indexSQL(change.table, change.column, dialectName);
+  }
+  const { table, column } = change;
+  const type = columnTypeFor(dialect, column, isKeyed(table, column));
+  return compiler(dialectName)
+    .schema.alterTable(table.name)
+    .addColumn(column.name, sql.raw(type) as any, (col) => {
+      let built = col;
+      if (column.default !== undefined) {
+        built = built.defaultTo(column.default);
+        if (!column.nullable) built = built.notNull();
+      }
+      if (column.references) {
+        built = built.references(`${column.references.table}.${column.references.column}`);
+        if (column.references.onDelete) built = built.onDelete(column.references.onDelete);
+      }
+      // Inline rather than a named table constraint: SQLite cannot ALTER one in, and
+      // the column is new, so no existing row can be caught out by it. A column that
+      // arrives later is bounded like a column that was there from the start.
+      const check = checkFor(column);
+      if (check) built = built.check(check);
+      return built;
+    })
+    .compile().sql;
+}
+
+/** Everything the database is missing, as statements ready to run. */
+export async function planMigration(
+  app: AppLike,
+  db: Kysely<any>,
+  options?: GenerateOptions,
+): Promise<{ changes: Change[]; statements: string[] }> {
+  const dialect = options?.dialect ?? 'sqlite';
+  const changes = orderChanges(delta(desiredTables(app, options), await actualState(db)), dialect);
+  return { changes, statements: changes.map((change) => changeSQL(change, dialect)) };
+}
+
+/**
+ * Bring the database up to what the entities describe — additively.
+ *
+ * Returns what it did, so a caller can log or refuse. Replaces the old
+ * create-if-not-exists pass: it also catches a field added to an existing entity,
+ * which used to be silently ignored.
+ */
+/**
+ * Bring the schema up to date. Takes the setup itself — `migrate(app, setup)` — so the
+ * common case never has to reach into `setup.db`, the one handle that meets no judge.
+ * A bare Kysely instance is still accepted, for a caller who holds only that.
+ */
+export async function migrate(
+  app: AppLike,
+  target: Kysely<any> | { db: Kysely<any> },
+  options?: GenerateOptions,
+): Promise<Change[]> {
+  const db = (target as { db?: Kysely<any> }).db ?? (target as Kysely<any>);
+  const { changes, statements } = await planMigration(app, db, options);
+  for (const statement of statements) {
+    await sql.raw(statement).execute(db);
+  }
+  return changes;
+}

package/src/fields.ts

@@ -0,0 +1,24 @@
+/**
+ * What an entity may state for THIS adapter, declared from OUTSIDE `@fougere/schema` —
+ * which names no engine and no column type, and must not learn one to let this exist.
+ *
+ * It replaces what the shape would have given, and only for the engine it names: an
+ * engine absent here keeps the shape's answer, so the entity still boots on every
+ * dialect. What an engine must HONOR is not stated here — it is a decision, and it
+ * belongs in `fougere.config.ts` beside `remotes:`, `sources:` and `ports:`.
+ */
+import type { DialectName } from './dialect.js';
+
+/** What sql holds, addressed by field — the shape every augmentation of the registry takes. */
+export type SqlFields<K extends string> = Partial<Record<K, SqlField>>;
+
+export interface SqlField {
+  /** The column type to emit, per engine. An engine absent here keeps the shape's own. */
+  columnType?: Partial<Record<DialectName, string>>;
+}
+
+declare module '@fougere/schema' {
+  interface FougereEntityAdapters<K extends string> {
+    sql?: SqlFields<K>;
+  }
+}