API Reference

This page is a map of the public Rust API. For complete signatures, trait bounds, and generated item documentation, use the docs.rs links in each section.

Most applications should start with the root crate:

graphile_worker - worker setup, task registration, job scheduling, cron helpers, lifecycle hooks, shutdown, recovery, and the most commonly used re-exports.

Worker Setup

Use WorkerOptions to configure and initialize a worker, then call Worker::run or Worker::run_once.

Important public types:

WorkerOptions - builder-style worker configuration.
WorkerBuildError - initialization errors.
Worker - initialized worker runtime.
WorkerShutdownConfig - graceful shutdown behavior.
ShutdownSignal - shareable shutdown future.

Common configuration methods include:

database_url, database, and pg_pool for database connections.
schema, concurrency, poll_interval, max_pg_conn, and use_local_time.
define_job, define_batch_job, and define_jobs for task registration.
add_forbidden_flag for workers that skip jobs with specific flags.
local_queue, complete_job_batch_delay, and fail_job_batch_delay for throughput tuning.
worker_recovery, heartbeat_interval, sweep_interval, sweep_threshold, and recovery_delay for dead worker recovery.
listen_os_shutdown_signals, shutdown_signal, shutdown_grace_period, and shutdown_interrupted_job_retry_delay for shutdown control.

use graphile_worker::{
    IntoTaskHandlerResult, TaskHandler, WorkerContext, WorkerOptions,
};
use serde::{Deserialize, Serialize};
use std::time::Duration;

#[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 {
        Ok::<(), String>(())
    }
}

let worker = WorkerOptions::default()
    .database_url("postgres://postgres:postgres@localhost/postgres")
    .schema("graphile_worker")
    .concurrency(8)
    .poll_interval(Duration::from_millis(500))
    .define_job::<SendEmail>()
    .init()
    .await?;

worker.run().await?;

Task Handlers

Task handler APIs live in graphile_worker_task_handler and are re-exported by graphile_worker.

Important public types:

TaskHandler - trait for a single job payload type.
IntoTaskHandlerResult - conversion trait for task return values such as () and Result<(), E>.
BatchTaskHandler - trait for JSON-array batch payloads.
BatchTaskResult and IntoBatchTaskHandlerResult - batch completion and partial failure results.
JobDefinition - reusable task registration value.
TaskHandlerOutcome and TaskHandlerFn - type-erased handler output and function type.
run_task_from_worker_ctx - helper that deserializes and runs a TaskHandler from WorkerContext.

Batch handlers operate on Vec<Self> item payloads. BatchTaskResult::ItemResults must return one result for each input item, in the same order; failed items are retried as a replacement JSON-array payload.

use graphile_worker::{
    BatchTaskHandler, IntoBatchTaskHandlerResult, WorkerContext, WorkerOptions,
};
use serde::{Deserialize, Serialize};

#[derive(Clone, Deserialize, Serialize)]
struct IndexRecord {
    id: i64,
}

impl BatchTaskHandler for IndexRecord {
    const IDENTIFIER: &'static str = "index_record";

    async fn run_batch(
        items: Vec<Self>,
        _ctx: WorkerContext,
    ) -> impl IntoBatchTaskHandlerResult {
        let results = items
            .into_iter()
            .map(|item| {
                if item.id > 0 {
                    Ok(())
                } else {
                    Err("invalid id")
                }
            })
            .collect::<Vec<_>>();

        results
    }
}

let options = WorkerOptions::default().define_batch_job::<IndexRecord>();

Job Scheduling And Management

Use WorkerUtils to add, update, and maintain jobs without running a worker loop in the same code path.

Important public types:

WorkerUtils - client for scheduling and maintenance operations.
JobSpec and JobSpecBuilder - optional job parameters.
JobKeyMode - job-key behavior: Replace, PreserveRunAt, or UnsafeDedupe.
RawJobSpec - raw batch scheduling input.
Job, JobBuilder, DbJob, and DbJobData - job records returned by scheduling and management APIs.
CleanupTask - cleanup operations from graphile_worker_utils::types.
RescheduleJobOptions - optional fields for rescheduling jobs.

Common WorkerUtils methods include:

add_job, add_raw_job, add_jobs, add_raw_jobs, and add_batch_job.
remove_job, complete_jobs, permanently_fail_jobs, and reschedule_jobs.
list_active_workers, sweep_stale_workers, sweep_stale_workers_with_config, and force_unlock_workers.
cleanup and migrate.

use graphile_worker::{JobKeyMode, JobSpec, WorkerUtils};
use serde_json::json;

let spec = JobSpec::builder()
    .queue_name("email")
    .job_key("welcome-email:user-123")
    .job_key_mode(JobKeyMode::PreserveRunAt)
    .max_attempts(5)
    .priority(-10)
    .build();

let job = utils
    .add_raw_job(
        "send_email",
        json!({ "to": "user@example.com" }),
        spec,
    )
    .await?;

Worker Context And Extensions

Context APIs live in graphile_worker_ctx and are re-exported by graphile_worker.

Important public types:

WorkerContext - runtime context passed to task handlers.
WorkerContextBuilder - builder for creating contexts.
WorkerContextExt - root-crate extension helpers for worker context.
TaskDetails and SharedTaskDetails - task identifier mappings.
Extensions and ReadOnlyExtensions from graphile_worker_extensions - typed application state storage.

Add shared state with WorkerOptions::add_extension. Task handlers receive a WorkerContext and can use the context APIs exposed by the generated docs.

Cron

