Jobs & cron

Railbase has a built-in background job runner and scheduler — no Redis, no separate worker process. Use it for anything that shouldn't block a request: sending email, generating documents, sweeping expired data.

Define a job

Register a handler under a kind at boot, then enqueue work against that kind at runtime. The registry (and the store) come up during App.Run, so register from inside OnBeforeServe — calling app.Jobs() directly in the ExecuteWith callback returns nil (the subsystem doesn't exist yet):

import "github.com/railbase/railbase/pkg/railbase/jobs"

cli.ExecuteWith(func(app *railbase.App) {
    app.OnBeforeServe(func(_ chi.Router) {
        // Register: maps a "kind" to a handler. j.Payload is the raw
        // JSON the enqueuer passed.
        app.Jobs().Register("email.welcome", func(ctx context.Context, j *jobs.Job) error {
            return sendWelcome(ctx, j.Payload)
        })
    })
})

// Enqueue (e.g. from a hook or REST handler — any time after boot):
_, err := app.JobsStore().Enqueue(ctx, "email.welcome",
    map[string]any{"user_id": id},
    jobs.EnqueueOptions{Delay: 30 * time.Second})

Jobs retry on failure (default 5 attempts). Return jobs.ErrPermanent to fail without retrying.

Inspect jobs from the CLI

railbase jobs list
railbase jobs show <id>
railbase jobs run-now <id>
railbase jobs cancel <id>
railbase jobs recover        # requeue jobs stuck in "running"

Schedule recurring work

Persisted schedules are managed with railbase cron (standard 5-field cron expressions):

railbase cron upsert nightly-report "0 3 * * *" report.generate
railbase cron list
railbase cron run-now nightly-report
railbase cron disable nightly-report

You can also schedule from a JavaScript hook:

$app.cronAdd("nightly", "0 3 * * *", () => { /* … */ });

The admin console shows the schedule table and lets you run, enable/disable, or edit entries — see Operating from the admin.