pg-boss 12.5.4 → 12.7.0

package/README.md

@@ -52,6 +52,108 @@ This will likely cater the most to teams already familiar with the simplicity of
 * Serverless function compatible
 * Multi-master compatible (for example, in a Kubernetes ReplicaSet)
 
+## CLI
+
+pg-boss includes a command-line interface for managing database migrations without writing code. This is useful for CI/CD pipelines, database setup scripts, or manual schema management.
+
+### Installation
+
+When installed globally, the CLI is available as `pg-boss`:
+
+```bash
+npm install -g pg-boss
+pg-boss --help
+```
+
+Or run directly with npx:
+
+```bash
+npx pg-boss --help
+```
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `migrate` | Run pending migrations (creates schema if not exists) |
+| `create` | Create initial pg-boss schema |
+| `version` | Show current schema version |
+| `rollback` | Rollback the last migration |
+| `plans <subcommand>` | Output SQL without executing (subcommands: `create`, `migrate`, `rollback`) |
+
+### Connection Configuration
+
+The CLI supports multiple ways to configure the database connection, in order of precedence:
+
+1. **Command-line arguments**
+   ```bash
+   pg-boss migrate --connection-string postgres://user:pass@host/database
+   # or individual options
+   pg-boss migrate --host localhost --port 5432 --database mydb --user postgres --password secret
+   ```
+
+2. **Environment variables**
+   ```bash
+   PGBOSS_DATABASE_URL=postgres://user:pass@host/database pg-boss migrate
+   # or individual variables
+   PGBOSS_HOST=localhost PGBOSS_PORT=5432 PGBOSS_DATABASE=mydb PGBOSS_USER=postgres PGBOSS_PASSWORD=secret pg-boss migrate
+   ```
+
+   This allows admin credentials for migrations to coexist with regular application database credentials (e.g., `DATABASE_URL` for the app, `PGBOSS_DATABASE_URL` for migrations).
+
+3. **Config file** (pgboss.json or .pgbossrc in current directory, or specify with `--config`)
+   ```bash
+   pg-boss migrate --config ./config/pgboss.json
+   ```
+
+   Config file format:
+   ```json
+   {
+     "host": "localhost",
+     "port": 5432,
+     "database": "mydb",
+     "user": "postgres",
+     "password": "secret",
+     "schema": "pgboss"
+   }
+   ```
+
+### Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--connection-string` | `-c` | PostgreSQL connection string |
+| `--host` | | Database host |
+| `--port` | | Database port |
+| `--database` | `-d` | Database name |
+| `--user` | `-u` | Database user |
+| `--password` | `-p` | Database password |
+| `--schema` | `-s` | pg-boss schema name (default: pgboss) |
+| `--config` | | Path to config file |
+| `--dry-run` | | Show SQL without executing (for migrate, create, rollback) |
+
+### Examples
+
+```bash
+# Create schema in a new database
+pg-boss create --connection-string postgres://localhost/myapp
+
+# Run migrations in CI/CD pipeline
+PGBOSS_DATABASE_URL=$PGBOSS_DATABASE_URL pg-boss migrate
+
+# Preview migration SQL before running
+pg-boss migrate --connection-string postgres://localhost/myapp --dry-run
+
+# Check current schema version
+pg-boss version -c postgres://localhost/myapp
+
+# Use a custom schema name
+pg-boss migrate -c postgres://localhost/myapp --schema myapp_jobs
+
+# Output SQL for creating schema (useful for review or manual execution)
+pg-boss plans create --schema myapp_jobs
+```
+
 ## Requirements
 * Node 22.12 or higher for CommonJS's require(esm)
 * PostgreSQL 13 or higher

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,QAW3C;AAED,iBAAS,aAAa,CAAE,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,OAAO,CA8ChD;AAED,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,CAyBA;AAED,iBAAS,cAAc,CAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,QAOlD;AAED,iBAAS,SAAS,CAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC,kBAAkB,GAAG,KAAK,CAAC,0BAA0B,CAmB9F;AAkBD,iBAAS,wBAAwB,CAAE,IAAI,EAAE,MAAM,QAK9C;AAED,iBAAS,eAAe,CAAE,IAAI,EAAE,MAAM,QAIrC;AAED,iBAAS,SAAS,CAAE,GAAG,EAAE,MAAM,QAI9B;AAuFD,OAAO,EACL,SAAS,EACT,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,aAAa,EACb,aAAa,EACb,SAAS,EACT,MAAM,EACN,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;AAMD,iBAAS,iBAAiB,CAAE,MAAM,GAAE,GAAQ,QAW3C;AAED,iBAAS,aAAa,CAAE,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,OAAO,CA+ChD;AAmED,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,CA2BA;AAED,iBAAS,cAAc,CAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,QAOlD;AAED,iBAAS,SAAS,CAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC,kBAAkB,GAAG,KAAK,CAAC,0BAA0B,CAoB9F;AAkBD,iBAAS,wBAAwB,CAAE,IAAI,EAAE,MAAM,QAK9C;AAED,iBAAS,eAAe,CAAE,IAAI,EAAE,MAAM,QAIrC;AAED,iBAAS,SAAS,CAAE,GAAG,EAAE,MAAM,QAI9B;AA+FD,OAAO,EACL,SAAS,EACT,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,aAAa,EACb,aAAa,EACb,SAAS,EACT,MAAM,EACN,iBAAiB,EAClB,CAAA"}

