Work that outlives the request.

Define typed jobs, run workers and schedules, publish notifications, and cache strings in your application’s PostgreSQL database.

Learning it for the first time? The recipe Run a background job walks through it in order. This page lists every name and limit.

Limits at a glance

A job is a struct with typed params

A job is a struct that extends Caramel::ColdBrew::Job and implements perform. Each param declares a typed field and its getter. The params form the JSON payload stored with the job. A default value makes the param optional when enqueueing.

struct SendInvitation < Caramel::ColdBrew::Job
  queue "mailers"
  retry_on IO::TimeoutError, attempts: 5, backoff: :exponential, base: 2.seconds
  param invite_id : Int64
  param note : String = ""

  def perform
    # Load the invite by invite_id and send it.
  end
end

A payload has no size limit of its own; store an id and load the record in perform. A PubSub payload does: 8,000 bytes, below.

Failed runs retry by rule

retry_on takes an exception class, attempts, backoff and base. attempts counts every run, the first included, except runs that maintenance released after their process died.

Rules on the job come first, then rules on its abstract parents, then global rules. The first matching rule wins.

Caramel::ColdBrew::Job.retry_on Socket::ConnectError,
  attempts: 6, backoff: :linear, base: 3.seconds

Status and hooks name the class, never the message

Caramel::ColdBrew.status(id) reads one job’s row through the current Repo connection; status(db, id) reads it on a handle, such as a spec’s db. statuses(ids) and statuses(db, ids) read many in one query and return a Hash(Int64, JobStatus).

status = Caramel::ColdBrew.status(db, id)
status.try(&.state) # => Caramel::ColdBrew::JobState::Queued

Two hooks observe failed runs. Register them at boot, before serve or work starts.

Caramel::ColdBrew.on_retry_scheduled do |event|
  Caramel::ColdBrew.publish("deliveries", event.to_json)
end
Caramel::ColdBrew.on_failed do |event|
  Log.error { "#{event.class_name} ##{event.id} failed: #{event.error_class}" }
end

Enqueue joins the business transaction

enqueue takes one keyword per param, plus run_at and priority. It returns the job’s Int64 id.

SugarORM::Repo.transaction do
  invite = Invite.create!(email: "elena@acme.com")
  SendInvitation.enqueue(invite_id: invite.id)
end

id = SendInvitation.enqueue(invite_id: 42, run_at: 10.minutes.from_now, priority: 5)
SendInvitation.enqueue(db, invite_id: 42, note: "resend")

A renamed job keeps its queued rows

A row stores the job’s fully qualified class name, and a worker runs the compiled job of that name. enqueue always stores the current name, so after you rename or move a class, rows queued before the deploy still carry the old one. List the old names on the class that replaced it.

struct App::RestockTea < Caramel::ColdBrew::Job
  renamed_from "App::Restock", "App::Stock::Restock"
  param tea_id : Int64

  def perform
    # Runs rows queued as App::Restock or App::Stock::Restock, too.
  end
end

Keep an old name until no row carries it. Because those commands only warn, run the new binary’s migrate before the old one stops, and read the list from a deploy script that fails on it.

names = Caramel::ColdBrew.unknown_queued_class_names(db)
abort "Stranded jobs: #{names.join(", ")}" unless names.empty?

serve and work run the workers

The application binary’s serve command starts Cold Brew beside the HTTP server. Its work command starts the same workers, maintenance and schedules without HTTP. Both read queue settings from the environment, and work’s flags replace them. Both need DATABASE_URL, CARAMEL_ENV and applied migrations; the deployment guide gives the environment.

bin/bookshelf work --queues=default,mailers --concurrency=4

Expect: Prints Bookshelf worker is ready: queues default, mailers; concurrency 4; scheduler on once the workers are claiming, with the application’s title first.

bin/bookshelf work --queues=default --no-scheduler

Expect: Prints Bookshelf worker is ready: queues default; concurrency 4; scheduler off. Every schedule is left to another process; maintenance still runs here.

Maintenance runs every 60 seconds in every process, even with --no-scheduler.

A schedule runs once per period

Caramel::ColdBrew.every(span, name) declares a block that runs once per period. Declare schedules at boot, before serve or work starts.

Caramel::ColdBrew.every(1.hour, "nightly-cleanup") { CleanupJob.enqueue }

Notifications arrive at most once

publish(channel, payload) sends a string with PostgreSQL pg_notify on the current Repo connection.

SugarORM::Repo.transaction do
  Caramel::ColdBrew.publish("board_#{board_id}", board_id.to_s)
end

A streaming action’s subscription therefore ends with its stream.

stream "text/event-stream" do |io|
  Caramel::ColdBrew.subscribe("board_#{id}") do |updates|
    loop { Caramel::SSE.write(io, event: "BoardUpdated", data: updates.receive) }
  end
end

The cache stores strings

Caramel::Cache stores string values in the unlogged caramel_cache table, through the current Repo connection.

report = Caramel::Cache.fetch("report:2026-10", expires_in: 10.minutes) do
  "computed report"
end
Caramel::Cache.write("banner", "Maintenance at noon")
Caramel::Cache.read("banner")   # => "Maintenance at noon"
Caramel::Cache.delete("banner") # => true

Keep only values you can compute again.

require "../spec_helper"

describe SendInvitation do
  it "runs once its queue is drained" do
    Corretto.session do |_client, db|
      id = SendInvitation.enqueue(db, invite_id: 42)
      Caramel::ColdBrew.drain_queue!(db, "mailers").should eq(1)
      Caramel::ColdBrew.status(db, id).not_nil!.state
        .should eq(Caramel::ColdBrew::JobState::Finished)
    end
  end
end

frappe corretto spec/jobs/send_invitation_spec.cr