Cron support is exposed from the root crate and split across three crates:

graphile_worker_crontab_parser - parse_crontab and CrontabParseError.
graphile_worker_crontab_types - Crontab, CrontabField, CrontabFill, CrontabTimer, CrontabTimerError, CrontabValue, and cron JobKeyMode.
graphile_worker_crontab_runner - CronRunner, cron_main, Clock, MockClock, KnownCrontab, and ScheduleCronJobError.

The root crate also re-exports:

Cron and CronBuilder for typed schedules.
CronInput for values accepted by WorkerOptions::with_cron.
CronJobKeyMode, which is the crontab JobKeyMode re-exported under a distinct root-crate name.

use graphile_worker::{Cron, CrontabFill, WorkerOptions};

let options = WorkerOptions::default()
    .define_job::<SendEmail>()
    .with_cron(
        Cron::daily_at::<SendEmail>(8, 0)?
            .fill(CrontabFill::hours(1)),
    );

let options = WorkerOptions::default()
    .with_cron("0 8 * * * send_email")?;

Database And Migrations

The database abstraction lives in graphile_worker_database.

Important public types:

Database, DatabaseDriver, DbTransaction, and TransactionDriver.
DbExecutor and DbExecutorArg.
DbError.
Schema.
Notification and NotificationStream.
DbCell, DbParams, DbRow, DbValue, and FromDbCell.
escape_identifier.

Driver modules are feature gated:

graphile_worker_database::sqlx with the driver-sqlx feature.
graphile_worker_database::tokio_postgres with the driver-tokio-postgres feature.

Migrations live in graphile_worker_migrations.

Important public items:

migrate - runs Graphile Worker schema migrations.
MigrateError - migration error type.
GraphileWorkerMigration - migration metadata type.
pg_version and sql modules.

The migration support crates are also public:

graphile_worker_migrations_core - GraphileWorkerMigration.
graphile_worker_migrations_macros - include_migrations!.

Lifecycle Hooks

Lifecycle hook APIs live in graphile_worker_lifecycle_hooks and are re-exported by graphile_worker.

Important public types:

HookRegistry - registry for hook handlers.
Plugin - plugin trait for registering hooks.
Event, HookOutput, and Interceptable - hook event traits.
TypeErasedHooks - erased hook registry.
HookResult and event-specific result types such as JobScheduleResult.
Event marker and context types exported from the crate's events and context modules.

Workers can register individual handlers with WorkerOptions::on or register a plugin with WorkerOptions::add_plugin.

use graphile_worker::{HookResult, JobStart, WorkerOptions};

let options = WorkerOptions::default()
    .on(JobStart, |ctx| async move {
        println!("starting job {}", ctx.job.id());
    })
    .on(graphile_worker::BeforeJobRun, |ctx| async move {
        if ctx.payload.get("skip").and_then(|value| value.as_bool()) == Some(true) {
            return HookResult::Skip;
        }

        HookResult::Continue
    });

Recovery And Shutdown

Recovery APIs are exposed from graphile_worker_recovery and re-exported by the root crate where they are part of the worker API.

Important public types:

WorkerRecoveryConfig - dead worker recovery settings.
SweepStaleWorkersOptions and SweepStaleWorkersResult - manual sweep input and output.
ResolvedSweepConfig - resolved sweep settings.
ActiveWorkerRow - heartbeat row returned by worker listing APIs.
INFRASTRUCTURE_RESILIENT_FLAG and job_has_resilient_flag - infrastructure-resilient job flag support.

Shutdown signal support lives in graphile_worker_shutdown_signal:

ShutdownSignal - cloneable shared future.
shutdown_signal - OS shutdown signal detector.

Runtime

graphile_worker_runtime provides runtime-neutral async building blocks used by the worker internals and exposed as a public crate.

Important public items:

channel, Receiver, and Sender.
Mutex, RwLock, RwLockReadGuard, and RwLockWriteGuard.
Notify and Notified.
spawn, AbortHandle, JoinHandle, and JoinError.
interval, sleep, sleep_until, timeout_at, Interval, and TimeoutError.

The crate requires either the runtime-tokio or runtime-async-std feature.

Admin Crates

Admin APIs are published as separate crates:

graphile_worker_admin_api - shared admin request and response DTO modules, plus SQLx read-query helpers behind its sqlx feature.
graphile_worker_admin_ui - native Axum admin server crate.
graphile_worker_admin_ui_client - admin UI client crate, including manifest_dir and WASM-only client code.

Feature Flags

The root crate default feature set is:

default = ["runtime-tokio", "tls-rustls", "driver-sqlx"]

Runtime features:

runtime-tokio
runtime-async-std

TLS features:

tls-rustls
tls-native-tls

Database driver features:

driver-sqlx
driver-tokio-postgres

OpenTelemetry compatibility features:

opentelemetry_0_30
opentelemetry_0_31
opentelemetry_0_32

Lower-Level Crates

These crates are public for advanced integration and internal composition, but most applications use them through graphile_worker re-exports:

graphile_worker_job - Job, JobBuilder, DbJob, and DbJobData.
graphile_worker_job_spec - JobSpec, JobSpecBuilder, and JobKeyMode.
graphile_worker_task_details - TaskDetails and SharedTaskDetails.
graphile_worker_queries - lower-level query modules such as add_job, get_job, complete_job, fail_job, return_jobs, recover_workers, task_identifiers, and worker_heartbeat.
graphile_worker_utils - WorkerUtils, client, and types.

Keyboard shortcuts

Graphile Worker RS