bikesched

A PostgreSQL-backed job scheduler for Java and Kotlin: durable steps, events and retries, with minimal dependencies, no extra infrastructure and an optional admin UI

[!NOTE] bikesched is at a super early stage (0.2.0-SNAPSHOT) and can break at any time: APIs and the database schema may change without notice and without migrations.

It is also a first experiment in building a library heavily with AI coding agents; hence the logo, a nod to Simon Willison's pelican riding a bicycle LLM benchmark.

Simon, the creator of the bikesched project: I was working on a project and looking for an open source library that does job scheduling with durable execution, has minimal dependencies and is PostgreSQL-focused, but didn't find one that fit. So instead of continuing that project, I started "bikeshedding" on a library with these properties, with AI doing much of the implementation, around the needs I'd actually run into.

bikesched stores jobs in PostgreSQL and lets every connected application instance (node) work on them. Nodes claim due jobs with SELECT … FOR UPDATE SKIP LOCKED, so many nodes can share one database without stepping on each other and without any coordinator besides PostgreSQL.

bikesched is inspired by some great job schedulers, like db-scheduler, JobRunr, Quartz and River, and by durable execution engines like Inngest and Restate. The goal is to keep it small and easy to drop into your app:

• Just two runtime dependencies in the core: the PostgreSQL JDBC driver and the SLF4J API (plus the annotations-only JSpecify jar). No framework, no migration tool, no JSON library, in the spirit of boring technology.
• Extension modules when you want them: Jackson for typed payloads, Kotlin extensions, Spring Boot auto-configuration, cron expressions, Micrometer metrics and an admin UI. Pull in only what you use.
• PostgreSQL is all you need: jobs, durable steps, events and nodes live in plain tables (bikesched_*), and bikesched creates and migrates the schema on first use.
• Modern Java: runs on Java 21 and later, with every job on its own virtual thread.

One thing bikesched isn't: a workflow engine. Steps and compensation live inside a single job, so there are no process models (BPMN), no visual modelling and no orchestration across services. If that's what you're after, have a look at Camunda or similar tools.

Module	Contents
bikesched-core	the scheduler; depends on the PostgreSQL driver and the SLF4J API only; optional schema migration spec
bikesched-jackson	JacksonJsonMapper: payloads, step results and events as records, via Jackson 3
bikesched-kotlin	Kotlin extensions: configuration DSL, typed handlers, kotlin.time durations
bikesched-annotations	job handlers declared as @JobHandler methods, see Annotations
bikesched-cron	cron expressions as CronRecurrence or as strings (schedule("0 3 * * *"), @JobHandler), via cron-utils, see Cron expressions
bikesched-micrometer	Micrometer meters for claims, attempts and published events, see Metrics

Features

• Jobs now, at a given time or after a delay, with priority, retries and timeouts; optionally in your own database transaction, with an idempotency key for callers that retry, and with a reference to the order or payment they are about, to find them in the admin UI
• Jobs start as soon as they are due: nodes notify each other with PostgreSQL LISTEN/NOTIFY, polling is only the safety net
• Durable steps whose results survive retries, with optional compensation (sagas)
• Failure handlers for permanently failed jobs (e.g. a dead-letter table) and for steps (with a fallback result)
• Cancellation from within a handler or from outside
• Postponing: a handler hit by a rate limit runs again later with job.postpone(…), without using up an attempt
• Recurring jobs with fixed-rate, fixed-delay, daily, weekly or custom schedules
• Events: jobs wait for an event without holding a thread and resume when it is published
• Sleeping: jobs pause for days with job.sleep(…) without holding a thread
• Polling: jobs check an external service until a result is ready, as one durable step suspended between checks
• Child jobs: jobs start other jobs exactly once and wait for their outcome and result without holding a thread
• Optional typed TypedJob/TypedEvent constants, next to plain string names
• A null-marked API (JSpecify): IDEs, NullAway and Kotlin see which values may be null
• Crash recovery: jobs of dead nodes are released and retried by others; a node that lost a job can no longer change its steps
• Ended jobs are deleted after a retention (7 days by default); optional history and statement timeout
• Pluggable JSON mapping and node, job and step ids in the SLF4J logging context
• An optional admin UI to find, retry and cancel jobs, with the lookups and actions behind bikesched.admin()

Quick start

DataSource dataSource = ...; // any PostgreSQL DataSource, e.g. a HikariCP pool

try (Bikesched bikesched = Bikesched.builder(dataSource)
        .nodeName("worker-1")              // optional, defaults to the host name
        .build()) {                    // migrates the schema, registers the node, starts polling

    // Register a handler for a job name ...
    bikesched.registerJobHandler("send-mail", job -> mailer.send(job.payload()));

    // ... and schedule jobs with that name
    bikesched.newJob("send-mail").payload("{\"to\": \"[email protected]\"}").schedule();
}

