Configuration

All settings live under the spring.batch.cluster.* namespace and are bound by BatchClusterProperties. Clustering is opt-in (enabled=true). Intervals and thresholds are in milliseconds; the defaults suit small-to-medium clusters (~2–20 nodes).

Property	Default	Description
capture-phase-timings	false	When true, records master-side coordination phase timestamps (received, partitioned, distributed, completion-detected) to the append-only BATCH_JOB_PHASE_EVENTS table, using the database clock. Off by default. Enables later reporting of coordination overhead; the table grows over time, so pair it with a retention/purge policy.
completed-tasks-cleanup-polling-interval	5000	How often a worker prunes its records of completed partition tasks.
concurrency-limit-per-node	10	Maximum number of partition steps this node executes concurrently.
enabled	false	Master switch for clustering. When false, none of the cluster components are activated.
heartbeat-interval	3000	How often this node updates its heartbeat (and refreshes its view of the cluster).
host-identifier	host-name	Whether a node registers itself in BATCH_NODES by host name or IP address.
initialize-schema	embedded	Whether the framework creates its cluster tables on startup, mirroring Spring Batch's own spring.batch.jdbc.initialize-schema. EMBEDDED (default) creates them only on genuinely in-memory embedded databases — it does not fire for file-mode H2 or any server database, which must create the cluster tables via spring.sql.init or a migration tool. ALWAYS always creates them; NEVER never does. For production, prefer a managed migration tool (Flyway/Liquibase) with NEVER, or apply the bundled DDL manually.
master-task-status-check-interval	500	Thread sleep time between each master-side check of overall partition completion.
node-cleanup-thread-interval	5000	How often the phase-2 sweep runs that removes long-unreachable nodes from the registry.
node-cleanup-threshold	30000	Heartbeat age after which an unreachable node is removed and its transferable partitions reassigned (phase 2).
node-id-prefix	—	Optional prefix for this node's auto-generated id. Defaults to the machine host name when unset. The actual node id is always <prefix>-<random-uuid>, generated once at startup, so it is guaranteed unique per JVM and per restart with no manual configuration.
orphaned-master-scan-interval	10000	How often each node scans for jobs whose master node has left the cluster, so the stranded (and otherwise permanently STARTED) job execution can be abandoned and made restartable.
orphaned-tasks-polling-interval	1000	How often the master scans for orphaned partitions (assigned to a lost node) to reassign.
task-polling-interval	1000	How often a worker polls BATCH_PARTITIONS for partitions assigned to it.
tracing-enabled	false	When true, emits verbose timing/diagnostic logs for heartbeats and polling. Keep off in production.
unreachable-node-thread-interval	5000	How often the phase-1 sweep runs that marks stale nodes UNREACHABLE.
unreachable-node-threshold	10000	Heartbeat age after which a node is marked UNREACHABLE (phase 1 of failover).

(The table above is generated from the @ConfigurationProperties source, so it never drifts from the code. The deprecated node-id property is intentionally omitted — see the note at the end of this page.)

The bundled example profiles use fast demo timings — don't copy them to production

So you can watch failover in seconds, the example profiles (application-h2.yml, application-postgres.yml, application-mysql.yml, application-oracle.yml) deliberately shorten these to heartbeat-interval: 1000, unreachable-node-threshold: 3000, node-cleanup-threshold: 5000 — so a dead node is removed in ~8s. Real deployments should keep the defaults above (a dead node is removed in ~75s): the longer thresholds tolerate GC pauses and brief network blips without prematurely evicting a healthy node and reassigning work it is still running.

Spring Batch core schema is a prerequisite

These tables have foreign keys to the standard Spring Batch tables, so the Spring Batch schema must exist first. Spring Boot 4 no longer auto-creates it — use Flyway/Liquibase or spring.sql.init (see Installation). The cluster auto-DDL runs after it via @DependsOnDatabaseInitialization.

Actuator exposure

The /actuator/batch-cluster endpoints expose node and partition detail. Restrict their exposure and protect them with authentication; do not expose them unauthenticated on a public interface.

The legacy node-id property has been removed (ids are generated automatically); a leftover value is ignored with a warning. Use node-id-prefix instead.