@ultimat3/db 1.1.0 → 2.0.0

package/src/expected-loop.ts

@@ -0,0 +1,53 @@
+// Single responsibility: the one way to declare that a loop of statements is deliberate, so a
+// statement-level diagnostic reports the loops nobody argued for and stays quiet about the rest.
+// A scope with a written reason — never a comment pragma and never a config list of exempt call
+// sites (axiom 1), because both put the argument somewhere other than the loop it defends.
+
+// `node:` because Bun exposes no native async-context primitive: the reason has to outlive every
+// `await` inside the scope, and `AsyncLocalStorage` is the only thing that carries a value across
+// them. A module-scope variable would be shared by two concurrent loops.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { assert } from '@ultimat3/core';
+
+const storage = new AsyncLocalStorage<string>();
+
+/**
+ * Run `fn` with every statement it issues — at any depth, across every `await` — marked expected
+ * and carrying `reason`. The reason rides on the `StatementEvent` (`expected`), so a diagnostic
+ * that buffers a request's statements and judges them at the end still holds the argument long
+ * after this scope closed.
+ *
+ * What it suppresses is a **verdict**, not the statements: they are still sent, still observed,
+ * still spans on the trace. A detector counting repeats gets the author's reason for this one
+ * instead of guessing, and the loop stays visible to everything that measures rather than judges.
+ *
+ * `reason` is required and non-blank because it *is* the mechanism — an exemption with no argument
+ * is a pragma, and the next reader cannot tell a considered loop from a silenced one. Nesting keeps
+ * the innermost reason: the closest scope is the one describing this loop.
+ *
+ * ```ts
+ * // one indexed lookup per search field beats one unindexed OR across all of them
+ * return expectedQueryLoop('search runs one indexed lookup per field', async () => {
+ *   for (const field of fields) hits.push(...(await repo.list({ where: [eq(field, term)] })));
+ *   return hits;
+ * });
+ * ```
+ */
+export function expectedQueryLoop<T>(reason: string, fn: () => T): T {
+  assert(
+    reason.trim() !== '',
+    'expectedQueryLoop() was given a blank reason, so the loop it silences carries no argument',
+    "pass why the loop is optimal: expectedQueryLoop('one indexed lookup per field', fn)",
+  );
+  return storage.run(reason, fn);
+}
+
+/**
+ * The innermost enclosing reason, or `undefined` outside every scope — which is every statement in
+ * an app that never calls `expectedQueryLoop`. Read by the two funnels when an observer is
+ * installed, and by nothing else: a diagnostic reads `StatementEvent.expected`, which is the same
+ * answer captured at the moment the statement settled.
+ */
+export function expectedQueryLoopReason(): string | undefined {
+  return storage.getStore();
+}

package/src/fake-pglite.ts

@@ -0,0 +1,32 @@
+// Single responsibility: the PGlite driver fake the adapter tests record statements against.
+// Shared rather than copied for the same reason `fake-reservable.ts` is: the assertion in every
+// one of these tests is the recorded ORDER, and two copies of the recorder drift into two orders.
+
+import type { PgliteDriver, PgliteResult } from './pglite';
+
+/** One statement as the driver received it — the text after binding, and the bound values. */
+export interface Recorded {
+  readonly text: string;
+  readonly values: readonly unknown[];
+}
+
+export type RecordingPgliteDriver = PgliteDriver & {
+  readonly calls: Recorded[];
+  closed: number;
+};
+
+/** A driver that answers every statement with `result` and remembers the order it saw them in. */
+export function fakeDriver(result: PgliteResult): RecordingPgliteDriver {
+  const calls: Recorded[] = [];
+  return {
+    calls,
+    closed: 0,
+    async query(text, values) {
+      calls.push({ text, values: values ?? [] });
+      return result;
+    },
+    async close() {
+      this.closed += 1;
+    },
+  };
+}

package/src/fake-reservable.ts

