@shivaedev/jobs 0.0.0 → 0.19.0

package/src/server/internal/settleDeferral.ts

@@ -0,0 +1,54 @@
+import { Schema } from "effect";
+import type { Job } from "pg-boss";
+import type { PgBossClient } from "#client.ts";
+import { STATELY_DEFERRAL_POLICY } from "#internal/deferral.ts";
+import { quotedSchema } from "#internal/storedRows.ts";
+
+const Settlement = Schema.Struct({ claimed: Schema.Boolean, deferred: Schema.Boolean });
+
+export async function settleDeferral(client: PgBossClient, schema: string, job: Job<unknown>, at: string, reason: string, maxDeferrals: number) {
+	if (client.getDb === undefined) {
+		throw new TypeError("This pg-boss client does not support getDb for RetryAt");
+	}
+	const quoted = quotedSchema(schema);
+	// Native failure settlement deletes and reinserts jobs, so a cascading job foreign key would erase the counter.
+	const { rows } = await client.getDb().executeSql(
+		`WITH claimed AS MATERIALIZED (
+			SELECT name, id, created_on,
+				GREATEST(keep_until, $4::timestamptz + (keep_until - start_after)) AS keep_until
+			FROM ${quoted}.job
+			WHERE name = $1 AND id = $2 AND state = 'active' AND retry_count = $3
+			AND date_trunc('milliseconds', started_on) = $6::timestamptz
+			FOR UPDATE
+		), counted AS (
+			INSERT INTO ${quoted}.effect_job_deferral AS previous (name, id, created_on, count, keep_until)
+			SELECT name, id, created_on, 1, keep_until FROM claimed
+			ON CONFLICT (name, id) DO UPDATE SET
+				count = CASE WHEN previous.created_on = EXCLUDED.created_on THEN previous.count + 1 ELSE 1 END,
+				created_on = EXCLUDED.created_on, keep_until = EXCLUDED.keep_until
+			WHERE previous.created_on <> EXCLUDED.created_on OR previous.count < $7
+			RETURNING name, id, keep_until
+		), deferred AS (
+			UPDATE ${quoted}.job AS job SET state = 'retry', start_after = $4::timestamptz,
+				policy = CASE WHEN job.policy = 'stately' THEN '${STATELY_DEFERRAL_POLICY}' ELSE job.policy END,
+				keep_until = counted.keep_until, started_on = NULL, heartbeat_on = NULL,
+				output = jsonb_build_object('jobDeferral', jsonb_build_object('at', $4::text, 'reason', $5::text))
+			FROM counted WHERE job.name = counted.name AND job.id = counted.id
+			RETURNING job.id
+		), cleaned AS (
+			DELETE FROM ${quoted}.effect_job_deferral WHERE (name, id) IN (
+				SELECT stale.name, stale.id FROM ${quoted}.effect_job_deferral AS stale
+				WHERE EXISTS (SELECT 1 FROM counted) AND stale.keep_until < ${quoted}.job_now()
+				AND (stale.name, stale.id) <> ($1, $2)
+				AND NOT EXISTS (
+					SELECT 1 FROM ${quoted}.job AS live
+					WHERE live.name = stale.name AND live.id = stale.id AND live.created_on = stale.created_on
+				)
+				ORDER BY stale.name, stale.id LIMIT 100 FOR UPDATE OF stale SKIP LOCKED
+			)
+		)
+		SELECT EXISTS (SELECT 1 FROM claimed) AS claimed, EXISTS (SELECT 1 FROM deferred) AS deferred`,
+		[job.name, job.id, job.retryCount, at, reason, Reflect.get(job, "startedOn"), maxDeferrals],
+	);
+	return Schema.decodeUnknownSync(Settlement)(rows[0]);
+}

package/src/server/internal/storedRows.ts

@@ -0,0 +1,17 @@
+import { Effect, Redacted, Schema } from "effect";
+import type { JobPayloadSchema, QueueDefinition } from "#definition.ts";
+import { PgBossPayloadError } from "#error.ts";
+import { payloadOf } from "#internal/tracing.ts";
+
+export function quotedSchema(schema: string): string {
+	return `"${schema.replaceAll('"', '""')}"`;
+}
+
+export function decodeStoredData<const TName extends string, const TPayload extends JobPayloadSchema>(
+	queue: Pick<QueueDefinition<TName, TPayload>, "name" | "schema">,
+	data: unknown,
+): Effect.Effect<TPayload["Type"], PgBossPayloadError, TPayload["DecodingServices"]> {
+	return Schema.decodeUnknownEffect(queue.schema)(payloadOf(data)).pipe(
+		Effect.mapError((error) => new PgBossPayloadError({ direction: "decode", original: Redacted.make(error), queue: queue.name })),
+	);
+}

