Scheduled jobs

Jobs can be scheduled to run at a future time and date instead of running immediately.

Basic usage

At insertion time, any job can specify a ScheduledAt as part of its InsertOpts to run it at a future time. The following code inserts a job that will run three hours from now:

_, err = riverClient.Insert(ctx,
    ScheduledArgs{
        Message: "hello from the future",
    },
    &river.InsertOpts{
        ScheduledAt: time.Now().Add(3 * time.Hour),
    }
)
if err != nil {
    // handle error
}

See the ScheduledJob example for complete code.

Pass a future Time as scheduled_at when inserting the job. This example delays it by three hours:

client.insert ScheduledArgs.new(message: "hello from the future"), scheduled_at: Time.now.utc + 3 * 3600

Set scheduled_at through InsertOpts with a UTC timestamp three hours in the future:

use riverqueue::{InsertOpts, chrono::{Duration, Utc}};

client.insert(ScheduledArgs { message: "hello from the future".into() })
    .opts(InsertOpts::default().with_scheduled_at(Utc::now() + Duration::hours(3)))
    .await?;

Pass a future Temporal.Instant as scheduledAt. Here, the job is scheduled three hours from now:

await client.insert(scheduledJob, { message: "hello from the future" }, {
  scheduledAt: Temporal.Now.instant().add({ hours: 3 }),
});

The job won’t be fetched before its scheduled_at time. The scheduler makes scheduled jobs available when they are due. Scheduling is not an exact timer: maintenance intervals, polling, and worker capacity can all add a delay.