@shivaedev/sql 0.25.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/sql",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Schema-derived repositories over native Effect SQL",
   "keywords": [
     "effect"
@@ -43,25 +43,30 @@
     "README.md"
   ],
   "dependencies": {
-    "@shivaedev/changes": "0.5.1"
+    "@shivaedev/changes": "0.5.1",
+    "@shivaedev/service": "0.6.0"
   },
   "devDependencies": {
     "@effect/platform-node": "4.0.6",
     "@effect/sql-pg": "4.0.6",
     "@effect/sql-sqlite-node": "4.0.6",
-    "@shivaedev/quality": "0.45.0",
-    "@shivaedev/service": "0.5.1",
-    "@shivaedev/test": "0.10.1",
-    "@shivaedev/test-sql": "0.11.0",
-    "@shivaedev/test-story": "0.24.0",
+    "@shivaedev/quality": "0.46.0",
+    "@shivaedev/test-sql": "0.12.0",
+    "@shivaedev/test-story": "0.25.0",
     "@types/node": "24.19.2",
     "effect": "4.0.6",
     "typescript": "7.0.2",
     "vitest": "5.0.5"
   },
   "peerDependencies": {
+    "@effect/sql-pg": "4.0.6",
     "effect": "4.0.6"
   },
+  "peerDependenciesMeta": {
+    "@effect/sql-pg": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=24"
   },

package/src/PostgresListenerError.ts

@@ -0,0 +1,9 @@
+import { Data } from "effect";
+
+export class PostgresListenerError extends Data.TaggedError("PostgresListenerError")<{
+	readonly connectionSetting: string;
+}> {
+	override get message() {
+		return `PostgreSQL change listener heartbeat timed out without receiving its own notification. Set ${this.connectionSetting} to a direct or session-mode connection to the application database.`;
+	}
+}

package/src/SchemaComponent.ts

@@ -1,12 +1,12 @@
 import { Effect } from "effect";
-import { Migrator, type SqlClient } from "effect/sql";
+import type { SqlClient } from "effect/sql";
 
