guide · cron jobs

Work that runs on a clock.

Nightly reports, hourly cleanups, a health ping every thirty seconds. Schedules live in the selected persistent backend: beside jobs in SQLite, or transactionally coordinated across a PostgreSQL broker fleet. Memory-only mode does not survive a restart.

A scheduler is a named rule that keeps producing jobs on a queue. Create it once with upsertJobScheduler() and bunqueue fires the job on every tick, whether that tick comes from a cron pattern or a fixed interval. Scheduler IDs are global to the selected backend—not scoped by queue—and, in PostgreSQL mode, shared by every broker in the namespace. Use names such as reports:daily-report when several applications share a deployment.

Quick Start

Create a scheduler with upsertJobScheduler. It works in both embedded and TCP mode, in every SDK (Python: upsert_job_scheduler, Rust: upsert_job_scheduler, Go: UpsertJobScheduler, Elixir: upsert_scheduler), and calling it again with the same global ID replaces that scheduler definition instead of duplicating it. Reusing an ID with a different queue moves the definition to that queue.

Bun

import { Queue, Worker } from 'bunqueue/client';

const queue = new Queue('reports', { embedded: true });

// Every day at 9:00 AM
await queue.upsertJobScheduler(
  'daily-report',
  {
    pattern: '0 9 * * *',
  },
  {
    name: 'daily-report',
    data: { type: 'sales' },
  }
);

// A normal worker processes the scheduled jobs
new Worker(
  'reports',
  async (job) => {
    console.log('Running report:', job.data.type);
  },
  { embedded: true }
);

Node.js / Deno

import { Queue, Worker } from 'bunqueue-client';

const queue = new Queue('reports');

// Every day at 9:00 AM
await queue.upsertJobScheduler(
  'daily-report',
  {
    pattern: '0 9 * * *',
  },
  {
    name: 'daily-report',
    data: { type: 'sales' },
  }
);

// A normal worker processes the scheduled jobs
new Worker('reports', async (job) => {
  console.log('Running report:', job.data.type);
});

Python

from bunqueue import Queue, Worker

queue = Queue("reports")

# Every day at 9:00 AM
queue.upsert_job_scheduler("daily-report",
    {"pattern": "0 9 * * *"},
    {"name": "daily-report", "data": {"type": "sales"}})

# A normal worker processes the scheduled jobs
def process(job):
    print("Running report:", job.data["type"])

Worker("reports", process).run()

PHP

use Bunqueue\Queue;
use Bunqueue\Worker;

$queue = new Queue('reports');

// Every day at 9:00 AM
$queue->upsertJobScheduler('daily-report',
    ['pattern' => '0 9 * * *'],
    ['name' => 'daily-report', 'data' => ['type' => 'sales']]);

// A normal worker processes the scheduled jobs
$worker = new Worker('reports', function (Bunqueue\Job $job) {
    $data = $job->data();
    echo "Running report: {$data['type']}\n";
});
$worker->run();

Go

queue := bunqueue.NewQueue("reports", bunqueue.Options{})

// Every day at 9:00 AM
err := queue.UpsertJobScheduler("daily-report",
    bunqueue.SchedulerRepeat{Pattern: "0 9 * * *"},
    bunqueue.SchedulerTemplate{
        Name: "daily-report",
        Data: map[string]any{"type": "sales"},
    })

// A normal worker processes the scheduled jobs
worker := bunqueue.NewWorker("reports", func(job *bunqueue.Job) (any, error) {
    fmt.Println("Running report:", job.Data()["type"])
    return nil, nil
}, bunqueue.WorkerOptions{})
worker.Run()

Rust

use bunqueue_client::{
    ConnectionOptions, Queue, SchedulerRepeat, SchedulerTemplate, Value, Worker, WorkerOptions,
};

let queue = Queue::new("reports", ConnectionOptions::default());

// Every day at 9:00 AM
queue.upsert_job_scheduler(
    "daily-report",
    SchedulerRepeat { pattern: Some("0 9 * * *".into()), ..Default::default() },
    SchedulerTemplate {
        name: Some("daily-report".into()),
        data: Value::Map(vec![(Value::from("type"), Value::from("sales"))]),
        ..Default::default()
    },
)?;

// A normal worker processes the scheduled jobs
let worker = Worker::new(
    "reports",
    |job| {
        println!("Running report: {:?}", job.data());
        Ok(Value::Nil)
    },
    WorkerOptions::default(),
);
worker.run()?;

Elixir

queue = Bunqueue.queue("reports")

# Every day at 9:00 AM
:ok =
  Bunqueue.Queue.upsert_scheduler(queue, "daily-report",
    %{pattern: "0 9 * * *"},
    %{name: "daily-report", data: %{type: "sales"}}
  )

# A normal worker processes the scheduled jobs
worker =
  Bunqueue.Worker.new("reports", fn job ->
    IO.puts("Running report: #{job.data["type"]}")
    {:ok, nil}
  end)

Bunqueue.Worker.run(worker)

Or from the CLI, against a running server:

bunqueue cron add daily-report -q reports -d '{"type":"daily"}' -s "0 9 * * *"
bunqueue cron list
bunqueue cron delete daily-report

Where to go next

Job Schedulers from the Queue	Named repeatable schedules on the Queue object
Cron Recipes	Fixed intervals, timezones, repeat-after-completion
Cron Reference	Expression syntax, every scheduler option, MCP