v0.28.0 Migration Guide

Runs-store schema moves to version 13Section anchor link

Version 13 adds two columns to triggers and one index, in support of sparkwing runs submit. idempotency_key carries a caller's deduplication token under a partial unique index on (pipeline, idempotency_key), so repeat submissions of one pipeline with one key produce one run as a database guarantee. claim_seq counts how many times a trigger has been claimed, so a dispatch whose lease lapsed cannot write an outcome over the run a newer claim is producing. The migration is automatic and additive; existing rows carry the empty key and generation zero.

A version 13 store cannot be opened by Sparkwing v0.27.0 or earlier. Before any process migrates a shared local store, replace every CLI, daemon, and wrapper binary that can open it with v0.28.0 or later, then restart long-lived processes (the wingd daemon, a resident trigger consumer, a dashboard) from the upgraded binary. For an installation where processes do not share a store, upgrade each store's readers together. No configuration or pipeline source change is required.

One development-only edge: an interim build of the v0.28.0 branch, before the schema was finalized, produced a version-13 database without claim_seq. That shape was never released and fails submission with no such column: claim_seq; delete the development state.db ($SPARKWING_HOME/state.db, default ~/.sparkwing/state.db) and let it be recreated.