@astralarium/repo-postgres 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Astralarium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,10 @@
-# Temporary Holding Version
+# `@astralarium/repo-postgres`
 
-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.
+Shared Postgres tooling: container images, schema modules, clients.
+
+Roles:
+
+- `app_admin`: schema owner.
+- `app_service`: app service.
+
+Roles are cluster-wide: one app per cluster.

package/container/init/.containerignore

@@ -0,0 +1,2 @@
+*
+!entrypoint.d

package/container/init/Containerfile

@@ -0,0 +1,26 @@
+FROM postgres:18-trixie
+
+# Extension names, space-separated: Debian's postgresql-<major>-<name> packages.
+ARG DB_EXTENSIONS=""
+RUN if [ -n "$DB_EXTENSIONS" ]; then \
+      packages=""; \
+      for name in $DB_EXTENSIONS; do packages="$packages postgresql-${PG_MAJOR}-${name}"; done; \
+      apt-get update \
+      && apt-get install -y --no-install-recommends $packages \
+      && rm -rf /var/lib/apt/lists/*; \
+    fi
+
+# `schemaHash` of the staged schema, this package and DB_EXTENSIONS.
+# The RUN keys the layer cache on it, so each hash gets its own ENV and LABEL.
+ARG DB_SCHEMA
+RUN echo "$DB_SCHEMA" > /etc/db-schema
+ENV DB_SCHEMA=$DB_SCHEMA
+LABEL db.schema=$DB_SCHEMA
+
+WORKDIR /docker-entrypoint-initdb.d
+COPY entrypoint.d/ .
+# Packed packages ship scripts without mode bits.
+RUN chmod 0755 *.sh
+
+# The staged schema: schema.sql beside sql/.
+COPY --from=schema . schema

package/container/init/entrypoint.d/init-db.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# First boot: creates `db_template`, the app roles (schema/roles.sql) and
+# its grants (schema/database-grants.sql), loads the staged schema
+# (schema/schema.sql includes sql/ in order) with schema/ as cwd, then
+# stamps the data directory with the image's DB_SCHEMA.
+
+set -euo pipefail
+
+cd "$( dirname "${BASH_SOURCE[0]}" )"
+
+export PGDATABASE="db_template"
+
+createdb "${PGDATABASE}"
+
+cd schema
+psql -X -v ON_ERROR_STOP=1 --file roles.sql
+psql -X -v ON_ERROR_STOP=1 --file database-grants.sql
+psql -X -v ON_ERROR_STOP=1 --file schema.sql
+
+echo "${DB_SCHEMA}" > /var/lib/postgresql/db-schema

package/container/snapshot/run-snapshot.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# First boot, after init-db.sh: recreates `db_template` with the staged
+# database-grants.sql, loads the dump at /app/data.sql, runs the staged
+# scrub.sql (each module's `scrub`) unless SNAPSHOT_SCRUB=0, then vacuums.
+# Init runs before the server listens: clients only see the scrubbed data.
+
+set -euo pipefail
+
+cd /docker-entrypoint-initdb.d/schema
+
+export PGDATABASE="db_template"
+
+dropdb --force "$PGDATABASE"
+createdb "$PGDATABASE"
+psql -X -v ON_ERROR_STOP=1 --file database-grants.sql
+
+psql -X -v ON_ERROR_STOP=1 --file /app/data.sql
+
+if [[ ${SNAPSHOT_SCRUB:-1} != 0 ]]; then
+  psql -X -v ON_ERROR_STOP=1 --single-transaction --file scrub.sql
+fi
+
+vacuumdb --full --analyze --echo

package/container/util/.containerignore

@@ -0,0 +1,2 @@
+*
+!entrypoint.d

package/container/util/Containerfile

@@ -0,0 +1,7 @@
+# Same base as container/init: pg_dump and psql match the server major.
+FROM postgres:18-trixie
+
+WORKDIR /entrypoint.d
+COPY entrypoint.d/ .
+# Packed packages ship scripts without mode bits.
+RUN chmod 0755 *.sh

package/container/util/entrypoint.d/dump-db.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Data-only dump of the PG* database: the app's rows, excluding extension
+# config tables (the target schema owns its own) and the rows of tables
+# matching DB_DUMP_EXCLUDE (space-separated schema-qualified pg_dump
+# patterns; a partitioned table covers its partitions). The replica role
+# skips triggers and FK checks on load.
+
+set -euo pipefail
+
+read -ra patterns <<< "${DB_DUMP_EXCLUDE:-}"
+excludes=()
+for pattern in ${patterns[@]+"${patterns[@]}"}; do
+    [[ $pattern == *.* ]] || { echo "dump-db: DB_DUMP_EXCLUDE pattern $pattern lacks a schema" >&2; exit 1; }
+    excludes+=("--exclude-table-data-and-children=$pattern")
+done
+
+echo "SET session_replication_role = 'replica';"
+
+pg_dump --data-only --exclude-extension='*' ${excludes[@]+"${excludes[@]}"}

package/container/util/entrypoint.d/upgrade-db.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Loads the PG* source database's data into a db_template clone on the
+# throwaway instance at CONTAINER_PGHOST and prints that clone's full
+# pg_dump. With /app/migrate.d/*.sql, the data comes from a copy of the
+# source those files migrate, in name order. Tables matching
+# DB_DUMP_EXCLUDE keep the clone's seed rows.
+
+set -euo pipefail
+
+CONTAINER_PGHOST=${CONTAINER_PGHOST:?temporary database host}
+
+TEMPLATE_DATABASE=db_template
+UPGRADE_PGDATABASE=db_upgrade
+MIGRATE_PGDATABASE=db_migrate
+
+# Name order, independent of the locale.
+LC_COLLATE=C
+shopt -s nullglob
+migratefiles=(/app/migrate.d/*.sql)
+
+# Runs a client against the throwaway instance's database <db>.
+on_local() {
+    local db=$1
+    shift
+    PGSSLMODE=prefer \
+    PGHOST="$CONTAINER_PGHOST" \
+    PGPORT=5432 \
+    PGUSER=postgres \
+    PGPASSWORD="" \
+    PGDATABASE="$db" \
+    "$@"
+}
+
+# Empties every table of the app_admin-owned schemas in the upgrade db: the
+# template's seed rows give way to the source's data. Tables matching
+# DB_DUMP_EXCLUDE (schema-qualified pg_dump patterns, `*` and `?`
+# wildcards) keep theirs, as the dump skips their rows.
+clear_app_data() {
+    on_local "$UPGRADE_PGDATABASE" psql -X -q -v ON_ERROR_STOP=1 \
+        -v exclude="${DB_DUMP_EXCLUDE:-}" >&2 <<'SQL'
+SET upgrade.dump_exclude = :'exclude';
+-- One pg_dump pattern part as an anchored regex.
+CREATE FUNCTION pg_temp.pattern_regex(part text) RETURNS text
+  LANGUAGE sql IMMUTABLE
+  RETURN '^(' || replace(replace(replace(lower(part), '$', '\$'), '?', '.'), '*', '.*') || ')$';
+DO $$
+DECLARE tables text;
+BEGIN
+  SELECT string_agg(c.oid::regclass::text, ', ') INTO tables
+  FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+  WHERE n.nspowner = 'app_admin'::regrole
+    AND c.relkind IN ('r', 'p')
+    AND NOT EXISTS (SELECT 1 FROM pg_inherits WHERE inhrelid = c.oid)
+    AND NOT EXISTS (
+      SELECT 1
+      FROM regexp_split_to_table(current_setting('upgrade.dump_exclude'), '\s+') AS pattern
+      WHERE pattern <> ''
+        AND n.nspname ~ pg_temp.pattern_regex(split_part(pattern, '.', 1))
+        AND c.relname ~ pg_temp.pattern_regex(
+          substr(pattern, strpos(pattern, '.') + 1))
+    );
+  IF tables IS NOT NULL THEN
+    EXECUTE 'TRUNCATE ' || tables;
+  END IF;
+END $$;
+SQL
+}
+
+while ! on_local postgres pg_isready >&2; do
+    echo "Waiting for local db instance..." >&2
+    sleep 2
+done
+echo "Local db connected!" >&2
+
+if (( ${#migratefiles[@]} )); then
+    echo "Copy remote db into the migration db..." >&2
+    on_local postgres createdb "$MIGRATE_PGDATABASE" >&2
+    # pg_cron loads only via shared_preload_libraries; the throwaway runs stock Postgres.
+    # The copy feeds a data-only dump and migrate files run as `postgres`,
+    # so owners and grants stay out.
+    pg_dump --no-owner --no-privileges --exclude-extension=pg_cron | on_local "$MIGRATE_PGDATABASE" psql -v ON_ERROR_STOP=1 >&2
+
+    for migratefile in "${migratefiles[@]}"; do
+        echo "Migrate: $(basename "$migratefile")..." >&2
+        on_local "$MIGRATE_PGDATABASE" psql -v ON_ERROR_STOP=1 < "$migratefile" >&2
+    done
+fi
+
+echo "Create upgrade db" >&2
+on_local postgres createdb -T "$TEMPLATE_DATABASE" "$UPGRADE_PGDATABASE" >&2
+clear_app_data
+
+echo "Copy data into the upgrade db..." >&2
+if (( ${#migratefiles[@]} )); then
+    on_local "$MIGRATE_PGDATABASE" /entrypoint.d/dump-db.sh
+else
+    /entrypoint.d/dump-db.sh
+fi | on_local "$UPGRADE_PGDATABASE" psql -v ON_ERROR_STOP=1 >&2
+
+echo "Dump upgrade db data" >&2
+echo "SET session_replication_role = 'replica';"
+on_local "$UPGRADE_PGDATABASE" pg_dump
+echo "DONE" >&2

package/dist/bin/stage-schema.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/stage-schema.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/** `stage-schema --app <module> <dir>`: stages the app's schema for psql
+ *  under `<dir>` (`PostgresProvider.stageSchema`). */
+import { appArgs } from "@astralarium/repo-deploy-info/server";
+import { loadDevConfig } from "@astralarium/repo-dev";
+import { ExpectedError, log } from "@astralarium/repo-telemetry";
+const USAGE = "Usage: stage-schema --app <module> <dir>";
+try {
+    const { app, argv } = appArgs(process.argv.slice(2), USAGE, {
+        positionals: 1,
+    });
+    const { database } = await loadDevConfig(app);
+    if (!database || !("stageSchema" in database))
+        throw new ExpectedError(`${app}: dev config declares no Postgres database`);
+    database.stageSchema(argv[0]);
+}
+catch (exception) {
+    log.error("stage_schema.failed", "stage-schema failed", { exception });
+    process.exitCode = 1;
+}

