@astralarium/repo-postgres 0.0.0-stage → 0.2.0

package/dist/src/provision/image.js

@@ -0,0 +1,159 @@
+/** The app's database image: schema hash, build, selection for test runs. */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { envDbName, output, sourceHash } from "@astralarium/repo-dev";
+import { packageRoot, readPackageManifest, } from "@astralarium/repo-package-files";
+import { ExpectedError } from "@astralarium/repo-telemetry";
+import { z } from "zod";
+import { detectRuntime, SCHEMA_LABEL } from "./container.js";
+import { dataDigest } from "./data.js";
+import { moduleExtensions, schemaDigest, stageSchema } from "./schema.js";
+/** `build-images.sh <runtime> <schema-hash> [db|util|all] [db-iidfile]`. */
+const BUILD_IMAGES = "scripts/build-images.sh";
+/** SQL the image bakes beside the schema: roles, database grants,
+ *  bootstrap, reset, drop. */
+const PACKAGE_SQL = "sql";
+/**
+ * What the package contributes to the image: `name@version` once
+ * installed from a registry; while linked from a workspace (files change
+ * without a version bump), the Git-visible `container/init` and `sql`
+ * sources and the build script.
+ */
+export function packageFingerprint(dir = packageRoot(import.meta.filename)) {
+    const real = realpathSync(dir);
+    if (real.split(sep).includes("node_modules")) {
+        const { name, version } = readPackageManifest(join(real, "package.json"));
+        return `${name}@${version}`;
+    }
+    return sourceHash(real, ["container/init", PACKAGE_SQL, BUILD_IMAGES]);
+}
+/**
+ * sha256 of what the image bakes: the staged schema (`schemaDigest`), the
+ * package fingerprint and the modules' extensions.
+ */
+export function schemaHash(options) {
+    return createHash("sha256")
+        .update(schemaDigest(options.modules))
+        .update(packageFingerprint())
+        .update(extensionList(options))
+        .digest("hex");
+}
+/** `DB_EXTENSIONS` for the image build. */
+function extensionList(options) {
+    return moduleExtensions(options.modules).join(" ");
+}
+/** Runs `build-images.sh` (through bash: packed scripts lose their mode
+ *  bits) with the image base name and `env` added. */
+function runBuildImages(args, name, env = {}) {
+    execFileSync("bash", [join(packageRoot(import.meta.filename), BUILD_IMAGES), ...args], {
+        stdio: "inherit",
+        env: { ...process.env, DB_NAME: name, ...env },
+    });
+}
+/**
+ * Builds database images with `build-images.sh` over a staged copy of the
+ * schema; base-image refresh is explicit.
+ */
+export function buildImages(options, runtime, hash, { target = "all", name, imageIdFile, refreshBase = false, }) {
+    const staged = mkdtempSync(join(tmpdir(), "db-schema-"));
+    try {
+        stageSchema(options.modules, staged);
+        runBuildImages([runtime, hash, target, ...(imageIdFile ? [imageIdFile] : [])], name, {
+            DB_SCHEMA_DIR: staged,
+            DB_EXTENSIONS: extensionList(options),
+            DB_REFRESH_BASE: refreshBase ? "true" : "",
+        });
+    }
+    finally {
+        rmSync(staged, { recursive: true, force: true });
+    }
+}
+/**
+ * Reuses the schema-tagged local image or builds it; returns its immutable
+ * ID. A reused image is retagged `<name>:latest`, as a build tags it.
+ */
+export function ensureImage(options, runtime, hash, name) {
+    const cached = output(runtime, [
+        "image",
+        "inspect",
+        "-f",
+        `{{.Id}}\t{{index .Config.Labels "${SCHEMA_LABEL}"}}`,
+        `${name}:${hash}`,
+    ]);
+    if (cached) {
+        const [id, schema] = cached.split("\t");
+        if (id && schema === hash) {
+            const image = id.startsWith("sha256:") ? id : `sha256:${id}`;
+            execFileSync(runtime, ["tag", image, `${name}:latest`]);
+            return image;
+        }
+    }
+    const dir = mkdtempSync(join(tmpdir(), "db-image-"));
+    try {
+        const imageIdFile = join(dir, "id");
+        buildImages(options, runtime, hash, { target: "db", name, imageIdFile });
+        return readFileSync(imageIdFile, "utf8").trim();
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/** Builds `<name>-util:latest` from the package's util sources
+ *  (layer-cached) and returns the tag. */
+export function ensureUtilImage(runtime, name) {
+    runBuildImages([runtime, "", "util"], name);
+    return `${name}-util:latest`;
+}
+/** Selects the schema image, tagged `name`, and records its immutable ID,
+ *  runtime and data digest. */
+export function prepareTestImage(options, name = options.name) {
+    const runtime = detectRuntime();
+    const hash = schemaHash(options);
+    return {
+        name: options.name,
+        runtime,
+        image: ensureImage(options, runtime, hash, name),
+        hash,
+        data: dataDigest(options.data ?? []),
+        host: `${process.version}/${process.platform}/${process.arch}`,
+    };
+}
+/** Publishes the manifest of the image tagged `envDbName` at `file`,
+ *  replacing it whole. */
+export function writeTestImage(options, file) {
+    const image = prepareTestImage(options, envDbName(options));
+    const path = fileURLToPath(file);
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = `${path}.${process.pid}.tmp`;
+    writeFileSync(temp, JSON.stringify(image) + "\n");
+    renameSync(temp, path);
+}
+const SHA256 = /^[a-f0-9]{64}$/;
+const testImageManifest = z.object({
+    name: z.string(),
+    runtime: z.string(),
+    image: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    hash: z.string().regex(SHA256),
+    data: z.string().regex(SHA256),
+    host: z.string(),
+});
+/** Reads a prepared database-image manifest; a malformed one is an
+ *  `ExpectedError`. */
+export function readTestImage(path) {
+    const text = readFileSync(path, "utf8");
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        value = undefined;
+    }
+    const result = testImageManifest.safeParse(value);
+    if (!result.success)
+        throw new ExpectedError(`${path}: invalid prepared test image; run the app's db:image task to regenerate it`);
+    return result.data;
+}

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

@@ -0,0 +1,17 @@
+import { type DatabaseProvider } from "@astralarium/repo-dev";
+import type { PostgresOptions } from "./options.ts";
+import { type PostgresTestDatabase } from "./test-database.ts";
+export { APP_SERVICE_ROLE } from "./connection.ts";
+export { ensureUtilImage } from "./image.ts";
+export type { PostgresOptions } from "./options.ts";
+export type { PostgresTestDatabase } from "./test-database.ts";
+/** The app's Postgres, as `DevConfig.database` and `TestApp.database` take it. */
+export interface PostgresProvider extends DatabaseProvider<PostgresTestDatabase> {
+    /**
+     * Writes the staged schema directory under `dir`, as the image bakes it
+     * (`stageSchema`).
+     */
+    stageSchema(dir: string): void;
+}
+/** The app's Postgres provider; the declaration is validated (`ExpectedError`). */
+export declare function postgresDatabase(options: PostgresOptions): PostgresProvider;

package/dist/src/provision/index.js

@@ -0,0 +1,205 @@
+/**
+ * Postgres as a `DatabaseProvider`: the app's schema image, one persistent
+ * container per checkout for dev, a disposable one per test run.
+ */
+import { isAbsolute } from "node:path";
+import { keepOrFindPort, RESOURCE_NAME, succeeds, } from "@astralarium/repo-dev";
+import { ExpectedError, log } from "@astralarium/repo-telemetry";
+import { z } from "zod";
+import { isSchemaModule, loadOrder, stringList, } from "../schema/module.js";
+import { adminConnectionString, APP_SERVICE_ROLE, appConnectionString, DEFAULT_PORT, probePostgres, } from "./connection.js";
+import { claimable, detectRuntime, holders, inspectContainer, OWNER_LABEL, removeContainer, removeVolume, StaleSchemaError, startPostgresContainer, volumeName, } from "./container.js";
+import { loadData } from "./data.js";
+import { checkDumpExclude, migrationMounts, requireFile, runDisposableServer, runUpgradeDump, } from "./disposable.js";
+import { buildImages, ensureImage, ensureUtilImage, schemaHash, writeTestImage, } from "./image.js";
+import { moduleServerArgs, stageSchema } from "./schema.js";
+import { startTestInstance, } from "./test-database.js";
+export { APP_SERVICE_ROLE } from "./connection.js";
+export { ensureUtilImage } from "./image.js";
+/** Container names tried per base: `<base>`, `<base>-2`, … */
+const NAME_ATTEMPTS = 100;
+const postgresOptions = z.object({
+    modules: z
+        .array(z.custom(isSchemaModule, {
+        error: "modules must hold defineSchemaModule results",
+    }))
+        .min(1, { error: "modules lists no schema module" })
+        .readonly()
+        .check((ctx) => {
+        try {
+            loadOrder(ctx.value);
+        }
+        catch (cause) {
+            ctx.issues.push({
+                code: "custom",
+                input: ctx.value,
+                message: cause instanceof Error ? cause.message : String(cause),
+            });
+        }
+    }),
+    name: z.string().regex(RESOURCE_NAME, {
+        error: "name must be a container resource name",
+    }),
+    serverArgs: stringList.optional(),
+    ephemeralArgs: stringList.optional(),
+    data: z
+        .array(z.string().refine(isAbsolute, { error: "data paths must be absolute" }))
+        .readonly()
+        .optional(),
+});
+class Postgres {
+    name;
+    #options;
+    #runtime;
+    constructor(options) {
+        this.#options = options;
+        this.name = options.name;
+    }
+    /** Detected once per process. */
+    get runtime() {
+        return (this.#runtime ??= detectRuntime());
+    }
+    async allocate({ base, owner, saved, }) {
+        const runtime = this.runtime;
+        const names = [
+            base,
+            ...Array.from({ length: NAME_ATTEMPTS - 1 }, (_, i) => `${base}-${i + 2}`),
+        ];
+        const name = [
+            ...new Set([
+                ...(saved.name && names.includes(saved.name) ? [saved.name] : []),
+                ...names,
+            ]),
+        ].find((candidate) => claim(runtime, candidate, owner));
+        if (!name)
+            throw new ExpectedError(`no free container name from ${base} to ${names.at(-1)}`);
+        // A claimable container is this checkout's: a running one keeps its port.
+        const container = inspectContainer(runtime, name);
+        const port = container?.running && container.bindings[0]?.HostPort
+            ? Number(container.bindings[0].HostPort)
+            : await keepOrFindPort(saved.port, DEFAULT_PORT);
+        return { name, port };
+    }
+    async ensure(resources, { allocation: { name, port }, image, owner, program, }) {
+        const options = this.#options;
+        const runtime = this.runtime;
+        const hash = schemaHash(options);
+        const resetHint = `${program} reset --db-name ${image} recreates it; this deletes local data.`;
+        try {
+            await startPostgresContainer(runtime, resources, {
+                name,
+                image: ensureImage(options, runtime, hash, image),
+                hash,
+                port,
+                volume: volumeName(name),
+                owner,
+                serverArgs: [
+                    ...moduleServerArgs(options.modules),
+                    ...(options.serverArgs ?? []),
+                ],
+            });
+        }
+        catch (cause) {
+            if (cause instanceof StaleSchemaError)
+                throw new ExpectedError(`${cause.message} ${resetHint}`, { cause });
+            throw cause;
+        }
+        try {
+            await probePostgres(appConnectionString(port, "db_template"));
+        }
+        catch (cause) {
+            throw new ExpectedError(`${name}: ${APP_SERVICE_ROLE} cannot connect to db_template with the dev credentials. Inspect the database, or ${resetHint}`, { cause });
+        }
+        await loadData(adminConnectionString(port, "db_template"), options.data ?? []);
+        log.info("dev.db_ready", "{name}: ready on :{port}", { name, port });
+    }
+    reset(name, image) {
+        removeContainer(this.runtime, name);
+        removeVolume(this.runtime, volumeName(name));
+        this.build(image);
+    }
+    stop(name, owner) {
+        let runtime;
+        try {
+            runtime = this.runtime;
+        }
+        catch {
+            return;
+        }
+        if (claimable(runtime, name, owner))
+            succeeds(runtime, ["stop", name]);
+    }
+    build(image) {
+        buildImages(this.#options, this.runtime, schemaHash(this.#options), {
+            name: image,
+            refreshBase: true,
+        });
+    }
+    async runDisposable({ allocation, image, serverArgs, snapshot, signal, }) {
+        if (snapshot)
+            requireFile(snapshot.dump);
+        await runDisposableServer(this.runtime, {
+            name: `${allocation.name}-${snapshot ? "snapshot" : "temp"}`,
+            image: this.#image(image),
+            port: await keepOrFindPort(undefined, DEFAULT_PORT, new Set([allocation.port])),
+            serverArgs,
+            snapshot,
+            signal,
+        });
+    }
+    async upgradeDump({ allocation, image, migrations, signal, }) {
+        const mounts = migrationMounts(migrations);
+        // eslint-disable-next-line turbo/no-undeclared-env-vars -- no turbo task runs this CLI
+        checkDumpExclude(process.env.DB_DUMP_EXCLUDE);
+        await runUpgradeDump(this.runtime, {
+            name: `${allocation.name}-upgrade`,
+            image: this.#image(image),
+            util: ensureUtilImage(this.runtime, image),
+            mounts,
+            signal,
+        });
+    }
+    /** This checkout's schema image under base name `image`, built when
+     *  missing: its immutable ID. */
+    #image(image) {
+        return ensureImage(this.#options, this.runtime, schemaHash(this.#options), image);
+    }
+    connectionString({ port }) {
+        return appConnectionString(port, "db_template");
+    }
+    startTestInstance(resources, name) {
+        return startTestInstance(resources, name, this.#options);
+    }
+    writeTestImage(file) {
+        writeTestImage(this.#options, file);
+    }
+    stageSchema(dir) {
+        stageSchema(this.#options.modules, dir);
+    }
+}
+/**
+ * `claimable`, naming each holder of `name` lacking `OWNER_LABEL` (a
+ * container or data volume) and the command freeing it: that holder keeps
+ * the name and its port from every checkout.
+ */
+function claim(runtime, name, owner) {
+    const held = holders(runtime, name);
+    if (held.every((holder) => holder.owner === owner))
+        return true;
+    for (const holder of held)
+        if (holder.owner === undefined)
+            log.warn("dev.db_name_held", "{kind, select, volume {Data volume} other {Container}} {name} carries no {label} label, so this checkout skips the name; free it with: {remove}", {
+                kind: holder.kind,
+                name: holder.name,
+                label: OWNER_LABEL,
+                remove: `${runtime} ${holder.kind === "volume" ? "volume rm" : "rm -f"} ${holder.name}`,
+            });
+    return false;
+}
+/** The app's Postgres provider; the declaration is validated (`ExpectedError`). */
+export function postgresDatabase(options) {
+    const result = postgresOptions.safeParse(options);
+    if (!result.success)
+        throw new ExpectedError(`invalid Postgres options:\n${z.prettifyError(result.error)}`);
+    return new Postgres(options);
+}

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

@@ -0,0 +1,23 @@
+import type { SchemaModule } from "../schema/module.ts";
+/** What an app declares for its Postgres image and local instances. */
+export interface PostgresOptions {
+    /**
+     * The app's schema modules; their `requires` load too. Files hash into
+     * the image tag; extensions install in the image; `preload` and
+     * `serverArgs` reach the dev instance.
+     */
+    modules: readonly SchemaModule[];
+    /** Image and instance base name; `DB_NAME` and `--db-name` override it. */
+    name: string;
+    /** Postgres server arguments for the dev instance, after the modules'. */
+    serverArgs?: readonly string[];
+    /** Postgres server arguments for disposable (test) instances; stock Postgres by default. */
+    ephemeralArgs?: readonly string[];
+    /**
+     * Data SQL after the schema: absolute `.sql` files, or directories whose
+     * `*.sql` run in name order. Loads into `db_template` on every dev start
+     * and once per test run, before project databases clone it; idempotent.
+     * Its digest joins the test image manifest.
+     */
+    data?: readonly string[];
+}

package/dist/src/provision/options.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,11 @@
+import { type SchemaModule } from "../schema/module.ts";
+/** sha256 over the staged psql entries, then the module file, asset,
+ *  `beforeReset` and `scrub` paths and contents, in load order. */
+export declare function schemaDigest(modules: readonly SchemaModule[]): string;
+/** Extensions every module installs, deduplicated in load order. */
+export declare function moduleExtensions(modules: readonly SchemaModule[]): string[];
+/** Persistent-instance server arguments: one `shared_preload_libraries`
+ *  over every module's `preload`, then each module's `serverArgs`. */
+export declare function moduleServerArgs(modules: readonly SchemaModule[]): string[];
+/** Writes the staged directory under `dir`, creating it. */
+export declare function stageSchema(modules: readonly SchemaModule[], dir: string): void;

package/dist/src/provision/schema.js

@@ -0,0 +1,134 @@
+/**
+ * The app's schema modules as psql loads them: a staged directory holding
+ * `schema.sql` (one `\i sql/<module>/<file>` per module file, in load
+ * order) beside `sql/` (each module's files and assets),
+ * `before-reset.sql` and `before-reset/` (each module's `beforeReset`),
+ * `scrub.sql` and `scrub/` (each module's `scrub`), and this package's
+ * `roles.sql`, `database-grants.sql`, `bootstrap.sql`, `reset.sql` and
+ * `drop-schemas.sql`. psql runs every entry with this directory as cwd.
+ * The image bakes it and runs `roles.sql`, `database-grants.sql`, then
+ * `schema.sql`, at first boot.
+ */
+import { createHash } from "node:crypto";
+import { copyFileSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { packageRoot } from "@astralarium/repo-package-files";
+import { ExpectedError } from "@astralarium/repo-telemetry";
+import { loadOrder } from "../schema/module.js";
+/** Entry psql runs from the staged directory. */
+const SCHEMA_ENTRY = "schema.sql";
+/** Directory of the staged module files, beside the entry. */
+const SCHEMA_FILES = "sql";
+/** Entry `reset.sql` runs ahead of its drop. */
+const BEFORE_RESET_ENTRY = "before-reset.sql";
+/** Directory of the staged `beforeReset` files. */
+const BEFORE_RESET_FILES = "before-reset";
+/** Entry a snapshot runs after its dump loads. */
+const SCRUB_ENTRY = "scrub.sql";
+/** Directory of the staged `scrub` files. */
+const SCRUB_FILES = "scrub";
+/** Each module's `files` or `assets` in load order, under `sql/<module>/`. */
+function moduleFiles(order, kind) {
+    return order.flatMap((module) => module[kind].map((path) => ({
+        staged: `${SCHEMA_FILES}/${module.name}/${basename(path)}`,
+        path,
+    })));
+}
+/** Each module's `beforeReset` or `scrub` in load order, as
+ *  `<dir>/<module>.sql`. */
+function moduleScripts(order, kind, dir) {
+    return order.flatMap((module) => {
+        const path = module[kind];
+        return path ? [{ staged: `${dir}/${module.name}.sql`, path }] : [];
+    });
+}
+/** Every staged module file, asset, `beforeReset` and `scrub` file, in load
+ *  order. */
+function stagedFiles(order) {
+    return [
+        ...moduleFiles(order, "files"),
+        ...moduleFiles(order, "assets"),
+        ...moduleScripts(order, "beforeReset", BEFORE_RESET_FILES),
+        ...moduleScripts(order, "scrub", SCRUB_FILES),
+    ];
+}
+/** psql entry including `files` in order. */
+function entry(header, files) {
+    return [header, ...files.map((file) => `\\i ${file.staged}`), ""].join("\n");
+}
+/** Staged psql entries as `[file name, text]`. */
+function entries(order) {
+    return [
+        [
+            SCHEMA_ENTRY,
+            entry("-- Schema load order, staged by @astralarium/repo-postgres from the app's schema modules.\n-- Run connected to the app database, after roles.sql and database-grants.sql.", moduleFiles(order, "files")),
+        ],
+        [
+            BEFORE_RESET_ENTRY,
+            entry("-- Each schema module's beforeReset in load order, staged by @astralarium/repo-postgres.\n-- Run by reset.sql as app_admin, inside its transaction.", moduleScripts(order, "beforeReset", BEFORE_RESET_FILES)),
+        ],
+        [
+            SCRUB_ENTRY,
+            entry("-- Each schema module's scrub in load order, staged by @astralarium/repo-postgres.\n-- Run by run-snapshot as superuser in db_template, inside one transaction.", moduleScripts(order, "scrub", SCRUB_FILES)),
+        ],
+    ];
+}
+/** The file's contents; a missing file names the path and its likely cause. */
+function readSchemaFile({ path }) {
+    try {
+        return readFileSync(path);
+    }
+    catch (cause) {
+        throw new ExpectedError(`schema file ${path} is missing: check the module declaring it, or install the package providing it`, { cause });
+    }
+}
+/** sha256 over the staged psql entries, then the module file, asset,
+ *  `beforeReset` and `scrub` paths and contents, in load order. */
+export function schemaDigest(modules) {
+    const order = loadOrder(modules);
+    const hash = createHash("sha256");
+    for (const [name, text] of entries(order)) {
+        hash.update(`${name}\0`);
+        hash.update(text);
+        hash.update("\0");
+    }
+    for (const file of stagedFiles(order)) {
+        hash.update(`${file.staged}\0`);
+        hash.update(readSchemaFile(file));
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}
+/** Extensions every module installs, deduplicated in load order. */
+export function moduleExtensions(modules) {
+    return [
+        ...new Set(loadOrder(modules).flatMap((module) => module.extensions)),
+    ];
+}
+/** Persistent-instance server arguments: one `shared_preload_libraries`
+ *  over every module's `preload`, then each module's `serverArgs`. */
+export function moduleServerArgs(modules) {
+    const order = loadOrder(modules);
+    const preload = [...new Set(order.flatMap((module) => module.preload))];
+    return [
+        ...(preload.length
+            ? ["-c", `shared_preload_libraries=${preload.join(",")}`]
+            : []),
+        ...order.flatMap((module) => module.serverArgs),
+    ];
+}
+/** Writes the staged directory under `dir`, creating it. */
+export function stageSchema(modules, dir) {
+    const order = loadOrder(modules);
+    for (const file of stagedFiles(order)) {
+        const target = join(dir, file.staged);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, readSchemaFile(file));
+    }
+    for (const [name, text] of entries(order))
+        writeFileSync(join(dir, name), text);
+    const scripts = join(packageRoot(import.meta.filename), "sql");
+    for (const name of readdirSync(scripts))
+        if (name.endsWith(".sql"))
+            copyFileSync(join(scripts, name), join(dir, name));
+}

package/dist/src/provision/test-database.d.ts

@@ -0,0 +1,29 @@
+import { type ResourceScope, type TestContainer, type TestDatabase } from "@astralarium/repo-dev";
+import type { PostgresOptions } from "./options.ts";
+/** Running seeded instance; fixtures may run tools in its container or network namespace. */
+export declare class PostgresTestDatabase implements TestDatabase {
+    /** Published loopback port. */
+    readonly port: number;
+    /** Container running the instance; other containers join its network
+     *  namespace. */
+    readonly container: TestContainer;
+    constructor(instance: {
+        port: number;
+        container: TestContainer;
+    });
+    /**
+     * `CREATE DATABASE … TEMPLATE db_template`; returns the `app_service`
+     * connection. A project whose name maps to an existing database is an
+     * `ExpectedError`.
+     */
+    createDatabase(name: string): Promise<string>;
+    /** `postgres` connection to the project database. */
+    adminConnectionString(name: string): string;
+}
+/**
+ * Sweeps stale test containers (`sweepTestInstances`), then starts
+ * `db-test-<name>-<uuid>`, labeled with this process's pid, on an assigned
+ * loopback port and loads the app's data into `db_template` (`testImage`).
+ * The run's resources remove the container and its data at teardown.
+ */
+export declare function startTestInstance(resources: ResourceScope, name: string, options: PostgresOptions): Promise<PostgresTestDatabase>;