@astralarium/repo-postgres 0.0.0-stage → 0.1.0

package/dist/src/schema/module.js

@@ -0,0 +1,122 @@
+/** Schema modules: a package's slice of the app database, loaded after
+ *  the modules it requires. psql runs module SQL from the staged schema
+ *  directory (`@astralarium/repo-postgres/provision` `stageSchema`). */
+import { basename, isAbsolute, resolve } from "node:path";
+import { ExpectedError } from "@astralarium/repo-telemetry";
+import { z } from "zod";
+/** Module and staged directory names. */
+const MODULE_NAME = /^[a-z][a-z0-9_-]*$/;
+const moduleName = z.string().regex(MODULE_NAME, {
+    error: "name must be lowercase letters, digits, - and _",
+});
+const absoluteRoot = z
+    .string()
+    .refine(isAbsolute, { error: "root must be absolute" });
+const sqlPath = z
+    .string()
+    .refine((path) => !isAbsolute(path) && path.endsWith(".sql"), {
+    error: "must be a relative .sql path",
+});
+const relativePath = z
+    .string()
+    .min(1)
+    .refine((path) => !isAbsolute(path), { error: "must be a relative path" });
+const absolutePath = z
+    .string()
+    .refine(isAbsolute, { error: "must be an absolute path" });
+const absoluteSqlPath = z
+    .string()
+    .refine((path) => isAbsolute(path) && path.endsWith(".sql"), {
+    error: "must be an absolute .sql path",
+});
+/** Non-empty strings, e.g. extensions or server arguments. */
+export const stringList = z.array(z.string().min(1)).readonly();
+/** `SchemaModule`'s shape; any installed copy of this package matches. */
+const schemaModule = z.object({
+    name: moduleName,
+    root: absoluteRoot,
+    files: z.array(absoluteSqlPath).readonly(),
+    assets: z.array(absolutePath).readonly(),
+    get requires() {
+        return z.array(schemaModule).readonly();
+    },
+    extensions: stringList,
+    preload: stringList,
+    serverArgs: stringList,
+    beforeReset: absoluteSqlPath.optional(),
+    scrub: absoluteSqlPath.optional(),
+});
+/** A value shaped as `defineSchemaModule` returns. */
+export function isSchemaModule(value) {
+    return schemaModule.safeParse(value).success;
+}
+const declaration = z
+    .object({
+    name: moduleName,
+    root: absoluteRoot,
+    files: z.array(sqlPath).readonly(),
+    assets: z.array(relativePath).readonly().optional(),
+    requires: z
+        .array(z.custom(isSchemaModule, {
+        error: "requires must hold defineSchemaModule results",
+    }))
+        .readonly()
+        .optional(),
+    extensions: stringList.optional(),
+    preload: stringList.optional(),
+    serverArgs: stringList.optional(),
+    beforeReset: sqlPath.optional(),
+    scrub: sqlPath.optional(),
+})
+    .refine(({ files, assets = [] }) => {
+    const paths = [...files, ...assets];
+    return new Set(paths.map((path) => basename(path))).size === paths.length;
+}, { error: "files and assets must have unique basenames" });
+/** A schema module; the declaration is validated (`ExpectedError`). */
+export function defineSchemaModule(module) {
+    const result = declaration.safeParse(module);
+    if (!result.success)
+        throw new ExpectedError(`invalid schema module ${module.name}:\n${z.prettifyError(result.error)}`);
+    const { root } = module;
+    return Object.freeze({
+        name: module.name,
+        root,
+        files: module.files.map((file) => resolve(root, file)),
+        assets: (module.assets ?? []).map((asset) => resolve(root, asset)),
+        requires: [...(module.requires ?? [])],
+        extensions: [...(module.extensions ?? [])],
+        preload: [...(module.preload ?? [])],
+        serverArgs: [...(module.serverArgs ?? [])],
+        ...(module.beforeReset && {
+            beforeReset: resolve(root, module.beforeReset),
+        }),
+        ...(module.scrub && { scrub: resolve(root, module.scrub) }),
+    });
+}
+/**
+ * `modules` and their `requires` closure in load order. One name on two
+ * module objects (two installed copies of a package) is an `ExpectedError`.
+ */
+export function loadOrder(modules) {
+    const order = [];
+    const seen = new Set();
+    // Declarations reference already-defined modules: the graph is acyclic.
+    const visit = (module) => {
+        if (seen.has(module))
+            return;
+        seen.add(module);
+        for (const required of module.requires)
+            visit(required);
+        order.push(module);
+    };
+    for (const module of modules)
+        visit(module);
+    const named = new Map();
+    for (const module of order) {
+        const held = named.get(module.name);
+        if (held)
+            throw new ExpectedError(`schema module ${module.name} is declared twice, from ${held.root} and ${module.root}; install one copy of its package`);
+        named.set(module.name, module);
+    }
+    return order;
+}

