migrane 1.0.0

package/dist/cli.js

@@ -0,0 +1,149 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { entryFor } from './bundle.js';
+import { findConfig, loadConfig } from './config.js';
+import { withDriver } from './connect.js';
+import { discover } from './discover.js';
+import { loadAll } from './load.js';
+import { reset, resetPlanFrom } from './reset.js';
+import { consoleReporter, down, status, up } from './runner.js';
+import { seed, seedStatus, unitsIn, unseed } from './seeds.js';
+/**
+ * The command surface. `bin/migrane.js` puts it behind the `migrane`
+ * executable, and {@link run} stays exported so an application can wire the
+ * same commands into its own scripts rather than reimplementing argument
+ * handling.
+ */
+const USAGE = [
+    'usage: up | down | status',
+    '       reset | fresh [unit]',
+    '       seed <unit> | unseed <unit>',
+    '       manifest',
+    '',
+    'options: --config <path>   the config to read, instead of looking for one',
+    '         --out <path>      where `manifest` writes',
+].join('\n');
+/** Reads `--name <value>` out of the arguments, leaving the rest in place. */
+const take = (args, name) => {
+    const at = args.indexOf(name);
+    return at === -1 ? undefined : args.splice(at, 2)[1];
+};
+const planOf = async (config) => ({
+    migrations: await loadAll(discover(config.dirs)),
+    table: config.table,
+    before: config.before,
+    guard: config.guard,
+});
+const seedsIn = (config) => {
+    if (!config.seeds)
+        throw new Error('this project declares no "seeds" directory.');
+    return config.seeds;
+};
+/** The seed half of {@link planOf}: read the directory, then load what it found. */
+const seedPlanOf = async (config) => ({
+    units: await loadAll(unitsIn(seedsIn(config))),
+    table: config.seedTable,
+    guard: config.guard,
+});
+/**
+ * Where the manifest goes: what `--out` names, or what the config declares.
+ *
+ * Neither is an error rather than a default, the same way a missing `seeds`
+ * directory is. Two reasons, and the second is the load-bearing one: a path
+ * this package invents is a generated file appearing in somebody's repository
+ * that they never named — and `entryFor` writes every specifier *relative to
+ * the destination*, so guessing where it goes guesses what is in it.
+ *
+ * `--out` resolves against the caller's cwd, because a path someone typed means
+ * what it says from where they typed it. The config's resolves against the
+ * config file, like every other path it declares.
+ */
+const manifestOut = (config, out, cwd) => {
+    if (out)
+        return isAbsolute(out) ? out : resolve(cwd, out);
+    if (config.manifest)
+        return config.manifest;
+    throw new Error('this project declares no "manifest" path. Add one to the config, or name it with --out <path>.');
+};
+const unitArg = (config, given) => {
+    const available = unitsIn(seedsIn(config)).map(({ name }) => name);
+    if (!given) {
+        throw new Error(`no seed unit given. Available: ${available.join(', ') || '(none)'}`);
+    }
+    if (!available.includes(given)) {
+        // A directory holding nothing runnable is not on this list, and that is the
+        // whole of what "unknown" means here — see `unitsIn`.
+        throw new Error(`unknown seed unit "${given}". Available: ${available.join(', ') || '(none)'}`);
+    }
+    return given;
+};
+/**
+ * The exit code is the contract a deploy reads: a one-shot migrate container
+ * that exits non-zero holds the previous release in place rather than starting
+ * a server against a schema that never got written.
+ */
+export const run = async (argv, cwd = process.cwd()) => {
+    const args = [...argv];
+    const explicit = take(args, '--config');
+    const out = take(args, '--out');
+    const [command, argument] = args;
+    if (!command) {
+        console.error(`\n  no command given.\n\n${USAGE}\n`);
+        return 1;
+    }
+    try {
+        const config = await loadConfig(findConfig(cwd, explicit));
+        switch (command) {
+            case 'up':
+                await withDriver(config, async (driver) => up(driver, await planOf(config)));
+                break;
+            case 'down':
+                await withDriver(config, async (driver) => down(driver, await planOf(config)));
+                break;
+            case 'status':
+                await withDriver(config, async (driver) => {
+                    await status(driver, await planOf(config));
+                    if (config.seeds)
+                        await seedStatus(driver, await seedPlanOf(config));
+                });
+                break;
+            case 'reset':
+                await withDriver(config, (driver) => reset(driver, resetPlanFrom(config)));
+                break;
+            case 'fresh':
+                await withDriver(config, async (driver) => {
+                    await reset(driver, resetPlanFrom(config));
+                    await up(driver, await planOf(config));
+                    if (argument) {
+                        await seed(driver, await seedPlanOf(config), unitArg(config, argument));
+                    }
+                });
+                break;
+            case 'seed':
+                await withDriver(config, async (driver) => seed(driver, await seedPlanOf(config), unitArg(config, argument)));
+                break;
+            case 'unseed':
+                await withDriver(config, async (driver) => unseed(driver, await seedPlanOf(config), unitArg(config, argument)));
+                break;
+            // The one command that opens no database: a build runs where there is
+            // nothing to connect to.
+            case 'manifest': {
+                const to = manifestOut(config, out, cwd);
+                mkdirSync(dirname(to), { recursive: true });
+                writeFileSync(to, entryFor({ config, to }));
+                consoleReporter.line(`wrote ${to}`);
+                break;
+            }
+            default:
+                console.error(`\n  unknown command: ${command}\n\n${USAGE}\n`);
+                return 1;
+        }
+    }
+    catch (error) {
+        consoleReporter.line('');
+        console.error(error instanceof Error ? error.message : error);
+        consoleReporter.line('');
+        return 1;
+    }
+    return 0;
+};

