@coffre/db 0.0.0-stage → 0.1.0

package/src/baseline/postgres.sql

@@ -0,0 +1,238 @@
+-- The schema on Postgres. Generated by `pnpm db:generate` from
+-- baseline/postgres.sql and src/schema.ts; edit those, not this.
+
+-- @schema
+
+-- The chain starts at sequence 0 from 32 zero bytes.
+INSERT INTO audit_chain_head (only_row, next_seq, head_hash)
+VALUES (true, 0, decode(repeat('00', 32), 'hex'));
+--> statement-breakpoint
+
+-- The audit log only grows, for every login, its owner's included. The
+-- grants below already keep the runtime login from changing it; this stops
+-- a bug or a careless statement by the owner too, who can still lift it
+-- with ALTER TABLE ... DISABLE TRIGGER. What an owner changes anyway, the
+-- entries' MACs and chain show.
+CREATE FUNCTION audit_log_append_only() RETURNS trigger LANGUAGE plpgsql AS $$
+BEGIN
+    RAISE EXCEPTION 'audit_log is append-only' USING ERRCODE = 'insufficient_privilege';
+END
+$$;
+--> statement-breakpoint
+CREATE TRIGGER audit_log_no_change BEFORE UPDATE OR DELETE ON audit_log
+    FOR EACH ROW EXECUTE FUNCTION audit_log_append_only();
+--> statement-breakpoint
+CREATE TRIGGER audit_log_no_truncate BEFORE TRUNCATE ON audit_log
+    FOR EACH STATEMENT EXECUTE FUNCTION audit_log_append_only();
+--> statement-breakpoint
+
+-- Two logins, provisioned outside coffre (their passwords are never ours),
+-- each with only the rights of its group:
+--
+--   coffre_runtime        the server, through coffre_app: read and insert,
+--                         UPDATE on named columns only, and never DELETE. A
+--                         revoked session, a used device code and a removed
+--                         sync key are rows that say so, not gaps.
+--   coffre_vault_runtime  the vault, through coffre_vault: its members and
+--                         grants, and reading what it decides on.
+--
+-- Both append to the audit log, each only as its own author (row-level
+-- security, below), and neither may change or delete an entry.
+DO $$
+DECLARE
+    name text;
+BEGIN
+    FOREACH name IN ARRAY ARRAY['coffre_app', 'coffre_vault'] LOOP
+        IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = name) THEN
+            EXECUTE format('CREATE ROLE %I', name);
+        END IF;
+    END LOOP;
+END
+$$;
+--> statement-breakpoint
+
+ALTER ROLE coffre_app
+    NOLOGIN INHERIT NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS;
+--> statement-breakpoint
+ALTER ROLE coffre_vault
+    NOLOGIN INHERIT NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS;
+--> statement-breakpoint
+
+DO $$
+DECLARE
+    name text;
+    runtime_role oid;
+BEGIN
+    FOREACH name IN ARRAY ARRAY['coffre_runtime', 'coffre_vault_runtime'] LOOP
+        SELECT oid INTO runtime_role FROM pg_roles WHERE rolname = name;
+        IF runtime_role IS NULL THEN
+            RAISE EXCEPTION '% must be provisioned before migrations', name;
+        END IF;
+
+        IF EXISTS (
+            SELECT 1
+              FROM pg_roles
+             WHERE oid = runtime_role
+               AND (rolsuper OR rolcreatedb OR rolcreaterole OR rolreplication OR rolbypassrls)
+        ) THEN
+            RAISE EXCEPTION '% has unsafe role attributes', name;
+        END IF;
+
+        IF EXISTS (
+            SELECT 1
+              FROM pg_shdepend
+             WHERE refclassid = 'pg_authid'::regclass
+               AND refobjid = runtime_role
+               AND deptype = 'o'
+        ) THEN
+            RAISE EXCEPTION '% owns database objects', name;
+        END IF;
+    END LOOP;
+END
+$$;
+--> statement-breakpoint
+
+REVOKE ALL PRIVILEGES ON ALL TABLES IN SCHEMA public
+    FROM coffre_app, coffre_runtime, coffre_vault, coffre_vault_runtime;
+--> statement-breakpoint
+REVOKE ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public
+    FROM coffre_app, coffre_runtime, coffre_vault, coffre_vault_runtime;
+--> statement-breakpoint
+REVOKE ALL PRIVILEGES ON ALL ROUTINES IN SCHEMA public
+    FROM coffre_app, coffre_runtime, coffre_vault, coffre_vault_runtime;
+--> statement-breakpoint
+REVOKE ALL PRIVILEGES ON SCHEMA public
+    FROM coffre_app, coffre_runtime, coffre_vault, coffre_vault_runtime;
+--> statement-breakpoint
+GRANT USAGE ON SCHEMA public TO coffre_app, coffre_vault;
+--> statement-breakpoint
+GRANT USAGE ON SCHEMA drizzle TO coffre_app, coffre_vault;
+--> statement-breakpoint
+GRANT SELECT ON drizzle.__drizzle_migrations TO coffre_app, coffre_vault;
+--> statement-breakpoint
+
+GRANT SELECT, INSERT ON
+    projects,
+    environments,
+    secrets,
+    secret_versions,
+    audit_log,
+    identities,
+    credentials,
+    device_authorizations,
+    syncs,
+    sync_keys
+TO coffre_app;
+--> statement-breakpoint
+
+GRANT SELECT ON
+    audit_chain_head,
+    vault_members,
+    vault_grants
+TO coffre_app;
+--> statement-breakpoint
+
+GRANT UPDATE (slug, name, archived_at) ON projects TO coffre_app;
+--> statement-breakpoint
+GRANT UPDATE (slug, name, archived_at) ON environments TO coffre_app;
+--> statement-breakpoint
+GRANT UPDATE (key, current_version_id, current_version, updated_at, archived_at) ON secrets TO coffre_app;
+--> statement-breakpoint
+GRANT UPDATE (next_seq, head_hash) ON audit_chain_head TO coffre_app;
+--> statement-breakpoint
+GRANT UPDATE (email, last_sign_in_at, revoked_at, revoked_by, auth_mac) ON identities TO coffre_app;
+--> statement-breakpoint
+GRANT UPDATE (last_used_at, last_used_ip, revoked_at, revoked_by, auth_mac) ON credentials TO coffre_app;
+--> statement-breakpoint
+GRANT UPDATE (decided_at, decision, generation, principal, consumed_at, auth_mac)
+    ON device_authorizations TO coffre_app;
+--> statement-breakpoint
+GRANT UPDATE (config, credential_secret_id, paused_at, archived_at, lease_until,
+              last_run_at, last_status, last_error)
+    ON syncs TO coffre_app;
+--> statement-breakpoint
+GRANT UPDATE (secret_version_id, pushed_at, removed_at) ON sync_keys TO coffre_app;
+--> statement-breakpoint
+
+-- The vault reads what it decides on and the log it chains to, and writes
+-- its members and grants. A revoked grant is deleted: the log keeps it.
+GRANT SELECT ON
+    projects,
+    environments,
+    secrets,
+    secret_versions,
+    audit_chain_head
+TO coffre_vault;
+--> statement-breakpoint
+GRANT SELECT, INSERT ON audit_log TO coffre_vault;
+--> statement-breakpoint
+GRANT SELECT, INSERT, UPDATE (status, owner, generation, created_at, created_by, status_changed_at, status_changed_by, access_seq, mac)
+    ON vault_members TO coffre_vault;
+--> statement-breakpoint
+GRANT SELECT, INSERT, DELETE ON vault_grants TO coffre_vault;
+--> statement-breakpoint
+GRANT UPDATE (next_seq, head_hash) ON audit_chain_head TO coffre_vault;
+--> statement-breakpoint
+
+REVOKE DELETE, TRUNCATE ON ALL TABLES IN SCHEMA public FROM coffre_app;
+--> statement-breakpoint
+REVOKE TRUNCATE ON ALL TABLES IN SCHEMA public FROM coffre_vault;
+--> statement-breakpoint
+REVOKE UPDATE ON audit_log, secret_versions FROM coffre_app, coffre_vault;
+--> statement-breakpoint
+REVOKE CREATE ON SCHEMA public FROM PUBLIC, coffre_app, coffre_runtime, coffre_vault, coffre_vault_runtime;
+--> statement-breakpoint
+
+-- Each login appends only as its own author. Its MAC is still what proves
+-- who wrote an entry: the table's owner passes these policies, as owners do.
+ALTER TABLE audit_log ENABLE ROW LEVEL SECURITY;
+--> statement-breakpoint
+CREATE POLICY audit_log_read ON audit_log FOR SELECT TO coffre_app, coffre_vault USING (true);
+--> statement-breakpoint
+CREATE POLICY audit_log_app_appends ON audit_log FOR INSERT TO coffre_app WITH CHECK (author = 'app');
+--> statement-breakpoint
+CREATE POLICY audit_log_vault_appends ON audit_log FOR INSERT TO coffre_vault WITH CHECK (author = 'vault');
+--> statement-breakpoint
+
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+    REVOKE ALL PRIVILEGES ON TABLES FROM coffre_app, coffre_runtime, coffre_vault, coffre_vault_runtime;
+--> statement-breakpoint
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+    REVOKE ALL PRIVILEGES ON SEQUENCES FROM coffre_app, coffre_runtime, coffre_vault, coffre_vault_runtime;
+--> statement-breakpoint
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+    REVOKE ALL PRIVILEGES ON ROUTINES FROM coffre_app, coffre_runtime, coffre_vault, coffre_vault_runtime;
+--> statement-breakpoint
+
+-- Each login is a member of its own group and of nothing else.
+DO $$
+DECLARE
+    login record;
+    membership record;
+BEGIN
+    EXECUTE format(
+        'REVOKE CREATE, TEMPORARY ON DATABASE %I FROM PUBLIC, coffre_app, coffre_runtime, coffre_vault, coffre_vault_runtime',
+        current_database()
+    );
+
+    FOR login IN
+        SELECT * FROM (VALUES ('coffre_runtime', 'coffre_app'), ('coffre_vault_runtime', 'coffre_vault')) AS logins (name, grp)
+    LOOP
+        FOR membership IN
+            SELECT granted.rolname
+              FROM pg_auth_members member_of
+              JOIN pg_roles member ON member.oid = member_of.member
+              JOIN pg_roles granted ON granted.oid = member_of.roleid
+             WHERE member.rolname = login.name
+               AND granted.rolname <> login.grp
+        LOOP
+            EXECUTE format('REVOKE %I FROM %I', membership.rolname, login.name);
+        END LOOP;
+    END LOOP;
+END
+$$;
+--> statement-breakpoint
+
+GRANT coffre_app TO coffre_runtime WITH ADMIN FALSE, INHERIT TRUE, SET FALSE;
+--> statement-breakpoint
+GRANT coffre_vault TO coffre_vault_runtime WITH ADMIN FALSE, INHERIT TRUE, SET FALSE;

