# Ratchet

> Ratchet is an open-source (Apache-2.0) distributed job scheduler for Java. It runs persistent background jobs, recurring schedules, batches and multi-step workflows across a cluster on Jakarta EE, Quarkus, Spring Boot and Micronaut, using the database you already run (PostgreSQL, MySQL, Oracle, SQL Server or MongoDB) as the queue.

This is Ratchet, the Java job scheduler at https://ratchet.run (source: https://github.com/ratchet-run/ratchet, Maven group run.ratchet). It is unrelated to ratchetphp/Ratchet (PHP WebSockets), Hatchet (hatchet.run) and sethvargo/ratchet.

## Table of Contents

### Use Cases

- [Offload Work After a Request](https://ratchet.run/use-cases/offload-after-request.md): Persist follow-up work in the same transaction as your business write, return the response immediately, and let Ratchet run the side effects on a worker, durably and with retries.
- [Scheduled & Recurring Jobs](https://ratchet.run/use-cases/scheduled-recurring-jobs.md): Cron and delayed jobs that survive restarts and never double-fire across a cluster, run inside the Jakarta EE server you already operate, with no separate scheduler.
- [Resilient Third-Party Integrations](https://ratchet.run/use-cases/resilient-integrations.md): Call flaky external APIs from durable jobs that retry transient failures with backoff and trip a circuit breaker during an outage, so a downstream provider going down does not take your work with it.
- [Durable LLM & Agent Workflows](https://ratchet.run/use-cases/durable-llm-workflows.md): Run LLM calls and multi-step agent workflows as persisted, retrying Ratchet jobs in a Jakarta EE app, with langchain4j-cdi supplying the model client.
- [Bulk & Batch Jobs](https://ratchet.run/use-cases/bulk-batch-jobs.md): Fan thousands of items out as one tracked batch, watch aggregate progress as it runs, and branch on the success rate when it finishes -- without writing the bookkeeping yourself.
- [Human-in-the-Loop Jobs](https://ratchet.run/use-cases/human-in-the-loop.md): Park a job in a waiting state until a person approves it, then resume exactly where it left off -- holding no thread, surviving restarts, and timing out on its own if nobody answers.

### Getting Started

- [Introduction](https://ratchet.run/getting-started/introduction.md): What Ratchet is (an open-source distributed job scheduler for Java on Jakarta EE, Quarkus, Spring Boot and Micronaut), why you would use it, and how it compares with other Java job schedulers.
- [Installation](https://ratchet.run/getting-started/installation.md): Add Ratchet to your Maven project with the BOM, choose your store module, and apply the database schema
- [Quick Start](https://ratchet.run/getting-started/quickstart.md): Schedule your first background job with Ratchet in under 5 minutes
- [Spring Boot](https://ratchet.run/deployment/spring-boot.md): Run persistent Ratchet jobs in Spring Boot 3.5 and 4.1 with SQL or MongoDB, Java 17 or 21, application transactions, and optional virtual threads.
- [Basic Concepts](https://ratchet.run/getting-started/basic-concepts.md): Core Ratchet terminology: jobs, schedules, stores, builders, contexts, and the CDI programming model
- [Your First Job](https://ratchet.run/getting-started/first-job.md): A complete walkthrough of creating a job with retries, backoff, parameters, callbacks, and event monitoring
- [Configuration](https://ratchet.run/getting-started/configuration.md): CDI producer setup, beans.xml requirements, and the required RatchetOptions bean

### Concepts

- [Architecture Overview](https://ratchet.run/concepts/overview.md): High-level architecture of Ratchet and how it fits into a Jakarta EE 10/11 application
- [Job Lifecycle](https://ratchet.run/concepts/job-lifecycle.md): Complete job state machine with transitions, guards, and edge cases
- [Job Types](https://ratchet.run/concepts/job-types.md): SINGLE, RECURRING, BATCH, CHAIN, WORKFLOW, and SYSTEM job types
- [Scheduling](https://ratchet.run/concepts/scheduling.md): Immediate, delayed, and cron-based job scheduling with adaptive polling
- [Execution Model](https://ratchet.run/concepts/execution-model.md): How jobs are polled, claimed, validated, executed, and post-processed
- [Error Handling](https://ratchet.run/concepts/error-handling.md): What happens when a job fails -- retries, DLQ routing, @DoNotRetry, and error sanitization
- [Retry Strategies](https://ratchet.run/concepts/retry-strategies.md): BackoffPolicy, RetryPolicy SPI, and how backoff delays are calculated
- [Batches](https://ratchet.run/concepts/batches.md): BatchBuilder for in-memory collections and StreamingBatchBuilder for large datasets
- [Workflows](https://ratchet.run/concepts/workflows.md): Job chaining, conditional branching, and WorkflowCondition types
- [Persistence](https://ratchet.run/concepts/persistence.md): Entity/document model, JobStore SPI composition, UUIDv7 identifiers, and constraint detection
- [Clustering](https://ratchet.run/concepts/clustering.md): ClusterCoordinator SPI, database-backed coordination, node identity, and multi-node consistency

### API Reference

- [API Reference Overview](https://ratchet.run/api-reference/overview.md): Index of Ratchet API classes, package structure, and how to navigate the reference documentation.
- [JobSchedulerService Reference](https://ratchet.run/api-reference/job-scheduler-service.md): Complete method reference for JobSchedulerService, the primary entry point for scheduling background jobs.
- [JobQueryService Reference](https://ratchet.run/api-reference/job-query-service.md): Read-only query API for dashboards, admin tools, job detail pages, history, and queue health.
- [JobBuilder Reference](https://ratchet.run/api-reference/job-builder.md): Complete reference for the JobBuilder fluent API for configuring and submitting individual jobs.
- [Job Options and Enums](https://ratchet.run/api-reference/job-options.md): Reference for JobOptions record, JobPriority, BackoffPolicy, and JobType enums.
- [BatchBuilder Reference](https://ratchet.run/api-reference/batch-builder.md): Complete reference for BatchBuilder and StreamingBatchBuilder for parallel and streaming batch job processing.
- [BatchContext Reference](https://ratchet.run/api-reference/batch-context.md): Reference for BatchContext and StreamingBatchContext records used for batch progress monitoring.
- [JobContext Reference](https://ratchet.run/api-reference/job-context.md): Thread-local access to job execution metadata, parameters, and logging during job execution.
- [JobResult Reference](https://ratchet.run/api-reference/job-result.md): Complete reference for JobResult, capturing job execution outcomes including success/failure, return values, timing, and metadata.
- [Annotations Reference](https://ratchet.run/api-reference/annotations.md): Declarative configuration annotations for recurring jobs, circuit breakers, retry control, and API stability.
- [Event System Reference](https://ratchet.run/api-reference/event-system.md): Complete reference for job lifecycle events, batch events, chain events, and event observation patterns.
- [Functional Interfaces](https://ratchet.run/api-reference/functional-interfaces.md): Reference for all serializable functional interfaces used in job definitions, callbacks, and workflow conditions.
- [WorkflowCondition Reference](https://ratchet.run/api-reference/workflow-condition.md): Reference for WorkflowCondition types, WorkflowBranch records, and priority-based workflow evaluation.
- [SPI Interfaces Reference](https://ratchet.run/api-reference/spi-interfaces.md): Extension points for customizing Ratchet behavior including retry, resilience, serialization, metrics, and clustering.

### Advanced

- [Customization Platform](https://ratchet.run/advanced/customization-platform.md): The supported CDI extension points for configuration, execution, payload resolution, logging, polling, and lifecycle hooks
- [SPI Implementation Guide](https://ratchet.run/advanced/spi-implementation.md): Complete guide to implementing Ratchet SPI interfaces for custom extensions
- [Circuit Breakers](https://ratchet.run/advanced/circuit-breakers.md): Built-in circuit breaker pattern for protecting job execution against cascading failures
- [Custom Retry Policies](https://ratchet.run/advanced/custom-retry-policies.md): Implementing custom retry policies for fine-grained control over job failure recovery
- [Payload and Result Customization](https://ratchet.run/advanced/custom-serialization.md): Customizing callback payload resolution and job result persistence
- [Payload Encryption](https://ratchet.run/advanced/payload-encryption.md): Encrypt sensitive job parameters and results at rest with authenticated encryption
- [Custom Logging](https://ratchet.run/advanced/custom-logging.md): Custom job-scoped logging with the JobLogger SPI
- [Metrics Collection](https://ratchet.run/advanced/metrics-collection.md): Collecting job execution metrics with the MetricsCollector SPI and Micrometer integration

### Deployment

- [Deployment Overview](https://ratchet.run/deployment/overview.md): What you need to deploy Ratchet: application server, database, modules, and configuration.
- [Runtime setup](https://ratchet.run/deployment/installation.md): Configure CDI, runtime options, ClassPolicy, and container resources after adding Ratchet dependencies
- [Configuration](https://ratchet.run/deployment/configuration.md): Configure Ratchet on Jakarta EE with a RatchetOptions producer, store resources, common options, per-job execution targets, the configuration source chain and SPI overrides.
- [Configuration reference](https://ratchet.run/deployment/configuration-reference.md): Complete property and environment-variable reference generated from Ratchet's typed configuration catalog
- [Spring Boot](https://ratchet.run/deployment/spring-boot.md): Run persistent Ratchet jobs in Spring Boot 3.5 and 4.1 with SQL or MongoDB, Java 17 or 21, application transactions, and optional virtual threads.
- [Quarkus Deployment](https://ratchet.run/deployment/quarkus.md): Run Ratchet on Quarkus, on the JVM and as a GraalVM native image, with the ratchet-quarkus extension.
- [Micronaut](https://ratchet.run/deployment/micronaut.md): Run persistent Ratchet jobs in Micronaut 4.10 and 5 with SQL or MongoDB, using the application's datasource, Hibernate session factory, and transactions.
- [Database Setup](https://ratchet.run/deployment/database-setup.md): Setting up MySQL, PostgreSQL, Oracle, SQL Server, or MongoDB for Ratchet: schema application, DataSource configuration, and connection pooling.
- [Upgrading](https://ratchet.run/deployment/rolling-upgrades.md): Upgrade steps between Ratchet releases, including the coordinated 0.3.1 to 0.4.0 storage-contract upgrade.
- [MySQL Deployment](https://ratchet.run/deployment/mysql.md): Run Ratchet on MySQL 8+. Covers schema setup, configuration, schema design, performance tuning, monitoring, maintenance and backup.
- [PostgreSQL Deployment](https://ratchet.run/deployment/postgresql.md): Run Ratchet on PostgreSQL 14+. Covers schema setup, configuration, advanced features, performance tuning, monitoring, maintenance, backup and high availability.
- [Oracle Deployment](https://ratchet.run/deployment/oracle.md): Run Ratchet on Oracle Database 23ai. Covers prerequisites, schema setup, configuration, Oracle dialect notes and schema auto-migration.
- [SQL Server Deployment](https://ratchet.run/deployment/sqlserver.md): Run Ratchet on Microsoft SQL Server 2022. Covers prerequisites, schema setup, configuration, T-SQL dialect notes and schema auto-migration.
- [MongoDB](https://ratchet.run/deployment/mongodb.md): Setting up the MongoDB store: collections, indexes, configuration, and migration from SQL stores
- [Clustering](https://ratchet.run/deployment/clustering.md): Running Ratchet across multiple nodes: claim-based execution, node heartbeats, wakeup coordination, and failure detection
- [Cluster Coordinators](https://ratchet.run/deployment/cluster-coordinators.md): First-party push-based cross-node wakeup modules: delivery guarantees, configuration, failure behavior, metrics, and the polling fallback floor
- [Docker Deployment](https://ratchet.run/deployment/docker.md): Running Ratchet applications in Docker with WildFly or Payara, including Docker Compose examples.
- [Kubernetes Deployment](https://ratchet.run/deployment/kubernetes.md): Deploying Ratchet on Kubernetes with Deployments, StatefulSets, ConfigMaps, and health probes.
- [Cluster Configuration](https://ratchet.run/deployment/cluster-configuration.md): Running Ratchet across multiple nodes: ClusterCoordinator, NodeIdentityProvider, recurring job deduplication, and distributed locking.
- [Multi-Cell Deployment](https://ratchet.run/deployment/multi-cell.md): Running several independent Ratchet cells side by side (one store per cell) for tenant isolation or throughput beyond a single shared store.
- [Performance Tuning](https://ratchet.run/deployment/performance-tuning.md): Tuning Ratchet's polling intervals, thread pools, batch sizes, timeouts, and database for high-throughput job scheduling.
- [Monitoring](https://ratchet.run/deployment/monitoring.md): Micrometer metrics, event-based monitoring, health checks, and alerting patterns for Ratchet deployments
- [Deployment Troubleshooting](https://ratchet.run/deployment/troubleshooting.md): Diagnosing and fixing common deployment problems: schema issues, connection failures, clustering problems, and performance bottlenecks

### Troubleshooting

- [Troubleshooting Overview](https://ratchet.run/troubleshooting/overview.md): How to diagnose issues with Ratchet, configure logging, and use the event system for debugging.
- [Common Issues](https://ratchet.run/troubleshooting/common-issues.md): Solutions for frequently encountered problems with Ratchet job scheduling, serialization, security, and database errors.
- [Debugging Guide](https://ratchet.run/troubleshooting/debugging.md): How to debug Ratchet jobs using event listeners, database queries, CDI observers, and optional per-job logging.
- [FAQ](https://ratchet.run/troubleshooting/faq.md): Frequently asked questions about Ratchet job scheduling, deployment, retry behavior, and compatibility.

### Compare

- [How Ratchet compares](https://ratchet.run/comparison/overview.md): Side-by-side comparisons of Ratchet with Quartz, JobRunr, Spring Batch, jBeret, and db-scheduler, including where each competitor wins.
- [Ratchet vs Quartz](https://ratchet.run/comparison/vs-quartz.md): How Ratchet differs from Quartz Scheduler in API design, persistence, CDI integration, and resilience, with honest tradeoffs.
- [Ratchet vs JobRunr](https://ratchet.run/comparison/vs-jobrunr.md): How Ratchet differs from JobRunr on lambda capture, DI model, store options, dashboard, licensing, and commercial support.
- [Ratchet vs Spring Batch](https://ratchet.run/comparison/vs-spring-batch.md): Why Spring Batch and Ratchet are different tools for different problems, and when you actually need each.
- [Ratchet vs jBeret (Jakarta Batch / JSR-352)](https://ratchet.run/comparison/vs-jberet.md): How Ratchet differs from jBeret and the Jakarta Batch spec, when to pick each, and where the spec itself is the deciding factor.
- [Ratchet vs db-scheduler](https://ratchet.run/comparison/vs-db-scheduler.md): When the smaller, simpler db-scheduler is the better choice, and when Ratchet's extra features earn the extra weight.


### Other

- [Untitled](https://ratchet.run/public/javadoc/legal/jquery.md)
- [Untitled](https://ratchet.run/public/javadoc/legal/jqueryUI.md)