package/dist/config.d.ts

@@ -0,0 +1,19 @@
+import type { Config } from './types.js';
+/**
+ * Finding and reading the consumer's config, and resolving everything in it to
+ * an absolute path.
+ *
+ * Paths are resolved against **the config file**, not the working directory, so
+ * `pnpm db:migrate` answers the same from the repository root as from the app.
+ */
+/** Identity, but it types the object literal at the point it is written. */
+export declare const defineConfig: (config: Config) => Config;
+export declare const findConfig: (cwd: string, explicit?: string) => string;
+/** A config with every optional key settled and every path absolute. */
+export interface Resolved extends Config {
+    dirs: string[];
+    table: string;
+    seedTable: string;
+    schema: string;
+}
+export declare const loadConfig: (file: string) => Promise<Resolved>;

package/dist/config.js

@@ -0,0 +1,62 @@
+import { existsSync } from 'node:fs';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { DEFAULTS } from './defaults.js';
+/**
+ * Finding and reading the consumer's config, and resolving everything in it to
+ * an absolute path.
+ *
+ * Paths are resolved against **the config file**, not the working directory, so
+ * `pnpm db:migrate` answers the same from the repository root as from the app.
+ */
+/** Identity, but it types the object literal at the point it is written. */
+export const defineConfig = (config) => config;
+/**
+ * Where the config is looked for, in order.
+ *
+ * `database/config.ts` first because everything a database needs belongs
+ * together in one directory; the `migrate.config.*` names after it, since that
+ * is what a consumer who has never read this will try.
+ */
+const CANDIDATES = [
+    'database/config.ts',
+    'migrate.config.ts',
+    'migrate.config.js',
+    'migrate.config.mjs',
+];
+export const findConfig = (cwd, explicit) => {
+    if (explicit) {
+        const path = isAbsolute(explicit) ? explicit : resolve(cwd, explicit);
+        if (!existsSync(path))
+            throw new Error(`no config at ${path}`);
+        return path;
+    }
+    for (const candidate of CANDIDATES) {
+        const path = resolve(cwd, candidate);
+        if (existsSync(path))
+            return path;
+    }
+    throw new Error(`no migration config found. Looked for ${CANDIDATES.join(', ')} under ${cwd}.`);
+};
+export const loadConfig = async (file) => {
+    const module = (await import(pathToFileURL(file).href));
+    const config = module.default;
+    if (!config)
+        throw new Error(`${file} has no default export.`);
+    if (!config.dirs?.length)
+        throw new Error(`${file} declares no "dirs".`);
+    if (typeof config.driver !== 'function') {
+        throw new Error(`${file} declares no "driver" factory.`);
+    }
+    const base = dirname(file);
+    const at = (path) => (isAbsolute(path) ? path : resolve(base, path));
+    return {
+        ...config,
+        dirs: config.dirs.map(at),
+        seeds: config.seeds ? at(config.seeds) : undefined,
+        manifest: config.manifest ? at(config.manifest) : undefined,
+        table: config.table ?? DEFAULTS.table,
+        seedTable: config.seedTable ?? DEFAULTS.seedTable,
+        schema: config.schema ?? DEFAULTS.schema,
+    };
+};