package/dist/src/schema/modules.d.ts

@@ -0,0 +1,15 @@
+/** The `app` schema: owned by `app_admin`, used by `app_service`. */
+export declare const appSchema: import("./module.ts").SchemaModule;
+/** pg_partman in schema `partman`, granted to `app_admin`; `reset.sql`
+ *  clears its config for the dropped schemas. */
+export declare const partman: import("./module.ts").SchemaModule;
+/** pg_trgm, for trigram (name) search. */
+export declare const trgm: import("./module.ts").SchemaModule;
+/**
+ * pg_cron on persistent instances, running jobs in `db_template`; job
+ * `cron-history-ttl` deletes run history past 7 days daily.
+ * Disposable instances skip it: its background worker holds
+ * `db_template` open, and test databases clone it as a template, which
+ * needs it idle.
+ */
+export declare const cron: import("./module.ts").SchemaModule;

package/dist/src/schema/modules.js

@@ -0,0 +1,48 @@
+/** The schema modules this package ships: the `app` schema and the
+ *  extensions apps opt into. */
+import { resolve } from "node:path";
+import { packageRoot } from "@astralarium/repo-package-files";
+import { defineSchemaModule } from "./module.js";
+/** This package's SQL. */
+const SQL_DIR = resolve(packageRoot(import.meta.filename), "sql");
+/** The `app` schema: owned by `app_admin`, used by `app_service`. */
+export const appSchema = defineSchemaModule({
+    name: "app",
+    root: resolve(SQL_DIR, "app"),
+    files: ["schema.sql"],
+});
+/** pg_partman in schema `partman`, granted to `app_admin`; `reset.sql`
+ *  clears its config for the dropped schemas. */
+export const partman = defineSchemaModule({
+    name: "partman",
+    root: resolve(SQL_DIR, "extensions/partman"),
+    files: ["schema.sql"],
+    extensions: ["partman"],
+    beforeReset: "before-reset.sql",
+});
+/** pg_trgm, for trigram (name) search. */
+export const trgm = defineSchemaModule({
+    name: "trgm",
+    root: resolve(SQL_DIR, "extensions/trgm"),
+    files: ["schema.sql"],
+});
+/**
+ * pg_cron on persistent instances, running jobs in `db_template`; job
+ * `cron-history-ttl` deletes run history past 7 days daily.
+ * Disposable instances skip it: its background worker holds
+ * `db_template` open, and test databases clone it as a template, which
+ * needs it idle.
+ */
+export const cron = defineSchemaModule({
+    name: "cron",
+    root: resolve(SQL_DIR, "extensions/cron"),
+    files: ["schema.sql"],
+    extensions: ["cron"],
+    preload: ["pg_cron"],
+    serverArgs: [
+        "-c",
+        "cron.database_name=db_template",
+        "-c",
+        "cron.use_background_workers=on",
+    ],
+});

package/dist/src/sql.d.ts

