@ultimat3/db 1.0.0

package/src/index.ts

@@ -0,0 +1,129 @@
+// Single responsibility: the public API of @ultimat3/db. Explicit named exports only —
+// `@ultimat3/auth`, `@ultimat3/entity`, `@ultimat3/jobs` and the CLI are written against this
+// list, so anything not here is an implementation detail and may change.
+
+export type { BranchInfo, BranchOptions, DropBranchOptions, ReapOptions } from './branch';
+export {
+  assertBranchName,
+  createBranch,
+  currentDatabase,
+  dropBranch,
+  listBranches,
+  reapBranches,
+} from './branch';
+export type {
+  DbClient,
+  DbConnection,
+  DbHealthReport,
+  PoolProfile,
+  PostgresClient,
+  PostgresClientOptions,
+  ReservableClient,
+} from './client';
+export {
+  baseClient,
+  checkDb,
+  createPostgresClient,
+  db,
+  isReservable,
+  POOL_PROFILES,
+  poolProfileFor,
+  setDbClient,
+} from './client';
+export type { DriftDifference, DriftKind, DriftOptions, DriftReport } from './drift';
+export {
+  assertNoDrift,
+  checkDrift,
+  diffSchema,
+  driftError,
+  expectedSchema,
+} from './drift';
+export type { DbErrorCode, DbErrorInit } from './errors';
+export {
+  branchExists,
+  branchNameInvalid,
+  DB_ERROR_CODES,
+  DB_ERROR_TITLES,
+  DbError,
+  dbDrift,
+  dbNotImplemented,
+  dbUnavailable,
+  identifierUnsafe,
+  migrationConflict,
+  migrationIrreversible,
+  readonlyViolation,
+  sqlUnsafe,
+} from './errors';
+export type { RecordedStatement, RecordingClient, StubResponse } from './fake';
+export { createRecordingClient } from './fake';
+export type {
+  ColumnDescriptionLike,
+  EntityDescriptionLike,
+  GeneratedMigration,
+  GenerateOptions,
+  ParsedIndex,
+} from './generate';
+export {
+  generateMigration,
+  migrationStamp,
+  parseIndexName,
+  slugify,
+  snapshotOf,
+} from './generate';
+export type {
+  ColumnDescription,
+  ForeignKeyDescription,
+  IndexDescription,
+  IntrospectOptions,
+  SchemaDescription,
+  TableDescription,
+} from './introspect';
+export { buildSchema, findTable, introspect } from './introspect';
+export type {
+  AppliedMigration,
+  LedgerRow,
+  MigrateOptions,
+  Migration,
+  MigrationReport,
+  RollbackOptions,
+} from './migrate';
+export {
+  auditLedger,
+  checksumOf,
+  ensureLedger,
+  LEDGER_TABLE,
+  MIGRATION_LOCK_KEY,
+  migrate,
+  migrationChecksum,
+  pendingMigrations,
+  readLedger,
+  rollback,
+  runningAppVersion,
+} from './migrate';
+export type {
+  PgliteClient,
+  PgliteDriver,
+  PgliteLoader,
+  PgliteModule,
+  PgliteOptions,
+  PgliteResult,
+} from './pglite';
+export {
+  createPgliteClient,
+  loadPgliteDriver,
+  PGLITE_FIX,
+  PGLITE_MEMORY,
+  pgliteDataDir,
+} from './pglite';
+export type { PgliteBranchInfo, PgliteBranchOptions } from './pglite-branch';
+export { branchPglite, pgliteBranchDir } from './pglite-branch';
+export type { MutationVerdict, ReadOnlyOptions } from './readonly';
+export { assertReadOnly, inspectStatement, readOnly, stripSqlNoise } from './readonly';
+export type { ReadOnlyQueryOptions, ReadOnlyQueryResult } from './readonly-query';
+export { READONLY_TIMEOUT_MS, readOnlyQuery } from './readonly-query';
+export type { ReadOnlyRoleOptions } from './readonly-role';
+export { ensureReadOnlyRole, grantReadOnlySql, READONLY_ROLE } from './readonly-role';
+export type { SqlFragment } from './sql';
+export { identifier, isSqlFragment, join, literal, raw, sql } from './sql';
+export type { DbTx, IsolationLevel, TransactionOptions } from './transaction';
+export { beginStatement, currentTx, withTransaction } from './transaction';

