pg-boss 12.30.0 → 12.31.0

package/README.md

@@ -46,7 +46,7 @@ This will likely cater the most to teams already familiar with the simplicity of
 * 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
+* Cron and RRULE scheduling, job deferral
 * Queue storage policies to support a variety of rate limiting, debouncing, and concurrency use cases
 * Priority queues, dead letter queues with redrive, automatic retries with exponential backoff
 * Pub/sub API for fan-out queue relationships
@@ -85,10 +85,10 @@ pg-boss is MIT licensed and always will be. It is maintained by one person, and
 
 <!-- sponsors:start The logos below are generated from GitHub Sponsors by scripts/sync-sponsors.js. Do not edit them directly. -->
 <div style="display: flex; flex-wrap: wrap; gap: 1rem; align-items: center; margin: 1.5rem 0;">
-  <a href="https://superpower.com/" target="_blank" rel="noopener"><img src="https://avatars.githubusercontent.com/u/114334709?s=200&amp;v=4" alt="Superpower" title="Superpower" width="96" height="96" style="border-radius: 8px;"></a>
-  <a href="https://altruistiq.com/" target="_blank" rel="noopener"><img src="https://avatars.githubusercontent.com/u/88195975?s=200&amp;v=4" alt="Altruistiq" title="Altruistiq" width="64" height="64" style="border-radius: 8px;"></a>
-  <a href="https://wasp.sh/" target="_blank" rel="noopener"><img src="https://avatars.githubusercontent.com/u/55102317?s=200&amp;v=4" alt="wasp-lang" title="wasp-lang" width="64" height="64" style="border-radius: 8px;"></a>
-  <a href="https://github.com/Ferry-Health" target="_blank" rel="noopener"><img src="https://avatars.githubusercontent.com/u/158637456?s=200&amp;v=4" alt="Ferry Health" title="Ferry Health" width="64" height="64" style="border-radius: 8px;"></a>
+  <a href="https://superpower.com/" target="_blank" rel="noopener"><img src="https://avatars.githubusercontent.com/u/114334709?s=256&amp;v=4" alt="Superpower" title="Superpower" width="96" height="96" style="border-radius: 8px;"></a>
+  <a href="https://altruistiq.com/" target="_blank" rel="noopener"><img src="https://avatars.githubusercontent.com/u/88195975?s=256&amp;v=4" alt="Altruistiq" title="Altruistiq" width="64" height="64" style="border-radius: 8px;"></a>
+  <a href="https://wasp.sh/" target="_blank" rel="noopener"><img src="https://avatars.githubusercontent.com/u/55102317?s=256&amp;v=4" alt="wasp-lang" title="wasp-lang" width="64" height="64" style="border-radius: 8px;"></a>
+  <a href="https://github.com/Ferry-Health" target="_blank" rel="noopener"><img src="https://avatars.githubusercontent.com/u/158637456?s=256&amp;v=4" alt="Ferry Health" title="Ferry Health" width="64" height="64" style="border-radius: 8px;"></a>
 </div>
 <!-- sponsors:end -->
 

package/dist/adapters/bun.d.ts

@@ -0,0 +1,33 @@
+import type { IDatabase } from '../types.ts';
+export interface BunSqlLike {
+    unsafe(text: string, values?: unknown[]): Promise<unknown>;
+    reserve(): Promise<BunReservedSqlLike>;
+    listen?(channel: string, onNotification: (payload: string) => void, onSubscribe?: () => void): Promise<BunSubscriptionLike>;
+}
+export interface BunSubscriptionLike {
+    unlisten(): Promise<void> | void;
+}
+export interface BunReservedSqlLike {
+    unsafe(text: string, values?: unknown[]): Promise<unknown>;
+    release(): void;
+}
+/**
+ * Adapts a `Bun.SQL` client to pg-boss's IDatabase, for running pg-boss on Bun's built-in
+ * PostgreSQL driver instead of the bundled `pg` pool.
+ *
+ * @example
+ * ```ts
+ * import { SQL } from 'bun'
+ * import { PgBoss, fromBunSql } from 'pg-boss'
+ *
+ * const boss = new PgBoss({ db: fromBunSql(new SQL(connectionString)) })
+ * await boss.start()
+ * ```
+ *
+ * The caller owns the client's lifecycle: pg-boss never calls `end()` on it.
+ *
+ * `useListenNotify` needs `sql.listen()`, which Bun added in 1.4.0. On an older runtime the adapter
+ * exposes no `listen` and pg-boss falls back to polling.
+ */
+export declare function fromBunSql(client: BunSqlLike): IDatabase;
+//# sourceMappingURL=bun.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bun.d.ts","sourceRoot":"","sources":["../../src/adapters/bun.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAM5C,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC1D,OAAO,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAAA;IAEtC,MAAM,CAAC,CACL,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,EACzC,WAAW,CAAC,EAAE,MAAM,IAAI,GACvB,OAAO,CAAC,mBAAmB,CAAC,CAAA;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CACjC;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC1D,OAAO,IAAI,IAAI,CAAA;CAChB;AAeD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAE,MAAM,EAAE,UAAU,GAAG,SAAS,CAiCzD"}