package/dist/connect.d.ts

@@ -0,0 +1,18 @@
+import type { Driver } from './types.js';
+/**
+ * Wait until the database answers, or fail saying what it answered last.
+ *
+ * Only *reaching* it is bounded: once a migration is running nothing here
+ * interrupts it, because killing the process mid-DDL is worse than any wait.
+ */
+export declare const reachable: (driver: Driver, timeout?: number) => Promise<void>;
+/**
+ * Open a driver, run one thing, close it however that ends.
+ *
+ * A closed driver is what lets a one-shot container exit rather than hang on an
+ * open pool, so there is deliberately no shape in which a caller opens one and
+ * forgets to close it.
+ */
+export declare const withDriver: <T>(config: {
+    driver: () => Driver | Promise<Driver>;
+}, use: (driver: Driver) => Promise<T>) => Promise<T>;

package/dist/connect.js

@@ -0,0 +1,49 @@
+/**
+ * Reaching a database and letting go of it. The CLI and a container entrypoint
+ * use the same two, so both open and close a connection the same way.
+ */
+/**
+ * How long a database gets to answer before this gives up, by default.
+ *
+ * In a compose stack Postgres is a container started alongside this one, and a
+ * driver that retries forever turns a one-shot migrate service into a deploy
+ * that never returns.
+ */
+const TIMEOUT = 120_000;
+/**
+ * Wait until the database answers, or fail saying what it answered last.
+ *
+ * Only *reaching* it is bounded: once a migration is running nothing here
+ * interrupts it, because killing the process mid-DDL is worse than any wait.
+ */
+export const reachable = async (driver, timeout = TIMEOUT) => {
+    const started = Date.now();
+    let last;
+    while (Date.now() - started < timeout) {
+        try {
+            await driver.query('SELECT 1');
+            return;
+        }
+        catch (error) {
+            last = error;
+            await new Promise((resolve) => setTimeout(resolve, 1_000));
+        }
+    }
+    throw new Error(`the database did not answer within ${timeout / 1_000}s — last attempt: ${last instanceof Error ? last.message : String(last)}`);
+};
+/**
+ * Open a driver, run one thing, close it however that ends.
+ *
+ * A closed driver is what lets a one-shot container exit rather than hang on an
+ * open pool, so there is deliberately no shape in which a caller opens one and
+ * forgets to close it.
+ */
+export const withDriver = async (config, use) => {
+    const driver = await config.driver();
+    try {
+        return await use(driver);
+    }
+    finally {
+        await driver.close();
+    }
+};

package/dist/defaults.d.ts

@@ -0,0 +1,22 @@
+/**
+ * What every optional setting falls back to, in one place.
+ *
+ * `config.ts` settles a consumer's file for the CLI; `planFrom`, `seedPlanFrom`
+ * and `resetPlanFrom` settle it for an entrypoint built from a manifest, which
+ * never sees that file. Both read these, because two spellings of one table
+ * name is how an image records migrations where the CLI cannot find them.
+ *
+ * A file of its own rather than a corner of `config.ts`, so the shipped path
+ * can read it without pulling a directory reader into an image that has no
+ * directories to read.
+ */
+export declare const DEFAULTS: {
+    /**
+     * Deploy tooling that reads the database directly — a health check, a ship
+     * script — tends to know this name too, and cannot import it. A consumer that
+     * overrides `table` owns telling every such reader as well.
+     */
+    readonly table: "migrations";
+    readonly seedTable: "seeds";
+    readonly schema: "public";
+};

package/dist/defaults.js

@@ -0,0 +1,22 @@
+/**
+ * What every optional setting falls back to, in one place.
+ *
+ * `config.ts` settles a consumer's file for the CLI; `planFrom`, `seedPlanFrom`
+ * and `resetPlanFrom` settle it for an entrypoint built from a manifest, which
+ * never sees that file. Both read these, because two spellings of one table
+ * name is how an image records migrations where the CLI cannot find them.
+ *
+ * A file of its own rather than a corner of `config.ts`, so the shipped path
+ * can read it without pulling a directory reader into an image that has no
+ * directories to read.
+ */
+export const DEFAULTS = {
+    /**
+     * Deploy tooling that reads the database directly — a health check, a ship
+     * script — tends to know this name too, and cannot import it. A consumer that
+     * overrides `table` owns telling every such reader as well.
+     */
+    table: 'migrations',
+    seedTable: 'seeds',
+    schema: 'public',
+};