@@ -0,0 +1,50 @@
+// Single responsibility: a `ReservableClient` whose pin is countable, wrapped over any `DbClient`.
+// The leak it exists to catch is invisible to the recording client — the statements are identical
+// whether or not the reservation ever came back, and only the counter says which happened. Shared
+// rather than copied: a second copy of a fixture asserts less than the first, silently.
+
+import type { DbClient, ReservableClient } from './client';
+
+/** Pins taken and pins given back. A leak is `reserves > releases`; the fix makes them equal. */
+export interface PinCounts {
+  reserves: number;
+  releases: number;
+}
+
+export interface ReservableFake {
+  readonly client: ReservableClient;
+  readonly pins: PinCounts;
+}
+
+/**
+ * Wrap `inner` in a pool that counts its reservations. `release()` is idempotent and
+ * `[Symbol.dispose]` is the same call, exactly as both real drivers are — so a double release
+ * counts once and only a genuine leak leaves the counters uneven.
+ */
+export function reservableOver(inner: DbClient): ReservableFake {
+  const pins: PinCounts = { reserves: 0, releases: 0 };
+  return {
+    pins,
+    client: {
+      query: (fragment) => inner.query(fragment),
+      one: (fragment) => inner.one(fragment),
+      execute: (fragment) => inner.execute(fragment),
+      reserve: async () => {
+        pins.reserves += 1;
+        let held = true;
+        const release = (): void => {
+          if (!held) return;
+          held = false;
+          pins.releases += 1;
+        };
+        return {
+          query: (fragment) => inner.query(fragment),
+          one: (fragment) => inner.one(fragment),
+          execute: (fragment) => inner.execute(fragment),
+          release,
+          [Symbol.dispose]: release,
+        };
+      },
+    },
+  };
+}

package/src/fake.ts

@@ -36,9 +36,22 @@ function matches(stub: Stub, text: string): boolean {
   return typeof stub.match === 'string' ? text.includes(stub.match) : stub.match.test(text);
 }
 
