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

package/src/drift.ts

@@ -0,0 +1,75 @@
+/** What a table PROMISES and what it now holds, when the two stopped agreeing. */
+import type { Kysely } from 'kysely';
+
+import type { TableDef } from './table.js';
+
+/** One column whose declaration moved and whose table did not follow. */
+export interface Drift {
+  table: string;
+  column: string;
+  /** What the entity says now. */
+  declared: string;
+  /** What the table still enforces. */
+  held: string;
+  /** What it costs, said where the reader is — a boot, not a migration plan. */
+  reason: string;
+}
+
+/**
+ * A migration is ADDITIVE by design: it creates what is missing and never touches a
+ * column that exists. That is a promise worth keeping — nothing is dropped behind your
+ * back — but it leaves a second fact unsaid, and unsaid is where it hurt: relax a
+ * `required` field and the table keeps its NOT NULL, so the write fails on a row, in
+ * production, long after the boot that could have named it.
+ *
+ * What is read here is what `actualState` already receives and throws away. `SchemaState`
+ * stays a set of names on purpose: `done()` reads it to decide whether a frozen step was
+ * already applied, and a wider one would make a replayed migration answer wrong.
+ */
+export async function drift(db: Kysely<any>, desired: TableDef[]): Promise<Drift[]> {
+  const held = new Map(
+    (await db.introspection.getTables())
+      .filter((table) => !table.isView)
+      .map((table) => [table.name, table.columns]),
+  );
+
+  const found: Drift[] = [];
+  for (const table of desired) {
+    const columns = held.get(table.name);
+    if (!columns) continue;
+
+    for (const column of table.columns) {
+      const live = columns.find((one) => one.name === column.name);
+      // A column the table does not have yet is the additive pass's business, not this one.
+      if (!live) continue;
+
+      if (column.nullable && !live.isNullable) {
+        found.push({
+          table: table.name,
+          column: column.name,
+          declared: 'optional',
+          held: 'NOT NULL',
+          reason: 'a write with no value for it fails at the row, not at boot',
+        });
+      }
+      if (!column.nullable && live.isNullable && !column.primary) {
+        found.push({
+          table: table.name,
+          column: column.name,
+          declared: 'required',
+          held: 'nullable',
+          reason: 'the door refuses what the table would still accept',
+        });
+      }
+    }
+  }
+
+  return found;
+}
+
+/** The one line a boot has room for, and the detail under it. */
+export const driftReport = (found: Drift[]): string =>
+  `${found.length} column(s) declare one thing and the table holds another:\n`
+  + found
+    .map((one) => `  ${one.table}.${one.column} — declared ${one.declared}, table keeps ${one.held}: ${one.reason}`)
+    .join('\n');

package/src/fields.ts

@@ -1,22 +1,31 @@
 /**
- * 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:`.
+ * 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.
  */
+import { AdapterFieldValidator, type Shape } from '@fougere/schema';
+import ENTRY_FORMAT from './adapter.schema.json' with { type: 'json' };
 import type { DialectName } from './dialect.js';
 
+/** The engines the format names — the one list, read off the file that states it. */
+type Engine = keyof typeof ENTRY_FORMAT.properties.columnType.properties;
+
 /** What sql holds, addressed by field — the shape every augmentation of the registry takes. */
 export type SqlFields<K extends string> = Readonly<Partial<Record<K, SqlField>>>;
 
 export interface SqlField {
   /** The column type to emit, per engine. An engine absent here keeps the shape's own. */
-  readonly columnType?: Readonly<Partial<Record<DialectName, string>>>;
+  readonly columnType?: Readonly<Partial<Record<Engine, string>>>;
 }
 