package/src/introspect.ts

@@ -0,0 +1,187 @@
+// Single responsibility: read the live schema out of `information_schema` / `pg_catalog` into a
+// plain, sortable description. Three consumers depend on this exact shape: drift detection, the
+// generated admin dashboard's schema view, and the MCP `schema.describe` tool. Keep it JSON-safe
+// and deterministically ordered — it is diffed and it is serialised.
+
+import { type DbClient, db } from './client';
+import { sql } from './sql';
+
+export interface ColumnDescription {
+  readonly name: string;
+  /** Postgres type name as reported by the catalog (`text`, `timestamptz`, `numeric(12,2)`). */
+  readonly dataType: string;
+  readonly nullable: boolean;
+  readonly default: string | null;
+  readonly position: number;
+}
+
+export interface IndexDescription {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly unique: boolean;
+  readonly primary: boolean;
+}
+
+export interface ForeignKeyDescription {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly referencedTable: string;
+  readonly referencedColumns: readonly string[];
+  readonly onDelete: string | null;
+}
+
+export interface TableDescription {
+  readonly schema: string;
+  readonly name: string;
+  readonly columns: readonly ColumnDescription[];
+  readonly primaryKey: readonly string[];
+  readonly indexes: readonly IndexDescription[];
+  readonly foreignKeys: readonly ForeignKeyDescription[];
+}
+
+export interface SchemaDescription {
+  readonly tables: readonly TableDescription[];
+}
+
+export interface IntrospectOptions {
+  readonly client?: DbClient | undefined;
+  readonly schema?: string | undefined;
+  /** The ledger is framework bookkeeping, not user schema — excluded so it never reads as drift. */
+  readonly exclude?: readonly string[] | undefined;
+}
+
+interface ColumnRow {
+  readonly table_name: string;
+  readonly column_name: string;
+  readonly data_type: string;
+  readonly is_nullable: string;
+  readonly column_default: string | null;
+  readonly ordinal_position: number;
+}
+
+interface IndexRow {
+  readonly table_name: string;
+  readonly index_name: string;
+  readonly is_unique: boolean;
+  readonly is_primary: boolean;
+  readonly columns: readonly string[];
+}
+
+interface ForeignKeyRow {
+  readonly table_name: string;
+  readonly constraint_name: string;
+  readonly columns: readonly string[];
+  readonly referenced_table: string;
+  readonly referenced_columns: readonly string[];
+  readonly on_delete: string | null;
+}
+
+const byName = (a: { name: string }, b: { name: string }): number => (a.name < b.name ? -1 : 1);
+
+export async function introspect(options: IntrospectOptions = {}): Promise<SchemaDescription> {
+  const client = options.client ?? db();
+  const schema = options.schema ?? 'public';
+  const excluded = options.exclude ?? ['x_migrations'];
+
+  const columns = await client.query<ColumnRow>(sql`
+    select table_name, column_name, data_type, is_nullable, column_default, ordinal_position
+    from information_schema.columns
+    where table_schema = ${schema}
+    order by table_name, ordinal_position
+  `);
+
+  const indexes = await client.query<IndexRow>(sql`
+    select
+      t.relname as table_name,
+      i.relname as index_name,
+      ix.indisunique as is_unique,
+      ix.indisprimary as is_primary,
+      array_agg(a.attname order by a.attnum) as columns
+    from pg_class t
+    join pg_namespace n on n.oid = t.relnamespace
+    join pg_index ix on ix.indrelid = t.oid
+    join pg_class i on i.oid = ix.indexrelid
+    join pg_attribute a on a.attrelid = t.oid and a.attnum = any(ix.indkey)
+    where n.nspname = ${schema} and t.relkind = 'r'
+    group by t.relname, i.relname, ix.indisunique, ix.indisprimary
+    order by t.relname, i.relname
+  `);
+
+  const foreignKeys = await client.query<ForeignKeyRow>(sql`
+    select
+      src.relname as table_name,
+      c.conname as constraint_name,
+      array_agg(sa.attname order by sa.attnum) as columns,
+      tgt.relname as referenced_table,
+      array_agg(ta.attname order by ta.attnum) as referenced_columns,
+      c.confdeltype as on_delete
+    from pg_constraint c
+    join pg_class src on src.oid = c.conrelid
+    join pg_class tgt on tgt.oid = c.confrelid
+    join pg_namespace n on n.oid = src.relnamespace
+    join pg_attribute sa on sa.attrelid = src.oid and sa.attnum = any(c.conkey)
+    join pg_attribute ta on ta.attrelid = tgt.oid and ta.attnum = any(c.confkey)
+    where c.contype = 'f' and n.nspname = ${schema}
+    group by src.relname, c.conname, tgt.relname, c.confdeltype
+    order by src.relname, c.conname
+  `);
+
+  return buildSchema(schema, excluded, columns, indexes, foreignKeys);
+}
+
+/** Pure, so the row -> description mapping is testable without a database. */
+export function buildSchema(
+  schema: string,
+  excluded: readonly string[],
+  columns: readonly ColumnRow[],
+  indexes: readonly IndexRow[],
+  foreignKeys: readonly ForeignKeyRow[],
+): SchemaDescription {
+  const names = [...new Set(columns.map((row) => row.table_name))]
+    .filter((name) => !excluded.includes(name))
+    .sort();
+
+  const tables = names.map((name): TableDescription => {
+    const tableIndexes = indexes
+      .filter((row) => row.table_name === name)
+      .map((row) => ({
+        name: row.index_name,
+        columns: [...row.columns],
+        unique: row.is_unique,
+        primary: row.is_primary,
+      }))
+      .sort(byName);
+    return {
+      schema,
+      name,
+      columns: columns
+        .filter((row) => row.table_name === name)
+        .map((row) => ({
+          name: row.column_name,
+          dataType: row.data_type,
+          nullable: row.is_nullable === 'YES',
+          default: row.column_default,
+          position: row.ordinal_position,
+        }))
+        .sort(byName),
+      primaryKey: tableIndexes.find((index) => index.primary)?.columns ?? [],
+      indexes: tableIndexes,
+      foreignKeys: foreignKeys
+        .filter((row) => row.table_name === name)
+        .map((row) => ({
+          name: row.constraint_name,
+          columns: [...row.columns],
+          referencedTable: row.referenced_table,
+          referencedColumns: [...row.referenced_columns],
+          onDelete: row.on_delete,
+        }))
+        .sort(byName),
+    };
+  });
+
+  return { tables };
+}
+
+export function findTable(schema: SchemaDescription, table: string): TableDescription | undefined {
+  return schema.tables.find((candidate) => candidate.name === table);
+}

