@viktorbarzin/pg 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# @viktorbarzin/pg
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Drizzle on Bun's built-in SQL client for an app on a shared Postgres:
+
+- a pool of at most 4 (`APP_POOL_MAX`; with the realtime LISTEN connection,
+  5 per pod) that reads the password from a mounted file on every new
+  connection, so a rotated password does not break new connections;
+- migrations under a session `pg_advisory_lock` (drizzle's migrator takes
+  none), a migrate CLI for an init container, and throwaway test databases.
+
+<!-- typecheck-preamble
+import { pgTable, text } from "drizzle-orm/pg-core";
+const items = pgTable("items", { title: text("title") });
+const schema = { items };
+-->
+```ts
+import { createPool, migrationLockKey, pgSettingsFromEnv, runMigrateCli } from "@viktorbarzin/pg";
+
+export const pool = createPool({ settings: () => pgSettingsFromEnv(), schema });
+await pool.getDb().select().from(items);
+
+// entrypoints/migrate.ts, bundled with `bun build --target bun`
+process.exitCode = await runMigrateCli({ lockKey: migrationLockKey("myapp") });
+```
+
+| Export | |
+|---|---|
+| `pgSettingsFromEnv(env?)` | `DATABASE_URL` (required) and `DATABASE_PASSWORD_FILE` |
+| `createSqlClient(settings, { max?, idleTimeout? })` | a Bun `SQL` client; idle connections kept by default |
+| `createPool({ settings, schema, key? })` | lazy, once per process: `getDb()`, `getClient()`, `close()` |
+| `migrationLockKey(appName)` | the first 8 bytes of sha256(`migrate:<app>`) as a signed int64 |
+| `runMigrations(client, opts)` | `{ applied }`; the client must have `max: 1`; `beforeMigrate` runs under the lock |
+| `runMigrateCli({ lockKey, beforeMigrate?, env? })` | reads `DATABASE_URL`, `DATABASE_PASSWORD_FILE`, `MIGRATIONS_DIR` (default `./drizzle`); returns the exit code |
+| `@viktorbarzin/pg/testing`: `createTestDatabase`, `migratedTestDatabase` | a randomly named database on `adminUrl`, dropped by `drop()` |
+
+Requires Bun >= 1.4.3. Peers: `drizzle-orm` ^0.45, `@viktorbarzin/log`, `@viktorbarzin/runtime`.

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+import { type Logger } from "@viktorbarzin/log";
+import { SQL } from "bun";
+import { type BunSQLDatabase } from "drizzle-orm/bun-sql";
+export interface PgSettings {
+    /** DATABASE_URL, normally without a password, e.g. `postgres://app@pg-host:5432/app`. */
+    url: string;
+    /** DATABASE_PASSWORD_FILE: a mounted file with the rotated password; null uses the URL's password. */
+    passwordFile: string | null;
+}
+/** ADR budget: 5 connections per pod, one of them the realtime LISTEN. */
+export declare const APP_POOL_MAX = 4;
+/**
+ * The platform env contract the Terraform app module sets: DATABASE_URL
+ * (required) and DATABASE_PASSWORD_FILE.
+ */
+export declare function pgSettingsFromEnv(env?: Record<string, string | undefined>): PgSettings;
+/** The mounted password file's contents, without one trailing newline. */
+export declare function readPasswordFile(path: string): Promise<string>;
+export declare function createSqlClient(settings: PgSettings, opts?: {
+    max?: number;
+    idleTimeout?: number;
+}): SQL;
+export interface Pool<TSchema extends Record<string, unknown>> {
+    getDb(): BunSQLDatabase<TSchema>;
+    getClient(): SQL;
+    close(): Promise<void>;
+}
+/**
+ * The app's pool, once per process (keyed by `key`): lazy, so nothing
+ * connects until the first getDb() or getClient().
+ */
+export declare function createPool<TSchema extends Record<string, unknown>>(opts: {
+    settings: () => PgSettings;
+    schema: TSchema;
+    key?: string;
+}): Pool<TSchema>;
+/** A per-app advisory-lock key: the first 8 bytes of sha256(`migrate:<app>`) as a signed int64. */
+export declare function migrationLockKey(appName: string): bigint;
+export interface MigrateOptions {
+    migrationsFolder: string;
+    lockKey: bigint;
+    migrationsSchema?: string;
+    migrationsTable?: string;
+    /** Runs under the lock, before the migrator (e.g. marking a pulled baseline as applied). */
+    beforeMigrate?: (client: SQL) => Promise<void>;
+    logger?: Logger;
+}
+/**
+ * Run the migrations in `migrationsFolder` under a session advisory lock.
+ * The client must have a pool of exactly one connection, so the lock, the
+ * migrator's transaction and the unlock share one session.
+ */
+export declare function runMigrations(client: SQL, opts: MigrateOptions): Promise<{
+    applied: number;
+}>;
+/**
+ * The migrate entrypoint's body, for an init container or Job:
+ *
+ *   process.exitCode = await runMigrateCli({ lockKey })
+ *
+ * Reads DATABASE_URL, DATABASE_PASSWORD_FILE and MIGRATIONS_DIR (default
+ * ./drizzle). Returns the exit code.
+ */
+export declare function runMigrateCli(opts: {
+    lockKey: bigint;
+    beforeMigrate?: MigrateOptions["beforeMigrate"];
+    env?: Record<string, string | undefined>;
+    logger?: Logger;
+}): Promise<number>;

