bullmq 6.0.11 → 6.1.0

package/dist/cjs/postgres/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isPgPool = exports.LATEST_SCHEMA_VERSION = exports.quoteSchemaName = exports.DEFAULT_SCHEMA = exports.MIGRATION_ADVISORY_LOCK_KEY = exports.RECOMMENDED_POSTGRES_VERSION = exports.MINIMUM_POSTGRES_VERSION = exports.assertPostgresVersion = exports.UnsupportedPostgresVersionError = exports.SchemaVersionMismatchError = exports.runMigrations = exports.PostgresQueueBackend = exports.PostgresConnection = exports.createPostgresBackend = void 0;
+exports.isPgPool = exports.LATEST_SCHEMA_VERSION = exports.quoteSchemaName = exports.DEFAULT_SCHEMA = exports.MIGRATION_ADVISORY_LOCK_KEY = exports.BULLMQ_MAJOR_VERSION = exports.RECOMMENDED_POSTGRES_VERSION = exports.MINIMUM_POSTGRES_VERSION = exports.assertPostgresVersion = exports.UnsupportedPostgresVersionError = exports.SchemaVersionMismatchError = exports.SchemaMigrationRequiredError = exports.assertSchemaCompatibility = exports.runMigrations = exports.PostgresQueueBackend = exports.PostgresConnection = exports.createPostgresBackend = void 0;
 var create_postgres_backend_1 = require("./create-postgres-backend");
 Object.defineProperty(exports, "createPostgresBackend", { enumerable: true, get: function () { return create_postgres_backend_1.createPostgresBackend; } });
 var postgres_connection_1 = require("./postgres-connection");
@@ -9,11 +9,14 @@ var postgres_queue_backend_1 = require("./postgres-queue-backend");
 Object.defineProperty(exports, "PostgresQueueBackend", { enumerable: true, get: function () { return postgres_queue_backend_1.PostgresQueueBackend; } });
 var migrator_1 = require("./migrator");
 Object.defineProperty(exports, "runMigrations", { enumerable: true, get: function () { return migrator_1.runMigrations; } });
+Object.defineProperty(exports, "assertSchemaCompatibility", { enumerable: true, get: function () { return migrator_1.assertSchemaCompatibility; } });
+Object.defineProperty(exports, "SchemaMigrationRequiredError", { enumerable: true, get: function () { return migrator_1.SchemaMigrationRequiredError; } });
 Object.defineProperty(exports, "SchemaVersionMismatchError", { enumerable: true, get: function () { return migrator_1.SchemaVersionMismatchError; } });
 Object.defineProperty(exports, "UnsupportedPostgresVersionError", { enumerable: true, get: function () { return migrator_1.UnsupportedPostgresVersionError; } });
 Object.defineProperty(exports, "assertPostgresVersion", { enumerable: true, get: function () { return migrator_1.assertPostgresVersion; } });
 Object.defineProperty(exports, "MINIMUM_POSTGRES_VERSION", { enumerable: true, get: function () { return migrator_1.MINIMUM_POSTGRES_VERSION; } });
 Object.defineProperty(exports, "RECOMMENDED_POSTGRES_VERSION", { enumerable: true, get: function () { return migrator_1.RECOMMENDED_POSTGRES_VERSION; } });
+Object.defineProperty(exports, "BULLMQ_MAJOR_VERSION", { enumerable: true, get: function () { return migrator_1.BULLMQ_MAJOR_VERSION; } });
 Object.defineProperty(exports, "MIGRATION_ADVISORY_LOCK_KEY", { enumerable: true, get: function () { return migrator_1.MIGRATION_ADVISORY_LOCK_KEY; } });
 Object.defineProperty(exports, "DEFAULT_SCHEMA", { enumerable: true, get: function () { return migrator_1.DEFAULT_SCHEMA; } });
 Object.defineProperty(exports, "quoteSchemaName", { enumerable: true, get: function () { return migrator_1.quoteSchemaName; } });

package/dist/cjs/postgres/migrations/index.js

