Deployment Overview

Ratchet runs inside your application. Choose the runtime integration before configuring persistence:

Runtime	Setup	Execution
Spring Boot	SQL or MongoDB starter, normal Boot connection properties	Boot 3.5/4.1, Java 17/21, JVM and native image (GraalVM 25)
Quarkus	Quarkus extension and selected store	JVM and native image
Micronaut	Micronaut integration, its JPA or MongoDB module, and selected store	Micronaut 4.10/5, Java 17/25, JVM and native image (GraalVM 25)
Jakarta EE 10/11	CDI beans, store resources, managed executors	Application server

The remaining setup on this page describes Jakarta EE. The linked guides cover the other runtimes.

What you need

Component	Requirement	Notes
Java	17 or later	Virtual threads available on 21+
Jakarta EE Runtime	10/11 with CDI, JPA, Interceptors, and Jakarta Concurrency	WildFly, Payara, Open Liberty, GlassFish 8, etc.
CDI	4.0+	`beans.xml` with `bean-discovery-mode="annotated"`
Database	MySQL 8+, PostgreSQL 14+, Oracle 23ai+, SQL Server 2022+, or MongoDB 6+	One store module per database
Build Tool	Maven 3.8+	BOM import for version management

Running on Quarkus instead of a Jakarta EE server? The ratchet-quarkus extension supports Quarkus on the JVM and as a GraalVM native image. See Quarkus Deployment. Running on Spring Boot? The SQL and MongoDB starters support Boot 3.5 and 4.1 on the JVM and as a native image. See Spring Boot Deployment. Running on Micronaut? The integration supports Micronaut 4.10 and 5 with SQL or MongoDB, on the JVM and as a native image. See Micronaut Deployment.

Ratchet modules

A typical deployment includes three Ratchet JARs:

ratchet-api          Public API, events, enums, SPI interfaces (Jakarta EE APIs only)
ratchet           Reference implementation — core engine, CDI integration, polling
ratchet-store-*      One of: ratchet-store-mysql, ratchet-store-postgresql, ratchet-store-oracle, ratchet-store-sqlserver, ratchet-store-mongodb

Optional modules:

ratchet-micrometer   Micrometer metrics integration
ratchet-quarkus      Quarkus extension (JVM and native) — see Quarkus Deployment
ratchet-spring-boot-starter           Spring Boot starter for SQL stores — see Spring Boot Deployment
ratchet-spring-boot-starter-mongodb   Spring Boot starter for MongoDB — see Spring Boot Deployment
ratchet-micronaut                     Micronaut integration; see Micronaut Deployment
ratchet-micronaut-jpa                 Micronaut SQL stores through Micronaut Hibernate JPA
ratchet-micronaut-mongodb             Micronaut MongoDB store through micronaut-mongo-sync
ratchet-micronaut-processor           Annotation processor for @CircuitBreakerProtected on Micronaut beans

All versions are managed through the ratchet-bom:

xml

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>run.ratchet</groupId>
      <artifactId>ratchet-bom</artifactId>
      <version>0.5.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Deployment scenarios

Single-node

The simplest deployment: one application instance connected to one database. No clustering configuration needed. Ratchet's polling engine runs inside the application server and executes jobs using its managed thread pool.

This is suitable for:

Development and testing
Low-throughput workloads (< 1,000 jobs/hour)
Applications where high availability is not critical

Multi-node (clustered)

Multiple application instances share the same database. Ratchet uses database-level claiming (SELECT ... FOR UPDATE SKIP LOCKED on PostgreSQL/MySQL/Oracle, UPDLOCK, READPAST row locks on SQL Server, atomic document updates on MongoDB) to ensure each job is claimed by exactly one node.

Recurring scans and destructive startup cleanup are already serialized through store-backed locks and leases. Implement ClusterCoordinator only if you want low-latency cross-node wakeups.

See Cluster Configuration for details.

Containerized

Ratchet runs in Docker or Kubernetes without any special configuration beyond what a standard Jakarta EE application needs. The database runs as a separate container or managed service.

See Docker Deployment and Kubernetes Deployment.

Database schema

Ratchet ships SQL DDL as plain files. No Flyway or Liquibase dependency is required. The schema files are bundled inside each SQL store module JAR at ddl/:

ratchet-store-mysql contains ddl/mysql-schema.sql
ratchet-store-postgresql contains ddl/postgresql-schema.sql
ratchet-store-mongodb initializes collections and indexes at startup

