Ratchet

Appearance

Upgrading ​

Upgrade from 0.5.0 to 0.5.1 ​

SQL stores gain V009__drop_node_info.sql, which drops the unused scheduler_node.node_info column. Ratchet never wrote to it, so no data is lost. Apply it through the configured migration mechanism, or use the updated canonical schema for new installations. MongoDB needs no change; existing node documents may still carry an empty node_info field, which Ratchet ignores.

MySQL also gains V010__widen_text_columns.sql, which changes ten TEXT columns to MEDIUMTEXT. Values over 64 KB, such as large signal payloads, extension state, encrypted values and long error messages, then fit on MySQL as they already do on the other stores. To change a column type, MySQL copies the whole table, and writes to that table wait until the copy finishes. On a large installation, run this migration in a quiet window.

MySQL also gains V013__priority_int.sql, which changes priority from TINYINT UNSIGNED to INT on scheduler_recurring_job, scheduler_job, scheduler_job_queue and scheduler_job_archive, as the other stores already declare it. Hibernate schema validation then passes on MySQL without a mapping file. Values, defaults and check constraints are unchanged. Like V010, it copies each table and blocks writes to it until the copy finishes, so run it in a quiet window on a large installation.

Extension state is now limited to 1 MiB of UTF-8 per namespace on every store. A store rejects larger state with IllegalArgumentException.

Upgrade from 0.4.0 to 0.5.0 ​

0.5.0 adds no schema migrations. SQL stores stay at V008, and MongoDB needs no new initialization. Deploy matching API, engine, and store artifacts on every node.

Custom stores need no new contract methods, but 0.5.0 moves the schema metadata API and changes some store-core members. See the store TCK guide before rebuilding a custom store.

Upgrade from 0.3.1 to 0.4.0 ​

Moving from 0.3.1 to 0.4.0 introduces a permanent-idempotency ledger and atomic completion/recurring store contracts. This transition requires a coordinated upgrade. Stop all older writers and retention jobs before migrating; do not run mixed versions against the migrated database. Older binaries can bypass the ledger and the new atomic bookkeeping contracts even when their SQL remains syntactically compatible.

This coordinated shutdown applies to this storage-contract transition. Future releases can support rolling upgrades when their schema and behavior remain compatible, with mixed-version tests covering the supported source and target versions.

Upgrade order ​

  1. Back up the database and rehearse restore and migration against a copy.
  2. Stop submissions from every producer. Drain running jobs, then stop all scheduler nodes, retention workers, and administrative processes that can write Ratchet data.
  3. For MySQL, PostgreSQL, Oracle, and SQL Server, apply V007__permanent_idempotency_keys.sql, then V008__priority_ordered_claim_index.sql, through the configured migration mechanism before starting 0.4.0 workers. V007 backfills permanent reservations from surviving job rows; V008 adds the priority-ordered claim index. Use the updated canonical schema for new installations. Preserve the migration history; do not modify or rerun previously recorded migrations.
  4. Deploy matching API, engine, and store artifacts everywhere. Custom stores must implement JobTerminalStore.commitCompletion, RecurringJobStore.commitRecurringExecutions, RecurringJobStore.searchRecurring, RecurringJobStore.countRecurring, and JobCrudStore.findOriginalJobIdByIdempotencyKey before starting. Lease-based recurring stores must also preserve opaque claim ownership through commit/release.
  5. For MongoDB, start the first upgraded node while all older writers remain stopped. Initialization backfills permanent key reservations from surviving jobs. MongoDB must support transactions through a replica set or sharded deployment. Verify initialization succeeds before starting additional nodes and producers.
  6. Verify normal submission, duplicate submission, execution, recurring scheduling, and batch/chain completion. Resume retention and producer traffic after these checks pass.

Retention and historical limits ​

The scheduler_idempotency_key table or collection retains a minimal key, original job UUID, and reservation timestamp. It is deliberately independent of job-history retention and has no cascading foreign key. Do not purge its rows during normal archive cleanup. Its size grows with distinct keys, including automatically generated keys.

A repeated key returns the original job UUID after job history is deleted; detailed history may no longer exist. Concurrent submissions may still produce a duplicate-key exception for a losing transaction. Retry in a fresh transaction to resolve the original UUID. Idempotency prevents a second job from being created; execution retains Ratchet's at-least-once semantics.

Migration preserves keys on surviving job rows and all subsequent submissions. Keys already lost through archival or deletion before this upgrade cannot be recovered from the database. Reconcile external history separately if that historical guarantee is required.

Version and database boundaries ​

Earlier MySQL/PostgreSQL compatibility tests with 0.1.1 establish common row-format readability, not permission to use a mixed fleet with the new permanent-key or atomic-bookkeeping guarantees. There is no mixed-version guarantee for 0.1.0; its identifier/schema conversion remains a separate, stopped migration.

Rollback boundary ​

Keep old binaries stopped after enabling the new contracts. Rolling back only the binaries would allow writes that bypass permanent reservations. Use the rehearsed database-and-binary restore procedure if rollback is necessary, accounting for any work performed since the backup.