@coffre/db 0.0.0 → 0.1.1

package/src/dialect.ts

@@ -0,0 +1,174 @@
+import { entityKind, getTableColumns, sql, type SQL } from 'drizzle-orm';
+import type { PgTable } from 'drizzle-orm/pg-core';
+
+import type { Queryable } from './database.ts';
+
+/**
+ * Differences between Postgres and the SQLite used for tests and local dev.
+ * Queries stay in the server's queries.ts; it never asks which database it has.
+ *
+ *                     Postgres                SQLite
+ *   isolation         READ COMMITTED          one writer at a time
+ *   lock a row        SELECT … FOR UPDATE     one writer at a time
+ *   rows changed      rowCount                rowsAffected
+ *   duplicate key     SQLSTATE 23505          SQLITE_CONSTRAINT_UNIQUE
+ *   clock             CURRENT_TIMESTAMP       strftime(…, 'now')
+ *   clock, in ms      clock_timestamp()       unixepoch('subsec')
+ *   a condition read  true / false            1 / 0
+ *
+ * Nothing here imports SQLite code, so the Worker bundles none.
+ */
+
+export type Table = PgTable;
+
+export type Engine = 'postgres' | 'sqlite';
+
+/** Which database this is, from the Drizzle dialect it was opened with. */
+export function engineOf(db: Queryable): Engine {
+  const kind = (db as unknown as { dialect: { constructor: { [entityKind]: string } } }).dialect.constructor[entityKind];
+  if (kind.startsWith('Pg')) return 'postgres';
+  if (kind.startsWith('SQLite')) return 'sqlite';
+  throw new Error(`unsupported database: ${kind}`);
+}
+
+/**
+ * Lock the rows a select reads until the transaction ends. SQLite has no row
+ * locks and needs none: connect.ts runs one transaction at a time, and each
+ * holds the database's write lock from its first statement.
+ *
+ * `no key update` is for rows others reference by foreign key: it keeps out
+ * every other writer of the row, but not an insert that points at it.
+ */
+export function forUpdate<Query extends { for: (strength: 'update' | 'no key update') => unknown }>(
+  db: Queryable,
+  query: Query,
+  strength: 'update' | 'no key update' = 'update',
+): ReturnType<Query['for']> {
+  if (engineOf(db) === 'sqlite') return query as ReturnType<Query['for']>;
+  return query.for(strength) as ReturnType<Query['for']>;
+}
+
+/** Insert the rows whose unique keys are free; returns how many that was. */
+export async function insertIfAbsent(db: Queryable, table: Table, rows: object[]): Promise<number> {
+  return changedRows(await db.insert(table).values(rows as never).onConflictDoNothing());
+}
+
+/**
+ * Insert the rows, or where one repeats the unique key `target`, overwrite
+ * `columns` of the existing row with the values it was about to insert.
+ */
+export async function upsert<T extends Table>(
+  db: Queryable,
+  table: T,
+  rows: object[],
+  target: (keyof T['$inferSelect'])[],
+  columns: (keyof T['$inferSelect'])[],
+): Promise<void> {
+  const all = getTableColumns(table) as Record<string, ReturnType<typeof getTableColumns>[string]>;
+  const incoming = (name: string) => sql`excluded.${sql.identifier(all[name].name)}`;
+  const set = Object.fromEntries(columns.map((name) => [name, incoming(name as string)]));
+  const query = db.insert(table).values(rows as never);
+  await query.onConflictDoUpdate({
+    target: target.map((name) => all[name as string]) as never,
+    set: set as never,
+  });
+}
+
+/** A condition read as a boolean: Postgres returns true or false, SQLite 1 or 0. */
+export function truth(condition: SQL): SQL<boolean> {
+  return condition.mapWith((value) => Number(value) === 1);
+}
+
+/** How many rows an insert, update or delete touched. */
+export function changedRows(result: unknown): number {
+  const header = result as { rowCount?: number | null; rowsAffected?: number };
+  return header.rowCount ?? header.rowsAffected ?? 0;
+}
+
+const DUPLICATE_KEY = new Set(['23505', 'SQLITE_CONSTRAINT_UNIQUE', 'SQLITE_CONSTRAINT_PRIMARYKEY']);
+
+/** Whether an insert or update failed on a unique constraint. */
+export function isUniqueViolation(error: unknown): boolean {
+  for (let cause = error; typeof cause === 'object' && cause !== null; ) {
+    const { code, extendedCode } = cause as { code?: unknown; extendedCode?: unknown };
+    if (DUPLICATE_KEY.has(code as string) || DUPLICATE_KEY.has(extendedCode as string)) return true;
+    cause = (cause as { cause?: unknown }).cause;
+  }
+  return false;
+}
+
+/**
+ * A consistent read of several statements that cannot write, such as
+ * verifying the chain. SQLite ignores it: its transactions already see one
+ * snapshot, and connect.ts runs them one at a time.
+ */
+export const SNAPSHOT = { isolationLevel: 'repeatable read', accessMode: 'read only' } as const;
+
+/**
+ * The database clock as text, for canonicalTimestamp. Entries from several
+ * servers order by it, so it is never an application server's.
+ */
+export function clock(db: Queryable): SQL<string> {
+  switch (engineOf(db)) {
+    case 'postgres':
+      return sql<string>`CURRENT_TIMESTAMP`;
+    case 'sqlite':
+      return sql<string>`strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`;
+  }
+}
+
+/**
+ * The database clock as milliseconds since the epoch, as the statement runs:
+ * Postgres's `clock_timestamp()`, not `CURRENT_TIMESTAMP`, which is the
+ * transaction's start and would date an entry that waited for the log's lock
+ * before one written while it waited. Read it in a statement after the lock.
+ */
+export function clockMillis(db: Queryable): SQL<number> {
+  switch (engineOf(db)) {
+    case 'postgres':
+      return sql`(extract(epoch from clock_timestamp()) * 1000)::bigint`.mapWith(Number);
+    case 'sqlite':
+      return sql`CAST(unixepoch('subsec') * 1000 AS INTEGER)`.mapWith(Number);
+  }
+}
+
+/**
+ * The migrator's own ledger, read by readiness to tell a database that is
+ * up but not yet migrated from one that is ready. Drizzle keeps it in a
+ * `drizzle` schema on Postgres, and in a plain table elsewhere.
+ */
+export function migrationLedger(db: Queryable): SQL {
+  const table = sql.identifier('__drizzle_migrations');
+  return engineOf(db) === 'postgres' ? sql`${sql.identifier('drizzle')}.${table}` : sql`${table}`;
+}
+
+const TIMESTAMP =
+  /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,6}))?(Z|[+-]\d{2}(?::?\d{2})?)?$/;
+
+/**
+ * The one rendering of a timestamp read as text: UTC, microseconds, `Z`.
+ *
+ * The audit chain covers occurred_at as text, so reading a row back has to
+ * reproduce it byte for byte. Databases hand timestamps back in their own
+ * shapes (`2026-09-27 12:34:56.1+02` from Postgres, ISO text from SQLite),
+ * and a Date would drop the microseconds, so every value goes through here
+ * on the way in and out:
+ *
+ *   2026-09-27 12:34:56.1+02  ->  2026-09-27T10:34:56.100000Z
+ *   2026-09-27T10:34:56.1Z   ->  2026-09-27T10:34:56.100000Z
+ */
+export function canonicalTimestamp(raw: string): string {
+  const match = TIMESTAMP.exec(raw);
+  if (match === null) throw new Error(`unexpected timestamp from the database: ${raw}`);
+  const [, year, month, day, hour, minute, second, fraction = '', zone = 'Z'] = match;
+  let offsetMinutes = 0;
+  if (zone !== 'Z') {
+    const sign = zone.startsWith('-') ? -1 : 1;
+    const digits = zone.slice(1).replace(':', '');
+    offsetMinutes = sign * (Number(digits.slice(0, 2)) * 60 + Number(digits.slice(2) || '0'));
+  }
+  const utc = new Date(
+    Date.UTC(+year, +month - 1, +day, +hour, +minute, +second) - offsetMinutes * 60_000,
+  );
+  return `${utc.toISOString().slice(0, 19)}.${fraction.padEnd(6, '0')}Z`;
+}