For SQL stores, apply the schema using whatever mechanism your team prefers: CLI tools, migration frameworks, or application startup scripts. MongoDB bootstraps collections and indexes automatically. See Database Setup for step-by-step instructions.

Core tables and collections

The SQL schema creates these primary tables. MongoDB uses analogous collections created by the store module.

Table	Purpose
`ratchet_schema_version`	SQL schema migration/checksum tracking
`scheduler_job`	Cold job metadata, payload, and terminal state
`scheduler_business_key_reservation`	Active business-key reservation guard
`scheduler_job_queue`	Hot executable queue table for claim/poll state
`scheduler_job_tag`	Tags for job categorization and querying
`scheduler_job_execution`	Per-attempt execution history with timing and errors
`scheduler_job_log`	Optional per-job log entries if your application persists `JobLogLine` events
`scheduler_batch`	Batch progress tracking
`scheduler_batch_metrics`	Batch performance metrics
`scheduler_job_archive`	Archived completed/failed jobs
`scheduler_recurring_job`	Recurring job masters
`scheduler_recurring_job_archive`	Archived recurring job masters
`scheduler_node`	Cluster node heartbeats
`scheduler_lock`	Distributed lock management
`scheduler_resource_limit`	Resource concurrency configuration
`scheduler_resource_permit`	Active resource permits for concurrency control
`scheduler_workflow_condition`	Workflow branching conditions

Configuration

Ratchet requires a CDI-produced RatchetOptions bean. If no producer is found, CDI fails deployment with UnsatisfiedResolutionException and the scheduler never starts. This acts as a first-class kill-switch for any deployment that includes ratchet without wanting it active.

The CDI integration has one active Ratchet runtime per classloader because serializer, encryption, and masking state are shared by that classloader. Stop and let the previous deployment release its jobs before starting another CDI container that shares those Ratchet classes. This is a lifecycle constraint, not support for multiple independent runtimes in one classloader.

The producer may build options programmatically or read RATCHET_* environment variables and MicroProfile Config via RatchetOptionsFactory.fromEnvironment(). See Configuration for both patterns.

Key configuration areas:

Area	RatchetOptions path	Default
Thread pool	`execution.maxConcurrency("SINGLE", ...)`	`20`
Polling	`polling.minDelayMs(...)`	`2000`
Batch size	`polling.batchSize(...)`	`50`
Job retention	`maintenance.jobRetentionDays(...)`	`90`
Clustering / node health	`node.heartbeatIntervalSeconds(...)`	`10`

See Configuration for the full reference.

Monitoring and observability

Ratchet provides multiple monitoring integration points:

Event system: CDI events for job lifecycle (started, completed, failed, DLQ)
MetricsCollector SPI: plug in Micrometer or any custom metrics backend
MicroProfile Health: implement health checks against the job store
Store queries: direct SQL queries or MongoDB queries against Ratchet storage for dashboards

See Monitoring & Observability for integration guides.

Deployment checklist

Before going to production:

Apply or initialize storage: run schema SQL for MySQL/PostgreSQL/Oracle/SQL Server; let MongoDB initialize collections and indexes at startup
Configure the store resource: JNDI-bound, JTA-managed DataSource for SQL stores, or a CDI-produced MongoDatabase for MongoDB
Check store isolation support: MySQL supports its default REPEATABLE READ and READ COMMITTED; consult the database-specific guide for other stores
Tune polling: adjust polling.minDelayMs, polling.maxDelayMs, and polling.batchSize for your workload
Set up retention: configure maintenance.jobRetentionDays, maintenance.dlqPurgeDays, and maintenance.logRetentionDays to prevent unbounded table growth
Enable metrics: wire MetricsCollector to your monitoring stack
Configure wakeups if needed: if running multiple nodes and you want faster cross-node responsiveness, implement ClusterCoordinator
Test failover: verify jobs recover when a node goes down

Next steps

Runtime setup -- CDI, security policy, and container resources
Database Setup -- Schema application for all stores
Upgrading -- Version coexistence boundaries and rollout order
Configuration -- Full configuration reference
Docker Deployment -- Containerized deployments
Kubernetes Deployment -- Orchestrated deployments

Deployment Overview ​

What you need ​

Ratchet modules ​

Deployment scenarios ​

Single-node ​

Multi-node (clustered) ​

Containerized ​

Database schema ​

Core tables and collections ​

Configuration ​

Monitoring and observability ​

Deployment checklist ​

Next steps ​