+/**
+ * The one statement a recording client cannot answer with silence. `migrate()` polls
+ * `pg_try_advisory_lock` until it wins or its deadline passes, so "no rows" reads as "another
+ * migrator holds it" — and every migration test in the framework, and in every app, would spend
+ * `MIGRATION_LOCK_WAIT_MS` waiting for a lock nobody holds before failing.
+ *
+ * Registered first, so `on(/pg_try_advisory_lock/, { rows: [{ locked: false }] })` still wins:
+ * later registrations override, and a test about contention says so out loud.
+ */
+const DEFAULT_STUBS: readonly Stub[] = [
+  { match: /pg_try_advisory_lock/, response: { rows: [{ locked: true }] } },
+];
+
 export function createRecordingClient(): RecordingClient {
   const statements: RecordedStatement[] = [];
-  const stubs: Stub[] = [];
+  const stubs: Stub[] = [...DEFAULT_STUBS];
 
   function respond(fragment: SqlFragment): StubResponse {
     statements.push({ text: fragment.text, values: [...fragment.values] });
@@ -61,7 +74,8 @@ export function createRecordingClient(): RecordingClient {
     },
     reset(): void {
       statements.length = 0;
-      stubs.length = 0;
+      // Back to the defaults, never to nothing: `reset()` restores the client a test was handed.
+      stubs.splice(0, stubs.length, ...DEFAULT_STUBS);
     },
     async query<T>(fragment: SqlFragment): Promise<readonly T[]> {
       return (respond(fragment).rows ?? []) as readonly T[];

package/src/foreign-key.ts

@@ -0,0 +1,41 @@
+// Single responsibility: what a foreign key *is* — where it points — and the two statements that
+// add or drop one. `generate.ts` writes them and `drift.ts` compares them, and a generator that
+// disagreed with a detector about whether two keys are the same key is drift on a correct database.
+
+import type { ForeignKeyDescription } from './introspect';
+
+/**
+ * A key's identity: its columns, its target table, its target columns — never its name. Postgres
+ * names an inline `references` clause `<table>_<column>_fkey` and a hand-written migration may have
+ * said `constraint fk_posts_org`; a key pointing the same way under another name is the same key.
+ *
+ * Both lists stay ordered, because a composite key is an ordered pairing: `(a, b) references t (x,
+ * y)` and `(b, a) references t (x, y)` are different constraints.
+ */
+export function foreignKeyTarget(key: ForeignKeyDescription): string {
+  return JSON.stringify([[...key.columns], key.referencedTable, [...key.referencedColumns]]);
+}
+
+const quoted = (names: readonly string[]): string => names.map((name) => `"${name}"`).join(', ');
+
+/**
+ * A statement of its own, never a clause inside `create table`. Inline, the constraint is created
+ * with the table, so the referenced table must already exist — and entity registration order is
+ * the app's import order, which has nothing to say about which table a `references()` points at.
+ * Two tables referencing each other cannot be expressed inline at all, in any order.
+ *
+ * The constraint is **named** here rather than left to Postgres' own convention, so the name the
+ * snapshot beside it records is a name this migration wrote and not a name it guessed.
+ */
+export function addForeignKey(table: string, key: ForeignKeyDescription): string {
+  return (
+    `alter table "${table}" add constraint "${key.name}" ` +
+    `foreign key (${quoted(key.columns)}) ` +
+    `references "${key.referencedTable}" (${quoted(key.referencedColumns)});`
+  );
+}
+
+/** The reverse. Dropping a constraint loses nothing the database cannot rebuild. */
+export function dropForeignKey(table: string, constraint: string): string {
+  return `alter table "${table}" drop constraint "${constraint}";`;
+}

package/src/generate.ts

@@ -1,12 +1,17 @@
 // Single responsibility: turn an entity snapshot into a timestamped, reversible migration.
-// `db` is tier 2 and cannot import `@ultimat3/entity`, so the snapshot arrives as a parameter —
+// `db` is tier 1 and cannot import `@ultimat3/entity`, so the snapshot arrives as a parameter —
 // the CLI passes `describeEntities()` and the types below mirror `EntityDescription` field for
 // field. Every generated migration must be reversible; a drop that loses data refuses instead.
 
+import { assert, systemClock } from '@ultimat3/core';
+import { isDestructive } from './destructive';
 import { migrationIrreversible } from './errors';
+import { addForeignKey, dropForeignKey, foreignKeyTarget } from './foreign-key';
 import {
   type ColumnDescription,
+  type ForeignKeyDescription,
   findTable,
+  type IndexDescription,
   type SchemaDescription,
   type TableDescription,
 } from './introspect';
@@ -24,14 +29,31 @@ export interface ColumnDescriptionLike {
   readonly references: string | null;
 }
 
+/**
+ * Structurally assignment-compatible with `@ultimat3/entity`'s `IndexDescription`.
+ *
+ * The column list is carried, never recovered from `name`. Entity names an index
+ * `<table>_<a>_<b>_idx`, and that convention does not run backwards: two columns joined by `_`
+ * are one string, so a composite index read back out of its own name became the single column
+ * `"org_id_created_at"` — DDL Postgres answers `42703` and a migration nobody can apply.
+ */
+export interface IndexDescriptionLike {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly unique: boolean;
+  /** Partial index predicate as SQL, `null` when the index covers every row. */
+  readonly where: string | null;
+  /** `null` is Postgres' own default (`asc`), never written out. */
+  readonly order: 'asc' | 'desc' | null;
+}
+
 /** Structurally assignment-compatible with `@ultimat3/entity`'s `EntityDescription`. */
 export interface EntityDescriptionLike {
   readonly name: string;
   readonly table: string;
   readonly primaryKey: readonly string[];
   readonly columns: readonly ColumnDescriptionLike[];
-  /** Index names only, following entity's `<table>_<column>_idx` / `_key` convention. */
-  readonly indexes: readonly string[];
+  readonly indexes: readonly IndexDescriptionLike[];
 }
 
 const SQL_TYPES: Readonly<Record<string, string>> = {
@@ -65,6 +87,16 @@ function defaultExpression(column: ColumnDescriptionLike): string | null {
   return null;
 }
 
+/**
+ * The two ends of a `references()`, which entity renders as `"<table>.<column>"`. Read once: the
+ * clause that writes the constraint and the snapshot that records it must not disagree about what
+ * it points at, or drift reports a key the database holds exactly as declared.
+ */
+function referenceParts(references: string): readonly [string, string] {
+  const [table = references, column = 'id'] = references.split('.');
+  return [table, column];
+}
+
 function columnClause(column: ColumnDescriptionLike): string {
   const parts = [`"${column.column}"`, sqlType(column.kind)];
   const expression = defaultExpression(column);
@@ -72,44 +104,68 @@ function columnClause(column: ColumnDescriptionLike): string {
   if (column.notNull) parts.push('not null');
   if (column.unique && !column.primaryKey) parts.push('unique');
   if (column.check !== null) parts.push(`check (${column.check})`);
-  if (column.references !== null) {
-    const [refTable = column.references, refColumn = 'id'] = column.references.split('.');
-    parts.push(`references "${refTable}" ("${refColumn}")`);
-  }
+  // No `references` clause. A foreign key is `alter table … add constraint`, emitted after every
+  // table exists (`foreignKeyPlan`) — inline it must point at a table that already exists, and
+  // entity registration order is the app's import order, which says nothing about that.
   return parts.join(' ');
 }
 
-export interface ParsedIndex {
-  readonly name: string;
-  readonly columns: readonly string[];
-  readonly unique: boolean;
-}
-
 /**
  * A `unique` column clause already creates an index, and Postgres names it exactly what the
  * entity's own convention names it — `<table>_<column>_key`. Emitting `create unique index` for
  * it too is the same index twice: `42P07`, and a migration that cannot be applied at all.
  * Mirrors the rule `entity()` already applies to a foreign key indexing its own column.
+ *
+ * A **partial** unique index is not that index: the column clause constrains every row, so
+ * skipping the partial one would silently widen the constraint the entity declared.
  */
 function impliedByColumnClause(
   entity: EntityDescriptionLike,
-  index: ParsedIndex,
+  index: IndexDescriptionLike,
   added: ReadonlySet<string>,
 ): boolean {
   const [only] = index.columns;
-  if (!index.unique || index.columns.length !== 1 || only === undefined) return false;
+  if (!index.unique || index.where !== null || index.columns.length !== 1 || only === undefined) {
+    return false;
+  }
   const column = entity.columns.find((each) => each.column === only);
   // `columnClause` writes `unique` under exactly this condition — keep the two in step.
+  //
+  // NOT an optional chain, despite what biome's useOptionalChain suggests: `column?.unique` is
+  // `boolean | undefined`, and this function returns `boolean`. The lint rule marks its own fix
+  // unsafe for exactly this reason — applying it turned a green typecheck red.
+  // biome-ignore lint/complexity/useOptionalChain: an optional chain widens the return to include undefined
   return column !== undefined && column.unique && !column.primaryKey && added.has(only);
 }
 
-/** Entity only records index names; the convention is what makes the columns recoverable. */
-export function parseIndexName(table: string, name: string): ParsedIndex {
-  const unique = name.endsWith('_key');
-  const prefix = `${table}_`;
-  const withoutTable = name.startsWith(prefix) ? name.slice(prefix.length) : name;
-  const middle = withoutTable.replace(/_(idx|key)$/, '');
-  return { name, columns: middle === '' ? [] : [middle], unique };
+/**
+ * The keys this entity declares, recorded so drift can see one dropped by hand. Recording
+ * `foreignKeys: []` while the same run emitted a constraint was a snapshot claiming a constraint
+ * does not exist that the migration beside it creates, and `compareTable` had nothing to compare —
+ * a key dropped on the database was invisible to every check the framework runs.
+ *
+ * The name is `<table>_<column>_fkey` — what Postgres would have called an inline `references`
+ * clause — and `addForeignKey` now writes it out, so the snapshot records a name the migration
+ * beside it chose rather than one it guessed. It is still *not* what drift matches on: see
+ * `compareForeignKeys` in `drift.ts`.
+ *
+ * `onDelete` stays `null`. `entity()` carries the option and no clause here has ever spelled one,
+ * so a value written down would be a claim about the database that is not true.
+ */
+function foreignKeysOf(entity: EntityDescriptionLike): ForeignKeyDescription[] {
+  return entity.columns
+    .filter((column) => column.references !== null)
+    .map((column): ForeignKeyDescription => {
+      const [table, key] = referenceParts(column.references ?? '');
+      return {
+        name: `${entity.table}_${column.column}_fkey`,
+        columns: [column.column],
+        referencedTable: table,
+        referencedColumns: [key],
+        onDelete: null,
+      };
+    })
+    .sort((a, b) => (a.name < b.name ? -1 : 1));
 }
 
 export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDescription {
@@ -130,11 +186,18 @@ export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDe
         name: entity.table,
         columns,
         primaryKey: [...entity.primaryKey],
-        indexes: entity.indexes.map((name) => ({
-          ...parseIndexName(entity.table, name),
+        // Whole, never partly: a snapshot that recorded the name and dropped the predicate made
+        // the next generation blind to a `where` or an `order` changing, and a partial index
+        // silently kept as a total one is a constraint the entity no longer declares.
+        indexes: entity.indexes.map((index) => ({
+          name: index.name,
+          columns: [...index.columns],
+          unique: index.unique,
           primary: false,
+          where: index.where,
+          order: index.order,
         })),
-        foreignKeys: [],
+        foreignKeys: foreignKeysOf(entity),
       };
     });
   return { tables };
@@ -148,18 +211,29 @@ function createTable(entity: EntityDescriptionLike): readonly string[] {
   const statements = [`create table "${entity.table}" (\n  ${clauses.join(',\n  ')}\n);`];
   // Every column of a new table carries its own clause, so every `unique` one brings its index.
   const added = new Set(entity.columns.map((column) => column.column));
-  for (const name of entity.indexes) {
-    const index = parseIndexName(entity.table, name);
-    if (index.columns.length === 0 || impliedByColumnClause(entity, index, added)) continue;
+  for (const index of entity.indexes) {
+    if (impliedByColumnClause(entity, index, added)) continue;
     statements.push(createIndex(entity.table, index));
   }
   return statements;
 }
 
-function createIndex(table: string, index: ParsedIndex): string {
+/**
+ * Every part of the declaration reaches the statement: the whole column list in its declared
+ * order, the direction when one was asked for, and the predicate that makes it partial. A part
+ * dropped here is a constraint the database does not hold or an index the planner cannot use.
+ */
+function createIndex(table: string, index: IndexDescriptionLike): string {
+  assert(
+    index.columns.length > 0,
+    `index "${index.name}" on "${table}" names no columns`,
+    `indexes: [{ on: ['<column>'] }]   # name the columns in the entity(), then x db gen`,
+  );
   const kind = index.unique ? 'create unique index' : 'create index';
-  const columns = index.columns.map((column) => `"${column}"`).join(', ');
-  return `${kind} "${index.name}" on "${table}" (${columns});`;
+  const direction = index.order === null ? '' : ` ${index.order}`;
+  const columns = index.columns.map((column) => `"${column}"${direction}`).join(', ');
+  const predicate = index.where === null ? '' : ` where (${index.where})`;
+  return `${kind} "${index.name}" on "${table}" (${columns})${predicate};`;
 }
 
 interface Plan {
@@ -167,6 +241,30 @@ interface Plan {
   readonly down: string[];
 }
 
+/**
+ * Every foreign key the entity declares that the previous snapshot does not already record, as its
+ * own `add constraint`. One call site for both cases the generator has — a table being created and
+ * a `references()` added to a column that already exists — because they are one question: which of
+ * this entity's keys does the database not hold yet.
+ *
+ * The statements land in a bucket of their own, appended after every table statement, so a key
+ * never runs before the table it points at. `down` is reversed as a whole, so pushing the drops
+ * last here puts them *first* on the way back: `drop table "posts"` with `comments` still
+ * referencing it is `2BP01`, a migration that cannot be rolled back at all.
+ */
+function foreignKeyPlan(
+  entity: EntityDescriptionLike,
+  live: TableDescription | undefined,
+  constraints: Plan,
+): void {
+  const held = new Set((live?.foreignKeys ?? []).map(foreignKeyTarget));
+  for (const key of foreignKeysOf(entity)) {
+    if (held.has(foreignKeyTarget(key))) continue;
+    constraints.up.push(addForeignKey(entity.table, key));
+    constraints.down.push(dropForeignKey(entity.table, key.name));
+  }
+}
+
 /**
  * Skipping an existing column by name alone missed the type moving under it: a table created
  * while money's currency was bare `char` keeps `char(1)` and rejects every ISO 4217 code, yet the
@@ -189,6 +287,44 @@ function retypeColumn(
   plan.down.push(alter(recorded.dataType));
 }
 
+/** The parts of an index Postgres cannot alter in place — every one of them is a rebuild. */
+function indexShape(index: IndexDescriptionLike | IndexDescription): string {
+  return JSON.stringify([[...index.columns], index.unique, index.where, index.order ?? null]);
+}
+
+/**
+ * A same-named index whose definition moved is dropped and recreated, because Postgres has no
+ * `alter index` for any of it — the column list, the uniqueness, the predicate and the direction
+ * are all fixed at creation.
+ *
+ * Matching on the name alone was the gap: `where` and `order` were not even recorded, so an
+ * entity narrowing an index to a predicate, or reversing it to `desc`, generated an empty
+ * migration and the database kept serving the old one. Both sides here are *generated* spellings
+ * — `recorded` is a previous migration's own snapshot, never the catalog's rewriting of it — so a
+ * text difference in `where` is a real change and not a formatting one.
+ */
+function redefineIndex(
+  table: string,
+  index: IndexDescriptionLike,
+  recorded: IndexDescription,
+  plan: Plan,
+): void {
+  if (indexShape(index) === indexShape(recorded)) return;
+  plan.up.push(`drop index "${index.name}";`, createIndex(table, index));
+  // `down` is reversed at assembly, so the pair is pushed forwards and read backwards: recreating
+  // the recorded definition is what must land last, after the new one is dropped.
+  plan.down.push(
+    createIndex(table, {
+      name: recorded.name,
+      columns: recorded.columns,
+      unique: recorded.unique,
+      where: recorded.where,
+      order: recorded.order,
+    }),
+    `drop index "${index.name}";`,
+  );
+}
+
 function diffTable(entity: EntityDescriptionLike, live: TableDescription, plan: Plan): void {
   const existing = new Map(live.columns.map((column) => [column.name, column]));
   const added = new Set<string>();
@@ -213,15 +349,18 @@ function diffTable(entity: EntityDescriptionLike, live: TableDescription, plan:
     plan.down.push(`alter table "${entity.table}" drop column "${column.column}";`);
   }
 
-  const indexed = new Set(live.indexes.map((index) => index.name));
-  for (const name of entity.indexes) {
-    if (indexed.has(name)) continue;
-    const index = parseIndexName(entity.table, name);
+  const indexed = new Map(live.indexes.map((index) => [index.name, index]));
+  for (const index of entity.indexes) {
+    const recorded = indexed.get(index.name);
+    if (recorded !== undefined) {
+      redefineIndex(entity.table, index, recorded, plan);
+      continue;
+    }
     // `added` only: an index over a column that was already there is implied by no clause this
     // migration emits, so it still needs a statement of its own.
-    if (index.columns.length === 0 || impliedByColumnClause(entity, index, added)) continue;
+    if (impliedByColumnClause(entity, index, added)) continue;
     plan.up.push(createIndex(entity.table, index));
-    plan.down.push(`drop index "${name}";`);
+    plan.down.push(`drop index "${index.name}";`);
   }
 }
 
@@ -242,6 +381,12 @@ export interface GeneratedMigration {
   readonly up: string;
   readonly down: string;
   readonly snapshot: SchemaDescription;
+  /**
+   * Whether `up` destroys data. Read off the generated SQL by the same classifier the gate runs,
+   * never assembled a second time from what the diff happened to push — one answer, so a migration
+   * cannot be written unmarked and then refused by `x verify` for lacking the mark.
+   */
+  readonly destructive: boolean;
 }
 
 export function migrationStamp(now: Date): string {
@@ -258,10 +403,13 @@ export function slugify(name: string): string {
 export function generateMigration(options: GenerateOptions): GeneratedMigration {
   const current = options.current ?? { tables: [] };
   const plan: Plan = { up: [], down: [] };
+  // Merged into `plan` once every table statement is in, never interleaved with them.
+  const constraints: Plan = { up: [], down: [] };
   const wanted = new Set(options.entities.map((entity) => entity.table));
 
   for (const entity of options.entities) {
     const live = findTable(current, entity.table);
+    foreignKeyPlan(entity, live, constraints);
     if (live === undefined) {
       plan.up.push(...createTable(entity));
       plan.down.push(`drop table "${entity.table}";`);
@@ -297,14 +445,19 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
     plan.down.push(`-- "${table.name}" cannot be restored; recover it from a backup`);
   }
 
-  const id = `${migrationStamp(options.now ?? new Date())}_${slugify(options.name)}`;
+  plan.up.push(...constraints.up);
+  plan.down.push(...constraints.down);
+
+  const id = `${migrationStamp(options.now ?? systemClock.now())}_${slugify(options.name)}`;
+  const up = plan.up.join('\n');
   return {
     id,
     name: options.name,
     fileName: `migrations/${id}.sql`,
-    up: plan.up.join('\n'),
+    up,
     // Reverse order: the last thing created is the first thing dropped.
     down: [...plan.down].reverse().join('\n'),
     snapshot: snapshotOf(options.entities),
+    destructive: isDestructive(up),
   };
 }