package/src/migrate.ts

@@ -0,0 +1,228 @@
+// Single responsibility: apply pending migrations and keep the `x_migrations` ledger honest.
+// An advisory lock serialises concurrent migrators; a checksum pins already-applied SQL; the
+// app-version fence is the `migrate` role's contract — a pod must refuse to migrate a database
+// another build already owns, because the alternative is two schemas racing during a rollout.
+
+import { baseClient, type DbClient } from './client';
+import { migrationConflict } from './errors';
+import type { SchemaDescription } from './introspect';
+import { raw, sql } from './sql';
+import { withTransaction } from './transaction';
+
+export const LEDGER_TABLE = 'x_migrations';
+
+/** Stable, arbitrary: every Ultimate migrator contends on this one key. */
+export const MIGRATION_LOCK_KEY = 4_919_202_607;
+
+export interface Migration {
+  /** Sort key and primary key. `20260726120000_add_publish_at`. */
+  readonly id: string;
+  readonly name: string;
+  readonly up: string;
+  readonly down: string;
+  /** Computed from `up` when absent. */
+  readonly checksum?: string | undefined;
+  /** The schema this migration leaves behind. `drift.ts` compares the live DB against it. */
+  readonly snapshot?: SchemaDescription | undefined;
+}
+
+export interface LedgerRow {
+  readonly id: string;
+  readonly name: string;
+  readonly checksum: string;
+  readonly applied_at: string;
+  readonly app_version: string;
+  readonly duration_ms: number;
+}
+
+export interface AppliedMigration {
+  readonly id: string;
+  readonly name: string;
+  readonly durationMs: number;
+}
+
+/** The `--json` payload of `x db migrate`. */
+export interface MigrationReport {
+  readonly applied: readonly AppliedMigration[];
+  readonly skipped: readonly string[];
+  readonly durationMs: number;
+  readonly appVersion: string;
+}
+
+export interface MigrateOptions {
+  readonly migrations: readonly Migration[];
+  /** The running build. Defaults to `APP_VERSION`, then `dev`. */
+  readonly appVersion?: string | undefined;
+  readonly client?: DbClient | undefined;
+  /** Skip the advisory lock. Only `x db branch` does this, against a private database. */
+  readonly lock?: boolean | undefined;
+}
+
+export function checksumOf(text: string): string {
+  return new Bun.CryptoHasher('sha256').update(text.trim()).digest('hex').slice(0, 32);
+}
+
+export function migrationChecksum(migration: Migration): string {
+  return migration.checksum ?? checksumOf(migration.up);
+}
+
+export function runningAppVersion(explicit?: string | undefined): string {
+  return explicit ?? process.env['APP_VERSION'] ?? 'dev';
+}
+
+export async function ensureLedger(client: DbClient): Promise<void> {
+  await client.execute(sql`
+    create table if not exists ${raw(LEDGER_TABLE)} (
+      id text primary key,
+      name text not null,
+      checksum text not null,
+      applied_at timestamptz not null default now(),
+      app_version text not null,
+      duration_ms integer not null
+    )
+  `);
+}
+
+export async function readLedger(client: DbClient): Promise<readonly LedgerRow[]> {
+  return client.query<LedgerRow>(sql`
+    select id, name, checksum, applied_at, app_version, duration_ms
+    from ${raw(LEDGER_TABLE)}
+    order by id
+  `);
+}
+
+/**
+ * Every reason a migrator must stop before touching the schema. Pure, so `x db status` can
+ * report the same verdict without holding the lock.
+ */
+export function auditLedger(
+  ledger: readonly LedgerRow[],
+  migrations: readonly Migration[],
+  appVersion: string,
+): void {
+  const known = new Map(migrations.map((migration) => [migration.id, migration]));
+
+  const foreign = ledger.filter((row) => !known.has(row.id) && row.app_version !== appVersion);
+  const first = foreign[0];
+  if (first !== undefined) {
+    throw migrationConflict(
+      `the ledger records migration "${first.id}" applied by app version "${first.app_version}" ` +
+        `but this build is "${appVersion}" and does not ship it`,
+      `x db status --json   # then deploy app version "${first.app_version}", or roll the ledger`,
+    );
+  }
+
+  for (const row of ledger) {
+    const migration = known.get(row.id);
+    if (migration === undefined) continue;
+    const checksum = migrationChecksum(migration);
+    if (checksum === row.checksum) continue;
+    throw migrationConflict(
+      `migration "${row.id}" was applied with checksum ${row.checksum} but now hashes ${checksum}`,
+      `x db gen "fix ${migration.name}"   # never edit an applied migration, add a new one`,
+    );
+  }
+}
+
+export function pendingMigrations(
+  ledger: readonly LedgerRow[],
+  migrations: readonly Migration[],
+): readonly Migration[] {
+  const applied = new Set(ledger.map((row) => row.id));
+  return [...migrations]
+    .sort((a, b) => (a.id < b.id ? -1 : 1))
+    .filter((migration) => !applied.has(migration.id));
+}
+
+async function withAdvisoryLock<T>(
+  client: DbClient,
+  enabled: boolean,
+  fn: () => Promise<T>,
+): Promise<T> {
+  if (!enabled) return fn();
+  await client.execute(sql`select pg_advisory_lock(${MIGRATION_LOCK_KEY})`);
+  try {
+    return await fn();
+  } finally {
+    await client
+      .execute(sql`select pg_advisory_unlock(${MIGRATION_LOCK_KEY})`)
+      .catch(() => undefined);
+  }
+}
+
+export async function migrate(options: MigrateOptions): Promise<MigrationReport> {
+  const client = options.client ?? baseClient();
+  const appVersion = runningAppVersion(options.appVersion);
+  const started = performance.now();
+
+  return withAdvisoryLock(client, options.lock !== false, async () => {
+    await ensureLedger(client);
+    const ledger = await readLedger(client);
+    auditLedger(ledger, options.migrations, appVersion);
+
+    const pending = pendingMigrations(ledger, options.migrations);
+    const applied: AppliedMigration[] = [];
+    for (const migration of pending) {
+      const at = performance.now();
+      await withTransaction(
+        async (tx) => {
+          await tx.execute(raw(migration.up));
+          const durationMs = Math.round(performance.now() - at);
+          await tx.execute(sql`
+            insert into ${raw(LEDGER_TABLE)} (id, name, checksum, app_version, duration_ms)
+            values (${migration.id}, ${migration.name}, ${migrationChecksum(migration)},
+                    ${appVersion}, ${durationMs})
+          `);
+        },
+        { client },
+      );
+      applied.push({
+        id: migration.id,
+        name: migration.name,
+        durationMs: Math.round(performance.now() - at),
+      });
+    }
+
+    return {
+      applied,
+      skipped: ledger.map((row) => row.id),
+      durationMs: Math.round(performance.now() - started),
+      appVersion,
+    };
+  });
+}
+
+export interface RollbackOptions {
+  readonly migrations: readonly Migration[];
+  readonly client?: DbClient | undefined;
+  readonly steps?: number | undefined;
+}
+
+/** Reverse the newest `steps` applied migrations. `x db rollback`. */
+export async function rollback(options: RollbackOptions): Promise<readonly string[]> {
+  const client = options.client ?? baseClient();
+  const steps = options.steps ?? 1;
+  const ledger = await readLedger(client);
+  const known = new Map(options.migrations.map((migration) => [migration.id, migration]));
+  const targets = [...ledger].reverse().slice(0, steps);
+  const reverted: string[] = [];
+
+  for (const row of targets) {
+    const migration = known.get(row.id);
+    if (migration === undefined) {
+      throw migrationConflict(
+        `migration "${row.id}" is in the ledger but not in this build, so its down SQL is unknown`,
+        `x db status --json   # deploy the build that shipped "${row.id}" and roll back there`,
+      );
+    }
+    await withTransaction(
+      async (tx) => {
+        await tx.execute(raw(migration.down));
+        await tx.execute(sql`delete from ${raw(LEDGER_TABLE)} where id = ${row.id}`);
+      },
+      { client },
+    );
+    reverted.push(row.id);
+  }
+  return reverted;
+}