@@ -10,17 +10,20 @@ exports.MIGRATIONS = [
     {
         version: 1,
         name: '0001_schema',
+        minClientVersion: 6,
         load: () => (0, sql_loader_1.loadMigrationSql)('0001_schema.sql'),
     },
     {
         version: 2,
         name: '0002_functions',
+        // This initial schema split is the sole same-major exception. Future schema
+        // migrations are breaking changes and require a new BullMQ major version.
+        minClientVersion: 6,
         load: () => (0, sql_loader_1.loadMigrationSql)('0002_functions.sql'),
     },
 ];
 /**
- * The highest schema version this BullMQ build knows how to produce. Compared
- * against the version recorded in the database to decide whether to migrate
- * (database older), no-op (equal), or refuse to run (database newer).
+ * The highest schema version this BullMQ build knows how to produce. Explicit
+ * migration applies older pending versions.
  */
 exports.LATEST_SCHEMA_VERSION = exports.MIGRATIONS.length > 0 ? exports.MIGRATIONS[exports.MIGRATIONS.length - 1].version : 0;

package/dist/cjs/postgres/migrator.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SchemaVersionMismatchError = exports.UnsupportedPostgresVersionError = exports.RECOMMENDED_POSTGRES_VERSION = exports.MINIMUM_POSTGRES_VERSION = exports.MIGRATION_ADVISORY_LOCK_KEY = exports.DEFAULT_SCHEMA = void 0;
+exports.SchemaMigrationRequiredError = exports.SchemaVersionMismatchError = exports.UnsupportedPostgresVersionError = exports.BULLMQ_MAJOR_VERSION = exports.RECOMMENDED_POSTGRES_VERSION = exports.MINIMUM_POSTGRES_VERSION = exports.MIGRATION_ADVISORY_LOCK_KEY = exports.DEFAULT_SCHEMA = void 0;
 exports.assertPostgresVersion = assertPostgresVersion;
 exports.quoteSchemaName = quoteSchemaName;
+exports.assertSchemaCompatibility = assertSchemaCompatibility;
 exports.runMigrations = runMigrations;
 exports.getCurrentSchemaVersion = getCurrentSchemaVersion;
 const migrations_1 = require("./migrations");
+const version_1 = require("../version");
 /**
  * Default PostgreSQL schema (namespace) the backend lives in. The schema is the
  * connection-level namespace for *all* queues — the SQL-native replacement for
@@ -38,6 +40,8 @@ exports.MINIMUM_POSTGRES_VERSION = 13;
  * (mirrors the Redis backend's `recommendedMinimumVersion`).
  */
 exports.RECOMMENDED_POSTGRES_VERSION = 14;
