Skip to content

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

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

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

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
bikesched-spring-boot-starter Spring Boot auto-configuration: the node from the context, @JobHandler beans found automatically, see Spring Boot
bikesched-admin a small admin page and JSON API: jobs, steps, events and nodes, with retry and cancel, served by the JDK’s HTTP server or any framework, see Admin UI
bikesched-test testing support: a test node factory, JobAwait wait helpers (Awaitility internally) and time skipping, see Testing

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\": \"alice@example.com\"}").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:

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.