Database
All state lives in plain PostgreSQL tables prefixed bikesched_, in the data source’s default
schema.
Migrations
The schema is created by bikesched’s own minimal migrator on first use (no Flyway or Liquibase).
Concurrent nodes are serialized with a PostgreSQL advisory lock; applied migrations are tracked with
checksums in bikesched_schema_migrations. The migration scripts ship in the jar under
org/bikesched/migrations/. Bikesched.migrate() runs the migration without registering the node
or polling, so an application can migrate at startup instead of on first use. The Spring starter
uses the same first-use initialization boundary (Spring
Boot).
Disable automatic migration
Use the core builder flag when migrations belong in a separate deploy step:
// Deployment: a data source with DDL rights, using the same bikesched library version.
try (var deploy = Bikesched.builder(migrationDataSource)
.autoStartPolling(false)
.build()) {
deploy.migrate();
}
// Application: no DDL rights required.
var scheduler = Bikesched.builder(applicationDataSource)
.migrateSchema(false)
.build();migrateSchema defaults to true. With false, first database use reads
bikesched_schema_migrations and requires every bundled version with its matching checksum.
It performs no DDL or history writes and does not acquire the migration advisory lock. Unknown
versions warn and are ignored, just as during migration, to allow rolling deployments. Validation
checks migration history, not the physical tables, columns or indexes: manually changed schema
objects are not detected.
With default polling, validation happens during build(), before node registration. With
autoStartPolling(false), building stays database-free; validation waits for the first operation
that needs the database, including reads. A failure is retried on the next database operation.
Finish deployment before starting application access; validation does not wait for a concurrent
migration. Success is cached per instance, not checked before every query.
The application needs schema USAGE, SELECT on the migration history, and normal table/sequence
permissions for scheduler operations. A missing history table or bundled version fails with
instructions to run Bikesched.migrate() using a migration-capable data source. A checksum mismatch
names the version and script: restore matching scripts/library and schema, rather than changing
recorded checksums to bypass validation. SQL failures preserve their cause; check connectivity,
search path and permissions too. Merely executing the bundled SQL without recording bikesched’s
migration history is not sufficient; the supported deploy path above maintains that history.
Explicit Bikesched.migrate() always runs the migrator, including when migrateSchema(false) is
set or validation already succeeded. It still needs DDL rights and never starts polling. In Spring,
set bikesched.migrate-schema=false for validation-only behavior. Flyway/Liquibase adapters and
configurable schemas are outside this feature.
Note
While bikesched is unreleased, schema changes are made to the first migration in place. A local
database created by an older build then fails the checksum check; recreate it, e.g. with
docker compose down -v.
Tables
| Table | Content |
|---|---|
bikesched_schema_migrations |
applied schema migrations with version, description, checksum, install time and duration; created by the migrator itself |
bikesched_nodes |
registered nodes with their id, name (not unique) and last heartbeat; dead nodes are removed by the others |
bikesched_jobs |
jobs with their name (selects the handler), their type (SINGLE, RECURRING or CHILD, see ADR 0059), state SCHEDULED, RUNNING, WAITING, SUCCEEDED, FAILED, CANCELLED, COMPENSATING, COMPENSATION_FAILED or FAILING, their payload, priority, attempts, timeout, lock (locked_by_node_id, the claiming node, and lock_token, new for every claim) and last_error; compensating jobs also carry the state they end in (compensation_end_state) and their compensation_attempts, failing jobs (whose failure handler runs) the state they end in (failure_end_state) and the runs of the handler (failure_attempts), jobs cancelled via Bikesched.cancel their cancel_requested_at and cancel_message; occurrences of recurring jobs also carry their recurrence description and their planned_run_at (the run they were planned for, not moved by retries or waits); succeeded jobs their result (Job results), child jobs their parent_job_id (a plain reference, no foreign key: the parent may be deleted after its retention while the child runs), jobs scheduled with an idempotency key their idempotency_key, jobs with a reference their reference |
bikesched_steps |
durable steps of each job, identified by their id (a UUIDv7 created when the step first starts and kept across its attempts, which every write to the step uses, see ADR 0057) and by their name, unique within the job; with their type (STEP, SLEEP, EVENT_WAIT, EVENT_PUBLISH, CHILD_JOB or POLL), state RUNNING, WAITING, SUCCEEDED, FAILING (attempts used up, or an event wait or poll timed out, failure handler yet to finish; its runs in failure_attempts), FAILED, TIMED_OUT, COMPENSATED, CANCELLED or POSTPONED (a STEP whose handler postponed the job, run again by the next attempt), their result, attempts, the node running them (locked_by_node_id, only while RUNNING) and whether they have a compensation (compensable; not for a step its failure handler resolved); event waits also carry event_name, event_key and their deadline (wake_at); once the event is received, its payload is copied into result and its id into event_id (a wait its failure handler resolved after a timeout has the fallback in result, no event_id, and keeps last_error); event publishes carry the published event’s event_name, event_key and event_id; event_id is a plain reference (no foreign key), so it outlives the event’s retention; sleeps carry their wake-up time (wake_at); polls carry the time of their next check (wake_at, while WAITING) and their deadline (deadline_at), and count their checks in attempts; child job steps carry the started child (child_job_id, a plain reference) and its name (child_job_name, so a replay starting another job under the same step name is rejected even after the child was deleted), the deadline of the parent’s wait (wake_at) and, once the child ended, its terminal state (child_end_state), its result (result) and its error or cancel message (last_error) |
bikesched_events |
published events (name, key, payload, published_at, the optional idempotency_key and reference), kept until expires_at (published + the event’s retention), see Retention and Idempotency keys |
bikesched_history |
only with the history enabled: one row per change of a job or of one of its steps (step_id), per published event and per node registering, stopping or being removed, keyed by its subject (subject_id: the job, event or node) and a UUIDv7 id, with its subject_type (JOB for jobs and their steps, EVENT, NODE), the action (what happened), for jobs and steps the resulting state and the job’s attempt count, who acted (actor_type: NODE, APPLICATION, JOB or USER, and the user’s actor_name), the node_id that wrote it, a caused_by_id (the event, job or node that caused it), its time (created_at, the database’s clock at the write) and data, a JSON object with the names and the action’s specifics built when the row is written; kept for the history retention, independently of its subject (no foreign keys), see ADR 0062 |
Text lengths
Names and keys are text columns, most of them indexed. To keep index entries well below
PostgreSQL’s B-tree limit (about 2.7 kB), their length is limited, in characters:
| Value | Limit |
|---|---|
| node name, job name, step name, event name, recurrence description | 1 to 200 |
| event key, idempotency key | 1 to 500 |
bikesched checks the limits where a value is passed in (IllegalArgumentException naming the
parameter), and CHECK constraints enforce them in the schema.
Messages are diagnostic text and are never rejected, so recording a failure cannot fail on its
length: errors (last_error of jobs and steps) and cancel messages (cancel_message) longer than
4000 characters are stored truncated, ending in … (truncated).
Collation
Every text column except the messages holds an identifier (names, keys, idempotency keys,
references, recurrences, types, states, history actions and actor names) and uses the "C"
collation, whatever the database’s default is: comparisons and sorts are byte-wise, which makes
the indexes on these columns faster, lets them serve the admin’s prefix searches, and keeps them
valid across glibc or ICU upgrades that change a linguistic sort order. The admin therefore lists
names in byte order, upper case before lower case. See
ADR 0063.
Connection pool
Every store call borrows its own connection; nothing beyond the listening connection (see Due jobs
start right away) is held for
longer. Size the pool at least maxConcurrentJobs (jobs) plus a few (poller, heartbeat, clean-ups)
plus one more if listenForDueJobs is on. With PGSimpleDataSource, the data source used by the
examples and these docs, every statement opens a new TCP connection and authenticates; use a pool
(e.g. HikariCP) in production.
Clean-ups
Every polling node deletes ended jobs with their steps (jobRetention), history entries
(history) and expired events (eventRetention) on its own interval. Each clean-up deletes
in batches of 1000 rows, oldest first, each batch in its own short transaction, and skips rows
another node is deleting, so a backlog neither holds locks nor holds back vacuum for long, and
stays below a statementTimeout. A batch starts where the previous one ended instead of at the
oldest index entry, so it does not read past the rows deleted before vacuum removed them (see
ADR 0052).
Deleted rows take space until autovacuum reclaims them. With high job volumes, let autovacuum run more often on the busy tables, for example:
alter table bikesched_jobs set (autovacuum_vacuum_scale_factor = 0.01);
alter table bikesched_steps set (autovacuum_vacuum_scale_factor = 0.01);
alter table bikesched_history set (autovacuum_vacuum_scale_factor = 0.01);Indexes and locks
Besides primary keys, the indexes cover the steps of a job by name (unique), the history (by created_at, for the cleanup; entries caused by an event, job or node; entries of users), the cleanup of ended jobs (finished_at), polling (due SCHEDULED/WAITING/COMPENSATING/FAILING jobs in
claim order, as a partial index that excludes finished jobs; it includes name, so jobs with names
the node has no handlers for are skipped on index entries), jobs per node, at most one pending
occurrence per recurring job (partial unique index), idempotency keys of jobs (unique per name,
partial: only jobs with a key), references of jobs and events ((reference, id), partial: only
rows with a reference), steps waiting for an event, steps waiting for
a child job (by child_job_id), the steps that published or received an event (by event_id,
for the admin lookups), the pages of the admin’s job list per name (name, id; ids are
time-ordered UUIDv7, so the primary keys serve the lists of all jobs and of all events), the admin’s search by short id (the last 8 hex digits of a job or event id), and
event lookup and cleanup. The index of the jobs per node holds only running jobs, and
bikesched_nodes has no index besides its primary key, so heartbeats are HOT updates. Waiting for, suspending at and publishing events also take transaction-scoped advisory
locks per event name and key; no table is involved. Step writes share-lock the job’s row while
checking that the job is still running with the writing attempt’s lock_token, so a concurrent
release waits for them. A job suspending at a wait for a child job locks the child’s step row
first; the child’s end updates the same row, so the two serialize and the parent is never left
waiting for a child that already ended.