bunqueue 2.8.59 → 2.9.0

package/dist/infrastructure/persistence/postgres/runtime.d.ts

@@ -0,0 +1,46 @@
+import { PostgresEventStream } from './events';
+import type { PostgresContext } from './context';
+import type { PostgresDeliveredStoreEvent, PostgresStorageConfig, PostgresStorageHealth } from './types';
+/** Connection, schema, event stream, health, and maintenance lifecycle. */
+export declare class PostgresQueueStoreRuntime {
+    readonly context: PostgresContext;
+    readonly events: PostgresEventStream;
+    private heartbeatTimer;
+    private recoveryTimer;
+    private dlqTimer;
+    private cronTimer;
+    private readyPromise;
+    private closing;
+    private closed;
+    private closeAttempt;
+    private leasesReleased;
+    private workersRemoved;
+    private brokerUnregistered;
+    private eventsClosed;
+    private eventStatusUnsubscribed;
+    private sqlClosed;
+    private brokerRegistrationStarted;
+    private readonly healthTracker;
+    private readonly unsubscribeEventStatus;
+    private readonly postCommitMaintenance;
+    private readonly maintenanceFlights;
+    private readonly eventCommitGc;
+    constructor(config: PostgresStorageConfig);
+    get config(): import("./types").ResolvedPostgresStorageConfig;
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+    private stopMaintenance;
+    private closeOnce;
+    private tryCloseStep;
+    health(): PostgresStorageHealth;
+    reportQueueRefresh(queue: string, error: unknown): void;
+    reportProjectionRefresh(queue: string, id: string, error: unknown): void;
+    private reportMaintenance;
+    onEvent(listener: (event: PostgresDeliveredStoreEvent) => void): () => void;
+    onInvalidation(listener: (queue: string) => void): () => void;
+    waitForWork(queue: string, timeoutMs: number, signal?: AbortSignal): Promise<void>;
+    private initializeOnce;
+    private startMaintenance;
+    private runMaintenance;
+    private heartbeatBroker;
+}

package/dist/infrastructure/persistence/postgres/runtime.js