@@ -0,0 +1,83 @@
+import postgres, { type Fragment, type JSONValue, type SerializableParameter, type Sql, type TransactionSql } from "postgres";
+export { type Fragment, type JSONValue, type Sql, type TransactionSql };
+/** Postgres SQLSTATE codes the apps handle
+ *  (https://www.postgresql.org/docs/current/errcodes-appendix.html). */
+export declare const SQLSTATE: {
+    /** `unique_violation`: a unique constraint refused the row. */
+    readonly uniqueViolation: "23505";
+    /** `insufficient_privilege`: the role lacks a privilege. */
+    readonly insufficientPrivilege: "42501";
+    /** `duplicate_database`: `CREATE DATABASE` named an existing database. */
+    readonly duplicateDatabase: "42P04";
+};
+/** One of `SQLSTATE`'s codes. */
+export type Sqlstate = (typeof SQLSTATE)[keyof typeof SQLSTATE];
+/** True when `error` is a Postgres error with SQLSTATE `code`; reads the
+ *  `code` field, so any copy of the Postgres.js package matches. */
+export declare function isSqlstate(error: unknown, code: Sqlstate): boolean;
+/** A pooled client over `connectionString` with `postgres`'s defaults. */
+export declare function sql(connectionString: string): Sql;
+/**
+ * A Durable Object's client, kept across its requests: each connection
+ * closes after `OBJECT_IDLE_S` idle, so an object past its last query
+ * holds none and may hibernate. Hyperdrive owns the real pooling.
+ */
+export declare function objectSql(connectionString: string): Sql;
+/**
+ * Runs `fn` with a one-shot client, closed once `fn` settles. Workers pins
+ * I/O objects to the request that created them, so a Worker's client lives
+ * within its request; Hyperdrive owns the real pooling.
+ */
+export declare function withSql<T>(connectionString: string, fn: (sql: Sql) => Promise<T>): Promise<T>;
+/** Fragment: `ms` milliseconds as an interval. */
+export declare function msInterval(sql: Sql | TransactionSql, ms: number): postgres.PendingQuery<postgres.Row[]>;
+/** A `WHERE` condition; falsy entries drop out of `and`. */
+export type Condition = Fragment | false | "" | 0 | null | undefined;
+/** Fragment: the truthy `conditions`, each parenthesized, joined by `AND`; `TRUE` when none. */
+export declare function and(sql: Sql | TransactionSql, conditions: readonly Condition[]): postgres.PendingQuery<postgres.Row[]> | postgres.Fragment;
+/**
+ * Fragment: `column = value` assignments, comma-separated, for the defined
+ * entries of `columns`; `undefined` leaves a column untouched, `null`
+ * writes NULL. Renders the same wherever it sits in an `UPDATE … SET`.
+ */
+export declare function setDefined(sql: Sql | TransactionSql, columns: Record<string, SerializableParameter | undefined>): postgres.PendingQuery<postgres.Row[]>;
+/** Fragment: the UTC date of `at`. */
+export declare function utcDate(sql: Sql | TransactionSql, at: Date): postgres.PendingQuery<postgres.Row[]>;
+/** A column holding a UUIDv7 id, optionally alias-qualified (`gen.id`):
+ *  read once per row, where a fragment like `uuidv7()` would generate a
+ *  new id at each use. */
+export declare class Column {
+    readonly name: string;
+    constructor(name: string);
+}
+/** `name` as a UUIDv7 id source for `uuidv7Date` and `Uuidv7Key`. */
+export declare function column(name: string): Column;
+/** A UUIDv7 id: a bound value, or a column. */
+export type Uuidv7Id = string | Column;
+/** Fragment: the UTC date of UUIDv7 `id`. */
+export declare function uuidv7Date(sql: Sql | TransactionSql, id: Uuidv7Id): postgres.PendingQuery<postgres.Row[]>;
+/** A UUIDv7 column paired with the date column holding its `uuidv7Date`. */
+export declare class Uuidv7Key {
+    /** UUIDv7 column, optionally alias-qualified (`mp.match_id`). */
+    readonly id: string;
+    /** Date column, optionally alias-qualified (`mp.time_id`). */
+    readonly date: string;
+    constructor(columns: {
+        id: string;
+        date: string;
+    });
+    /** The same columns qualified by table alias `alias`. */
+    in(alias: string): Uuidv7Key;
+    /** Fragment: the column list `id, date`. */
+    columns(sql: Sql | TransactionSql): postgres.PendingQuery<postgres.Row[]>;
+    /** Fragment: the value list for `columns`. */
+    values(sql: Sql | TransactionSql, id: Uuidv7Id): postgres.PendingQuery<postgres.Row[]>;
+    /** Fragment: rows keyed by `id`. */
+    eq(sql: Sql | TransactionSql, id: Uuidv7Id): postgres.PendingQuery<postgres.Row[]>;
+    /** Fragment: rows keyed before `cursor` in v7 order. */
+    before(sql: Sql | TransactionSql, cursor: string): postgres.PendingQuery<postgres.Row[]>;
+    /** Fragment: rows keyed after `cursor` in v7 order. */
+    after(sql: Sql | TransactionSql, cursor: string): postgres.PendingQuery<postgres.Row[]>;
+    /** Fragment: rows whose id timestamp falls in `[since, before)`; the date bounds prune partitions. */
+    createdIn(sql: Sql | TransactionSql, since: Date, before: Date): postgres.PendingQuery<postgres.Row[]>;
+}

