Inserts a job into the queue.

Returns the inserted job with database-generated fields populated.

Ordering and concurrency

Standalone (ungrouped) jobs are claimed in (priority ASC, id ASC) order. Grouped jobs are claimed one-per-group, with the head of each group chosen by (attempts DESC, priority ASC, id ASC). The attempts DESC prefix prioritises a chronically-failing job so it either succeeds or reaches maxAttempts and moves to the DLQ, rather than starving fresh jobs behind it indefinitely. Concurrent inserts to the same group are serialized at the trigger level: the AFTER INSERT trigger's ON CONFLICT DO UPDATE on the groups table takes a row-level lock, preventing out-of-order commits within a group.

Deduplication

• Nothing: Always insert (dedup_key is NULL)
• Just (IgnoreDuplicate k): Skip if dedup_key exists, return Nothing
• Just (ReplaceDuplicate k): Replace existing job unless actively in-flight on its first attempt. Returns Nothing only when attempts > 0, not_visible_until > NOW(), and last_error IS NULL (i.e., the job is being processed for the first time). Jobs that have previously failed (last_error IS NOT NULL) can always be replaced, even if currently in-flight on a retry attempt - this is by design, so that a fresh replacement takes priority over a failing job.

parentId is validated: if set to a non-existent job ID, returns Nothing. For building parent-child trees, prefer insertJobTree which handles parentId, isRollup, and suspended atomically.

Insert a job without validating that the parent exists.

This is an internal fast path for callers that already guarantee the parent is present (e.g. insertJobTree). External callers should use insertJob which validates the parent first.

Insert multiple jobs in a single batch operation.

Supports dedup keys: IgnoreDuplicate jobs are silently skipped on conflict, ReplaceDuplicate jobs update the existing row (unless actively in-flight). Only actually inserted or replaced jobs are returned.

If multiple jobs in the batch share the same dedup key, only the last occurrence is kept (last writer wins), consistent with sequential insertJob calls.

Does not validate parentId - callers must ensure referenced parents exist. For parent-child trees, use insertJobTree instead.

Insert a child's result into the results table.

Each child gets its own row keyed by (parent_id, child_id). The FK ON DELETE CASCADE ensures cleanup when the parent is acked.

Returns the number of rows inserted (1 on success).

Get all child results for a parent from the results table.

Returns a Map from child ID to the result Value.

Get DLQ child errors for a parent.

Returns a Map from child job ID to the last error message.

Snapshot results into parent_state before DLQ move.

Claim up to maxJobs visible jobs, respecting head-of-line blocking (one job per group). Uses a single-CTE claim with the groups table.

Batched variant of claimNextVisibleJobs - claims up to batchSize jobs per group, across up to maxBatches groups.

Acknowledge a job as completed (smart ack).

Deletes standalone jobs; suspends parents waiting for children; wakes parents when the last sibling completes. Uses an advisory lock for child jobs to serialize with concurrent sibling acks.

Returns 1 on success, 0 if the job was already gone.

Acknowledge multiple jobs as completed.

Iterates calling ackJob so every job gets smart-ack treatment (parent suspend/wake logic). Returns the total number of rows affected.

Bulk ack for standalone jobs (no parent, no tree logic).

A single DELETE with unnest - one round trip for N jobs. Only valid for jobs claimed in BatchedJobsMode, which guarantees parent_id IS NULL AND parent_state IS NULL.

Returns the number of rows deleted.

Set the visibility timeout for a job

Batch variant of setVisibilityTimeout. Returns per-job status (success, acked, or stolen).

Detailed information about the result of a visibility update operation for a single job.

Update a job for retry with backoff and error tracking

Returns the number of rows updated (0 if job was already claimed by another worker).

Move a job to the DLQ. Cascades descendants for rollup parents. Wakes the parent if this was a child job.

Returns 0 if the job was already claimed by another worker.

Moves multiple jobs from the main queue to the dead-letter queue.

Each job is moved with its own error message. Jobs that have already been claimed by another worker (attempts mismatch) are silently skipped.

Returns the total number of jobs moved to DLQ.

Retry a job from the DLQ (re-inserts with attempts reset to 0). The dedup_key is NOT restored - retried jobs won't conflict with new dedup inserts.

Check whether a DLQ job exists by ID.

List jobs in the dead letter queue

Returns jobs ordered by failed_at (most recent first).

List DLQ jobs filtered by parent_id.

Returns jobs ordered by failed_at (most recent first).

Count DLQ jobs matching a parent_id.

Delete a job from the DLQ. If the job was a child, tries to resume the parent when no siblings remain.

Delete multiple jobs from the dead letter queue.

