@shivaedev/local-postgres 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.12.0 - 2026-11-03
+
+### Added
+
+- App-owned PostgreSQL instances initialize and preserve application data, run as scoped children with private Unix sockets and no TCP listener, and refuse incompatible data major versions with `AppPostgresVersionMismatch`.
+- Migration Effects run after a `pg_dump` backup, with configurable retention of completed backups. `PostgresBinaries` separates binary sourcing from lifecycle management; `hostPostgresBinaries` supplies host-installed executables.
+
 ## 0.11.0 - 2026-11-03
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # @shivaedev/local-postgres
 
-Make development and integration tests share one persistent local PostgreSQL service. Repeat setup without rebuilding the database contents, and keep each application's database names and schema preparation in its own setup script.
+Make development and integration tests share one persistent local PostgreSQL service, or let a local application own a private instance. Keep data across starts and leave schema preparation with the application.
 
 ## Why you want this
 
@@ -112,12 +112,52 @@ The last three functions are members of the object returned by `localPostgres`,
 
 The module export pattern also exposes the lower-level Docker and container command functions in `@shivaedev/local-postgres/server/adapters/docker.ts` and `@shivaedev/local-postgres/server/adapters/localContainer.ts`. Use `@shivaedev/local-postgres/server/localPostgres.ts` for application preparation.
 
+### An instance owned by a local application
+
+`appPostgres` from `@shivaedev/local-postgres/server/appPostgres.ts` initializes a cluster in `dataDirectory` and starts PostgreSQL as a child in the current Effect scope. Closing the scope sends a fast-shutdown signal and waits for the child to exit. The data directory survives; the temporary socket directory is removed. Keep the scope open for the application's lifetime:
+
+```ts
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { Effect } from "effect";
+import { hostPostgresBinaries } from "@shivaedev/local-postgres/server/adapters/hostPostgresBinaries.ts";
+import { appPostgres } from "@shivaedev/local-postgres/server/appPostgres.ts";
+
+const app = Effect.scoped(
+	Effect.gen(function* () {
+		const postgres = yield* appPostgres({ dataDirectory: "/path/to/app/data", backupsToKeep: 3 });
+		yield* Effect.log(postgres.connectionUrl);
+		yield* Effect.never;
+	}),
+);
+
+NodeRuntime.runMain(app.pipe(Effect.provide(hostPostgresBinaries()), Effect.provide(NodeServices.layer)));
+```
+
+The instance listens on a Unix socket in a directory with permissions `0700` and opens no TCP listener. `connectionUrl` selects the `postgres` database and role through that socket. Use it with the application's PostgreSQL client. App-owned mode is separate from the shared development service on port 55432.
+
+Before migrations, yield `migrateAppPostgres(instance, migrations)` from `@shivaedev/local-postgres/server/migrateAppPostgres.ts`. `migrations` is the application's Effect, such as its `@shivaedev/sql` migration entry point. The wrapper finishes a custom-format `pg_dump` before evaluating that Effect. A backup failure prevents the migration from running. Completed dumps live in `dataDirectory/backups`; `backupsToKeep` defaults to five and must be a positive integer. After each completed backup, only the newest configured number of dumps remain. The same module exports `backupAppPostgres(instance)` for an explicit backup; it returns the completed dump's path.
+
+The instance reads its binaries from the `PostgresBinaries` port in `@shivaedev/local-postgres/server/PostgresBinaries.ts`. `hostPostgresBinaries(directory?)` supplies host executables: either from the supplied directory, from `PATH`, or from `pg_config --bindir` when `postgres` is absent from `PATH`. It checks `initdb`, `postgres` and `pg_dump`. Another adapter can supply the port's `initdb`, `postgres` and `pgDump` paths without changing instance management.
+
+Before starting an existing cluster, the instance compares `PG_VERSION` with the server binary's major version. A mismatch fails with `AppPostgresVersionMismatch` from `@shivaedev/local-postgres/server/AppPostgresVersionMismatch.ts`, carrying `dataDirectory`, `expectedMajor` and `observedMajor`. It does not initialize or upgrade that data directory. Choose upgrades and restores outside this package.
+
+App-owned mode needs host PostgreSQL server and client binaries and a Unix-socket-capable system. Its real-instance stories skip with a diagnostic when those binaries are absent; set `PLATFORM_LOCAL_POSTGRES_BIN_DIRECTORY` to run them with a particular installed binary directory.
+
 ### Install and machine setup
 
+For shared development and test setup tooling:
+
 ```sh
 pnpm add --save-dev @shivaedev/local-postgres @effect/platform-node effect
 ```
 