package/src/server/internal/testingClient.ts

@@ -0,0 +1,134 @@
+import type { Job, PgBoss, SendOptions, UpdateOptions, UpdateRequest, UpdateResponse } from "pg-boss";
+import type { PgBossClient } from "#client.ts";
+import { deferralObservers } from "#internal/deferral.ts";
+import { expireAttempt } from "#internal/expireAttempt.ts";
+import { observeTestingSettlements } from "#internal/observeTestingSettlements.ts";
+import { testingExpirations } from "#internal/testingExpirations.ts";
+import type { TestingBatch, TestingWork } from "#internal/testingIdle.ts";
+
+export interface TestingControls {
+	readonly changed: () => void;
+	readonly expirations: Map<string, number>;
+	readonly expirySeconds: Map<string, number>;
+	readonly failures: Set<string>;
+	readonly retryPolicy: Pick<SendOptions, "retryBackoff" | "retryDelay">;
+	readonly work: TestingWork;
+}
+
+export function testingClient(client: PgBoss, schema: string, controls: TestingControls): PgBossClient {
+	const settlements = observeTestingSettlements(client, (name) => {
+		for (const batch of controls.work.batches) {
+			if (batch.name === name) {
+				batch.settled = true;
+			}
+		}
+		controls.changed();
+	});
+	const expirations = testingExpirations(client);
+	function update(request: UpdateRequest): Promise<UpdateResponse>;
+	function update(name: string, data: object | null | undefined, options?: UpdateOptions): Promise<UpdateResponse>;
+	async function update(request: string | UpdateRequest, data?: object | null, options?: UpdateOptions): Promise<UpdateResponse> {
+		const result = typeof request === "string" ? await client.update(request, data, options) : await client.update(request);
+		controls.changed();
+		return result;
+	}
+	const overrides: Partial<PgBossClient> = {
+		complete: async (...args) => {
+			const result = await client.complete(...args);
+			controls.changed();
+			return result;
+		},
+		createQueue: (name, options) => {
+			const { retryDelayMax, ...rest } = options ?? {};
+			return client.createQueue(name, {
+				...rest,
+				...(controls.retryPolicy.retryBackoff === false || retryDelayMax === undefined ? {} : { retryDelayMax }),
+				...controls.retryPolicy,
+			});
+		},
+		fail: async (...args) => {
+			const result = await client.fail(...args);
+			controls.changed();
+			return result;
+		},
+		retry: async (...args) => {
+			const result = await client.retry(...args);
+			controls.changed();
+			return result;
+		},
+		send: async (name, data, options) => {
+			if (controls.failures.delete(name)) {
+				throw new Error("Injected pg-boss send failure");
+			}
+			const attempts = controls.expirations.get(name);
+			const expireInSeconds = controls.expirySeconds.get(name);
+			const { retryDelayMax, ...rest } = options ?? {};
+			const id = await expirations.send(
+				name,
+				data,
+				{
+					...rest,
+					...(controls.retryPolicy.retryBackoff === false || retryDelayMax === undefined ? {} : { retryDelayMax }),
+					...controls.retryPolicy,
+					...(attempts === undefined ? {} : { retryLimit: attempts - 1 }),
+					...(expireInSeconds === undefined ? {} : { expireInSeconds }),
+				},
+				attempts,
+			);
+			controls.changed();
+			return id;
+		},
+		stop: async (options) => {
+			try {
+				await client.stop(options);
+			} finally {
+				settlements.close();
+			}
+		},
+		update,
+		updateQueue: (name, options) =>
+			client.updateQueue(name, {
+				...options,
+				...controls.retryPolicy,
+				...(controls.retryPolicy.retryBackoff === false ? { retryDelayMax: null } : {}),
+			}),
+		work: (name, options, handler) => {
+			settlements.watch(name);
+			controls.work.queues.add(name);
+			return client.work(name, options, async (jobs: Job<unknown>[]) => {
+				const batch: TestingBatch = { name, settled: false };
+				controls.work.batches.add(batch);
+				controls.changed();
+				try {
+					const ready: Job<unknown>[] = [];
+					for (const job of jobs) {
+						const attempts = await expirations.attemptsFor(job);
+						if (attempts !== undefined && job.retryCount + 1 >= attempts) {
+							await expireAttempt(client, schema, job);
+						} else {
+							ready.push(job);
+						}
+					}
+					if (ready.length > 0) {
+						await handler(ready);
+					}
+				} finally {
+					controls.work.batches.delete(batch);
+					controls.changed();
+				}
+			});
+		},
+	};
+	const wrapped = new Proxy(client, {
+		get(target, property) {
+			if (Object.hasOwn(overrides, property)) {
+				const override: unknown = Reflect.get(overrides, property);
+				return override;
+			}
+			const value: unknown = Reflect.get(target, property);
+			return typeof value === "function" ? value.bind(target) : value;
+		},
+	});
+	deferralObservers.set(wrapped, controls.changed);
+	return wrapped;
+}

