Getting started
This page adds bikesched to an application and runs a first job. Configuration covers the builder options, nodes, JSON mapping and logging after that.
Requirements
- Java 21 or later. Every job runs on its own virtual thread.
- PostgreSQL. bikesched’s own tests run against PostgreSQL 18. bikesched creates and migrates its
tables (
bikesched_*) on first use, so the database user needs the right to create tables in the data source’s default schema, unless migrations run as a separate deploy step (see Database). - A
javax.sql.DataSourcefor that database, ideally a connection pool such as HikariCP.
Installation
All modules share the group org.bikesched and one version. bikesched-core is all you need; it
brings the PostgreSQL JDBC driver and slf4j-api along.
Note
These docs are for version 0.2.0-SNAPSHOT; the
GitHub Releases list the releases.
Releases and snapshots are published to GitHub Packages, which needs a GitHub token with the
read:packages scope even for public packages, hence the repository blocks below.
Gradle (Kotlin DSL), with the token in the Gradle properties gpr.user and gpr.token (e.g. in
~/.gradle/gradle.properties):
repositories {
mavenCentral()
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")
}Maven, with the token in a <server> entry with the id github in ~/.m2/settings.xml:
<repositories>
<repository>
<id>github</id>
<url>https://maven.pkg.github.com/bikesched/bikesched</url>
<snapshots><enabled>true</enabled></snapshots>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>org.bikesched</groupId>
<artifactId>bikesched-core</artifactId>
<version>0.2.0-SNAPSHOT</version>
</dependency>
</dependencies><!-- ~/.m2/settings.xml -->
<servers>
<server>
<id>github</id>
<username>your-github-user</username>
<password>your-token-with-read-packages</password>
</server>
</servers>Optional modules are added the same way, with the same version:
| Artifact | Adds |
|---|---|
bikesched-jackson |
typed payloads and results mapped with Jackson, see JSON mapping |
bikesched-kotlin |
Kotlin extensions |
bikesched-annotations |
job handlers as @JobHandler methods |
bikesched-cron |
cron expressions for recurring jobs |
bikesched-micrometer |
Micrometer meters |
bikesched-spring-boot-starter |
the Spring Boot auto-configuration, which replaces the setup below |
bikesched-admin |
the admin UI (or bikesched-admin-shaded, with nanojson relocated) |
bikesched-test |
test nodes and wait helpers, as a test dependency |
A first job
Build one Bikesched instance per application, register a handler for each job name and schedule
jobs. Building the instance migrates the schema, registers the node and starts polling for due
jobs; closing it stops the node.
DataSource dataSource = ...; // your PostgreSQL DataSource
try (Bikesched bikesched = Bikesched.builder(dataSource).build()) {
// Register a handler for a job name ...
bikesched.registerJobHandler("send-mail", job -> mailer.send(job.payload()));
// ... and schedule a job with that name, due right away
UUID jobId = bikesched.newJob("send-mail")
.payload("{\"to\": \"alice@example.com\"}")
.schedule();
}Without a JSON mapper, payloads are JSON text. With bikesched-jackson, handlers and builders take
records instead:
record Mail(String to) {}
TypedJob<Mail> sendMail = TypedJob.of("send-mail", Mail.class);
Bikesched bikesched = Bikesched.builder(dataSource)
.jsonMapper(new JacksonJsonMapper())
.build();
bikesched.registerJobHandler(sendMail, (job, mail) -> mailer.send(mail.to()));
bikesched.newJob(sendMail).payload(new Mail("alice@example.com")).schedule();In an application, the instance lives as long as the application: build it at startup and close it on shutdown. Every application instance connected to the same database is a node, and the nodes share the due jobs between them.
To see it running without writing code, start PostgreSQL with docker compose up -d in a clone of
the repository and run the simple example with
./gradlew :bikesched-examples:java:runSimple.
Next steps
- Jobs: retries, failure handlers, cancellation, timeouts and the history
- Multi-step jobs: durable steps, event waits and child jobs
- Patterns: common problems and the examples solving them