@@ -0,0 +1,236 @@
+import { recoverExpiredPostgresLeases } from './recovery';
+import { releasePostgresBrokerLeases } from './leaseRelease';
+import { PostgresEventStream } from './events';
+import { prunePostgresEventCommits } from './eventJournal';
+import { maintainPostgresDlq, repairPostgresDlq } from './dlqMaintenance';
+import { listPostgresCrons, processPostgresCrons, reconcilePostgresCronsOnStartup } from './crons';
+import { purgeStalePostgresWorkers, removePostgresBrokerWorkers } from './workers';
+import { initializePostgresSchema } from './schemaInitialization';
+import { PostgresPostCommitMaintenance } from './postCommitMaintenance';
+import { sweepPostgresEventRetention } from './telemetry';
+import { prunePostgresCompletionTombstones } from './completionLifecycle';
+import { PostgresMaintenanceFlights } from './maintenanceFlights';
+import { resolvePostgresRuntimeConfig } from './runtimeConfig';
+import { PostgresEventCommitGc } from './eventCommitGc';
+import { createPostgresConnection } from './connection';
+import { PostgresStorageHealthTracker } from './storageHealth';
+import { heartbeatPostgresBroker, PostgresBrokerSessionFencedError, purgeStalePostgresBrokers, registerPostgresBroker, unregisterPostgresBroker, } from './brokerSessions';
+/** Connection, schema, event stream, health, and maintenance lifecycle. */
+export class PostgresQueueStoreRuntime {
+    context;
+    events;
+    heartbeatTimer = null;
+    recoveryTimer = null;
+    dlqTimer = null;
+    cronTimer = null;
+    readyPromise = null;
+    closing = false;
+    closed = false;
+    closeAttempt = null;
+    leasesReleased = false;
+    workersRemoved = false;
+    brokerUnregistered = false;
+    eventsClosed = false;
+    eventStatusUnsubscribed = false;
+    sqlClosed = false;
+    brokerRegistrationStarted = false;
+    healthTracker;
+    unsubscribeEventStatus;
+    postCommitMaintenance;
+    maintenanceFlights;
+    eventCommitGc;
+    constructor(config) {
+        const resolved = resolvePostgresRuntimeConfig(config);
+        const sql = createPostgresConnection(resolved);
+        this.healthTracker = new PostgresStorageHealthTracker(resolved);
+        this.postCommitMaintenance = new PostgresPostCommitMaintenance((subsystem, error) => this.reportMaintenance(subsystem, error), Math.max(25, resolved.pollIntervalMs));
+        this.maintenanceFlights = new PostgresMaintenanceFlights((subsystem, error) => this.reportMaintenance(subsystem, error));
+        this.context = {
+            sql,
+            config: resolved,
+            postCommitMaintenance: (subsystem, operation) => this.postCommitMaintenance.run(subsystem, operation),
+        };
+        this.eventCommitGc = new PostgresEventCommitGc((batchSize, maxBatches) => prunePostgresEventCommits(this.context, batchSize, maxBatches), (subsystem, error) => this.reportMaintenance(subsystem, error));
+        this.events = new PostgresEventStream(this.context);
+        this.unsubscribeEventStatus = this.events.subscribeDrainStatus((error) => {
+            if (error === null)
+                this.healthTracker.clear('event-stream');
+            else
+                this.healthTracker.record('event-stream', error);
+        });
+    }
+    get config() {
+        return this.context.config;
+    }
+    initialize() {
+        this.readyPromise ??= this.initializeOnce();
+        return this.readyPromise;
+    }
+    close() {
+        if (this.closed)
+            return Promise.resolve();
+        if (this.closeAttempt)
+            return this.closeAttempt;
+        this.closing = true;
+        this.stopMaintenance();
+        const attempt = this.closeOnce().finally(() => {
+            this.closeAttempt = null;
+        });
+        this.closeAttempt = attempt;
+        return attempt;
+    }
+    stopMaintenance() {
+        this.postCommitMaintenance.close();
+        this.maintenanceFlights.close();
+        this.eventCommitGc.close();
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        if (this.recoveryTimer)
+            clearInterval(this.recoveryTimer);
+        if (this.dlqTimer)
+            clearInterval(this.dlqTimer);
+        if (this.cronTimer)
+            clearInterval(this.cronTimer);
+        this.heartbeatTimer = null;
+        this.recoveryTimer = null;
+        this.dlqTimer = null;
+        this.cronTimer = null;
+    }
+    async closeOnce() {
+        const errors = [];
+        let initialized = true;
+        try {
+            await this.initialize();
+        }
+        catch (error) {
+            initialized = false;
+            errors.push(error);
+        }
+        if (initialized || this.brokerRegistrationStarted) {
+            await this.maintenanceFlights.drain();
+            await this.eventCommitGc.drain();
+            await this.postCommitMaintenance.drain();
+            this.leasesReleased = await this.tryCloseStep(this.leasesReleased, () => releasePostgresBrokerLeases(this.context), errors);
+            this.workersRemoved = await this.tryCloseStep(this.workersRemoved, () => removePostgresBrokerWorkers(this.context), errors);
+            this.brokerUnregistered = await this.tryCloseStep(this.brokerUnregistered, async () => {
+                await unregisterPostgresBroker(this.context);
+            }, errors);
+        }
+        this.eventsClosed = await this.tryCloseStep(this.eventsClosed, () => this.events.close(), errors);
+        if (this.eventsClosed && !this.eventStatusUnsubscribed) {
+            this.unsubscribeEventStatus();
+            this.eventStatusUnsubscribed = true;
+        }
+        const databaseClosed = !this.brokerRegistrationStarted ||
+            (this.leasesReleased && this.workersRemoved && this.brokerUnregistered);
+        if (databaseClosed) {
+            this.sqlClosed = await this.tryCloseStep(this.sqlClosed, () => this.context.sql.close({ timeout: 5 }), errors);
+        }
+        if (this.eventsClosed && this.sqlClosed && (!initialized || databaseClosed)) {
+            this.closed = true;
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1)
+            throw new AggregateError(errors, 'PostgreSQL shutdown failed');
+    }
+    async tryCloseStep(completed, operation, errors) {
+        if (completed)
+            return true;
+        try {
+            await operation();
+            return true;
+        }
+        catch (error) {
+            errors.push(error);
+            return false;
+        }
+    }
+    health() {
+        return this.healthTracker.snapshot();
+    }
+    reportQueueRefresh(queue, error) {
+        const key = `queue-refresh:${queue}`;
+        if (error === null) {
+            this.healthTracker.clear(key);
+            return;
+        }
+        this.healthTracker.record(key, error, `Queue refresh ${queue}: `);
+    }
+    reportProjectionRefresh(queue, id, error) {
+        const key = `projection-refresh:${id}`;
+        if (error === null) {
+            this.healthTracker.clear(key);
+            return;
+        }
+        this.healthTracker.record(key, error, `Projection refresh ${queue}/${id}: `);
+    }
+    reportMaintenance(subsystem, error) {
+        const key = `maintenance:${subsystem}`;
+        if (error === null)
+            this.healthTracker.clear(key);
+        else
+            this.healthTracker.record(key, error);
+    }
+    onEvent(listener) {
+        return this.events.subscribe(listener);
+    }
+    onInvalidation(listener) {
+        return this.events.subscribeInvalidation(listener);
+    }
+    waitForWork(queue, timeoutMs, signal) {
+        return this.events.wait(queue, timeoutMs, signal);
+    }
+    async initializeOnce() {
+        try {
+            await this.context.sql.connect();
+            await initializePostgresSchema(this.context);
+            await listPostgresCrons(this.context);
+            await registerPostgresBroker(this.context);
+            this.brokerRegistrationStarted = true;
+            await reconcilePostgresCronsOnStartup(this.context);
+            await recoverExpiredPostgresLeases(this.context);
+            await repairPostgresDlq(this.context);
+            await prunePostgresCompletionTombstones(this.context);
+            await sweepPostgresEventRetention(this.context);
+            await prunePostgresEventCommits(this.context);
+            await this.events.start();
+            if (!this.closing)
+                this.startMaintenance();
+            this.healthTracker.clear('lifecycle');
+        }
+        catch (error) {
+            this.healthTracker.record('lifecycle', error);
+            throw error;
+        }
+    }
+    startMaintenance() {
+        this.eventCommitGc.start();
+        const heartbeatMs = Math.max(1000, Math.floor(this.config.leaseDurationMs / 3));
+        this.heartbeatTimer = setInterval(() => void this.runMaintenance(() => this.heartbeatBroker(), 'heartbeat'), heartbeatMs);
+        this.recoveryTimer = setInterval(() => void this.runMaintenance(() => recoverExpiredPostgresLeases(this.context), 'recovery'), Math.max(500, Math.floor(this.config.leaseDurationMs / 2)));
+        this.dlqTimer = setInterval(() => {
+            void this.runMaintenance(async () => {
+                await maintainPostgresDlq(this.context);
+                await purgeStalePostgresWorkers(this.context);
+                await purgeStalePostgresBrokers(this.context);
+            }, 'dlq');
+            void this.runMaintenance(() => sweepPostgresEventRetention(this.context), 'event-retention');
+            void this.postCommitMaintenance.run('completion-retention', () => prunePostgresCompletionTombstones(this.context));
+        }, 60_000);
+        this.cronTimer = setInterval(() => void this.runMaintenance(() => processPostgresCrons(this.context), 'cron'), this.config.pollIntervalMs);
+    }
+    async runMaintenance(operation, subsystem = 'maintenance') {
+        await this.maintenanceFlights.run(subsystem, operation);
+    }
+    async heartbeatBroker() {
+        try {
+            await heartbeatPostgresBroker(this.context);
+        }
+        catch (error) {
+            if (error instanceof PostgresBrokerSessionFencedError)
+                this.stopMaintenance();
+            throw error;
+        }
+    }
+}

package/dist/infrastructure/persistence/postgres/runtimeConfig.d.ts

@@ -0,0 +1,21 @@
+import type { PostgresStorageConfig } from './types';
+export declare function resolvePostgresRuntimeConfig(config: PostgresStorageConfig): {
+    url: string;
+    namespace: string;
+    brokerId: string;
+    brokerSessionId: string;
+    poolSize: number;
+    leaseDurationMs: number;
+    pollIntervalMs: number;
+    statementTimeoutMs: number;
+    lockTimeoutMs: number;
+    idleTransactionTimeoutMs: number;
+    maxConcurrentOperations: number;
+    maxQueuedOperations: number;
+    maxSnapshotJobs: number;
+    maxSnapshotPayloadBytes: number;
+    maxQueueEvents: number;
+    maxMetricDataPoints: number;
+    maxCompletedJobs: number;
+    maxJobResults: number;
+};

package/dist/infrastructure/persistence/postgres/runtimeConfig.js