package/src/server/internal/testingDeferrals.ts

@@ -0,0 +1,44 @@
+import { DateTime } from "effect";
+import type { PgBoss } from "pg-boss";
+import type { QueueDefinition } from "#definition.ts";
+import { deferralOf } from "#internal/deferral.ts";
+import { quotedSchema } from "#internal/storedRows.ts";
+import { testingOperation } from "#internal/testingReadout.ts";
+
+export function testingDeferrals(client: () => PgBoss, schema: () => string, changed: () => void) {
+	return {
+		deferred: (queue: Pick<QueueDefinition, "name">) =>
+			testingOperation(
+				"deferred",
+				async () => {
+					const jobs = await client().findJobs(queue.name);
+					return jobs.flatMap((job) => {
+						const deferral = job.state === "retry" && job.startedOn === null ? deferralOf(job) : undefined;
+						return deferral === undefined ? [] : [{ at: DateTime.makeUnsafe(job.startAfter), reason: deferral.reason }];
+					});
+				},
+				queue.name,
+			),
+		runDeferredNow: (queue: Pick<QueueDefinition, "name">) =>
+			testingOperation(
+				"runDeferredNow",
+				async () => {
+					const quoted = quotedSchema(schema());
+					await client()
+						.getDb()
+						.executeSql(
+							`UPDATE ${quoted}.job SET start_after = ${quoted}.job_now()
+				WHERE name = $1 AND state = 'retry' AND output ? 'jobDeferral' AND started_on IS NULL`,
+							[queue.name],
+						);
+					changed();
+					for (const worker of client()
+						.getWipData()
+						.filter((candidate) => candidate.name === queue.name)) {
+						client().notifyWorker(worker.id);
+					}
+				},
+				queue.name,
+			),
+	};
+}

package/src/server/internal/testingExpirations.ts

@@ -0,0 +1,31 @@
+import type { Job, PgBoss, SendOptions } from "pg-boss";
+
+export function testingExpirations(client: PgBoss) {
+	const snapshots = new Map<string, Promise<number | undefined>>();
+	return {
+		attemptsFor: (job: Job<unknown>) => snapshots.get(`${job.name}:${job.id}`),
+		send(name: string, data: object | null | undefined, options: SendOptions, attempts: number | undefined) {
+			if (attempts === undefined && options.id === undefined) {
+				return client.send(name, data, options);
+			}
+			const id = options.id ?? crypto.randomUUID();
+			const key = `${name}:${id}`;
+			const previous = snapshots.get(key);
+			const sending = client.send(name, data, { ...options, id });
+			// A worker may claim the row before send returns. Wait for its result before applying the snapshot.
+			const snapshot = sending
+				.then(
+					(sent) => (sent === id ? attempts : previous),
+					() => previous,
+				)
+				.then((value) => {
+					if (value === undefined && snapshots.get(key) === snapshot) {
+						snapshots.delete(key);
+					}
+					return value;
+				});
+			snapshots.set(key, snapshot);
+			return sending;
+		},
+	};
+}

package/src/server/internal/testingIdle.ts