package/src/baseline/sqlite.sql

@@ -0,0 +1,27 @@
+-- The schema on SQLite. Generated by `pnpm db:generate` from
+-- baseline/sqlite.sql and src/schema.sqlite.ts; edit those, not this.
+
+-- @schema
+
+-- The chain starts at sequence 0 from 32 zero bytes.
+INSERT INTO `audit_chain_head` (`only_row`, `next_seq`, `head_hash`) VALUES (true, 0, zeroblob(32));
+--> statement-breakpoint
+
+-- The audit log only grows: no statement may change or delete an entry.
+-- What gets past this anyway, the entries' MACs and chain show.
+-- REPLACE can delete without firing DELETE triggers, so refuse it before insert.
+CREATE TRIGGER `audit_log_no_replace` BEFORE INSERT ON `audit_log`
+WHEN EXISTS (SELECT 1 FROM `audit_log` WHERE `seq` = NEW.`seq`)
+BEGIN
+    SELECT RAISE(ABORT, 'audit_log is append-only');
+END;
+--> statement-breakpoint
+CREATE TRIGGER `audit_log_no_update` BEFORE UPDATE ON `audit_log`
+BEGIN
+    SELECT RAISE(ABORT, 'audit_log is append-only');
+END;
+--> statement-breakpoint
+CREATE TRIGGER `audit_log_no_delete` BEFORE DELETE ON `audit_log`
+BEGIN
+    SELECT RAISE(ABORT, 'audit_log is append-only');
+END;

