Upgrades

Supported paths

v1.0.0 supports fresh installations and upgrades from the previous main schema (feda9b1) or an earlier published release. Those versions have no transaction hash chain; this release introduces canonical v3 directly. The intermediate, unreleased v2 migration set (44eddbc) is outside the supported paths. See the changelog for everything in the release.

Procedure

# 1. Back up PostgreSQL and confirm the restore works.# 2. Stop old API servers and workers.$ ledgerforge version$ ledgerforge migrate up# 3. Start the new servers and workers, then check:$ ledgerforge verify$ ledgerforge audit verify

1. Back up first. The first checkpoint export anchors history from that point; it isn't retroactive external custody.
2. Stop old servers and workers during the transition: they don't persist immutable execution controls.
3. Run migrations in a maintenance window with a bounded PostgreSQL lock_timeout, retrying if busy writers block the brief exclusive lock.
4. Start compatible processes and run both read-only checks. They report unsupported legacy rows and pending coverage separately.

What the integrity migrations do

Migration 1781162340 adds nullable chain versions without updating the transaction table. 1781162341 builds the journal lookup index concurrently and validates the chain constraint separately. 1791504100 adds nullable execution controls without a data rewrite, and 1791504101 validates its constraint separately. Concurrent index builds and validation still scan tables, so budget time, I/O and disk for large installations. If a concurrent index build is interrupted, check pg_index.indisvalid, drop the invalid index concurrently and rerun migrations before starting workers.