@@ -0,0 +1,52 @@
+import { Effect, Schema } from "effect";
+import type { PgBoss } from "pg-boss";
+import type { PgBossTestingError } from "#error.ts";
+import { quotedSchema } from "#internal/storedRows.ts";
+import { testingOperation } from "#internal/testingReadout.ts";
+
+export interface TestingBatch {
+	readonly name: string;
+	settled: boolean;
+}
+
+export interface TestingWork {
+	readonly batches: Set<TestingBatch>;
+	readonly queues: Set<string>;
+}
+
+const Busy = Schema.Struct({ busy: Schema.Boolean });
+
+export function testingIdle(
+	client: () => PgBoss,
+	schema: () => string,
+	work: TestingWork,
+	signal: { readonly revision: Effect.Effect<number>; readonly waitForChange: (after: number) => Effect.Effect<number> },
+): Effect.Effect<void, PgBossTestingError> {
+	const busy = testingOperation("waitForIdle", async () => {
+		const quoted = quotedSchema(schema());
+		const { rows } = await client()
+			.getDb()
+			.executeSql(
+				`/* jobs testing idle */ SELECT EXISTS (
+					SELECT 1 FROM ${quoted}.job
+					WHERE name = ANY($1::text[]) AND (
+						(state < 'active' AND NOT blocked AND start_after <= ${quoted}.job_now())
+						OR state = 'active'
+					)
+				) AS busy`,
+				[[...work.queues]],
+			);
+		return (await Schema.decodeUnknownPromise(Busy)(rows[0])).busy;
+	});
+	return Effect.gen(function* () {
+		while (true) {
+			const revision = yield* signal.revision;
+			// A batch with no settlement since its fetch still holds active jobs, so it is busy without a read.
+			const unsettled = [...work.batches].some((batch) => !batch.settled);
+			if (work.queues.size === 0 || !(unsettled || (yield* busy))) {
+				return;
+			}
+			yield* signal.waitForChange(revision);
+		}
+	});
+}

package/src/server/internal/testingReadout.ts

@@ -0,0 +1,19 @@
+import { Effect, Redacted } from "effect";
+import type { FindJobsOptions, PgBoss } from "pg-boss";
+import type { JobPayloadSchema, QueueDefinition } from "#definition.ts";
+import { PgBossTestingError } from "#error.ts";
+import { decodeStoredData } from "#internal/storedRows.ts";
+
+export function testingOperation<A>(operation: string, run: () => Promise<A>, queue?: string) {
+	return Effect.tryPromise({
+		catch: (original) => new PgBossTestingError({ operation, original: Redacted.make(original), queue }),
+		try: run,
+	});
+}
+
+export function testingReadout(client: () => PgBoss) {
+	return <TName extends string, TPayload extends JobPayloadSchema>(queue: QueueDefinition<TName, TPayload>, options?: FindJobsOptions) =>
+		testingOperation("jobs", () => client().findJobs<unknown>(queue.name, options), queue.name).pipe(
+			Effect.flatMap((jobs) => Effect.forEach(jobs, (job) => decodeStoredData(queue, job.data).pipe(Effect.map((data) => ({ ...job, data }))))),
+		);
+}

package/src/server/internal/testingSignal.ts

@@ -0,0 +1,30 @@
+import { Effect } from "effect";
+
+export function testingSignal() {
+	let revision = 0;
+	const listeners = new Set<(revision: number) => void>();
+	return {
+		changed() {
+			revision += 1;
+			// A resumed waiter can wait again synchronously; it must wait for the next change, not this one.
+			const waiting = [...listeners];
+			listeners.clear();
+			for (const listener of waiting) {
+				listener(revision);
+			}
+		},
+		revision: Effect.sync(() => revision),
+		waitForChange: (after: number): Effect.Effect<number> =>
+			Effect.callback((resume) => {
+				if (revision !== after) {
+					resume(Effect.succeed(revision));
+					return;
+				}
+				function listener(current: number) {
+					resume(Effect.succeed(current));
+				}
+				listeners.add(listener);
+				return Effect.sync(() => listeners.delete(listener));
+			}),
+	};
+}

package/src/server/internal/testingSnapshot.ts

