Docs / Operations Operate
Upgrades
Upgrading the binary, the console, the storage format and cached compilation output.
- Read the release notes and newest devlogs for changes that affect your workspace.
- Take a backup (
ekos home backup). For the console there is no downgrade. - Install the new version — the installer or package, or for the container
git pull(or a new image tag) anddocker compose -f deploy/docker-compose.yml up -d --build. Keep the old binary until you have verified. - Run
ekos doctorandekos config validate— unknown config sections are rejected. - The console upgrades its own database when it starts.
- Re-running the pipeline is not needed for an upgrade; it is how new compiler features reach an existing project. The build fingerprint includes the pipeline's logic version, so changed analyzers reprocess automatically; no manual
.ekoswipe is needed. For a project with model-backed passes a re-run costs money. - If a read-only client (MCP server) reports a stale search index, run
ekos ledger repaironce.
Search index format
From RFC 0229 (tantivy 0.27) the search index is written in a newer format. A newer EKOS reads an older index as it is; an older EKOS cannot read an index a newer one wrote, and runs without search (it says so) until the index is rebuilt. To go back, restore the backup.
Storage format migration
| From | To | Command |
|---|---|---|
| SQLite v1 | v2 compact | ekos ledger migrate |
| SQLite | fact engine (v3) | ekos ledger migrate --v3 |
An existing SQLite workspace is never migrated automatically. Migrate a copy first and compare ekos status before and after.
Cached output
A CompilerPass skipped as cached uses its version and inputs. If an upgrade changes a pass without bumping its version, clear with ekos clean and rebuild.