How kagkarlsson/db-scheduler works
db-scheduler is an embeddable, database-backed Java task scheduler designed for clustered execution. Applications define task types and schedules, build and start a Scheduler, then submit or inspect instances through its client API. The runtime polls and claims due work, invokes task handlers, and records completion, retry, or recurrence state in a relational table. Spring Boot starters and optional health/metrics support are separate integration branches. Several runtime internals are unsampled, so unverified execution links are marked dashed rather than asserted.
Main entry points: Scheduler.java Scheduler · Executor.java Task execution · TaskRepository.java Repository contract · SchedulerClient.java Scheduling client
Components 20
Tasks and schedules
- Task definitions
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/Task.java - Task builders
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/helper/Tasks.java - Schedule types
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/schedule/Schedule.java - Task instances
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/TaskInstance.java - Scheduled instances
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/SchedulableInstance.java
Scheduler runtime
- Scheduler
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/Scheduler.java - Scheduling client
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/SchedulerClient.java - Due polling
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/FetchCandidates.java - Task execution
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/Executor.java - Completion handling
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/CompletionHandler.java - Failure handling
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/FailureHandler.java - Task resolution
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/TaskResolver.java
Persistence
- Repository contract
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/TaskRepository.java - JDBC repository
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/jdbc/JdbcTaskRepository.java - JDBC transactions
db-scheduler/src/main/java/com/github/kagkarlsson/jdbc/TransactionManager.java - Relational database
Framework integrations
- Spring Boot starter
db-scheduler-spring-boot-starter-parent/db-scheduler-spring-common/src/main/java/com/github/kagkarlsson/scheduler/boot/config/DbSchedulerStarter.java - Health indicator
db-scheduler-spring-boot-starter-parent/db-scheduler-spring-boot3-starter/src/main/java/com/github/kagkarlsson/scheduler/boot/actuator/DbSchedulerHealthIndicator.java - Metrics support
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/stats/MicrometerStatsRegistry.java
Other components
- Application
Connections 21
- Application → Task builders: defines tasks
README.md - Task builders → Task definitions: builds
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/helper/Tasks.java - Task definitions → Schedule types: uses schedules
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/helper/Tasks.java - Application → Scheduler: builds and starts
README.md - Scheduler → Due polling: runs polling
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/Scheduler.java - Due polling → Task execution: dispatches due work
- Task execution → Task resolution: resolves task
- Task execution → Completion handling: handles result
- Task execution → Failure handling: handles failure
- Completion handling → Repository contract: reschedules
- Failure handling → Repository contract: retries
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/FailureHandler.java - Application → Scheduling client: submits instances
README.md - Scheduling client → Repository contract: reads and writes
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/SchedulerClient.java - Scheduling client → Task instances: accepts instances
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/SchedulerClient.java - Task instances → Scheduled instances: forms scheduled work
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/TaskInstance.java - Repository contract → JDBC repository: implemented by
db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/jdbc/JdbcTaskRepository.java - JDBC repository → Relational database: persists executions
README.md - JDBC repository → JDBC transactions: uses transactions
- Spring Boot starter → Scheduler: starts scheduler
- Health indicator → Scheduler: checks state
db-scheduler-spring-boot-starter-parent/db-scheduler-spring-boot3-starter/src/main/java/com/github/kagkarlsson/scheduler/boot/actuator/DbSchedulerHealthIndicator.java - Metrics support → Scheduler: observes runtime