@astralarium/repo-postgres 0.0.0-stage → 0.2.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,39 @@
-# 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.
+
+```sql
+SELECT slug.slug('Room 52'); -- room-52
+```
+
+```ts
+// app modules: `taskclaimJobs` (requires `taskclaim`, `cron`) deletes expired claims hourly
+postgresDatabase({ modules: [appModule, slug, taskclaimJobs], name: "app-db" });
+```
+
+```ts
+// producer: one message per key per window
+await enqueueClaimed(
+  sql,
+  env.REFRESH,
+  `project:${id}`,
+  { id },
+  { windowSeconds: 300 },
+);
+
+// consumer
+await consumeClaimed(sql, batch, {
+  parse: parseRefreshTask,
+  run: refreshProject,
+  maxRetries: 3, // the consumer's max_retries
+  retryAfterMs: (e) =>
+    e instanceof RetryAfterError ? e.retryAfterMs : undefined,
+});
+```

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 {};