A handler that throws fails the attempt; the job is retried until its maximum number of attempts is used up and then marked FAILED.

This is where bikesched stops looking like a regular job scheduler: a handler can run durable steps and wait for an event, without holding a thread or re-doing work on retries or resumes:

bikesched.registerJobHandler("order", job -> {
    Order order = job.payload(Order.class);

    // Creates a Stripe PaymentIntent; runs once, a retried or resumed job gets the id back instead
    String paymentIntentId = job.step("create-payment-intent", String.class,
            step -> stripe.createPaymentIntent(order).id());

    // Suspends (no thread held) until Stripe's webhook reports on this payment intent
    PaymentUpdated webhook = job.waitForEvent("await-payment", "payment-intent-updated", paymentIntentId,
                    PaymentUpdated.class)
            .receive();

    switch (webhook.status()) {
        case SUCCEEDED -> job.step("mark-paid", () -> orders.markPaid(order, paymentIntentId));
        case FAILED -> job.step("mark-failed", () -> orders.markFailed(order, paymentIntentId));
    }
});

// in the Stripe webhook endpoint, possibly minutes or days later
bikesched.newEvent("payment-intent-updated", webhookPayload.paymentIntentId())
        .payload(webhookPayload)
        .publish();

A plain job scheduler would need its own tables and glue code to carry order and paymentIntentId across that wait, to not create a second payment intent on a retry, and to resume on another node after a crash; here it's job.step(...) and job.waitForEvent(...). See Steps and compensation and Events.

Documentation

The documentation covers the concepts in detail:

• Getting started: installation with Gradle or Maven, a first job, and the configuration (builder options, nodes, JSON mapping, logging)
• Jobs: scheduling, writing handlers, retries, failure handlers, cancellation, history, retention, timeouts; recurring jobs and changing handlers safely for jobs in flight
• Multi-step jobs: steps and compensation, events and child jobs
• Patterns: common problems (outbox, deduplication, rate limits, webhooks, approvals, fan-out, periodic work, sagas) and the examples solving them
• Integrations: Spring Boot, Kotlin, annotations, testing
• Operations: admin UI, metrics, database tables and migrations

Examples

Runnable examples with tests — a taxi booking saga with event waits and compensation, a cinema ticket order with a StandaloneJobHandler, a webhook with a polling fallback, a provider's rate limit with Bucket4j, chat messages deduplicated by idempotency keys, an approval with a reminder and an escalation, a fan-out with child jobs, a recurring job on two nodes, and a Spring Boot application whose node and handlers are wired by the starter — live in the bikesched-examples modules.

Building

Requirements: JDK 26 (or let Gradle provision it via the toolchain) and Docker for the tests, which run against PostgreSQL 18 with Testcontainers. The build compiles for Java 21, the oldest Java version bikesched supports (ADR 0049).

./gradlew build

The load and failure tests (database restarts, cut-off nodes, hanging connections, throughput) take a few minutes and run on demand, before a release: ./gradlew :bikesched-stress-tests:stressTest.

To try it out locally, start PostgreSQL with Docker Compose and run the simple example, which registers a handler and runs one job:

docker compose up -d                      # POSTGRES_PORT=5433 docker compose up -d if 5432 is taken
./gradlew :bikesched-examples:java:runSimple   # honors POSTGRES_PORT as well

All dependency and tool versions are managed in gradle/libs.versions.toml.

Releases and snapshots

Releases (see the GitHub Releases) and the snapshots of main and the release branches are published to GitHub Packages: org.bikesched:bikesched-core, bikesched-jackson, bikesched-kotlin, bikesched-annotations, bikesched-cron, bikesched-micrometer, bikesched-spring-boot-starter, bikesched-admin, bikesched-admin-shaded and bikesched-test, all with the same version (0.2.0-SNAPSHOT on this branch). Reading from GitHub Packages requires a GitHub token with the read:packages scope, even for public packages. How releases are cut: RELEASING.md.

repositories {
    maven {
        url = uri("https://maven.pkg.github.com/bikesched/bikesched")
        credentials {
            username = providers.gradleProperty("gpr.user").get()
            password = providers.gradleProperty("gpr.token").get()   // token with read:packages
        }
    }
}

dependencies {
    implementation("org.bikesched:bikesched-core:0.2.0-SNAPSHOT")
}

License

bikesched is licensed under the Apache License 2.0: you may use, modify and embed it, also in commercial and closed-source products. Simon, the creator of the bikesched project: it's permissive on purpose, so that anyone who runs into the same need I did can drop it into their own project, open or closed source, without license-review friction. The name and logo are trademarks, see the trademark policy for how to refer to bikesched and how to name forks.