package/dist/src/provision/connection.d.ts

@@ -0,0 +1,11 @@
+/** Preferred published port; a taken one moves to the next free port up. */
+export declare const DEFAULT_PORT = 5432;
+/** The app's login role, as `sql/roles.sql` creates it: non-superuser;
+ *  schema access through grants; `app_admin` inherits it. */
+export declare const APP_SERVICE_ROLE = "app_service";
+/** Local connection as `APP_SERVICE_ROLE`. */
+export declare function appConnectionString(port: number, database: string): string;
+/** Local connection as `postgres`. */
+export declare function adminConnectionString(port: number, database: string): string;
+/** Authenticates through the host port and executes a read-only query. */
+export declare function probePostgres(connectionString: string): Promise<void>;

package/dist/src/provision/connection.js

@@ -0,0 +1,33 @@
+/** Connections to local instances: trust auth on the published loopback port. */
+import postgres from "postgres";
+/** Preferred published port; a taken one moves to the next free port up. */
+export const DEFAULT_PORT = 5432;
+/**
+ * Loopback connection string for a local instance. The containers trust
+ * every connection on their published loopback port; the password is a
+ * placeholder the Cloudflare tooling insists on.
+ */
+function localConnectionString(user, port, database) {
+    return `postgres://${user}:trust@127.0.0.1:${port}/${database}`;
+}
+/** The app's login role, as `sql/roles.sql` creates it: non-superuser;
+ *  schema access through grants; `app_admin` inherits it. */
+export const APP_SERVICE_ROLE = "app_service";
+/** Local connection as `APP_SERVICE_ROLE`. */
+export function appConnectionString(port, database) {
+    return localConnectionString(APP_SERVICE_ROLE, port, database);
+}
+/** Local connection as `postgres`. */
+export function adminConnectionString(port, database) {
+    return localConnectionString("postgres", port, database);
+}
+/** Authenticates through the host port and executes a read-only query. */
+export async function probePostgres(connectionString) {
+    const sql = postgres(connectionString, { max: 1, connect_timeout: 5 });
+    try {
+        await sql `SELECT 1`;
+    }
+    finally {
+        await sql.end({ timeout: 1 });
+    }
+}