package/dist/attorney.js

@@ -51,8 +51,57 @@ function checkSendArgs(args) {
     validateExpirationConfig(options);
     validateRetentionConfig(options);
     validateDeletionConfig(options);
+    validateGroupConfig(options);
     return { name, data, options };
 }
+function validateGroupConfig(config) {
+    if (!('group' in config) || config.group === undefined || config.group === null) {
+        return;
+    }
+    assert(typeof config.group === 'object', 'group must be an object');
+    assert(typeof config.group.id === 'string' && config.group.id.length > 0, 'group.id must be a non-empty string');
+    assert(!('tier' in config.group) || (typeof config.group.tier === 'string' && config.group.tier.length > 0), 'group.tier must be a non-empty string if provided');
+}
+function validateGroupConcurrencyValue(value, optionName) {
+    if (typeof value === 'number') {
+        assert(Number.isInteger(value) && value >= 1, `${optionName} must be an integer >= 1`);
+        return;
+    }
+    assert(typeof value === 'object', `${optionName} must be a number or an object with { default, tiers? }`);
+    assert(Number.isInteger(value.default) && value.default >= 1, `${optionName}.default must be an integer >= 1`);
+    if ('tiers' in value && value.tiers) {
+        assert(typeof value.tiers === 'object', `${optionName}.tiers must be an object`);
+        for (const [tier, limit] of Object.entries(value.tiers)) {
+            assert(typeof tier === 'string' && tier.length > 0, `${optionName} tier keys must be non-empty strings`);
+            assert(Number.isInteger(limit) && limit >= 1, `${optionName}.tiers["${tier}"] must be an integer >= 1`);
+        }
+    }
+}
+function validateGroupConcurrencyConfig(config) {
+    const hasGlobal = config.groupConcurrency != null;
+    const hasLocal = config.localGroupConcurrency != null;
+    assert(!(hasGlobal && hasLocal), 'cannot specify both groupConcurrency and localGroupConcurrency - choose one');
+    if (hasGlobal)
+        validateGroupConcurrencyValue(config.groupConcurrency, 'groupConcurrency');
+    if (hasLocal) {
+        validateGroupConcurrencyValue(config.localGroupConcurrency, 'localGroupConcurrency');
+        validateLocalGroupConcurrencyLimit(config.localGroupConcurrency, config.localConcurrency);
+    }
+}
+function validateLocalGroupConcurrencyLimit(localGroupConcurrency, localConcurrency) {
+    const effectiveLocalConcurrency = localConcurrency ?? 1;
+    if (typeof localGroupConcurrency === 'number') {
+        assert(localGroupConcurrency <= effectiveLocalConcurrency, `localGroupConcurrency (${localGroupConcurrency}) cannot exceed localConcurrency (${effectiveLocalConcurrency})`);
+    }
+    else if (typeof localGroupConcurrency === 'object') {
+        assert(localGroupConcurrency.default <= effectiveLocalConcurrency, `localGroupConcurrency.default (${localGroupConcurrency.default}) cannot exceed localConcurrency (${effectiveLocalConcurrency})`);
+        if (localGroupConcurrency.tiers) {
+            for (const [tier, limit] of Object.entries(localGroupConcurrency.tiers)) {
+                assert(limit <= effectiveLocalConcurrency, `localGroupConcurrency.tiers["${tier}"] (${limit}) cannot exceed localConcurrency (${effectiveLocalConcurrency})`);
+            }
+        }
+    }
+}
 function checkWorkArgs(name, args) {
     let options, callback;
     assert(name, 'queue name is required');
@@ -71,6 +120,8 @@ function checkWorkArgs(name, args) {
     assert(!('batchSize' in options) || (Number.isInteger(options.batchSize) && options.batchSize >= 1), 'batchSize must be an integer > 0');
     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');
+    validateGroupConcurrencyConfig(options);
     return { options, callback };
 }
 function checkFetchArgs(name, options) {
@@ -92,6 +143,7 @@ function getConfig(value) {
     applySchemaConfig(config);
     applyOpsConfig(config);
     applyScheduleConfig(config);
+    applyBamConfig(config);
     validateWarningConfig(config);
     return config;
 }
@@ -157,7 +209,7 @@ function applyOpsConfig(config) {
     assert(config.queueCacheIntervalSeconds / 60 / 60 <= POLICY.MAX_EXPIRATION_HOURS, `configuration assert: queueCacheIntervalSeconds cannot exceed ${POLICY.MAX_EXPIRATION_HOURS} hours`);
 }
 function validateDeletionConfig(config) {
-    assert(!('deleteAfterSeconds' in config) || config.deleteAfterSeconds >= 1, 'configuration assert: deleteAfterSeconds must be at least every second');
+    assert(!('deleteAfterSeconds' in config) || config.deleteAfterSeconds >= 0, 'configuration assert: deleteAfterSeconds must be at least 0 (0 disables deletion)');
 }
 function applyScheduleConfig(config) {
     assert(!('clockMonitorIntervalSeconds' in config) || (config.clockMonitorIntervalSeconds >= 1 && config.clockMonitorIntervalSeconds <= 600), 'configuration assert: clockMonitorIntervalSeconds must be between 1 second and 10 minutes');
@@ -167,4 +219,9 @@ function applyScheduleConfig(config) {
     assert(!('cronWorkerIntervalSeconds' in config) || (config.cronWorkerIntervalSeconds >= 1 && config.cronWorkerIntervalSeconds <= 45), 'configuration assert: cronWorkerIntervalSeconds must be between 1 and 45 seconds');
     config.cronWorkerIntervalSeconds = config.cronWorkerIntervalSeconds || 5;
 }
+function applyBamConfig(config) {
+    const minInterval = config.__test__bypass_bam_interval_check ? 1 : 10;
+    assert(!('bamIntervalSeconds' in config) || config.bamIntervalSeconds >= minInterval, `configuration assert: bamIntervalSeconds must be at least ${minInterval} seconds`);
+    config.bamIntervalSeconds = config.bamIntervalSeconds || 60;
+}
 export { assertKey, assertPostgresObjectName, assertQueueName, checkFetchArgs, checkSendArgs, checkWorkArgs, getConfig, POLICY, validateQueueArgs };

package/dist/bam.d.ts

@@ -0,0 +1,14 @@
+import EventEmitter from 'node:events';
+import * as types from './types.js';
+declare class Bam extends EventEmitter implements types.EventsMixin {
+    #private;
+    events: {
+        error: string;
+        bam: string;
+    };
+    constructor(db: types.IDatabase, config: types.ResolvedConstructorOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export default Bam;
+//# sourceMappingURL=bam.d.ts.map

package/dist/bam.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bam.d.ts","sourceRoot":"","sources":["../src/bam.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AAEtC,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;IAUpC,KAAK;IAWL,IAAI;CAgGX;AAED,eAAe,GAAG,CAAA"}

package/dist/bam.js

@@ -0,0 +1,114 @@
+import EventEmitter from 'node:events';
+import * as plans from './plans.js';
+import * as types from './types.js';
+const events = {
+    error: 'error',
+    bam: 'bam'
+};
+class Bam extends EventEmitter {
+    #stopped;
+    #working;
+    #pollInterval;
+    #db;
+    #config;
+    events = events;
+    constructor(db, config) {
+        super();
+        this.#db = db;
+        this.#config = config;
+        this.#stopped = true;
+        this.#working = false;
+    }
+    async start() {
+        if (!this.#stopped)
+            return;
+        this.#stopped = false;
+        setImmediate(() => this.#onPoll());
+        this.#pollInterval = setInterval(() => this.#onPoll(), this.#config.bamIntervalSeconds * 1000);
+    }
+    async stop() {
+        if (this.#stopped)
+            return;
+        this.#stopped = true;
+        if (this.#pollInterval) {
+            clearInterval(this.#pollInterval);
+            this.#pollInterval = undefined;
+        }
+    }
+    async #onPoll() {
+        if (this.#stopped || this.#working || !this.#config.migrate)
+            return;
+        this.#working = true;
+        try {
+            if (this.#config.__test__throw_bam) {
+                throw new Error(this.#config.__test__throw_bam);
+            }
+            const sql = plans.trySetBamTime(this.#config.schema, this.#config.bamIntervalSeconds);
+            const { rows } = await this.#db.executeSql(sql);
+            if (rows.length === 1) {
+                await this.#processCommands();
+            }
+        }
+        catch (err) {
+            this.emit(events.error, err);
+        }
+        finally {
+            this.#working = false;
+        }
+    }
+    async #processCommands() {
+        if (this.#stopped)
+            return;
+        const entry = await this.#getNextCommand();
+        if (!entry || this.#stopped)
+            return;
+        this.emit(events.bam, {
+            id: entry.id,
+            name: entry.name,
+            status: 'in_progress',
+            queue: entry.queue,
+            table: entry.table
+        });
+        try {
+            await this.#db.executeSql(entry.command);
+            if (this.#stopped)
+                return;
+            await this.#markCompleted(entry.id);
+            this.emit(events.bam, {
+                id: entry.id,
+                name: entry.name,
+                status: 'completed',
+                queue: entry.queue,
+                table: entry.table
+            });
+        }
+        catch (err) {
+            if (this.#stopped)
+                return;
+            await this.#markFailed(entry.id, err);
+            this.emit(events.error, err);
+            this.emit(events.bam, {
+                id: entry.id,
+                name: entry.name,
+                status: 'failed',
+                queue: entry.queue,
+                table: entry.table,
+                error: String(err)
+            });
+        }
+    }
+    async #getNextCommand() {
+        const sql = plans.getNextBamCommand(this.#config.schema);
+        const { rows } = await this.#db.executeSql(sql);
+        return rows[0] || null;
+    }
+    async #markCompleted(id) {
+        const sql = plans.setBamCompleted(this.#config.schema, id);
+        await this.#db.executeSql(sql);
+    }
+    async #markFailed(id, error) {
+        const sql = plans.setBamFailed(this.#config.schema, id, String(error));
+        await this.#db.executeSql(sql);
+    }
+}
+export default Bam;

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;AAYnC,cAAM,IAAK,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;;IAQ1D,MAAM;;;MAAS;gBAGb,EAAE,EAAE,KAAK,CAAC,SAAS,EACnB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAkBpC,KAAK;IAUL,IAAI;IAiEJ,SAAS,CAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE;CAwEtD;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;AAYnC,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;IAmBpC,KAAK;IAWL,IAAI;IAkEJ,SAAS,CAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE;CAuFtD;AAED,eAAe,IAAI,CAAA"}

package/dist/boss.js

@@ -12,6 +12,7 @@ const WARNINGS = {
 };
 class Boss extends EventEmitter {
     #stopped;
+    #stopping;
     #maintaining;
     #superviseInterval;
     #db;
@@ -24,6 +25,7 @@ class Boss extends EventEmitter {
         this.#config = config;
         this.#manager = manager;
         this.#stopped = true;
+        this.#stopping = false;
         if (config.warningSlowQuerySeconds) {
             WARNINGS.SLOW_QUERY.seconds = config.warningSlowQuerySeconds;
         }
@@ -33,12 +35,14 @@ class Boss extends EventEmitter {
     }
     async start() {
         if (this.#stopped) {
+            this.#stopping = false;
             this.#superviseInterval = setInterval(() => this.#onSupervise(), this.#config.superviseIntervalSeconds * 1000);
             this.#stopped = false;
         }
     }
     async stop() {
         if (!this.#stopped) {
+            this.#stopping = true;
             if (this.#superviseInterval)
                 clearInterval(this.#superviseInterval);
             this.#stopped = true;
@@ -105,9 +109,13 @@ class Boss extends EventEmitter {
             return acc;
         }, {});
         for (const queueGroup of Object.values(queueGroups)) {
+            if (this.#stopping)
+                return;
             const { table, queues } = queueGroup;
             const names = queues.map((i) => i.name);
             while (names.length) {
+                if (this.#stopping)
+                    return;
                 const chunk = names.splice(0, 100);
                 await this.#monitor(table, chunk);
                 await this.#maintain(table, chunk);
@@ -115,12 +123,18 @@ class Boss extends EventEmitter {
         }
     }
     async #monitor(table, names) {
+        if (this.#stopping)
+            return;
         const command = plans.trySetQueueMonitorTime(this.#config.schema, names, this.#config.monitorIntervalSeconds);
         const { rows } = await this.#executeQuery(command);
+        if (this.#stopping)
+            return;
         if (rows.length) {
             const queues = rows.map((q) => q.name);
             const cacheStatsSql = plans.cacheQueueStats(this.#config.schema, table, queues);
             const { rows: rowsCacheStats } = await this.#executeSql(cacheStatsSql);
+            if (this.#stopping)
+                return;
             const warnings = rowsCacheStats.filter(i => i.queuedCount > (i.warningQueueSize || WARNINGS.LARGE_QUEUE.size));
             for (const warning of warnings) {
                 this.emit(events.warning, {
@@ -133,8 +147,12 @@ class Boss extends EventEmitter {
         }
     }
     async #maintain(table, names) {
+        if (this.#stopping)
+            return;
         const command = plans.trySetQueueDeletionTime(this.#config.schema, names, this.#config.maintenanceIntervalSeconds);
         const { rows } = await this.#executeQuery(command);
+        if (this.#stopping)
+            return;
         if (rows.length) {
             const queues = rows.map((q) => q.name);
             const sql = plans.deletion(this.#config.schema, table, queues);

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}