@@ -0,0 +1,39 @@
+import { hostname } from 'node:os';
+function integerAtLeast(value, fallback, minimum) {
+    if (!Number.isFinite(value))
+        return fallback;
+    return Math.max(minimum, Math.floor(value));
+}
+export function resolvePostgresRuntimeConfig(config) {
+    const url = new URL(config.url);
+    if (url.protocol !== 'postgres:' && url.protocol !== 'postgresql:') {
+        throw new Error('PostgreSQL storage requires a postgres:// or postgresql:// URL');
+    }
+    if (config.maxQueueEvents !== undefined &&
+        Number.isFinite(config.maxQueueEvents) &&
+        config.maxQueueEvents < 1) {
+        throw new Error('PostgreSQL storage requires maxQueueEvents to be at least 1');
+    }
+    const poolSize = integerAtLeast(config.poolSize, 4, 2);
+    const maxConcurrentOperations = integerAtLeast(config.maxConcurrentOperations, 16, 1);
+    return {
+        url: config.url,
+        namespace: config.namespace?.trim() || 'default',
+        brokerId: config.brokerId?.trim() || `${hostname()}:${process.pid}:${Bun.randomUUIDv7().slice(-12)}`,
+        brokerSessionId: Bun.randomUUIDv7(),
+        poolSize,
+        leaseDurationMs: integerAtLeast(config.leaseDurationMs, 30_000, 1000),
+        pollIntervalMs: integerAtLeast(config.pollIntervalMs, 250, 25),
+        statementTimeoutMs: integerAtLeast(config.statementTimeoutMs, 30_000, 1),
+        lockTimeoutMs: integerAtLeast(config.lockTimeoutMs, 5_000, 1),
+        idleTransactionTimeoutMs: integerAtLeast(config.idleTransactionTimeoutMs, 30_000, 1),
+        maxConcurrentOperations,
+        maxQueuedOperations: integerAtLeast(config.maxQueuedOperations, 128, 0),
+        maxSnapshotJobs: integerAtLeast(config.maxSnapshotJobs, 100_000, 1),
+        maxSnapshotPayloadBytes: integerAtLeast(config.maxSnapshotPayloadBytes, 256 * 1024 * 1024, 1),
+        maxQueueEvents: integerAtLeast(config.maxQueueEvents, 10_000, 1),
+        maxMetricDataPoints: integerAtLeast(config.maxMetricDataPoints, 20_160, 0),
+        maxCompletedJobs: integerAtLeast(config.maxCompletedJobs, 50_000, 1),
+        maxJobResults: integerAtLeast(config.maxJobResults, 10_000, 0),
+    };
+}

package/dist/infrastructure/persistence/postgres/schema.d.ts