package/dist/src/provision/container.d.ts

@@ -0,0 +1,87 @@
+import { type ResourceScope } from "@astralarium/repo-dev";
+/** Image label carrying the `schemaHash()` it was built from. */
+export declare const SCHEMA_LABEL = "db.schema";
+/** Container and volume label naming the checkout that owns it. */
+export declare const OWNER_LABEL = "dev.owner";
+/** `CONTAINER_RUNTIME`, else the first of podman, docker that answers `info`. */
+export declare function detectRuntime(): string;
+/** The container's data was initialised from a schema other than its image's. */
+export declare class StaleSchemaError extends Error {
+    constructor(runtime: string, container: string, stamp: string | null);
+}
+/** Existing container: run state, image ID and labels. */
+interface ContainerState {
+    running: boolean;
+    /** SHA-256 image ID, including the algorithm prefix. */
+    image: string;
+    /** `SCHEMA_LABEL` value; undefined on an unlabeled image. */
+    schema?: string;
+    /** `OWNER_LABEL` value; undefined on an unlabeled container. */
+    owner?: string;
+    /** `ARGS_LABEL` value; undefined on an unlabeled container. */
+    args?: string;
+    /** Requested loopback publish specification. */
+    bindings: {
+        HostIp: string;
+        HostPort: string;
+    }[];
+    /** Mount at the Postgres data directory. */
+    dataMount?: {
+        Type: string;
+        Name?: string;
+        Destination: string;
+    };
+}
+/** One `container inspect`; null for an absent `name`. */
+export declare function inspectContainer(runtime: string, name: string): ContainerState | null;
+/** Persistent data volume of dev instance `name`. */
+export declare function volumeName(name: string): string;
+/** Something holding dev instance `name`: its container or its data volume. */
+interface Holder {
+    kind: "container" | "volume";
+    /** Container or volume name. */
+    name: string;
+    /** `OWNER_LABEL` value; undefined when unlabeled. */
+    owner?: string;
+}
+/** The existing container and data volume of dev instance `name`. */
+export declare function holders(runtime: string, name: string): Holder[];
+/** Container `name` and its data volume are each absent or labeled as
+ *  owned by `owner`, so a volume surviving its container stays with the
+ *  checkout that made it. */
+export declare function claimable(runtime: string, name: string, owner: string): boolean;
+/** `rm -f`; a missing container is fine, any other failure throws. */
+export declare function removeContainer(runtime: string, name: string): void;
+/** `volume rm -f`; a missing volume is fine, any other failure throws. */
+export declare function removeVolume(runtime: string, name: string): void;
+/** Local Postgres instance. */
+interface PostgresContainerOptions {
+    /** Container name. */
+    name: string;
+    /** Immutable image ID from `ensureImage`. */
+    image: string;
+    /** Schema hash of the image. */
+    hash: string;
+    /** Published loopback port; omitted lets the runtime assign one. */
+    port?: number;
+    /** Persistent data volume, created labeled for `owner`; omitted uses the container's disposable storage. */
+    volume?: string;
+    /** Owning checkout, stored as `OWNER_LABEL` on the container and the volume. */
+    owner?: string;
+    /** Postgres server arguments appended to the image command. */
+    serverArgs?: readonly string[];
+    /** Further container labels, applied at creation. */
+    labels?: Readonly<Record<string, string>>;
+}
+/**
+ * Reuses a container of exactly `image`, `owner`, server arguments and
+ * settings, else recreates it (named volumes survive). Resolves once
+ * Postgres accepts connections and the data carries `hash`, with the
+ * published host port. `resources` stops a persistent container this call
+ * started; one already running is left alone. The caller removes an
+ * ephemeral one (`volume` unset).
+ */
+export declare function startPostgresContainer(runtime: string, resources: ResourceScope, { name, image, hash, port, volume, owner, serverArgs, labels, }: PostgresContainerOptions): Promise<{
+    port: number;
+}>;
+export {};