If any deleted jobs were children, tries to resume their parents when no siblings remain. Parent IDs are deduplicated and sorted to prevent deadlocks between concurrent batch deletes.

Returns the total number of DLQ jobs deleted.

Filter predicates for job listing queries.

List jobs with composable filters.

Returns jobs ordered by ID (descending, newest first).

List jobs with composable filters and an explicit sort spec.

Nothing for both sort args yields the default ordering (id DESC).

Count jobs with composable filters.

List DLQ jobs with composable filters.

Returns jobs ordered by failed_at (most recent first).

List DLQ jobs with composable filters and an explicit sort spec.

Nothing for both sort args yields the default ordering (failed_at DESC).

Count DLQ jobs with composable filters.

List jobs in the queue with pagination.

Returns jobs ordered by ID (descending).

Get a single job by its ID

Get a single job by its dedup key.

Get all jobs for a specific group key.

Cancels (deletes) a job by ID.

Returns 0 if the job has children - use cancelJobCascade to delete a parent and all its descendants.

If the deleted job was a child and no siblings remain, the parent is resumed for its completion round.

Cancels (deletes) multiple jobs by ID.

Each job gets full wake-parent logic (same as cancelJob). Wrapped in a transaction so that cancelling multiple children of the same parent sees a consistent view - the last cancel's CTE correctly detects no remaining siblings and resumes the parent. Returns the total number of jobs deleted.

Promote a delayed or retrying job to be immediately visible.

Refuses in-flight jobs (attempts > 0 with no last_error). Returns 1 on success, 0 if not found, already visible, or in-flight.

Statistics about the job queue

Get statistics about the job queue

Count all jobs in a table

Count jobs matching a group key

Count DLQ jobs

List jobs filtered by parent_id with pagination.

Count jobs matching a parent_id.

Count children for a batch of potential parent IDs.

Returns a Map from parent_id to (total, paused) counts (only non-zero entries).

Count children in the DLQ for a batch of potential parent IDs.

Returns a Map from parent_id to DLQ child count (only non-zero entries).

Pause all visible children of a parent job.

Sets suspended = TRUE for claimable children, making them unclaimable. In-flight children (currently being processed by workers) are left alone so their visibility timeout can expire normally if the worker crashes. Returns the number of children paused.

Resume all suspended children of a parent job.

Only affects children whose suspended = TRUE. Returns the number of children resumed.

Cancel a job and all its descendants recursively.

Uses a recursive CTE to find all descendants and deletes them all. If the root job itself is a child, resumes its parent for a completion round. Returns the total number of jobs deleted (parent + all descendants).

Cancel an entire job tree by walking up from any node to the root, then cascade-deleting everything from the root down.

Unlike cancelJobCascade, this does NOT call tryResumeParent - the root by definition has no parent. Returns the total number of jobs deleted.

Suspend a job, making it unclaimable.

Only suspends non-in-flight jobs (not currently being processed by workers). Returns the number of rows updated (0 if job doesn't exist, is in-flight, or already suspended).

Resume a suspended job, making it claimable again.

Returns the number of rows updated (0 if job doesn't exist or isn't suspended).

Full recompute of the groups table from the main queue.

Corrects any drift in job_count, min_priority, min_id, and in_flight_until. Checks the reaper sequence to skip if a recent run occurred within the given interval. Uses an advisory lock to serialize concurrent attempts, then locks all groups rows to prevent trigger interleaving.

Upsert a cron schedule's default expression and overlap policy.

Preserves user overrides and enabled state.

List all cron schedules ordered by name.

Get a single cron schedule by name.

Update a cron schedule (patch semantics).

Returns the number of rows affected (0 = not found, 1 = updated).

Delete schedules whose names are not in the given list.

Returns the number of rows deleted. Does nothing if the list is empty.

Update last_fired_at to NOW() for a cron schedule.

Advance last_checked_at to the supplied watermark for the given cron schedule names. The watermark must be the minute boundary the scheduler finished evaluating, not NOW(). A wrapping GREATEST in the SQL keeps the column monotonic when concurrent worker pools race.

Claim a minute floor for a schedule. True = caller proceeds with the insert. False = another pool already fired this minute, skip.

Try to acquire the (schema, name) cron leader lock. Must be inside a transaction.

Read the raw parent_state snapshot from the DB.

Internal operation used by the worker for DLQ-retried finalizers that have a persisted snapshot.

Read child results, DLQ errors, parent_state snapshot, and DLQ failures for a rollup finalizer in a single query.

Merge raw child results from three sources.

Precedence (left-biased union): DLQ errors > results > snapshot.