@bakery-framework/orm 1.0.0

package/src/sync/load.ts

@@ -0,0 +1,368 @@
+import { Case, fs } from '@bakery-framework/core/utils'
+import { Try } from '@bakery-framework/core/utils/common'
+import { collectConstraints } from '../define'
+import type * as SyncTypes from './types'
+
+/**
+ * Where a project's data model lives, and how it is read.
+ *
+ * Two layouts are supported. `orm/` is the newer one: tables in `schema.ts`,
+ * indexes in `indexes.ts`, foreign keys in `foreign.ts`, re-exported from
+ * `orm/index.ts`. A single `schema.ts` at the root still works, so nothing
+ * has to move.
+ *
+ * The folder is not only tidier — it separates what the generator owns from
+ * what a person wrote. `--choose=db` regenerates tables; with everything in
+ * one file it has to rewrite indexes and foreign keys too, and anything
+ * hand-authored alongside them is collateral.
+ *
+ * Both of those are *defaults*, probed in that order from the app's cwd. An
+ * app that keeps its model somewhere else — `db/`, `src/database/`, a path
+ * shared with another tool — sets `schema` in `server.config.ts` and this
+ * stops guessing:
+ *
+ * ```ts
+ * export default defineConfig({ schema: 'db/orm' })   // folder layout
+ * export default defineConfig({ schema: 'db/model.ts' }) // single file
+ * ```
+ *
+ * A configured path is resolved against the app's cwd and is **not** a hint.
+ * If it does not exist the load fails (`missing`) instead of quietly falling
+ * back to the defaults: a typo in that one string would otherwise leave the
+ * app running against no schema at all, and `--choose=db` would then generate
+ * a fresh one at the typo'd path while the real model sits untouched
+ * somewhere else.
+ */
+/**
+ * Which shape the generator must write back.
+ *
+ * `folder` means `table()` values in `<dir>/schema.ts`, with `<dir>/index.ts`
+ * owning the re-exports and the schema registration. `file` and `none` mean the
+ * single-file `DBInfo` namespace, which carries its own registration block.
+ * Emitting the wrong one is not cosmetic — see `SchemaBuilder.generate`.
+ */
+export type SchemaLayout = 'folder' | 'file' | 'none'
+
+export interface LoadedSchema {
+  constraints: SyncTypes.DBConstraints
+  indexes: SyncTypes.DBIndexes
+  /**
+   * `Field.Foreign()` references whose target is neither a primary key nor
+   * uniquely indexed, as `child.col -> parent.col`.
+   *
+   * SQL forbids those. MySQL and Postgres refuse the CREATE outright; SQLite
+   * accepts the DDL and then fails *every insert* with `foreign key mismatch`,
+   * naming two tables and nothing else — so the caller aborts on this rather
+   * than letting it surface at runtime.
+   */
+  unreferenceable?: string[]
+  /** The file the generator should write tables back to. */
+  targetPath: string
+  layout: SchemaLayout
+  /**
+   * The path a configured `schema` pointed at that does not exist. Set only
+   * for that case — never when nothing is configured, since absence is a
+   * supported state for the defaults. The caller must abort rather than sync.
+   */
+  missing?: string
+}
+
+const CONSTRAINT_TYPES = new Set(['index', 'unique', 'foreign'])
+
+/**
+ * Foreign keys are declarable but not implemented, and the failure is nasty:
+ * no adapter emits FOREIGN KEY DDL, so a declaration is created as an ordinary
+ * index. The next diff then compares `foreign` in TypeScript against `index`
+ * in the database, decides to drop and re-add it, and — because index drops
+ * count as destructive — aborts the sync. The dev server stops starting, with
+ * nothing pointing at the cause.
+ *
+ * Failing here converts that into one clear message. The alternative would be
+ * to keep quietly creating an index, which is worse than useless: it looks
+ * like referential integrity and enforces nothing.
+ */
+export function findUnsupportedForeignKeys(
+  indexes: Record<string, unknown>,
+): string[] {
+  return Object.entries(indexes)
+    .filter(([, entry]) => (entry as { type?: string })?.type === 'foreign')
+    .map(([name]) => name)
+}
+
+/** Pull index/unique/foreign declarations out of a module's exports. */
+function collectIndexes(module: Record<string, unknown>) {
+  const indexes: Record<string, unknown> = {}
+
+  for (const [name, exported] of Object.entries(module)) {
+    if (!exported || typeof exported !== 'object') continue
+    const entry = exported as { type?: string; table?: string }
+    if (entry.type && CONSTRAINT_TYPES.has(entry.type) && entry.table) {
+      indexes[name] = entry
+    }
+  }
+
+  return indexes
+}
+
+/**
+ * The app's configured schema location, or `undefined` for auto-detection.
+ *
+ * Takes the whole config object rather than the field so the one place that
+ * knows the config's shape is here. `unknown` because core's `AppConfig` does
+ * not declare `schema` yet — `defaultConfig` in `core/core/config.ts` is
+ * annotated `Required<AppConfig>`, so declaring the field there forces a
+ * default value for it, and there is no single path to give: the default is
+ * the *probe*, not a location. Core spreads unknown keys from
+ * `server.config.ts` through verbatim, so the option works today, and adding
+ * the two lines that type it changes nothing here.
+ */
+export function schemaFromConfig(config: unknown): string | undefined {
+  const value = (config as { schema?: unknown } | null | undefined)?.schema
+  if (typeof value !== 'string') return undefined
+  return value.trim() || undefined
+}
+
+async function importFresh(path: string) {
+  // Cache-busted: db:sync runs repeatedly in a dev process that has already
+  // imported the previous version of these modules.
+  return Try.catch(import(`${path}?t=${Date.now()}`))
+}
+
+function emptyAt(targetPath: string): LoadedSchema {
+  return { constraints: {}, indexes: {}, targetPath, layout: 'none' }
+}
+
+/**
+ * Import `entry` and pull the schema out of it.
+ *
+ * `targetPath` is passed rather than derived: for the folder layout the
+ * generator writes to `schema.ts` *beside* the entry, because `index.ts`
+ * re-exports hand-authored `indexes.ts` / `foreign.ts` and must survive
+ * `--choose=db` untouched.
+ */
+async function readSchema(
+  entry: string,
+  layout: 'folder' | 'file',
+  targetPath: string,
+): Promise<LoadedSchema> {
+  const [error, module] = await importFresh(entry)
+  if (error || !module) return emptyAt(targetPath)
+
+  if (layout === 'folder') {
+    const resolved = resolveColumnForeignKeys(
+      collectConstraints(module) as SyncTypes.DBConstraints,
+      collectIndexes(module) as SyncTypes.DBIndexes,
+    )
+    return { ...resolved, targetPath, layout: 'folder' }
+  }
+
+  // The single-file layout may declare tables either way: the original
+  // `DBInfo` namespace, or `table()` values once a project starts migrating.
+  const fromDbInfo = module.DBInfo?.constraints
+  const constraints = fromDbInfo ?? collectConstraints(module)
+  const indexes =
+    module.DBInfo?.indexes ?? module.indexes ?? collectIndexes(module)
+
+  const resolved = resolveColumnForeignKeys(
+    constraints as SyncTypes.DBConstraints,
+    indexes as SyncTypes.DBIndexes,
+  )
+  return {
+    ...resolved,
+    targetPath,
+    layout: Object.keys(constraints).length ? 'file' : 'none',
+  }
+}
+
+type Resolved =
+  | { entry: string; layout: 'folder' | 'file'; targetPath: string }
+  | { missing: string; targetPath: string }
+
+/**
+ * Turn a configured `schema` value into an entry file and a write target.
+ *
+ * Relative paths resolve against the app's cwd — the framework's own location
+ * is irrelevant and, once it is an installed package, meaningless.
+ *
+ * A directory means the folder layout. So does a path ending in `index.ts`,
+ * which is the same folder addressed by its entry file; pointing the
+ * generator at that file would have it overwrite the re-exports.
+ */
+
+/**
+ * Where the folder layout's table declarations live.
+ *
+ * `tables.ts`, beside `views.ts` and `indexes.ts` — one file per kind of
+ * declaration, which is the separation the folder layout exists for. It was
+ * `schema.ts`, which read oddly next to its siblings and collided with the
+ * single-file layout's `schema.ts` in conversation.
+ *
+ * The old name is still honoured when it is the one on disk. Loading never
+ * cared — that goes through `index.ts`'s re-exports, so any filename works —
+ * but *generation* writes here, and writing `tables.ts` beside someone's
+ * existing `schema.ts` would leave two files declaring the same tables.
+ */
+async function folderTarget(dir: string): Promise<string> {
+  const tables = `${dir}/tables.ts`
+  if (await Bun.file(tables).exists()) return tables
+  const legacy = `${dir}/schema.ts`
+  return (await Bun.file(legacy).exists()) ? legacy : tables
+}
+
+async function resolveConfigured(
+  cwd: string,
+  configured: string,
+): Promise<Resolved> {
+  const path = fs.resolve(cwd, configured)
+
+  if (await fs.isDir(path)) {
+    const entry = `${path}/index.ts`
+    const target = await folderTarget(path)
+    if (!(await Bun.file(entry).exists())) {
+      return { missing: entry, targetPath: target }
+    }
+    return { entry, layout: 'folder', targetPath: target }
+  }
+
+  if (!(await Bun.file(path).exists()))
+    return { missing: path, targetPath: path }
+
+  if (fs.parse(path).base === 'index.ts') {
+    return {
+      entry: path,
+      layout: 'folder',
+      targetPath: await folderTarget(fs.dirname(path)),
+    }
+  }
+
+  return { entry: path, layout: 'file', targetPath: path }
+}
+
+export async function loadSchema(
+  cwd: string,
+  configured?: string,
+): Promise<LoadedSchema> {
+  if (configured) {
+    const resolved = await resolveConfigured(cwd, configured)
+    if ('missing' in resolved) {
+      return { ...emptyAt(resolved.targetPath), missing: resolved.missing }
+    }
+    return readSchema(resolved.entry, resolved.layout, resolved.targetPath)
+  }
+
+  const empty = emptyAt(`${cwd}/schema.ts`)
+
+  const folderEntry = `${cwd}/orm/index.ts`
+  if (await Bun.file(folderEntry).exists()) {
+    const loaded = await readSchema(
+      folderEntry,
+      'folder',
+      await folderTarget(`${cwd}/orm`),
+    )
+    // Unchanged from before this file learned about `config.schema`: when the
+    // folder entry exists but cannot be imported, the generator stays pointed
+    // at <cwd>/schema.ts. Where a *broken* module leaves the write target is a
+    // separate question from where the schema is found.
+    return loaded.layout === 'none' ? empty : loaded
+  }
+
+  const filePath = `${cwd}/schema.ts`
+  if (!(await Bun.file(filePath).exists())) return empty
+
+  return readSchema(filePath, 'file', filePath)
+}
+
+/**
+ * Turn `Field.Foreign(users.id)` columns into real foreign key declarations.
+ *
+ * Runs once, where the whole schema is in scope, and does two things a column
+ * cannot do on its own:
+ *
+ * 1. **Copies the referenced column's type onto the child.** MySQL rejects a
+ *    foreign key whose types do not match exactly — an `INT` child against a
+ *    `BIGINT` parent is refused — and the two declarations are usually pages
+ *    apart. Copying makes the mismatch unrepresentable rather than merely
+ *    unlikely. `length` comes along for a `Varchar` key, for the same reason.
+ * 2. **Emits the key into the index map**, which is where `collectForeignKeys`
+ *    and the diff already look. `foreign()` still exists and is unchanged; this
+ *    is a second way to declare the same thing, for the single-column case.
+ *
+ * A reference to a table or column that does not exist is left alone rather
+ * than guessed at: the column keeps its placeholder type and no key is emitted,
+ * so the failure surfaces as a missing constraint rather than a silently wrong
+ * one.
+ */
+function isUnique(
+  indexes: SyncTypes.DBIndexes,
+  table: string,
+  column: string,
+): boolean {
+  return Object.values(indexes).some(
+    (i: any) =>
+      i?.type === 'unique' &&
+      Case.snake(i.table) === Case.snake(table) &&
+      i.cols?.length === 1 &&
+      Case.snake(i.cols[0]) === Case.snake(column),
+  )
+}
+
+export function resolveColumnForeignKeys(
+  constraints: SyncTypes.DBConstraints,
+  indexes: SyncTypes.DBIndexes,
+): {
+  constraints: SyncTypes.DBConstraints
+  indexes: SyncTypes.DBIndexes
+  /** References whose target is neither a primary key nor uniquely indexed. */
+  unreferenceable: string[]
+} {
+  const out = { ...indexes } as Record<string, unknown>
+  const unreferenceable: string[] = []
+
+  for (const [tableName, cols] of Object.entries(constraints)) {
+    // A view cannot carry a foreign key, and `view(name, sourceTable, body)`
+    // borrows the source table's columns — `_references` included. Without this
+    // the view gets a key of its own, which no dialect will create, so every
+    // sync plans to add it again: an empty printed plan and a run that never
+    // reports a perfectly synced database.
+    if ((cols as any)?._view) continue
+    for (const [colName, col] of Object.entries(cols as Record<string, any>)) {
+      const ref = col?._references
+      if (!ref) continue
+
+      const target = (constraints as any)[ref.table]?.[ref.column]
+      if (target) {
+        col.type = target.type
+        if (typeof target.length === 'number') col.length = target.length
+        // Never the parent's primary/autoIncrement: the child is a plain
+        // column that happens to point at one.
+
+        // SQL requires a foreign key's target to be a primary key or carry a
+        // unique index. MySQL and Postgres refuse the CREATE outright; SQLite
+        // *accepts the DDL* and then fails every insert with
+        // `foreign key mismatch`, naming the two tables and nothing else.
+        // Saying so here, against the schema, beats debugging that at runtime.
+        if (!target.primary && !isUnique(indexes, ref.table, ref.column)) {
+          unreferenceable.push(
+            `${tableName}.${colName} -> ${ref.table}.${ref.column}`,
+          )
+        }
+      }
+
+      out[`fk_${Case.snake(tableName)}_${Case.snake(colName)}`] = {
+        type: 'foreign',
+        table: tableName,
+        cols: [colName],
+        refTable: ref.table,
+        refCols: [ref.column],
+        onDelete: ref.onDelete,
+        onUpdate: ref.onUpdate,
+      }
+    }
+  }
+
+  return {
+    constraints,
+    indexes: out as SyncTypes.DBIndexes,
+    unreferenceable,
+  }
+}

