pg-boss 12.5.4 → 12.7.0

package/dist/plans.js

@@ -39,9 +39,13 @@ function create(schema, version, options) {
         createTableQueue(schema),
         createTableSchedule(schema),
         createTableSubscription(schema),
+        createTableBam(schema),
+        jobTableFormatFunction(schema),
+        jobTableRunFunction(schema),
+        jobTableRunAsyncFunction(schema),
         createTableJob(schema),
         createPrimaryKeyJob(schema),
-        createTableJobCommon(schema, COMMON_JOB_TABLE),
+        createTableJobCommon(schema),
         createQueueFunction(schema),
         deleteQueueFunction(schema),
         insertVersion(schema, version)
@@ -69,7 +73,8 @@ function createTableVersion(schema) {
     return `
     CREATE TABLE ${schema}.version (
       version int primary key,
-      cron_on timestamp with time zone
+      cron_on timestamp with time zone,
+      bam_on timestamp with time zone
     )
   `;
 }
@@ -128,6 +133,113 @@ function createTableSubscription(schema) {
     )
   `;
 }
+function createTableBam(schema) {
+    return `
+    CREATE TABLE ${schema}.bam (
+      id uuid PRIMARY KEY default gen_random_uuid(),
+      name text NOT NULL,
+      version int NOT NULL,
+      status text NOT NULL DEFAULT 'pending',
+      queue text,
+      table_name text NOT NULL,
+      command text NOT NULL,
+      error text,
+      created_on timestamp with time zone NOT NULL DEFAULT now(),
+      started_on timestamp with time zone,
+      completed_on timestamp with time zone
+    )
+  `;
+}
+function jobTableFormatFunction(schema) {
+    return `
+    CREATE FUNCTION ${schema}.job_table_format(command text, table_name text)
+    RETURNS text AS
+    $$
+      SELECT format(
+        replace(
+          replace(command, '.job', '.%1$I'),
+          'job_i', '%1$s_i'
+        ),
+        table_name
+      );
+    $$
+    LANGUAGE sql IMMUTABLE;
+  `;
+}
+function jobTableRunFunction(schema) {
+    return `
+    CREATE FUNCTION ${schema}.job_table_run(command text, tbl_name text DEFAULT NULL, queue_name text DEFAULT NULL)
+    RETURNS VOID AS
+    $$
+    DECLARE
+      tbl RECORD;
+    BEGIN
+      IF queue_name IS NOT NULL THEN
+        SELECT table_name INTO tbl_name FROM ${schema}.queue WHERE name = queue_name;
+      END IF;
+
+      IF tbl_name IS NOT NULL THEN
+        EXECUTE ${schema}.job_table_format(command, tbl_name);
+        RETURN;
+      END IF;
+
+      EXECUTE ${schema}.job_table_format(command, '${COMMON_JOB_TABLE}');
+
+      FOR tbl IN SELECT table_name FROM ${schema}.queue WHERE partition = true
+      LOOP
+        EXECUTE ${schema}.job_table_format(command, tbl.table_name);
+      END LOOP;
+    END;
+    $$
+    LANGUAGE plpgsql;
+  `;
+}
+function jobTableRunAsyncFunction(schema) {
+    return `
+    CREATE FUNCTION ${schema}.job_table_run_async(command_name text, version int, command text, tbl_name text DEFAULT NULL, queue_name text DEFAULT NULL)
+    RETURNS VOID AS
+    $$
+    BEGIN
+      IF queue_name IS NOT NULL THEN
+        SELECT table_name INTO tbl_name FROM ${schema}.queue WHERE name = queue_name;
+      END IF;
+
+      IF tbl_name IS NOT NULL THEN
+        INSERT INTO ${schema}.bam (name, version, status, queue, table_name, command)
+        VALUES (
+          command_name,
+          version,
+          'pending',
+          queue_name,
+          tbl_name,
+          ${schema}.job_table_format(command, tbl_name)
+        );
+        RETURN;
+      END IF;
+
+      INSERT INTO ${schema}.bam (name, version, status, queue, table_name, command)
+      SELECT
+        command_name,
+        version,
+        'pending',
+        NULL,
+        '${COMMON_JOB_TABLE}',
+        ${schema}.job_table_format(command, '${COMMON_JOB_TABLE}')
+      UNION ALL
+      SELECT
+        command_name,
+        version,
+        'pending',
+        queue.name,
+        queue.table_name,
+        ${schema}.job_table_format(command, queue.table_name)
+      FROM ${schema}.queue
+      WHERE partition = true;
+    END;
+    $$
+    LANGUAGE plpgsql;
+  `;
+}
 function createTableJob(schema) {
     return `
     CREATE TABLE ${schema}.job (
@@ -145,6 +257,8 @@ function createTableJob(schema) {
       deletion_seconds int not null default ${QUEUE_DEFAULTS.deletion_seconds},
       singleton_key text,
       singleton_on timestamp without time zone,
+      group_id text,
+      group_tier text,
       start_after timestamp with time zone not null default now(),
       created_on timestamp with time zone not null default now(),
       started_on timestamp with time zone,
@@ -156,7 +270,7 @@ function createTableJob(schema) {
     ) PARTITION BY LIST (name)
   `;
 }
-const JOB_COLUMNS_MIN = 'id, name, data, expire_seconds as "expireInSeconds"';
+const JOB_COLUMNS_MIN = 'id, name, data, expire_seconds as "expireInSeconds", group_id as "groupId", group_tier as "groupTier"';
 const JOB_COLUMNS_ALL = `${JOB_COLUMNS_MIN},
   policy,
   state,
@@ -177,21 +291,22 @@ const JOB_COLUMNS_ALL = `${JOB_COLUMNS_MIN},
   dead_letter as "deadLetter",
   output
 `;
-function createTableJobCommon(schema, table) {
-    const format = (command) => command.replaceAll('.job', `.${table}`) + ';';
-    return `
-    CREATE TABLE ${schema}.${table} (LIKE ${schema}.job INCLUDING GENERATED INCLUDING DEFAULTS);
-    ${format(createPrimaryKeyJob(schema))}
-    ${format(createQueueForeignKeyJob(schema))}
-    ${format(createQueueForeignKeyJobDeadLetter(schema))}
-    ${format(createIndexJobPolicyShort(schema))}
-    ${format(createIndexJobPolicySingleton(schema))}
-    ${format(createIndexJobPolicyStately(schema))}
-    ${format(createIndexJobPolicyExclusive(schema))}
-    ${format(createIndexJobThrottle(schema))}
-    ${format(createIndexJobFetch(schema))}
+function createTableJobCommon(schema) {
+    return `
+    CREATE TABLE ${schema}.${COMMON_JOB_TABLE} (LIKE ${schema}.job INCLUDING GENERATED INCLUDING DEFAULTS);
 
-    ALTER TABLE ${schema}.job ATTACH PARTITION ${schema}.${table} DEFAULT;
+    SELECT ${schema}.job_table_run($cmd$${createPrimaryKeyJob(schema)}$cmd$, '${COMMON_JOB_TABLE}');
+    SELECT ${schema}.job_table_run($cmd$${createQueueForeignKeyJob(schema)}$cmd$, '${COMMON_JOB_TABLE}');
+    SELECT ${schema}.job_table_run($cmd$${createQueueForeignKeyJobDeadLetter(schema)}$cmd$, '${COMMON_JOB_TABLE}');
+    SELECT ${schema}.job_table_run($cmd$${createIndexJobPolicyShort(schema)}$cmd$, '${COMMON_JOB_TABLE}');
+    SELECT ${schema}.job_table_run($cmd$${createIndexJobPolicySingleton(schema)}$cmd$, '${COMMON_JOB_TABLE}');
+    SELECT ${schema}.job_table_run($cmd$${createIndexJobPolicyStately(schema)}$cmd$, '${COMMON_JOB_TABLE}');
+    SELECT ${schema}.job_table_run($cmd$${createIndexJobPolicyExclusive(schema)}$cmd$, '${COMMON_JOB_TABLE}');
+    SELECT ${schema}.job_table_run($cmd$${createIndexJobThrottle(schema)}$cmd$, '${COMMON_JOB_TABLE}');
+    SELECT ${schema}.job_table_run($cmd$${createIndexJobFetch(schema)}$cmd$, '${COMMON_JOB_TABLE}');
+    SELECT ${schema}.job_table_run($cmd$${createIndexJobGroupConcurrency(schema)}$cmd$, '${COMMON_JOB_TABLE}');
+
+    ALTER TABLE ${schema}.job ATTACH PARTITION ${schema}.${COMMON_JOB_TABLE} DEFAULT;
   `;
 }
 function createQueueFunction(schema) {
@@ -248,22 +363,23 @@ function createQueueFunction(schema) {
       END IF;
 
       EXECUTE format('CREATE TABLE ${schema}.%I (LIKE ${schema}.job INCLUDING DEFAULTS)', tablename);
-      
-      EXECUTE format('${formatPartitionCommand(createPrimaryKeyJob(schema))}', tablename);
-      EXECUTE format('${formatPartitionCommand(createQueueForeignKeyJob(schema))}', tablename);
-      EXECUTE format('${formatPartitionCommand(createQueueForeignKeyJobDeadLetter(schema))}', tablename);
 
-      EXECUTE format('${formatPartitionCommand(createIndexJobFetch(schema))}', tablename);
-      EXECUTE format('${formatPartitionCommand(createIndexJobThrottle(schema))}', tablename);
-      
+      EXECUTE ${schema}.job_table_format($cmd$${createPrimaryKeyJob(schema)}$cmd$, tablename);
+      EXECUTE ${schema}.job_table_format($cmd$${createQueueForeignKeyJob(schema)}$cmd$, tablename);
+      EXECUTE ${schema}.job_table_format($cmd$${createQueueForeignKeyJobDeadLetter(schema)}$cmd$, tablename);
+
+      EXECUTE ${schema}.job_table_format($cmd$${createIndexJobFetch(schema)}$cmd$, tablename);
+      EXECUTE ${schema}.job_table_format($cmd$${createIndexJobThrottle(schema)}$cmd$, tablename);
+      EXECUTE ${schema}.job_table_format($cmd$${createIndexJobGroupConcurrency(schema)}$cmd$, tablename);
+
       IF options->>'policy' = 'short' THEN
-        EXECUTE format('${formatPartitionCommand(createIndexJobPolicyShort(schema))}', tablename);
+        EXECUTE ${schema}.job_table_format($cmd$${createIndexJobPolicyShort(schema)}$cmd$, tablename);
       ELSIF options->>'policy' = 'singleton' THEN
-        EXECUTE format('${formatPartitionCommand(createIndexJobPolicySingleton(schema))}', tablename);
+        EXECUTE ${schema}.job_table_format($cmd$${createIndexJobPolicySingleton(schema)}$cmd$, tablename);
       ELSIF options->>'policy' = 'stately' THEN
-        EXECUTE format('${formatPartitionCommand(createIndexJobPolicyStately(schema))}', tablename);
+        EXECUTE ${schema}.job_table_format($cmd$${createIndexJobPolicyStately(schema)}$cmd$, tablename);
       ELSIF options->>'policy' = 'exclusive' THEN
-        EXECUTE format('${formatPartitionCommand(createIndexJobPolicyExclusive(schema))}', tablename);
+        EXECUTE ${schema}.job_table_format($cmd$${createIndexJobPolicyExclusive(schema)}$cmd$, tablename);
       END IF;
 
       EXECUTE format('ALTER TABLE ${schema}.%I ADD CONSTRAINT cjc CHECK (name=%L)', tablename, queue_name);
@@ -273,12 +389,6 @@ function createQueueFunction(schema) {
     LANGUAGE plpgsql;
   `;
 }
-function formatPartitionCommand(command) {
-    return command
-        .replace('.job', '.%1$I')
-        .replace('job_i', '%1$s_i')
-        .replaceAll("'", "''");
-}
 function deleteQueueFunction(schema) {
     return `
     CREATE FUNCTION ${schema}.delete_queue(queue_name text)
@@ -340,6 +450,9 @@ function createIndexJobFetch(schema) {
 function createIndexJobPolicyExclusive(schema) {
     return `CREATE UNIQUE INDEX job_i6 ON ${schema}.job (name, COALESCE(singleton_key, '')) WHERE state <= '${JOB_STATES.active}' AND policy = '${QUEUE_POLICIES.exclusive}'`;
 }
+function createIndexJobGroupConcurrency(schema) {
+    return `CREATE INDEX job_i7 ON ${schema}.job (name, group_id) WHERE state = '${JOB_STATES.active}' AND group_id IS NOT NULL`;
+}
 function trySetQueueMonitorTime(schema, queues, seconds) {
     return trySetQueueTimestamp(schema, queues, 'monitor_on', seconds);
 }
@@ -349,6 +462,9 @@ function trySetQueueDeletionTime(schema, queues, seconds) {
 function trySetCronTime(schema, seconds) {
     return trySetTimestamp(schema, 'cron_on', seconds);
 }
+function trySetBamTime(schema, seconds) {
+    return trySetTimestamp(schema, 'bam_on', seconds);
+}
 function trySetTimestamp(schema, column, seconds) {
     return `
     UPDATE ${schema}.version
@@ -507,34 +623,133 @@ function versionTableExists(schema) {
 function insertVersion(schema, version) {
     return `INSERT INTO ${schema}.version(version) VALUES ('${version}')`;
 }
-function fetchNextJob({ schema, table, name, policy, limit, includeMetadata, priority = true, ignoreStartAfter = false, ignoreSingletons = null }) {
-    const singletonFetch = limit > 1 && (policy === QUEUE_POLICIES.singleton || policy === QUEUE_POLICIES.stately);
-    const cte = singletonFetch ? 'grouped' : 'next';
+function buildFetchParams(options) {
+    const { ignoreSingletons, ignoreGroups, groupConcurrency } = options;
     const hasIgnoreSingletons = ignoreSingletons != null && ignoreSingletons.length > 0;
+    const hasIgnoreGroups = ignoreGroups != null && ignoreGroups.length > 0;
+    const hasGroupConcurrency = groupConcurrency != null;
+    const groupConcurrencyConfig = hasGroupConcurrency
+        ? (typeof groupConcurrency === 'number' ? { default: groupConcurrency } : groupConcurrency)
+        : null;
+    const hasTiers = groupConcurrencyConfig?.tiers && Object.keys(groupConcurrencyConfig.tiers).length > 0;
+    const values = [];
+    let paramIndex = 0;
+    let ignoreSingletonsParam = '';
+    let ignoreGroupsParam = '';
+    let defaultGroupLimitParam = '';
+    let tiersParam = '';
+    if (hasIgnoreSingletons) {
+        paramIndex++;
+        ignoreSingletonsParam = `$${paramIndex}::text[]`;
+        values.push(ignoreSingletons);
+    }
+    if (hasIgnoreGroups) {
+        paramIndex++;
+        ignoreGroupsParam = `$${paramIndex}::text[]`;
+        values.push(ignoreGroups);
+    }
+    if (hasGroupConcurrency && groupConcurrencyConfig) {
+        paramIndex++;
+        defaultGroupLimitParam = `$${paramIndex}::int`;
+        values.push(groupConcurrencyConfig.default);
+        if (hasTiers) {
+            paramIndex++;
+            tiersParam = `$${paramIndex}::jsonb`;
+            values.push(JSON.stringify(groupConcurrencyConfig.tiers));
+        }
+    }
+    return { values, ignoreSingletonsParam, ignoreGroupsParam, defaultGroupLimitParam, tiersParam };
+}
+function fetchNextJob(options) {
+    const { schema, table, name, policy, limit, includeMetadata, priority = true, orderByCreatedOn = true, ignoreStartAfter = false, groupConcurrency } = options;
+    const singletonFetch = limit > 1 && (policy === QUEUE_POLICIES.singleton || policy === QUEUE_POLICIES.stately);
+    const hasIgnoreSingletons = options.ignoreSingletons != null && options.ignoreSingletons.length > 0;
+    const hasIgnoreGroups = options.ignoreGroups != null && options.ignoreGroups.length > 0;
+    const hasGroupConcurrency = groupConcurrency != null;
+    const hasTiers = hasGroupConcurrency &&
+        typeof groupConcurrency === 'object' &&
+        groupConcurrency.tiers &&
+        Object.keys(groupConcurrency.tiers).length > 0;
+    const params = buildFetchParams(options);
+    const whereConditions = [
+        `name = '${name}'`,
+        `state < '${JOB_STATES.active}'`,
+        !ignoreStartAfter ? 'start_after < now()' : '',
+        hasIgnoreSingletons ? `singleton_key <> ALL(${params.ignoreSingletonsParam})` : '',
+        hasIgnoreGroups ? `(group_id IS NULL OR group_id <> ALL(${params.ignoreGroupsParam}))` : ''
+    ].filter(Boolean).join(' AND ');
+    const selectCols = [
+        'id',
+        singletonFetch ? 'singleton_key' : '',
+        hasGroupConcurrency ? 'group_id, group_tier' : ''
+    ].filter(Boolean).join(', ');
+    const activeGroupCountsCte = hasGroupConcurrency
+        ? `active_group_counts AS (
+        SELECT group_id, COUNT(*)::int as active_cnt
+        FROM ${schema}.${table}
+        WHERE name = '${name}' AND state = '${JOB_STATES.active}' AND group_id IS NOT NULL
+        GROUP BY group_id
+      ), `
+        : '';
+    const nextCte = `
+      next AS (
+        SELECT ${selectCols}
+        FROM ${schema}.${table}
+        WHERE ${whereConditions}
+        ORDER BY ${priority ? 'priority desc, ' : ''}${orderByCreatedOn ? 'created_on, ' : ''}id
+        LIMIT ${limit}
+        FOR UPDATE SKIP LOCKED
+      )`;
+    const singletonCte = singletonFetch
+        ? `, singleton_ranking AS (
+        SELECT id, ${hasGroupConcurrency ? 'group_id, group_tier, ' : ''}
+          row_number() OVER (PARTITION BY singleton_key) as singleton_rn
+        FROM next
+      )`
+        : '';
+    const groupConcurrencyCtes = hasGroupConcurrency
+        ? `,
+      group_ranking AS (
+        SELECT t.id
+          , t.group_id
+          , t.group_tier
+          ${singletonFetch ? ', singleton_rn' : ''}
+          , ROW_NUMBER() OVER (PARTITION BY t.group_id ORDER BY t.id) as group_rn
+          , COALESCE(agc.active_cnt, 0) as active_cnt
+        FROM ${singletonFetch ? 'singleton_ranking' : 'next'} t
+        LEFT JOIN active_group_counts agc ON t.group_id = agc.group_id
+        ${singletonFetch ? 'WHERE singleton_rn = 1' : ''}
+      ),
+      group_filtered AS (
+        SELECT id FROM group_ranking
+        WHERE group_id IS NULL
+          OR (active_cnt + group_rn) <= ${hasTiers
+            ? `COALESCE((${params.tiersParam} ->> group_tier)::int, ${params.defaultGroupLimitParam})`
+            : params.defaultGroupLimitParam}
+      )`
+        : '';
+    const finalCte = (hasGroupConcurrency)
+        ? 'group_filtered'
+        : (singletonFetch)
+            ? 'singleton_ranking'
+            : 'next';
     return {
         text: `
-    WITH next as (
-      SELECT id ${singletonFetch ? ', singleton_key' : ''}
-      FROM ${schema}.${table}
-      WHERE name = '${name}'
-        AND state < '${JOB_STATES.active}'
-        ${ignoreStartAfter ? '' : 'AND start_after < now()'}
-        ${hasIgnoreSingletons ? 'AND singleton_key <> ALL($1::text[])' : ''}
-      ORDER BY ${priority ? 'priority desc, ' : ''}created_on, id
-      LIMIT ${limit}
-      FOR UPDATE SKIP LOCKED
-    )
-    ${singletonFetch ? ', grouped as ( SELECT id, row_number() OVER (PARTITION BY singleton_key) FROM next)' : ''}
-    UPDATE ${schema}.${table} j SET
-      state = '${JOB_STATES.active}',
-      started_on = now(),
-      retry_count = CASE WHEN started_on IS NOT NULL THEN retry_count + 1 ELSE retry_count END
-    FROM ${cte}
-    WHERE name = '${name}' AND j.id = ${cte}.id
-      ${singletonFetch ? ` AND ${cte}.row_number = 1` : ''}
-    RETURNING j.${includeMetadata ? JOB_COLUMNS_ALL : JOB_COLUMNS_MIN}
-  `,
-        values: hasIgnoreSingletons ? [ignoreSingletons] : []
+      WITH
+      ${activeGroupCountsCte}
+      ${nextCte}
+      ${singletonCte}
+      ${groupConcurrencyCtes}
+      UPDATE ${schema}.${table} j SET
+        state = '${JOB_STATES.active}',
+        started_on = now(),
+        retry_count = CASE WHEN started_on IS NOT NULL THEN retry_count + 1 ELSE retry_count END
+      FROM ${finalCte}
+      WHERE name = '${name}' AND j.id = ${finalCte}.id
+      ${singletonFetch && !hasGroupConcurrency ? 'AND singleton_rn = 1' : ''}
+      RETURNING j.${includeMetadata ? JOB_COLUMNS_ALL : JOB_COLUMNS_MIN}
+    `,
+        values: params.values
     };
 }
 function completeJobs(schema, table) {
@@ -580,6 +795,14 @@ function resumeJobs(schema, table) {
     SELECT COUNT(*) from results
   `;
 }
+function restoreJobs(schema, table) {
+    return `
+    UPDATE ${schema}.${table}
+    SET state = '${JOB_STATES.created}'
+    WHERE name = $1
+      AND id IN (SELECT UNNEST($2::uuid[]))
+  `;
+}
 function insertJobs(schema, { table, name, returnId = true }) {
     const sql = `
     INSERT INTO ${schema}.${table} (
@@ -590,6 +813,8 @@ function insertJobs(schema, { table, name, returnId = true }) {
       start_after,
       singleton_key,
       singleton_on,
+      group_id,
+      group_tier,
       expire_seconds,
       deletion_seconds,
       keep_until,
@@ -611,6 +836,8 @@ function insertJobs(schema, { table, name, returnId = true }) {
         WHEN "singletonSeconds" IS NOT NULL THEN 'epoch'::timestamp + '1s'::interval * ("singletonSeconds" * floor(( date_part('epoch', now()) + COALESCE("singletonOffset",0)) / "singletonSeconds" ))
         ELSE NULL
         END as singleton_on,
+      "groupId" as group_id,
+      "groupTier" as group_tier,
       COALESCE("expireInSeconds", q.expire_seconds) as expire_seconds,
       COALESCE("deleteAfterSeconds", q.deletion_seconds) as deletion_seconds,
       j.start_after + (COALESCE("retentionSeconds", q.retention_seconds) * interval '1s') as keep_until,
@@ -638,10 +865,12 @@ function insertJobs(schema, { table, name, returnId = true }) {
         "singletonKey" text,
         "singletonSeconds" integer,
         "singletonOffset" integer,
+        "groupId" text,
+        "groupTier" text,
         "expireInSeconds" integer,
         "deleteAfterSeconds" integer,
         "retentionSeconds" integer
-      ) 
+      )
     ) j
     JOIN ${schema}.queue q ON q.name = '${name}'
     ON CONFLICT DO NOTHING
@@ -684,6 +913,8 @@ function failJobs(schema, table, where, output) {
         started_on,
         singleton_key,
         singleton_on,
+        group_id,
+        group_tier,
         expire_seconds,
         deletion_seconds,
         created_on,
@@ -711,7 +942,7 @@ function failJobs(schema, table, where, output) {
              WHEN NOT retry_backoff THEN now() + retry_delay * interval '1'
              ELSE now() + LEAST(
                retry_delay_max,
-               retry_delay + (
+               retry_delay * (
                 2 ^ LEAST(16, retry_count + 1) / 2 +
                 2 ^ LEAST(16, retry_count + 1) / 2 * random()
                )
@@ -720,6 +951,8 @@ function failJobs(schema, table, where, output) {
         started_on,
         singleton_key,
         singleton_on,
+        group_id,
+        group_tier,
         expire_seconds,
         deletion_seconds,
         created_on,
@@ -748,6 +981,8 @@ function failJobs(schema, table, where, output) {
         started_on,
         singleton_key,
         singleton_on,
+        group_id,
+        group_tier,
         expire_seconds,
         deletion_seconds,
         created_on,
@@ -772,6 +1007,8 @@ function failJobs(schema, table, where, output) {
         started_on,
         singleton_key,
         singleton_on,
+        group_id,
+        group_tier,
         expire_seconds,
         deletion_seconds,
         created_on,
@@ -813,7 +1050,7 @@ function deletion(schema, table, queues) {
     WHERE name = ANY(${serializeArrayParam(queues)})
       AND
       (
-        completed_on + deletion_seconds * interval '1s' < now()
+        (deletion_seconds > 0 AND completed_on + deletion_seconds * interval '1s' < now())
         OR
         (state < '${JOB_STATES.active}' AND keep_until < now())
       )
@@ -901,7 +1138,83 @@ function assertMigration(schema, version) {
     // raises 'division by zero' if already on desired schema version
     return `SELECT version::int/(version::int-${version}) from ${schema}.version`;
 }
+function findJobs(schema, table, options) {
+    const { queued, byKey, byData, byId } = options;
+    let paramIndex = 1;
+    const whereConditions = [];
+    if (byId) {
+        ++paramIndex;
+        whereConditions.push(`AND id = $${paramIndex}`);
+    }
+    if (byKey) {
+        ++paramIndex;
+        whereConditions.push(`AND singleton_key = $${paramIndex}`);
+    }
+    if (byData) {
+        ++paramIndex;
+        whereConditions.push(`AND data @> $${paramIndex}`);
+    }
+    if (queued) {
+        whereConditions.push(`AND state < '${JOB_STATES.active}'`);
+    }
+    return `
+    SELECT ${JOB_COLUMNS_ALL}
+    FROM ${schema}.${table}
+    WHERE name = $1
+      ${whereConditions.join('\n      ')}
+    `;
+}
 function getJobById(schema, table) {
-    return `SELECT ${JOB_COLUMNS_ALL} FROM ${schema}.${table} WHERE name = $1 AND id = $2`;
+    return `
+    SELECT ${JOB_COLUMNS_ALL}
+    FROM ${schema}.${table}
+    WHERE name = $1
+      AND id = $2
+    `;
+}
+function getNextBamCommand(schema) {
+    return `
+    UPDATE ${schema}.bam
+    SET status = 'in_progress', started_on = now()
+    WHERE id = (
+      SELECT id FROM ${schema}.bam
+      WHERE status IN ('pending', 'failed')
+        AND NOT EXISTS (SELECT 1 FROM ${schema}.bam WHERE status = 'in_progress')
+      ORDER BY created_on
+      LIMIT 1
+    )
+    RETURNING id, name, version, status, queue, table_name as "table", command, error,
+              created_on as "createdOn", started_on as "startedOn", completed_on as "completedOn"
+  `;
+}
+function setBamCompleted(schema, id) {
+    return `
+    UPDATE ${schema}.bam
+    SET status = 'completed', completed_on = now()
+    WHERE id = '${id}'
+  `;
+}
+function setBamFailed(schema, id, error) {
+    const escapedError = error.replace(/'/g, "''");
+    return `
+    UPDATE ${schema}.bam
+    SET status = 'failed', error = '${escapedError}', completed_on = now()
+    WHERE id = '${id}'
+  `;
+}
+function getBamStatus(schema) {
+    return `
+    SELECT status, count(*)::int as count, max(created_on) as "lastCreatedOn"
+    FROM ${schema}.bam
+    GROUP BY status
+  `;
+}
+function getBamEntries(schema) {
+    return `
+    SELECT id, name, version, status, queue, table_name as "table", command, error,
+           created_on as "createdOn", started_on as "startedOn", completed_on as "completedOn"
+    FROM ${schema}.bam
+    ORDER BY version, created_on
+  `;
 }
-export { create, insertVersion, getVersion, setVersion, versionTableExists, fetchNextJob, completeJobs, cancelJobs, resumeJobs, retryJobs, deleteJobsById, deleteAllJobs, deleteQueuedJobs, deleteStoredJobs, truncateTable, failJobsById, failJobsByTimeout, insertJobs, getTime, getSchedules, getSchedulesByQueue, schedule, unschedule, subscribe, unsubscribe, getQueuesForEvent, deletion, cacheQueueStats, updateQueue, createQueue, deleteQueue, getQueues, getQueueStats, trySetQueueMonitorTime, trySetQueueDeletionTime, trySetCronTime, locked, assertMigration, getJobById, QUEUE_POLICIES, JOB_STATES, MIGRATE_RACE_MESSAGE, CREATE_RACE_MESSAGE, DEFAULT_SCHEMA, };
+export { create, insertVersion, getVersion, setVersion, versionTableExists, fetchNextJob, completeJobs, cancelJobs, resumeJobs, restoreJobs, retryJobs, findJobs, deleteJobsById, deleteAllJobs, deleteQueuedJobs, deleteStoredJobs, truncateTable, failJobsById, failJobsByTimeout, insertJobs, getTime, getSchedules, getSchedulesByQueue, schedule, unschedule, subscribe, unsubscribe, getQueuesForEvent, deletion, cacheQueueStats, updateQueue, createQueue, deleteQueue, getQueues, getQueueStats, trySetQueueMonitorTime, trySetQueueDeletionTime, trySetCronTime, trySetBamTime, locked, assertMigration, getJobById, getNextBamCommand, setBamCompleted, setBamFailed, getBamStatus, getBamEntries, QUEUE_POLICIES, JOB_STATES, MIGRATE_RACE_MESSAGE, CREATE_RACE_MESSAGE, DEFAULT_SCHEMA, };