package/dist/src/sql.js

@@ -0,0 +1,146 @@
+import postgres from "postgres";
+/** Postgres SQLSTATE codes the apps handle
+ *  (https://www.postgresql.org/docs/current/errcodes-appendix.html). */
+export const SQLSTATE = {
+    /** `unique_violation`: a unique constraint refused the row. */
+    uniqueViolation: "23505",
+    /** `insufficient_privilege`: the role lacks a privilege. */
+    insufficientPrivilege: "42501",
+    /** `duplicate_database`: `CREATE DATABASE` named an existing database. */
+    duplicateDatabase: "42P04",
+};
+/** True when `error` is a Postgres error with SQLSTATE `code`; reads the
+ *  `code` field, so any copy of the Postgres.js package matches. */
+export function isSqlstate(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        error.code === code);
+}
+/** A pooled client over `connectionString` with `postgres`'s defaults. */
+export function sql(connectionString) {
+    return postgres(connectionString);
+}
+/** Seconds an object's idle connection stays open (`objectSql`). */
+const OBJECT_IDLE_S = 10;
+/**
+ * A Durable Object's client, kept across its requests: each connection
+ * closes after `OBJECT_IDLE_S` idle, so an object past its last query
+ * holds none and may hibernate. Hyperdrive owns the real pooling.
+ */
+export function objectSql(connectionString) {
+    return postgres(connectionString, { idle_timeout: OBJECT_IDLE_S });
+}
+/**
+ * Runs `fn` with a one-shot client, closed once `fn` settles. Workers pins
+ * I/O objects to the request that created them, so a Worker's client lives
+ * within its request; Hyperdrive owns the real pooling.
+ */
+export async function withSql(connectionString, fn) {
+    const client = postgres(connectionString, { max: 1 });
+    try {
+        return await fn(client);
+    }
+    finally {
+        await client.end({ timeout: 5 });
+    }
+}
+/** Fragment: `ms` milliseconds as an interval. */
+export function msInterval(sql, ms) {
+    return sql `(${ms}::float8 * interval '1 millisecond')`;
+}
+/** Fragment: the truthy `conditions`, each parenthesized, joined by `AND`; `TRUE` when none. */
+export function and(sql, conditions) {
+    const kept = conditions.filter((c) => !!c);
+    if (kept.length === 0)
+        return sql `TRUE`;
+    return kept
+        .slice(1)
+        .reduce((joined, c) => sql `${joined} AND (${c})`, sql `(${kept[0]})`);
+}
+/**
+ * Fragment: `column = value` assignments, comma-separated, for the defined
+ * entries of `columns`; `undefined` leaves a column untouched, `null`
+ * writes NULL. Renders the same wherever it sits in an `UPDATE … SET`.
+ */
+export function setDefined(sql, columns) {
+    const assignments = Object.entries(columns).flatMap(([column, value]) => value === undefined ? [] : [sql `${sql(column)} = ${value}`]);
+    if (assignments.length === 0) {
+        throw new Error("setDefined: every column is undefined");
+    }
+    return assignments
+        .slice(1)
+        .reduce((list, assignment) => sql `${list}, ${assignment}`, assignments[0]);
+}
+/** Fragment: the UTC date of `at`. */
+export function utcDate(sql, at) {
+    return sql `(${at} AT TIME ZONE 'UTC')::date`;
+}
+/** A column holding a UUIDv7 id, optionally alias-qualified (`gen.id`):
+ *  read once per row, where a fragment like `uuidv7()` would generate a
+ *  new id at each use. */
+export class Column {
+    name;
+    constructor(name) {
+        this.name = name;
+    }
+}
+/** `name` as a UUIDv7 id source for `uuidv7Date` and `Uuidv7Key`. */
+export function column(name) {
+    return new Column(name);
+}
+/** Fragment: `id` as SQL. */
+function idSql(sql, id) {
+    return typeof id === "string" ? sql `${id}` : sql(id.name);
+}
+/** Fragment: the UTC date of UUIDv7 `id`. */
+export function uuidv7Date(sql, id) {
+    return sql `(uuid_extract_timestamp((${idSql(sql, id)})::uuid) AT TIME ZONE 'UTC')::date`;
+}
+/** A UUIDv7 column paired with the date column holding its `uuidv7Date`. */
+export class Uuidv7Key {
+    /** UUIDv7 column, optionally alias-qualified (`mp.match_id`). */
+    id;
+    /** Date column, optionally alias-qualified (`mp.time_id`). */
+    date;
+    constructor(columns) {
+        this.id = columns.id;
+        this.date = columns.date;
+    }
+    /** The same columns qualified by table alias `alias`. */
+    in(alias) {
+        return new Uuidv7Key({
+            id: `${alias}.${this.id}`,
+            date: `${alias}.${this.date}`,
+        });
+    }
+    /** Fragment: the column list `id, date`. */
+    columns(sql) {
+        return sql `${sql(this.id)}, ${sql(this.date)}`;
+    }
+    /** Fragment: the value list for `columns`. */
+    values(sql, id) {
+        return sql `${idSql(sql, id)}, ${uuidv7Date(sql, id)}`;
+    }
+    /** Fragment: rows keyed by `id`. */
+    eq(sql, id) {
+        return sql `${sql(this.id)} = ${idSql(sql, id)}
+      AND ${sql(this.date)} = ${uuidv7Date(sql, id)}`;
+    }
+    /** Fragment: rows keyed before `cursor` in v7 order. */
+    before(sql, cursor) {
+        return sql `${sql(this.id)} < ${cursor}::uuid
+      AND ${sql(this.date)} <= ${uuidv7Date(sql, cursor)}`;
+    }
+    /** Fragment: rows keyed after `cursor` in v7 order. */
+    after(sql, cursor) {
+        return sql `${sql(this.id)} > ${cursor}::uuid
+      AND ${sql(this.date)} >= ${uuidv7Date(sql, cursor)}`;
+    }
+    /** Fragment: rows whose id timestamp falls in `[since, before)`; the date bounds prune partitions. */
+    createdIn(sql, since, before) {
+        return sql `${sql(this.date)} >= ${utcDate(sql, since)}
+      AND ${sql(this.date)} <= ${utcDate(sql, before)}
+      AND uuid_extract_timestamp(${sql(this.id)}) >= ${since}
+      AND uuid_extract_timestamp(${sql(this.id)}) < ${before}`;
+    }
+}