package/dist/discover.d.ts

@@ -0,0 +1,42 @@
+import type { Discovered } from './types.js';
+/**
+ * Orders two relative paths segment by segment, comparing leading numbers as
+ * numbers.
+ *
+ * Plain lexicographic ordering would put `10-users` before `9-people`, which
+ * makes correctness depend on remembering to zero-pad. Comparing the number
+ * itself means `9-` and `10-` sort the way they read, and a directory whose
+ * segments are all numbered sorts correctly by path alone.
+ */
+export declare const compareNatural: (a: string, b: string) => number;
+/**
+ * Shared with seed units, which are directories of parts composed exactly like
+ * a directory migration and differ only in being picked by name.
+ */
+export declare const filesIn: (path: string, directory: boolean) => string[];
+/**
+ * Hashes everything the migration would execute — every file of a directory
+ * migration, not only its first. Editing a part has to be as visible as
+ * editing the whole, or the applied-migration check has a hole in it.
+ *
+ * **SHA-256 truncated to sixteen hex characters** — sixty-four bits, and worth
+ * stating because the value is stored in a row per migration and every
+ * consumer's database holds it. The question it answers is *did these bytes
+ * change since they were applied*, not *could someone construct a second file
+ * that hashes the same*, and sixty-four bits settles the first comfortably. It
+ * is short on purpose: a refusal naming it is a line a person has to read.
+ */
+/**
+ * The `index.ts` a directory composes itself with, if it has one. Directly
+ * inside it — one nested deeper is a part like any other.
+ */
+export declare const indexIn: (dir: string, files: readonly string[]) => string | undefined;
+export declare const checksumOf: (files: readonly string[]) => string;
+/**
+ * Every migration across every root, in the order they run: the roots' order,
+ * then the leading number within a root.
+ *
+ * The name is the storage key, so it has to be unique across all of them — the
+ * one thing here that is global rather than local to a directory.
+ */
+export declare const discover: (roots: readonly string[]) => Discovered[];

package/dist/discover.js