@@ -0,0 +1,4 @@
+export declare const POSTGRES_SCHEMA_VERSION = 17;
+/** PostgreSQL schema for the database-authoritative distributed queue engine. */
+export declare const POSTGRES_SCHEMA = "\nCREATE TABLE IF NOT EXISTS bunqueue_schema_migrations (\n  version INTEGER PRIMARY KEY,\n  applied_at BIGINT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS bunqueue_jobs (\n  namespace TEXT NOT NULL,\n  id TEXT NOT NULL,\n  queue TEXT NOT NULL,\n  payload BYTEA NOT NULL,\n  state TEXT NOT NULL CHECK (\n    state IN ('waiting', 'prioritized', 'delayed', 'waiting-children',\n              'active', 'completed', 'failed')\n  ),\n  priority INTEGER NOT NULL DEFAULT 0,\n  lifo BOOLEAN NOT NULL DEFAULT FALSE,\n  run_at BIGINT NOT NULL,\n  created_at BIGINT NOT NULL,\n  started_at BIGINT,\n  completed_at BIGINT,\n  attempts INTEGER NOT NULL DEFAULT 0,\n  max_attempts INTEGER NOT NULL DEFAULT 3,\n  ttl BIGINT,\n  timeout BIGINT,\n  unique_key TEXT,\n  unique_expires_at BIGINT,\n  custom_id TEXT,\n  group_id TEXT,\n  parent_id TEXT,\n  lease_owner TEXT,\n  lease_broker_id TEXT,\n  lease_broker_session_id TEXT,\n  lease_token TEXT,\n  lease_until BIGINT,\n  lease_renewals INTEGER NOT NULL DEFAULT 0,\n  result BYTEA,\n  dlq_entry BYTEA,\n  dlq_retry_state BYTEA,\n  error TEXT,\n  failure_reason TEXT,\n  version BIGINT NOT NULL DEFAULT 0,\n  PRIMARY KEY (namespace, id)\n);\n\nCREATE INDEX IF NOT EXISTS bunqueue_jobs_ready_idx\n  ON bunqueue_jobs(namespace, queue, priority DESC, run_at ASC, id ASC)\n  WHERE state IN ('waiting', 'prioritized', 'delayed');\nCREATE INDEX IF NOT EXISTS bunqueue_jobs_state_idx\n  ON bunqueue_jobs(namespace, queue, state, created_at, id);\nCREATE INDEX IF NOT EXISTS bunqueue_jobs_lease_idx\n  ON bunqueue_jobs(namespace, lease_until)\n  WHERE state = 'active';\nCREATE INDEX IF NOT EXISTS bunqueue_jobs_parent_idx\n  ON bunqueue_jobs(namespace, parent_id)\n  WHERE parent_id IS NOT NULL;\nCREATE INDEX IF NOT EXISTS bunqueue_jobs_group_ready_idx\n  ON bunqueue_jobs(namespace, queue, group_id, priority DESC, run_at ASC, id ASC)\n  WHERE group_id IS NOT NULL AND state IN ('waiting', 'prioritized', 'delayed');\nCREATE INDEX IF NOT EXISTS bunqueue_jobs_group_active_idx\n  ON bunqueue_jobs(namespace, queue, group_id, lease_until)\n  WHERE group_id IS NOT NULL AND state = 'active';\nCREATE INDEX IF NOT EXISTS bunqueue_jobs_lifo_ready_idx\n  ON bunqueue_jobs(namespace, queue, priority DESC, id DESC)\n  WHERE group_id IS NULL AND lifo AND state IN ('waiting', 'prioritized', 'delayed');\nCREATE INDEX IF NOT EXISTS bunqueue_jobs_ttl_pending_idx\n  ON bunqueue_jobs(namespace, queue, created_at, id)\n  WHERE ttl IS NOT NULL AND state IN ('waiting', 'prioritized', 'delayed');\nALTER TABLE bunqueue_jobs\n  ADD COLUMN IF NOT EXISTS unique_expires_at BIGINT;\nALTER TABLE bunqueue_jobs\n  ADD COLUMN IF NOT EXISTS lease_broker_id TEXT;\nALTER TABLE bunqueue_jobs\n  ADD COLUMN IF NOT EXISTS lease_broker_session_id TEXT;\nALTER TABLE bunqueue_jobs\n  ADD COLUMN IF NOT EXISTS lease_renewals INTEGER NOT NULL DEFAULT 0;\nALTER TABLE bunqueue_jobs\n  ADD COLUMN IF NOT EXISTS dlq_retry_state BYTEA;\nCREATE INDEX IF NOT EXISTS bunqueue_jobs_broker_session_lease_idx\n  ON bunqueue_jobs(namespace, lease_broker_id, lease_broker_session_id, id)\n  WHERE state = 'active';\n\nCREATE TABLE IF NOT EXISTS bunqueue_dependencies (\n  namespace TEXT NOT NULL,\n  job_id TEXT NOT NULL,\n  dependency_id TEXT NOT NULL,\n  PRIMARY KEY (namespace, job_id, dependency_id)\n);\nCREATE INDEX IF NOT EXISTS bunqueue_dependencies_dependency_idx\n  ON bunqueue_dependencies(namespace, dependency_id, job_id);\n\nCREATE TABLE IF NOT EXISTS bunqueue_flow_failures (\n  namespace TEXT NOT NULL,\n  parent_id TEXT NOT NULL,\n  child_id TEXT NOT NULL,\n  child_queue TEXT NOT NULL,\n  mode TEXT NOT NULL CHECK (mode IN ('fail', 'remove', 'ignore', 'continue')),\n  error TEXT NOT NULL,\n  created_at BIGINT NOT NULL,\n  PRIMARY KEY (namespace, parent_id, child_id)\n);\nCREATE INDEX IF NOT EXISTS bunqueue_flow_failures_parent_idx\n  ON bunqueue_flow_failures(namespace, parent_id, mode);\n\nCREATE TABLE IF NOT EXISTS bunqueue_repeat_links (\n  namespace TEXT NOT NULL,\n  original_id TEXT NOT NULL,\n  successor_id TEXT NOT NULL,\n  PRIMARY KEY (namespace, original_id)\n);\nCREATE INDEX IF NOT EXISTS bunqueue_repeat_links_successor_idx\n  ON bunqueue_repeat_links(namespace, successor_id);\n\nCREATE TABLE IF NOT EXISTS bunqueue_job_logs (\n  id BIGSERIAL PRIMARY KEY,\n  namespace TEXT NOT NULL,\n  job_id TEXT NOT NULL,\n  timestamp BIGINT NOT NULL,\n  level TEXT NOT NULL CHECK (level IN ('info', 'warn', 'error')),\n  message TEXT NOT NULL\n);\nCREATE INDEX IF NOT EXISTS bunqueue_job_logs_job_idx\n  ON bunqueue_job_logs(namespace, job_id, id);\n\nCREATE TABLE IF NOT EXISTS bunqueue_crons (\n  namespace TEXT NOT NULL,\n  name TEXT NOT NULL,\n  payload BYTEA NOT NULL,\n  next_run BIGINT NOT NULL,\n  executions INTEGER NOT NULL DEFAULT 0,\n  max_limit INTEGER,\n  updated_at BIGINT NOT NULL,\n  PRIMARY KEY (namespace, name)\n);\nCREATE INDEX IF NOT EXISTS bunqueue_crons_due_idx\n  ON bunqueue_crons(namespace, next_run, name);\n\nCREATE TABLE IF NOT EXISTS bunqueue_workers (\n  namespace TEXT NOT NULL,\n  id TEXT NOT NULL,\n  broker_id TEXT NOT NULL,\n  broker_session_id TEXT,\n  client_id TEXT,\n  queues TEXT[] NOT NULL,\n  payload BYTEA NOT NULL,\n  last_seen BIGINT NOT NULL,\n  PRIMARY KEY (namespace, id)\n);\nCREATE INDEX IF NOT EXISTS bunqueue_workers_queue_idx\n  ON bunqueue_workers USING GIN(queues);\nCREATE INDEX IF NOT EXISTS bunqueue_workers_broker_idx\n  ON bunqueue_workers(namespace, broker_id, client_id);\nALTER TABLE bunqueue_workers\n  ADD COLUMN IF NOT EXISTS broker_session_id TEXT;\nCREATE INDEX IF NOT EXISTS bunqueue_workers_broker_session_idx\n  ON bunqueue_workers(namespace, broker_id, broker_session_id, client_id);\n\nCREATE TABLE IF NOT EXISTS bunqueue_metric_buckets (\n  namespace TEXT NOT NULL,\n  queue TEXT NOT NULL,\n  metric_type TEXT NOT NULL CHECK (metric_type IN ('completed', 'failed')),\n  minute BIGINT NOT NULL,\n  count INTEGER NOT NULL,\n  PRIMARY KEY (namespace, queue, metric_type, minute)\n);\nCREATE TABLE IF NOT EXISTS bunqueue_metric_totals (\n  namespace TEXT NOT NULL,\n  queue TEXT NOT NULL,\n  metric_type TEXT NOT NULL CHECK (metric_type IN ('completed', 'failed')),\n  total_count BIGINT NOT NULL,\n  prev_ts BIGINT NOT NULL,\n  prev_count INTEGER NOT NULL,\n  PRIMARY KEY (namespace, queue, metric_type)\n);\n\nCREATE TABLE IF NOT EXISTS bunqueue_completions (\n  namespace TEXT NOT NULL,\n  job_id TEXT NOT NULL,\n  queue TEXT NOT NULL,\n  completed_at BIGINT NOT NULL,\n  result BYTEA,\n  PRIMARY KEY (namespace, job_id)\n);\nCREATE INDEX IF NOT EXISTS bunqueue_completions_queue_idx\n  ON bunqueue_completions(namespace, queue, job_id);\nCREATE INDEX IF NOT EXISTS bunqueue_completions_recent_idx\n  ON bunqueue_completions(namespace, completed_at DESC, job_id DESC);\n\nCREATE TABLE IF NOT EXISTS bunqueue_queue_state (\n  namespace TEXT NOT NULL,\n  queue TEXT NOT NULL,\n  paused BOOLEAN NOT NULL DEFAULT FALSE,\n  rate_limit INTEGER,\n  rate_duration_ms BIGINT,\n  rate_window_started_at BIGINT,\n  rate_expires_at BIGINT,\n  rate_count INTEGER NOT NULL DEFAULT 0,\n  concurrency_limit INTEGER,\n  stall_config BYTEA,\n  dlq_config BYTEA,\n  PRIMARY KEY (namespace, queue)\n);\n\nALTER TABLE bunqueue_queue_state\n  ADD COLUMN IF NOT EXISTS rate_expires_at BIGINT;\n\nINSERT INTO bunqueue_queue_state (namespace, queue)\nSELECT DISTINCT namespace, queue FROM bunqueue_jobs\nON CONFLICT (namespace, queue) DO NOTHING;\n\nCREATE TABLE IF NOT EXISTS bunqueue_events (\n  id BIGSERIAL PRIMARY KEY,\n  namespace TEXT NOT NULL,\n  queue TEXT NOT NULL,\n  event_type TEXT NOT NULL,\n  job_id TEXT NOT NULL,\n  occurred_at BIGINT NOT NULL,\n  payload BYTEA\n);\nCREATE INDEX IF NOT EXISTS bunqueue_events_namespace_id_idx\n  ON bunqueue_events(namespace, id);\nCREATE INDEX IF NOT EXISTS bunqueue_events_queue_id_idx\n  ON bunqueue_events(namespace, queue, id DESC);\n\nCREATE TABLE IF NOT EXISTS bunqueue_event_prune_watermarks (\n  namespace TEXT NOT NULL,\n  queue TEXT NOT NULL,\n  source_event_id BIGINT NOT NULL,\n  pruned_through BIGINT NOT NULL,\n  PRIMARY KEY (namespace, queue, source_event_id)\n);\nCREATE INDEX IF NOT EXISTS bunqueue_event_prune_watermarks_namespace_queue_idx\n  ON bunqueue_event_prune_watermarks(namespace, queue, pruned_through DESC);\n\n\nCREATE SEQUENCE IF NOT EXISTS bunqueue_event_commit_seq AS BIGINT CACHE 1;\nALTER SEQUENCE bunqueue_event_commit_seq\n  AS BIGINT INCREMENT BY 1 NO MINVALUE NO MAXVALUE NO CYCLE CACHE 1;\n\nCREATE TABLE IF NOT EXISTS bunqueue_event_commits (\n  namespace TEXT NOT NULL,\n  transaction_id BIGINT NOT NULL,\n  commit_seq BIGINT,\n  PRIMARY KEY (namespace, transaction_id)\n);\n\nALTER TABLE bunqueue_event_commits\n  ADD COLUMN IF NOT EXISTS namespace TEXT;\nALTER TABLE bunqueue_event_commits\n  ADD COLUMN IF NOT EXISTS transaction_id BIGINT;\nALTER TABLE bunqueue_event_commits\n  ADD COLUMN IF NOT EXISTS commit_seq BIGINT;\nALTER TABLE bunqueue_event_commits\n  ALTER COLUMN namespace TYPE TEXT USING namespace::text,\n  ALTER COLUMN transaction_id TYPE BIGINT USING transaction_id::bigint,\n  ALTER COLUMN commit_seq TYPE BIGINT USING commit_seq::bigint;\n\nALTER TABLE bunqueue_events\n  ADD COLUMN IF NOT EXISTS transaction_id BIGINT;\nALTER TABLE bunqueue_events\n  ALTER COLUMN transaction_id DROP DEFAULT;\nALTER TABLE bunqueue_events\n  ALTER COLUMN transaction_id TYPE BIGINT USING transaction_id::bigint;\nALTER TABLE bunqueue_events\n  ALTER COLUMN transaction_id SET DEFAULT (pg_current_xact_id()::text::bigint);\n\nALTER TABLE bunqueue_event_prune_watermarks\n  ADD COLUMN IF NOT EXISTS transaction_id BIGINT;\nALTER TABLE bunqueue_event_prune_watermarks\n  ADD COLUMN IF NOT EXISTS commit_seq BIGINT;\nALTER TABLE bunqueue_event_prune_watermarks\n  ADD COLUMN IF NOT EXISTS pruned_commit_seq BIGINT;\nALTER TABLE bunqueue_event_prune_watermarks\n  ADD COLUMN IF NOT EXISTS prunes_current_transaction BOOLEAN NOT NULL DEFAULT FALSE;\nALTER TABLE bunqueue_event_prune_watermarks\n  ALTER COLUMN transaction_id DROP DEFAULT,\n  ALTER COLUMN pruned_commit_seq DROP DEFAULT,\n  ALTER COLUMN prunes_current_transaction DROP DEFAULT;\nALTER TABLE bunqueue_event_prune_watermarks\n  ALTER COLUMN transaction_id TYPE BIGINT USING transaction_id::bigint,\n  ALTER COLUMN commit_seq TYPE BIGINT USING commit_seq::bigint,\n  ALTER COLUMN pruned_commit_seq TYPE BIGINT USING pruned_commit_seq::bigint,\n  ALTER COLUMN prunes_current_transaction TYPE BOOLEAN\n    USING prunes_current_transaction::boolean;\nALTER TABLE bunqueue_event_prune_watermarks\n  ALTER COLUMN transaction_id SET DEFAULT (pg_current_xact_id()::text::bigint);\nALTER TABLE bunqueue_event_prune_watermarks\n  ALTER COLUMN pruned_commit_seq SET DEFAULT 0,\n  ALTER COLUMN prunes_current_transaction SET DEFAULT FALSE;\n\nUPDATE bunqueue_events\nSET transaction_id = -id\nWHERE transaction_id IS NULL;\nUPDATE bunqueue_event_prune_watermarks\nSET transaction_id = COALESCE(transaction_id, -source_event_id),\n    commit_seq = COALESCE(commit_seq, source_event_id),\n    pruned_commit_seq = COALESCE(pruned_commit_seq, commit_seq, source_event_id)\nWHERE transaction_id IS NULL OR commit_seq IS NULL OR pruned_commit_seq IS NULL;\n\nALTER TABLE bunqueue_events\n  ALTER COLUMN transaction_id SET NOT NULL;\nALTER TABLE bunqueue_event_commits\n  ALTER COLUMN namespace SET NOT NULL,\n  ALTER COLUMN transaction_id SET NOT NULL;\nALTER TABLE bunqueue_event_prune_watermarks\n  ALTER COLUMN transaction_id SET NOT NULL,\n  ALTER COLUMN pruned_commit_seq SET NOT NULL,\n  ALTER COLUMN prunes_current_transaction SET NOT NULL;\n\nDO $migration$\nBEGIN\n  IF EXISTS (\n    SELECT 1 FROM pg_attribute\n    WHERE attrelid = to_regclass('bunqueue_events')\n      AND attname = 'commit_seq' AND NOT attisdropped\n  ) THEN\n    EXECUTE $sql$\n      INSERT INTO bunqueue_event_commits (namespace, transaction_id, commit_seq)\n      SELECT namespace, transaction_id, MAX(commit_seq)\n      FROM bunqueue_events\n      WHERE commit_seq IS NOT NULL\n      GROUP BY namespace, transaction_id\n      ON CONFLICT (namespace, transaction_id) DO UPDATE SET\n        commit_seq = GREATEST(\n          COALESCE(bunqueue_event_commits.commit_seq, 0),\n          excluded.commit_seq\n        )\n    $sql$;\n  ELSE\n    INSERT INTO bunqueue_event_commits (namespace, transaction_id, commit_seq)\n    SELECT namespace, transaction_id, MAX(id)\n    FROM bunqueue_events\n    GROUP BY namespace, transaction_id\n    ON CONFLICT (namespace, transaction_id) DO NOTHING;\n  END IF;\nEND;\n$migration$;\n\nINSERT INTO bunqueue_event_commits (namespace, transaction_id, commit_seq)\nSELECT namespace, transaction_id, MAX(commit_seq)\nFROM bunqueue_event_prune_watermarks\nWHERE commit_seq IS NOT NULL\nGROUP BY namespace, transaction_id\nON CONFLICT (namespace, transaction_id) DO UPDATE SET\n  commit_seq = GREATEST(\n    COALESCE(bunqueue_event_commits.commit_seq, 0),\n    excluded.commit_seq\n  );\n\nDO $block$\nDECLARE\n  journal_floor BIGINT := 0;\n  legacy_head_floor BIGINT := 0;\n  sequence_floor BIGINT := 0;\nBEGIN\n  SELECT COALESCE(MAX(commit_seq), 0) INTO journal_floor\n  FROM bunqueue_event_commits;\n  SELECT last_value INTO sequence_floor FROM bunqueue_event_commit_seq;\n  IF to_regclass('bunqueue_event_commit_heads') IS NOT NULL THEN\n    EXECUTE 'SELECT COALESCE(MAX(commit_seq), 0) FROM bunqueue_event_commit_heads'\n      INTO legacy_head_floor;\n  END IF;\n  PERFORM setval(\n    'bunqueue_event_commit_seq',\n    GREATEST(journal_floor, legacy_head_floor, sequence_floor, 1),\n    TRUE\n  );\nEND;\n$block$;\n\nDROP TABLE IF EXISTS bunqueue_event_commit_heads;\n\nDROP TRIGGER IF EXISTS bunqueue_events_register_commit ON bunqueue_events;\nDROP TRIGGER IF EXISTS bunqueue_watermarks_insert_register_commit\n  ON bunqueue_event_prune_watermarks;\nDROP TRIGGER IF EXISTS bunqueue_watermarks_update_register_commit\n  ON bunqueue_event_prune_watermarks;\nDROP TABLE IF EXISTS bunqueue_event_commit_assignments CASCADE;\nDROP INDEX IF EXISTS bunqueue_events_commit_idx;\nDROP INDEX IF EXISTS bunqueue_events_pending_commit_idx;\nALTER TABLE bunqueue_events DROP COLUMN IF EXISTS commit_seq;\n\nDROP INDEX IF EXISTS bunqueue_events_transaction_idx;\nDROP INDEX IF EXISTS bunqueue_event_commits_replay_idx;\nDROP INDEX IF EXISTS bunqueue_event_prune_watermarks_commit_idx;\nDROP INDEX IF EXISTS bunqueue_event_prune_watermarks_pending_commit_idx;\nDROP INDEX IF EXISTS bunqueue_event_prune_watermarks_transaction_idx;\n\nCREATE INDEX bunqueue_events_transaction_idx\n  ON bunqueue_events(namespace, transaction_id, id);\nCREATE INDEX bunqueue_event_commits_replay_idx\n  ON bunqueue_event_commits(namespace, commit_seq, transaction_id)\n  WHERE commit_seq IS NOT NULL;\nCREATE INDEX bunqueue_event_prune_watermarks_commit_idx\n  ON bunqueue_event_prune_watermarks(namespace, queue, commit_seq DESC)\n  WHERE commit_seq IS NOT NULL;\nCREATE INDEX bunqueue_event_prune_watermarks_pending_commit_idx\n  ON bunqueue_event_prune_watermarks(namespace, transaction_id)\n  WHERE commit_seq IS NULL;\nCREATE INDEX bunqueue_event_prune_watermarks_transaction_idx\n  ON bunqueue_event_prune_watermarks(namespace, transaction_id);\n\nCREATE OR REPLACE FUNCTION bunqueue_register_event_rows()\nRETURNS TRIGGER LANGUAGE plpgsql AS $function$\nBEGIN\n  INSERT INTO bunqueue_event_commits (namespace, transaction_id)\n  SELECT DISTINCT namespace, transaction_id FROM new_event_rows\n  ORDER BY namespace, transaction_id\n  ON CONFLICT DO NOTHING;\n  RETURN NULL;\nEND;\n$function$;\n\nCREATE OR REPLACE FUNCTION bunqueue_register_watermark_rows()\nRETURNS TRIGGER LANGUAGE plpgsql AS $function$\nBEGIN\n  INSERT INTO bunqueue_event_commits (namespace, transaction_id)\n  SELECT DISTINCT namespace, transaction_id FROM new_watermark_rows\n  ORDER BY namespace, transaction_id\n  ON CONFLICT DO NOTHING;\n  RETURN NULL;\nEND;\n$function$;\n\nCREATE OR REPLACE FUNCTION bunqueue_assign_event_commit()\nRETURNS TRIGGER LANGUAGE plpgsql AS $function$\nDECLARE\n  assigned_commit_seq BIGINT;\nBEGIN\n  PERFORM pg_advisory_xact_lock(hashtextextended(\n    'bunqueue:event-commit:' || length(NEW.namespace)::text || ':' || NEW.namespace,\n    0\n  ));\n  assigned_commit_seq := nextval('bunqueue_event_commit_seq');\n\n  UPDATE bunqueue_event_commits\n  SET commit_seq = assigned_commit_seq\n  WHERE namespace = NEW.namespace\n    AND transaction_id = NEW.transaction_id\n    AND commit_seq IS NULL;\n  UPDATE bunqueue_event_prune_watermarks\n  SET commit_seq = assigned_commit_seq,\n      pruned_commit_seq = CASE\n        WHEN prunes_current_transaction THEN GREATEST(\n          COALESCE(pruned_commit_seq, 0), assigned_commit_seq\n        )\n        ELSE pruned_commit_seq\n      END,\n      prunes_current_transaction = FALSE\n  WHERE namespace = NEW.namespace\n    AND transaction_id = NEW.transaction_id\n    AND commit_seq IS NULL;\n  RETURN NULL;\nEND;\n$function$;\n\nDROP TRIGGER IF EXISTS bunqueue_events_register_commit ON bunqueue_events;\nCREATE TRIGGER bunqueue_events_register_commit\nAFTER INSERT ON bunqueue_events\nREFERENCING NEW TABLE AS new_event_rows\nFOR EACH STATEMENT EXECUTE FUNCTION bunqueue_register_event_rows();\n\nDROP TRIGGER IF EXISTS bunqueue_watermarks_insert_register_commit\n  ON bunqueue_event_prune_watermarks;\nCREATE TRIGGER bunqueue_watermarks_insert_register_commit\nAFTER INSERT ON bunqueue_event_prune_watermarks\nREFERENCING NEW TABLE AS new_watermark_rows\nFOR EACH STATEMENT EXECUTE FUNCTION bunqueue_register_watermark_rows();\n\nDROP TRIGGER IF EXISTS bunqueue_watermarks_update_register_commit\n  ON bunqueue_event_prune_watermarks;\nCREATE TRIGGER bunqueue_watermarks_update_register_commit\nAFTER UPDATE ON bunqueue_event_prune_watermarks\nREFERENCING NEW TABLE AS new_watermark_rows\nFOR EACH STATEMENT EXECUTE FUNCTION bunqueue_register_watermark_rows();\n\nDROP TRIGGER IF EXISTS bunqueue_assign_event_commit\n  ON bunqueue_event_commits;\nCREATE CONSTRAINT TRIGGER bunqueue_assign_event_commit\nAFTER INSERT ON bunqueue_event_commits\nDEFERRABLE INITIALLY DEFERRED\nFOR EACH ROW EXECUTE FUNCTION bunqueue_assign_event_commit();\n\n\nCREATE TABLE IF NOT EXISTS bunqueue_brokers (\n  namespace TEXT NOT NULL,\n  broker_id TEXT NOT NULL,\n  session_id TEXT,\n  started_at BIGINT NOT NULL,\n  heartbeat_at BIGINT NOT NULL,\n  PRIMARY KEY (namespace, broker_id)\n);\nALTER TABLE bunqueue_brokers\n  ADD COLUMN IF NOT EXISTS session_id TEXT;\n\nDROP INDEX IF EXISTS bunqueue_jobs_live_unique_key_idx;\nCREATE UNIQUE INDEX bunqueue_jobs_live_unique_key_idx\n  ON bunqueue_jobs(namespace, queue, unique_key)\n  WHERE unique_key IS NOT NULL\n    AND state IN ('waiting', 'prioritized', 'delayed', 'waiting-children', 'active');\n";
+export declare const POSTGRES_EVENT_CHANNEL = "bunqueue_jobs_changed";