-export interface SchemaComponent<R = never> {
-	readonly apply: Effect.Effect<unknown, unknown, R | SqlClient.SqlClient>;
+export interface SchemaComponent<R = never, E = unknown> {
+	readonly apply: Effect.Effect<unknown, E, R | SqlClient.SqlClient>;
 	readonly name: string;
-	readonly pending: Effect.Effect<string | undefined, unknown, R | SqlClient.SqlClient>;
+	readonly pending: Effect.Effect<string | undefined, E, R | SqlClient.SqlClient>;
 }
 
-export function runSchemaComponent<A, R>(name: string, effect: Effect.Effect<A, unknown, R>) {
-	return effect.pipe(Effect.mapError((cause) => new Migrator.MigrationError({ cause, kind: "Failed", message: `Schema component ${name} failed.` })));
+export function runSchemaComponent<A, E, R>(name: string, effect: Effect.Effect<A, E, R>) {
+	return effect.pipe(Effect.tapCause((cause) => Effect.logError(`Schema component ${name} failed.`, cause)));
 }

package/src/WorkerRelease.ts

@@ -1,11 +1,6 @@
-import { Context, Effect, type Scope, Semaphore } from "effect";
-
-export class WorkerRelease extends Context.Service<
-	WorkerRelease,
-	{
-		readonly register: <E>(control: (active: boolean) => Effect.Effect<void, E>) => Effect.Effect<void, E, Scope.Scope>;
-	}
->()("@shivaedev/sql/WorkerRelease") {}
+import { Effect, Semaphore } from "effect";
+import { defineService } from "@shivaedev/service/defineService.ts";
+import { genericMethod } from "@shivaedev/service/genericMethod.ts";
 
 export const makeWorkerRelease = Effect.fn("EffectSql.makeWorkerRelease")(function* () {
 	const mutex = Semaphore.makeUnsafe(1);
@@ -23,7 +18,7 @@ export const makeWorkerRelease = Effect.fn("EffectSql.makeWorkerRelease")(functi
 		return Effect.acquireRelease(locked(attach), () => locked(detach));
 	}
 	return {
-		service: WorkerRelease.of({ register }),
+		service: { register },
 		setActive: (next: boolean) =>
 			locked(
 				Effect.gen(function* () {
@@ -36,3 +31,10 @@ export const makeWorkerRelease = Effect.fn("EffectSql.makeWorkerRelease")(functi
 			).pipe(Effect.uninterruptible),
 	};
 });
+
+export const WorkerRelease = defineService({
+	id: "@shivaedev/sql/WorkerRelease",
+	initialize: makeWorkerRelease(),
+	methods: ({ service }) => ({ register: genericMethod(service.register) }),
+	requires: [],
+});

package/src/adapters/makePostgresClient.ts

@@ -0,0 +1,72 @@
+import * as PgClient from "@effect/sql-pg/PgClient";
+import type * as PgConnection from "@effect/sql-pg/PgConnection";
+import * as PgPool from "@effect/sql-pg/PgPool";
+import { Effect, Predicate, Stream } from "effect";
+import { SqlClient, type SqlConnection, Statement } from "effect/sql";
+import { SqlError, UnknownError } from "effect/sql/SqlError";
+
+const json = Statement.custom<PgClient.PgCustom>("PgJson");
+
+export const makePostgresClient = Effect.fn("Sql.makePostgresClient")(function* (config: PgClient.PgClientConfig) {
+	const pool = yield* PgPool.PgPool;
+	const acquirer = Effect.map(pool.get, postgresConnection);
+	const client = yield* SqlClient.make({
+		acquirer,
+		borrower: (use) => pool.use((connection) => use(postgresConnection(connection))),
+		commit,
+		compiler: PgClient.makeCompiler(config.transformQueryNames),
+		driver: "pg",
+		prepareTransactionControls: true,
+		releaseSavepoint: (name) => `RELEASE SAVEPOINT ${name}`,
+		spanAttributes: [
+			["db.system.name", "postgresql"],
+			["db.namespace", config.database ?? config.username ?? "postgres"],
+			["server.address", config.host ?? "localhost"],
+			["server.port", config.port ?? 5432],
+		],
+		transactionAcquirer: Effect.map(pool.reserve, postgresConnection),
+		transformRows: config.transformResultNames === undefined ? undefined : Statement.defaultTransforms(config.transformResultNames).array,
+	});
+	return Object.assign(client, {
+		[PgClient.TypeId]: PgClient.TypeId,
+		config,
+		json: (value: unknown) => Statement.fragment([json(value)]),
+		listen: (channel: string) => Effect.flatMap(pool.reserve, (connection) => connection.listen(channel)),
+		notify: (channel: string, payload: string) =>
+			pool.use((connection) => connection.query("SELECT pg_notify($1, $2)", [channel, payload])).pipe(Effect.asVoid),
+	}) satisfies PgClient.PgClient;
+});
+
+function postgresConnection(connection: PgConnection.PgConnection): SqlConnection.Connection {
+	function execute(sql: string, params: readonly unknown[], transformRows: Parameters<SqlConnection.Connection["execute"]>[2], prepare = true) {
+		const rows = Effect.map(connection.query(sql, params, prepare), (result) => result.rows);
+		return transformRows === undefined ? rows : Effect.map(rows, transformRows);
+	}
+	return {
+		execute,
+		executeRaw: (sql, params) => connection.query(sql, params),
+		executeStream: (sql, params, transformRows) => {
+			const stream = connection.stream(sql, params);
+			return transformRows === undefined ? stream : Stream.mapArray(stream, (rows) => [transformRows(rows)]).pipe(Stream.flattenIterable);
+		},
+		executeUnprepared: (sql, params, transformRows) => execute(sql, params, transformRows, false),
+		executeValues: (sql, params) => connection.queryValues(sql, params),
+		executeValuesUnprepared: (sql, params) => connection.queryValues(sql, params, false),
+	};
+}
+
+function commit(connection: SqlConnection.Connection) {
+	return Effect.flatMap(connection.executeRaw("COMMIT", []), (result) =>
+		Predicate.hasProperty(result, "command") && result.command === "ROLLBACK"
+			? Effect.fail(
+					new SqlError({
+						reason: new UnknownError({
+							cause: new Error("COMMIT rolled back an aborted transaction"),
+							message: "PgClient: COMMIT rolled back an aborted transaction",
+							operation: "commit",
+						}),
+					}),
+				)
+			: Effect.void,
+	);
+}

package/src/adapters/postgresStream.ts

@@ -0,0 +1,26 @@
+import { createConnection } from "node:net";
+import type { PgPoolConfig } from "@effect/sql-pg/PgClient";
+import { Effect, Redacted } from "effect";
+
+export const postgresStream = Effect.fn("Sql.postgresStream")(function* (
+	url: Redacted.Redacted<string>,
+	address: Pick<PgPoolConfig, "host" | "port">,
+) {
+	const disconnected = new Set<Promise<void>>();
+	// Native pool shutdown sends Terminate without waiting for its sockets to close.
+	yield* Effect.addFinalizer(() => Effect.promise(() => Promise.all([...disconnected])));
+	return () => {
+		const target = new URL(Redacted.value(url));
+		const host = address.host ?? target.searchParams.getAll("host").at(-1) ?? (decodeURIComponent(target.hostname) || "localhost");
+		const port = address.port ?? 5432;
+		const socket = createConnection(host.startsWith("/") ? { path: `${host}/.s.PGSQL.${port}` } : { host, noDelay: true, port });
+		const closed = new Promise<void>((resolve) =>
+			socket.once("close", () => {
+				disconnected.delete(closed);
+				resolve();
+			}),
+		);
+		disconnected.add(closed);
+		return socket;
+	};
+});

package/src/assertPostgresMigrations.ts

@@ -3,8 +3,8 @@ import { Migrator } from "effect/sql";
 import type { PostgresMigrationOptions } from "./migrations.ts";
 import { type PendingPostgresMigrations, pendingPostgresMigrations } from "./pendingPostgresMigrations.ts";
 
-export const assertPostgresMigrations = Effect.fn("EffectSql.assertPostgresMigrations")(function* <R>(
-	options: Pick<PostgresMigrationOptions<R>, "loader" | "table" | "components" | "release">,
+export const assertPostgresMigrations = Effect.fn("EffectSql.assertPostgresMigrations")(function* <R, E = never>(
+	options: Pick<PostgresMigrationOptions<R, E>, "loader" | "table" | "components" | "release">,
 ) {
 	const pending = yield* pendingPostgresMigrations(options);
 	if (pending.migrations.length > 0 || pending.components.length > 0) {

package/src/coordinateWorkerRelease.ts

@@ -1,4 +1,5 @@
-import { Duration, Effect } from "effect";
+import { Duration, Effect, Exit, Schedule, Scope } from "effect";
+import { isSqlError } from "effect/sql/SqlError";
 import { readPostgresRelease } from "./postgresRelease.ts";
 import { releaseWorkers } from "./releaseWorkers.ts";
 import { makeWorkerRelease } from "./WorkerRelease.ts";
@@ -9,6 +10,8 @@ export const coordinateWorkerRelease = Effect.fn("EffectSql.coordinateWorkerRele
 	table = "effect_sql_migrations",
 ) {
 	const gate = yield* makeWorkerRelease();
+	const scope = yield* Scope.fork(yield* Effect.scope);
+	const retries = Schedule.spaced(Duration.toMillis(pollInterval) / 4).pipe(Schedule.upTo({ times: 3 }));
 	const rows = yield* releaseWorkers(release, Duration.toMillis(pollInterval) * 5, table);
 	let claimed = false;
 	const poll = Effect.gen(function* () {
@@ -24,10 +27,33 @@ export const coordinateWorkerRelease = Effect.fn("EffectSql.coordinateWorkerRele
 			}
 		}
 	});
-	yield* Effect.addFinalizer(() => rows.remove.pipe(Effect.orDie));
+	function tick<A, E, R>(name: string, effect: Effect.Effect<A, E, R>) {
+		return effect.pipe(
+			Effect.tapCause((cause) => Effect.logWarning(`Worker release ${name} failed`, cause)),
+			Effect.retry({ schedule: retries, while: isSqlError }),
+		);
+	}
+	function loop<E, R>(name: string, effect: Effect.Effect<unknown, E, R>) {
+		return Effect.forever(Effect.sleep(pollInterval).pipe(Effect.andThen(tick(name, effect)))).pipe(
+			Effect.catchCause((cause) =>
+				Effect.logError(`Worker release ${name} stopped; closing worker scope`, cause).pipe(
+					Effect.andThen(Scope.close(scope, Exit.failCause(cause))),
+				),
+			),
+			Scope.provide(scope),
+			Effect.forkIn(scope),
+		);
+	}
+	yield* Scope.addFinalizer(
+		scope,
+		rows.remove.pipe(
+			Effect.tapCause((cause) => Effect.logError("Worker release cleanup failed", cause)),
+			Effect.orDie,
+		),
+	);
 	// Heartbeats continue while offWork waits for active jobs to finish.
-	yield* Effect.forever(Effect.sleep(pollInterval).pipe(Effect.andThen(rows.heartbeat))).pipe(Effect.orDie, Effect.forkScoped);
-	yield* poll;
-	yield* Effect.forever(Effect.sleep(pollInterval).pipe(Effect.andThen(poll))).pipe(Effect.orDie, Effect.forkScoped);
+	yield* loop("heartbeat", rows.heartbeat);
+	yield* tick("poll", poll).pipe(Scope.provide(scope));
+	yield* loop("poll", poll);
 	return gate.service;
 });

package/src/databaseAddress.ts

@@ -0,0 +1,25 @@
+import type { PgPoolConfig } from "@effect/sql-pg/PgClient";
+import { Redacted } from "effect";
+
+export function databaseAddress(value: Redacted.Redacted<string>): Pick<PgPoolConfig, "host" | "port"> {
+	try {
+		const url = new URL(Redacted.value(value));
+		if (url.protocol !== "postgres:" && url.protocol !== "postgresql:") {
+			return {};
+		}
+		const hostname = url.hostname.startsWith("[") ? url.hostname.slice(1, -1) : decodeURIComponent(url.hostname);
+		// PgConnection applies query parameters in order, after the authority.
+		const host = url.searchParams.getAll("host").at(-1) ?? hostname;
+		const rawPort = url.searchParams.getAll("port").at(-1) ?? url.port;
+		const port = rawPort === "" ? undefined : Number(rawPort);
+		if (host.includes(",") || (port !== undefined && (!Number.isInteger(port) || port < 1 || port > 65_535))) {
+			return {};
+		}
+		return {
+			...(host === "" && !url.searchParams.has("host") ? {} : { host }),
+			...(port === undefined ? {} : { port }),
+		};
+	} catch {
+		return {};
+	}
+}

package/src/internal/CommandRecovery.ts

@@ -0,0 +1,5 @@
+import { Context, Effect } from "effect";
+
+export const CommandRecovery = Context.Reference<Effect.Effect<void>>("@shivaedev/sql/CommandRecovery", {
+	defaultValue: () => Effect.void,
+});

package/src/listenForChanges.ts

@@ -1,44 +1,44 @@
-import { Clock, Deferred, type Duration, Effect, type Exit, Queue, Scope } from "effect";
+import { Clock, Deferred, type Duration, Effect, Queue, Random, Scope } from "effect";
 import * as Reactivity from "effect/reactivity/Reactivity";
-import { decodeKeys } from "./notifyPayload.ts";
+import type { SqlError } from "effect/sql/SqlError";
+import { decodeKeys, resyncPayload } from "./notifyPayload.ts";
+import { PostgresListenerError } from "./PostgresListenerError.ts";
 import type { PostgresChangesOptions } from "./postgresChanges.ts";
 
-function closeListener(scope: Scope.Closeable, outcome: Exit.Exit<unknown, unknown>, timeout: Duration.Input) {
-	return Effect.suspend(() => {
-		function bounded(finalizer: (exit: Exit.Exit<unknown, unknown>) => Effect.Effect<void>) {
-			return (exit: Exit.Exit<unknown, unknown>) => finalizer(exit).pipe(Effect.interruptible, Effect.timeoutOption(timeout), Effect.asVoid);
-		}
-		// Bound each finalizer so a stalled UNLISTEN cannot prevent the native connection release that follows it.
-		if (scope.state._tag === "Open") {
-			const state = scope.state;
-			if (state.finalizer !== undefined) {
-				state.finalizer = bounded(state.finalizer);
-			}
-			if (state.finalizers !== undefined) {
-				for (const [key, finalizer] of state.finalizers) {
-					state.finalizers.set(key, bounded(finalizer));
-				}
-			}
-		}
-		return Scope.closeUnsafe(scope, outcome) ?? Effect.void;
-	});
+function listenerScope(timeout: Duration.Input) {
+	// Release the native connection alongside listener cleanup, even when a listener finalizer stalls.
+	return Effect.acquireRelease(Scope.make("parallel"), (scope, exit) =>
+		Effect.suspend(() => Scope.closeUnsafe(scope, exit) ?? Effect.void).pipe(Effect.interruptible, Effect.timeoutOption(timeout), Effect.asVoid),
+	);
 }
 
 export const listenForChanges = Effect.fn("PostgresChanges.listenForChanges")(function* (options: PostgresChangesOptions) {
-	const ready = yield* Deferred.make<void>();
+	const ready = yield* Deferred.make<void, SqlError | PostgresListenerError>();
 	const reactivity = yield* Reactivity.Reactivity;
 	const { client, channel, resync } = options;
 	const timeout = options.heartbeatTimeout ?? "10 seconds";
+	function deadline<A, E, R>(effect: Effect.Effect<A, E, R>) {
+		return effect.pipe(
+			Effect.timeoutOrElse({
+				duration: timeout,
+				orElse: () => Effect.fail(new PostgresListenerError({ connectionSetting: options.connectionSetting ?? "client" })),
+			}),
+		);
+	}
 	let lostAt: number | undefined;
 	const attempt = Effect.scoped(
 		Effect.gen(function* () {
-			const scope = yield* Effect.acquireRelease(Scope.make(), (listenerScope, exit) => closeListener(listenerScope, exit, timeout));
-			const token = JSON.stringify({ heartbeat: crypto.randomUUID() });
+			const scope = yield* listenerScope(timeout);
+			const notifications = yield* (options.listenerClient ?? client).listen(channel).pipe(Scope.provide(scope), deadline);
+			const token = JSON.stringify({ heartbeat: `${yield* Random.nextInt}:${yield* Random.nextInt}` });
 			let ack = yield* Deferred.make<void>();
 			function receive(payload: string) {
 				if (payload === token) {
 					return Effect.asVoid(Deferred.succeed(ack, undefined));
 				}
+				if (payload === resyncPayload) {
+					return Effect.asVoid(resync);
+				}
 				if (!payload.startsWith("[")) {
 					return Effect.void;
 				}
@@ -47,17 +47,14 @@ export const listenForChanges = Effect.fn("PostgresChanges.listenForChanges")(fu
 					Effect.catchCause(() => resync),
 				);
 			}
-			const listening = Effect.gen(function* () {
-				const notifications = yield* client.listen(channel).pipe(Scope.provide(scope));
-				yield* Effect.forever(
-					Effect.flatMap(Queue.takeAll(notifications), (batch) =>
-						Effect.forEach(batch, (notification) => receive(notification.payload), { discard: true }),
-					),
-				);
-			});
+			const listening = Effect.forever(
+				Effect.flatMap(Queue.takeAll(notifications), (batch) =>
+					Effect.forEach(batch, (notification) => receive(notification.payload), { discard: true }),
+				),
+			);
 			const send = Effect.asVoid(client`select pg_notify(${channel}, ${token})`);
 			const monitor = Effect.gen(function* () {
-				yield* Effect.raceFirst(Deferred.await(ack), Effect.forever(Effect.andThen(send, Effect.sleep("50 millis")))).pipe(Effect.timeout(timeout));
+				yield* Effect.andThen(send, Deferred.await(ack)).pipe(deadline);
 				const streamCount = yield* resync;
 				if (lostAt !== undefined) {
 					const downtimeMs = (yield* Clock.currentTimeMillis) - lostAt;
@@ -71,23 +68,28 @@ export const listenForChanges = Effect.fn("PostgresChanges.listenForChanges")(fu
 					Effect.gen(function* () {
 						yield* Effect.sleep(options.heartbeatInterval ?? "5 seconds");
 						ack = yield* Deferred.make<void>();
-						yield* Effect.andThen(send, Deferred.await(ack)).pipe(Effect.timeout(timeout));
+						yield* Effect.andThen(send, Deferred.await(ack)).pipe(deadline);
 					}),
 				);
 			});
-			yield* Effect.raceFirst(listening, monitor).pipe(Effect.onExit(() => resync));
-		}),
+			yield* Effect.raceFirst(listening, monitor);
+		}).pipe(Effect.onExit(() => resync)),
 	);
 	yield* Effect.forever(
 		attempt.pipe(
-			Effect.catchCause(() =>
+			Effect.catchCause((cause) =>
 				Effect.gen(function* () {
+					if (!(yield* Deferred.isDone(ready))) {
+						yield* Effect.logError("PostgreSQL change listener startup failed", cause);
+						yield* Deferred.failCause(ready, cause);
+						return;
+					}
 					if (lostAt !== undefined) {
-						yield* Effect.logDebug("PostgreSQL change listener reconnect failed; retrying");
+						yield* Effect.logDebug("PostgreSQL change listener reconnect failed; retrying", cause);
 						return;
 					}
 					lostAt = yield* Clock.currentTimeMillis;
-					yield* Effect.logWarning("PostgreSQL change listener lost; resynchronizing live streams");
+					yield* Effect.logWarning("PostgreSQL change listener lost; resynchronizing live streams", cause);
 				}),
 			),
 			Effect.andThen(Effect.sleep(options.retryDelay ?? "1 second")),

package/src/migrations.ts

@@ -1,13 +1,14 @@
-import { Duration, Effect, Option } from "effect";
+import { Duration, Effect, Option, Schema } from "effect";
 import * as Reactivity from "effect/reactivity/Reactivity";
 import { Migrator, SqlClient } from "effect/sql";
+import type { SqlError } from "effect/sql/SqlError";
 import { advisoryXactLock } from "./advisoryXactLock.ts";
 import { postgresRelease } from "./postgresRelease.ts";
 import { runSchemaComponent, type SchemaComponent } from "./SchemaComponent.ts";
 import { transact } from "./transact.ts";
 
-export interface PostgresMigrationOptions<R> {
-	readonly components?: readonly SchemaComponent<R>[];
+export interface PostgresMigrationOptions<R, E = never> {
+	readonly components?: readonly SchemaComponent<R, E>[];
 	readonly loader: Migrator.Loader<R>;
 	readonly lockTimeout: Duration.Input;
 	readonly release?: string;
@@ -16,13 +17,13 @@ export interface PostgresMigrationOptions<R> {
 
 const migrate = Migrator.make({});
 
-export const migratePostgres = Effect.fn("EffectSql.migratePostgres")(function* <R>({
+export const migratePostgres = Effect.fn("EffectSql.migratePostgres")(function* <R, E = never>({
 	loader,
 	components = [],
 	table = "effect_sql_migrations",
 	lockTimeout,
 	release,
-}: PostgresMigrationOptions<R>) {
+}: PostgresMigrationOptions<R, E>) {
 	const sql = yield* SqlClient.SqlClient;
 	const available = yield* Effect.serviceOption(Reactivity.Reactivity);
 	const reactivity = Option.isSome(available) ? available.value : yield* Reactivity.make;
@@ -37,7 +38,9 @@ export const migratePostgres = Effect.fn("EffectSql.migratePostgres")(function*
   name text not null
 )`;
 		const current = [...(yield* loader)].sort(([left], [right]) => left - right);
-		const applied = yield* sql<{ id: number }>`select migration_id as id from ${sql(table)}`.withoutTransform;
+		const applied = yield* sql`select migration_id as id from ${sql(table)}`.withoutTransform.pipe(
+			Effect.flatMap(Schema.decodeUnknownEffect(Schema.Array(Schema.Struct({ id: Schema.Int })))),
+		);
 		const appliedIds = new Set(applied.map(({ id }) => id));
 		const latest = applied.reduce((max, { id }) => Math.max(max, id), 0);
 		const missing = current.filter(([id]) => id <= latest && !appliedIds.has(id));
@@ -51,7 +54,11 @@ export const migratePostgres = Effect.fn("EffectSql.migratePostgres")(function*
 		}
 		return yield* migrate({ loader: Effect.succeed(current), table });
 	}).pipe(transact({ onSqlError: (error) => error }), Effect.provideService(Reactivity.Reactivity, reactivity));
-	for (const component of [...components, ...(release === undefined ? [] : [postgresRelease(release, table)])]) {
+	const schemaComponents: readonly SchemaComponent<R, E | SqlError | Schema.SchemaError>[] = [
+		...components,
+		...(release === undefined ? [] : [postgresRelease(release, table)]),
+	];
+	for (const component of schemaComponents) {
 		yield* runSchemaComponent(component.name, component.apply);
 	}
 	return appliedMigrations;

package/src/notifyPayload.ts

@@ -2,6 +2,8 @@ import { Effect, Schema } from "effect";
 import { SqlError, UnknownError } from "effect/sql/SqlError";
 
 export const NotificationKeys = Schema.Array(Schema.Union([Schema.String, Schema.Finite]));
+// Older listeners reconcile unknown array entries instead of ignoring them.
+export const resyncPayload = JSON.stringify([{ _tag: "Resync" }]);
 export const decodeKeys = Schema.decodeUnknownEffect(Schema.fromJsonString(NotificationKeys));
 const encoder = new TextEncoder();
 

package/src/pendingPostgresMigrations.ts

@@ -1,30 +1,35 @@
-import { Effect } from "effect";
+import { Effect, Schema } from "effect";
 import { SqlClient } from "effect/sql";
+import type { SqlError } from "effect/sql/SqlError";
 import type { PostgresMigrationOptions } from "./migrations.ts";
 import { postgresRelease } from "./postgresRelease.ts";
-import { runSchemaComponent } from "./SchemaComponent.ts";
+import { runSchemaComponent, type SchemaComponent } from "./SchemaComponent.ts";
 
 export interface PendingPostgresMigrations {
 	readonly components: readonly { readonly name: string; readonly detail: string }[];
 	readonly migrations: readonly { readonly id: number; readonly name: string }[];
 }
 
-export const pendingPostgresMigrations = Effect.fn("EffectSql.pendingPostgresMigrations")(function* <R>({
+export const pendingPostgresMigrations = Effect.fn("EffectSql.pendingPostgresMigrations")(function* <R, E = never>({
 	loader,
 	components = [],
 	table = "effect_sql_migrations",
 	release,
-}: Pick<PostgresMigrationOptions<R>, "loader" | "table" | "components" | "release">) {
+}: Pick<PostgresMigrationOptions<R, E>, "loader" | "table" | "components" | "release">) {
 	const expected = yield* loader;
 	const migrations: { id: number; name: string }[] = [];
 	if (expected.length > 0) {
 		const sql = yield* SqlClient.SqlClient;
 		const identifier = sql`${sql(table)}`.compile()[0];
-		const [ledger] = yield* sql<{ name: string | null }>`select to_regclass(${identifier})::text as name`.withoutTransform;
+		const [ledger] = yield* sql`select to_regclass(${identifier})::text as name`.withoutTransform.pipe(
+			Effect.flatMap(Schema.decodeUnknownEffect(Schema.Array(Schema.Struct({ name: Schema.NullOr(Schema.String) })))),
+		);
 		const applied =
 			ledger === undefined || ledger.name === null
 				? []
-				: yield* sql<{ id: number; name: string }>`select migration_id as id, name from ${sql(table)}`.withoutTransform;
+				: yield* sql`select migration_id as id, name from ${sql(table)}`.withoutTransform.pipe(
+						Effect.flatMap(Schema.decodeUnknownEffect(Schema.Array(Schema.Struct({ id: Schema.Int, name: Schema.String })))),
+					);
 		for (const [id, name] of expected) {
 			if (!applied.some((row) => row.id === id && row.name === name)) {
 				migrations.push({ id, name });
@@ -32,7 +37,11 @@ export const pendingPostgresMigrations = Effect.fn("EffectSql.pendingPostgresMig
 		}
 	}
 	const pendingComponents: { name: string; detail: string }[] = [];
-	for (const component of [...components, ...(release === undefined ? [] : [postgresRelease(release, table)])]) {
+	const schemaComponents: readonly SchemaComponent<R, E | SqlError | Schema.SchemaError>[] = [
+		...components,
+		...(release === undefined ? [] : [postgresRelease(release, table)]),
+	];
+	for (const component of schemaComponents) {
 		const detail = yield* runSchemaComponent(component.name, component.pending);
 		if (detail !== undefined) {
 			pendingComponents.push({ detail, name: component.name });

package/src/postgresChanges.ts

@@ -2,8 +2,9 @@ import { Context, type Duration, Effect, Layer, type Queue, type Scope } from "e
 import * as Reactivity from "effect/reactivity/Reactivity";
 import { SqlClient } from "effect/sql";
 import type { SqlError } from "effect/sql/SqlError";
+import { CommandRecovery } from "#internal/CommandRecovery.ts";
 import { listenForChanges } from "./listenForChanges.ts";
-import { encodeKeys } from "./notifyPayload.ts";
+import { encodeKeys, resyncPayload } from "./notifyPayload.ts";
 import { BeforeCommit, CommittedSink } from "./transact.ts";
 
 export interface PostgresNotification {
@@ -17,8 +18,10 @@ export interface PostgresChangeClient extends SqlClient.SqlClient {
 export interface PostgresChangesOptions {
 	readonly channel: string;
 	readonly client: PostgresChangeClient;
+	readonly connectionSetting?: string;
 	readonly heartbeatInterval?: Duration.Input;
 	readonly heartbeatTimeout?: Duration.Input;
+	readonly listenerClient?: Pick<PostgresChangeClient, "listen">;
 	readonly resync: Effect.Effect<number>;
 	readonly retryDelay?: Duration.Input;
 }
@@ -42,7 +45,12 @@ export function postgresChanges(options: PostgresChangesOptions) {
 					sql.transactionService === options.client.transactionService ? Effect.void : Reactivity.invalidate(keys),
 				);
 			}
-			return Context.make(BeforeCommit, notify).pipe(Context.add(CommittedSink, committed));
+			const recover = options.resync.pipe(
+				Effect.andThen(options.client`select pg_notify(${options.channel}, ${resyncPayload})`),
+				Effect.catchCause((cause) => Effect.logError("Committed command Resync broadcast failed; other hosts may remain stale", cause)),
+				Effect.asVoid,
+			);
+			return Context.make(BeforeCommit, notify).pipe(Context.add(CommittedSink, committed), Context.add(CommandRecovery, recover));
 		}),
 	);
 }

package/src/postgresLayer.ts

@@ -0,0 +1,27 @@
+import * as PgClient from "@effect/sql-pg/PgClient";
+import * as PgPool from "@effect/sql-pg/PgPool";
+import { Context, Effect, Layer, type Redacted } from "effect";
+import * as Reactivity from "effect/reactivity/Reactivity";
+import { SqlClient } from "effect/sql";
+import { makePostgresClient } from "#adapters/makePostgresClient.ts";
+import { postgresStream } from "#adapters/postgresStream.ts";
+import type { SqlNameTransforms } from "#clientOptions.ts";
+import { databaseAddress } from "#databaseAddress.ts";
+
+export interface PostgresOptions extends SqlNameTransforms {
+	readonly applicationName?: string | undefined;
+	readonly maxConnections?: number | undefined;
+}
+
+export function postgresLayer(url: Redacted.Redacted<string>, options?: PostgresOptions) {
+	return Layer.effectContext(
+		Effect.gen(function* () {
+			const address = databaseAddress(url);
+			const stream = yield* postgresStream(url, address);
+			const config = { ...options, ...address, stream, url };
+			const pool = yield* PgPool.make(config);
+			const client = yield* makePostgresClient(config).pipe(Effect.provideService(PgPool.PgPool, pool));
+			return Context.make(PgPool.PgPool, pool).pipe(Context.add(PgClient.PgClient, client), Context.add(SqlClient.SqlClient, client));
+		}),
+	).pipe(Layer.provide(Reactivity.layer));
+}