package/src/baseline.ts

@@ -0,0 +1,104 @@
+import { execFileSync } from 'node:child_process';
+import { readFile, rm, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+import {
+  generateDrizzleJson,
+  generateMigration,
+  generateSQLiteDrizzleJson,
+  generateSQLiteMigration,
+} from 'drizzle-kit/api';
+
+import type { Engine } from './dialect.ts';
+import { migrationsFolder } from './migrate.ts';
+import * as postgres from './schema.ts';
+import * as sqlite from './schema.sqlite.ts';
+
+/**
+ * coffre has never been deployed, so there is no database to upgrade: each
+ * engine has one migration, its baseline, and a schema change regenerates it
+ * rather than adding a second. After the first deployment, changes become new
+ * migrations and this goes.
+ *
+ * A baseline is baseline/<engine>.sql with its `-- @schema` line replaced by
+ * the tables drizzle-kit generates from that engine's schema. The template
+ * holds what a schema cannot say: the audit chain's first rows, and the
+ * Postgres runtime role and its grants.
+ *
+ * `pnpm db:generate` runs this file and rewrites the baselines that are stale.
+ */
+
+export const ENGINES: readonly Engine[] = ['postgres', 'sqlite'];
+
+const TAG = '0000_baseline';
+const MARKER = '-- @schema\n';
+const here = fileURLToPath(new URL('.', import.meta.url));
+const packageRoot = fileURLToPath(new URL('..', import.meta.url));
+
+async function template(engine: Engine): Promise<{ head: string; tail: string }> {
+  const text = await readFile(`${here}baseline/${engine}.sql`, 'utf8');
+  const [head, tail, ...more] = text.split(MARKER);
+  if (tail === undefined || more.length > 0) {
+    throw new Error(`baseline/${engine}.sql needs exactly one ${MARKER.trim()} line`);
+  }
+  return { head, tail };
+}
+
+export async function journal(engine: Engine): Promise<{ idx: number; tag: string }[]> {
+  const text = await readFile(`${migrationsFolder(engine)}/meta/_journal.json`, 'utf8');
+  return (JSON.parse(text) as { entries: { idx: number; tag: string }[] }).entries;
+}
+
+/** The statements that would bring the engine's last snapshot to its schema. */
+async function pending(engine: Engine): Promise<string[]> {
+  const last = String((await journal(engine)).at(-1)!.idx).padStart(4, '0');
+  const snapshot = JSON.parse(
+    await readFile(`${migrationsFolder(engine)}/meta/${last}_snapshot.json`, 'utf8'),
+  ) as never;
+  switch (engine) {
+    case 'postgres':
+      return generateMigration(snapshot, generateDrizzleJson(postgres) as never);
+    case 'sqlite':
+      return generateSQLiteMigration(snapshot, (await generateSQLiteDrizzleJson(sqlite)) as never);
+  }
+}
+
+/** Why the engine's baseline is out of date: empty when it is not. */
+export async function staleness(engine: Engine): Promise<string[]> {
+  const tags = await journal(engine).then(
+    (entries) => entries.map((entry) => entry.tag),
+    () => [],
+  );
+  if (tags.length !== 1 || tags[0] !== TAG) return [`expected only ${TAG}, found [${tags.join(', ')}]`];
+  const reasons = await pending(engine);
+  const { head, tail } = await template(engine);
+  const baseline = await readFile(`${migrationsFolder(engine)}/${TAG}.sql`, 'utf8');
+  if (!baseline.startsWith(head) || !baseline.endsWith(tail)) reasons.push(`baseline/${engine}.sql changed`);
+  return reasons;
+}
+
+async function regenerate(engine: Engine): Promise<void> {
+  const folder = migrationsFolder(engine);
+  await rm(folder, { recursive: true, force: true });
+  execFileSync(
+    `${packageRoot}node_modules/.bin/drizzle-kit`,
+    ['generate', '--config', `drizzle.${engine}.config.ts`, '--name', 'baseline'],
+    { cwd: here, stdio: 'inherit' },
+  );
+  const tables = (await readFile(`${folder}/${TAG}.sql`, 'utf8')).trimEnd();
+  const breakpoint = tables.endsWith('--> statement-breakpoint') ? '' : '--> statement-breakpoint';
+  const { head, tail } = await template(engine);
+  await writeFile(`${folder}/${TAG}.sql`, `${head}${tables}${breakpoint}\n${tail}`);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  for (const engine of ENGINES) {
+    const reasons = await staleness(engine);
+    if (reasons.length === 0) {
+      console.log(`${engine}: the baseline is up to date`);
+      continue;
+    }
+    console.log(`${engine}: regenerating the baseline (${reasons.length} change${reasons.length === 1 ? '' : 's'})`);
+    await regenerate(engine);
+  }
+}

package/src/commits.ts

@@ -0,0 +1,47 @@
+/**
+ * Work to do once a transaction has committed, and never if it rolls back.
+ *
+ * Drizzle has no such hook, so every database this package opens has its
+ * `transaction` wrapped (`trackCommits`): it gives each transaction a list,
+ * runs the list after COMMIT returns, and drops it on a rollback. A nested
+ * transaction, a savepoint, hands its list to the one around it when it is
+ * released, so nothing runs before the outermost commit.
+ *
+ * The log's append uses it to remember the head it wrote only once that
+ * head is in the database (log.ts).
+ */
+
+type Pending = (() => void)[];
+
+/** What anything that opens transactions looks like, a database or a transaction. */
+type Transactional = { transaction: (...args: never[]) => Promise<unknown> };
+
+const pending = new WeakMap<object, Pending>();
+
+/**
+ * Run `then` once `tx` has committed, all the way out. Returns false, and
+ * never runs it, for a transaction this package did not open.
+ */
+export function afterCommit(tx: object, then: () => void): boolean {
+  const list = pending.get(tx);
+  if (list === undefined) return false;
+  list.push(then);
+  return true;
+}
+
+/** `db`, its transactions tracked for `afterCommit`. */
+export function trackCommits<T extends Transactional>(db: T, outer: Pending | null = null): T {
+  const run = db.transaction.bind(db) as (work: (tx: Transactional) => Promise<unknown>, ...rest: unknown[]) => Promise<unknown>;
+  const transaction = async (work: (tx: Transactional) => Promise<unknown>, ...rest: unknown[]) => {
+    const list: Pending = [];
+    const result = await run((tx) => {
+      pending.set(tx, list);
+      return work(trackCommits(tx, list));
+    }, ...rest);
+    if (outer !== null) outer.push(...list);
+    else for (const then of list) then();
+    return result;
+  };
+  db.transaction = transaction as T['transaction'];
+  return db;
+}

package/src/connect.ts

@@ -0,0 +1,168 @@
+import { resolve } from 'node:path';
+
+import type { Client, ResultSet, Transaction as LibsqlTransaction, TransactionMode } from '@libsql/client';
+import pg from 'pg';
+
+import { createDatabase, type Database } from './database.ts';
+import type { Engine } from './dialect.ts';
+import { asPostgresDatabase } from './portable.ts';
+
+/**
+ * Open a database from its URL, on a Node server:
+ *
+ *   postgres://… or postgresql://…   node-postgres
+ *   file:… or libsql:…                @libsql/client (SQLite)
+ *
+ * The SQLite driver loads only when asked for. The Worker does not
+ * come through here; it builds its Postgres database from the Hyperdrive
+ * pool with createDatabase.
+ */
+export async function openDatabase(url: string): Promise<OpenDatabase> {
+  switch (engineOfUrl(url)) {
+    case 'postgres': {
+      const pool = new pg.Pool({ connectionString: url });
+      return { engine: 'postgres', db: createDatabase(pool), close: () => pool.end() };
+    }
+    case 'sqlite': {
+      const [{ createClient }, { drizzle }, schema] = await Promise.all([
+        import('@libsql/client'),
+        import('drizzle-orm/libsql'),
+        import('./schema.sqlite.ts'),
+      ]);
+      // A lone statement that finds the database locked waits this long.
+      const client = createClient({ url, timeout: 5_000, intMode: 'bigint' });
+      if (url.startsWith('file:')) await client.execute('PRAGMA journal_mode = WAL');
+      const db = drizzle({ client: oneTransactionAtATime(client, writeQueueFor(url)), schema });
+      return { engine: 'sqlite', db: asPostgresDatabase(db), close: async () => client.close() };
+    }
+  }
+}
+
+export type OpenDatabase = { engine: Engine; db: Database; close: () => Promise<void> };
+
+export function engineOfUrl(url: string): Engine {
+  const scheme = url.slice(0, url.indexOf(':'));
+  if (scheme === 'postgres' || scheme === 'postgresql') return 'postgres';
+  if (scheme === 'mysql') throw new Error('coffre supports Postgres; MySQL support was removed');
+  if (scheme === 'file' || scheme === 'libsql') return 'sqlite';
+  throw new Error(`unsupported database URL scheme: ${scheme}:`);
+}
+
+// --- SQLite: one writer at a time ---------------------------------------------------
+
+/**
+ * SQLite lets one connection write at a time and fails the others at once
+ * with SQLITE_BUSY rather than queueing them; 24 concurrent audit appends were
+ * enough to see it. So transactions queue here instead, in the order they
+ * asked, one open at a time per database file, however many clients or
+ * connections reach it. Each begins IMMEDIATE (libsql's default), taking the
+ * write lock with its first statement, which is what makes a read inside it
+ * as good as a locked one (see forUpdate).
+ */
+class WriteQueue {
+  #tail: Promise<void> = Promise.resolve();
+
+  /** Wait for our turn; the returned function ends it. */
+  acquire(): Promise<() => void> {
+    let release!: () => void;
+    const turn = new Promise<void>((done) => (release = done));
+    const ready = this.#tail.then(() => release);
+    this.#tail = this.#tail.then(() => turn);
+    return ready;
+  }
+}
+
+const queues = new Map<string, WriteQueue>();
+
+function writeQueueFor(url: string): WriteQueue {
+  // file:/a.db, file:///a.db and a relative file:a.db from / are one file.
+  const key = url.startsWith('file:') ? resolve(url.replace(/^file:(\/\/)?/, '').split('?')[0]) : url;
+  let queue = queues.get(key);
+  if (queue === undefined) queues.set(key, (queue = new WriteQueue()));
+  return queue;
+}
+
+function oneTransactionAtATime(client: Client, queue: WriteQueue): Client {
+  return new Proxy(client, {
+    get(target, key) {
+      if (key === 'execute') {
+        return async (...args: Parameters<Client['execute']>) => numbers(await target.execute(...args));
+      }
+      if (key === 'transaction') {
+        return async (mode?: TransactionMode) => {
+          const release = await queue.acquire();
+          try {
+            return settling(await target.transaction(mode), release);
+          } catch (error) {
+            release();
+            throw error;
+          }
+        };
+      }
+      if (key === 'batch' || key === 'migrate' || key === 'executeMultiple') {
+        return async (...args: unknown[]) => {
+          const release = await queue.acquire();
+          try {
+            const result = await (target[key] as (...args: unknown[]) => Promise<ResultSet[] | void>)(...args);
+            return result?.map(numbers);
+          } finally {
+            release();
+          }
+        };
+      }
+      const value = Reflect.get(target, key, target);
+      return typeof value === 'function' ? value.bind(target) : value;
+    },
+  });
+}
+
+/** Ends the transaction's turn when it commits, rolls back or closes. */
+function settling(tx: LibsqlTransaction, release: () => void): LibsqlTransaction {
+  let settled = false;
+  const settle = () => {
+    if (settled) return;
+    settled = true;
+    release();
+  };
+  const { commit, rollback, close, execute, batch } = tx;
+  tx.execute = async (...args) => numbers(await execute.apply(tx, args));
+  tx.batch = async (...args) => (await batch.apply(tx, args)).map(numbers);
+  tx.commit = async () => {
+    try {
+      return await commit.call(tx);
+    } finally {
+      settle();
+    }
+  };
+  tx.rollback = async () => {
+    try {
+      return await rollback.call(tx);
+    } finally {
+      settle();
+    }
+  };
+  tx.close = () => {
+    try {
+      close.call(tx);
+    } finally {
+      settle();
+    }
+  };
+  return tx;
+}
+
+/** Keep large counters exact; Drizzle's booleans and dates still need safe numbers. */
+function numbers(result: ResultSet): ResultSet {
+  result.rows = result.rows.map((row) => {
+    // libSQL exposes both named and immutable indexed values on each row.
+    const properties = Object.getOwnPropertyDescriptors(row);
+    for (const property of Object.values(properties)) {
+      const value = property.value;
+      if (typeof value === 'bigint' && value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)) {
+        property.value = Number(value);
+      }
+    }
+    return Object.create(Object.getPrototypeOf(row), properties);
+  });
+  return result;
+}