package/src/sync/rollback.ts

@@ -0,0 +1,200 @@
+import '@bakery-framework/core/core/init'
+
+import { Logger, messageLogger } from '@bakery-framework/core/logger'
+import type { SQLAdapter } from '../adapters/base'
+import { SchemaBuilder } from './builder'
+import { MESSAGES as SYNC_MESSAGES, SyncEngine } from './engine'
+import { type LedgerEntry, readLedgerEntries } from './ledger'
+import { loadSchema, schemaFromConfig } from './load'
+import type * as SyncTypes from './types'
+
+const logger = new Logger('db-rollback')
+
+// prettier-ignore
+const rollbackMsgs = {
+  NO_HISTORY:
+    'E %rNothing to roll back to%*: this database has no schema history. The ledger fills up as %ydb:sync%* applies changes, so there is nothing recorded before the current state.',
+  ONLY_ONE:
+    'E %rNothing to roll back to%*: only one schema has ever been applied (#{id}). A rollback needs a previous state to restore.',
+  NO_SUCH_ENTRY:
+    'E %rNo schema #{id} in this database’s history%*. Run %ydb:history%* to see what is there.',
+  IS_CURRENT:
+    'E %rSchema #{id} is already the current one%*. Rolling back to it would do nothing.',
+  TARGET:
+    'I Rolling back to schema %y#{id}%* ({when} UTC), applied {steps} change(s) ago.',
+  NO_INDEX_RECORD:
+    'W %ySchema #{id} predates the ledger recording indexes%*, so this rollback leaves indexes exactly as they are. Tables and columns roll back; index changes made since then do not.',
+  SCHEMA_REWRITTEN: 'I Rewrote %y{path}%* to match the restored schema.',
+  SCHEMA_KEPT:
+    'W %y--keep-schema: schema.ts still describes the newer schema.%* The next %ydb:sync%* — including the one a dev boot runs — will apply it again and undo this rollback. Revert the file yourself, or re-run without the flag.',
+  DONE: 'I %gRollback complete%*.',
+} as const
+
+const MESSAGES = messageLogger(logger, rollbackMsgs)
+
+/**
+ * Which recorded schema to restore.
+ *
+ * Default is one step back, which is what "roll back" means with no argument.
+ * `entries` is newest first, so index 1 is the previous state and index 0 is
+ * where we are now.
+ */
+export function pickTarget(
+  entries: LedgerEntry[],
+  toId?: number,
+):
+  | { ok: true; target: LedgerEntry; steps: number }
+  | { ok: false; code: keyof typeof rollbackMsgs; id?: number } {
+  if (!entries.length) return { ok: false, code: 'NO_HISTORY' }
+  if (toId === undefined) {
+    if (entries.length < 2)
+      return { ok: false, code: 'ONLY_ONE', id: entries[0]!.id }
+    return { ok: true, target: entries[1]!, steps: 1 }
+  }
+  const index = entries.findIndex(e => e.id === toId)
+  if (index < 0) return { ok: false, code: 'NO_SUCH_ENTRY', id: toId }
+  if (index === 0) return { ok: false, code: 'IS_CURRENT', id: toId }
+  return { ok: true, target: entries[index]!, steps: index }
+}
+
+export class RollbackService {
+  protected constructor() {}
+
+  static helpRequested(argv: string[] = process.argv.slice(2)): boolean {
+    return argv.includes('--help') || argv.includes('-h')
+  }
+
+  static printHelp(): void {
+    console.log(`
+Usage: bun run db:rollback [--to=<id>] [--dry-run] [--force-sync] [--keep-schema]
+
+Restores a schema this database previously had. The state is read from the
+ledger Bakery writes on every sync, so there are no migration files and no
+hand-written down-migrations.
+
+Flags:
+  --to=<id>       Roll back to a specific schema (see db:history). Default is
+                  one step back.
+  --dry-run       Preview the changes without applying them
+  --force-sync    In production, allow destructive changes
+  --keep-schema   Do not rewrite schema.ts. The next sync will undo the
+                  rollback -- see the warning it prints.
+  --help, -h      Show this help message
+
+A rollback is a migration like any other: it can drop columns, and dropping a
+column drops its data. It takes a backup first and asks before destructive
+changes, exactly as db:sync does.
+`)
+  }
+
+  /** `--to=12`, or undefined. A non-numeric value is treated as absent. */
+  static parseTo(argv: string[] = process.argv.slice(2)): number | undefined {
+    const raw = argv.find(a => a.startsWith('--to='))?.slice('--to='.length)
+    if (raw === undefined) return undefined
+    const n = Number(raw)
+    return Number.isInteger(n) ? n : undefined
+  }
+
+  static async run(): Promise<void> {
+    if (RollbackService.helpRequested()) return RollbackService.printHelp()
+
+    const { initConfig } = await import('@bakery-framework/core/core/config')
+    const { closeDB, connection, initDB } = await import('../connection')
+    const config = await initConfig()
+    await initDB()
+
+    const entries = await readLedgerEntries(connection)
+    const picked = pickTarget(entries, RollbackService.parseTo())
+    if (!picked.ok) {
+      // Switched rather than indexed: `MESSAGES[code]` types as the
+      // intersection of every message's parameters, so it demands `when` and
+      // `steps` from a message that has neither.
+      const id = picked.id ?? 0
+      if (picked.code === 'NO_HISTORY') MESSAGES.NO_HISTORY()
+      else if (picked.code === 'ONLY_ONE') MESSAGES.ONLY_ONE({ id })
+      else if (picked.code === 'NO_SUCH_ENTRY') MESSAGES.NO_SUCH_ENTRY({ id })
+      else MESSAGES.IS_CURRENT({ id })
+      await closeDB()
+      return process.exit(1)
+    }
+
+    const { target, steps } = picked
+    const { formatWhen } = await import('./history')
+    MESSAGES.TARGET({
+      id: target.id,
+      when: formatWhen(target.appliedAt),
+      steps,
+    })
+
+    // A v1 row recorded no indexes, and replaying it with an empty index set
+    // would read as "drop every index" — a silent, permanent performance
+    // change dressed up as a rollback. Restoring the *live* indexes instead
+    // means the plan contains no index work at all, which is the honest
+    // degradation: it does less than asked, and says so.
+    let indexes: SyncTypes.DBIndexes
+    if (target.indexes === undefined) {
+      MESSAGES.NO_INDEX_RECORD({ id: target.id })
+      indexes = await connection.getIndexes()
+    } else {
+      indexes = target.indexes
+    }
+
+    // Only for the path and layout. The constraints in schema.ts describe where
+    // we are now, which is precisely what a rollback is leaving behind.
+    const loaded = await loadSchema(process.cwd(), schemaFromConfig(config))
+
+    await RollbackService.apply(
+      connection,
+      target,
+      indexes,
+      loaded.targetPath,
+      loaded.layout,
+    )
+    await closeDB()
+  }
+
+  private static async apply(
+    adapter: SQLAdapter,
+    target: LedgerEntry,
+    indexes: SyncTypes.DBIndexes,
+    schemaPath: string,
+    layout: Parameters<typeof SchemaBuilder.generate>[4],
+  ): Promise<void> {
+    // The whole point of the ledger: a rollback is just a sync whose target is
+    // a schema we already stored. Backups, the destructive-change prompt,
+    // `--dry-run`, `--force-sync` and the new ledger row all come from
+    // `SyncEngine.run` unchanged — there is no second migration path to keep
+    // correct, which is the only reason this file is as short as it is.
+    await SyncEngine.run(
+      adapter,
+      target.constraints,
+      indexes,
+      schemaPath,
+      layout,
+    )
+
+    if (process.argv.includes('--dry-run')) return
+
+    // Without this the rollback is undone by the next thing that syncs, and a
+    // dev boot syncs. schema.ts still says what the *newer* schema was, so it
+    // would be applied straight back over the top.
+    if (process.argv.includes('--keep-schema')) {
+      MESSAGES.SCHEMA_KEPT()
+      return
+    }
+    await SchemaBuilder.generate(
+      adapter,
+      schemaPath,
+      SYNC_MESSAGES,
+      target.constraints,
+      layout,
+    )
+    MESSAGES.SCHEMA_REWRITTEN({ path: schemaPath })
+    MESSAGES.DONE()
+  }
+}
+
+if (import.meta.main) {
+  await RollbackService.run()
+  process.exit(0)
+}