package/src/drizzle.postgres.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'drizzle-kit';
+
+export default defineConfig({
+  dialect: 'postgresql',
+  schema: './schema.ts',
+  out: './migrations/postgres',
+});

package/src/drizzle.sqlite.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'drizzle-kit';
+
+export default defineConfig({
+  dialect: 'sqlite',
+  schema: './schema.sqlite.ts',
+  out: './migrations/sqlite',
+});

package/src/hyperdrive.ts

@@ -0,0 +1,63 @@
+import pg from 'pg';
+
+import type { PoolLike } from './database.ts';
+import { postgresConnection } from './postgres.ts';
+
+/** Postgres through a Hyperdrive binding: `postgres(env.HYPERDRIVE)`. */
+export type PostgresDatabase = { readonly engine: 'postgres'; readonly hyperdrive: { readonly connectionString: string } };
+
+/** Postgres through Hyperdrive, the one database a Worker runs on, the app's and the vault's. */
+export function postgres(hyperdrive: { readonly connectionString: string }): PostgresDatabase {
+  if (typeof hyperdrive?.connectionString !== 'string') {
+    throw new Error('postgres() takes the Hyperdrive binding, e.g. postgres(env.HYPERDRIVE)');
+  }
+  return { engine: 'postgres', hyperdrive };
+}
+
+/**
+ * Request-scoped node-postgres adapter for Hyperdrive.
+ *
+ * Hyperdrive owns the durable origin pool. The Worker creates edge clients
+ * only inside one invocation, which prevents I/O objects from leaking across
+ * Worker request contexts while keeping the Pool shape Drizzle expects. The
+ * class name must end in `Pool`: that is how Drizzle knows to check out a
+ * client for each transaction.
+ */
+export class HyperdrivePool implements Exclude<PoolLike, pg.Pool> {
+  readonly #connectionString: string;
+
+  constructor(connectionString: string) {
+    if (connectionString.trim().length === 0) {
+      throw new Error('Hyperdrive returned an empty connection string');
+    }
+    this.#connectionString = connectionString;
+  }
+
+  readonly query: pg.Pool['query'] = (async (...args: unknown[]) => {
+    const client = await this.#connectClient();
+    try {
+      return await (client.query as (...queryArgs: unknown[]) => Promise<unknown>)(...args);
+    } finally {
+      await client.end();
+    }
+  }) as pg.Pool['query'];
+
+  async connect(): Promise<Pick<pg.PoolClient, 'query'> & { release: () => void }> {
+    const client = await this.#connectClient();
+    let released = false;
+    return {
+      query: client.query.bind(client) as pg.PoolClient['query'],
+      release: () => {
+        if (released) return;
+        released = true;
+        client.end().catch(() => {});
+      },
+    };
+  }
+
+  async #connectClient(): Promise<pg.Client> {
+    const client = new pg.Client(postgresConnection(this.#connectionString));
+    await client.connect();
+    return client;
+  }
+}

package/src/log.ts

@@ -0,0 +1,177 @@
+import { GENESIS_HASH, sealEntry, type LogFields, type LogKey } from '@coffre/core/audit';
+import { desc, eq } from 'drizzle-orm';
+
+import { afterCommit } from './commits.ts';
+import { tablesOf, type Transaction } from './database.ts';
+import { clockMillis, forUpdate } from './dialect.ts';
+
+/**
+ * Appending to the audit log, the one table both the app and the vault
+ * write, each under its own key (@coffre/core/audit says what an entry's MAC
+ * and hash cover).
+ *
+ * Every append locks the log's head first, `audit_chain_head`, so entries
+ * from any process take their numbers in one order. It then reads the
+ * database clock, after the lock, and the log's last entry, which the head
+ * must name: a head that does not was moved, or entries were deleted behind
+ * it, and the append refuses.
+ *
+ * This is deliberately not a queue and not best-effort: the entries go in
+ * the caller's transaction, so if the append fails, what it records does
+ * not happen either.
+ */
+
+/** An entry to append: what it says. The append numbers, dates, signs and chains it. */
+export type NewEntry = {
+  actor: string;
+  action: string;
+  decision: 'allow' | 'deny';
+  code?: string | null;
+  subjectPrincipal?: string | null;
+  projectId?: string | null;
+  environmentId?: string | null;
+  secretId?: string | null;
+  secretVersionId?: string | null;
+  operationId?: string | null;
+  requestId?: string | null;
+  sourceIp?: string | null;
+  relatedSeq?: bigint | null;
+  /** JSON text. */
+  metadata?: string;
+};
+
+export type Appended = {
+  /** The first entry's number, and the next number after the last. */
+  seqStart: bigint;
+  nextSeq: bigint;
+  headHash: Buffer;
+  /** Milliseconds since the epoch, the database's, shared by the batch. */
+  occurredAt: number;
+};
+
+/** The log's head does not name its last entry: something moved it, or cut the log behind it. */
+export class LogHeadMismatch extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'LogHeadMismatch';
+  }
+}
+
+/**
+ * The log's head is behind one this process wrote: the database was rolled
+ * back, or entries were cut off its end. That cannot be told from a restore,
+ * so the append refuses and someone has to look.
+ */
+export class LogRewound extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'LogRewound';
+  }
+}
+
+/**
+ * The newest head each writer has written, under each of its keys, while
+ * the process lives. A head is remembered only once the transaction that
+ * wrote it has committed, all the way out (commits.ts): one that rolls back
+ * never puts it ahead of the database, and the last batch committed is
+ * covered too. When commits race, the furthest head stays.
+ */
+const remembered = new WeakMap<LogKey, { epoch: number; nextSeq: bigint; headHash: Buffer }>();
+let epoch = 0;
+
+function remember(key: LogKey, head: { nextSeq: bigint; headHash: Buffer }): void {
+  const before = remembered.get(key);
+  if (before !== undefined && before.epoch === epoch && before.nextSeq >= head.nextSeq) return;
+  remembered.set(key, { epoch, ...head });
+}
+
+/**
+ * Forget every head written so far. For tests that empty the database
+ * between cases, which is exactly what the check above refuses.
+ */
+export function forgetLogHeads(): void {
+  epoch += 1;
+}
+
+/**
+ * Lock the log's head, and read it. A transaction that appends takes this
+ * before any other row, so the lock order is the same everywhere; taking it
+ * again in the same transaction is free.
+ */
+export async function lockLogHead(tx: Transaction): Promise<{ nextSeq: bigint; headHash: Buffer }> {
+  const { auditChainHead } = tablesOf(tx);
+  const [head] = await forUpdate(
+    tx,
+    tx
+      .select({ nextSeq: auditChainHead.nextSeq, headHash: auditChainHead.headHash })
+      .from(auditChainHead)
+      .where(eq(auditChainHead.onlyRow, true)),
+  );
+  if (head === undefined) throw new Error('audit_chain_head is missing; refusing to write an unchained entry');
+  return head;
+}
+
+export async function appendEntries(tx: Transaction, key: LogKey, entries: readonly NewEntry[]): Promise<Appended> {
+  if (entries.length === 0) throw new Error('appendEntries called with no entries');
+  const { auditChainHead, auditLog } = tablesOf(tx);
+
+  // Every append queues here, if its transaction has not already.
+  const head = await lockLogHead(tx);
+  const [{ now }] = await tx.select({ now: clockMillis(tx) }).from(auditChainHead);
+  const [last] = await tx
+    .select({ seq: auditLog.seq, hash: auditLog.hash })
+    .from(auditLog)
+    .orderBy(desc(auditLog.seq))
+    .limit(1);
+
+  const expected = last === undefined ? { nextSeq: 0n, headHash: GENESIS_HASH } : { nextSeq: last.seq + 1n, headHash: last.hash };
+  if (head.nextSeq !== expected.nextSeq || !head.headHash.equals(expected.headHash)) {
+    throw new LogHeadMismatch(
+      `the log's head says entry ${head.nextSeq} comes next, but the log ends ${last === undefined ? 'empty' : `at entry ${last.seq}`}, or with another hash`,
+    );
+  }
+  const before = remembered.get(key);
+  if (
+    before !== undefined &&
+    before.epoch === epoch &&
+    (head.nextSeq < before.nextSeq || (head.nextSeq === before.nextSeq && !head.headHash.equals(before.headHash)))
+  ) {
+    throw new LogRewound(`the log ends before entry ${before.nextSeq}, which this process wrote: it was rolled back`);
+  }
+
+  let seq = head.nextSeq;
+  let prevHash = head.headHash;
+  const rows: (typeof auditLog.$inferInsert)[] = [];
+  for (const entry of entries) {
+    const fields: LogFields = {
+      seq,
+      author: key.author,
+      keyId: key.keyId,
+      occurredAt: now,
+      actor: entry.actor,
+      action: entry.action,
+      decision: entry.decision,
+      code: entry.code ?? null,
+      subjectPrincipal: entry.subjectPrincipal ?? null,
+      projectId: entry.projectId ?? null,
+      environmentId: entry.environmentId ?? null,
+      secretId: entry.secretId ?? null,
+      secretVersionId: entry.secretVersionId ?? null,
+      operationId: entry.operationId ?? null,
+      requestId: entry.requestId ?? null,
+      sourceIp: entry.sourceIp ?? null,
+      relatedSeq: entry.relatedSeq ?? null,
+      metadata: entry.metadata ?? '{}',
+    };
+    const { mac, hash } = sealEntry(key, prevHash, fields);
+    rows.push({ ...fields, prevHash, mac, hash });
+    prevHash = hash;
+    seq += 1n;
+  }
+
+  await tx.insert(auditLog).values(rows);
+  await tx.update(auditChainHead).set({ nextSeq: seq, headHash: prevHash }).where(eq(auditChainHead.onlyRow, true));
+  const written = { nextSeq: seq, headHash: prevHash };
+  afterCommit(tx, () => remember(key, written));
+  return { seqStart: head.nextSeq, ...written, occurredAt: now };
+}

