@fougere/adapter-sql 0.6.0-alpha.0 → 0.8.0-alpha.0

package/src/crud.ts

@@ -1,25 +1,12 @@
 import { Lifecycle, Role } from '@fougere/schema';
-/**
- * SqlStorage — per-entity storage over Kysely, one implementation for every engine.
- *
- * Structurally matches @fougere/core's Storage (duck typed, no dep). There is
- * no generated table object: Kysely addresses tables and columns by name, so the
- * entity stays the only description. The field↔column mapping is explicit rather
- * than a global plugin — auth tables carry their own naming and must not be
- * rewritten behind the caller's back.
- *
- * `create` and `update` re-read the row instead of using `RETURNING`: the
- * contract is to hand back the COMPLETE row, including defaults realised by SQL.
- * That also makes the code identical on MySQL and SQL Server, which have no
- * `RETURNING` clause.
- */
+/** SqlStorage — per-entity storage over Kysely, one implementation for every engine. */
 import { sql, type Kysely } from 'kysely';
-import { applyCreate, applyUpdate, schemaOf, type Fields, type SchemaView, type SchemaOrCard } from '@fougere/schema';
+import { applyCreate, applyUpdate, type Fields, type SchemaView } from '@fougere/schema';
 import { toTable, toTableName, type TableDef } from './table.js';
 import { resolveDialect, type Dialect, type DialectName } from './dialect.js';
 // The contract entry and not the main one: `FougereError` crosses a process boundary and
 // lives there for that reason, and this package must not drag the boot to raise one.
-import { FougereError, ErrorCode } from '@fougere/core/contract';
+import { comparisonOf, comparisonsIn, ErrorCode, FougereError, type Comparison } from '@fougere/core/contract';
 import { codecsOf, type ValueCodec } from './values.js';
 
 /** ListOptions — duplicated from @fougere/core to avoid a runtime dep. */
@@ -48,14 +35,7 @@ interface PrimaryKeyInfo {
   isComposite: boolean;
 }
 