+/** The BullMQ major version used for PostgreSQL schema compatibility checks. */
+exports.BULLMQ_MAJOR_VERSION = parseInt(version_1.version.split('.')[0], 10);
 /**
  * Thrown when the connected PostgreSQL server is older than {@link
  * MINIMUM_POSTGRES_VERSION}. Pass `skipVersionCheck: true` on the connection to
@@ -69,19 +73,7 @@ async function assertPostgresVersion(client, skipVersionCheck = false) {
     }
     const { rows } = await client.query(`SELECT current_setting('server_version_num') AS num, ` +
         `current_setting('server_version') AS ver`);
-    const major = Math.floor(parseInt((_b = (_a = rows[0]) === null || _a === void 0 ? void 0 : _a.num) !== null && _b !== void 0 ? _b : '0', 10) / 10000);
-    const reported = (_d = (_c = rows[0]) === null || _c === void 0 ? void 0 : _c.ver) !== null && _d !== void 0 ? _d : 'unknown';
-    if (major < exports.MINIMUM_POSTGRES_VERSION) {
-        throw new UnsupportedPostgresVersionError(reported, exports.MINIMUM_POSTGRES_VERSION);
-    }
-    if (major < exports.RECOMMENDED_POSTGRES_VERSION) {
-        const warned = assertPostgresVersion._warnedRecommendedVersion;
-        if (!warned) {
-            assertPostgresVersion._warnedRecommendedVersion = true;
-            console.warn(`BullMQ: PostgreSQL ${exports.RECOMMENDED_POSTGRES_VERSION} or newer is ` +
-                `recommended for the PostgreSQL backend (detected ${reported}).`);
-        }
-    }
+    assertPostgresVersionValues((_b = (_a = rows[0]) === null || _a === void 0 ? void 0 : _a.num) !== null && _b !== void 0 ? _b : '0', (_d = (_c = rows[0]) === null || _c === void 0 ? void 0 : _c.ver) !== null && _d !== void 0 ? _d : 'unknown');
 }
 /**
  * Validates a PostgreSQL schema name and returns it double-quoted for safe
@@ -107,26 +99,70 @@ function quoteSchemaName(schema) {
  * to upgrade BullMQ — schema downgrades are not supported.
  */
 class SchemaVersionMismatchError extends Error {
-    constructor(databaseVersion, supportedVersion) {
-        super(`BullMQ: the PostgreSQL schema is at version ${databaseVersion}, but this ` +
-            `version of BullMQ only supports schema versions up to ${supportedVersion}. ` +
-            `The database was migrated by a newer BullMQ release; upgrade BullMQ to ` +
-            `continue (schema downgrades are not supported).`);
-        this.databaseVersion = databaseVersion;
-        this.supportedVersion = supportedVersion;
+    constructor(minimumClientVersion, clientVersion) {
+        super(`BullMQ: the PostgreSQL schema requires BullMQ major version ` +
+            `${minimumClientVersion} or newer, but this client is major version ` +
+            `${clientVersion}. Upgrade BullMQ to use this schema.`);
+        this.minimumClientVersion = minimumClientVersion;
+        this.clientVersion = clientVersion;
         this.name = 'SchemaVersionMismatchError';
+        this.databaseVersion = minimumClientVersion;
+        this.supportedVersion = clientVersion;
     }
 }
 exports.SchemaVersionMismatchError = SchemaVersionMismatchError;
+/** Thrown when a connection uses a schema that has not been initialized. */
+class SchemaMigrationRequiredError extends Error {
+    constructor(schema) {
+        super(`BullMQ: PostgreSQL schema ${JSON.stringify(schema)} is not initialized. ` +
+            'Run the migrations explicitly or pass `migrate: true` on the connection.');
+        this.schema = schema;
+        this.name = 'SchemaMigrationRequiredError';
+    }
+}
+exports.SchemaMigrationRequiredError = SchemaMigrationRequiredError;
+/**
+ * Checks schema and server compatibility with one read and without locks or DDL.
+ */
+async function assertSchemaCompatibility(client, schema = exports.DEFAULT_SCHEMA, options = {}) {
+    var _a, _b, _c, _d;
+    const quotedSchema = quoteSchemaName(schema);
+    let rows;
+    try {
+        ({ rows } = await client.query(`SELECT COALESCE(MAX(version), 0)::int AS version,
+              COALESCE(
+                MAX((to_jsonb(migration)->>'min_client_version')::int),
+                $1
+              )::int AS min_client_version,
+              current_setting('server_version_num') AS server_version_num,
+              current_setting('server_version') AS server_version
+         FROM ${quotedSchema}.migration`, [exports.BULLMQ_MAJOR_VERSION]));
+    }
+    catch (err) {
+        if (err.code === '42P01') {
+            throw new SchemaMigrationRequiredError(schema);
+        }
+        throw err;
+    }
+    const state = rows[0];
+    if (!options.skipVersionCheck) {
+        assertPostgresVersionValues((_a = state === null || state === void 0 ? void 0 : state.server_version_num) !== null && _a !== void 0 ? _a : '0', (_b = state === null || state === void 0 ? void 0 : state.server_version) !== null && _b !== void 0 ? _b : 'unknown');
+    }
+    const minimumClientVersion = (_c = state === null || state === void 0 ? void 0 : state.min_client_version) !== null && _c !== void 0 ? _c : exports.BULLMQ_MAJOR_VERSION;
+    if (minimumClientVersion > exports.BULLMQ_MAJOR_VERSION) {
+        throw new SchemaVersionMismatchError(minimumClientVersion, exports.BULLMQ_MAJOR_VERSION);
+    }
+    return (_d = state === null || state === void 0 ? void 0 : state.version) !== null && _d !== void 0 ? _d : 0;
+}
 /**
  * Brings the database schema up to {@link LATEST_SCHEMA_VERSION}.
  *
- * Run on the backend's first `waitUntilReady()` (a constructor cannot perform
- * async I/O). Behaviour by current database version:
+ * Run explicitly with `runMigrations()` or by passing `migrate: true` on the
+ * connection. Behaviour by current database version:
  *
  * - **older** than supported → applies the pending migrations in order.
  * - **equal** to supported → no-op.
- * - **newer** than supported → throws {@link SchemaVersionMismatchError}.
+ * - **newer** than bundled → no-op if its minimum client major is compatible.
  *
  * ## Atomicity
  *
@@ -185,9 +221,9 @@ async function runMigrations(client, schema = exports.DEFAULT_SCHEMA, options =
         await client.query(`SET LOCAL search_path TO ${quotedSchema}`);
         await ensureLedgerTable(client);
         const currentVersion = await getCurrentSchemaVersion(client);
-        if (currentVersion > migrations_1.LATEST_SCHEMA_VERSION) {
-            // Rolled back by the catch below; nothing has been written anyway.
-            throw new SchemaVersionMismatchError(currentVersion, migrations_1.LATEST_SCHEMA_VERSION);
+        const minimumClientVersion = await getMinimumClientVersion(client);
+        if (minimumClientVersion > exports.BULLMQ_MAJOR_VERSION) {
+            throw new SchemaVersionMismatchError(minimumClientVersion, exports.BULLMQ_MAJOR_VERSION);
         }
         if (currentVersion < migrations_1.LATEST_SCHEMA_VERSION) {
             for (const migration of migrations_1.MIGRATIONS) {
@@ -220,13 +256,35 @@ async function ensureLedgerTable(client) {
     await client.query(`CREATE TABLE IF NOT EXISTS migration (
        version    integer PRIMARY KEY,
        name       text NOT NULL,
+       min_client_version integer NOT NULL,
        applied_at timestamptz NOT NULL DEFAULT now()
      )`);
+    await client.query('ALTER TABLE migration ADD COLUMN IF NOT EXISTS min_client_version integer');
+    await client.query('UPDATE migration SET min_client_version = $1 WHERE min_client_version IS NULL', [exports.BULLMQ_MAJOR_VERSION]);
+    await client.query('ALTER TABLE migration ALTER COLUMN min_client_version SET NOT NULL');
+}
+async function getMinimumClientVersion(client) {
+    var _a, _b;
+    const { rows } = await client.query(`SELECT COALESCE(MAX(min_client_version), $1)::int AS min_client_version
+       FROM migration`, [exports.BULLMQ_MAJOR_VERSION]);
+    return (_b = (_a = rows[0]) === null || _a === void 0 ? void 0 : _a.min_client_version) !== null && _b !== void 0 ? _b : exports.BULLMQ_MAJOR_VERSION;
 }
 async function applyMigration(client, migration) {
     await client.query(migration.load());
-    await client.query('INSERT INTO migration (version, name) VALUES ($1, $2)', [
-        migration.version,
-        migration.name,
-    ]);
+    await client.query(`INSERT INTO migration (version, name, min_client_version)
+     VALUES ($1, $2, $3)`, [migration.version, migration.name, migration.minClientVersion]);
+}
+function assertPostgresVersionValues(num, reported) {
+    const major = Math.floor(parseInt(num, 10) / 10000);
+    if (major < exports.MINIMUM_POSTGRES_VERSION) {
+        throw new UnsupportedPostgresVersionError(reported, exports.MINIMUM_POSTGRES_VERSION);
+    }
+    if (major < exports.RECOMMENDED_POSTGRES_VERSION) {
+        const warned = assertPostgresVersion._warnedRecommendedVersion;
+        if (!warned) {
+            assertPostgresVersion._warnedRecommendedVersion = true;
+            console.warn(`BullMQ: PostgreSQL ${exports.RECOMMENDED_POSTGRES_VERSION} or newer is ` +
+                `recommended for the PostgreSQL backend (detected ${reported}).`);
+        }
+    }
 }

package/dist/cjs/postgres/postgres-connection.js

@@ -35,10 +35,8 @@ function loadPgModule() {
  *   "wait for job" primitive (lazily established).
  *
  * Lifecycle mirrors {@link RedisConnection}: it is an {@link EventEmitter} that
- * surfaces normalized `'ready' | 'error' | 'close'` events, exposes
- * {@link PostgresConnection.waitUntilReady} (which also runs the schema
- * migrations exactly once, on a dedicated checked-out client) and
- * {@link PostgresConnection.close}.
+ * surfaces normalized `'ready' | 'error' | 'close'` events and exposes
+ * {@link PostgresConnection.waitUntilReady} and {@link PostgresConnection.close}.
  */
 class PostgresConnection extends events_1.EventEmitter {
     constructor(connection) {
@@ -53,6 +51,7 @@ class PostgresConnection extends events_1.EventEmitter {
             this.ownsPool = false;
             this.schema = migrator_1.DEFAULT_SCHEMA;
             this.skipVersionCheck = false;
+            this.migrateOnConnect = false;
             this.pgModule = undefined;
             this.listenClientConfig = undefined;
         }
@@ -62,11 +61,18 @@ class PostgresConnection extends events_1.EventEmitter {
                 ? {
                     schema: undefined,
                     skipVersionCheck: undefined,
+                    migrate: undefined,
+                    skipMigrations: undefined,
                     connectionString: connection,
                 }
-                : connection, { schema, skipVersionCheck } = _a, poolConfig = tslib_1.__rest(_a, ["schema", "skipVersionCheck"]);
+                : connection, { schema, skipVersionCheck, migrate, skipMigrations } = _a, poolConfig = tslib_1.__rest(_a, ["schema", "skipVersionCheck", "migrate", "skipMigrations"]);
+            if (migrate !== undefined && skipMigrations !== undefined) {
+                throw new Error('BullMQ: `migrate` and `skipMigrations` are mutually exclusive. Set only one.');
+            }
             this.schema = schema !== null && schema !== void 0 ? schema : migrator_1.DEFAULT_SCHEMA;
             this.skipVersionCheck = skipVersionCheck !== null && skipVersionCheck !== void 0 ? skipVersionCheck : false;
+            this.migrateOnConnect =
+                migrate !== null && migrate !== void 0 ? migrate : (skipMigrations === undefined ? false : !skipMigrations);
             // Validate early so a bad schema name fails fast (and before any DDL).
             const quotedSchema = (0, migrator_1.quoteSchemaName)(this.schema);
             // Pin every pooled connection's search_path to the schema so the `.sql`
@@ -101,11 +107,11 @@ class PostgresConnection extends events_1.EventEmitter {
         }
     }
     /**
-     * Resolves once the pool is reachable and the schema is up to date.
+     * Resolves once the pool is reachable and the schema is compatible.
      *
-     * Idempotent and memoized: the migration runs exactly once per connection,
-     * on a single dedicated client checked out of the pool (so the migration's
-     * advisory lock and transaction share one session — see {@link runMigrations}).
+     * Idempotent and memoized. By default this only reads the migration ledger.
+     * When `migrate: true` was configured, migrations run on one checked-out
+     * client so their advisory lock and transaction share a session.
      */
     async waitUntilReady() {
         if (!this.readyPromise) {
@@ -116,9 +122,16 @@ class PostgresConnection extends events_1.EventEmitter {
     async bootstrap() {
         const client = await this.pool.connect();
         try {
-            await (0, migrator_1.runMigrations)(client, this.schema, {
-                skipVersionCheck: this.skipVersionCheck,
-            });
+            if (this.migrateOnConnect) {
+                await (0, migrator_1.runMigrations)(client, this.schema, {
+                    skipVersionCheck: this.skipVersionCheck,
+                });
+            }
+            else {
+                await (0, migrator_1.assertSchemaCompatibility)(client, this.schema, {
+                    skipVersionCheck: this.skipVersionCheck,
+                });
+            }
         }
         finally {
             client.release();