package/src/database.ts

@@ -0,0 +1,63 @@
+import { getTableName, is, Table } from 'drizzle-orm';
+import { drizzle, type NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type pg from 'pg';
+
+import { trackCommits } from './commits.ts';
+import * as schema from './schema.ts';
+
+export { schema };
+
+/**
+ * A database, typed as Postgres whichever it is; see portable.ts for why
+ * that holds. connect.ts opens one of each from a URL.
+ */
+export type Database = NodePgDatabase<typeof schema>;
+export type Transaction = Parameters<Parameters<Database['transaction']>[0]>[0];
+/** Anything a read can run on: the database, or an open transaction. */
+export type Queryable = Database | Transaction;
+
+/**
+ * What Drizzle needs from a connection pool. A `pg.Pool` fits, and so does the
+ * per-invocation Hyperdrive pool, whose class name ends in `Pool` for the
+ * same reason: that is how Drizzle knows to check out a client for a
+ * transaction rather than run BEGIN on a shared connection.
+ */
+export type PoolLike = pg.Pool | {
+  query: pg.Pool['query'];
+  connect: () => Promise<Pick<pg.PoolClient, 'query'> & { release: () => void }>;
+};
+
+export function createDatabase(pool: PoolLike): Database {
+  return trackCommits(drizzle(pool as pg.Pool, { schema }));
+}
+
+/**
+ * The tables of the database's own dialect: the Postgres ones on Postgres,
+ * the SQLite ones on SQLite. Every query builds on these.
+ */
+export function tablesOf(db: Queryable): typeof schema {
+  return db._.fullSchema;
+}
+
+const byName = new WeakMap<object, Map<string, Table>>();
+
+/**
+ * The database's own twin of `table`, which may be another dialect's: the
+ * server names tables by importing schema.ts, and the database decides
+ * which one that means.
+ */
+export function own<T extends Table>(db: Queryable, table: T): T {
+  const tables = tablesOf(db);
+  let named = byName.get(tables);
+  if (named === undefined) {
+    named = new Map(
+      Object.values(tables)
+        .filter((value) => is(value, Table))
+        .map((value) => [getTableName(value), value]),
+    );
+    byName.set(tables, named);
+  }
+  const found = named.get(getTableName(table));
+  if (found === undefined) throw new Error(`no table ${getTableName(table)} in this database`);
+  return found as T;
+}