package/dist/infrastructure/persistence/postgres/schema.js

@@ -0,0 +1,257 @@
+import { POSTGRES_EVENT_JOURNAL_SCHEMA } from './eventJournalSchema';
+export const POSTGRES_SCHEMA_VERSION = 17;
+/** PostgreSQL schema for the database-authoritative distributed queue engine. */
+export const POSTGRES_SCHEMA = `
+CREATE TABLE IF NOT EXISTS bunqueue_schema_migrations (
+  version INTEGER PRIMARY KEY,
+  applied_at BIGINT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS bunqueue_jobs (
+  namespace TEXT NOT NULL,
+  id TEXT NOT NULL,
+  queue TEXT NOT NULL,
+  payload BYTEA NOT NULL,
+  state TEXT NOT NULL CHECK (
+    state IN ('waiting', 'prioritized', 'delayed', 'waiting-children',
+              'active', 'completed', 'failed')
+  ),
+  priority INTEGER NOT NULL DEFAULT 0,
+  lifo BOOLEAN NOT NULL DEFAULT FALSE,
+  run_at BIGINT NOT NULL,
+  created_at BIGINT NOT NULL,
+  started_at BIGINT,
+  completed_at BIGINT,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  max_attempts INTEGER NOT NULL DEFAULT 3,
+  ttl BIGINT,
+  timeout BIGINT,
+  unique_key TEXT,
+  unique_expires_at BIGINT,
+  custom_id TEXT,
+  group_id TEXT,
+  parent_id TEXT,
+  lease_owner TEXT,
+  lease_broker_id TEXT,
+  lease_broker_session_id TEXT,
+  lease_token TEXT,
+  lease_until BIGINT,
+  lease_renewals INTEGER NOT NULL DEFAULT 0,
+  result BYTEA,
+  dlq_entry BYTEA,
+  dlq_retry_state BYTEA,
+  error TEXT,
+  failure_reason TEXT,
+  version BIGINT NOT NULL DEFAULT 0,
+  PRIMARY KEY (namespace, id)
+);
+
+CREATE INDEX IF NOT EXISTS bunqueue_jobs_ready_idx
+  ON bunqueue_jobs(namespace, queue, priority DESC, run_at ASC, id ASC)
+  WHERE state IN ('waiting', 'prioritized', 'delayed');
+CREATE INDEX IF NOT EXISTS bunqueue_jobs_state_idx
+  ON bunqueue_jobs(namespace, queue, state, created_at, id);
+CREATE INDEX IF NOT EXISTS bunqueue_jobs_lease_idx
+  ON bunqueue_jobs(namespace, lease_until)
+  WHERE state = 'active';
+CREATE INDEX IF NOT EXISTS bunqueue_jobs_parent_idx
+  ON bunqueue_jobs(namespace, parent_id)
+  WHERE parent_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS bunqueue_jobs_group_ready_idx
+  ON bunqueue_jobs(namespace, queue, group_id, priority DESC, run_at ASC, id ASC)
+  WHERE group_id IS NOT NULL AND state IN ('waiting', 'prioritized', 'delayed');
+CREATE INDEX IF NOT EXISTS bunqueue_jobs_group_active_idx
+  ON bunqueue_jobs(namespace, queue, group_id, lease_until)
+  WHERE group_id IS NOT NULL AND state = 'active';
+CREATE INDEX IF NOT EXISTS bunqueue_jobs_lifo_ready_idx
+  ON bunqueue_jobs(namespace, queue, priority DESC, id DESC)
+  WHERE group_id IS NULL AND lifo AND state IN ('waiting', 'prioritized', 'delayed');
+CREATE INDEX IF NOT EXISTS bunqueue_jobs_ttl_pending_idx
+  ON bunqueue_jobs(namespace, queue, created_at, id)
+  WHERE ttl IS NOT NULL AND state IN ('waiting', 'prioritized', 'delayed');
+ALTER TABLE bunqueue_jobs
+  ADD COLUMN IF NOT EXISTS unique_expires_at BIGINT;
+ALTER TABLE bunqueue_jobs
+  ADD COLUMN IF NOT EXISTS lease_broker_id TEXT;
+ALTER TABLE bunqueue_jobs
+  ADD COLUMN IF NOT EXISTS lease_broker_session_id TEXT;
+ALTER TABLE bunqueue_jobs
+  ADD COLUMN IF NOT EXISTS lease_renewals INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE bunqueue_jobs
+  ADD COLUMN IF NOT EXISTS dlq_retry_state BYTEA;
+CREATE INDEX IF NOT EXISTS bunqueue_jobs_broker_session_lease_idx
+  ON bunqueue_jobs(namespace, lease_broker_id, lease_broker_session_id, id)
+  WHERE state = 'active';
+
+CREATE TABLE IF NOT EXISTS bunqueue_dependencies (
+  namespace TEXT NOT NULL,
+  job_id TEXT NOT NULL,
+  dependency_id TEXT NOT NULL,
+  PRIMARY KEY (namespace, job_id, dependency_id)
+);
+CREATE INDEX IF NOT EXISTS bunqueue_dependencies_dependency_idx
+  ON bunqueue_dependencies(namespace, dependency_id, job_id);
+
+CREATE TABLE IF NOT EXISTS bunqueue_flow_failures (
+  namespace TEXT NOT NULL,
+  parent_id TEXT NOT NULL,
+  child_id TEXT NOT NULL,
+  child_queue TEXT NOT NULL,
+  mode TEXT NOT NULL CHECK (mode IN ('fail', 'remove', 'ignore', 'continue')),
+  error TEXT NOT NULL,
+  created_at BIGINT NOT NULL,
+  PRIMARY KEY (namespace, parent_id, child_id)
+);
+CREATE INDEX IF NOT EXISTS bunqueue_flow_failures_parent_idx
+  ON bunqueue_flow_failures(namespace, parent_id, mode);
+
+CREATE TABLE IF NOT EXISTS bunqueue_repeat_links (
+  namespace TEXT NOT NULL,
+  original_id TEXT NOT NULL,
+  successor_id TEXT NOT NULL,
+  PRIMARY KEY (namespace, original_id)
+);
+CREATE INDEX IF NOT EXISTS bunqueue_repeat_links_successor_idx
+  ON bunqueue_repeat_links(namespace, successor_id);
+
+CREATE TABLE IF NOT EXISTS bunqueue_job_logs (
+  id BIGSERIAL PRIMARY KEY,
+  namespace TEXT NOT NULL,
+  job_id TEXT NOT NULL,
+  timestamp BIGINT NOT NULL,
+  level TEXT NOT NULL CHECK (level IN ('info', 'warn', 'error')),
+  message TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS bunqueue_job_logs_job_idx
+  ON bunqueue_job_logs(namespace, job_id, id);
+
+CREATE TABLE IF NOT EXISTS bunqueue_crons (
+  namespace TEXT NOT NULL,
+  name TEXT NOT NULL,
+  payload BYTEA NOT NULL,
+  next_run BIGINT NOT NULL,
+  executions INTEGER NOT NULL DEFAULT 0,
+  max_limit INTEGER,
+  updated_at BIGINT NOT NULL,
+  PRIMARY KEY (namespace, name)
+);
+CREATE INDEX IF NOT EXISTS bunqueue_crons_due_idx
+  ON bunqueue_crons(namespace, next_run, name);
+
+CREATE TABLE IF NOT EXISTS bunqueue_workers (
+  namespace TEXT NOT NULL,
+  id TEXT NOT NULL,
+  broker_id TEXT NOT NULL,
+  broker_session_id TEXT,
+  client_id TEXT,
+  queues TEXT[] NOT NULL,
+  payload BYTEA NOT NULL,
+  last_seen BIGINT NOT NULL,
+  PRIMARY KEY (namespace, id)
+);
+CREATE INDEX IF NOT EXISTS bunqueue_workers_queue_idx
+  ON bunqueue_workers USING GIN(queues);
+CREATE INDEX IF NOT EXISTS bunqueue_workers_broker_idx
+  ON bunqueue_workers(namespace, broker_id, client_id);
+ALTER TABLE bunqueue_workers
+  ADD COLUMN IF NOT EXISTS broker_session_id TEXT;
+CREATE INDEX IF NOT EXISTS bunqueue_workers_broker_session_idx
+  ON bunqueue_workers(namespace, broker_id, broker_session_id, client_id);
+
+CREATE TABLE IF NOT EXISTS bunqueue_metric_buckets (
+  namespace TEXT NOT NULL,
+  queue TEXT NOT NULL,
+  metric_type TEXT NOT NULL CHECK (metric_type IN ('completed', 'failed')),
+  minute BIGINT NOT NULL,
+  count INTEGER NOT NULL,
+  PRIMARY KEY (namespace, queue, metric_type, minute)
+);
+CREATE TABLE IF NOT EXISTS bunqueue_metric_totals (
+  namespace TEXT NOT NULL,
+  queue TEXT NOT NULL,
+  metric_type TEXT NOT NULL CHECK (metric_type IN ('completed', 'failed')),
+  total_count BIGINT NOT NULL,
+  prev_ts BIGINT NOT NULL,
+  prev_count INTEGER NOT NULL,
+  PRIMARY KEY (namespace, queue, metric_type)
+);
+
+CREATE TABLE IF NOT EXISTS bunqueue_completions (
+  namespace TEXT NOT NULL,
+  job_id TEXT NOT NULL,
+  queue TEXT NOT NULL,
+  completed_at BIGINT NOT NULL,
+  result BYTEA,
+  PRIMARY KEY (namespace, job_id)
+);
+CREATE INDEX IF NOT EXISTS bunqueue_completions_queue_idx
+  ON bunqueue_completions(namespace, queue, job_id);
+CREATE INDEX IF NOT EXISTS bunqueue_completions_recent_idx
+  ON bunqueue_completions(namespace, completed_at DESC, job_id DESC);
+
+CREATE TABLE IF NOT EXISTS bunqueue_queue_state (
+  namespace TEXT NOT NULL,
+  queue TEXT NOT NULL,
+  paused BOOLEAN NOT NULL DEFAULT FALSE,
+  rate_limit INTEGER,
+  rate_duration_ms BIGINT,
+  rate_window_started_at BIGINT,
+  rate_expires_at BIGINT,
+  rate_count INTEGER NOT NULL DEFAULT 0,
+  concurrency_limit INTEGER,
+  stall_config BYTEA,
+  dlq_config BYTEA,
+  PRIMARY KEY (namespace, queue)
+);
+
+ALTER TABLE bunqueue_queue_state
+  ADD COLUMN IF NOT EXISTS rate_expires_at BIGINT;
+
+INSERT INTO bunqueue_queue_state (namespace, queue)
+SELECT DISTINCT namespace, queue FROM bunqueue_jobs
+ON CONFLICT (namespace, queue) DO NOTHING;
+
+CREATE TABLE IF NOT EXISTS bunqueue_events (
+  id BIGSERIAL PRIMARY KEY,
+  namespace TEXT NOT NULL,
+  queue TEXT NOT NULL,
+  event_type TEXT NOT NULL,
+  job_id TEXT NOT NULL,
+  occurred_at BIGINT NOT NULL,
+  payload BYTEA
+);
+CREATE INDEX IF NOT EXISTS bunqueue_events_namespace_id_idx
+  ON bunqueue_events(namespace, id);
+CREATE INDEX IF NOT EXISTS bunqueue_events_queue_id_idx
+  ON bunqueue_events(namespace, queue, id DESC);
+
+CREATE TABLE IF NOT EXISTS bunqueue_event_prune_watermarks (
+  namespace TEXT NOT NULL,
+  queue TEXT NOT NULL,
+  source_event_id BIGINT NOT NULL,
+  pruned_through BIGINT NOT NULL,
+  PRIMARY KEY (namespace, queue, source_event_id)
+);
+CREATE INDEX IF NOT EXISTS bunqueue_event_prune_watermarks_namespace_queue_idx
+  ON bunqueue_event_prune_watermarks(namespace, queue, pruned_through DESC);
+
+${POSTGRES_EVENT_JOURNAL_SCHEMA}
+
+CREATE TABLE IF NOT EXISTS bunqueue_brokers (
+  namespace TEXT NOT NULL,
+  broker_id TEXT NOT NULL,
+  session_id TEXT,
+  started_at BIGINT NOT NULL,
+  heartbeat_at BIGINT NOT NULL,
+  PRIMARY KEY (namespace, broker_id)
+);
+ALTER TABLE bunqueue_brokers
+  ADD COLUMN IF NOT EXISTS session_id TEXT;
+
+DROP INDEX IF EXISTS bunqueue_jobs_live_unique_key_idx;
+CREATE UNIQUE INDEX bunqueue_jobs_live_unique_key_idx
+  ON bunqueue_jobs(namespace, queue, unique_key)
+  WHERE unique_key IS NOT NULL
+    AND state IN ('waiting', 'prioritized', 'delayed', 'waiting-children', 'active');
+`;
+export const POSTGRES_EVENT_CHANNEL = 'bunqueue_jobs_changed';

package/dist/infrastructure/persistence/postgres/schemaInitialization.d.ts

@@ -0,0 +1,3 @@
+import { type PostgresContext } from './context';
+/** Initialize or migrate the shared schema without locking live tables when current. */
+export declare function initializePostgresSchema(ctx: PostgresContext): Promise<void>;