Inserts a job into the queue.

Returns the inserted job with database-generated fields populated.

Ordering and concurrency

Jobs are claimed in ID order (lowest ID first within a priority level). 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 dead letter queue.

This permanently removes the job from the DLQ without retrying it. If the deleted job was a child, tries to resume the parent when no siblings remain in the main queue.

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).

Count jobs with composable filters.

List DLQ jobs with composable filters.

Returns jobs ordered by failed_at (most recent first).

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 all jobs for a specific group key

Useful for debugging or admin UI to see all jobs for a specific entity.

Get all in-flight jobs (currently being processed by workers)

A job is considered in-flight if it has been claimed (attempts > 0) and its visibility timeout hasn't expired yet.

Useful for monitoring active work and detecting stuck jobs.

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 in-flight jobs

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.

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.