migrane 0.3.0

package/dist/cli.js

@@ -0,0 +1,167 @@
+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, loadAll, unitsIn } from './discover.js';
+import { reset, resetPlanFrom } from './reset.js';
+import { toConsole, down, status, up } from './runner.js';
+import { Refusal } from './safety.js';
+import { seed, seedStatus, unseed } from './seeds.js';
+import { MigrationChangedError } from './storage.js';
+/**
+ * The command surface. `bin/migrane.js` puts it behind the `migrane`
+ * executable; {@link run} is exported for that file alone, not for the
+ * package — an application that wants these commands under its own runtime
+ * writes its own entry over `migrane/ship`.
+ */
+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.
+ *
+ * A code, never a sentence — what lets a consumer's tooling go fully through
+ * the CLI and still distinguish outcomes by contract instead of matching
+ * stderr:
+ *
+ * | code | meaning                                          |
+ * | ---- | ------------------------------------------------ |
+ * | 0    | ok                                               |
+ * | 1    | failure                                          |
+ * | 2    | refused: a migration changed after it was applied |
+ * | 3    | refused: the guard said no                        |
+ */
+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 }));
+                toConsole.line(`wrote ${to}`);
+                break;
+            }
+            default:
+                console.error(`\n  unknown command: ${command}\n\n${USAGE}\n`);
+                return 1;
+        }
+    }
+    catch (error) {
+        toConsole.line('');
+        console.error(error instanceof Error ? error.message : error);
+        toConsole.line('');
+        // The two refusals a consumer's tooling is entitled to tell apart from a
+        // crash, each behind a class rather than a wording — see the table above.
+        if (error instanceof MigrationChangedError)
+            return 2;
+        if (error instanceof Refusal)
+            return 3;
+        return 1;
+    }
+    return 0;
+};

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+import type { Config } from './types.js';
+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. `defineConfig` lives in `index.ts` rather than here, so
+ * that importing it — which every config file does, and every config file gets
+ * bundled into an image — never drags a directory reader along.
+ *
+ * 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.
+ */
+/**
+ * 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,20 @@
+import type { Driver } from './types.js';
+/**
+ * Reaching a database and letting go of it. The CLI and a container entrypoint
+ * use the same shape, so both open and close a connection the same way.
+ *
+ * There is deliberately no "wait until the database answers" helper here:
+ * waiting is orchestration, and the orchestrator already owns it —
+ * `depends_on: condition: service_healthy` in a compose file says it where a
+ * timeout can be tuned without a release.
+ */
+/**
+ * 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,25 @@
+/**
+ * Reaching a database and letting go of it. The CLI and a container entrypoint
+ * use the same shape, so both open and close a connection the same way.
+ *
+ * There is deliberately no "wait until the database answers" helper here:
+ * waiting is orchestration, and the orchestrator already owns it —
+ * `depends_on: condition: service_healthy` in a compose file says it where a
+ * timeout can be tuned without a release.
+ */
+/**
+ * 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; `createPlans` settles 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; `createPlans` settles 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,62 @@
+import type { Discovered, Migration } 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[];
+/**
+ * Every directory under the seeds root holding something runnable — the seed
+ * half of {@link discover}.
+ *
+ * A unit composes exactly like a directory migration, `index.ts` rule
+ * included. `discover()` cannot find it because that enforces a
+ * `<number>-<slug>` name, and a unit has no number: you pick it by name, so
+ * `sequence` is `0` for all of them. A directory holding nothing runnable is
+ * skipped, as `discover` does.
+ */
+export declare const unitsIn: (dir: string) => Discovered[];
+/**
+ * Loads one discovered migration, composing its parts if it has several.
+ *
+ * `run` rather than `files`: a directory with an `index.ts` runs that one file,
+ * and the rest are its imports. They still count towards the checksum, which is
+ * discovery's business rather than this one's.
+ */
+export declare const load: (entry: Discovered) => Promise<Migration>;
+export declare const loadAll: (entries: readonly Discovered[]) => Promise<Migration[]>;

package/dist/discover.js

@@ -0,0 +1,228 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { basename, extname, join, relative, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { compose, parseSql } from './load.js';
+/**
+ * Everything that reads the source tree: finding migrations and seed units on
+ * disk, putting them in the order they run, and loading what was found. It is
+ * one file so the boundary is one import — the runtime half of the package
+ * (`ship.ts` and below) never touches this, which is what lets it compile for
+ * a target with no filesystem at all.
+ *
+ * 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;
+};
+/**
+ * Every directory under the seeds root holding something runnable — the seed
+ * half of {@link discover}.
+ *
+ * A unit composes exactly like a directory migration, `index.ts` rule
+ * included. `discover()` cannot find it because that enforces a
+ * `<number>-<slug>` name, and a unit has no number: you pick it by name, so
+ * `sequence` is `0` for all of them. A directory holding nothing runnable is
+ * skipped, as `discover` does.
+ */
+export const unitsIn = (dir) => existsSync(dir)
+    ? readdirSync(dir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .flatMap((entry) => {
+        const path = join(dir, entry.name);
+        const files = filesIn(path, true);
+        if (!files.length)
+            return [];
+        const index = indexIn(path, files);
+        return [
+            {
+                name: entry.name,
+                sequence: 0,
+                path,
+                run: index ? [index] : files,
+                files,
+                checksum: checksumOf(files),
+            },
+        ];
+    })
+        .sort((a, b) => a.name.localeCompare(b.name))
+    : [];
+const loadFile = async (file, root) => {
+    const label = relative(root, file) || file;
+    if (extname(file) === '.sql') {
+        return parseSql(readFileSync(file, 'utf8'), label);
+    }
+    // A file URL rather than the path: on Windows a bare absolute path is not a
+    // valid specifier, and this is the one place the package touches the loader.
+    const module = (await import(pathToFileURL(file).href));
+    if (typeof module.up !== 'function') {
+        throw new Error(`${label} does not export an "up" function.`);
+    }
+    return module;
+};
+/**
+ * Loads one discovered migration, composing its parts if it has several.
+ *
+ * `run` rather than `files`: a directory with an `index.ts` runs that one file,
+ * and the rest are its imports. They still count towards the checksum, which is
+ * discovery's business rather than this one's.
+ */
+export const load = async (entry) => {
+    const parts = await Promise.all(entry.run.map((file) => loadFile(file, entry.path)));
+    return {
+        name: entry.name,
+        sequence: entry.sequence,
+        checksum: entry.checksum,
+        module: parts.length === 1 ? parts[0] : compose(parts),
+    };
+};
+export const loadAll = (entries) => Promise.all(entries.map(load));

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;