package/src/migrate-main.ts

@@ -0,0 +1,8 @@
+// `pnpm db:migrate`: the workspace's own migrator, for dev
+// and the tests. A deployment runs `coffre-server migrate`.
+import { migrateDatabase } from './migrate.ts';
+
+const url = process.env.DATABASE_URL?.trim();
+if (!url) throw new Error('DATABASE_URL is required');
+await migrateDatabase(url);
+console.log('database schema is up to date');

package/src/migrate.ts

@@ -0,0 +1,207 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+import { engineOfUrl } from './connect.ts';
+import type { Engine } from './dialect.ts';
+import { postgresConnection } from './postgres.ts';
+
+/**
+ * Bring a database up to date with its engine's migration tree:
+ * migrations/postgres or migrations/sqlite. Both trees
+ * describe one schema; see schema-parity.test.ts.
+ *
+ * Applied history must be a prefix of the local journal, byte for byte,
+ * before and after. Only one migrator runs at a time: Postgres takes an
+ * advisory lock, and SQLite's own write lock covers the
+ * whole run. Restricted runtime roles are Postgres-only (baseline/postgres.sql).
+ */
+
+const MIGRATION_LOCK_KEY = '7165058122361679213';
+
+interface JournalEntry {
+  idx: number;
+  when: number;
+  tag: string;
+}
+
+interface ExpectedMigration {
+  createdAt: string;
+  hash: string;
+  tag: string;
+}
+
+interface AppliedMigration {
+  created_at: string;
+  hash: string;
+}
+
+/** A connection that applies one engine's tree. */
+interface Migrator {
+  /** The applied history, oldest first, or null before the first migration. */
+  applied(): Promise<AppliedMigration[] | null>;
+  lock(): Promise<void>;
+  unlock(): Promise<void>;
+  migrate(migrationsFolder: string): Promise<void>;
+  /** Reassert privileges a one-database backup does not carry. */
+  restrict(): Promise<void>;
+  close(): Promise<void>;
+}
+
+/**
+ * Beside this module: src/migrations in the workspace, and dist/migrations
+ * in the built package, where the build copies them.
+ */
+export function migrationsFolder(engine: Engine): string {
+  return fileURLToPath(new URL(`./migrations/${engine}`, import.meta.url));
+}
+
+async function expectedMigrations(engine: Engine): Promise<ExpectedMigration[]> {
+  const folder = migrationsFolder(engine);
+  const journal = JSON.parse(await readFile(`${folder}/meta/_journal.json`, 'utf8')) as { entries?: JournalEntry[] };
+  if (!Array.isArray(journal.entries)) {
+    throw new Error('invalid Drizzle migration journal');
+  }
+
+  const expected = await Promise.all(
+    journal.entries.map(async (entry, position) => {
+      if (
+        entry.idx !== position
+        || !Number.isSafeInteger(entry.when)
+        || typeof entry.tag !== 'string'
+        || !/^[a-zA-Z0-9_-]+$/.test(entry.tag)
+      ) {
+        throw new Error(`invalid Drizzle migration journal entry at index ${position}`);
+      }
+      const sqlText = await readFile(`${folder}/${entry.tag}.sql`, 'utf8');
+      return {
+        createdAt: String(entry.when),
+        hash: createHash('sha256').update(sqlText).digest('hex'),
+        tag: entry.tag,
+      };
+    }),
+  );
+
+  for (let index = 1; index < expected.length; index += 1) {
+    if (BigInt(expected[index - 1].createdAt) >= BigInt(expected[index].createdAt)) {
+      throw new Error('Drizzle migration journal timestamps must be strictly increasing');
+    }
+  }
+  return expected;
+}
+
+function verifyHistory(
+  expected: ExpectedMigration[],
+  applied: AppliedMigration[] | null,
+  requireComplete: boolean,
+): void {
+  const rows = applied ?? [];
+  if (rows.length > expected.length) {
+    throw new Error('database contains migrations that are absent from this image');
+  }
+  if (requireComplete && rows.length !== expected.length) {
+    throw new Error(`migration history is incomplete: expected ${expected.length}, found ${rows.length}`);
+  }
+
+  rows.forEach((row, index) => {
+    const local = expected[index];
+    if (row.created_at !== local.createdAt || row.hash !== local.hash) {
+      throw new Error(
+        `migration history diverged at ${local.tag}; applied migrations must never be edited`,
+      );
+    }
+  });
+}
+
+async function postgresMigrator(url: string): Promise<Migrator> {
+  const [{ default: pg }, { drizzle }, { migrate }] = await Promise.all([
+    import('pg'),
+    import('drizzle-orm/node-postgres'),
+    import('drizzle-orm/node-postgres/migrator'),
+  ]);
+  const pool = new pg.Pool({ ...postgresConnection(url), application_name: 'coffre-migrations', max: 1 });
+  const client = await pool.connect();
+  return {
+    async applied() {
+      const relation = await client.query<{ relation: string | null }>(
+        "SELECT to_regclass('drizzle.__drizzle_migrations')::text AS relation",
+      );
+      if (!relation.rows[0]?.relation) return null;
+      const result = await client.query<AppliedMigration>(
+        'SELECT hash, created_at::text FROM drizzle.__drizzle_migrations ORDER BY created_at, id',
+      );
+      return result.rows;
+    },
+    async lock() {
+      await client.query("SET lock_timeout = '5min'");
+      await client.query('SELECT pg_advisory_lock($1::bigint)', [MIGRATION_LOCK_KEY]);
+    },
+    async unlock() {
+      await client.query('SELECT pg_advisory_unlock($1::bigint)', [MIGRATION_LOCK_KEY]);
+    },
+    migrate: (migrationsFolder) => migrate(drizzle(client), { migrationsFolder }),
+    async restrict() {
+      // pg_dump carries table privileges, but not privileges on the database itself.
+      await client.query(`DO $$ BEGIN
+        EXECUTE format(
+          'REVOKE CREATE, TEMPORARY ON DATABASE %I FROM PUBLIC, coffre_app, coffre_runtime, coffre_vault, coffre_vault_runtime',
+          current_database()
+        );
+      END $$`);
+    },
+    async close() {
+      client.release();
+      await pool.end();
+    },
+  };
+}
+
+async function sqliteMigrator(url: string): Promise<Migrator> {
+  const [{ openDatabase }, { migrate }] = await Promise.all([
+    import('./connect.ts'),
+    import('drizzle-orm/libsql/migrator'),
+  ]);
+  const { db, close } = await openDatabase(url);
+  const sqlite = db as unknown as Parameters<typeof migrate>[0];
+  return {
+    async applied() {
+      const tables = await sqlite.all(
+        "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = '__drizzle_migrations'",
+      );
+      if (tables.length === 0) return null;
+      return sqlite.all<AppliedMigration>(
+        'SELECT hash, CAST(created_at AS TEXT) AS created_at FROM __drizzle_migrations ORDER BY created_at, id',
+      );
+    },
+    // The migration runs as one transaction, in the database's write queue.
+    async lock() {},
+    async unlock() {},
+    migrate: (migrationsFolder) => migrate(sqlite, { migrationsFolder }),
+    async restrict() {},
+    close,
+  };
+}
+
+/** Apply missing migrations, check their history and reassert database privileges. */
+export async function migrateDatabase(url: string): Promise<void> {
+  const engine = engineOfUrl(url);
+  const expected = await expectedMigrations(engine);
+  const migrator = await { postgres: postgresMigrator, sqlite: sqliteMigrator }[engine](url);
+  let locked = false;
+
+  try {
+    await migrator.lock();
+    locked = true;
+
+    verifyHistory(expected, await migrator.applied(), false);
+    await migrator.migrate(migrationsFolder(engine));
+    verifyHistory(expected, await migrator.applied(), true);
+    await migrator.restrict();
+  } finally {
+    try {
+      if (locked) await migrator.unlock();
+    } finally {
+      await migrator.close();
+    }
+  }
+}