@@ -0,0 +1,53 @@
+import { Effect, Schema } from "effect";
+import type { PgBoss } from "pg-boss";
+import type { PgBossPayloadError, PgBossTestingError } from "#error.ts";
+import { decodeStoredData, quotedSchema } from "#internal/storedRows.ts";
+import { testingOperation } from "#internal/testingReadout.ts";
+import type { SnapshotQueue, UnfinishedJob } from "#testing.ts";
+
+const Rows = Schema.Array(
+	Schema.Struct({
+		data: Schema.Unknown,
+		id: Schema.String,
+		queue: Schema.String,
+		startAfter: Schema.DateTimeUtcFromDate,
+		state: Schema.Literals(["created", "retry", "active", "failed"]),
+	}),
+);
+
+export function testingSnapshot(client: () => PgBoss, schema: () => string) {
+	return <const TQueues extends readonly SnapshotQueue[]>(
+		queues: TQueues,
+	): Effect.Effect<
+		readonly UnfinishedJob<TQueues[number]>[],
+		PgBossPayloadError | PgBossTestingError,
+		TQueues[number]["schema"]["DecodingServices"]
+	> => {
+		const byName = new Map<string, TQueues[number]>(queues.map((queue) => [queue.name, queue]));
+		return testingOperation("snapshot", async () => {
+			const quoted = quotedSchema(schema());
+			const { rows } = await client()
+				.getDb()
+				.executeSql(
+					`SELECT id, name AS queue, state, data, start_after AS "startAfter"
+					FROM ${quoted}.job
+					WHERE name = ANY($1::text[]) AND state IN ('created', 'retry', 'active', 'failed')
+					ORDER BY created_on, id`,
+					[[...byName.keys()]],
+				);
+			return Schema.decodeUnknownPromise(Rows)(rows);
+		}).pipe(
+			Effect.flatMap((rows) =>
+				Effect.forEach(rows, ({ data, queue: name, ...row }) => {
+					const queue = byName.get(name);
+					if (queue === undefined) {
+						return Effect.die(new Error(`The snapshot returned a job of an unrequested queue ${name}`));
+					}
+					return decodeStoredData<TQueues[number]["name"], TQueues[number]["schema"]>(queue, data).pipe(
+						Effect.map((decoded): UnfinishedJob<TQueues[number]> => ({ ...row, data: decoded, queue: queue.name })),
+					);
+				}),
+			),
+		);
+	};
+}

package/src/server/internal/tracing.ts

@@ -0,0 +1,44 @@
+import { Effect, Option, Schema, Tracer } from "effect";
+import type { Job } from "pg-boss";
+
+const TracedPayload = Schema.Struct({
+	_tag: Schema.Literal("@shivaedev/jobs/TracedPayload"),
+	payload: Schema.Unknown,
+	span: Schema.Struct({ sampled: Schema.Boolean, spanId: Schema.String, traceId: Schema.String }),
+});
+
+const isTracedPayload = Schema.is(TracedPayload);
+
+export function capturePayload(payload: object): Effect.Effect<object> {
+	return Effect.map(Effect.option(Effect.currentParentSpan), (span) =>
+		Option.isNone(span)
+			? payload
+			: ({
+					_tag: "@shivaedev/jobs/TracedPayload",
+					payload,
+					span: { sampled: span.value.sampled, spanId: span.value.spanId, traceId: span.value.traceId },
+				} satisfies typeof TracedPayload.Type),
+	);
+}
+
+export function payloadOf(data: unknown): unknown {
+	return isTracedPayload(data) ? data.payload : data;
+}
+
+export function traceJob<A, E, R>(effect: Effect.Effect<A, E, R>, job: Job<unknown>, queue: string) {
+	return Effect.withSpan(effect, queue, {
+		attributes: {
+			"job.attempt": job.retryCount + 1,
+			"job.id": job.id,
+			"job.name": job.name,
+			"job.queue": queue,
+			"job.retry_count": job.retryCount,
+			"messaging.destination.name": queue,
+			"messaging.message.id": job.id,
+			"messaging.system": "pg-boss",
+		},
+		kind: "consumer",
+		links: isTracedPayload(job.data) ? [{ attributes: {}, span: Tracer.externalSpan(job.data.span) }] : [],
+		root: true,
+	});
+}

package/src/server/internal/waitForBatchExpiry.ts

@@ -0,0 +1,30 @@
+import { Clock, Effect } from "effect";
+import type { Job } from "pg-boss";
+import type { PgBossClient } from "#client.ts";
+import { type PgBossError, toPgBossError } from "#error.ts";
+import { deadlineOf } from "#internal/deadlineOf.ts";
+
+export function waitForBatchExpiry(client: PgBossClient, name: string, jobs: readonly Job<unknown>[]): Effect.Effect<void, PgBossError> {
+	return Effect.gen(function* () {
+		const findJobs = client.findJobs?.bind(client);
+		if (findJobs === undefined) {
+			return yield* Effect.fail(new TypeError("This pg-boss client does not support reading interrupted claims"));
+		}
+		const deadline = Math.max(0, ...jobs.map(deadlineOf)) + 1000;
+		let delay = 25;
+		const poll = Effect.gen(function* () {
+			for (const job of jobs) {
+				while (true) {
+					const current = (yield* Effect.tryPromise({ catch: (error) => error, try: () => findJobs(name, { id: job.id }) }))[0];
+					if (current?.state !== "active" || current.retryCount !== job.retryCount) {
+						break;
+					}
+					// Aborting the signal precedes pg-boss's failure write; returning early would complete this claim.
+					yield* Effect.sleep(delay);
+					delay = Math.min(delay * 2, 500);
+				}
+			}
+		});
+		return yield* poll.pipe(Effect.timeout(Math.max(0, deadline - (yield* Clock.currentTimeMillis))));
+	}).pipe(Effect.mapError((error) => toPgBossError("settle", error, name)));
+}