package/src/sync/types.ts

@@ -0,0 +1,101 @@
+export type ColumnType =
+  | 'integer'
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'buffer'
+  | 'bigint'
+  | 'json'
+
+export interface ColumnConstraint {
+  type: ColumnType
+  /**
+   * Character length, for a sized text column (`VARCHAR(n)`).
+   *
+   * **Now part of the column diff**, so widening a `Varchar` migrates. This
+   * used to say the opposite, and the reason was sound at the time: it needed
+   * every adapter to report the width back exactly, and any that did not would
+   * rebuild the table on every sync. That is no longer a guess — all three
+   * were measured against live servers, and the one real trap (MySQL reporting
+   * `character_maximum_length = 65535` for an unsized `TEXT`) is handled in
+   * `SQLAdapter.sizedTextLength`.
+   *
+   * Compared only when both the schema and the database declare a width. An
+   * unsized column in the schema is not a request to shrink whatever is there.
+   */
+  length?: number
+  /**
+   * The permitted values of an enum column — `Field.Enum([...])`.
+   *
+   * Not part of the column diff, for exactly the reason `length` is not:
+   * MySQL reports an ENUM's members back in its own spelling, Postgres reports
+   * a CHECK constraint from a different catalog altogether, and any adapter
+   * that reported them even slightly differently would rebuild the table on
+   * every sync. Consequence to know, and it is the same one: **changing an
+   * enum's members does not migrate on its own.**
+   */
+  _enum?: string[]
+  primary?: boolean
+  autoIncrement?: boolean
+  nullable?: boolean
+  default?: unknown
+  _oldColumn?: string
+  _transform?: (oldValue: unknown, oldRow?: Record<string, unknown>) => unknown
+}
+
+export type TableConstraints = {
+  [column: string]: ColumnConstraint
+} & {
+  _view?: string
+  _oldTable?: string
+  _transform?: (oldRow: Record<string, unknown>) => unknown
+}
+
+export interface IndexConstraint {
+  type: 'index' | 'unique' | 'foreign'
+  table: string
+  cols: string[]
+  /** Set only when `type` is 'foreign'. */
+  refTable?: string
+  refCols?: string[]
+}
+
+/**
+ * A foreign key as the database reports it.
+ *
+ * Identity is the tuple, not the name: SQLite's `PRAGMA foreign_key_list`
+ * does not return a constraint name at all, so keying on one would make every
+ * SQLite foreign key look new on every sync — the perpetual-rebuild failure
+ * this project keeps hitting.
+ */
+/**
+ * Referential actions, normalised to the SQL spelling.
+ *
+ * One vocabulary for three dialects: MySQL and SQLite report these words back
+ * verbatim, Postgres reports single characters (`c`, `a`, `r`, `n`, `d`) which
+ * the adapter maps. Without one normal form the diff would compare `CASCADE`
+ * against `c` and drop-and-recreate the key on every sync.
+ */
+export type ForeignKeyAction =
+  | 'NO ACTION'
+  | 'RESTRICT'
+  | 'CASCADE'
+  | 'SET NULL'
+  | 'SET DEFAULT'
+
+export interface ForeignKeyInfo {
+  table: string
+  cols: string[]
+  refTable: string
+  refCols: string[]
+  name?: string
+  /** Defaults to `NO ACTION`, which is what every dialect emits when omitted. */
+  onDelete?: ForeignKeyAction
+  onUpdate?: ForeignKeyAction
+}
+
+export type DBForeignKeys = Record<string, ForeignKeyInfo>
+
+export type DBConstraints = Record<string, TableConstraints>
+
+export type DBIndexes = Record<string, IndexConstraint>