+/** Judges what an entity states under `adapters.sql`, against the format this adapter ships. */
+export const sqlEntries = AdapterFieldValidator.of(ENTRY_FORMAT as Shape);
+
+type Assert<T extends true> = T;
+/** A fifth dialect does not compile until `adapter.schema.json` names it. */
+type _EnginesMatchDialects = Assert<
+  [Exclude<DialectName, Engine>] extends [never] ? true : false
+>;
+
 declare module '@fougere/schema' {
   interface FougereEntityAdapters<K extends string> {
     sql?: SqlFields<K>;

package/src/index.ts

@@ -1,15 +1,15 @@
 export { createTableSQL, createIndexSQL, indexSQL, addForeignKeyConstraintSQL, generateSQL, autoMigrate, compiler } from './ddl.js';
 export { onQuery, logQueries, type QueryEvent, type QuerySink } from './query.js';
+export type { FkEdge, TableOrder } from './order.js';
 export type { GenerateOptions, SqlSink } from './ddl.js';
-export { toTable, toTables, toTableName, toSnakeCase, isKeyed, orderTables } from './table.js';
+export { toTable, toTables, toTableName, toSnakeCase, isKeyed } from './table.js';
+export { orderTables } from './order.js';
 export type {
   TableDef,
   ColumnDef,
   ColumnShape,
   ColumnReference,
   RelationResolve,
-  FkEdge,
-  TableOrder,
   EntityEntry,
   FrondLike,
   AppLike,
@@ -34,6 +34,8 @@ export type { ValueCodec } from './values.js';
 // runtime that has neither. It lives at `@fougere/adapter-sql/sqlite`.
 export { setupKysely, sqlSink } from './setup.js';
 export type { Setup, SqlSource, SetupOptions } from './setup.js';
+export { drift, driftReport } from './drift.js';
+export type { Drift } from './drift.js';
 export { actualState, desiredTables, delta, orderChanges, changeSQL, planMigration, migrate } from './diff.js';
 export type { SchemaState, Change } from './diff.js';
 // The non-additive half — realised only from a step a human wrote down.

package/src/order.ts

@@ -0,0 +1,63 @@
+/**
+ * In what order a batch of tables is created — the one question that reads a `TableDef` and
+ * knows nothing above it: no entity, no axis, no schema.
+ */
+import type { ColumnDef, TableDef } from './table.js';
+
+export interface FkEdge {
+  table: TableDef;
+  column: ColumnDef;
+}
+
+export interface TableOrder {
+  /** Tables in dependency order — a `ref()` target always precedes its referrer. */
+  ordered: TableDef[];
+  /** FK columns whose target could not be ordered first — a cycle. Constrain after creation. */
+  deferred: FkEdge[];
+}
+
+/**
+ * Order a table set so a `ref()`'s target always exists before the table that points at it —
+ * required by every engine except SQLite, which resolves FK targets lazily and accepts any order
+ * (and has no `ALTER TABLE ADD CONSTRAINT` to close a cycle with — a caller on that dialect skips
+ * this function entirely).
+ */
+export function orderTables(tables: TableDef[]): TableOrder {
+  const byName = new Map(tables.map((table) => [table.name, table]));
+  const needs = new Map(
+    tables.map((table) => [
+      table.name,
+      new Set(
+        table.columns
+          .filter((c) => c.references && c.references.table !== table.name && byName.has(c.references.table))
+          .map((c) => c.references!.table),
+      ),
+    ]),
+  );
+
+  const ordered: TableDef[] = [];
+  const deferred: FkEdge[] = [];
+  const done = new Set<string>();
+
+  while (needs.size > 0) {
+    const ready = [...needs.keys()].find((name) => [...needs.get(name)!].every((dep) => done.has(dep)));
+    if (ready) {
+      ordered.push(byName.get(ready)!);
+      done.add(ready);
+      needs.delete(ready);
+      continue;
+    }
+    // Every table left waits on another table left — a cycle. Break it by
+    // deferring one edge: every column of the first remaining table that points
+    // at its first unmet dependency.
+    const [name, deps] = [...needs.entries()][0];
+    const dep = [...deps].find((d) => !done.has(d))!;
+    const table = byName.get(name)!;
+    for (const column of table.columns) {
+      if (column.references?.table === dep) deferred.push({ table, column });
+    }
+    deps.delete(dep);
+  }
+
+  return { ordered, deferred };
+}

package/src/query.ts

@@ -5,12 +5,7 @@ export interface QueryEvent {
   /** Which storage ran it — a process may open several (`sources:`). */
   storage: string;
   sql: string;
-  /**
-   * How MANY parameters, never their values.
-   *
-   * They are user data nobody chose to expose — the rule the call log states for a body.
-   * The count is what a reader needs anyway: it is how you see an `IN (?, ?, ?)` grow.
-   */
+  /** How MANY parameters, never their values. */
   parameters: number;
   /** Rounded to three decimals: a sub-microsecond statement reports 17 digits otherwise. */
   ms: number;
@@ -22,17 +17,7 @@ export type QuerySink = (event: QueryEvent) => void;
 
 const sinks: QuerySink[] = [];
 
-/**
- * Be told about every statement this process runs, and get the unsubscription back.
- *
- * A subscription and not an option, for one reason that decides it: Kysely takes its `log`
- * at CONSTRUCTION, and the storage is built during the boot — before any extension's
- * `up(app)` runs. So the only way to subscribe afterwards is for the log to be installed
- * from the start and route to whoever is listening.
- *
- * The same shape core states for `onLog` and observability for `onSpan`. Costs nothing when
- * nobody listens: `logQueries` returns on an empty list before touching the event.
- */
+/** Be told about every statement this process runs, and get the unsubscription back. */
 export function onQuery(sink: QuerySink): () => void {
   sinks.push(sink);
 

package/src/setup.ts

@@ -1,17 +1,10 @@
-/**
- * Storage setup — the shape every engine answers, and no driver at all.
- *
- * Fougere has no business choosing a driver (`pg`, `mysql2`, `tedious`, `better-sqlite3`,
- * a D1 binding), so the caller builds the Kysely dialect and hands it over — no dynamic
- * import, no optional dependency. This file therefore reaches for nothing: it is what a
- * runtime with no filesystem imports. The one driver this package does own lives behind
- * `@fougere/adapter-sql/sqlite`.
- */
+/** Storage setup — the shape every engine answers, and no driver at all. */
 import { Kysely, sql, type Dialect as KyselyDialect } from 'kysely';
 import type { Source, SourceView } from '@fougere/core';
 import { createStorageFactory, type StorageFactoryOptions } from './crud.js';
 import { logQueries } from './query.js';
-import { migrate } from './diff.js';
+import { desiredTables, migrate } from './diff.js';
+import { drift, driftReport } from './drift.js';
 import { toTableName } from './table.js';
 import type { DialectName } from './dialect.js';
 import type { SqlSink } from './ddl.js';
@@ -19,63 +12,39 @@ import type { SqlSink } from './ddl.js';
 export interface SetupOptions {
   /** Override naming for specific entities (e.g. better-auth wants singular table names). */
   storageFactoryOptions?: StorageFactoryOptions;
-  /**
-   * What to call this storage when a query is reported.
-   *
-   * A process may open several (`sources:`), and a module-level sink sees them all — without
-   * a name, two statements from two databases read as one stream. Defaults to what
-   * distinguishes them anyway: the engine here, the file path for SQLite.
-   */
+  /** What to call this storage when a query is reported. */
   name?: string;
 }
 
-/**
- * A `Source` realized by SQL — and the three members that are SQL's, not the routing's.
- *
- * `dialect`, `db` and `sink` are to a source what `Kysely` is to `SqlStorage.client`: what
- * this adapter is MADE OF, reached by narrowing. Nothing that routes entities across
- * sources reads them.
- */
+/** A `Source` realized by SQL — and the three members that are SQL's, not the routing's. */
 export interface SqlSource extends Source {
   dialect: DialectName;
   storageFactory: ReturnType<typeof createStorageFactory>;
   /** Runs raw statements — what `autoMigrate` writes through. */
   sink: SqlSink;
   /**
-   * The Kysely instance, for what precedes any entity: `migrate(app, setup)` writes the
-   * schema through it, and a script may need it before a container exists.
-   *
-   * It is not the way to reach data from inside an app — that is the injected `Storage`,
-   * whose `client` gives the same handle while keeping the scope of its entity.
+   * The Kysely instance, for what precedes any entity: `migrate(app, setup)` writes the schema
+   * through it, and a script may need it before a container exists.
    */
   db: Kysely<any>;
-  /**
-   * Run `fn` inside one transaction of this engine, with a storage factory bound to it.
-   *
-   * The transaction belongs to the engine, so obtaining one is a gesture on the engine and
-   * nowhere else. Nothing new is handed back: `Transaction<DB> extends Kysely<DB>` and
-   * `SqlStorage` takes a `Kysely<any>`, so the SAME storage is rebuilt over the substituted
-   * connection — which is why a frame needs no support in this package.
-   */
+  /** Run `fn` inside one transaction of this engine, with a storage factory bound to it. */
   transacted<R>(fn: (storageFactory: ReturnType<typeof createStorageFactory>) => Promise<R>): Promise<R>;
 }
 
 /** The name this shape answered to before it was one realization among several. */
 export type Setup = SqlSource;
 
-/**
- * The migration of what lives in ONE sql source, carrying its own dialect.
- *
- * It was the router's gesture, which had to know how SQL migrates — and did not pass the
- * dialect, so every source was migrated as sqlite, the documented Postgres case included.
- * A source knows its own engine, so the gesture is its own.
- */
+/** What every SQL engine keeps at the rows, whatever the dialect: the index IS the constraint. */
+export const sqlEnforces = ['unique'] as const;
+
+/** The migration of what lives in ONE sql source, carrying its own dialect. */
 function migrating(db: Kysely<any>, dialect: DialectName, opts: SetupOptions) {
-  return async (view: SourceView): Promise<void> => {
-    await migrate(view as never, db, {
-      dialect,
-      tableName: opts.storageFactoryOptions?.tableName ?? toTableName,
-    });
+  return async (view: SourceView): Promise<void | string> => {
+    const options = { dialect, tableName: opts.storageFactoryOptions?.tableName ?? toTableName };
+    await migrate(view as never, db, options);
+    const found = await drift(db, desiredTables(view as never, options));
+
+    return found.length ? driftReport(found) : undefined;
   };
 }
 
@@ -99,6 +68,7 @@ export function setupKysely(
     migrate: migrating(db, dialect, opts),
     close: () => db.destroy(),
     name: opts.name ?? dialect,
+    enforces: sqlEnforces,
     transacted: (fn) => db.transaction().execute((trx) => fn(createStorageFactory(trx, opts.storageFactoryOptions, dialect))),
   };
 }

package/src/sqlite.ts

@@ -1,20 +1,13 @@
-/**
- * SQLite on a file — the convention a first run meets, and the only driver this package owns.
- *
- * It sits behind its own subpath because `better-sqlite3` is a NATIVE module and `node:fs`
- * is a builtin: a bundler cannot prune a module that imports them, so re-exporting this
- * from the index made the whole adapter unreachable from a runtime that has neither. Same
- * cut as `@fougere/transport-http/receive`, and for the same reason — share the projection,
- * never the plumbing.
- */
+/** SQLite on a file — the convention a first run meets, and the only driver this package owns. */
 import { mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { Kysely, SqliteDialect } from 'kysely';
 import Database from 'better-sqlite3';
 import { createStorageFactory } from './crud.js';
 import { logQueries } from './query.js';
-import { sqlSink, type SetupOptions, type SqlSource } from './setup.js';
-import { migrate } from './diff.js';
+import { drift, driftReport } from './drift.js';
+import { sqlSink, sqlEnforces, type SetupOptions, type SqlSource } from './setup.js';
+import { desiredTables, migrate } from './diff.js';
 import { toTableName } from './table.js';
 import { Sources, type Source, type SourceConfig, type SourceView } from '@fougere/core';
 
@@ -43,22 +36,22 @@ export function setupSqlite(opts: SqliteSetupOptions = {}): SqliteSetup {
     storageFactory: createStorageFactory(db, opts.storageFactoryOptions, 'sqlite'),
     sink: sqlSink(db),
     migrate: async (view: SourceView) => {
-      await migrate(view as never, db, { dialect: 'sqlite', tableName: opts.storageFactoryOptions?.tableName ?? toTableName });
+      const options = { dialect: 'sqlite' as const, tableName: opts.storageFactoryOptions?.tableName ?? toTableName };
+      await migrate(view as never, db, options);
+      // What the additive pass left alone and the entity no longer agrees with. Asked
+      // AFTER, so a column it just created is judged against what it just wrote.
+      const found = await drift(db, desiredTables(view as never, options));
+
+      return found.length ? driftReport(found) : undefined;
     },
     close: () => db.destroy(),
     name: opts.name ?? path,
+    enforces: sqlEnforces,
     transacted: (fn) => db.transaction().execute((trx) => fn(createStorageFactory(trx, opts.storageFactoryOptions, 'sqlite'))),
   };
 }
 
-/**
- * `source: 'sql'` — answered HERE and not in the driver-free index, because answering a
- * name means building a driver, and this is the one this package owns.
- *
- * The refusal is `refuseUnresolvable` moved: it lived in `@fougere/defaults`, which happened
- * to import the driver, so a second adapter had nowhere to say it exists. A dialect this
- * package cannot build from a name is refused here, where the reason is true.
- */
+/** `source. */
 Sources.register('sql', (conf: SourceConfig): Source => {
   const dialect = conf.dialect as string | undefined;
   if (dialect !== undefined && dialect !== 'sqlite') {

package/src/step.ts

@@ -1,15 +1,4 @@
-/**
- * The half `delta()` refuses — realised from an intention that was written down.
- *
- * `diff.ts` states its own guarantee: additive only, because "a rename is not even
- * detectable from a diff (it reads as a drop plus an add)". That still holds, and this
- * file does not weaken it. What changed is upstream: a frozen step (`fougere freeze`)
- * carries a rename because a human declared it at the moment they made it. The intention
- * exists now, so it can be realised — and only what the step actually says.
- *
- * A drop and a rename both touch live data, so this is the only place either can come
- * from: never introspection, never a guess.
- */
+/** The half `delta()` refuses — realised from an intention that was written down. */
 import { sql, type Kysely } from 'kysely';
 import type { Change as ShapeChange, SetDiff } from '@fougere/schema';
 import { dequal } from 'dequal';
@@ -42,25 +31,11 @@ export interface Plan {
 export interface PlanOptions {
   /** Entity key → table name. Same resolver `desiredTables` takes. */
   tableName?: (name: string) => string;
-  /**
-   * What the database actually holds, from `actualState`. Given, a change already
-   * realised is skipped.
-   *
-   * Idempotence by OBSERVATION and not by bookkeeping — the same choice `delta` makes.
-   * A ledger of applied steps would be a second record of a fact the columns already
-   * carry, and the two would disagree the day someone renamed a column by hand.
-   */
+  /** What the database actually holds, from `actualState`. */
   actual?: SchemaState;
 }
 
-/**
- * Collapse a chain of steps into one, following each field through its renames.
- *
- * A step judges itself on two names — old gone, new here — so an intermediate rename is
- * unrecognisable once its target has been renamed again: both names are absent and it is
- * proposed forever. Composing the chain first asks the question about the name the field
- * ENDS on, which is the only one the tables can answer.
- */
+/** Collapse a chain of steps into one, following each field through its renames. */
 export function collapseChain(steps: readonly SetDiff[]): SetDiff {
   const entities: SetDiff['entities'] = {};
   const added: string[] = [];
@@ -70,9 +45,9 @@ export function collapseChain(steps: readonly SetDiff[]): SetDiff {
     added.push(...step.entitiesAdded);
     removed.push(...step.entitiesRemoved);
     for (const [entity, answer] of Object.entries(step.entities)) {
-      const held = (entities[entity] ??= { changes: [], ambiguous: [] });
-      held.ambiguous.push(...answer.ambiguous);
-      for (const change of answer.changes) compose(held.changes, change);
+      const entry = (entities[entity] ??= { changes: [], ambiguous: [] });
+      entry.ambiguous.push(...answer.ambiguous);
+      for (const change of answer.changes) compose(entry.changes, change);
     }
   }
 
@@ -80,9 +55,8 @@ export function collapseChain(steps: readonly SetDiff[]): SetDiff {
 }
 
 /**
- * Add one change to what the chain has said so far, rewriting rather than appending when
- * it continues a field already moved. A rename back to its origin cancels: the tables
- * never held the name in between, so there is nothing for them to do.
+ * Add one change to what the chain has said so far, rewriting rather than appending when it
+ * continues a field already moved.
  */
 function compose(held: ShapeChange[], change: ShapeChange): void {
   if (change.kind === 'renamed') {
@@ -113,11 +87,7 @@ function compose(held: ShapeChange[], change: ShapeChange): void {
   held.push({ ...change, field: origin.from });
 }
 
-/**
- * Turn a frozen step into what the tables must do, and what nobody may decide for you.
- *
- * Pure, like `delta` — the comparison is one thing, running it is another.
- */
+/** Turn a frozen step into what the tables must do, and what nobody may decide for you. */
 export function planStep(step: SetDiff, tables: TableDef[], options: PlanOptions = {}): Plan {
   const resolve = options.tableName ?? toTableName;
   const actual = options.actual;
@@ -191,7 +161,7 @@ function realise(
 
     case 'reshaped':
       // A tightened bound is a CHECK, and altering one on a live table is engine-specific
-      // AND may be refused by rows already stored. The judge still enforces it at the door.
+      // AND may be refused by rows already stored. The validator still enforces it at the door.
       return {
         entity,
         field: change.field,
@@ -203,13 +173,7 @@ function realise(
   }
 }
 
-/**
- * An axis other than shape moved. Only some of it is a fact about the table.
- *
- * `boundary` never is — it says who may read or write, which no column holds. `lifecycle`
- * is one only through the DEFAULT clause. `role` is one three times over, and two of those
- * are constraints a live table may already contradict.
- */
+/** An axis other than shape moved. */
 function restated(entity: string, change: Extract<ShapeChange, { kind: 'restated' }>): { change?: StepChange } | Refusal {
   const refuse = (reason: string): Refusal => ({ entity, field: change.field, reason });
 
@@ -246,13 +210,7 @@ function literalOf(rules: { create?: unknown } | undefined): unknown {
 
 const show = (value: unknown): string => (value === undefined ? 'none' : JSON.stringify(value));
 
-/**
- * Has the table already moved? Read off the columns themselves.
- *
- * A rename whose old name is gone and whose new one is there has happened; a drop whose
- * column is absent has happened. Unknown state (no introspection given) answers no, so a
- * plan built without it proposes everything the step says.
- */
+/** Has the table already moved? Read off the columns themselves. */
 function done(change: StepChange, columns: Set<string> | undefined): boolean {
   if (!columns) return false;
   return change.kind === 'renameColumn'