Upgrading

Versions that must match

Rule	Why
Every process that conducts joobq-pro workflows on the same Redis runs joobq-pro 0.4.1 or later (this server pins ~> 0.4.1)	An older engine ignores a blueprint's task queue and would send SDK steps to Crystal workers
Every SDK worker of a task queue whose blueprints use heartbeat_ms runs an SDK release that beats	An older worker ignores the task's heartbeat_ms, never beats, and its steps are timed out
An SDK talks to a server of its own version or later	An older server drops the blueprint fields it does not know
Upgrade every process before the first worker build promote or re-pin, and before a definition with scopes is registered	Older code cannot read build_pinned events or fold scope events
Redis 6.2 or newer	The SDK gateway and JoobQ need it

Order

In short: Crystal workers, then the server, then the SDK workers.

1. Back up PostgreSQL (see Backups and retention).
2. Upgrade the workers that conduct workflows (Crystal workers with joobq-pro).
3. Run the new server's migrations (./joobqui migrate, or let the first instance apply them at start: the migrator holds a PostgreSQL advisory lock, so several instances starting at once do not race).
4. Replace the server instances one by one; on SIGTERM each one hands its leader leases over.
5. Upgrade the SDK workers: an SDK talks to a server of its own version or later (an older server drops the blueprint fields it does not know), so they come after the server.

Runs in flight

• An SDK workflow run keeps the blueprint version it started with: a worker that registers a changed blueprint gets a new content hash, and only runs started after that use it.