package/dist/testkit/index.d.ts

@@ -0,0 +1,13 @@
+/** Test support: transactions that roll back, and Vitest hooks for
+ *  Postgres.js under workerd. */
+import type { Sql, TransactionSql } from "../src/sql.ts";
+/** Runs `fn` in a transaction that always rolls back; resolves to its result. */
+export declare function rolledBack<T>(sql: Sql, fn: (tx: TransactionSql) => Promise<T>): Promise<T>;
+/** Vitest `onUnhandledError` dropping only Postgres.js's close/read race
+ *  under workerd (https://github.com/porsager/postgres/issues/1196): a
+ *  `read` on a socket the driver already closed. */
+export declare function ignorePostgresCloseRace(error: {
+    name?: string;
+    message: string;
+    stack?: string;
+}): false | undefined;

package/dist/testkit/index.js

@@ -0,0 +1,31 @@
+/** Thrown out of `rolledBack`'s transaction to roll it back. */
+class Rollback extends Error {
+    result;
+    constructor(result) {
+        super("rolledBack: rollback");
+        this.result = result;
+    }
+}
+/** Runs `fn` in a transaction that always rolls back; resolves to its result. */
+export function rolledBack(sql, fn) {
+    return sql
+        .begin(async (tx) => {
+        throw new Rollback(await fn(tx));
+    })
+        .catch((error) => {
+        if (error instanceof Rollback)
+            return error.result;
+        throw error;
+    });
+}
+/** Vitest `onUnhandledError` dropping only Postgres.js's close/read race
+ *  under workerd (https://github.com/porsager/postgres/issues/1196): a
+ *  `read` on a socket the driver already closed. */
+export function ignorePostgresCloseRace(error) {
+    const firstFrame = error.stack?.split("\n")[1]?.trim() ?? "";
+    if (error.name === "TypeError" &&
+        error.message === "This socket has been closed." &&
+        /^at read \(.+\/node_modules\/postgres\/cf\/polyfills\.js(?:\?[^:]*)?:\d+:\d+\)$/.test(firstFrame)) {
+        return false;
+    }
+}