package/src/pglite-branch.ts

@@ -0,0 +1,84 @@
+// Single responsibility: branching the embedded database. PGlite has no `CREATE DATABASE ...
+// TEMPLATE`, so a branch is a copy of the data directory — which is why the branch name is
+// validated before it ever reaches a path, and why the caller must have closed the source first:
+// this copies files, it does not take a snapshot of a running instance.
+
+import { cp, mkdir, rm, stat } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import type { BranchInfo } from './branch';
+import { assertBranchName } from './branch';
+import { branchExists, dbNotImplemented, dbUnavailable } from './errors';
+import { PGLITE_MEMORY, pgliteDataDir } from './pglite';
+
+export interface PgliteBranchOptions {
+  /** The data directory to copy — what `x dev` is running against. A `pglite://` url also works. */
+  readonly from: string;
+  /** Where to put the branch. Defaults to `<from>-<branch>`, beside the source. */
+  readonly to?: string | undefined;
+  /** Replace an existing branch directory instead of refusing. */
+  readonly force?: boolean | undefined;
+  readonly now?: Date | undefined;
+}
+
+export interface PgliteBranchInfo extends BranchInfo {
+  /** Hand this straight to `createPgliteClient({ dataDir })`. */
+  readonly dataDir: string;
+}
+
+/** One place decides the on-disk layout, so `x db branch` and `x db reset` agree about it. */
+export const pgliteBranchDir = (from: string, branch: string): string =>
+  join(dirname(from), `${basename(from)}-${branch}`);
+
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function directorySize(dir: string): Promise<number> {
+  let total = 0;
+  for await (const entry of new Bun.Glob('**/*').scan({ cwd: dir, absolute: true })) {
+    total += Bun.file(entry).size;
+  }
+  return total;
+}
+
+/** The embedded peer of `createBranch()`: same guarantees, a directory instead of a template. */
+export async function branchPglite(
+  branch: string,
+  options: PgliteBranchOptions,
+): Promise<PgliteBranchInfo> {
+  // The name is spliced into a filesystem path, so an unvalidated one is traversal rather than a
+  // typo — the same reason `createBranch` validates before reaching `CREATE DATABASE`.
+  assertBranchName(branch);
+  const from = pgliteDataDir(options.from);
+  if (from === PGLITE_MEMORY) {
+    throw dbNotImplemented(
+      'branching an in-memory PGlite',
+      'x dev   # a branch copies .x/pgdata, so the database has to be on disk first',
+    );
+  }
+  if (!(await isDirectory(from))) {
+    throw dbUnavailable(`there is no PGlite data directory at ${from}, so nothing to branch`);
+  }
+
+  const to = options.to ?? pgliteBranchDir(from, branch);
+  if (await isDirectory(to)) {
+    if (options.force !== true) throw branchExists(branch);
+    await rm(to, { recursive: true, force: true });
+  }
+  await mkdir(dirname(to), { recursive: true });
+  // `node:fs` because Bun has no recursive directory copy and PGlite has no TEMPLATE to ask
+  // instead. Portable on purpose: the CLI used to shell out to `cp --reflink=auto`, which is a
+  // GNU flag that macOS does not have.
+  await cp(from, to, { recursive: true });
+
+  return {
+    name: branch,
+    createdAt: (options.now ?? new Date()).toISOString(),
+    dataDir: to,
+    sizeBytes: await directorySize(to),
+  };
+}

