Crate graphile_worker 

Graphile Worker RS

A PostgreSQL-backed job queue for Rust applications, based on Graphile Worker.

Graphile Worker RS lets you run durable background jobs from Rust while keeping PostgreSQL as the queue and coordination backend. It supports typed task handlers, delayed jobs, priorities, queues, retries, cron jobs, graceful shutdown, optional dead-worker recovery, lifecycle hooks, CLI tooling, and an admin UI.

Documentation

• Guide - task-oriented documentation, examples, configuration, operations, and troubleshooting.
• API reference - generated Rust API docs.
• Examples - runnable repository examples.

Installation

cargo add graphile_worker

Tokio, rustls, and SQLx are enabled by default:

[dependencies]
graphile_worker = "0.13"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
serde = { version = "1", features = ["derive"] }

For async-std, tokio-postgres, native TLS, or OpenTelemetry compatibility features, see the feature flags guide.

Quick Start

use graphile_worker::{
    IntoTaskHandlerResult, JobSpec, TaskHandler, WorkerContext, WorkerOptions,
};
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize)]
struct SendEmail {
    to: String,
}

impl TaskHandler for SendEmail {
    const IDENTIFIER: &'static str = "send_email";

    async fn run(self, _ctx: WorkerContext) -> impl IntoTaskHandlerResult {
        println!("Sending email to {}", self.to);
        Ok::<(), String>(())
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let worker = WorkerOptions::default()
        .database_url("postgres://postgres:password@localhost/mydb")
        .concurrency(5)
        .schema("graphile_worker")
        .define_job::<SendEmail>()
        .init()
        .await?;

    worker
        .create_utils()
        .add_job(
            SendEmail {
                to: "user@example.com".to_string(),
            },
            JobSpec::default(),
        )
        .await?;

    worker.run().await?;
    Ok(())
}

For a complete walkthrough, read Quick Start and First Worker.

Highlights

• PostgreSQL-backed durable queue with SKIP LOCKED job claiming.
• Low-latency wakeups through PostgreSQL LISTEN/NOTIFY.
• Typed Rust task handlers and batch task handlers.
• Delayed jobs, priorities, retry attempts, job keys, and named queues.
• Cron-like recurring jobs through the crontab crates.
• Worker utilities for adding, rescheduling, completing, failing, cleaning up, and recovering jobs.
• Optional local queue for batch-fetching jobs and reducing database round trips.
• Graceful shutdown and optional heartbeat-based dead-worker recovery.
• Lifecycle hooks for logging, metrics, validation, and custom policies.
• CLI and admin UI crates for operational workflows.

Compatibility

This is a Rust rewrite of Graphile Worker. It is mostly compatible with the Node.js version and can run side by side with it when the shared PostgreSQL schema and job contracts match.

One notable implementation difference: the Node.js version uses one worker id per process, while this Rust implementation uses one worker id per worker instance and processes jobs through the enabled async runtime.

See Compatibility for details.

Development

Common commands:

just lint
just test-docker
just docs
just docs-serve 3002

Before committing, run:

just lint
just test-docker

See CONTRIBUTING.md for contribution details.

License

MIT. See LICENSE.md.

Graphile Worker RS

A PostgreSQL-backed job queue implementation for Rust applications. This crate is a Rust port of the Node.js Graphile Worker library.

Architecture Overview

Graphile Worker uses PostgreSQL as its backend for job storage and coordination. The system consists of several key components:

• Worker: Processes jobs from the queue using the specified concurrency.
• WorkerUtils: Utility functions for job management (adding, removing, rescheduling, etc.).
• TaskHandler: Trait that defines how specific job types are processed.
• Job Specification: Configures job parameters like priority, retry behavior, and scheduling.
• Migrations: Automatic schema management for the database tables.

Database Schema

Graphile Worker manages its own database schema (default: graphile_worker). It automatically handles migrations and uses the following tables:

• _private_jobs: Stores job data, state, and execution metadata
• _private_tasks: Tracks registered task types
• _private_job_queues: Manages job queue names for serialized job execution
• _private_workers: Tracks active worker instances

Module Structure

The crate is organized into the following modules:

Re-exports

pub use cron::Cron;

pub use cron::CronBuilder;

pub use builder::CronInput;

pub use builder::WorkerBuildError;

pub use builder::WorkerOptions;

pub use context_ext::WorkerContextExt;

pub use local_queue::LocalQueue;

pub use local_queue::LocalQueueConfig;

pub use local_queue::LocalQueueError;

pub use local_queue::LocalQueueSignalSender;

pub use local_queue::RefetchDelayConfig;

pub use runner::Worker;

Modules

builder

Configuration and initialization of worker instances

context_ext

cron

errors

Error types used throughout the crate

local_queue

LocalQueue for batch-fetching jobs to improve throughput

recovery

Dead worker recovery

row_mapping

runner

Core worker implementation for running the job queue

sql

SQL query implementations for interacting with the database

sqlx

streams

Job stream management for processing jobs

worker_utils

Utility functions for job management Utility functions for adding, managing, and maintaining jobs.

Structs

ActiveWorkerRow

AfterJobRun

AfterJobRunContext

BeforeJobRun

BeforeJobRunContext

BeforeJobSchedule

BeforeJobScheduleContext

CronJobScheduled

CronJobScheduledContext

CronTick

CronTickContext

Crontab

A crontab defines a task to be executed at a specific time(s)

CrontabFill

A crontab fill represents how long a crontab should be backfilled For instance the server is down for 1 hour, the task should be backfilled for 1 hour

CrontabTimer

A crontab timer is a set of crontab values for each field (minutes, hours, days, months, days of week)

Database

DbError

DbJob

DbJob represents a job as stored in the database.

DbJobData

Named field carrier for constructing a DbJob.

DbParams

DbRow

DbTransaction

HookRegistry

Job

Job extends DbJob with an additional task_identifier field.

JobBuilder

Builder for Job.

JobComplete

JobCompleteContext

JobDefinition

Reusable registration value for a TaskHandler.

JobFail

JobFailContext

JobFetch

JobFetchContext

JobInterrupted

JobInterruptedContext

JobPermanentlyFail

JobPermanentlyFailContext

JobRecovery

JobRecoveryContext

JobSpec

JobSpecBuilder

Builder for JobSpec.

JobStart

JobStartContext

LocalQueueGetJobsComplete

LocalQueueGetJobsCompleteContext

LocalQueueInit

LocalQueueInitContext

LocalQueueRefetchDelayAbort

LocalQueueRefetchDelayAbortContext

LocalQueueRefetchDelayExpired

LocalQueueRefetchDelayExpiredContext

LocalQueueRefetchDelayStart

LocalQueueRefetchDelayStartContext

LocalQueueReturnJobs

LocalQueueReturnJobsContext

LocalQueueSetMode

LocalQueueSetModeContext

Notification

RawJobSpec

Schema

SharedTaskDetails

SweepStaleWorkersOptions

SweepStaleWorkersResult

TaskDetails

WorkerContext

Context provided to task handlers when processing a job.

WorkerContextBuilder

WorkerInit

WorkerInitContext

WorkerRecovered

WorkerRecoveredContext

WorkerRecoveryConfig

Dead worker recovery configuration.

WorkerShutdown

WorkerShutdownConfig

Worker shutdown behavior.

WorkerShutdownContext

WorkerStart

WorkerStartContext

WorkerUtils

The WorkerUtils struct provides a set of utility methods for managing jobs.

Enums

BatchTaskResult

Result returned by a batch task handler.

CronJobKeyMode

Behavior when an existing job with the same job key is found is controlled by this setting

CrontabField

Crontab time fields used for validating typed schedule construction.

CrontabTimerError

Error returned when typed schedule constructors receive invalid values.

CrontabValue

A crontab value can be a number, a range, a step or any value It is used to represent a crontab value for a specific field (hour, day, month, etc.) When specifying a specific number, range or step, it should be valid for the field (e.g. 0-59 for minutes, 0-23 for hours, etc.)

DbCell

DbValue

FailureReason

HookResult

JobKeyMode

JobRecoveryResult

JobScheduleResult

JobSpecBuilderError

Error type for JobSpecBuilder

LocalQueueMode

ShutdownReason

TaskHandlerOutcome

Outcome returned by type-erased task handlers.

Constants

INFRASTRUCTURE_RESILIENT_FLAG

Job flag indicating the job may run for a long time and should use a longer sweep threshold before being recovered from a seemingly-dead worker.

Traits

BatchTaskHandler

Core trait for defining batch task handlers.

DatabaseDriver

DbExecutor

DbExecutorArg

Event

FromDbCell

HookOutput

Interceptable

IntoBatchTaskHandlerResult

Trait for converting batch task return types into a standardized result.

IntoTaskHandlerResult

Trait for converting task handler return types into a standardized Result.

Plugin

TaskHandler

Core trait for defining task handlers in Graphile Worker.

TransactionDriver

Functions

escape_identifier

parse_crontab

Parse a crontab definition into a Vec of crontab

run_task_from_worker_ctx

Internal function to execute a task handler from a worker context.

Type Aliases

BoxFuture

NotificationStream

ShutdownSignal

A shareable future that completes when a shutdown signal is received.

TaskHandlerFn

Type-erased function used by workers to run a task from a WorkerContext.