Skip to content
Docs

bikesched logo: a bicycle shaped like a B, with a subtle clock hand and motion streaks

Docs

bikesched is a job scheduler for Java that keeps all of its state in PostgreSQL. Every application instance connected to the database is a node: nodes claim due jobs with SELECT … FOR UPDATE SKIP LOCKED, so many nodes share one database without stepping on each other and without any coordinator besides PostgreSQL.

bikesched admin UI: a web interface for managing jobs, events and nodes

Concepts

  • Node: a Bikesched instance. It registers in bikesched_nodes, sends heartbeats, polls for due jobs and runs them on virtual threads, up to its concurrency limit. Nodes clean up after each other: the running jobs of a crashed node are released and retried elsewhere.
  • Job: a unit of work with a name, an optional JSON payload, a priority, a retry limit and a timeout. A handler registered for the name runs it. Its type tells how it was started: single, recurring or as a child job.
  • Step: a named, durable part of a job. A completed step is not executed again when the job is retried; its stored result is returned instead. Steps can declare a compensation that undoes them if the job is cancelled or fails (a saga).
  • Recurring job: a job name with a Recurrence; each run is a regular job (an occurrence).
  • Event: a message with a name and a key. A job can wait for an event as a step; it is suspended without holding a thread until the event is published, then resumes.
  • Child job: a job started exactly once as a step of its parent. The parent can wait for it without holding a thread and receives its outcome and result.

Guarantees

  • At-least-once: a job may run again, e.g. after its node crashed, so handlers (and compensations) should be idempotent. Durable steps keep completed work from being repeated.
  • Transactional scheduling: jobs and events can be created in your own database transaction; they only become visible when you commit.
  • No lost events: an event published while a job starts waiting for it is never missed, and a job that starts waiting after the event was published receives it right away (within the event retention).

Contents

  • Getting started: requirements, installation with Gradle or Maven, a first job
    • Configuration: builder options, nodes, JSON mapping (bikesched-jackson), logging
  • Jobs: scheduling, writing handlers, retries, cancellation, history, timeouts
    • Recurring jobs: schedules, cron expressions (bikesched-cron) and occurrences
    • Changing handlers: what happens to jobs in flight when a deploy changes their handler, safe and unsafe changes
  • Multi-step jobs: durable steps, event waits and child jobs inside one job
  • Patterns: outbox, deduplication, rate limits, webhooks, approvals, fan-out, periodic work, sagas
  • Integrations: optional modules on top of the core
    • Spring Boot: the auto-configured node (bikesched-spring-boot-starter)
    • Kotlin: the bikesched-kotlin extensions
    • Annotations: job handlers as @JobHandler methods (bikesched-annotations)
    • Testing: test nodes, job wait helpers and time skipping (bikesched-test)
  • Operations: running bikesched in production
    • Admin UI: a page for jobs, steps, events and nodes with retry and cancel (bikesched-admin), and the lookups behind it
    • Metrics: JobListener, EventListener and the Micrometer meters (bikesched-micrometer)
    • Database: tables, indexes and migrations

The examples show the concepts working together; the patterns explain which example solves which problem. The decision records explain why bikesched works the way it does.