package/dist/src/provision/container.js

@@ -0,0 +1,244 @@
+/** Postgres containers: runtime detection, inspection, startup, readiness. */
+import { execFileSync, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { output, READY_TIMEOUT_MS, succeeds, waitFor, } from "@astralarium/repo-dev";
+import { ExpectedError } from "@astralarium/repo-telemetry";
+/** Image label carrying the `schemaHash()` it was built from. */
+export const SCHEMA_LABEL = "db.schema";
+/** Container and volume label naming the checkout that owns it. */
+export const OWNER_LABEL = "dev.owner";
+/** Container label carrying the sha256 of its Postgres server arguments. */
+const ARGS_LABEL = "db.args";
+/** File the init script writes the image's schema hash to, inside the data volume. */
+const SCHEMA_STAMP = "/var/lib/postgresql/db-schema";
+/** `CONTAINER_RUNTIME`, else the first of podman, docker that answers `info`. */
+export function detectRuntime() {
+    const override = process.env.CONTAINER_RUNTIME;
+    if (override)
+        return override;
+    for (const bin of ["podman", "docker"]) {
+        if (succeeds(bin, ["info"]))
+            return bin;
+    }
+    throw new ExpectedError("neither podman nor docker is running");
+}
+/** Schema hash the container's data was initialised from; null while
+ *  init has yet to complete. */
+function schemaStamp(runtime, container) {
+    return output(runtime, ["exec", container, "cat", SCHEMA_STAMP]);
+}
+/** The container's data was initialised from a schema other than its image's. */
+export class StaleSchemaError extends Error {
+    constructor(runtime, container, stamp) {
+        super(stamp === null
+            ? `${container} has no schema stamp: its first boot is incomplete (see ${runtime} logs ${container}).`
+            : `${container} data was initialised from another schema.`);
+    }
+}
+/** Host port published for Postgres; the container must be running. */
+function publishedPort(runtime, container) {
+    const port = Number(execFileSync(runtime, [
+        "container",
+        "inspect",
+        "-f",
+        '{{(index (index .NetworkSettings.Ports "5432/tcp") 0).HostPort}}',
+        container,
+    ], { encoding: "utf8" }).trim());
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error(`${container} has no published Postgres port: ${port}`);
+    return port;
+}
+/** One `container inspect`; null for an absent `name`. */
+export function inspectContainer(runtime, name) {
+    const state = output(runtime, [
+        "container",
+        "inspect",
+        "-f",
+        "{{json .}}",
+        name,
+    ]);
+    if (state === null)
+        return null;
+    const inspected = JSON.parse(state);
+    const image = inspected.Image;
+    return {
+        running: inspected.State.Running,
+        image: image.startsWith("sha256:") ? image : `sha256:${image}`,
+        schema: inspected.Config.Labels[SCHEMA_LABEL],
+        owner: inspected.Config.Labels[OWNER_LABEL],
+        args: inspected.Config.Labels[ARGS_LABEL],
+        bindings: inspected.HostConfig.PortBindings["5432/tcp"] ?? [],
+        dataMount: inspected.Mounts.find((mount) => mount.Destination === "/var/lib/postgresql"),
+    };
+}
+/** Persistent data volume of dev instance `name`. */
+export function volumeName(name) {
+    return `${name}-data`;
+}
+/** A named volume's `OWNER_LABEL`; null for an absent `name`. */
+function inspectVolume(runtime, name) {
+    const labels = output(runtime, [
+        "volume",
+        "inspect",
+        "-f",
+        "{{json .Labels}}",
+        name,
+    ]);
+    if (labels === null)
+        return null;
+    const parsed = JSON.parse(labels || "null");
+    return { owner: parsed?.[OWNER_LABEL] };
+}
+/** The existing container and data volume of dev instance `name`. */
+export function holders(runtime, name) {
+    const found = [];
+    const container = inspectContainer(runtime, name);
+    if (container)
+        found.push({ kind: "container", name, owner: container.owner });
+    const volume = inspectVolume(runtime, volumeName(name));
+    if (volume)
+        found.push({ kind: "volume", name: volumeName(name), owner: volume.owner });
+    return found;
+}
+/** Container `name` and its data volume are each absent or labeled as
+ *  owned by `owner`, so a volume surviving its container stays with the
+ *  checkout that made it. */
+export function claimable(runtime, name, owner) {
+    return holders(runtime, name).every((holder) => holder.owner === owner);
+}
+/** Creates `volume` labeled for `owner` when absent; one labeled
+ *  otherwise throws, keeping each checkout on its own data. */
+function ensureVolume(runtime, volume, owner) {
+    const current = inspectVolume(runtime, volume);
+    if (current === null) {
+        execFileSync(runtime, [
+            "volume",
+            "create",
+            ...(owner ? ["--label", `${OWNER_LABEL}=${owner}`] : []),
+            volume,
+        ], { stdio: ["ignore", "ignore", "inherit"] });
+        return;
+    }
+    if (current.owner !== owner)
+        throw new ExpectedError(`data volume ${volume} is ${current.owner === undefined ? "unlabeled" : `labeled for ${current.owner}`}; rerun to allocate another instance, or free the name with: ${runtime} volume rm ${volume}`);
+}
+/** `rm -f`; a missing container is fine, any other failure throws. */
+export function removeContainer(runtime, name) {
+    if (inspectContainer(runtime, name) === null)
+        return;
+    execFileSync(runtime, ["rm", "-f", "-v", name], {
+        stdio: ["ignore", "ignore", "inherit"],
+    });
+}
+/** `volume rm -f`; a missing volume is fine, any other failure throws. */
+export function removeVolume(runtime, name) {
+    if (inspectVolume(runtime, name) === null)
+        return;
+    execFileSync(runtime, ["volume", "rm", "-f", name], {
+        stdio: ["ignore", "ignore", "inherit"],
+    });
+}
+/**
+ * Reuses a container of exactly `image`, `owner`, server arguments and
+ * settings, else recreates it (named volumes survive). Resolves once
+ * Postgres accepts connections and the data carries `hash`, with the
+ * published host port. `resources` stops a persistent container this call
+ * started; one already running is left alone. The caller removes an
+ * ephemeral one (`volume` unset).
+ */
+export async function startPostgresContainer(runtime, resources, { name, image, hash, port, volume, owner, serverArgs = [], labels = {}, }) {
+    const args = [
+        ...serverArgs,
+        ...(volume
+            ? []
+            : [
+                "-c",
+                "fsync=off",
+                "-c",
+                "synchronous_commit=off",
+                "-c",
+                "full_page_writes=off",
+            ]),
+    ];
+    const argsHash = createHash("sha256")
+        .update(JSON.stringify(args))
+        .digest("hex");
+    const current = inspectContainer(runtime, name);
+    const reuse = current !== null &&
+        current.schema === hash &&
+        current.image === image &&
+        current.owner === owner &&
+        current.args === argsHash &&
+        current.bindings.length === 1 &&
+        current.bindings[0]?.HostIp === "127.0.0.1" &&
+        (port === undefined || current.bindings[0].HostPort === String(port)) &&
+        (volume
+            ? current.dataMount?.Type === "volume" &&
+                current.dataMount.Name === volume
+            : current.dataMount === undefined);
+    if (!reuse && volume)
+        ensureVolume(runtime, volume, owner);
+    if (current && !reuse)
+        removeContainer(runtime, name);
+    if (!reuse) {
+        execFileSync(runtime, [
+            "create",
+            "--name",
+            name,
+            "--env",
+            "POSTGRES_HOST_AUTH_METHOD=trust",
+            "--env",
+            "PGUSER=postgres",
+            ...(owner ? ["--label", `${OWNER_LABEL}=${owner}`] : []),
+            "--label",
+            `${ARGS_LABEL}=${argsHash}`,
+            ...Object.entries(labels).flatMap(([key, value]) => [
+                "--label",
+                `${key}=${value}`,
+            ]),
+            "--publish",
+            `127.0.0.1:${port ?? ""}:5432`,
+            ...(volume ? ["--volume", `${volume}:/var/lib/postgresql`] : []),
+            image,
+            ...args,
+        ], { stdio: ["ignore", "ignore", "inherit"] });
+    }
+    if (!(reuse && current.running)) {
+        if (volume)
+            resources.own({
+                dispose: () => {
+                    execFileSync(runtime, ["stop", name], { stdio: "ignore" });
+                },
+            });
+        execFileSync(runtime, ["start", name], { stdio: "ignore" });
+    }
+    try {
+        await waitForPostgres(runtime, name, resources.signal);
+    }
+    catch (error) {
+        spawnSync(runtime, ["logs", "--tail", "50", name], { stdio: "inherit" });
+        throw error;
+    }
+    const stamp = schemaStamp(runtime, name);
+    if (stamp !== hash)
+        throw new StaleSchemaError(runtime, name, stamp);
+    return { port: publishedPort(runtime, name) };
+}
+/** Resolves once `pg_isready` succeeds in `container`: init SQL has been applied. */
+function waitForPostgres(runtime, container, signal) {
+    return waitFor(() => {
+        if (succeeds(runtime, [
+            "exec",
+            container,
+            "pg_isready",
+            "-h",
+            "127.0.0.1",
+            "-U",
+            "postgres",
+        ]))
+            return true;
+        if (!inspectContainer(runtime, container)?.running)
+            throw new ExpectedError(`${container} exited during startup. Inspect: ${runtime} logs ${container}`);
+        return false;
+    }, `${container} not ready after ${READY_TIMEOUT_MS}ms. Inspect: ${runtime} logs ${container}`, READY_TIMEOUT_MS, signal);
+}

package/dist/src/provision/data.d.ts

@@ -0,0 +1,8 @@
+/** `data`'s files in load order: each file as given, each directory's
+ *  `*.sql` in name order. */
+export declare function dataFiles(data: readonly string[]): string[];
+/** sha256 over the data files' names and contents, in load order; the
+ *  same across checkouts. */
+export declare function dataDigest(data: readonly string[]): string;
+/** Runs the data files in load order, each as one multi-statement script. */
+export declare function loadData(connectionString: string, data: readonly string[]): Promise<void>;