package/dist/index.js

@@ -0,0 +1,150 @@
+/**
+ * Postgres access for an app on the shared CNPG cluster: Drizzle on Bun's
+ * built-in SQL client (`drizzle-orm/bun-sql`).
+ *
+ * - The password comes from DATABASE_PASSWORD_FILE, read each time a new
+ *   connection opens, so a Vault rotation does not break new connections.
+ * - An app pod keeps at most 5 connections: the pool (APP_POOL_MAX = 4) plus
+ *   the realtime LISTEN connection. The migrate entrypoint uses 1.
+ * - Nothing connects at import time: the first getDb() call opens the pool.
+ * - drizzle-orm's migrator takes no lock of its own, so runMigrations holds a
+ *   session-level pg_advisory_lock around it.
+ */
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { getLogger } from "@viktorbarzin/log";
+import { processSingleton } from "@viktorbarzin/runtime";
+import { SQL } from "bun";
+import { drizzle } from "drizzle-orm/bun-sql";
+import { migrate } from "drizzle-orm/bun-sql/migrator";
+/** ADR budget: 5 connections per pod, one of them the realtime LISTEN. */
+export const APP_POOL_MAX = 4;
+function nonEmpty(value) {
+    return value === undefined || value.trim() === "" ? null : value.trim();
+}
+/**
+ * The platform env contract the Terraform app module sets: DATABASE_URL
+ * (required) and DATABASE_PASSWORD_FILE.
+ */
+export function pgSettingsFromEnv(env = process.env) {
+    const url = nonEmpty(env.DATABASE_URL);
+    if (url === null)
+        throw new Error("DATABASE_URL is not set");
+    return { url, passwordFile: nonEmpty(env.DATABASE_PASSWORD_FILE) };
+}
+/** The mounted password file's contents, without one trailing newline. */
+export async function readPasswordFile(path) {
+    const text = await Bun.file(path).text();
+    return text.replace(/\r?\n$/, "");
+}
+export function createSqlClient(settings, opts = {}) {
+    const { passwordFile } = settings;
+    return new SQL({
+        url: settings.url,
+        max: opts.max ?? APP_POOL_MAX,
+        idleTimeout: opts.idleTimeout ?? 0,
+        ...(passwordFile ? { password: () => readPasswordFile(passwordFile) } : {}),
+    });
+}
+/**
+ * The app's pool, once per process (keyed by `key`): lazy, so nothing
+ * connects until the first getDb() or getClient().
+ */
+export function createPool(opts) {
+    const slot = processSingleton(opts.key ?? "db.pool", () => ({
+        shared: null,
+    }));
+    const open = () => {
+        if (slot.shared === null) {
+            const client = createSqlClient(opts.settings());
+            slot.shared = { client, db: drizzle({ client, schema: opts.schema }) };
+        }
+        return slot.shared;
+    };
+    return {
+        getDb: () => open().db,
+        getClient: () => open().client,
+        async close() {
+            if (slot.shared === null)
+                return;
+            const { client } = slot.shared;
+            slot.shared = null;
+            await client.close();
+        },
+    };
+}
+/** A per-app advisory-lock key: the first 8 bytes of sha256(`migrate:<app>`) as a signed int64. */
+export function migrationLockKey(appName) {
+    const digest = createHash("sha256").update(`migrate:${appName}`).digest();
+    return BigInt.asIntN(64, digest.readBigUInt64BE(0));
+}
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+async function appliedCount(client, schema, table) {
+    const [exists] = await client `
+		select to_regclass(${`"${schema}"."${table}"`}) is not null as found`;
+    if (!exists.found)
+        return 0;
+    const [row] = await client.unsafe(`select count(*)::int as n from "${schema}"."${table}"`);
+    return row.n;
+}
+/**
+ * Run the migrations in `migrationsFolder` under a session advisory lock.
+ * The client must have a pool of exactly one connection, so the lock, the
+ * migrator's transaction and the unlock share one session.
+ */
+export async function runMigrations(client, opts) {
+    const log = opts.logger ?? getLogger("pg.migrate");
+    const schema = opts.migrationsSchema ?? "drizzle";
+    const table = opts.migrationsTable ?? "__drizzle_migrations";
+    if (!IDENTIFIER.test(schema) || !IDENTIFIER.test(table))
+        throw new Error("migrations schema and table must be plain identifiers");
+    log.info("waiting for migration lock", { lock_key: opts.lockKey });
+    await client `select pg_advisory_lock(${opts.lockKey})`;
+    try {
+        if (opts.beforeMigrate)
+            await opts.beforeMigrate(client);
+        const before = await appliedCount(client, schema, table);
+        await migrate(drizzle({ client }), {
+            migrationsFolder: opts.migrationsFolder,
+            migrationsSchema: schema,
+            migrationsTable: table,
+        });
+        const applied = (await appliedCount(client, schema, table)) - before;
+        log.info("migrations complete", { applied });
+        return { applied };
+    }
+    finally {
+        await client `select pg_advisory_unlock(${opts.lockKey})`;
+    }
+}
+/**
+ * The migrate entrypoint's body, for an init container or Job:
+ *
+ *   process.exitCode = await runMigrateCli({ lockKey })
+ *
+ * Reads DATABASE_URL, DATABASE_PASSWORD_FILE and MIGRATIONS_DIR (default
+ * ./drizzle). Returns the exit code.
+ */
+export async function runMigrateCli(opts) {
+    const env = opts.env ?? process.env;
+    const log = opts.logger ?? getLogger("pg.migrate");
+    const folder = resolve(nonEmpty(env.MIGRATIONS_DIR) ?? "drizzle");
+    let client = null;
+    try {
+        client = createSqlClient(pgSettingsFromEnv(env), { max: 1 });
+        await runMigrations(client, {
+            migrationsFolder: folder,
+            lockKey: opts.lockKey,
+            logger: log,
+            ...(opts.beforeMigrate ? { beforeMigrate: opts.beforeMigrate } : {}),
+        });
+        return 0;
+    }
+    catch (err) {
+        log.exception("migration failed", err, { migrations_dir: folder });
+        return 1;
+    }
+    finally {
+        await client?.close().catch(() => { });
+    }
+}