+For an app-owned instance, install these as runtime dependencies:
+
+```sh
+pnpm add @shivaedev/local-postgres @effect/platform-node effect
+```
+
 The package requires Node 24 or later and uses Effect as a peer dependency. It needs host `psql` or a local Docker installation. SQL uses host `psql` when available and falls back to the container's client when the host executable is missing. Both clients receive the connection password through `PGPASSWORD`, outside the command line. Query failures retain PostgreSQL's diagnostics and command failure details (and a platform `cause` when a process cannot start) without exposing the connection password.
 
 The shared baseline is PostgreSQL 18.6 on loopback port 55432. Docker preparation uses container and volume name `development-postgres`, loopback publication `127.0.0.1:55432:5432`, and this image:
@@ -132,8 +172,8 @@ Yield `dockerEnvironment` from `@shivaedev/local-postgres/server/dockerEnvironme
 
 ### Limits
 
-- The service version, port, container name and volume name are fixed. Choose any upgrade and data-preservation procedure outside this package.
-- Keep commands in development and test setup tooling; setup never becomes an application request path.
+- The shared service's version, port, container name and volume name are fixed. Choose any upgrade and data-preservation procedure outside this package.
+- Keep shared-service commands in development and test setup tooling. App-owned mode manages the local child's lifetime; runtime queries belong to the application's SQL client.
 - Keep allowed names, schema changes, test isolation and cleanup in the application. Preparation is not a database reset.
 - A prepared database name has 1–63 lowercase letters, digits or underscores and starts with a letter. An allowlisted connection URL does not bypass this SQL-name constraint.
 - Concurrent creation of the same absent database is not supported. Prepare databases before parallel tests begin.

package/dist/server/AppPostgresVersionMismatch.d.ts

@@ -0,0 +1,11 @@
+import { Schema } from "effect";
+declare const AppPostgresVersionMismatch_base: Schema.Class<AppPostgresVersionMismatch, Schema.TaggedStruct<"AppPostgresVersionMismatch", {
+    readonly dataDirectory: Schema.String;
+    readonly expectedMajor: Schema.String;
+    readonly observedMajor: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class AppPostgresVersionMismatch extends AppPostgresVersionMismatch_base {
+    get message(): string;
+}
+export {};
+//# sourceMappingURL=AppPostgresVersionMismatch.d.ts.map

package/dist/server/AppPostgresVersionMismatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppPostgresVersionMismatch.d.ts","sourceRoot":"","sources":["../../src/server/AppPostgresVersionMismatch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;;;;;;AAEhC,qBAAa,0BAA2B,SAAQ,+BAI9C;IACD,IAAa,OAAO,WAEnB;CACD"}

package/dist/server/AppPostgresVersionMismatch.js

@@ -0,0 +1,11 @@
+import { Schema } from "effect";
+export class AppPostgresVersionMismatch extends Schema.TaggedError()("AppPostgresVersionMismatch", {
+    dataDirectory: Schema.String,
+    expectedMajor: Schema.String,
+    observedMajor: Schema.String,
+}) {
+    get message() {
+        return `PostgreSQL ${this.expectedMajor} cannot open ${this.dataDirectory}: its data belongs to PostgreSQL ${this.observedMajor}.`;
+    }
+}
+//# sourceMappingURL=AppPostgresVersionMismatch.js.map

package/dist/server/AppPostgresVersionMismatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppPostgresVersionMismatch.js","sourceRoot":"","sources":["../../src/server/AppPostgresVersionMismatch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,MAAM,OAAO,0BAA2B,SAAQ,MAAM,CAAC,WAAW,EAA8B,CAAC,4BAA4B,EAAE;IAC9H,aAAa,EAAE,MAAM,CAAC,MAAM;IAC5B,aAAa,EAAE,MAAM,CAAC,MAAM;IAC5B,aAAa,EAAE,MAAM,CAAC,MAAM;CAC5B,CAAC;IACD,IAAa,OAAO;QACnB,OAAO,cAAc,IAAI,CAAC,aAAa,gBAAgB,IAAI,CAAC,aAAa,oCAAoC,IAAI,CAAC,aAAa,GAAG,CAAC;IACpI,CAAC;CACD"}

package/dist/server/PostgresBinaries.d.ts

@@ -0,0 +1,11 @@
+import { Context } from "effect";
+export interface PostgresExecutables {
+    readonly initdb: string;
+    readonly pgDump: string;
+    readonly postgres: string;
+}
+declare const PostgresBinaries_base: Context.ServiceClass<PostgresBinaries, "@shivaedev/local-postgres/PostgresBinaries", PostgresExecutables>;
+export declare class PostgresBinaries extends PostgresBinaries_base {
+}
+export {};
+//# sourceMappingURL=PostgresBinaries.d.ts.map

package/dist/server/PostgresBinaries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PostgresBinaries.d.ts","sourceRoot":"","sources":["../../src/server/PostgresBinaries.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEjC,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;;AAED,qBAAa,gBAAiB,SAAQ,qBAAsG;CAAG"}

package/dist/server/PostgresBinaries.js

@@ -0,0 +1,4 @@
+import { Context } from "effect";
+export class PostgresBinaries extends Context.Service()("@shivaedev/local-postgres/PostgresBinaries") {
+}
+//# sourceMappingURL=PostgresBinaries.js.map

package/dist/server/PostgresBinaries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PostgresBinaries.js","sourceRoot":"","sources":["../../src/server/PostgresBinaries.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAQjC,MAAM,OAAO,gBAAiB,SAAQ,OAAO,CAAC,OAAO,EAAyC,CAAC,4CAA4C,CAAC;CAAG"}

package/dist/server/adapters/hostPostgresBinaries.d.ts

@@ -0,0 +1,4 @@
+import { Layer, Path } from "effect";
+import { PostgresBinaries } from "#server/PostgresBinaries.ts";
+export declare function hostPostgresBinaries(directory?: string): Layer.Layer<PostgresBinaries, import("../PostgresCommandError.ts").PostgresCommandError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | Path.Path>;
+//# sourceMappingURL=hostPostgresBinaries.d.ts.map

package/dist/server/adapters/hostPostgresBinaries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostPostgresBinaries.d.ts","sourceRoot":"","sources":["../../../src/server/adapters/hostPostgresBinaries.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAE7C,OAAO,EAAE,gBAAgB,EAA4B,MAAM,6BAA6B,CAAC;AAEzF,wBAAgB,oBAAoB,CAAC,SAAS,CAAC,EAAE,MAAM,0KAsBtD"}

package/dist/server/adapters/hostPostgresBinaries.js

@@ -0,0 +1,20 @@
+import { Effect, Layer, Path } from "effect";
+import { missingCommand, runCommand } from "#server/adapters/runCommand.ts";
+import { PostgresBinaries } from "#server/PostgresBinaries.ts";
+export function hostPostgresBinaries(directory) {
+    return Layer.effect(PostgresBinaries, Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const bin = directory
+            ?? (yield* runCommand("postgres", ["--version"]).pipe(Effect.as(""), Effect.catchTag("PostgresCommandError", (error) => (missingCommand(error) ? runCommand("pg_config", ["--bindir"]) : Effect.fail(error)))));
+        const executables = {
+            initdb: bin ? path.join(bin, "initdb") : "initdb",
+            pgDump: bin ? path.join(bin, "pg_dump") : "pg_dump",
+            postgres: bin ? path.join(bin, "postgres") : "postgres",
+        };
+        for (const command of Object.values(executables)) {
+            yield* runCommand(command, ["--version"]);
+        }
+        return executables;
+    }));
+}
+//# sourceMappingURL=hostPostgresBinaries.js.map

package/dist/server/adapters/hostPostgresBinaries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostPostgresBinaries.js","sourceRoot":"","sources":["../../../src/server/adapters/hostPostgresBinaries.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAC5E,OAAO,EAAE,gBAAgB,EAA4B,MAAM,6BAA6B,CAAC;AAEzF,MAAM,UAAU,oBAAoB,CAAC,SAAkB;IACtD,OAAO,KAAK,CAAC,MAAM,CAClB,gBAAgB,EAChB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QACnB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAC9B,MAAM,GAAG,GACR,SAAS;eACN,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CACpD,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,EACb,MAAM,CAAC,QAAQ,CAAC,sBAAsB,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CACxI,CAAC,CAAC;QACJ,MAAM,WAAW,GAAwB;YACxC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ;YACjD,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS;YACnD,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU;SACvD,CAAC;QACF,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;YAClD,KAAK,CAAC,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;QAC3C,CAAC;QACD,OAAO,WAAW,CAAC;IACpB,CAAC,CAAC,CACF,CAAC;AACH,CAAC"}

package/dist/server/appPostgres.d.ts

@@ -0,0 +1,22 @@
+import { Effect, FileSystem, Path } from "effect";
+import { ChildProcessSpawner } from "effect/process";
+import { LocalPostgresError } from "#server/LocalPostgresError.ts";
+import { PostgresBinaries } from "#server/PostgresBinaries.ts";
+import { PostgresCommandError } from "#server/PostgresCommandError.ts";
+export interface AppPostgresOptions {
+    readonly backupsToKeep?: number;
+    readonly dataDirectory: string;
+}
+export interface AppPostgresInstance {
+    readonly backupsToKeep: number;
+    readonly connectionUrl: string;
+    readonly dataDirectory: string;
+    readonly socketDirectory: string;
+}
+export declare const appPostgres: (args_0: AppPostgresOptions) => Effect.Effect<{
+    backupsToKeep: number;
+    connectionUrl: string;
+    dataDirectory: string;
+    socketDirectory: string;
+}, import("./AppPostgresVersionMismatch.ts").AppPostgresVersionMismatch | LocalPostgresError | import("effect/PlatformError").PlatformError | PostgresCommandError | import("effect/Cause").TimeoutError, ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path | PostgresBinaries | import("effect/Scope").Scope>;
+//# sourceMappingURL=appPostgres.d.ts.map

package/dist/server/appPostgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appPostgres.d.ts","sourceRoot":"","sources":["../../src/server/appPostgres.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,MAAM,EAAE,UAAU,EAAE,IAAI,EAAU,MAAM,QAAQ,CAAC;AACpE,OAAO,EAAgB,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAGvE,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CACjC;AAED,eAAO,MAAM,WAAW;;;;;wUA4DtB,CAAC"}

package/dist/server/appPostgres.js

@@ -0,0 +1,50 @@
+import { Deferred, Effect, FileSystem, Path, Stream } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
+import { LocalPostgresError } from "#server/LocalPostgresError.ts";
+import { PostgresBinaries } from "#server/PostgresBinaries.ts";
+import { PostgresCommandError } from "#server/PostgresCommandError.ts";
+import { prepareAppPostgresData } from "#server/prepareAppPostgresData.ts";
+export const appPostgres = Effect.fn("LocalPostgres.appPostgres")(function* ({ dataDirectory, backupsToKeep = 5 }) {
+    if (!Number.isSafeInteger(backupsToKeep) || backupsToKeep < 1) {
+        return yield* new LocalPostgresError({ message: "backupsToKeep must be a positive integer." });
+    }
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const binaries = yield* PostgresBinaries;
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const directory = path.resolve(dataDirectory);
+    yield* prepareAppPostgresData(directory);
+    const socketDirectory = yield* fs.makeTempDirectoryScoped({ prefix: "app-postgres-" });
+    yield* fs.chmod(socketDirectory, 0o700);
+    const child = yield* spawner.spawn(ChildProcess.make(binaries.postgres, [
+        "-D",
+        directory,
+        "-h",
+        "",
+        "-k",
+        socketDirectory,
+        "-c",
+        "unix_socket_permissions=0700",
+        "-c",
+        "logging_collector=off",
+        "-c",
+        "log_destination=stderr",
+        "-c",
+        "lc_messages=C",
+    ], { env: { "LC_ALL": "C" }, extendEnv: true, killSignal: "SIGINT", stdin: "ignore", stdout: "ignore" }));
+    const ready = yield* Deferred.make();
+    let diagnostics = "";
+    yield* child.stderr.pipe(Stream.decodeText, Stream.splitLines, Stream.runForEach((line) => {
+        diagnostics = line;
+        return line.includes("database system is ready to accept connections") ? Deferred.succeed(ready, undefined) : Effect.void;
+    }), Effect.forkScoped);
+    yield* Effect.raceFirst(Deferred.await(ready), Effect.flatMap(child.exitCode, (code) => Effect.fail(new PostgresCommandError({
+        command: binaries.postgres,
+        exitCode: Number(code),
+        message: diagnostics || "PostgreSQL exited before becoming ready.",
+    })))).pipe(Effect.timeout("30 seconds"));
+    const connection = new URL("postgresql://postgres@localhost/postgres");
+    connection.searchParams.set("host", socketDirectory);
+    return { backupsToKeep, connectionUrl: connection.toString(), dataDirectory: directory, socketDirectory };
+});
+//# sourceMappingURL=appPostgres.js.map

package/dist/server/appPostgres.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appPostgres.js","sourceRoot":"","sources":["../../src/server/appPostgres.ts"],"names":[],"mappings":"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"}

package/dist/server/migrateAppPostgres.d.ts

@@ -0,0 +1,6 @@
+import { Effect, FileSystem, Path } from "effect";
+import type { AppPostgresInstance } from "#server/appPostgres.ts";
+import { PostgresBinaries } from "#server/PostgresBinaries.ts";
+export declare const backupAppPostgres: (instance: AppPostgresInstance) => Effect.Effect<string, import("effect/PlatformError").PlatformError | import("./PostgresCommandError.ts").PostgresCommandError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | FileSystem.FileSystem | Path.Path | PostgresBinaries>;
+export declare function migrateAppPostgres<A, E, R>(instance: AppPostgresInstance, migration: Effect.Effect<A, E, R>): Effect.Effect<A, E | import("effect/PlatformError").PlatformError | import("./PostgresCommandError.ts").PostgresCommandError, R | import("effect/process/ChildProcessSpawner").ChildProcessSpawner | FileSystem.FileSystem | Path.Path | PostgresBinaries>;
+//# sourceMappingURL=migrateAppPostgres.d.ts.map

package/dist/server/migrateAppPostgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrateAppPostgres.d.ts","sourceRoot":"","sources":["../../src/server/migrateAppPostgres.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAEzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAE/D,eAAO,MAAM,iBAAiB,4RAyB5B,CAAC;AAEH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,8PAE3G"}

package/dist/server/migrateAppPostgres.js

@@ -0,0 +1,31 @@
+import { Clock, Effect, FileSystem, Path } from "effect";
+import { runCommand } from "#server/adapters/runCommand.ts";
+import { PostgresBinaries } from "#server/PostgresBinaries.ts";
+export const backupAppPostgres = Effect.fn("LocalPostgres.backupAppPostgres")(function* (instance) {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const binaries = yield* PostgresBinaries;
+    const directory = path.join(instance.dataDirectory, "backups");
+    yield* fs.makeDirectory(directory, { mode: 0o700, recursive: true });
+    const timestamp = yield* Clock.currentTimeMillis;
+    const backup = yield* Effect.scoped(Effect.gen(function* () {
+        const staging = yield* fs.makeTempDirectoryScoped({ directory, prefix: `backup-${timestamp}-` });
+        const file = path.join(staging, "dump.partial");
+        yield* runCommand(binaries.pgDump, ["--format=custom", "--file", file, "--dbname", instance.connectionUrl]);
+        const completed = `${staging}.dump`;
+        yield* fs.rename(file, completed);
+        return completed;
+    }));
+    const files = (yield* fs.readDirectory(directory))
+        .filter((name) => /^backup-\d+-.+\.dump$/u.test(name))
+        .sort()
+        .reverse();
+    for (const file of files.slice(instance.backupsToKeep)) {
+        yield* fs.remove(path.join(directory, file));
+    }
+    return backup;
+});
+export function migrateAppPostgres(instance, migration) {
+    return backupAppPostgres(instance).pipe(Effect.andThen(migration));
+}
+//# sourceMappingURL=migrateAppPostgres.js.map

package/dist/server/migrateAppPostgres.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrateAppPostgres.js","sourceRoot":"","sources":["../../src/server/migrateAppPostgres.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAE5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAE/D,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,EAAE,CAAC,iCAAiC,CAAC,CAAC,QAAQ,CAAC,EAAE,QAA6B;IACrH,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC;IACxC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;IAC9B,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,gBAAgB,CAAC;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IAC/D,KAAK,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACrE,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC;IACjD,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,MAAM,CAClC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QACnB,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC,uBAAuB,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,SAAS,GAAG,EAAE,CAAC,CAAC;QACjG,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;QAChD,KAAK,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,iBAAiB,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC;QAC5G,MAAM,SAAS,GAAG,GAAG,OAAO,OAAO,CAAC;QACpC,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAClC,OAAO,SAAS,CAAC;IAClB,CAAC,CAAC,CACF,CAAC;IACF,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;SAChD,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;SACrD,IAAI,EAAE;SACN,OAAO,EAAE,CAAC;IACZ,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;QACxD,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC,CAAC,CAAC;AAEH,MAAM,UAAU,kBAAkB,CAAU,QAA6B,EAAE,SAAiC;IAC3G,OAAO,iBAAiB,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;AACpE,CAAC"}

package/dist/server/prepareAppPostgresData.d.ts

@@ -0,0 +1,6 @@
+import { Effect, FileSystem, Path } from "effect";
+import { AppPostgresVersionMismatch } from "#server/AppPostgresVersionMismatch.ts";
+import { LocalPostgresError } from "#server/LocalPostgresError.ts";
+import { PostgresBinaries } from "#server/PostgresBinaries.ts";
+export declare const prepareAppPostgresData: (dataDirectory: string) => Effect.Effect<undefined, AppPostgresVersionMismatch | LocalPostgresError | import("effect/PlatformError").PlatformError | import("./PostgresCommandError.ts").PostgresCommandError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | FileSystem.FileSystem | Path.Path | PostgresBinaries>;
+//# sourceMappingURL=prepareAppPostgresData.d.ts.map

package/dist/server/prepareAppPostgresData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepareAppPostgresData.d.ts","sourceRoot":"","sources":["../../src/server/prepareAppPostgresData.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAClD,OAAO,EAAE,0BAA0B,EAAE,MAAM,uCAAuC,CAAC;AAEnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAE/D,eAAO,MAAM,sBAAsB,yUA4BjC,CAAC"}

package/dist/server/prepareAppPostgresData.js

@@ -0,0 +1,35 @@
+import { Effect, FileSystem, Path } from "effect";
+import { AppPostgresVersionMismatch } from "#server/AppPostgresVersionMismatch.ts";
+import { runCommand } from "#server/adapters/runCommand.ts";
+import { LocalPostgresError } from "#server/LocalPostgresError.ts";
+import { PostgresBinaries } from "#server/PostgresBinaries.ts";
+export const prepareAppPostgresData = Effect.fn("LocalPostgres.prepareAppPostgresData")(function* (dataDirectory) {
+    const binaries = yield* PostgresBinaries;
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const version = yield* runCommand(binaries.postgres, ["--version"]);
+    const expectedMajor = /\b(?<major>\d+)\./u.exec(version)?.groups?.major;
+    if (!expectedMajor) {
+        return yield* new LocalPostgresError({ message: `Cannot read PostgreSQL major version from ${version}.` });
+    }
+    const versionFile = path.join(dataDirectory, "PG_VERSION");
+    if (yield* fs.exists(versionFile)) {
+        const observedMajor = (yield* fs.readFileString(versionFile)).trim();
+        if (observedMajor !== expectedMajor) {
+            return yield* new AppPostgresVersionMismatch({ dataDirectory, expectedMajor, observedMajor });
+        }
+        return;
+    }
+    yield* fs.makeDirectory(dataDirectory, { recursive: true });
+    yield* runCommand(binaries.initdb, [
+        "--pgdata",
+        dataDirectory,
+        "--username",
+        "postgres",
+        "--auth-local=trust",
+        "--auth-host=reject",
+        "--encoding=UTF8",
+        "--locale=C",
+    ]);
+});
+//# sourceMappingURL=prepareAppPostgresData.js.map

package/dist/server/prepareAppPostgresData.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepareAppPostgresData.js","sourceRoot":"","sources":["../../src/server/prepareAppPostgresData.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAClD,OAAO,EAAE,0BAA0B,EAAE,MAAM,uCAAuC,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAE/D,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC,EAAE,CAAC,sCAAsC,CAAC,CAAC,QAAQ,CAAC,EAAE,aAAqB;IACvH,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,gBAAgB,CAAC;IACzC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC;IACxC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;IAC9B,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;IACpE,MAAM,aAAa,GAAG,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC;IACxE,IAAI,CAAC,aAAa,EAAE,CAAC;QACpB,OAAO,KAAK,CAAC,CAAC,IAAI,kBAAkB,CAAC,EAAE,OAAO,EAAE,6CAA6C,OAAO,GAAG,EAAE,CAAC,CAAC;IAC5G,CAAC;IACD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC;IAC3D,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QACnC,MAAM,aAAa,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACrE,IAAI,aAAa,KAAK,aAAa,EAAE,CAAC;YACrC,OAAO,KAAK,CAAC,CAAC,IAAI,0BAA0B,CAAC,EAAE,aAAa,EAAE,aAAa,EAAE,aAAa,EAAE,CAAC,CAAC;QAC/F,CAAC;QACD,OAAO;IACR,CAAC;IACD,KAAK,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,aAAa,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,KAAK,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,EAAE;QAClC,UAAU;QACV,aAAa;QACb,YAAY;QACZ,UAAU;QACV,oBAAoB;QACpB,oBAAoB;QACpB,iBAAiB;QACjB,YAAY;KACZ,CAAC,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/local-postgres",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Repeatable local PostgreSQL preparation with one shared persistent service",
   "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/local-postgres#readme",
   "bugs": {
@@ -41,8 +41,8 @@
   ],
   "devDependencies": {
     "@effect/platform-node": "4.0.6",
-    "@shivaedev/quality": "0.57.0",
-    "@shivaedev/test-story": "0.35.0",
+    "@shivaedev/quality": "0.57.1",
+    "@shivaedev/test-story": "0.36.0",
     "@types/node": "24.19.2",
     "effect": "4.0.6",
     "typescript": "7.0.2",

package/src/server/AppPostgresVersionMismatch.ts

@@ -0,0 +1,11 @@
+import { Schema } from "effect";
+
+export class AppPostgresVersionMismatch extends Schema.TaggedError<AppPostgresVersionMismatch>()("AppPostgresVersionMismatch", {
+	dataDirectory: Schema.String,
+	expectedMajor: Schema.String,
+	observedMajor: Schema.String,
+}) {
+	override get message() {
+		return `PostgreSQL ${this.expectedMajor} cannot open ${this.dataDirectory}: its data belongs to PostgreSQL ${this.observedMajor}.`;
+	}
+}

package/src/server/PostgresBinaries.ts

@@ -0,0 +1,9 @@
+import { Context } from "effect";
+
+export interface PostgresExecutables {
+	readonly initdb: string;
+	readonly pgDump: string;
+	readonly postgres: string;
+}
+
+export class PostgresBinaries extends Context.Service<PostgresBinaries, PostgresExecutables>()("@shivaedev/local-postgres/PostgresBinaries") {}

package/src/server/adapters/hostPostgresBinaries.ts

@@ -0,0 +1,27 @@
+import { Effect, Layer, Path } from "effect";
+import { missingCommand, runCommand } from "#server/adapters/runCommand.ts";
+import { PostgresBinaries, type PostgresExecutables } from "#server/PostgresBinaries.ts";
+
+export function hostPostgresBinaries(directory?: string) {
+	return Layer.effect(
+		PostgresBinaries,
+		Effect.gen(function* () {
+			const path = yield* Path.Path;
+			const bin =
+				directory
+				?? (yield* runCommand("postgres", ["--version"]).pipe(
+					Effect.as(""),
+					Effect.catchTag("PostgresCommandError", (error) => (missingCommand(error) ? runCommand("pg_config", ["--bindir"]) : Effect.fail(error))),
+				));
+			const executables: PostgresExecutables = {
+				initdb: bin ? path.join(bin, "initdb") : "initdb",
+				pgDump: bin ? path.join(bin, "pg_dump") : "pg_dump",
+				postgres: bin ? path.join(bin, "postgres") : "postgres",
+			};
+			for (const command of Object.values(executables)) {
+				yield* runCommand(command, ["--version"]);
+			}
+			return executables;
+		}),
+	);
+}

package/src/server/appPostgres.ts

@@ -0,0 +1,80 @@
+import { Deferred, Effect, FileSystem, Path, Stream } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
+import { LocalPostgresError } from "#server/LocalPostgresError.ts";
+import { PostgresBinaries } from "#server/PostgresBinaries.ts";
+import { PostgresCommandError } from "#server/PostgresCommandError.ts";
+import { prepareAppPostgresData } from "#server/prepareAppPostgresData.ts";
+
+export interface AppPostgresOptions {
+	readonly backupsToKeep?: number;
+	readonly dataDirectory: string;
+}
+
+export interface AppPostgresInstance {
+	readonly backupsToKeep: number;
+	readonly connectionUrl: string;
+	readonly dataDirectory: string;
+	readonly socketDirectory: string;
+}
+
+export const appPostgres = Effect.fn("LocalPostgres.appPostgres")(function* ({ dataDirectory, backupsToKeep = 5 }: AppPostgresOptions) {
+	if (!Number.isSafeInteger(backupsToKeep) || backupsToKeep < 1) {
+		return yield* new LocalPostgresError({ message: "backupsToKeep must be a positive integer." });
+	}
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const binaries = yield* PostgresBinaries;
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+	const directory = path.resolve(dataDirectory);
+	yield* prepareAppPostgresData(directory);
+	const socketDirectory = yield* fs.makeTempDirectoryScoped({ prefix: "app-postgres-" });
+	yield* fs.chmod(socketDirectory, 0o700);
+	const child = yield* spawner.spawn(
+		ChildProcess.make(
+			binaries.postgres,
+			[
+				"-D",
+				directory,
+				"-h",
+				"",
+				"-k",
+				socketDirectory,
+				"-c",
+				"unix_socket_permissions=0700",
+				"-c",
+				"logging_collector=off",
+				"-c",
+				"log_destination=stderr",
+				"-c",
+				"lc_messages=C",
+			],
+			{ env: { "LC_ALL": "C" }, extendEnv: true, killSignal: "SIGINT", stdin: "ignore", stdout: "ignore" },
+		),
+	);
+	const ready = yield* Deferred.make<void>();
+	let diagnostics = "";
+	yield* child.stderr.pipe(
+		Stream.decodeText,
+		Stream.splitLines,
+		Stream.runForEach((line) => {
+			diagnostics = line;
+			return line.includes("database system is ready to accept connections") ? Deferred.succeed(ready, undefined) : Effect.void;
+		}),
+		Effect.forkScoped,
+	);
+	yield* Effect.raceFirst(
+		Deferred.await(ready),
+		Effect.flatMap(child.exitCode, (code) =>
+			Effect.fail(
+				new PostgresCommandError({
+					command: binaries.postgres,
+					exitCode: Number(code),
+					message: diagnostics || "PostgreSQL exited before becoming ready.",
+				}),
+			),
+		),
+	).pipe(Effect.timeout("30 seconds"));
+	const connection = new URL("postgresql://postgres@localhost/postgres");
+	connection.searchParams.set("host", socketDirectory);
+	return { backupsToKeep, connectionUrl: connection.toString(), dataDirectory: directory, socketDirectory } satisfies AppPostgresInstance;
+});

package/src/server/migrateAppPostgres.ts

@@ -0,0 +1,35 @@
+import { Clock, Effect, FileSystem, Path } from "effect";
+import { runCommand } from "#server/adapters/runCommand.ts";
+import type { AppPostgresInstance } from "#server/appPostgres.ts";
+import { PostgresBinaries } from "#server/PostgresBinaries.ts";
+
+export const backupAppPostgres = Effect.fn("LocalPostgres.backupAppPostgres")(function* (instance: AppPostgresInstance) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const binaries = yield* PostgresBinaries;
+	const directory = path.join(instance.dataDirectory, "backups");
+	yield* fs.makeDirectory(directory, { mode: 0o700, recursive: true });
+	const timestamp = yield* Clock.currentTimeMillis;
+	const backup = yield* Effect.scoped(
+		Effect.gen(function* () {
+			const staging = yield* fs.makeTempDirectoryScoped({ directory, prefix: `backup-${timestamp}-` });
+			const file = path.join(staging, "dump.partial");
+			yield* runCommand(binaries.pgDump, ["--format=custom", "--file", file, "--dbname", instance.connectionUrl]);
+			const completed = `${staging}.dump`;
+			yield* fs.rename(file, completed);
+			return completed;
+		}),
+	);
+	const files = (yield* fs.readDirectory(directory))
+		.filter((name) => /^backup-\d+-.+\.dump$/u.test(name))
+		.sort()
+		.reverse();
+	for (const file of files.slice(instance.backupsToKeep)) {
+		yield* fs.remove(path.join(directory, file));
+	}
+	return backup;
+});
+
+export function migrateAppPostgres<A, E, R>(instance: AppPostgresInstance, migration: Effect.Effect<A, E, R>) {
+	return backupAppPostgres(instance).pipe(Effect.andThen(migration));
+}

package/src/server/prepareAppPostgresData.ts

@@ -0,0 +1,35 @@
+import { Effect, FileSystem, Path } from "effect";
+import { AppPostgresVersionMismatch } from "#server/AppPostgresVersionMismatch.ts";
+import { runCommand } from "#server/adapters/runCommand.ts";
+import { LocalPostgresError } from "#server/LocalPostgresError.ts";
+import { PostgresBinaries } from "#server/PostgresBinaries.ts";
+
+export const prepareAppPostgresData = Effect.fn("LocalPostgres.prepareAppPostgresData")(function* (dataDirectory: string) {
+	const binaries = yield* PostgresBinaries;
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const version = yield* runCommand(binaries.postgres, ["--version"]);
+	const expectedMajor = /\b(?<major>\d+)\./u.exec(version)?.groups?.major;
+	if (!expectedMajor) {
+		return yield* new LocalPostgresError({ message: `Cannot read PostgreSQL major version from ${version}.` });
+	}
+	const versionFile = path.join(dataDirectory, "PG_VERSION");
+	if (yield* fs.exists(versionFile)) {
+		const observedMajor = (yield* fs.readFileString(versionFile)).trim();
+		if (observedMajor !== expectedMajor) {
+			return yield* new AppPostgresVersionMismatch({ dataDirectory, expectedMajor, observedMajor });
+		}
+		return;
+	}
+	yield* fs.makeDirectory(dataDirectory, { recursive: true });
+	yield* runCommand(binaries.initdb, [
+		"--pgdata",
+		dataDirectory,
+		"--username",
+		"postgres",
+		"--auth-local=trust",
+		"--auth-host=reject",
+		"--encoding=UTF8",
+		"--locale=C",
+	]);
+});