@@ -0,0 +1,160 @@
+import { createHash } from 'node:crypto';
+import { readdirSync, readFileSync } from 'node:fs';
+import { basename, extname, join, relative, sep } from 'node:path';
+/**
+ * Finding migrations on disk, and putting them in the order they run.
+ *
+ * One rule at every level: **a leading number orders it, a glob finds it.**
+ * That holds for a migration inside a root and for a part inside a directory
+ * migration, so there is no index file listing parts and no array to remember
+ * to edit — adding a table is adding a file.
+ */
+/** `001-initial`, `20260826143000-add-products`. Both work, and they can mix. */
+const NAMED = /^(\d+)-\S+$/;
+const LEADING = /^(\d+)/;
+const RUNNABLE = new Set(['.ts', '.sql']);
+const stripExtension = (segment) => {
+    const extension = extname(segment);
+    return RUNNABLE.has(extension)
+        ? segment.slice(0, -extension.length)
+        : segment;
+};
+/**
+ * Orders two relative paths segment by segment, comparing leading numbers as
+ * numbers.
+ *
+ * Plain lexicographic ordering would put `10-users` before `9-people`, which
+ * makes correctness depend on remembering to zero-pad. Comparing the number
+ * itself means `9-` and `10-` sort the way they read, and a directory whose
+ * segments are all numbered sorts correctly by path alone.
+ */
+export const compareNatural = (a, b) => {
+    const left = a.split(sep);
+    const right = b.split(sep);
+    for (let index = 0; index < Math.max(left.length, right.length); index++) {
+        const one = left[index];
+        const other = right[index];
+        // The shorter path is a prefix of the longer: a file beside a directory
+        // runs before what is inside it.
+        if (one === undefined)
+            return -1;
+        if (other === undefined)
+            return 1;
+        const first = LEADING.exec(one)?.[1];
+        const second = LEADING.exec(other)?.[1];
+        if (first !== undefined && second !== undefined) {
+            const difference = Number(first) - Number(second);
+            if (difference !== 0)
+                return difference;
+        }
+        // Compared without the extension, so `010-users.ts` sits beside a
+        // `010-users/` directory rather than being ordered against it by `.ts`.
+        // Once they tie, the prefix rule above runs the file before the directory's
+        // contents, which is the order the names were chosen to mean.
+        const difference = stripExtension(one).localeCompare(stripExtension(other));
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+};
+const walk = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory())
+        return walk(path);
+    return RUNNABLE.has(extname(entry.name)) ? [path] : [];
+});
+/**
+ * Shared with seed units, which are directories of parts composed exactly like
+ * a directory migration and differ only in being picked by name.
+ */
+export const filesIn = (path, directory) => directory
+    ? walk(path).sort((a, b) => compareNatural(relative(path, a), relative(path, b)))
+    : [path];
+/**
+ * Hashes everything the migration would execute — every file of a directory
+ * migration, not only its first. Editing a part has to be as visible as
+ * editing the whole, or the applied-migration check has a hole in it.
+ *
+ * **SHA-256 truncated to sixteen hex characters** — sixty-four bits, and worth
+ * stating because the value is stored in a row per migration and every
+ * consumer's database holds it. The question it answers is *did these bytes
+ * change since they were applied*, not *could someone construct a second file
+ * that hashes the same*, and sixty-four bits settles the first comfortably. It
+ * is short on purpose: a refusal naming it is a line a person has to read.
+ */
+/**
+ * The `index.ts` a directory composes itself with, if it has one. Directly
+ * inside it — one nested deeper is a part like any other.
+ */
+export const indexIn = (dir, files) => files.find((file) => file === join(dir, 'index.ts'));
+export const checksumOf = (files) => {
+    const hash = createHash('sha256');
+    for (const file of files)
+        hash.update(readFileSync(file));
+    return hash.digest('hex').slice(0, 16);
+};
+/**
+ * A `.ts`/`.sql` file is one migration; a directory is one migration of parts.
+ *
+ * **An `index.ts` in a directory is the migration.** Given one it is the only
+ * file imported, and the array it composes is the order — data rather than
+ * import order, so it survives an IDE reordering the imports above it.
+ *
+ * Without an index, every runnable file composes in path order and the numbers
+ * carry the dependency order. The choice is per directory: an index earns
+ * itself on a large migration and is ceremony on two files.
+ */
+const inRoot = (root) => readdirSync(root, { withFileTypes: true })
+    .flatMap((entry) => {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) {
+        const files = filesIn(path, true);
+        // A directory holding nothing runnable is a directory, not a migration
+        // someone forgot to fill in — scaffolding a name before writing it is
+        // normal, and refusing that would be refusing work in progress.
+        if (!files.length)
+            return [];
+        const index = indexIn(path, files);
+        return [
+            { name: entry.name, path, run: index ? [index] : files, files },
+        ];
+    }
+    const extension = extname(entry.name);
+    return RUNNABLE.has(extension)
+        ? [
+            {
+                name: basename(entry.name, extension),
+                path,
+                run: [path],
+                files: [path],
+            },
+        ]
+        : [];
+})
+    .sort((a, b) => compareNatural(a.name, b.name));
+/**
+ * Every migration across every root, in the order they run: the roots' order,
+ * then the leading number within a root.
+ *
+ * The name is the storage key, so it has to be unique across all of them — the
+ * one thing here that is global rather than local to a directory.
+ */
+export const discover = (roots) => {
+    const found = roots.flatMap(inRoot).map((entry) => {
+        const sequence = NAMED.exec(entry.name)?.[1];
+        if (sequence === undefined) {
+            // Skipping it would mean a migration that never runs and never says so.
+            throw new Error(`Migration "${entry.name}" must be named <number>-<slug>, e.g. 001-initial or 20260826143000-add-products.`);
+        }
+        return {
+            ...entry,
+            sequence: Number(sequence),
+            checksum: checksumOf(entry.files),
+        };
+    });
+    const duplicate = found.find((entry, index) => found.findIndex((other) => other.name === entry.name) !== index);
+    if (duplicate) {
+        throw new Error(`Two migrations are named "${duplicate.name}". The name is the storage key, so it has to be unique across every root.`);
+    }
+    return found;
+};

package/dist/drivers/pg.d.ts