package/src/pglite-turns.ts

@@ -0,0 +1,51 @@
+// Single responsibility: taking turns on PGlite's one connection. Embedded Postgres is a single
+// session, not a pool, so two units of work that each `BEGIN` would be sharing one transaction —
+// the second `COMMIT` commits the first's uncommitted rows and the first `ROLLBACK` finds nothing
+// to undo. This queue makes them consecutive instead, which is what a pinned pool connection
+// gives `withTransaction` and `readOnlyQuery` on a real server.
+
+/**
+ * Gives the connection back. Idempotent for free: it is a settled promise's `resolve`, not a
+ * counter, so a second call cannot hand out a second turn — the next caller is already awake.
+ */
+export type Turn = () => void;
+
+export interface TurnQueue {
+  /** Wait for the connection, then keep it until the returned `Turn` is called. */
+  take(): Promise<Turn>;
+  /** Take a turn, run, give it back — the whole life of a single statement. */
+  run<T>(work: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * FIFO, because the tail is the only thing a new caller waits on and every caller extends it in
+ * the order it arrived. The tail never rejects: a turn whose work threw must still be the turn
+ * the next caller waits for, or one failed statement strands the connection for the process.
+ */
+export function createTurnQueue(): TurnQueue {
+  let tail: Promise<void> = Promise.resolve();
+
+  async function take(): Promise<Turn> {
+    let release!: () => void;
+    const held = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const mine = tail;
+    // Claim the slot before awaiting: two synchronous `take()` calls must queue behind each
+    // other, not both read the same tail and run at once.
+    tail = mine.then(() => held);
+    await mine;
+    return release;
+  }
+
+  async function run<T>(work: () => Promise<T>): Promise<T> {
+    const turn = await take();
+    try {
+      return await work();
+    } finally {
+      turn();
+    }
+  }
+
+  return { take, run };
+}