-/**
- * The primary key, read off the role axis.
- *
- * Used to answer "what identifies a row" — where to point a WHERE, what a cursor
- * carries. The generated ids and managed timestamps that used to be computed here
- * moved to `applyCreate`/`applyUpdate` (`@fougere/schema`): nothing in them was about
- * SQL, and every other storage was re-deriving them from scratch.
- */
+/** The primary key, read off the role axis. */
 function analyzeFields(entity: SchemaView): { pk: PrimaryKeyInfo } {
   const pkNames = Object.entries(entity.getFields())
     .filter(([, field]) => Role.of(field).isPrimary)
@@ -110,7 +90,7 @@ export class SqlStorage {
 
   constructor(
     private db: Kysely<any>,
-    source: SchemaOrCard,
+    entity: SchemaView,
     tableName: string,
     selectFields?: Set<string>,
     dialect: DialectName = 'sqlite',
@@ -119,10 +99,6 @@ export class SqlStorage {
     this.dialect = resolved;
     this.maxBindings = resolved.maxBindings;
     this.upsertClause = resolved.upsert;
-    // Normalized once: the table projection and the axis analysis below both read the
-    // schema, and a card handed to each separately would be rebuilt twice into two
-    // unrelated field objects. Past this line nothing knows which form arrived.
-    const entity = schemaOf(source);
     this.table = toTable(tableName, entity);
     for (const column of this.table.columns) {
       this.toColumn.set(column.field, column.name);
@@ -134,7 +110,7 @@ export class SqlStorage {
     this.selectFields = selectFields;
   }
 
-  /** The Kysely instance this storage wraps — no judge sits behind it. See Storage.client. */
+  /** The Kysely instance this storage wraps — no validator sits behind it. See Storage.client. */
   get client(): Kysely<any> {
     return this.db;
   }
@@ -142,7 +118,7 @@ export class SqlStorage {
   /** Returns a scoped storage that restricts all read results to the fields of the given schema. */
   output(schema: SchemaView): SqlStorage {
     const scoped = Object.create(this) as SqlStorage;
-    (scoped as any).selectFields = new Set(Object.keys(schema.getFields()));
+    scoped.selectFields = new Set(Object.keys(schema.getFields()));
     return scoped;
   }
 
@@ -177,18 +153,11 @@ export class SqlStorage {
     return data;
   }
 
-  /**
-   * Apply a primary-key filter (simple or composite).
-   *
-   * The key crosses to the column exactly like every other value — `whereAll` states
-   * the rule two lines below and this did not follow it. It cost nothing while every
-   * generated key was a string; a key that holds a Date (`primary(created())`) inserted
-   * fine and then failed its own re-read, with the row already persisted.
-   */
+  /** Apply a primary-key filter (simple or composite). */
   private wherePk<Q extends { where(a: any, b: any, c: any): Q }>(query: Q, id: string | Record<string, unknown>): Q {
     if (this.pk.isComposite) {
-      const obj = id as Record<string, unknown>;
-      return this.pk.names.reduce((q, name) => q.where(this.column(name), '=', this.write(name, obj[name])), query);
+      const composite = id as Record<string, unknown>;
+      return this.pk.names.reduce((q, name) => q.where(this.column(name), '=', this.write(name, composite[name])), query);
     }
     const name = this.pk.names[0];
     return query.where(this.column(name), '=', this.write(name, id));
@@ -203,12 +172,50 @@ export class SqlStorage {
   // dual already went through this same door. An empty set matches nothing, said in
   // SQL rather than by returning the whole table.
   private whereAll<Q extends { where(a: any, b: any, c: any): Q }>(query: Q, criteria: Record<string, unknown>): Q {
-    return Object.entries(criteria).reduce(
-      (q, [key, value]) => Array.isArray(value)
+    return Object.entries(criteria).reduce((q, [key, value]) => {
+      const comparison = comparisonOf(this.fields[key], value);
+      if (comparison) return this.compared(q, key, comparison);
+
+      return Array.isArray(value)
         ? q.where(this.column(key), 'in', [...new Set(value)].map((v) => this.write(key, v)))
-        : q.where(this.column(key), '=', this.write(key, value)),
-      query,
-    );
+        : q.where(this.column(key), '=', this.write(key, value));
+    }, query);
+  }
+
+  /**
+   * What a bare value and a set could not say. Every comparison a criterion names is
+   * AND-ed, which is the rule two criteria already follow — `{ gte: 100, lte: 400 }` is
+   * one range, not two answers.
+   */
+  private compared<Q extends { where(a: any, b: any, c: any): Q }>(
+    query: Q,
+    key: string,
+    comparison: Comparison,
+  ): Q {
+    const column = this.column(key);
+    const bound = (value: unknown) => this.write(key, value);
+
+    return comparisonsIn(comparison).reduce((q, [name, value]) => {
+      switch (name) {
+        case 'gte': return q.where(column, '>=', bound(value));
+        case 'lte': return q.where(column, '<=', bound(value));
+        case 'gt': return q.where(column, '>', bound(value));
+        case 'lt': return q.where(column, '<', bound(value));
+        case 'ne': return q.where(column, '!=', bound(value));
+        case 'contains': return q.where(column, 'like', `%${String(value)}%`);
+        case 'notIn': {
+          const values = [...new Set(value as readonly unknown[])].map(bound);
+
+          return values.length ? q.where(column, 'not in', values) : q;
+        }
+        case 'isNull': return q.where(column, value ? 'is' : 'is not', null);
+        case 'between': {
+          const [low, high] = value as [unknown, unknown];
+
+          return q.where(column, '>=', bound(low)).where(column, '<=', bound(high));
+        }
+      }
+    }, query);
   }
 
   async list(options?: ListOptions & SelectOption & { where?: Record<string, unknown> }): Promise<ListResult<Record<string, unknown>>> {
@@ -277,11 +284,8 @@ export class SqlStorage {
   }
 
   /**
-   * One query for N keys, never N queries — what every page-level read stands on:
-   * a computed field, a relation, a resolver on the other side of a wire.
-   *
-   * A composite key has no list form: it is refused by name rather than answering a
-   * partial result that reads as complete.
+   * One query for N keys, never N queries — what every page-level read stands on: a computed
+   * field, a relation, a resolver on the other side of a wire.
    */
   async findByKeys(ids: readonly string[], options?: SelectOption): Promise<Map<string, Record<string, unknown>>> {
     if (this.pk.isComposite) {
@@ -307,13 +311,7 @@ export class SqlStorage {
     return found;
   }
 
-  /**
-   * The other direction of a relation, in one query — see the port's `findAllByKeys`.
-   *
-   * The grouping key is read off the ROW rather than trusted from the request: a codec
-   * may write a value one way and read it back another, and a group keyed on the
-   * request's spelling would then be empty while the rows sit there.
-   */
+  /** The other direction of a relation, in one query — see the port's `findAllByKeys`. */
   async findAllByKeys(
     field: string,
     keys: readonly string[],
@@ -324,25 +322,13 @@ export class SqlStorage {
     const rows = await this.findAllBy({ [field]: [...keys] }, options);
     for (const row of rows) {
       const key = String(row[field]);
-      const held = grouped.get(key);
-      if (held) held.push(row); else grouped.set(key, [row]);
+      const bucket = grouped.get(key);
+      if (bucket) bucket.push(row); else grouped.set(key, [row]);
     }
     return grouped;
   }
 
-  /**
-   * Write the row, or make the existing one look like this — one statement.
-   *
-   * The gesture an import needs and the port did not have: `create` throws on the
-   * second run (`UNIQUE constraint failed`), so re-reading anything meant deleting
-   * first. Measured pulling 500 rows from an API twice.
-   *
-   * Both lifecycles are realized, each on the side it belongs to: `applyCreate` fills
-   * what a first write owes (a generated key, `created()`, a declared default) and
-   * `applyUpdate` stamps what every write owes (`updated()`). On conflict the key and
-   * the creation stamps are left alone — a row keeps the moment it appeared, whatever
-   * later overwrites say.
-   */
+  /** Write the row, or make the existing one look like this — one statement. */
   async upsert(input: Record<string, unknown>, options?: SelectOption): Promise<Record<string, unknown>> {
     if (this.upsertClause === false) {
       throw new Error(
@@ -373,17 +359,7 @@ export class SqlStorage {
     return (await this.findById(id as never, options))!;
   }
 
-  /**
-   * Upsert a whole page in one statement — what an import writes through.
-   *
-   * Row by row, 500 rows were 500 statements (measured pulling an API); the shape of
-   * an import is a page, so the write should be one too. Sliced like every other batch,
-   * but by rows × COLUMNS: a statement binds values, not rows, so the ceiling divides.
-   *
-   * Answers how many rows were written and not the rows themselves. `create` hands back
-   * the complete row because a caller acts on it; an import acts on none of them, and
-   * re-reading a page to satisfy a symmetry nobody uses would double the work.
-   */
+  /** Upsert a whole page in one statement — what an import writes through. */
   async upsertAll(inputs: readonly Record<string, unknown>[], _options?: SelectOption): Promise<number> {
     if (this.upsertClause === false) {
       throw new Error(
@@ -460,12 +436,7 @@ export class SqlStorage {
     return out;
   }
 
-  /**
-   * One criteria object per statement — the oversized set is the one that splits.
-   *
-   * Only ONE criterion may be split: two split sets would need their cross product,
-   * which is a different query, so the second is refused rather than silently wrong.
-   */
+  /** One criteria object per statement — the oversized set is the one that splits. */
   private refuseOversized(criteria: Record<string, unknown>, op: string): void {
     for (const [key, value] of Object.entries(criteria)) {
       if (!Array.isArray(value) || new Set(value).size <= this.maxBindings) continue;
@@ -500,7 +471,7 @@ export class SqlStorage {
 
     await this.refusal(() => this.db.insertInto(this.table.name).values(this.toRow(data)).execute());
 
-    // Contract: create returns the COMPLETE row (validation judges absence, it
+    // Contract: create returns the COMPLETE row (validation validates absence, it
     // never fills) — re-read so SQL-realised defaults appear. Same move as update().
     const id = this.pk.isComposite
       ? Object.fromEntries(this.pk.names.map((n) => [n, data[n]]))
@@ -523,12 +494,8 @@ export class SqlStorage {
   }
 
   /**
-   * A duplicate is an ANSWER, not a failure — so it leaves as `CONFLICT` and not as the
-   * blank `Internal error` a caller used to get. The engine's own wording never travels:
-   * it names a table and a constraint, which is our schema and not the caller's business.
-   *
-   * Only the dialect can recognize it; this method knows no engine, which is the rule
-   * `dialect.ts` exists to keep.
+   * A duplicate is an ANSWER, not a failure — so it leaves as `CONFLICT` and not as the blank
+   * `Internal error` a caller used to get.
    */
   private async refusal<R>(write: () => Promise<R>): Promise<R> {
     try {
@@ -557,14 +524,8 @@ export interface StorageFactoryOptions {
   tableName?: (entityName: string) => string;
 }
 
-/**
- * Create a StorageFactory backed by Kysely — same call shape on every engine.
- *
- * ```ts
- * const app = await createApp({ createContainer, storageFactory: createStorageFactory(db) });
- * ```
- */
+/** Create a StorageFactory backed by Kysely — same call shape on every engine. */
 export function createStorageFactory(db: Kysely<any>, options?: StorageFactoryOptions, dialect: DialectName = 'sqlite') {
   const resolve = options?.tableName ?? toTableName;
-  return (entity: SchemaOrCard, name: string) => new SqlStorage(db, entity, resolve(name), undefined, dialect);
+  return (entity: SchemaView, name: string) => new SqlStorage(db, entity, resolve(name), undefined, dialect);
 }

package/src/ddl.ts

@@ -1,12 +1,4 @@
-/**
- * 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.
- */
+/** DDL — the table description, rendered as SQL. */
 import {
   Kysely,
   DummyDriver,
@@ -18,13 +10,13 @@ import {
 } from 'kysely';
 import {
   isKeyed,
-  orderTables,
   toTableName,
   toTables,
   type AppLike,
   type ColumnDef,
   type TableDef,
 } from './table.js';
+import { orderTables } from './order.js';
 import { columnTypeFor, resolveDialect, type DialectName } from './dialect.js';
 import { checkFor } from './check.js';
 
@@ -58,18 +50,7 @@ export function compiler(name: DialectName): Kysely<any> {
 
 // ─── 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`).
- */
+/** Render `CREATE TABLE` for one described table. */
 export function createTableSQL(
   table: TableDef,
   dialectName: DialectName,
@@ -89,7 +70,7 @@ export function createTableSQL(
       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
+      // Uniqueness is the storage's to enforce: no shape can express it, since validating
       // one value never sees the other rows.
       if (column.unique) built = built.unique();
       if (column.references && !skip?.has(column.name)) {
@@ -121,18 +102,16 @@ export function createTableSQL(
   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).
- */
+/** `CREATE INDEX` for every column that asked for one. */
 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);
+  // A `unique()` on a table that already exists has nowhere else to land: `createTable`
+  // writes it as a column constraint, and no engine here can ALTER one in. As an index it
+  // arrives — or the statement fails on the rows that already break it, which is the answer.
+  if (column.unique) builder = builder.unique();
   if (dialectName !== 'mssql') builder = builder.ifNotExists();
   return builder.compile().sql;
 }
@@ -145,10 +124,8 @@ export function createIndexSQL(table: TableDef, dialectName: DialectName): strin
 }
 
 /**
- * `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.
+ * `ALTER TABLE ADD CONSTRAINT` for one FK `orderTables` deferred — closes a relation cycle once
+ * every table in it exists.
  */
 export function addForeignKeyConstraintSQL(table: TableDef, column: ColumnDef, dialectName: DialectName): string {
   const ref = column.references!;
@@ -170,20 +147,8 @@ export interface GenerateOptions {
 }
 
 /**
- * `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.
+ * `CREATE TABLE` for every entity the app hosts — scanned frond entities plus auth runtime
+ * entities when present.
  */
 export function generateSQL(app: AppLike, options?: GenerateOptions): string[] {
   const resolve = options?.tableName ?? toTableName;
@@ -227,13 +192,7 @@ 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.
- */
+/** Create every missing table. */
 export function autoMigrate(app: AppLike, sink: SqlSink, options?: GenerateOptions): void | Promise<void> {
   const pending = generateSQL(app, options)
     .map((statement) => runOn(sink, statement))

package/src/dialect.ts

@@ -1,62 +1,22 @@
-/**
- * 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`.
- */
+/** Dialect — the only place that speaks SQL. */
 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.
-   */
+  /** SQL type for a column. */
   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.
-   */
+  /** How many values one statement may bind — what splits a batch read into several. */
   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.
-   */
+  /** How this engine spells "write it, or replace what is there". */
   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.
-   */
+  /** Is this the engine refusing a duplicate, rather than failing? */
   isUniqueViolation(error: unknown): boolean;
 }
 
@@ -193,11 +153,8 @@ export function resolveDialect(name: DialectName): 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.
+ * The type this column is emitted with — what the entity stated when it named THIS engine, the
+ * shape's own answer otherwise.
  */
 export function columnTypeFor(dialect: Dialect, column: ColumnDef, keyed: boolean): string {
   return column.stated?.columnType?.[dialect.name] ?? dialect.columnType(column, keyed);

package/src/diff.ts

@@ -1,29 +1,17 @@
-/**
- * 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.
- */
+/** Diff — what the database is missing, compared to what the entities describe. */
 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';
+import { orderTables } from './order.js';
 
 /** What the database actually holds: column names per table. */
 export type SchemaState = Map<string, Set<string>>;
@@ -66,26 +54,21 @@ export function delta(desired: TableDef[], actual: SchemaState): Change[] {
   // 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.
+  //
+  // `unique` comes here too, and for that very reason: written as a column constraint it
+  // only ever reached a table being created, so the rule was declared and never realized on
+  // a database that had already lived. A unique index is the one form that can arrive late.
   for (const table of desired) {
     for (const column of table.columns) {
-      if (column.index) changes.push({ kind: 'createIndex', table, column });
+      if (column.index || (column.unique && !column.primary)) 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.
+ * 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.
  */
 export function orderChanges(changes: Change[], dialectName: DialectName): Change[] {
   if (dialectName === 'sqlite') return changes;
@@ -112,14 +95,7 @@ export function orderChanges(changes: Change[], dialectName: DialectName): Chang
   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.
- */
+/** Render one change. */
 export function changeSQL(change: Change, dialectName: DialectName): string {
   const dialect = resolveDialect(dialectName);
   if (change.kind === 'createTable') {
@@ -141,10 +117,12 @@ export function changeSQL(change: Change, dialectName: DialectName): string {
     .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.default !== undefined) built = built.defaultTo(column.default);
+      // Stated whether a default fills it or not: the same declaration gave NOT NULL on a
+      // fresh table and nothing on a migrated one, so two databases of one entity promised
+      // different things. Without a default the engine refuses on a table holding rows —
+      // which is the refusal `planStep` already names, arriving here instead of never.
+      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);
@@ -170,18 +148,8 @@ export async function planMigration(
   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.
- */
+/** Bring the database up to what the entities describe — additively. */
+/** Bring the schema up to date. */
 export async function migrate(
   app: AppLike,
   target: Kysely<any> | { db: Kysely<any> },