pg-boss 12.25.1 → 12.26.1

package/README.md

@@ -1,8 +1,9 @@
 Queueing jobs in Postgres from Node.js like a boss.
 
-[![NPM](https://nodei.co/npm/pg-boss.svg?style=shields&color=blue)](https://nodei.co/npm/pg-boss/)
 [![Build](https://github.com/timgit/pg-boss/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/timgit/pg-boss/actions/workflows/ci.yml)
-[![Coverage Status](https://coveralls.io/repos/github/timgit/pg-boss/badge.svg?branch=master)](https://coveralls.io/github/timgit/pg-boss?branch=master)
+[![Coverage](https://img.shields.io/coverallsCoverage/github/timgit/pg-boss)](https://coveralls.io/github/timgit/pg-boss?branch=master)
+[![NPM](https://img.shields.io/npm/v/pg-boss)](https://www.npmjs.com/package/pg-boss)
+
 
 ```js
 async function readme() {

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

@@ -1 +1 @@
-{"version":3,"file":"knex.d.ts","sourceRoot":"","sources":["../../src/adapters/knex.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAI5C,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,EAAE,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,GAAG,EAAE,CAAA;KAAE,EAAE,CAAC,CAAA;CACrG;AAED,wBAAgB,QAAQ,CAAE,GAAG,EAAE,mBAAmB,GAAG,SAAS,CAW7D"}
+{"version":3,"file":"knex.d.ts","sourceRoot":"","sources":["../../src/adapters/knex.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAI5C,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,EAAE,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,GAAG,EAAE,CAAA;KAAE,EAAE,CAAC,CAAA;CACrG;AAED,wBAAgB,QAAQ,CAAE,GAAG,EAAE,mBAAmB,GAAG,SAAS,CAgB7D"}

package/dist/adapters/knex.js

@@ -7,7 +7,12 @@ export function fromKnex(trx) {
             // so each textual occurrence (including reuse of the same $N) must be
             // mapped to its own ? with the value duplicated in textual order.
             const { parts, reordered } = parsePlaceholders(text, values);
-            const knexSql = parts.join('?');
+            // Several pg-boss queries (e.g. updateJob) also contain literal jsonb `?` key-exists
+            // operators. knex.raw() scans the whole string for `?` to fill bindings, so those
+            // literal occurrences must be escaped as `\?` (knex's own literal-? syntax) before
+            // joining in the real placeholders — otherwise knex miscounts bindings and throws
+            // "Undefined binding(s) detected" on any query that mixes both.
+            const knexSql = parts.map(part => part.replace(/\?/g, '\\?')).join('?');
             return unwrapSQLResult(await trx.raw(knexSql, reordered));
         }
     };

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;AAyDD,iBAAS,iBAAiB,CAAE,MAAM,GAAE,GAAQ,QAc3C;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,CAuD3E;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,CAwB9F;AAsDD,iBAAS,wBAAwB,CAAE,IAAI,EAAE,MAAM,QAK9C;AAED,iBAAS,eAAe,CAAE,IAAI,EAAE,MAAM,QAIrC;AAED,iBAAS,SAAS,CAAE,GAAG,EAAE,MAAM,QAI9B;AAoJD,OAAO,EACL,SAAS,EACT,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,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;AAqED,iBAAS,iBAAiB,CAAE,MAAM,GAAE,GAAQ,QAc3C;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;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,CAwB9F;AA4DD,iBAAS,wBAAwB,CAAE,IAAI,EAAE,MAAM,QAK9C;AAED,iBAAS,eAAe,CAAE,IAAI,EAAE,MAAM,QAIrC;AAED,iBAAS,SAAS,CAAE,GAAG,EAAE,MAAM,QAI9B;AAoJD,OAAO,EACL,SAAS,EACT,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,aAAa,EACb,SAAS,EACT,MAAM,EACN,gBAAgB,EAChB,iBAAiB,EAClB,CAAA"}

package/dist/attorney.js

@@ -15,7 +15,8 @@ const COMPATIBILITY_FLAGS = [
     'noDeferrableConstraints',
     'noAdvisoryLocks',
     'noCoveringIndexes',
-    'noListenNotify'
+    'noListenNotify',
+    'noIndexProgressView'
 ];
 // The single source of truth for backend presets, mirrored by test/testHelper.ts.
 const BACKEND_PROFILES = {
@@ -29,16 +30,27 @@ const BACKEND_PROFILES = {
             noDeferrableConstraints: true,
             noAdvisoryLocks: true,
             noCoveringIndexes: true,
-            noListenNotify: 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.
+            noIndexProgressView: true
         }
     },
     yugabytedb: {
         kind: 'distributed',
         flags: {
             noAdvisoryLocks: true,
-            noTablePartitioning: true
+            noTablePartitioning: true,
+            // Index builds are a distributed backfill that pg_stat_progress_create_index doesn't reflect,
+            // so liveness would misread an in-flight build as dead. BAM falls back to the timeout instead.
+            noIndexProgressView: true
         }
     },
+    // No noIndexProgressView: pg-boss keeps its tables coordinator-local (it never calls
+    // create_distributed_table), so CREATE INDEX CONCURRENTLY runs against ordinary local Postgres tables
+    // on the coordinator, where pg_stat_progress_create_index is accurate and liveness-based reclaim is
+    // valid. This holds ONLY while the tables stay coordinator-local — if they are ever distributed, the
+    // coordinator's progress view would misread in-flight worker builds as dead and BAM could double-build.
     citus: { kind: 'distributed', flags: {} },
     pglite: { kind: 'embedded', flags: {} }
 };
@@ -127,12 +139,17 @@ function checkUpdateArgs(args, { upsert = false } = {}) {
     assert(match === undefined || JOB_MATCH_STRATEGIES.includes(match), `match must be one of: ${JOB_MATCH_STRATEGIES.join(', ')}`);
     assert(!('priority' in options) || (Number.isInteger(options.priority)), 'priority must be an integer');
     if ('startAfter' in options) {
-        options.startAfter = (options.startAfter instanceof Date && typeof options.startAfter.toISOString === 'function')
-            ? options.startAfter.toISOString()
-            : (+options.startAfter > 0)
-                ? '' + options.startAfter
-                : (typeof options.startAfter === 'string')
-                    ? options.startAfter
+        // Unlike send(), update() must honor a numeric startAfter of 0 (or negative) — the caller is
+        // explicitly pulling a deferred job forward to now. The send-style `+startAfter > 0` guard
+        // coerced 0 to undefined, which JSON.stringify then dropped, silently making the edit a no-op.
+        // Any finite number is passed through as a seconds interval ('0' -> now()); a string is kept.
+        const startAfter = options.startAfter;
+        options.startAfter = (startAfter instanceof Date && typeof startAfter.toISOString === 'function')
+            ? startAfter.toISOString()
+            : (typeof startAfter === 'number' && Number.isFinite(startAfter))
+                ? '' + startAfter
+                : (typeof startAfter === 'string')
+                    ? startAfter
                     : undefined;
     }
     validateRetryConfig(options);
@@ -377,6 +394,11 @@ function resolveBackend(config) {
     if (config.__test__noAdvisoryLocks) {
         config.noAdvisoryLocks = true;
     }
+    // Test hook: exercise the no-liveness BAM reclaim path (timeout-only, no CONCURRENTLY healing)
+    // used by CockroachDB/YugabyteDB, on a plain Postgres instance.
+    if (config.__test__noIndexProgressView) {
+        config.noIndexProgressView = true;
+    }
 }
 function assertPostgresObjectName(name) {
     assert(typeof name === 'string', 'Name must be a string');

package/dist/bam.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bam.d.ts","sourceRoot":"","sources":["../src/bam.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AAGtC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAOnC,cAAM,GAAI,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;;IAOzD,MAAM;;;MAAS;gBAGb,EAAE,EAAE,KAAK,CAAC,SAAS,EACnB,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAU1C,IAAI,OAAO,IAAK,OAAO,CAEtB;IAEK,KAAK;IAWL,IAAI;CAuGX;AAED,eAAe,GAAG,CAAA"}
+{"version":3,"file":"bam.d.ts","sourceRoot":"","sources":["../src/bam.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AAGtC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAOnC,cAAM,GAAI,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;;IAOzD,MAAM;;;MAAS;gBAGb,EAAE,EAAE,KAAK,CAAC,SAAS,EACnB,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAU1C,IAAI,OAAO,IAAK,OAAO,CAEtB;IAEK,KAAK;IAWL,IAAI;CA8HX;AAED,eAAe,GAAG,CAAA"}

package/dist/bam.js

@@ -80,6 +80,28 @@ class Bam extends EventEmitter {
             table: entry.table
         });
         try {
+            // A re-attempted command (a stale in_progress reclaim, or a retry of a prior 'failed' — including
+            // failed rows left by older releases) may have an INVALID index behind it from an interrupted or
+            // failed CREATE INDEX CONCURRENTLY. Drop it first (best-effort, IF EXISTS) so the re-run rebuilds
+            // cleanly instead of the command's own IF NOT EXISTS skipping over a broken index forever. Only on
+            // the liveness path — CockroachDB/YugabyteDB roll interrupted builds back, so there's nothing to
+            // heal and DROP ... CONCURRENTLY isn't their model.
+            if (entry.reattempt && !this.#config.noIndexProgressView) {
+                const dropSql = plans.bamHealDrop(this.#config.schema, entry.command);
+                if (dropSql) {
+                    // Only heal an index the previous attempt left INVALID. A re-attempt can also fire for a
+                    // build that actually SUCCEEDED but whose row was never marked completed (a graceful stop
+                    // landed between the CREATE and markCompleted) — that index is VALID and in use, so dropping
+                    // it would tear down a live production index for the whole rebuild window. Probe indisvalid
+                    // first; skip the drop for a valid (or absent) index and let the command's IF NOT EXISTS re-run
+                    // no-op it and mark the row done.
+                    const probeSql = plans.bamHealProbe(this.#config.schema, entry.command);
+                    const { rows } = await this.#db.executeSql(probeSql);
+                    if (rows[0]?.invalid) {
+                        await this.#db.executeSql(dropSql);
+                    }
+                }
+            }
             await this.#db.executeSql(entry.command);
             if (this.#stopped)
                 return;
@@ -108,7 +130,7 @@ class Bam extends EventEmitter {
         }
     }
     async #getNextCommand() {
-        const sql = plans.getNextBamCommand(this.#config.schema);
+        const sql = plans.getNextBamCommand(this.#config.schema, { useLiveness: !this.#config.noIndexProgressView });
         const { rows } = await this.#db.executeSql(sql);
         return rows[0] || null;
     }

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;AAmBnC,cAAM,IAAK,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;;IAW1D,MAAM;;;MAAS;gBAGb,EAAE,EAAE,KAAK,CAAC,SAAS,EACnB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAa1C,IAAI,WAAW,IAAK,OAAO,CAE1B;IAEK,KAAK;IAWL,IAAI;IA8FJ,SAAS,CAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE;CAwItD;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;AAmBnC,cAAM,IAAK,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;;IAW1D,MAAM;;;MAAS;gBAGb,EAAE,EAAE,KAAK,CAAC,SAAS,EACnB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAa1C,IAAI,WAAW,IAAK,OAAO,CAE1B;IAEK,KAAK;IAWL,IAAI;IA8FJ,SAAS,CAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE;CAgItD;AAED,eAAe,IAAI,CAAA"}

package/dist/boss.js

@@ -146,7 +146,6 @@ class Boss extends EventEmitter {
             acc[table].queues.push(q);
             return acc;
         }, {});
-        const heartbeatQueueNames = new Set(queues.filter(q => q.heartbeatSeconds != null).map(q => q.name));
         for (const queueGroup of Object.values(queueGroups)) {
             if (this.#stopping)
                 return;
@@ -156,7 +155,7 @@ class Boss extends EventEmitter {
                 if (this.#stopping)
                     return;
                 const chunk = names.splice(0, 100);
-                await this.#monitor(table, chunk, heartbeatQueueNames);
+                await this.#monitor(table, chunk);
                 await this.#maintain(table, chunk);
             }
         }
@@ -165,7 +164,7 @@ class Boss extends EventEmitter {
         await this.#maintainWarnings();
         await this.#maintainQueueStats();
     }
-    async #monitor(table, names, heartbeatQueueNames) {
+    async #monitor(table, names) {
         if (this.#stopping)
             return;
         const command = plans.trySetQueueMonitorTime(this.#config.schema, names, this.#config.monitorIntervalSeconds);
@@ -200,15 +199,12 @@ class Boss extends EventEmitter {
             }
             if (this.#stopping)
                 return;
-            const heartbeatQueues = queues.filter(q => heartbeatQueueNames.has(q));
-            if (heartbeatQueues.length) {
-                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);
-                }
+            if (this.#config.noMultiMutationCte) {
+                await this.#manager.failJobsByHeartbeatDistributed(table, queues);
+            }
+            else {
+                const heartbeatSql = plans.failJobsByHeartbeat(this.#config.schema, table, queues, this.#config.noAdvisoryLocks);
+                await this.#executeQuery(heartbeatSql);
             }
         }
     }

package/dist/cli.js

@@ -4,6 +4,7 @@ import { readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import Db from "./db.js";
 import * as plans from "./plans.js";
+import Contractor from "./contractor.js";
 import * as migrationStore from "./migrationStore.js";
 import packageJson from '../package.json' with { type: 'json' };
 const schemaVersion = packageJson.pgboss.schema;
@@ -17,6 +18,7 @@ Commands:
   migrate     Run pending migrations (creates schema if not exists)
   create      Create the pg-boss schema (initial installation)
   version     Show current schema version
+  doctor      Check for schema/index drift against the expected shape
   plans       Output SQL plans without executing
   rollback    Rollback the last migration
 
@@ -234,12 +236,15 @@ async function cmdMigrate(args) {
     const schema = config.schema || plans.DEFAULT_SCHEMA;
     if (args.dryRun) {
         // 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.
+        // (best effort) to read the DB's actual version and enumerate partitioned tables; fall back to
+        // job_common only offline.
         let partitionTables = [];
+        let version = null;
         try {
             const db = await createDb(config);
             try {
                 partitionTables = await getPartitionTables(db, schema);
+                version = await getSchemaVersion(db, schema);
             }
             finally {
                 await db.close();
@@ -248,8 +253,16 @@ async function cmdMigrate(args) {
         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:');
+        if (version !== null && version >= schemaVersion) {
+            console.log(`-- pg-boss schema "${schema}" is already at version ${version} (latest: ${schemaVersion}); nothing to migrate.`);
+            return;
+        }
+        // Render from the DB's actual version so the printed SQL is exactly what `migrate` would run.
+        // 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 });
+        console.log(`-- SQL to migrate pg-boss from version ${fromVersion} to ${schemaVersion}:`);
         console.log(sql);
         return;
     }
@@ -312,6 +325,134 @@ async function cmdRollback(args) {
         await db.close();
     }
 }
+async function cmdDoctor(args) {
+    const config = getConnectionConfig(args);
+    const schema = config.schema || plans.DEFAULT_SCHEMA;
+    const db = await createDb(config);
+    try {
+        const version = await getSchemaVersion(db, schema);
+        if (version === null) {
+            console.log(`pg-boss is not installed in schema "${schema}"`);
+            process.exitCode = 1;
+            return;
+        }
+        console.log(`Schema "${schema}" version ${version} (latest: ${schemaVersion})`);
+        if (version < schemaVersion) {
+            console.log(`⚠ Migrations pending: ${schemaVersion - version} — run "pg-boss migrate" before trusting drift results`);
+        }
+        // Reuse the same drift scan the boss.detectSchemaDrift() API runs, rather than duplicating the
+        // catalog queries + computeSchemaDrift wiring here (the two copies had already drifted apart and
+        // carried divergent best-effort/backend-gating bugs). Contractor.detectDrift handles the
+        // partitioned probe, best-effort catalog fallbacks, and backend-specific gating in one place.
+        const contractor = new Contractor(db, { ...config, schema });
+        const report = await contractor.detectDrift();
+        if (report.building.length) {
+            console.log(`\nBuilding (async index build in progress — not yet drift) (${report.building.length}):`);
+            for (const i of report.building)
+                console.log(`  ${i.table}.${i.name}`);
+        }
+        // Extra indexes are informational (a stale pg-boss index or a user-added one) — a warning, not
+        // drift. Printed regardless of overall status; it never changes the exit code.
+        if (report.extraIndexes.length) {
+            console.log(`\n⚠ EXTRA INDEXES (present on a managed table but not expected — harmless) (${report.extraIndexes.length}):`);
+            for (const i of report.extraIndexes)
+                console.log(`  ${i.table}.${i.name}`);
+        }
+        if (report.ok) {
+            console.log('\n✓ No drift detected');
+            return;
+        }
+        if (report.missingTables.length) {
+            console.log(`\nMISSING TABLES (expected but absent) (${report.missingTables.length}):`);
+            for (const t of report.missingTables)
+                console.log(`  ${t}`);
+        }
+        // Each drifted index is printed with the expected (correct) definition and, where one exists, the
+        // actual definition beneath it, for a direct side-by-side comparison and copy-paste remediation.
+        if (report.missing.length) {
+            console.log(`\nMISSING (expected but absent) (${report.missing.length}):`);
+            for (const i of report.missing) {
+                console.log(`  ${i.table}.${i.name}`);
+                if (i.definition)
+                    console.log(`    expected: ${i.definition}`);
+            }
+        }
+        if (report.invalid.length) {
+            // The definition is correct — the index is just invalid (interrupted build) — so show the DDL to
+            // drop and rebuild it, not an expected-vs-actual comparison (they would be identical).
+            console.log(`\nINVALID (present but marked invalid — drop and rebuild) (${report.invalid.length}):`);
+            for (const i of report.invalid) {
+                console.log(`  ${i.table}.${i.name}`);
+                if (i.definition)
+                    console.log(`    rebuild: ${i.definition}`);
+            }
+        }
+        if (report.mismatched.length) {
+            console.log(`\nMISMATCHED (definition differs) (${report.mismatched.length}):`);
+            for (const m of report.mismatched) {
+                console.log(`  ${m.table}.${m.name} [${m.differs.join(', ')}]`);
+                if (m.definition)
+                    console.log(`    expected: ${m.definition}`);
+                console.log(`    actual:   ${m.actualDefinition}`);
+            }
+        }
+        if (report.missingFunctions.length) {
+            console.log(`\nMISSING FUNCTIONS (expected but absent) (${report.missingFunctions.length}):`);
+            for (const f of report.missingFunctions) {
+                console.log(`  ${f.name}`);
+                console.log(`    expected: ${f.definition}`);
+            }
+        }
+        if (report.mismatchedFunctions.length) {
+            console.log(`\nMISMATCHED FUNCTIONS (body differs) (${report.mismatchedFunctions.length}):`);
+            for (const f of report.mismatchedFunctions) {
+                console.log(`  ${f.name}`);
+                console.log(`    expected: ${f.definition}`);
+                console.log(`    actual:   ${f.actualDefinition}`);
+            }
+        }
+        if (report.columnDrift.length) {
+            console.log(`\nCOLUMN DRIFT (missing/unexpected columns, or default/type/nullability drift) (${report.columnDrift.length}):`);
+            for (const c of report.columnDrift) {
+                console.log(`  ${c.table}`);
+                if (c.missingColumns.length)
+                    console.log(`    missing:    ${c.missingColumns.join(', ')}`);
+                if (c.unexpectedColumns.length)
+                    console.log(`    unexpected: ${c.unexpectedColumns.join(', ')}`);
+                for (const d of c.defaultMismatches)
+                    console.log(`    default ${d.column}: expected ${d.expected}, actual ${d.actual}`);
+                for (const d of c.typeMismatches)
+                    console.log(`    type ${d.column}: expected ${d.expected}, actual ${d.actual}`);
+                for (const d of c.nullabilityMismatches)
+                    console.log(`    nullability ${d.column}: expected ${d.expected ? 'NOT NULL' : 'nullable'}, actual ${d.actual ? 'NOT NULL' : 'nullable'}`);
+            }
+        }
+        if (report.constraintDrift.length) {
+            console.log(`\nCONSTRAINT DRIFT (missing or unexpected constraints) (${report.constraintDrift.length}):`);
+            for (const c of report.constraintDrift) {
+                console.log(`  ${c.table}`);
+                if (c.missingConstraints.length)
+                    for (const d of c.missingConstraints)
+                        console.log(`    missing:    ${d}`);
+                if (c.unexpectedConstraints.length)
+                    for (const d of c.unexpectedConstraints)
+                        console.log(`    unexpected: ${d}`);
+            }
+        }
+        if (report.enumDrift) {
+            const e = report.enumDrift;
+            console.log('\nENUM DRIFT (value set/order differs):');
+            console.log(`  ${e.name}`);
+            console.log(`    expected: ${e.expectedValues.join(', ')}`);
+            console.log(`    actual:   ${e.actualValues.join(', ')}`);
+        }
+        console.log('\n✗ Schema drift detected');
+        process.exitCode = 1;
+    }
+    finally {
+        await db.close();
+    }
+}
 async function cmdPlans(args) {
     const fileConfig = loadConfigFile(args.config);
     const schema = args.schema || process.env.PGBOSS_SCHEMA || fileConfig.schema || plans.DEFAULT_SCHEMA;
@@ -371,6 +512,9 @@ async function main() {
             case 'version':
                 await cmdVersion(args);
                 break;
+            case 'doctor':
+                await cmdDoctor(args);
+                break;
             case 'create':
                 await cmdCreate(args);
                 break;

package/dist/contractor.d.ts

@@ -14,6 +14,7 @@ declare class Contractor {
     schemaVersion(): Promise<number | null>;
     isInstalled(): Promise<boolean>;
     start(): Promise<void>;
+    detectDrift(): Promise<types.SchemaDriftReport>;
     check(): Promise<void>;
     create(): Promise<void>;
     migrate(version: number): Promise<void>;

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,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"}
+{"version":3,"file":"contractor.d.ts","sourceRoot":"","sources":["../src/contractor.ts"],"names":[],"mappings":"AAKA,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;IAiBL,WAAW,IAAK,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC;IAqGhD,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

@@ -1,5 +1,6 @@
 import assert from 'node:assert';
 import * as plans from "./plans.js";
+import * as drifter from "./drifter.js";
 import * as migrationStore from "./migrationStore.js";
 import packageJson from '../package.json' with { type: 'json' };
 const schemaVersion = packageJson.pgboss.schema;
@@ -44,6 +45,102 @@ class Contractor {
             await this.create();
         }
     }
+    // Presence-level schema drift scan: compares the managed indexes the code expects against the live
+    // catalog. Partitioned vs. non-partitioned is read from the database (job_common presence), and the
+    // per-queue policy indexes are computed from the queue table, so conditional indexes are handled.
+    async detectDrift() {
+        const schema = this.config.schema;
+        const probe = await this.db.executeSql(plans.jobCommonExists(schema));
+        const partitioned = !!probe.rows[0].name;
+        const partitions = partitioned
+            ? (await this.db.executeSql(plans.getManagedQueuePartitions(schema))).rows
+            : [];
+        const liveResult = await this.db.executeSql(drifter.getSchemaIndexes(schema));
+        const live = liveResult.rows.map((r) => ({
+            name: r.name,
+            table: r.table,
+            valid: r.valid,
+            def: r.def,
+            constraintBacked: r.constraintBacked
+        }));
+        // The bam table only exists from schema v27; ignore its absence on very old schemas.
+        let bamCommands = [];
+        try {
+            const bamResult = await this.db.executeSql(plans.getIncompleteBamCommands(schema));
+            bamCommands = bamResult.rows.map((r) => r.command);
+        }
+        catch {
+            bamCommands = [];
+        }
+        // Function-body and enum drift are best-effort: pg_get_functiondef is unsupported on some backends
+        // (CockroachDB), so a failure here SKIPS the function check rather than aborting the whole scan.
+        // `functionsSupported` must be tracked separately from an empty result: an empty `liveFunctions`
+        // means "query failed / unsupported", which is NOT the same as "no functions found" — feeding
+        // `live: []` to the drift check would report every expected function as missing and flip `ok` to
+        // false on every CockroachDB scan. So the check is gated (passed `undefined`) when the query throws.
+        let liveFunctions = [];
+        let functionsSupported = true;
+        try {
+            const fnResult = await this.db.executeSql(drifter.getSchemaFunctions(schema));
+            liveFunctions = fnResult.rows.map((r) => ({ name: r.name, def: r.def }));
+        }
+        catch {
+            functionsSupported = false;
+        }
+        let enumLabels = [];
+        try {
+            const enumResult = await this.db.executeSql(drifter.getEnumDefinition(schema));
+            enumLabels = enumResult.rows.map((r) => r.label);
+        }
+        catch {
+            enumLabels = [];
+        }
+        // Table presence is read from a catalog-only query independent of the column diff below. The column
+        // query uses pg_get_expr (unsupported on some backends) and is best-effort; if it throws, the column
+        // check is skipped — but table presence must NOT collapse to "everything missing", so it comes from
+        // its own pg_class probe. pg_class is available everywhere, so this rarely throws; if it somehow
+        // does, fall back to the columns-derived set rather than aborting the scan.
+        let liveTables = null;
+        try {
+            const tableResult = await this.db.executeSql(drifter.getSchemaTables(schema));
+            liveTables = tableResult.rows.map((r) => r.table);
+        }
+        catch {
+            liveTables = null;
+        }
+        let liveColumns = [];
+        try {
+            const colResult = await this.db.executeSql(drifter.getSchemaColumns(schema));
+            liveColumns = colResult.rows.map((r) => ({ table: r.table, column: r.column, default: r.default, type: r.type, notNull: r.notNull }));
+        }
+        catch {
+            liveColumns = [];
+        }
+        let liveConstraints = [];
+        try {
+            const conResult = await this.db.executeSql(drifter.getSchemaConstraints(schema));
+            liveConstraints = conResult.rows.map((r) => ({ table: r.table, def: r.def }));
+        }
+        catch {
+            liveConstraints = [];
+        }
+        const building = new Set(bamCommands.map(plans.bamCommandIndexName).filter((n) => n !== null));
+        // CockroachDB renders column types (INT8 vs integer), default expressions, and constraint
+        // definitions differently from standard Postgres, so the canonical-form checks would false-positive
+        // there. Restrict type/default/constraint drift to Postgres-typed backends; the presence checks
+        // (tables, indexes, column names, functions, enum) still run everywhere.
+        const canonicalPg = this.config.backend !== 'cockroachdb';
+        const expectedColumns = plans.expectedManagedColumns(schema, partitioned, partitions)
+            .map(c => canonicalPg ? c : { table: c.table, columns: c.columns });
+        return drifter.computeSchemaDrift({
+            indexes: { expected: plans.expectedManagedIndexes(schema, partitioned, partitions), live, building },
+            tables: { expected: plans.expectedManagedTables(schema, partitioned, partitions), live: liveTables ?? [...new Set(liveColumns.map(c => c.table))] },
+            functions: functionsSupported ? { expected: plans.expectedManagedFunctions(schema, partitioned), live: liveFunctions } : undefined,
+            columns: { expected: expectedColumns, live: liveColumns },
+            constraints: canonicalPg ? { expected: plans.expectedManagedConstraints(schema, partitioned), live: liveConstraints } : undefined,
+            enum: { name: 'job_state', expected: plans.EXPECTED_JOB_STATES, actual: enumLabels }
+        });
+    }
     async check() {
         const installed = await this.isInstalled();
         if (!installed) {

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;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"}
+{"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;IAmFxB,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

@@ -52,6 +52,12 @@ class Db extends EventEmitter {
         let client = null;
         let reconnectTimer = null;
         let attempt = 0;
+        // Only self-heal once the listener has been established at least once. If the INITIAL connect
+        // fails, the rejection propagates to the caller (Notifier.start), which falls back to
+        // polling-only and discards this subscription's close handle — so a reconnect scheduled from
+        // the client 'error' handler would be an untracked connection nothing can close, keeping the
+        // event loop alive and delivering notifications into a stopped manager.
+        let established = false;
         const scheduleReconnect = () => {
             if (closed || reconnectTimer)
                 return;
@@ -73,7 +79,8 @@ class Db extends EventEmitter {
                     next.end().catch(() => { });
                     if (client === next)
                         client = null;
-                    scheduleReconnect();
+                    if (established)
+                        scheduleReconnect();
                 }
             });
             next.on('notification', msg => {
@@ -98,6 +105,7 @@ class Db extends EventEmitter {
                 throw err;
             }
             attempt = 0;
+            established = true;
             onReconnect();
         };
         await connect();