pg-boss 12.19.1 → 12.21.0

package/README.md

@@ -42,15 +42,17 @@ This will likely cater the most to teams already familiar with the simplicity of
 
 ## Summary
 * Exactly-once job delivery
-* Create jobs within your existing database transaction
-* Backpressure-compatible polling workers
-* Cron scheduling
+* Create jobs in an existing db transaction, including adapters for popular ORMs such as Drizzle, Knex, Kysely, Prisma
+* Backpressure-compatible polling workers, including support for LISTEN/NOTIFY low latency delivery
+* Job dependency workflow orchestration
+* Cron scheduling, job deferral
 * Queue storage policies to support a variety of rate limiting, debouncing, and concurrency use cases
-* Priority queues, dead letter queues, job deferral, automatic retries with exponential backoff
+* Priority queues, dead letter queues, automatic retries with exponential backoff
 * Pub/sub API for fan-out queue relationships
 * SQL support for non-Node.js runtimes for most operations
 * Serverless function compatible
 * Multi-master compatible (for example, in a Kubernetes ReplicaSet)
+* [Additional database backends](https://timgit.github.io/pg-boss/database-backends) for Postgres-based databases such as CockroachDB, YugabyteDB and Citus. Or, use embedded PGlite for running entirely in-process.
 
 ## CLI
 
@@ -62,55 +64,13 @@ See the [CLI documentation](https://timgit.github.io/pg-boss/cli) for details.
 
 A web-based dashboard is available in the [`@pg-boss/dashboard`](https://www.npmjs.com/package/@pg-boss/dashboard) package for monitoring and managing jobs, queues and schedules.
 
-See the [dashboard documentation](https://github.com/timgit/pg-boss/blob/master/packages/dashboard/README.md) for full configuration and deployment options.
+See the [dashboard documentation](https://timgit.github.io/pg-boss/dashboard) for details.
 
 ## Proxy
 
 A HTTP proxy is available in the [`@pg-boss/proxy`](https://www.npmjs.com/package/@pg-boss/proxy) package if needed to support use cases such as platform compatibility and connection pooling or scalability.
 
-See the [proxy documentation](https://github.com/timgit/pg-boss/blob/master/packages/proxy/README.md) for full configuration and deployment options.
-
-## ORM Transaction Adapters
-
-pg-boss ships adapters for running operations inside ORM-managed transactions.  Each adapter wraps the ORM's transaction object as an `IDatabase` you can pass via the `db` option on `send()`, `insert()`, `fetch()`, `complete()`, and other methods.
-
-### Knex / Kysely / Prisma
-
-```ts
-import { fromKnex, fromKysely, fromPrisma } from 'pg-boss'
-```
-
-```ts
-// Knex
-await knex.transaction(async (trx) => {
-  await boss.send('my-queue', data, { db: fromKnex(trx) })
-})
-
-// Kysely
-await db.transaction().execute(async (trx) => {
-  await boss.send('my-queue', data, { db: fromKysely(trx) })
-})
-
-// Prisma (v7+ with @prisma/adapter-pg)
-await prisma.$transaction(async (tx) => {
-  await boss.send('my-queue', data, { db: fromPrisma(tx) })
-})
-```
-
-### Drizzle
-
-The Drizzle adapter accepts the `sql` tagged-template function from `drizzle-orm` as a second argument so it can construct parameterised queries without a runtime dependency on `drizzle-orm`.
-
-```ts
-import { fromDrizzle } from 'pg-boss'
-import { sql } from 'drizzle-orm'
-```
-
-```ts
-await db.transaction(async (tx) => {
-  await boss.send('my-queue', data, { db: fromDrizzle(tx, sql) })
-})
-```
+See the [proxy documentation](https://timgit.github.io/pg-boss/proxy) for details.
 
 ## Requirements
 * Node 22.12 or higher for CommonJS's require(esm)

package/dist/adapters/index.d.ts

@@ -2,8 +2,10 @@ export { fromKnex } from './knex.ts';
 export { fromKysely } from './kysely.ts';
 export { fromDrizzle } from './drizzle.ts';
 export { fromPrisma } from './prisma.ts';
+export { fromPglite } from './pglite.ts';
 export type { KnexTransactionLike } from './knex.ts';
 export type { KyselyTransactionLike } from './kysely.ts';
 export type { DrizzleTransactionLike, DrizzleSqlTagLike } from './drizzle.ts';
 export type { PrismaTransactionLike } from './prisma.ts';
+export type { PGliteLike } from './pglite.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,YAAY,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AACpD,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACxD,YAAY,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAC7E,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,YAAY,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AACpD,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACxD,YAAY,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAC7E,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACxD,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA"}

package/dist/adapters/index.js

@@ -2,3 +2,4 @@ export { fromKnex } from "./knex.js";
 export { fromKysely } from "./kysely.js";
 export { fromDrizzle } from "./drizzle.js";
 export { fromPrisma } from "./prisma.js";
+export { fromPglite } from "./pglite.js";

package/dist/adapters/pglite.d.ts

@@ -0,0 +1,12 @@
+import type { IDatabase } from '../types.ts';
+export interface PGliteLike {
+    query<T = any>(query: string, params?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+    exec(query: string): Promise<Array<{
+        rows: any[];
+    }>>;
+    listen?(channel: string, callback: (payload: string) => void): Promise<() => Promise<void>>;
+}
+export declare function fromPglite(pglite: PGliteLike): IDatabase;
+//# sourceMappingURL=pglite.d.ts.map

package/dist/adapters/pglite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pglite.d.ts","sourceRoot":"","sources":["../../src/adapters/pglite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAM5C,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,EAAE,CAAA;KAAE,CAAC,CAAA;IACzE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,GAAG,EAAE,CAAA;KAAE,CAAC,CAAC,CAAA;IACpD,MAAM,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;CAC5F;AAUD,wBAAgB,UAAU,CAAE,MAAM,EAAE,UAAU,GAAG,SAAS,CA6CzD"}

package/dist/adapters/pglite.js

@@ -0,0 +1,51 @@
+// Adapts a PGlite instance (embedded single-connection WASM PostgreSQL) to pg-boss's IDatabase.
+// PGlite is full PostgreSQL, so it needs none of the distributed compatibility flags — pair it
+// with `backend: 'pglite'`. The user owns the PGlite instance lifecycle (construction and close).
+//
+// PGlite uses native `$1` placeholders, so no placeholder translation is needed. The one wrinkle is
+// that `query()` runs a single statement only, while pg-boss issues concatenated multi-statement DDL
+// (migrations/schema creation) with no parameters — those must go through `exec()`, which mirrors the
+// simple-vs-extended protocol split that the default `pg.Pool`-backed driver relies on.
+export function fromPglite(pglite) {
+    // pg-boss issues each statement expecting connection-pool semantics: an error on one statement
+    // must not affect the next. PGlite has a single connection, so a failed statement inside a
+    // BEGIN...COMMIT block (e.g. a migration that rolls back) leaves the connection in an aborted
+    // transaction that poisons every later query. A pooled driver sidesteps this by handing out a
+    // fresh connection; we emulate it by rolling back any aborted transaction before rethrowing.
+    const run = async (text, values) => {
+        if (values?.length) {
+            return await pglite.query(text, values);
+        }
+        // No parameters: may be a multi-statement block (e.g. a `locked()` BEGIN ... RETURNING ...
+        // COMMIT). exec() returns one result per statement; flatten their rows so a RETURNING in the
+        // middle isn't lost behind a trailing COMMIT. This mirrors how pg-boss unwraps the array that
+        // node-postgres returns for multi-statement queries (see unwrapSQLResult).
+        const results = await pglite.exec(text);
+        return { rows: results.flatMap(r => r.rows ?? []) };
+    };
+    const db = {
+        async executeSql(text, values) {
+            try {
+                return await run(text, values);
+            }
+            catch (err) {
+                await pglite.query('ROLLBACK').catch(() => { });
+                throw err;
+            }
+        }
+    };
+    // PGlite is embedded single-connection PostgreSQL, so LISTEN/NOTIFY works entirely in-process:
+    // the same instance both NOTIFYs (via pg-boss's inlined pg_notify) and delivers to listeners.
+    // Only expose `listen` when the instance actually supports it (older builds/mocks may not), so
+    // the notifier cleanly falls back to polling otherwise. There is no network connection to drop,
+    // hence no reconnect loop — onReconnect is invoked once after the initial subscribe to mirror
+    // the pooled driver and force a gap-recovery fetch.
+    if (typeof pglite.listen === 'function') {
+        db.listen = async (channel, onNotification, onReconnect) => {
+            const unsubscribe = await pglite.listen(channel, onNotification);
+            onReconnect();
+            return { close: async () => { await unsubscribe(); } };
+        };
+    }
+    return db;
+}

package/dist/attorney.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attorney.d.ts","sourceRoot":"","sources":["../src/attorney.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAExC,QAAA,MAAM,MAAM;;;;CAIX,CAAA;AAMD,iBAAS,iBAAiB,CAAE,MAAM,GAAE,GAAQ,QAY3C;AAED,iBAAS,aAAa,CAAE,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,OAAO,CAgDhD;AAWD,iBAAS,gBAAgB,CAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,QA2D/C;AA2GD,iBAAS,aAAa,CAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG;IAClD,OAAO,EAAE,KAAK,CAAC,mBAAmB,CAAA;IAClC,QAAQ,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;CACjC,CA6BA;AAED,iBAAS,cAAc,CAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,QAQlD;AAED,iBAAS,SAAS,CAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC,kBAAkB,GAAG,KAAK,CAAC,0BAA0B,CAoB9F;AAwBD,iBAAS,wBAAwB,CAAE,IAAI,EAAE,MAAM,QAK9C;AAED,iBAAS,eAAe,CAAE,IAAI,EAAE,MAAM,QAIrC;AAED,iBAAS,SAAS,CAAE,GAAG,EAAE,MAAM,QAI9B;AA2GD,OAAO,EACL,SAAS,EACT,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,aAAa,EACb,aAAa,EACb,SAAS,EACT,MAAM,EACN,gBAAgB,EAChB,iBAAiB,EAClB,CAAA"}
+{"version":3,"file":"attorney.d.ts","sourceRoot":"","sources":["../src/attorney.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAExC,QAAA,MAAM,MAAM;;;;CAIX,CAAA;AAyDD,iBAAS,iBAAiB,CAAE,MAAM,GAAE,GAAQ,QAc3C;AAED,iBAAS,aAAa,CAAE,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,OAAO,CAgDhD;AAWD,iBAAS,gBAAgB,CAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,QA2D/C;AA2GD,iBAAS,aAAa,CAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG;IAClD,OAAO,EAAE,KAAK,CAAC,mBAAmB,CAAA;IAClC,QAAQ,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;CACjC,CA8BA;AAED,iBAAS,cAAc,CAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,QAQlD;AAED,iBAAS,SAAS,CAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC,kBAAkB,GAAG,KAAK,CAAC,0BAA0B,CAuB9F;AAgDD,iBAAS,wBAAwB,CAAE,IAAI,EAAE,MAAM,QAK9C;AAED,iBAAS,eAAe,CAAE,IAAI,EAAE,MAAM,QAIrC;AAED,iBAAS,SAAS,CAAE,GAAG,EAAE,MAAM,QAI9B;AAmID,OAAO,EACL,SAAS,EACT,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,aAAa,EACb,aAAa,EACb,SAAS,EACT,MAAM,EACN,gBAAgB,EAChB,iBAAiB,EAClB,CAAA"}

package/dist/attorney.js

@@ -5,11 +5,49 @@ const POLICY = {
     MIN_POLLING_INTERVAL_MS: 500,
     MAX_RETENTION_DAYS: 365
 };
+// The internal compatibility flags a backend can toggle. A backend sets only the flags that differ
+// from stock PostgreSQL; everything else defaults to false. These are derived from the backend
+// profile and are not user-configurable (see resolveBackend).
+const COMPATIBILITY_FLAGS = [
+    'noSkipLocked',
+    'noMultiMutationCte',
+    'noTablePartitioning',
+    'noDeferrableConstraints',
+    'noAdvisoryLocks',
+    'noCoveringIndexes',
+    'noListenNotify'
+];
+// The single source of truth for backend presets, mirrored by test/testHelper.ts.
+const BACKEND_PROFILES = {
+    postgres: { kind: 'standard', flags: {} },
+    cockroachdb: {
+        kind: 'distributed',
+        flags: {
+            noSkipLocked: true,
+            noMultiMutationCte: true,
+            noTablePartitioning: true,
+            noDeferrableConstraints: true,
+            noAdvisoryLocks: true,
+            noCoveringIndexes: true,
+            noListenNotify: true
+        }
+    },
+    yugabytedb: {
+        kind: 'distributed',
+        flags: {
+            noAdvisoryLocks: true,
+            noTablePartitioning: true
+        }
+    },
+    citus: { kind: 'distributed', flags: {} },
+    pglite: { kind: 'embedded', flags: {} }
+};
 function assertObjectName(value, name = 'Name') {
     assert(/^[\w.\-/]+$/.test(value), `${name} can only contain alphanumeric characters, underscores, hyphens, periods, or forward slashes`);
 }
 function validateQueueArgs(config = {}) {
     assert(!('deadLetter' in config) || config.deadLetter === null || (typeof config.deadLetter === 'string'), 'deadLetter must be a string');
+    assert(!('notify' in config) || typeof config.notify === 'boolean', 'notify must be a boolean');
     if (config.deadLetter) {
         assertObjectName(config.deadLetter, 'deadLetter');
     }
@@ -224,6 +262,7 @@ function checkWorkArgs(name, args) {
     assert(!('includeMetadata' in options) || typeof options.includeMetadata === 'boolean', 'includeMetadata must be a boolean');
     assert(!('priority' in options) || typeof options.priority === 'boolean', 'priority must be a boolean');
     assert(!('localConcurrency' in options) || (Number.isInteger(options.localConcurrency) && options.localConcurrency >= 1), 'localConcurrency must be an integer >= 1');
+    assert(!('perJobResults' in options) || typeof options.perJobResults === 'boolean', 'perJobResults must be a boolean');
     validatePriorityRangeConfig(options);
     validateGroupConcurrencyConfig(options);
     validateHeartbeatRefreshConfig(options);
@@ -246,6 +285,8 @@ function getConfig(value) {
     config.supervise = ('supervise' in config) ? config.supervise : true;
     config.migrate = ('migrate' in config) ? config.migrate : true;
     config.createSchema = ('createSchema' in config) ? config.createSchema : true;
+    config.useListenNotify = ('useListenNotify' in config) ? config.useListenNotify : false;
+    resolveBackend(config);
     applySchemaConfig(config);
     applyOpsConfig(config);
     applyScheduleConfig(config);
@@ -265,6 +306,24 @@ function validateWarningConfig(config) {
     assert(!('warningRetentionDays' in config) || (Number.isInteger(config.warningRetentionDays) && config.warningRetentionDays >= 1), 'configuration assert: warningRetentionDays must be an integer >= 1');
     assert(!('warningRetentionDays' in config) || config.warningRetentionDays <= POLICY.MAX_RETENTION_DAYS, `configuration assert: warningRetentionDays cannot exceed ${POLICY.MAX_RETENTION_DAYS} days`);
 }
+// Expands config.backend into the internal compatibility flags. The flags are derived
+// solely from the backend profile — they are not part of the public input, so a
+// deployment can't end up with an inconsistent combination.
+function resolveBackend(config) {
+    const backend = ('backend' in config) ? config.backend : 'postgres';
+    assert(backend in BACKEND_PROFILES, `configuration assert: backend must be one of ${Object.keys(BACKEND_PROFILES).join(', ')}`);
+    config.backend = backend;
+    const { flags } = BACKEND_PROFILES[backend];
+    for (const flag of COMPATIBILITY_FLAGS) {
+        config[flag] = flags[flag] ?? false;
+    }
+    // Test hook: exercise the distributed runtime paths (atomic fetch + split mutations)
+    // on top of the current backend's schema, without standing up a distributed database.
+    if (config.__test__distributed) {
+        config.noSkipLocked = true;
+        config.noMultiMutationCte = true;
+    }
+}
 function assertPostgresObjectName(name) {
     assert(typeof name === 'string', 'Name must be a string');
     assert(name.length <= 50, 'Name cannot exceed 50 characters');
@@ -309,6 +368,23 @@ function applyPollingInterval(config) {
     config.pollingInterval = ('pollingIntervalSeconds' in config)
         ? config.pollingIntervalSeconds * 1000
         : 2000;
+    assert(!('notifyPollingIntervalSeconds' in config) || config.notifyPollingIntervalSeconds >= POLICY.MIN_POLLING_INTERVAL_MS / 1000, `configuration assert: notifyPollingIntervalSeconds must be at least every ${POLICY.MIN_POLLING_INTERVAL_MS}ms`);
+    // Relaxed backstop poll used only while NOTIFY is active for the queue; falls back to
+    // pollingInterval when notify is unavailable. It must never be smaller than the base poll —
+    // that would make a notify-active queue poll more aggressively than an idle one, the opposite
+    // of the intent. When explicit, reject a value below the base; when defaulted, floor it at the
+    // base so bumping pollingIntervalSeconds past 30s can't silently leave notify smaller.
+    if ('notifyPollingIntervalSeconds' in config) {
+        config.notifyPollingInterval = config.notifyPollingIntervalSeconds * 1000;
+        assert(config.notifyPollingInterval >= config.pollingInterval, 'configuration assert: notifyPollingIntervalSeconds must be at least pollingIntervalSeconds');
+    }
+    else {
+        config.notifyPollingInterval = Math.max(30000, config.pollingInterval);
+    }
+    // Burst triggers: no transform, just validation. Both put the worker into continuous-fetch
+    // (no delay) mode; see JobPollingOptions for precedence.
+    assert(!('burstWhenReadyExceeds' in config) || (Number.isInteger(config.burstWhenReadyExceeds) && config.burstWhenReadyExceeds >= 1), 'configuration assert: burstWhenReadyExceeds must be an integer >= 1');
+    assert(!('burstWhenBatchFull' in config) || typeof config.burstWhenBatchFull === 'boolean', 'configuration assert: burstWhenBatchFull must be a boolean');
 }
 function applyOpsConfig(config) {
     assert(!('superviseIntervalSeconds' in config) || config.superviseIntervalSeconds >= 1, 'configuration assert: superviseIntervalSeconds must be at least every second');

package/dist/boss.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"boss.d.ts","sourceRoot":"","sources":["../src/boss.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AACtC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAGvC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAkBnC,cAAM,IAAK,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;;IAS1D,MAAM;;;MAAS;gBAGb,EAAE,EAAE,KAAK,CAAC,SAAS,EACnB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAmB1C,IAAI,WAAW,IAAK,OAAO,CAE1B;IAEK,KAAK;IAWL,IAAI;IA+EJ,SAAS,CAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE;CAwGtD;AAED,eAAe,IAAI,CAAA"}
+{"version":3,"file":"boss.d.ts","sourceRoot":"","sources":["../src/boss.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AACtC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAGvC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAkBnC,cAAM,IAAK,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;;IAS1D,MAAM;;;MAAS;gBAGb,EAAE,EAAE,KAAK,CAAC,SAAS,EACnB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAmB1C,IAAI,WAAW,IAAK,OAAO,CAE1B;IAEK,KAAK;IAWL,IAAI;IA+EJ,SAAS,CAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE;CAqHtD;AAED,eAAe,IAAI,CAAA"}

package/dist/boss.js

@@ -151,22 +151,37 @@ class Boss extends EventEmitter {
             return;
         if (rows.length) {
             const queues = rows.map((q) => q.name);
-            const cacheStatsSql = plans.cacheQueueStats(this.#config.schema, table, queues);
+            const cacheStatsSql = plans.cacheQueueStats(this.#config.schema, table, queues, this.#config.noAdvisoryLocks);
             const { rows: rowsCacheStats } = await this.#executeQuery(cacheStatsSql);
             if (this.#stopping)
                 return;
-            const warnings = rowsCacheStats.filter(i => i.queuedCount > (i.warningQueueSize || WARNINGS.LARGE_QUEUE.size));
+            // Coerce with Number(): CockroachDB returns these integer columns as strings, so a bare `>`
+            // would compare lexicographically ("100" > "9" === false) and silently miss the backlog. On
+            // standard Postgres these are already numbers, so Number() is a no-op.
+            const warnings = rowsCacheStats.filter(i => Number(i.queuedCount) > (Number(i.warningQueueSize) || WARNINGS.LARGE_QUEUE.size));
             for (const warning of warnings) {
                 await emitAndPersistWarning(this.#warningContext, WARNING_TYPES.QUEUE_BACKLOG, WARNINGS.LARGE_QUEUE.message, warning);
             }
-            const sql = plans.failJobsByTimeout(this.#config.schema, table, queues);
-            await this.#executeQuery(sql);
+            // CockroachDB rejects the multi-mutation failJobs() CTE these use, so under noMultiMutationCte
+            // route expiry through the manager's split select/delete/re-insert variants instead.
+            if (this.#config.noMultiMutationCte) {
+                await this.#manager.failJobsByTimeoutDistributed(table, queues);
+            }
+            else {
+                const sql = plans.failJobsByTimeout(this.#config.schema, table, queues, this.#config.noAdvisoryLocks);
+                await this.#executeQuery(sql);
+            }
             if (this.#stopping)
                 return;
             const heartbeatQueues = queues.filter(q => heartbeatQueueNames.has(q));
             if (heartbeatQueues.length) {
-                const heartbeatSql = plans.failJobsByHeartbeat(this.#config.schema, table, heartbeatQueues);
-                await this.#executeQuery(heartbeatSql);
+                if (this.#config.noMultiMutationCte) {
+                    await this.#manager.failJobsByHeartbeatDistributed(table, heartbeatQueues);
+                }
+                else {
+                    const heartbeatSql = plans.failJobsByHeartbeat(this.#config.schema, table, heartbeatQueues, this.#config.noAdvisoryLocks);
+                    await this.#executeQuery(heartbeatSql);
+                }
             }
         }
     }
@@ -179,9 +194,9 @@ class Boss extends EventEmitter {
             return;
         if (rows.length) {
             const queues = rows.map((q) => q.name);
-            const sql = plans.deletion(this.#config.schema, table, queues);
+            const sql = plans.deletion(this.#config.schema, table, queues, this.#config.noAdvisoryLocks);
             await this.#executeQuery(sql);
-            const depSql = plans.cleanupDependencies(this.#config.schema, table, queues);
+            const depSql = plans.cleanupDependencies(this.#config.schema, table, queues, this.#config.noAdvisoryLocks);
             await this.#executeQuery(depSql);
         }
     }

package/dist/cli.js

@@ -146,6 +146,27 @@ async function createDb(config) {
     await db.open();
     return db;
 }
+// Like getConnectionConfig, but returns null instead of exiting when no connection is
+// configured — used by commands (e.g. `plans`) where a connection is optional.
+function tryGetConnectionConfig(args) {
+    const fileConfig = loadConfigFile(args.config);
+    const hasConnection = args.connectionString || process.env.PGBOSS_DATABASE_URL || fileConfig.connectionString ||
+        args.host || process.env.PGBOSS_HOST || fileConfig.host ||
+        args.database || process.env.PGBOSS_DATABASE || fileConfig.database;
+    return hasConnection ? getConnectionConfig(args) : null;
+}
+// Enumerates partitioned queue table names so inlined index builds can fan out across
+// them. Returns [] on any failure (e.g. unreachable DB or pre-partition schema), leaving
+// the export to target job_common only.
+async function getPartitionTables(db, schema) {
+    try {
+        const result = await db.executeSql(plans.getPartitionedQueueTables(schema));
+        return result.rows.map((row) => row.table_name);
+    }
+    catch {
+        return [];
+    }
+}
 async function getSchemaVersion(db, schema) {
     try {
         const result = await db.executeSql(plans.versionTableExists(schema));
@@ -212,7 +233,22 @@ async function cmdMigrate(args) {
     const config = getConnectionConfig(args);
     const schema = config.schema || plans.DEFAULT_SCHEMA;
     if (args.dryRun) {
-        const sql = migrationStore.migrate(schema, 0);
+        // The CLI has no BAM worker, so inline the async index builds as direct DDL. Connect
+        // (best effort) to enumerate partitioned tables; fall back to job_common only offline.
+        let partitionTables = [];
+        try {
+            const db = await createDb(config);
+            try {
+                partitionTables = await getPartitionTables(db, schema);
+            }
+            finally {
+                await db.close();
+            }
+        }
+        catch {
+            // no reachable database: emit a job_common-only static script
+        }
+        const sql = migrationStore.migrate(schema, 0, undefined, undefined, { inlineAsync: true, partitionTables });
         console.log('-- SQL to migrate pg-boss from version 0 to latest:');
         console.log(sql);
         return;
@@ -232,8 +268,15 @@ async function cmdMigrate(args) {
             return;
         }
         console.log(`Migrating pg-boss schema "${schema}" from version ${version} to ${schemaVersion}...`);
-        const sql = migrationStore.migrate(schema, version);
+        // Inline the async index builds rather than enqueuing BAM rows that nothing will run
+        // (the CLI exits without a worker); enumerate partitions so they are covered too.
+        const partitionTables = await getPartitionTables(db, schema);
+        const { sql, concurrent } = migrationStore.migrateCommands(schema, version, undefined, undefined, { inlineAsync: true, partitionTables });
         await db.executeSql(sql);
+        // CONCURRENTLY index builds must run outside the migration transaction, one at a time.
+        for (const statement of concurrent) {
+            await db.executeSql(statement);
+        }
         console.log(`Successfully migrated pg-boss schema "${schema}" to version ${schemaVersion}`);
     }
     finally {
@@ -279,10 +322,34 @@ async function cmdPlans(args) {
             console.log('-- SQL to create pg-boss schema:');
             console.log(plans.create(schema, schemaVersion, { createSchema: true }));
             break;
-        case 'migrate':
+        case 'migrate': {
+            // Inline the async index builds (no BAM worker runs an exported script). A connection
+            // is optional: with one, fan the builds out across partitioned tables; without one,
+            // emit a job_common-only script and note the limitation.
+            const connectionConfig = tryGetConnectionConfig(args);
+            let partitionTables = [];
+            if (connectionConfig) {
+                try {
+                    const db = await createDb(connectionConfig);
+                    try {
+                        partitionTables = await getPartitionTables(db, schema);
+                    }
+                    finally {
+                        await db.close();
+                    }
+                }
+                catch {
+                    // unreachable database: fall back to a job_common-only script
+                }
+            }
             console.log('-- SQL to migrate pg-boss (from version 0 to latest):');
-            console.log(migrationStore.migrate(schema, 0));
+            if (!connectionConfig) {
+                console.log('-- note: no database connection provided; partitioned queue tables were not enumerated.');
+                console.log('-- Run with a connection (e.g. --connection-string) to include per-partition index builds.');
+            }
+            console.log(migrationStore.migrate(schema, 0, undefined, undefined, { inlineAsync: true, partitionTables }));
             break;
+        }
         case 'rollback':
             console.log(`-- SQL to rollback pg-boss from version ${schemaVersion} to ${schemaVersion - 1}:`);
             console.log(migrationStore.rollback(schema, schemaVersion));

package/dist/contractor.d.ts

@@ -3,7 +3,9 @@ declare class Contractor {
     static constructionPlans(schema?: string, options?: {
         createSchema: boolean;
     }): string;
-    static migrationPlans(schema?: string, version?: number): string;
+    static migrationPlans(schema?: string, version?: number, options?: {
+        partitionTables?: string[];
+    }): string;
     static rollbackPlans(schema?: string, version?: number): string;
     private config;
     private db;

package/dist/contractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contractor.d.ts","sourceRoot":"","sources":["../src/contractor.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAIxC,cAAM,UAAU;IACd,MAAM,CAAC,iBAAiB,CAAE,MAAM,SAAuB,EAAE,OAAO;;KAAyB;IAIzF,MAAM,CAAC,cAAc,CAAE,MAAM,SAAuB,EAAE,OAAO,SAAoB;IAIjF,MAAM,CAAC,aAAa,CAAE,MAAM,SAAuB,EAAE,OAAO,SAAgB;IAI5E,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,EAAE,CAAiB;IAC3B,OAAO,CAAC,UAAU,CAAmB;gBAExB,EAAE,EAAE,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAMpE,aAAa;IAKb,WAAW;IAKX,KAAK;IAcL,KAAK;IAcL,MAAM;IASN,OAAO,CAAE,OAAO,EAAE,MAAM;IASxB,IAAI,CAAE,OAAO,EAAE,MAAM;IAKrB,QAAQ,CAAE,OAAO,EAAE,MAAM;CAIhC;AAED,eAAe,UAAU,CAAA"}
+{"version":3,"file":"contractor.d.ts","sourceRoot":"","sources":["../src/contractor.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAIxC,cAAM,UAAU;IACd,MAAM,CAAC,iBAAiB,CAAE,MAAM,SAAuB,EAAE,OAAO;;KAAyB;IAIzF,MAAM,CAAC,cAAc,CAAE,MAAM,SAAuB,EAAE,OAAO,SAAoB,EAAE,OAAO,GAAE;QAAE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;KAAO;IAO/H,MAAM,CAAC,aAAa,CAAE,MAAM,SAAuB,EAAE,OAAO,SAAgB;IAI5E,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,EAAE,CAAiB;IAC3B,OAAO,CAAC,UAAU,CAAmB;gBAExB,EAAE,EAAE,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAMpE,aAAa;IAKb,WAAW;IAKX,KAAK;IAcL,KAAK;IAcL,MAAM;IASN,OAAO,CAAE,OAAO,EAAE,MAAM;IASxB,IAAI,CAAE,OAAO,EAAE,MAAM;IAKrB,QAAQ,CAAE,OAAO,EAAE,MAAM;CAIhC;AAED,eAAe,UAAU,CAAA"}

package/dist/contractor.js

@@ -7,8 +7,11 @@ class Contractor {
     static constructionPlans(schema = plans.DEFAULT_SCHEMA, options = { createSchema: true }) {
         return plans.create(schema, schemaVersion, options);
     }
-    static migrationPlans(schema = plans.DEFAULT_SCHEMA, version = schemaVersion - 1) {
-        return migrationStore.migrate(schema, version);
+    static migrationPlans(schema = plans.DEFAULT_SCHEMA, version = schemaVersion - 1, options = {}) {
+        // Exported plans run without a BAM worker, so inline the async index builds as direct
+        // DDL rather than job_table_run_async() enqueues (see issue #766). Callers that hold a
+        // live connection can pass partitionTables to fan the builds out across partitions.
+        return migrationStore.migrate(schema, version, undefined, undefined, { inlineAsync: true, partitionTables: options.partitionTables });
     }
     static rollbackPlans(schema = plans.DEFAULT_SCHEMA, version = schemaVersion) {
         return migrationStore.rollback(schema, version);
@@ -62,7 +65,7 @@ class Contractor {
     }
     async migrate(version) {
         try {
-            const commands = migrationStore.migrate(this.config.schema, version, this.migrations);
+            const commands = migrationStore.migrate(this.config.schema, version, this.migrations, this.config.noAdvisoryLocks);
             await this.db.executeSql(commands);
         }
         catch (err) {
@@ -70,11 +73,11 @@ class Contractor {
         }
     }
     async next(version) {
-        const commands = migrationStore.next(this.config.schema, version, this.migrations);
+        const commands = migrationStore.next(this.config.schema, version, this.migrations, this.config.noAdvisoryLocks);
         await this.db.executeSql(commands);
     }
     async rollback(version) {
-        const commands = migrationStore.rollback(this.config.schema, version, this.migrations);
+        const commands = migrationStore.rollback(this.config.schema, version, this.migrations, this.config.noAdvisoryLocks);
         await this.db.executeSql(commands);
     }
 }

package/dist/db.d.ts

@@ -11,6 +11,7 @@ declare class Db extends EventEmitter implements types.IDatabase, types.EventsMi
     open(): Promise<void>;
     close(): Promise<void>;
     executeSql(text: string, values?: unknown[]): Promise<import("pg").QueryResult<any>>;
+    listen(channel: string, onNotification: (payload: string) => void, onReconnect: () => void): Promise<types.ListenHandle>;
     withTransaction<T>(fn: (db: types.IDatabase) => Promise<T>): Promise<T>;
 }
 export default Db;

package/dist/db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AAGtC,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAExC,cAAM,EAAG,SAAQ,YAAa,YAAW,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,WAAW;IACzE,OAAO,CAAC,IAAI,CAAU;IACtB,OAAO,CAAC,MAAM,CAAuB;IAGrC,MAAM,EAAE,OAAO,CAAA;gBAEF,MAAM,EAAE,KAAK,CAAC,eAAe;IAY1C,MAAM;;MAEL;IAEK,IAAI;IAMJ,KAAK;IAOL,UAAU,CAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE;IAgB5C,eAAe,CAAC,CAAC,EAAG,EAAE,EAAE,CAAC,EAAE,EAAE,KAAK,CAAC,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAmB/E;AAED,eAAe,EAAE,CAAA"}
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AAGtC,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAExC,cAAM,EAAG,SAAQ,YAAa,YAAW,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,WAAW;IACzE,OAAO,CAAC,IAAI,CAAU;IACtB,OAAO,CAAC,MAAM,CAAuB;IAGrC,MAAM,EAAE,OAAO,CAAA;gBAEF,MAAM,EAAE,KAAK,CAAC,eAAe;IAY1C,MAAM;;MAEL;IAEK,IAAI;IAMJ,KAAK;IAOL,UAAU,CAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE;IAoB5C,MAAM,CACV,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,EACzC,WAAW,EAAE,MAAM,IAAI,GACtB,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC;IA4ExB,eAAe,CAAC,CAAC,EAAG,EAAE,EAAE,CAAC,EAAE,EAAE,KAAK,CAAC,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAmB/E;AAED,eAAe,EAAE,CAAA"}

package/dist/db.js

@@ -42,6 +42,80 @@ class Db extends EventEmitter {
         // }
         return await this.pool.query(text, values);
     }
+    // Opens a dedicated, session-pinned connection for LISTEN/NOTIFY. A separate pg.Client
+    // (not a pooled connection) is used so the listener never depletes the query pool and so
+    // reconnection is self-contained. On any drop the client reconnects with capped backoff
+    // and re-runs LISTEN, then calls onReconnect so the caller can recover missed messages.
+    async listen(channel, onNotification, onReconnect) {
+        assert(this.opened, 'Database not opened. Call open() before listening.');
+        let closed = false;
+        let client = null;
+        let reconnectTimer = null;
+        let attempt = 0;
+        const scheduleReconnect = () => {
+            if (closed || reconnectTimer)
+                return;
+            const backoff = Math.min(30000, 1000 * 2 ** Math.min(attempt, 5));
+            attempt++;
+            reconnectTimer = setTimeout(() => {
+                reconnectTimer = null;
+                connect().catch(() => scheduleReconnect());
+            }, backoff);
+        };
+        const connect = async () => {
+            if (closed)
+                return;
+            const next = new pg.Client(this.config);
+            next.on('error', error => {
+                this.emit('error', error);
+                if (!closed) {
+                    next.removeAllListeners();
+                    next.end().catch(() => { });
+                    if (client === next)
+                        client = null;
+                    scheduleReconnect();
+                }
+            });
+            next.on('notification', msg => {
+                if (msg.payload !== undefined)
+                    onNotification(msg.payload);
+            });
+            // Track the client before connecting so close() can tear down a connect still in flight
+            // (e.g. shutdown during a reconnect). If connect or LISTEN then rejects, the catch ends
+            // it and rethrows — without that, a LISTEN that fails after connect() succeeded would
+            // leak an open connection. The reconnect .catch below reschedules on failure; an initial
+            // failure propagates to the caller.
+            client = next;
+            try {
+                await next.connect();
+                await next.query(`LISTEN "${channel}"`);
+            }
+            catch (err) {
+                next.removeAllListeners();
+                await next.end().catch(() => { });
+                if (client === next)
+                    client = null;
+                throw err;
+            }
+            attempt = 0;
+            onReconnect();
+        };
+        await connect();
+        return {
+            close: async () => {
+                closed = true;
+                if (reconnectTimer) {
+                    clearTimeout(reconnectTimer);
+                    reconnectTimer = null;
+                }
+                if (client) {
+                    client.removeAllListeners();
+                    await client.end().catch(() => { });
+                    client = null;
+                }
+            }
+        };
+    }
     async withTransaction(fn) {
         assert(this.opened, 'Database not opened. Call open() before executing SQL.');
         const client = await this.pool.connect();