@@ -0,0 +1,9 @@
+import { type PoolConfig } from 'pg';
+import type { Driver } from '../types.js';
+/**
+ * A driver over a `pg` pool.
+ *
+ * Takes a connection string or a `PoolConfig`, so `pgDriver(process.env.DATABASE_URL)`
+ * is the whole setup for most consumers.
+ */
+export declare const pgDriver: (config: string | PoolConfig) => Driver;

package/dist/drivers/pg.js

@@ -0,0 +1,109 @@
+import { Pool } from 'pg';
+/**
+ * The reference driver, and the shortest statement of what a driver is: three
+ * methods over `node-postgres`, and the host they reach.
+ *
+ * `pg` is an optional peer dependency — importing `migrane` does not reach
+ * it, only importing this file does. A consumer on another client writes sixty
+ * lines like these instead of adopting ours.
+ */
+/**
+ * The simple query protocol answers a multi-statement request with one result
+ * per statement. Rows come from the last of them, which is what a caller
+ * reading `SELECT 1` at the end of a script expects.
+ */
+const rowsOf = (result) => (Array.isArray(result) ? (result.at(-1)?.rows ?? []) : result.rows);
+const queryable = (client) => ({
+    async query(text, values) {
+        // Passing no array at all rather than an empty one: `pg` switches to the
+        // extended protocol the moment values are present, and that protocol
+        // permits exactly one statement per request.
+        const result = values?.length
+            ? await client.query(text, [...values])
+            : await client.query(text);
+        return rowsOf(result);
+    },
+});
+const sessionOver = (client) => ({
+    ...queryable(client),
+    /**
+     * PostgreSQL's spelling of the lock `withLock` asks for. Blocking rather than
+     * `pg_try_advisory_lock`, per the contract on {@link Session.lock}; why it is
+     * session-level is `lock.ts`'s business.
+     */
+    async lock(key, run) {
+        await client.query('SELECT pg_advisory_lock($1)', [key]);
+        try {
+            return await run();
+        }
+        finally {
+            await client.query('SELECT pg_advisory_unlock($1)', [key]);
+        }
+    },
+    async transaction(run) {
+        await client.query('BEGIN');
+        try {
+            const result = await run(queryable(client));
+            await client.query('COMMIT');
+            return result;
+        }
+        catch (error) {
+            // A rollback that itself fails must not replace the error that caused it
+            // — that one is the answer to what went wrong.
+            await client.query('ROLLBACK').catch(() => { });
+            throw error;
+        }
+    },
+});
+/**
+ * Where these coordinates point, read the way `pg` itself reads them.
+ *
+ * It is worth the twenty lines because `Driver.host` is what the destructive
+ * commands refuse on: a host this cannot make out must never come back looking
+ * like `localhost`. So every branch either produces the real host or produces
+ * something that is plainly not this machine — including the last one, which
+ * declines to guess. It also never returns the string it was given, because a
+ * connection string carries a password and this value is printed.
+ */
+const hostOf = (config) => {
+    if (typeof config !== 'string') {
+        return config.connectionString
+            ? hostOf(config.connectionString)
+            : // `pg`'s own precedence, so the guard and the pool cannot disagree: an
+                // omitted host means PGHOST, and then the local socket.
+                (config.host ?? process.env.PGHOST ?? '');
+    }
+    try {
+        // Brackets around an IPv6 address belong to the URL syntax, not to the
+        // address, and `DB_ALLOW_REMOTE` has to be typeable as what is printed.
+        return new URL(config).hostname.replace(/^\[|\]$/g, '');
+    }
+    catch {
+        // The libpq keyword form — `host=db.example.com port=5432 …`. Anything
+        // else is unreadable, and an unreadable host is not this machine.
+        return /(?:^|\s)host=(\S+)/.exec(config)?.[1] ?? 'unknown';
+    }
+};
+/**
+ * A driver over a `pg` pool.
+ *
+ * Takes a connection string or a `PoolConfig`, so `pgDriver(process.env.DATABASE_URL)`
+ * is the whole setup for most consumers.
+ */
+export const pgDriver = (config) => {
+    const pool = new Pool(typeof config === 'string' ? { connectionString: config } : config);
+    return {
+        ...queryable(pool),
+        host: hostOf(config),
+        async session(run) {
+            const client = await pool.connect();
+            try {
+                return await run(sessionOver(client));
+            }
+            finally {
+                client.release();
+            }
+        },
+        close: () => pool.end(),
+    };
+};