@shivaedev/local-postgres 0.7.0 → 0.9.0

package/src/server/localContainer.ts

@@ -1,51 +1,47 @@
-import type { ExecFileSyncOptionsWithStringEncoding } from "node:child_process";
-import { env } from "node:process";
+import { Effect } from "effect";
+import { clientConnection } from "#clientConnection.ts";
+import { LocalPostgresError } from "#LocalPostgresError.ts";
+import type { docker as runDocker } from "#localDocker.ts";
+import { PostgresCommandError } from "#PostgresCommandError.ts";
+import type { CommandOptions } from "#runCommand.ts";
 
 export const POSTGRES_IMAGE = "postgres:18.6-alpine@sha256:77f585114c32fbca283dc835b0596f4e52b51b4c6662d7810b2f4084f60a1873";
 const CONTAINER = "development-postgres";
-type Docker = (args: readonly string[], options?: ExecFileSyncOptionsWithStringEncoding) => string;
+type Docker = (args: readonly string[], options?: CommandOptions) => ReturnType<typeof runDocker>;
 
-export function sqlInContainer(docker: Docker, url: URL, args: readonly string[], options: ExecFileSyncOptionsWithStringEncoding) {
-	const id = docker(["ps", "--filter", "publish=55432", "--format", "{{.ID}}"], options).trim();
+export const sqlInContainer = Effect.fn("LocalPostgres.sqlInContainer")(function* (
+	docker: Docker,
+	url: URL,
+	args: readonly string[],
+	options: CommandOptions,
+) {
+	const id = yield* docker(["ps", "--filter", "publish=55432", "--format", "{{.ID}}"], options);
 	if (!id || id.includes("\n")) {
-		throw new Error("Install psql or start the shared PostgreSQL service with Docker.");
+		return yield* new PostgresCommandError({ command: "psql", message: "Install psql or start the shared PostgreSQL service with Docker." });
 	}
-	if (docker(["inspect", "--format", "{{.Config.Image}}", id], options).trim() !== POSTGRES_IMAGE) {
-		throw new Error("The shared PostgreSQL image differs from the pinned baseline. Upgrade explicitly, preserving data.");
+	if ((yield* docker(["inspect", "--format", "{{.Config.Image}}", id], options)) !== POSTGRES_IMAGE) {
+		return yield* new LocalPostgresError({
+			message: "The shared PostgreSQL image differs from the pinned baseline. Upgrade explicitly, preserving data.",
+		});
 	}
-	// libpq treats + literally in URI passwords.
-	const password = new URLSearchParams(url.search.replaceAll("+", "%2B")).getAll("password").at(-1) ?? decodeURIComponent(url.password);
-	const inside = new URL(url);
+	const { url: inside, options: settings } = yield* clientConnection(url, options);
 	inside.hostname = "127.0.0.1";
 	inside.port = "5432";
-	inside.password = "";
-	inside.searchParams.delete("password");
-	try {
-		return docker(["exec", "--env", "PGPASSWORD", id, "psql", ...args, "--dbname", inside.toString()], {
-			...options,
-			env: { ...env, ...options.env, ...(password && { "PGPASSWORD": password }) },
-		}).trim();
-	} catch (error) {
-		throw new Error(error instanceof Error && "stderr" in error ? String(error.stderr) : "PostgreSQL query failed.", { cause: error });
-	}
-}
+	return yield* docker(["exec", "--env", "PGPASSWORD", id, "psql", ...args, "--dbname", inside.toString()], settings);
+});
 
-export function startContainer(docker: Docker) {
-	docker(["info"]);
-	let existing: boolean;
-	try {
-		docker(["container", "inspect", CONTAINER]);
-		existing = true;
-	} catch {
-		existing = false;
-	}
+export const startContainer = Effect.fn("LocalPostgres.startContainer")(function* (docker: Docker) {
+	yield* docker(["info"]);
+	const existing = yield* docker(["container", "ls", "--all", "--filter", `name=^/${CONTAINER}$`, "--format", "{{.ID}}"]);
 	if (existing) {
-		if (docker(["inspect", "--format", "{{.Config.Image}}", CONTAINER]).trim() !== POSTGRES_IMAGE) {
-			throw new Error("The shared PostgreSQL container uses a different image. Preserve its volume and upgrade it explicitly.");
+		if ((yield* docker(["inspect", "--format", "{{.Config.Image}}", CONTAINER])) !== POSTGRES_IMAGE) {
+			return yield* new LocalPostgresError({
+				message: "The shared PostgreSQL container uses a different image. Preserve its volume and upgrade it explicitly.",
+			});
 		}
-		docker(["start", CONTAINER]);
+		yield* docker(["start", CONTAINER]);
 	} else {
-		docker([
+		yield* docker([
 			"run",
 			"--detach",
 			"--name",
@@ -61,4 +57,4 @@ export function startContainer(docker: Docker) {
 			POSTGRES_IMAGE,
 		]);
 	}
-}
+});

package/src/server/localDocker.ts

@@ -1,27 +1,35 @@
-import { type ExecFileSyncOptionsWithStringEncoding, execFileSync } from "node:child_process";
+import { Effect } from "effect";
+import { LocalPostgresError } from "#LocalPostgresError.ts";
+import { type CommandOptions, runCommand } from "#runCommand.ts";
 
 export type DockerEnvironment = Readonly<{ "DOCKER_CONTEXT"?: string | undefined; "DOCKER_HOST"?: string | undefined }>;
 
-export function docker(
+export const docker = Effect.fn("LocalPostgres.docker")(function* (
 	environment: DockerEnvironment,
 	args: readonly string[],
-	options: ExecFileSyncOptionsWithStringEncoding = { encoding: "utf8" },
+	options: CommandOptions = {},
 ) {
 	const context = environment.DOCKER_CONTEXT;
 	const host = environment.DOCKER_HOST;
+	if ((["DOCKER_CONTEXT", "DOCKER_HOST"] as const).some((key) => options.env?.[key] && options.env[key] !== environment[key])) {
+		return yield* new LocalPostgresError({ message: "Docker command environment conflicts with the Docker endpoint settings." });
+	}
+	const settings = {
+		...options,
+		env: { ...environment, ...options.env, "DOCKER_CONTEXT": context ?? "", "DOCKER_HOST": host ?? "" },
+		extendEnv: true,
+	};
 	const endpoint =
 		(!context && host)
-		|| execFileSync("docker", ["context", "inspect", ...(context ? [context] : []), "--format", "{{.Endpoints.docker.Host}}"], {
-			encoding: "utf8",
-		}).trim();
-	const url = new URL(endpoint);
+		|| (yield* runCommand("docker", ["context", "inspect", ...(context ? [context] : []), "--format", "{{.Endpoints.docker.Host}}"], settings));
+	const url = yield* Effect.try({ catch: () => new LocalPostgresError({ message: "Invalid Docker endpoint." }), try: () => new URL(endpoint) });
 	if (
 		!(
 			(["unix:", "npipe:"].includes(url.protocol) && ["", "localhost"].includes(url.hostname))
 			|| (url.protocol === "tcp:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))
 		)
 	) {
-		throw new Error("Local database setup requires a local Docker endpoint; remote contexts are refused.");
+		return yield* new LocalPostgresError({ message: "Local database setup requires a local Docker endpoint; remote contexts are refused." });
 	}
-	return execFileSync("docker", args, options);
-}
+	return yield* runCommand("docker", args, { ...settings, env: { ...settings.env, "DOCKER_CONTEXT": "", "DOCKER_HOST": endpoint } });
+});

package/src/server/localPostgres.ts

@@ -1,31 +1,27 @@
-import { type ExecFileSyncOptionsWithStringEncoding, execFileSync } from "node:child_process";
-import { env } from "node:process";
-import { ensureConnections } from "./localConnections.ts";
-import { sqlInContainer, startContainer } from "./localContainer.ts";
-import { type DockerEnvironment, docker } from "./localDocker.ts";
-import { PostgresVersionMismatch } from "./PostgresVersionMismatch.ts";
+import { Effect, Schedule } from "effect";
+import { clientConnection } from "#clientConnection.ts";
+import { LocalPostgresError } from "#LocalPostgresError.ts";
+import { ensureConnections } from "#localConnections.ts";
+import { sqlInContainer, startContainer } from "#localContainer.ts";
+import { type DockerEnvironment, docker } from "#localDocker.ts";
+import { PostgresVersionMismatch } from "#PostgresVersionMismatch.ts";
+import { type CommandOptions, missingCommand, runCommand } from "#runCommand.ts";
 
 export const LOCAL_SERVER = "postgresql://postgres:postgres@127.0.0.1:55432";
 
-export function assertLocalDatabase(value: string, names: readonly string[]) {
-	const url = new URL(value);
-	const name = url.pathname.slice(1);
+export const assertLocalDatabase = Effect.fn("LocalPostgres.assertLocalDatabase")(function* (value: string, names: readonly string[]) {
+	const message = `Use a local database on 127.0.0.1:55432 named ${names.join(" or ")}.`;
+	const url = yield* Effect.try({ catch: () => new LocalPostgresError({ message }), try: () => new URL(value) });
 	if (
 		!(["postgres:", "postgresql:"].includes(url.protocol) && ["localhost", "127.0.0.1"].includes(url.hostname))
 		|| url.port !== "55432"
 		|| ["host", "hostaddr", "port", "dbname", "service"].some((key) => url.searchParams.has(key))
-		|| !names.includes(name)
+		|| !names.includes(url.pathname.slice(1))
 	) {
-		throw new Error(`Use a local database on 127.0.0.1:55432 named ${names.join(" or ")}.`);
+		return yield* new LocalPostgresError({ message });
 	}
 	return url;
-}
-
-function clientEnvironment(url: URL) {
-	// libpq treats + literally in URI passwords.
-	const password = new URLSearchParams(url.search.replaceAll("+", "%2B")).getAll("password").at(-1) ?? decodeURIComponent(url.password);
-	return { ...env, ...(password && { "PGPASSWORD": password }) };
-}
+});
 
 export interface ReadinessOptions {
 	readonly attempts?: number;
@@ -33,90 +29,71 @@ export interface ReadinessOptions {
 }
 
 export function localPostgres(environment: DockerEnvironment, { attempts = 30, delayMillis = 1000 }: ReadinessOptions = {}) {
-	function localDocker(args: readonly string[], options: ExecFileSyncOptionsWithStringEncoding = { encoding: "utf8" }) {
+	function localDocker(args: readonly string[], options?: CommandOptions) {
 		return docker(environment, args, options);
 	}
-	function sql(value: string | URL, query: string) {
-		const url = new URL(value);
-		assertLocalDatabase(url.toString(), [url.pathname.slice(1)]);
-		const childEnvironment = clientEnvironment(url);
-		url.password = "";
-		url.searchParams.delete("password");
-		for (const key of ["schema", "connection_limit", "pool_timeout", "pgbouncer"]) {
-			url.searchParams.delete(key);
-		}
-
-		const args = ["-X", "--set", "ON_ERROR_STOP=1", "-At", "-c", query];
-		if (!url.searchParams.has("connect_timeout")) {
-			url.searchParams.set("connect_timeout", "3");
-		}
-		const options = {
-			encoding: "utf8",
-			env: childEnvironment,
-			stdio: ["ignore", "pipe", "pipe"],
-		} satisfies ExecFileSyncOptionsWithStringEncoding;
-		try {
-			return execFileSync("psql", [...args, "--dbname", url.toString()], options).trim();
-		} catch (error) {
-			if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-				return sqlInContainer(localDocker, url, args, options);
-			}
-			throw new Error(error instanceof Error && "stderr" in error ? String(error.stderr) : "PostgreSQL query failed.", { cause: error });
-		}
-	}
-
-	function startPostgres(connection = LOCAL_SERVER) {
-		const server = new URL(connection);
+	const sql = localSql(localDocker);
+	const startPostgres = Effect.fn("LocalPostgres.startPostgres")(function* (connection = LOCAL_SERVER) {
+		const server = yield* Effect.try({
+			catch: () => new LocalPostgresError({ message: "Invalid local database URL." }),
+			try: () => new URL(connection),
+		});
 		server.pathname = "/postgres";
-		assertLocalDatabase(server.toString(), ["postgres"]);
+		yield* assertLocalDatabase(server.toString(), ["postgres"]);
 		function waitForVersion() {
-			for (let attempt = 0; attempt < attempts; attempt += 1) {
-				try {
-					return sql(server, "SHOW server_version");
-				} catch {
-					Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delayMillis);
-				}
-			}
-			return undefined;
+			return sql(server, "SHOW server_version").pipe(Effect.retry({ schedule: Schedule.spaced(delayMillis), times: attempts - 1 }));
 		}
-		function confirmVersion(observed: string | undefined) {
-			if (observed !== "18.6") {
-				throw new PostgresVersionMismatch(observed);
-			}
-		}
-		let version: string | undefined;
-		try {
-			version = sql(server, "SHOW server_version");
-		} catch {
-			startContainer(localDocker);
-			version = waitForVersion();
+		function confirmVersion(observed: string) {
+			return /^18\.6(?:\s|$)/u.test(observed)
+				? Effect.void
+				: Effect.fail(new PostgresVersionMismatch({ expectedVersion: "18.6", observedVersion: observed }));
 		}
-		confirmVersion(version);
-		ensureConnections(
+		const version = yield* sql(server, "SHOW server_version").pipe(
+			Effect.catchTag("PostgresCommandError", () => Effect.andThen(startContainer(localDocker), waitForVersion)),
+		);
+		yield* confirmVersion(version);
+		yield* ensureConnections(
 			localDocker,
 			(query) => sql(server, query),
-			() => confirmVersion(waitForVersion()),
+			() => Effect.flatMap(waitForVersion(), confirmVersion),
 		);
-	}
-
-	function prepareDatabases(values: readonly string[]) {
+	});
+	const prepareDatabases = Effect.fn("LocalPostgres.prepareDatabases")(function* (values: readonly string[]) {
+		const urls: URL[] = [];
 		for (const value of values) {
-			const name = new URL(value).pathname.slice(1);
-			assertLocalDatabase(value, [name]);
+			const parsed = yield* Effect.try({
+				catch: () => new LocalPostgresError({ message: "Invalid local database URL." }),
+				try: () => new URL(value),
+			});
+			const name = parsed.pathname.slice(1);
+			const url = yield* assertLocalDatabase(value, [name]);
 			if (!/^[a-z][a-z0-9_]{0,62}$/u.test(name)) {
-				throw new Error("Invalid local database name.");
+				return yield* new LocalPostgresError({ message: "Invalid local database name." });
 			}
+			urls.push(url);
 		}
-		startPostgres(values[0]);
-		for (const value of values) {
-			const url = new URL(value);
+		yield* startPostgres(values[0]);
+		for (const url of urls) {
 			const name = url.pathname.slice(1);
 			const server = new URL(url);
 			server.pathname = "/postgres";
-			if (!sql(server, `SELECT 1 FROM pg_database WHERE datname = '${name}'`)) {
-				sql(server, `CREATE DATABASE "${name}"`);
+			if (!(yield* sql(server, `SELECT 1 FROM pg_database WHERE datname = '${name}'`))) {
+				yield* sql(server, `CREATE DATABASE "${name}"`);
 			}
 		}
-	}
+	});
 	return { prepareDatabases, sql, startPostgres };
 }
+
+function localSql(localDocker: (args: readonly string[], options?: CommandOptions) => ReturnType<typeof docker>) {
+	return Effect.fn("LocalPostgres.sql")(function* (value: string | URL, query: string) {
+		const parsed = yield* Effect.try({ catch: () => new LocalPostgresError({ message: "Invalid local database URL." }), try: () => new URL(value) });
+		const { url, options } = yield* clientConnection(yield* assertLocalDatabase(parsed.toString(), [parsed.pathname.slice(1)]));
+		const args = ["-X", "--set", "ON_ERROR_STOP=1", "-At", "-c", query];
+		return yield* runCommand("psql", [...args, "--dbname", url.toString()], options).pipe(
+			Effect.catchTag("PostgresCommandError", (error) =>
+				missingCommand(error) ? sqlInContainer(localDocker, url, args, options) : Effect.fail(error),
+			),
+		);
+	});
+}

package/src/server/runCommand.ts

@@ -0,0 +1,31 @@
+import { Effect, PlatformError, Stream } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
+import { PostgresCommandError } from "#PostgresCommandError.ts";
+
+export type CommandOptions = Pick<ChildProcess.CommandOptions, "env" | "extendEnv">;
+
+export const runCommand = Effect.fn("LocalPostgres.runCommand")(function* (command: string, args: readonly string[], options: CommandOptions = {}) {
+	const label = command === "docker" ? `docker ${args[0] ?? ""}`.trim() : command;
+	return yield* Effect.scoped(
+		Effect.gen(function* () {
+			const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+			const child = yield* spawner.spawn(ChildProcess.make(command, args, { ...options, stdin: "ignore" }));
+			const [stdout, stderr, code] = yield* Effect.all(
+				[Stream.mkString(Stream.decodeText(child.stdout)), Stream.mkString(Stream.decodeText(child.stderr)), child.exitCode],
+				{ concurrency: "unbounded" },
+			);
+			if (code !== 0) {
+				return yield* new PostgresCommandError({
+					command: label,
+					exitCode: Number(code),
+					message: stderr.trim() || `${command} exited with code ${code}.`,
+				});
+			}
+			return stdout.trim();
+		}),
+	).pipe(Effect.catchTag("PlatformError", (cause) => Effect.fail(new PostgresCommandError({ cause, command: label, message: cause.message }))));
+});
+
+export function missingCommand(error: PostgresCommandError) {
+	return error.cause instanceof PlatformError.PlatformError && error.cause.reason._tag === "NotFound";
+}