Docs
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.
Concepts
- Node: a
Bikeschedinstance. It registers inbikesched_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
- Configuration: builder options, nodes, JSON mapping
(
- 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
- Recurring jobs: schedules, cron expressions (
- Multi-step jobs: durable steps, event waits and child jobs inside
one job
- Steps and compensation: durable steps, sleeping, polling and sagas
- Events: waiting for and publishing events
- Child jobs: starting and waiting for child jobs, job results
- 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-kotlinextensions - Annotations: job handlers as
@JobHandlermethods (bikesched-annotations) - Testing: test nodes, job wait helpers and time skipping (
bikesched-test)
- Spring Boot: the auto-configured node
(
- Operations: running bikesched in production
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.