package/dist/adapters/bun.js

@@ -0,0 +1,86 @@
+import { expandArrayParams } from "./placeholders.js";
+// pg-boss ships schema installation, migration and maintenance as `BEGIN; ... COMMIT;` scripts
+// (plans.transaction / plans.locked). Bun rejects those on a pooled connection with `Only use
+// sql.begin, sql.reserved or max: 1`, because the pool is free to hand the next statement to a
+// different connection. A reserved connection is pinned for its lifetime and takes them as-is.
+const STARTS_TRANSACTION = /^\s*BEGIN\b/i;
+// Bun reports every server error as ERR_POSTGRES_SERVER_ERROR and puts the SQLSTATE in `errno`,
+// where node-postgres puts it in `code`. pg-boss reads `code` to recognise a handful of states it
+// treats as control flow rather than failure - 23505 from a lost fetch race, 22012 from the
+// in-SQL insert guard, 25001 from REINDEX inside a transaction - so an unmapped error turns a
+// tolerated race into a thrown one.
+const BUN_SERVER_ERROR = 'ERR_POSTGRES_SERVER_ERROR';
+/**
+ * Adapts a `Bun.SQL` client to pg-boss's IDatabase, for running pg-boss on Bun's built-in
+ * PostgreSQL driver instead of the bundled `pg` pool.
+ *
+ * @example
+ * ```ts
+ * import { SQL } from 'bun'
+ * import { PgBoss, fromBunSql } from 'pg-boss'
+ *
+ * const boss = new PgBoss({ db: fromBunSql(new SQL(connectionString)) })
+ * await boss.start()
+ * ```
+ *
+ * The caller owns the client's lifecycle: pg-boss never calls `end()` on it.
+ *
+ * `useListenNotify` needs `sql.listen()`, which Bun added in 1.4.0. On an older runtime the adapter
+ * exposes no `listen` and pg-boss falls back to polling.
+ */
+export function fromBunSql(client) {
+    const db = {
+        async executeSql(text, values) {
+            const query = expandArrayParams(text, values);
+            // A parameterless call goes through the simple protocol, which is what lets a multi-statement
+            // script run at all; pg-boss only ever concatenates statements when there is nothing to bind.
+            const run = (target) => query.values.length
+                ? target.unsafe(query.text, query.values)
+                : target.unsafe(query.text);
+            try {
+                return unwrapBunResult(await (STARTS_TRANSACTION.test(text) ? runReserved(client, run) : run(client)));
+            }
+            catch (err) {
+                throw withSqlState(err);
+            }
+        }
+    };
+    // Bun's third argument fires on the initial subscribe and again after each reconnect - it
+    // re-establishes the connection and re-subscribes every channel on its own - which is exactly
+    // what pg-boss's onReconnect is for: a notification sent while the listener was down is gone,
+    // so the gap has to be closed by a fetch. Only expose `listen` when the client actually has it
+    // (Bun < 1.4.0, or a mock), so the notifier cleanly falls back to polling otherwise.
+    if (typeof client.listen === 'function') {
+        db.listen = async (channel, onNotification, onReconnect) => {
+            const subscription = await client.listen(channel, onNotification, onReconnect);
+            return { close: async () => { await subscription.unlisten(); } };
+        };
+    }
+    return db;
+}
+async function runReserved(client, run) {
+    const reserved = await client.reserve();
+    try {
+        return await run(reserved);
+    }
+    finally {
+        reserved.release();
+    }
+}
+// Bun returns the rows of a single statement as a flat array, and one such array per statement for
+// a multi-statement script. Flatten the latter so a RETURNING in the middle of a transaction block
+// is not lost behind the trailing COMMIT's empty result - the same unwrapping the PGlite adapter
+// does for exec() and pg-boss does for node-postgres (see unwrapSQLResult).
+function unwrapBunResult(result) {
+    if (!Array.isArray(result)) {
+        return { rows: [] };
+    }
+    return { rows: result.some(Array.isArray) ? result.flat() : result };
+}
+function withSqlState(err) {
+    const error = err;
+    if (error?.code === BUN_SERVER_ERROR && error.errno) {
+        error.code = error.errno;
+    }
+    return err;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"drizzle.d.ts","sourceRoot":"","sources":["../../src/adapters/drizzle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAI5C,MAAM,WAAW,sBAAsB;IAGrC,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,GAAG,EAAE,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,GAAG,EAAE,CAAA;KAAE,EAAE,GAAG,GAAG,EAAE,CAAC,CAAA;CAC9E;AAED,MAAM,WAAW,iBAAiB;IAChC,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAA;IAC9D,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAA;CAC/B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAE,EAAE,EAAE,sBAAsB,EAAE,GAAG,EAAE,iBAAiB,GAAG,SAAS,CAa1F"}
+{"version":3,"file":"drizzle.d.ts","sourceRoot":"","sources":["../../src/adapters/drizzle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAI5C,MAAM,WAAW,sBAAsB;IAGrC,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,GAAG,EAAE,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,GAAG,EAAE,CAAA;KAAE,EAAE,GAAG,GAAG,EAAE,CAAC,CAAA;CAC9E;AAED,MAAM,WAAW,iBAAiB;IAChC,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAA;IAC9D,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAA;CAC/B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAE,EAAE,EAAE,sBAAsB,EAAE,GAAG,EAAE,iBAAiB,GAAG,SAAS,CAQ1F"}

package/dist/adapters/drizzle.js

@@ -1,4 +1,4 @@
-import { parsePlaceholders } from "./placeholders.js";
+import { ARRAY_CAST, parsePlaceholders } from "./placeholders.js";
 import { unwrapSQLResult } from "../tools.js";
 /**
  * Wraps a drizzle-orm transaction as an {@link IDatabase}.
@@ -21,13 +21,50 @@ export function fromDrizzle(tx, sql) {
     return {
         async executeSql(text, values) {
             const { parts, reordered } = parsePlaceholders(text, values);
-            const strings = Object.assign([...parts], { raw: [...parts] });
-            // Bind each value through sql.param so drizzle emits exactly one placeholder
-            // per value. A bare array would otherwise be expanded into a parameter list
-            // ($2, $3, ...) instead of a single array-typed parameter, breaking any query
-            // with `= ANY($N::uuid[])` (deleteJob/complete/fail/cancel/resume/retry).
-            const params = reordered.map(value => sql.param(value));
+            const { strings, params } = buildQuery(parts, reordered, sql);
             return unwrapSQLResult(await tx.execute(sql(strings, ...params)));
         }
     };
 }
+// A parameter cast to an array type (`$N::uuid[]`) is expanded into an inline
+// ARRAY[...] constructor of scalar parameters rather than bound whole.
+//
+// Binding the array whole (sql.param([a, b])) is what postgres wants, and it is
+// what node-postgres and postgres-js do, but Bun's SQL client cannot encode a JS
+// array: it stringifies it to `a,b`, and every `= ANY($N::uuid[])` in pg-boss then
+// fails with `malformed array literal` (oven-sh/bun#18775). Letting drizzle expand
+// the array on its own is no better - it emits a bare `$2, $3` list, which is not
+// valid where the statement expects one array expression.
+//
+// ARRAY[$2, $3] is valid everywhere a single array parameter was, keeps every
+// element a real bind parameter (so no value is ever escaped into SQL text), and
+// carries no driver-specific knowledge.
+//
+// The array cast is what makes the rewrite safe to apply, so it is required rather
+// than assumed (see ARRAY_CAST).
+function buildQuery(parts, values, sql) {
+    const literals = [];
+    const params = [];
+    let pending = parts[0];
+    for (let i = 0; i < values.length; i++) {
+        const value = values[i];
+        if (Array.isArray(value) && ARRAY_CAST.test(parts[i + 1])) {
+            // ARRAY[] alone has no element type; the cast that qualified this parameter
+            // for the rewrite is what resolves it.
+            pending += 'ARRAY[';
+            for (let element = 0; element < value.length; element++) {
+                literals.push(pending);
+                params.push(sql.param(value[element]));
+                pending = element === value.length - 1 ? '' : ',';
+            }
+            pending += ']' + parts[i + 1];
+            continue;
+        }
+        literals.push(pending);
+        params.push(sql.param(value));
+        pending = parts[i + 1];
+    }
+    literals.push(pending);
+    const strings = Object.assign(literals, { raw: [...literals] });
+    return { strings, params };
+}

package/dist/adapters/index.d.ts

@@ -3,9 +3,11 @@ export { fromKysely } from './kysely.ts';
 export { fromDrizzle } from './drizzle.ts';
 export { fromPrisma } from './prisma.ts';
 export { fromPglite } from './pglite.ts';
+export { fromBunSql } from './bun.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';
+export type { BunSqlLike, BunReservedSqlLike } from './bun.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;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"}
+{"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;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAErC,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;AAC7C,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA"}

package/dist/adapters/index.js

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

package/dist/adapters/placeholders.d.ts

@@ -11,4 +11,19 @@ export declare function parsePlaceholders(text: string, values?: readonly unknow
     parts: string[];
     reordered: unknown[];
 };
+export declare const ARRAY_CAST: RegExp;
+/**
+ * Rewrites `$N` placeholders into a fresh sequential list, expanding any array-cast parameter
+ * into an inline `ARRAY[...]` constructor of scalar parameters.
+ *
+ * Postgres wants an array bound whole, and node-postgres, postgres-js and PGlite all encode one.
+ * Bun's SQL client cannot: it stringifies the array, so `= ANY($N::uuid[])` reaches the server as
+ * `a,b` and fails with `malformed array literal` (oven-sh/bun#18775). `ARRAY[$2,$3]` is valid
+ * everywhere a single array parameter was, and every element stays a bind parameter, so no value
+ * is ever escaped into SQL text.
+ */
+export declare function expandArrayParams(text: string, values?: readonly unknown[]): {
+    text: string;
+    values: unknown[];
+};
 //# sourceMappingURL=placeholders.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"placeholders.d.ts","sourceRoot":"","sources":["../../src/adapters/placeholders.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG;IAC7E,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,SAAS,EAAE,OAAO,EAAE,CAAA;CACrB,CAcA"}
+{"version":3,"file":"placeholders.d.ts","sourceRoot":"","sources":["../../src/adapters/placeholders.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG;IAC7E,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,SAAS,EAAE,OAAO,EAAE,CAAA;CACrB,CAcA;AAMD,eAAO,MAAM,UAAU,QAA6B,CAAA;AAEpD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG;IAC7E,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,EAAE,CAAA;CAClB,CAgBA"}

package/dist/adapters/placeholders.js

@@ -22,3 +22,31 @@ export function parsePlaceholders(text, values) {
     parts.push(text.slice(lastIndex));
     return { parts, reordered };
 }
+// A parameter cast to an array type, as in `$2::uuid[]`. pg-boss binds job ids and queue names
+// this way, and the cast is what tells an adapter the value is a postgres array rather than a
+// JSON one - a JS array bound to a json column is a JSON array, and rewriting that would change
+// what gets stored.
+export const ARRAY_CAST = /^::[a-z_][a-z0-9_]*\[\]/i;
+/**
+ * Rewrites `$N` placeholders into a fresh sequential list, expanding any array-cast parameter
+ * into an inline `ARRAY[...]` constructor of scalar parameters.
+ *
+ * Postgres wants an array bound whole, and node-postgres, postgres-js and PGlite all encode one.
+ * Bun's SQL client cannot: it stringifies the array, so `= ANY($N::uuid[])` reaches the server as
+ * `a,b` and fails with `malformed array literal` (oven-sh/bun#18775). `ARRAY[$2,$3]` is valid
+ * everywhere a single array parameter was, and every element stays a bind parameter, so no value
+ * is ever escaped into SQL text.
+ */
+export function expandArrayParams(text, values) {
+    const { parts, reordered } = parsePlaceholders(text, values);
+    const expanded = [];
+    let rewritten = parts[0];
+    for (let i = 0; i < reordered.length; i++) {
+        const value = reordered[i];
+        rewritten += Array.isArray(value) && ARRAY_CAST.test(parts[i + 1])
+            ? `ARRAY[${value.map(element => `$${expanded.push(element)}`).join(',')}]`
+            : `$${expanded.push(value)}`;
+        rewritten += parts[i + 1];
+    }
+    return { text: rewritten, values: expanded };
+}

package/dist/attorney.d.ts

@@ -4,6 +4,7 @@ declare const POLICY: {
     MIN_POLLING_INTERVAL_MS: number;
     MAX_RETENTION_DAYS: number;
 };
+declare const COMPATIBILITY_FLAGS: readonly ["noSkipLocked", "noMultiMutationCte", "noTablePartitioning", "noDeferrableConstraints", "noAdvisoryLocks", "noCoveringIndexes", "noAddColumnBackfill", "noListenNotify", "noIndexProgressView", "noReindex", "noMonitorVacuum"];
 declare function validateQueueArgs(config?: any): void;
 declare function pinZonelessDateTime(value: string): string;
 declare function checkSendArgs(args: any): types.Request;
@@ -21,5 +22,5 @@ declare function getConfig(value: string | types.ConstructorOptions): types.Reso
 declare function assertPostgresObjectName(name: string): void;
 declare function assertQueueName(name: string): void;
 declare function assertKey(key: string): void;
-export { assertKey, assertPostgresObjectName, assertQueueName, checkFetchArgs, checkSendArgs, checkUpdateArgs, checkWorkArgs, getConfig, pinZonelessDateTime, POLICY, validateFlowJobs, validateGroupConfig, validateQueueArgs };
+export { assertKey, COMPATIBILITY_FLAGS, assertPostgresObjectName, assertQueueName, checkFetchArgs, checkSendArgs, checkUpdateArgs, checkWorkArgs, getConfig, pinZonelessDateTime, POLICY, validateFlowJobs, validateGroupConfig, validateQueueArgs };
 //# sourceMappingURL=attorney.d.ts.map

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;AAkFD,iBAAS,iBAAiB,CAAE,MAAM,GAAE,GAAQ,QAc3C;AAgBD,iBAAS,mBAAmB,CAAE,KAAK,EAAE,MAAM,UAE1C;AAED,iBAAS,aAAa,CAAE,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,OAAO,CAgDhD;AAOD,iBAAS,eAAe,CAAE,IAAI,EAAE,GAAG,EAAE,EAAE,MAAc,EAAE;;CAAK,GAAG,KAAK,CAAC,OAAO,CA4D3E;AAED,iBAAS,mBAAmB,CAAE,MAAM,EAAE,GAAG,QAOxC;AAED,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,CAyB9F;AA4FD,iBAAS,wBAAwB,CAAE,IAAI,EAAE,MAAM,QAiC9C;AAED,iBAAS,eAAe,CAAE,IAAI,EAAE,MAAM,QAIrC;AAED,iBAAS,SAAS,CAAE,GAAG,EAAE,MAAM,QAI9B;AA+LD,OAAO,EACL,SAAS,EACT,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,aAAa,EACb,SAAS,EACT,mBAAmB,EACnB,MAAM,EACN,gBAAgB,EAChB,mBAAmB,EACnB,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;AAKD,QAAA,MAAM,mBAAmB,2OAYf,CAAA;AAsEV,iBAAS,iBAAiB,CAAE,MAAM,GAAE,GAAQ,QAc3C;AAgBD,iBAAS,mBAAmB,CAAE,KAAK,EAAE,MAAM,UAE1C;AAED,iBAAS,aAAa,CAAE,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,OAAO,CAgDhD;AAOD,iBAAS,eAAe,CAAE,IAAI,EAAE,GAAG,EAAE,EAAE,MAAc,EAAE;;CAAK,GAAG,KAAK,CAAC,OAAO,CA4D3E;AAED,iBAAS,mBAAmB,CAAE,MAAM,EAAE,GAAG,QAOxC;AAED,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,CAyB9F;AA4FD,iBAAS,wBAAwB,CAAE,IAAI,EAAE,MAAM,QAiC9C;AAED,iBAAS,eAAe,CAAE,IAAI,EAAE,MAAM,QAIrC;AAED,iBAAS,SAAS,CAAE,GAAG,EAAE,MAAM,QAI9B;AA+LD,OAAO,EACL,SAAS,EACT,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,aAAa,EACb,SAAS,EACT,mBAAmB,EACnB,MAAM,EACN,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EAClB,CAAA"}

package/dist/attorney.js

@@ -15,6 +15,7 @@ const COMPATIBILITY_FLAGS = [
     'noDeferrableConstraints',
     'noAdvisoryLocks',
     'noCoveringIndexes',
+    'noAddColumnBackfill',
     'noListenNotify',
     'noIndexProgressView',
     'noReindex',
@@ -32,6 +33,10 @@ const BACKEND_PROFILES = {
             noDeferrableConstraints: true,
             noAdvisoryLocks: true,
             noCoveringIndexes: true,
+            // ADD COLUMN runs as a schema-change job, so a transaction cannot write the column it just
+            // added: the UPDATE fails with "column is being backfilled". A migration that seeds a new
+            // column leaves the seeding statement out here.
+            noAddColumnBackfill: true,
             noListenNotify: true,
             // Online DDL runs as a schema-change job, not the PG CONCURRENTLY path, and
             // pg_stat_progress_create_index isn't available — so BAM can't use liveness-based reclaim.
@@ -617,4 +622,4 @@ function applyFlowConfig(config) {
     assert(!('flowIntervalSeconds' in config) || config.flowIntervalSeconds >= minInterval, `configuration assert: flowIntervalSeconds must be at least ${minInterval} seconds`);
     config.flowIntervalSeconds = config.flowIntervalSeconds || 5;
 }
-export { assertKey, assertPostgresObjectName, assertQueueName, checkFetchArgs, checkSendArgs, checkUpdateArgs, checkWorkArgs, getConfig, pinZonelessDateTime, POLICY, validateFlowJobs, validateGroupConfig, validateQueueArgs };
+export { assertKey, COMPATIBILITY_FLAGS, assertPostgresObjectName, assertQueueName, checkFetchArgs, checkSendArgs, checkUpdateArgs, checkWorkArgs, getConfig, pinZonelessDateTime, POLICY, validateFlowJobs, validateGroupConfig, validateQueueArgs };

package/dist/cli.js

@@ -6,6 +6,7 @@ import Db from "./db.js";
 import * as plans from "./plans.js";
 import Contractor from "./contractor.js";
 import * as migrationStore from "./migrationStore.js";
+import * as attorney from "./attorney.js";
 import packageJson from '../package.json' with { type: 'json' };
 const schemaVersion = packageJson.pgboss.schema;
 function printHelp() {
@@ -34,6 +35,8 @@ Options:
   --password, -p <pass>   Database password
   --connection-string     Full connection string (overrides other connection options)
   --ssl                   Enable SSL connection
+  --backend <profile>     Database backend: postgres (default), cockroachdb, yugabytedb, citus.
+                          Non-postgres backends need this to emit schema they accept.
   --dry-run               Output SQL without executing (for plans and reindex commands)
   --force                 Rebuild every job index, not just the bloated ones (reindex)
 
@@ -45,6 +48,7 @@ Environment Variables:
   PGBOSS_USER             Database user
   PGBOSS_PASSWORD         Database password
   PGBOSS_SCHEMA           Schema name (default: pgboss)
+  PGBOSS_BACKEND          Database backend profile (default: postgres)
 
 Config File (pgboss.json):
   {
@@ -54,7 +58,8 @@ Config File (pgboss.json):
     "user": "postgres",
     "password": "secret",
     "schema": "pgboss",
-    "ssl": false
+    "ssl": false,
+    "backend": "postgres"
   }
 
 Examples:
@@ -62,6 +67,7 @@ Examples:
   pg-boss migrate --schema my_schema
   pg-boss create --connection-string postgres://user:pass@localhost/db
   pg-boss plans migrate --dry-run
+  pg-boss migrate --backend cockroachdb --connection-string postgres://root@localhost:26257/db
   pg-boss version
   PGBOSS_DATABASE_URL=postgres://localhost/mydb pg-boss migrate
 `);
@@ -90,6 +96,13 @@ function loadConfigFile(configPath) {
     }
     return {};
 }
+// Resolves the connection AND the backend compatibility flags, because every command that writes
+// schema needs both. Without the flags a CockroachDB target is handed stock-PostgreSQL DDL - table
+// partitioning, advisory locks, covering indexes, a backfill of a column added in the same
+// transaction - and the command fails partway through a migration rather than up front. The flags
+// are derived from --backend / PGBOSS_BACKEND / the config file by the same attorney.getConfig() the
+// library constructor uses, so the CLI and a running boss cannot disagree about what a backend
+// supports.
 function getConnectionConfig(args) {
     const fileConfig = loadConfigFile(args.config);
     const config = {
@@ -110,7 +123,28 @@ function getConnectionConfig(args) {
         console.error('Run "pg-boss --help" for more information.');
         process.exit(1);
     }
-    return config;
+    return resolveBackendConfig(config, args, fileConfig);
+}
+// Runs a config through the library's own resolver so the compatibility flags come from one place.
+// Split out of getConnectionConfig because `plans` has to answer offline, where there is a backend
+// to honour but no connection to read.
+function resolveBackendConfig(config, args, fileConfig) {
+    const backend = args.backend || process.env.PGBOSS_BACKEND || fileConfig.backend;
+    if (backend) {
+        // pglite is in-process and has no connection string, so it can only be driven from library code.
+        if (backend === 'pglite') {
+            console.error('Error: the pglite backend is in-process and cannot be used from the CLI.');
+            process.exit(1);
+        }
+        config.backend = backend;
+    }
+    try {
+        return attorney.getConfig(config);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
 }
 function parseCliArgs() {
     const { values, positionals } = parseArgs({
@@ -125,6 +159,7 @@ function parseCliArgs() {
             password: { type: 'string', short: 'p' },
             'connection-string': { type: 'string' },
             ssl: { type: 'boolean' },
+            backend: { type: 'string' },
             'dry-run': { type: 'boolean' },
             force: { type: 'boolean' }
         },
@@ -141,6 +176,7 @@ function parseCliArgs() {
         password: values.password,
         connectionString: values['connection-string'],
         ssl: values.ssl,
+        backend: values.backend,
         dryRun: values['dry-run'],
         force: values.force,
         command: positionals[0],
@@ -214,7 +250,7 @@ async function cmdCreate(args) {
     const config = getConnectionConfig(args);
     const schema = config.schema || plans.DEFAULT_SCHEMA;
     if (args.dryRun) {
-        const sql = plans.create(schema, schemaVersion, { createSchema: true });
+        const sql = plans.create(schema, schemaVersion, { ...config, createSchema: true });
         console.log('-- SQL to create pg-boss schema:');
         console.log(sql);
         return;
@@ -227,7 +263,7 @@ async function cmdCreate(args) {
             return;
         }
         console.log(`Creating pg-boss schema "${schema}"...`);
-        const sql = plans.create(schema, schemaVersion, { createSchema: true });
+        const sql = plans.create(schema, schemaVersion, { ...config, createSchema: true });
         await db.executeSql(sql);
         console.log(`Successfully created pg-boss schema "${schema}" at version ${schemaVersion}`);
     }
@@ -265,7 +301,7 @@ async function cmdMigrate(args) {
         // Offline (or not yet installed) we can't know it, so fall back to the oldest supported starting
         // version — the full chain — instead of a bogus "from 0" that fails on non-idempotent steps.
         const fromVersion = version ?? migrationStore.getMinVersion(schema);
-        const sql = migrationStore.migrate(schema, fromVersion, undefined, undefined, { inlineAsync: true, partitionTables });
+        const sql = migrationStore.migrate(schema, fromVersion, migrationStore.getAllForConfig(config), config.noAdvisoryLocks, { inlineAsync: true, partitionTables });
         console.log(`-- SQL to migrate pg-boss from version ${fromVersion} to ${schemaVersion}:`);
         console.log(sql);
         return;
@@ -275,7 +311,7 @@ async function cmdMigrate(args) {
         const version = await getSchemaVersion(db, schema);
         if (version === null) {
             console.log(`pg-boss is not installed. Creating schema "${schema}"...`);
-            const sql = plans.create(schema, schemaVersion, { createSchema: true });
+            const sql = plans.create(schema, schemaVersion, { ...config, createSchema: true });
             await db.executeSql(sql);
             console.log(`Successfully created pg-boss schema "${schema}" at version ${schemaVersion}`);
             return;
@@ -288,7 +324,7 @@ async function cmdMigrate(args) {
         // 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 });
+        const { sql, concurrent } = migrationStore.migrateCommands(schema, version, migrationStore.getAllForConfig(config), config.noAdvisoryLocks, { 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) {
@@ -315,13 +351,13 @@ async function cmdRollback(args) {
             return;
         }
         if (args.dryRun) {
-            const sql = migrationStore.rollback(schema, version);
+            const sql = migrationStore.rollback(schema, version, migrationStore.getAllForConfig(config), config.noAdvisoryLocks);
             console.log(`-- SQL to rollback pg-boss from version ${version} to ${version - 1}:`);
             console.log(sql);
             return;
         }
         console.log(`Rolling back pg-boss schema "${schema}" from version ${version} to ${version - 1}...`);
-        const sql = migrationStore.rollback(schema, version);
+        const sql = migrationStore.rollback(schema, version, migrationStore.getAllForConfig(config), config.noAdvisoryLocks);
         await db.executeSql(sql);
         console.log(`Successfully rolled back pg-boss schema "${schema}" to version ${version - 1}`);
     }
@@ -489,6 +525,14 @@ async function cmdReindex(args) {
             process.exitCode = 1;
             return;
         }
+        // A declared backend answers this without a round trip: REINDEX is rejected outright on
+        // CockroachDB and unimplemented on YugabyteDB, and neither can measure bloat in the first place.
+        if (config.noReindex) {
+            console.error(`Reindexing is not supported on the ${config.backend} backend.`);
+            console.error('Index maintenance there is handled by the storage engine, and the bloat check cannot run: pg_class.relpages and pg_relation_size() are unavailable or always zero.');
+            process.exitCode = 1;
+            return;
+        }
         const sql = args.force ? plans.getJobIndexes(schema) : plans.getBloatedIndexes(schema);
         let rows;
         try {
@@ -497,9 +541,8 @@ async function cmdReindex(args) {
         catch (err) {
             // The check reads pg_class.relpages and pg_relation_size(). CockroachDB has neither (it
             // rejects `reltuples / relpages` as an unsupported binary operator) and YugabyteDB reports
-            // zeroes for every relation. The CLI takes a connection string, not a backend profile, so
-            // there is nothing to gate on ahead of time — say what happened instead of surfacing a raw
-            // catalog error.
+            // zeroes for every relation. --backend catches those up front (above); this stays for a target
+            // that was not declared — say what happened instead of surfacing a raw catalog error.
             console.error(`Could not read index statistics from schema "${schema}": ${err.message}`);
             console.error('The bloat check reads pg_class.relpages and pg_relation_size(), which CockroachDB and YugabyteDB do not provide.');
             process.exitCode = 1;
@@ -569,11 +612,14 @@ async function cmdPlans(args) {
     const fileConfig = loadConfigFile(args.config);
     const schema = args.schema || process.env.PGBOSS_SCHEMA || fileConfig.schema || plans.DEFAULT_SCHEMA;
     const subCommand = args.subCommand || 'migrate';
+    // A connection is optional here, but the backend is not: printed SQL is meant to be run, so it has
+    // to be the SQL that backend accepts.
+    const config = resolveBackendConfig({ schema }, args, fileConfig);
     switch (subCommand) {
         case 'create':
         case 'construct':
             console.log('-- SQL to create pg-boss schema:');
-            console.log(plans.create(schema, schemaVersion, { createSchema: true }));
+            console.log(plans.create(schema, schemaVersion, { ...config, createSchema: true }));
             break;
         case 'migrate': {
             // Inline the async index builds (no BAM worker runs an exported script). A connection
@@ -600,12 +646,12 @@ async function cmdPlans(args) {
                 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 }));
+            console.log(migrationStore.migrate(schema, 0, migrationStore.getAllForConfig(config), config.noAdvisoryLocks, { 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));
+            console.log(migrationStore.rollback(schema, schemaVersion, migrationStore.getAllForConfig(config), config.noAdvisoryLocks));
             break;
         default:
             console.error(`Unknown plans subcommand: ${subCommand}`);

package/dist/contractor.d.ts

@@ -1,12 +1,8 @@
 import type * as types from './types.ts';
 declare class Contractor {
-    static constructionPlans(schema?: string, options?: {
-        createSchema: boolean;
-    }): string;
-    static migrationPlans(schema?: string, version?: number, options?: {
-        partitionTables?: types.MigrationPartition[];
-    }): string;
-    static rollbackPlans(schema?: string, version?: number): string;
+    static constructionPlans(schema?: string, options?: types.ConstructionPlanOptions): string;
+    static migrationPlans(schema?: string, version?: number, options?: types.MigrationPlanOptions): string;
+    static rollbackPlans(schema?: string, version?: number, options?: types.PlanOptions): string;
     private config;
     private db;
     private migrations;

package/dist/contractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contractor.d.ts","sourceRoot":"","sources":["../src/contractor.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAOxC,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,KAAK,CAAC,kBAAkB,EAAE,CAAA;KAAO;IAOjJ,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;YAsBG,yBAAyB;IAkCjC,WAAW,IAAK,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC;IA4GhD,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":"AAMA,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAkBxC,cAAM,UAAU;IACd,MAAM,CAAC,iBAAiB,CAAE,MAAM,SAAuB,EAAE,OAAO,GAAE,KAAK,CAAC,uBAA4B;IAapG,MAAM,CAAC,cAAc,CAAE,MAAM,SAAuB,EAAE,OAAO,SAAoB,EAAE,OAAO,GAAE,KAAK,CAAC,oBAAyB;IAS3H,MAAM,CAAC,aAAa,CAAE,MAAM,SAAuB,EAAE,OAAO,SAAgB,EAAE,OAAO,GAAE,KAAK,CAAC,WAAgB;IAM7G,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;IAgBpE,aAAa;IAKb,WAAW;IAKX,KAAK;YAsBG,yBAAyB;IAkCjC,WAAW,IAAK,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC;IA4GhD,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"}