package/dist/testkit/schema.d.ts

@@ -0,0 +1,14 @@
+import type { TestContainer } from "@astralarium/repo-dev";
+import type { SchemaModule } from "../src/schema/module.ts";
+/** The SQL of `module`'s `kind` file; throws when it declares none. */
+export declare function moduleScript(module: SchemaModule, kind: "scrub" | "beforeReset"): string;
+/**
+ * Test: the image's staged `reset.sql` runs unchanged, drops every schema
+ * `app_admin` owns and reloads the app's schema; the staged `scrub.sql`
+ * then runs on the reloaded schema in one transaction, as a snapshot runs
+ * it. Runs on scratch database `app`, a clone of `db_template` granted by
+ * the staged `database-grants.sql`, on the instance of
+ * `adminConnectionString` (a superuser connection); one call per package,
+ * as each package's run owns its instance.
+ */
+export declare function testSchemaReset(adminConnectionString: string, container: TestContainer | undefined): void;

package/dist/testkit/schema.js

@@ -0,0 +1,89 @@
+/** Test support: the image's staged `reset.sql` and `scrub.sql`, run as a
+ *  deploy and a snapshot run them; a module's `scrub` and `beforeReset`
+ *  SQL. */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { ExpectedError } from "@astralarium/repo-telemetry";
+import { expect, it } from "vitest";
+import { withSql } from "../src/sql.js";
+/** Database `reset.sql` connects to. */
+const RESET_DATABASE = "app";
+/** Staged schema directory the image bakes (`container/init`). */
+const STAGED_SCHEMA = "/docker-entrypoint-initdb.d/schema";
+/** The SQL of `module`'s `kind` file; throws when it declares none. */
+export function moduleScript(module, kind) {
+    const file = module[kind];
+    if (!file)
+        throw new Error(`schema module ${module.name} declares no ${kind}`);
+    return readFileSync(file, "utf8");
+}
+/** Schemas `app_admin` owns, sorted. */
+async function ownedSchemas(sql) {
+    const rows = await sql `
+    SELECT nspname FROM pg_namespace
+    WHERE nspowner = to_regrole('app_admin')
+    ORDER BY nspname
+  `;
+    return rows.map(({ nspname }) => nspname);
+}
+/** Runs the staged `file` with psql in `container`, connected to
+ *  `database`, cwd = the staged directory (so `\i` and `\copy` resolve);
+ *  `args` go before the connection options. */
+function psql(container, database, file, ...args) {
+    execFileSync(container.runtime, [
+        "exec",
+        "-i",
+        "-w",
+        STAGED_SCHEMA,
+        "--env",
+        "PGOPTIONS=-c client_min_messages=warning",
+        container.name,
+        "psql",
+        "-X",
+        "-q",
+        "-v",
+        "ON_ERROR_STOP=1",
+        ...args,
+        "-d",
+        database,
+        "-f",
+        file,
+    ], { stdio: ["ignore", "ignore", "inherit"] });
+}
+/**
+ * Test: the image's staged `reset.sql` runs unchanged, drops every schema
+ * `app_admin` owns and reloads the app's schema; the staged `scrub.sql`
+ * then runs on the reloaded schema in one transaction, as a snapshot runs
+ * it. Runs on scratch database `app`, a clone of `db_template` granted by
+ * the staged `database-grants.sql`, on the instance of
+ * `adminConnectionString` (a superuser connection); one call per package,
+ * as each package's run owns its instance.
+ */
+export function testSchemaReset(adminConnectionString, container) {
+    it("a reset drops every schema app_admin owns and reloads the app's schema; the staged scrub.sql runs on it", async () => {
+        if (!container)
+            throw new ExpectedError("testSchemaReset needs a containerized test instance (dbContainer)");
+        const instanceUrl = new URL(adminConnectionString);
+        instanceUrl.pathname = "/postgres";
+        const appUrl = new URL(adminConnectionString);
+        appUrl.pathname = `/${RESET_DATABASE}`;
+        await withSql(instanceUrl.href, async (instance) => {
+            await instance `CREATE DATABASE ${instance(RESET_DATABASE)} TEMPLATE db_template`;
+            try {
+                psql(container, RESET_DATABASE, "database-grants.sql");
+                await withSql(appUrl.href, async (app) => {
+                    const before = await ownedSchemas(app);
+                    expect(before).not.toEqual([]);
+                    // An extra app_admin schema the drop must clear.
+                    await app `CREATE SCHEMA reset_probe AUTHORIZATION app_admin`;
+                    psql(container, "postgres", "reset.sql");
+                    expect(await ownedSchemas(app)).toEqual(before);
+                    psql(container, RESET_DATABASE, "scrub.sql", "--single-transaction");
+                });
+            }
+            finally {
+                await instance `DROP DATABASE ${instance(RESET_DATABASE)} WITH (FORCE)`;
+            }
+        });
+    });
+}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@astralarium/repo-postgres",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "license": "MIT",
+  "homepage": "https://github.com/astralarium/repo/tree/main/packages/repo-postgres#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/astralarium/repo.git",
+    "directory": "packages/repo-postgres"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "container",
+    "scripts",
+    "sql"
+  ],
+  "bin": {
+    "postgres-dump-db": "./scripts/dump-db.sh",
+    "stage-schema": "./dist/bin/stage-schema.js"
+  },
+  "exports": {
+    "./provision": "./dist/src/provision/index.js",
+    "./schema": "./dist/src/schema/index.js",
+    "./sql": "./dist/src/sql.js",
+    "./testkit": "./dist/testkit/index.js",
+    "./testkit/schema": "./dist/testkit/schema.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "postgres": "^3.4.9",
+    "zod": "^4.6.7",
+    "@astralarium/repo-telemetry": "^0.1.0",
+    "@astralarium/repo-package-files": "^0.1.0",
+    "@astralarium/repo-dev": "^0.1.0",
+    "@astralarium/repo-deploy-info": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.2.0",
+    "eslint": "^10.2.1",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.3",
+    "@astralarium/repo-config-eslint": "^0.1.0",
+    "@astralarium/repo-config-typescript": "^0.1.0",
+    "@astralarium/repo-config-vitest": "^0.1.0"
+  },
+  "peerDependencies": {
+    "vitest": "^5.0.3"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24.2"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit && tsc -p tsconfig.build.json --noEmit",
+    "lint": "eslint",
+    "test": "vitest"
+  }
 }