package/src/server/schema.ts

@@ -0,0 +1,84 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import type { Connection } from "effect/sql/SqlConnection";
+import { getConstructionPlans, getMigrationPlans, type MigrationPartition, PgBoss } from "pg-boss";
+import pgBossPackage from "pg-boss/package.json" with { type: "json" };
+import type { SchemaComponent } from "@shivaedev/sql/SchemaComponent.ts";
+import { type PgBossError, toPgBossError } from "#error.ts";
+import { deferralStorePlan } from "#internal/deferralStorePlan.ts";
+import { runSchemaPlan } from "#internal/runSchemaPlan.ts";
+import { resumeSchemaIndexes } from "#internal/schemaIndexBuilds.ts";
+
+export interface PgBossSchemaOptions {
+	readonly schema?: string;
+}
+
+async function installSchema(
+	connection: Connection,
+	options: PgBossSchemaOptions,
+	run: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>,
+): Promise<void> {
+	const schema = options.schema ?? "pgboss";
+	const construction = getConstructionPlans(schema);
+	const client = new PgBoss({
+		db: { executeSql: async (text, values = []) => ({ rows: Array.from(await run(connection.executeUnprepared(text, values, undefined))) }) },
+		schema,
+	});
+	if (!(await client.isInstalled())) {
+		await runSchemaPlan(connection, construction, run);
+		return;
+	}
+	const version = await client.schemaVersion();
+	if (version === null) {
+		throw new Error("The pg-boss version table is empty");
+	}
+	if (version > pgBossPackage.pgboss.schema) {
+		return;
+	}
+	if (version >= 27) {
+		await resumeSchemaIndexes(client, schema);
+	}
+	if (version < pgBossPackage.pgboss.schema) {
+		const partitionTables: MigrationPartition[] = Array.from(
+			await run(connection.executeUnprepared(`SELECT table_name AS "tableName", policy FROM ${schema}.queue WHERE partition = true`, [], undefined)),
+		);
+		await runSchemaPlan(connection, getMigrationPlans(schema, version, { partitionTables }), run, { schema, version: pgBossPackage.pgboss.schema });
+		await resumeSchemaIndexes(client, schema);
+	}
+}
+
+export function installPgBossSchema(options: PgBossSchemaOptions = {}): Effect.Effect<void, PgBossError, SqlClient.SqlClient> {
+	return Effect.scoped(
+		Effect.gen(function* () {
+			const sql = yield* SqlClient.SqlClient;
+			const connection = yield* sql.reserve;
+			const run = Effect.runPromiseWith(yield* Effect.context<never>());
+			yield* Effect.tryPromise({
+				catch: (error) => error,
+				try: async () => {
+					await installSchema(connection, options, run);
+					await run(connection.executeRaw(deferralStorePlan(options.schema ?? "pgboss"), []));
+				},
+			});
+		}).pipe(Effect.mapError((error) => toPgBossError("install", error))),
+	).pipe(Effect.uninterruptible);
+}
+
+export function pgBossSchema(options: PgBossSchemaOptions = {}): SchemaComponent {
+	const schema = options.schema ?? "pgboss";
+	return {
+		apply: installPgBossSchema(options),
+		name: `pg-boss:${schema}`,
+		pending: Effect.gen(function* () {
+			const sql = yield* SqlClient.SqlClient;
+			const table = sql`${sql(schema)}.${sql("version")}`;
+			const [installed] = yield* sql<{ name: string | null }>`select to_regclass(${table.compile()[0]})::text as name`.withoutTransform;
+			const [row] =
+				installed === undefined || installed.name === null ? [] : yield* sql<{ version: number }>`select version from ${table}`.withoutTransform;
+			const required = pgBossPackage.pgboss.schema;
+			return row === undefined || row.version < required
+				? `schema ${schema}, installed version ${row?.version ?? "missing"}, required version ${required}`
+				: undefined;
+		}),
+	};
+}