Struct WorkerUtils 

pub struct WorkerUtils { /* private fields */ }

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

This is the primary interface for adding jobs to the queue, managing existing jobs, performing maintenance tasks, and migrating the database schema.

Implementations

impl WorkerUtils

pub fn new(database: impl Into<Database>, schema: impl Into<Schema>) -> Self

Creates a new instance of WorkerUtils.

Arguments

• database - Database connection handle
• schema - The schema where Graphile Worker tables are stored

Returns

A new WorkerUtils instance

pub fn with_hooks(self, hooks: Arc<HookRegistry>) -> Self

Adds lifecycle hooks to this WorkerUtils instance.

pub fn with_task_details(self, task_details: SharedTaskDetails) -> Self

Adds task details to this WorkerUtils instance.

When task_details is provided, cleanup operations that include GcTaskIdentifiers will automatically refresh the task details to ensure the worker can still pick up jobs after task identifiers are garbage collected.

pub fn with_use_local_time(self, use_local_time: bool) -> Self

Sets whether to use local application time or database time for timestamps.

When use_local_time is true, the application’s Utc::now() is used for timestamps, which can help handle clock drift between the application server and database server. When false (default), PostgreSQL’s now() is used instead.

impl WorkerUtils

pub async fn remove_job(&self, job_key: &str) -> Result<(), GraphileWorkerError>

Removes a job from the queue by its job key.

Useful for cancelling scheduled jobs that haven’t run yet.

pub async fn complete_jobs( &self, ids: &[i64], ) -> Result<Vec<DbJob>, GraphileWorkerError>

Marks multiple jobs as completed.

pub async fn permanently_fail_jobs( &self, ids: &[i64], reason: &str, ) -> Result<Vec<DbJob>, GraphileWorkerError>

Marks multiple jobs as permanently failed with a reason.

pub async fn reschedule_jobs( &self, ids: &[i64], options: RescheduleJobOptions, ) -> Result<Vec<DbJob>, GraphileWorkerError>

Reschedules multiple jobs with new parameters.

This allows changing when jobs will run next, their priority, and their retry behavior.

pub async fn list_active_workers( &self, sweep_threshold: Duration, ) -> Result<Vec<ActiveWorkerRow>, GraphileWorkerError>

Lists workers registered in the heartbeat table.

pub async fn sweep_stale_workers( &self, options: SweepStaleWorkersOptions, ) -> Result<SweepStaleWorkersResult, GraphileWorkerError>

Sweeps inactive workers and orphan locks, recovering their jobs.

pub async fn sweep_stale_workers_with_config( &self, recovery_config: &WorkerRecoveryConfig, options: SweepStaleWorkersOptions, ) -> Result<SweepStaleWorkersResult, GraphileWorkerError>

Sweeps inactive workers with an explicit recovery configuration.

pub async fn force_unlock_workers( &self, worker_ids: &[&str], ) -> Result<(), GraphileWorkerError>

Force unlocks worker records in the database.

Useful for recovering from situations where workers crashed without properly releasing their locks, allowing their jobs to be picked up by other workers.

pub async fn cleanup( &self, tasks: &[CleanupTask], ) -> Result<(), GraphileWorkerError>

Runs database cleanup tasks to maintain performance.

When GcTaskIdentifiers is included in the tasks and this WorkerUtils instance was created with task details (via with_task_details), the task identifiers known to this worker will be preserved and refreshed after cleanup.

pub async fn migrate(&self) -> Result<(), MigrateError>

Runs database migrations to ensure the schema is up to date.

impl WorkerUtils

pub async fn add_job<T: TaskHandler>( &self, payload: T, spec: JobSpec, ) -> Result<Job, GraphileWorkerError>

Adds a job to the queue with type safety.

Uses the TaskHandler trait to ensure that the job identifier and payload type match, providing compile-time type safety.

Example

let job = utils.add_job(
    MyTask { data: "hello".to_string() },
    JobSpec::default()
).await?;

pub async fn add_raw_job<P>( &self, identifier: &str, payload: P, spec: JobSpec, ) -> Result<Job, GraphileWorkerError>

where P: Serialize,

Adds a job to the queue with a raw identifier and payload.

Doesn’t require the task handler to be defined at compile time, allowing for dynamic job creation. However, lacks the compile-time type safety of add_job.

Example

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

pub async fn add_jobs<T: TaskHandler + Clone>( &self, jobs: &[(T, &JobSpec)], ) -> Result<Vec<Job>, GraphileWorkerError>

Adds multiple jobs of the same type to the queue in a single batch operation.

This is more efficient than calling add_job multiple times when you need to add many jobs of the same type, as it uses a single database round trip.

Limitations

• job_key_mode: UnsafeDedupe is not supported in batch operations
• job_key_mode is applied uniformly: if any job uses PreserveRunAt, it applies to all jobs in the batch. For per-job job_key_mode control, use add_job individually.

pub async fn add_raw_jobs( &self, jobs: &[RawJobSpec], ) -> Result<Vec<Job>, GraphileWorkerError>

Adds multiple jobs with raw identifiers and payloads in a single batch operation.

This allows adding jobs of different types in a single batch, but without compile-time type safety. More efficient than multiple add_raw_job calls.

Limitations

• job_key_mode: UnsafeDedupe is not supported in batch operations
• job_key_mode is applied uniformly: if any job uses PreserveRunAt, it applies to all jobs in the batch. For per-job job_key_mode control, use add_raw_job individually.

pub async fn add_batch_job<T: BatchTaskHandler>( &self, payloads: Vec<T>, spec: JobSpec, ) -> Result<Job, GraphileWorkerError>

Adds a batch job to the queue with type safety.

The database payload is a JSON array of T items. Register the same identifier with the worker builder’s batch-job registration API so the worker can run the batch and retry only failed items after partial success.

Trait Implementations

impl Clone for WorkerUtils

fn clone(&self) -> WorkerUtils

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.