package/dist/testing.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Throwaway Postgres databases for tests. Point `adminUrl` (TEST_DATABASE_URL
+ * by convention) at a server where that role may create databases; each
+ * database gets a random name and is dropped with `drop()`.
+ */
+import { SQL } from "bun";
+export interface TestDatabase {
+    url: string;
+    drop(): Promise<void>;
+}
+export declare function createTestDatabase(opts: {
+    adminUrl: string;
+    prefix?: string;
+}): Promise<TestDatabase>;
+export interface MigratedTestDatabase extends TestDatabase {
+    /** A client on the new database (pool of 2). */
+    client: SQL;
+}
+/** A new database with the app's migrations applied. `drop()` closes the client too. */
+export declare function migratedTestDatabase(opts: {
+    adminUrl: string;
+    migrationsFolder: string;
+    lockKey: bigint;
+    prefix?: string;
+}): Promise<MigratedTestDatabase>;

package/dist/testing.js

@@ -0,0 +1,61 @@
+/**
+ * Throwaway Postgres databases for tests. Point `adminUrl` (TEST_DATABASE_URL
+ * by convention) at a server where that role may create databases; each
+ * database gets a random name and is dropped with `drop()`.
+ */
+import { SQL } from "bun";
+import { runMigrations } from "./index.js";
+const NAME_PREFIX = /^[a-z][a-z0-9_]*$/;
+export async function createTestDatabase(opts) {
+    const prefix = opts.prefix ?? "test";
+    if (!NAME_PREFIX.test(prefix))
+        throw new Error("prefix must be lowercase letters, digits and _");
+    const name = `${prefix}_${crypto.randomUUID().replaceAll("-", "")}`;
+    const admin = new SQL(opts.adminUrl);
+    try {
+        await admin.unsafe(`create database ${name}`);
+    }
+    finally {
+        await admin.close();
+    }
+    const url = new URL(opts.adminUrl);
+    url.pathname = `/${name}`;
+    return {
+        url: url.toString(),
+        async drop() {
+            const cleanup = new SQL(opts.adminUrl);
+            try {
+                await cleanup.unsafe(`drop database if exists ${name} with (force)`);
+            }
+            finally {
+                await cleanup.close();
+            }
+        },
+    };
+}
+/** A new database with the app's migrations applied. `drop()` closes the client too. */
+export async function migratedTestDatabase(opts) {
+    const db = await createTestDatabase({
+        adminUrl: opts.adminUrl,
+        ...(opts.prefix ? { prefix: opts.prefix } : {}),
+    });
+    const migrator = new SQL({ url: db.url, max: 1 });
+    try {
+        await runMigrations(migrator, {
+            migrationsFolder: opts.migrationsFolder,
+            lockKey: opts.lockKey,
+        });
+    }
+    finally {
+        await migrator.close();
+    }
+    const client = new SQL({ url: db.url, max: 2 });
+    return {
+        url: db.url,
+        client,
+        async drop() {
+            await client.close();
+            await db.drop();
+        },
+    };
+}

package/package.json

@@ -1,6 +1,50 @@
 {
-  "name": "@viktorbarzin/pg",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@viktorbarzin/pg",
+	"version": "1.0.0",
+	"description": "Drizzle on Bun SQL: a small pool that re-reads a rotated password file, migrations under an advisory lock, a migrate CLI and throwaway test databases.",
+	"license": "MIT",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./testing": {
+			"types": "./dist/testing.d.ts",
+			"default": "./dist/testing.js"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"sideEffects": false,
+	"engines": {
+		"bun": ">=1.4.3"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ViktorBarzin/app-kit.git",
+		"directory": "packages/pg"
+	},
+	"homepage": "https://github.com/ViktorBarzin/app-kit/tree/master/packages/pg#readme",
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"scripts": {
+		"build": "tsc -b",
+		"test": "bun test"
+	},
+	"peerDependencies": {
+		"@viktorbarzin/log": "^1.0.0",
+		"@viktorbarzin/runtime": "^1.0.0",
+		"drizzle-orm": "^0.45.0"
+	},
+	"devDependencies": {
+		"@viktorbarzin/log": "^1.0.0",
+		"@viktorbarzin/runtime": "^1.0.0",
+		"drizzle-orm": "^0.45.4"
+	}
+}