Database upgrades & migrations (what happens to your data when you update Omniscio)

What it is

Short answer: yes — your database upgrades itself automatically, and your data is preserved. When you run a newer version of Omniscio for the first time, it quietly brings the structure of your existing database up to date — no prompt, no manual step, nothing for you to do. Before it changes anything it saves a complete backup copy, so an upgrade can't lose your data.

Omniscio keeps everything — your projects, sessions, every chat message, settings, snippets, and recipes — in a single SQLite database file called mission-control.db, stored in Omniscio's app-data folder.

As Omniscio gains features, the shape of that database changes: new tables, new columns, new indexes. Omniscio keeps track of exactly which of these structural updates your database has already received, so a new build can apply only the ones you're missing.

A migration is one small, ordered step that updates the database's structure (for example, "add the alarm recurrence columns"). Migrations only ever add structure — they never delete your conversations or settings.

There are two kinds of step, and your database records both so none is ever run twice:

• The frozen baseline — the original ~260 numbered steps that built up Omniscio's database shape over its first year. This series is now closed (the highest number is 261); it never grows again. Your database records the highest baseline number it has reached.
• Dated steps (the "ledger") — every new structural change going forward is a single dated step with its own name. Your database keeps a checklist of which dated steps it has run and, on each launch, runs any it hasn't seen — in date order. This is what lets several developers add database changes at the same time without stepping on each other.

Either way the effect on your data is identical and the safety guarantees below apply to both.

Where to find it

There is nothing to open and nothing to switch on — the upgrade happens by itself in the moments behind the splash screen the first time you launch a newer version. The two places it can surface to you are your inbox, which carries a notice if you ever roll back to a build older than your data, and Settings → Backup, which is where the one-click restore lives if an upgrade step itself fails. The pre-upgrade copies themselves sit in a backups folder inside the app's own data folder, described below.

How it behaves

What happens when you launch a new version

Every time Omniscio starts, before the main window opens, it checks which structural updates your database is missing:

1. Your database is behind the build — the normal case right after an update. Omniscio runs every update your database hasn't received yet, in order, one after another. If you skipped several releases it simply runs all the missing steps in sequence to catch up. When it finishes, your database records the steps it ran and the app opens normally.
2. Your database is already current. Nothing to do; Omniscio opens immediately.
3. Your database is ahead of the build — you rolled back to an older Omniscio. See Downgrades below.

This all happens in the moments behind the splash screen. You never see a migration prompt — it's automatic and required, because the new code expects the new shape.

However you got the new version

The migration step is the same no matter how the new build arrived on your machine:

• Installed (Setup) builds can download and install updates themselves (via electron-updater).
• Portable builds are updated by re-downloading the newer portable file and running it.
• Either way, the new build opens the same mission-control.db already sitting in your app-data folder and migrates it in place. Your data doesn't move — only its structure is brought up to date.

Your data is backed up first

Before Omniscio applies any migration, it writes a complete copy of your current database into a backups folder inside Omniscio's app-data folder, named after the version it's leaving — for example mission-control-v210.db. This copy is taken only when there's actually an upgrade to perform, and Omniscio keeps the 3 most recent pre-upgrade backups, pruning older ones.

So if an upgrade ever went wrong, the exact state of your database from just before the upgrade is sitting right there, untouched. (Taking this backup is fail-closed — if it can't be written, Omniscio refuses the upgrade and stops with a clear "Database Error" message that points you at the backups folder, rather than migrating with no rollback point.)

This pre-upgrade backup is separate from, and in addition to, Omniscio's other backup features:

• the routine timestamped backups Omniscio takes on its own,
• the weekly encrypted configuration backup emailed to Gmail (setup-backup.md),
• and the full encrypted snapshot mirrored to a cloud-sync folder (backup-mirror.md).

Downgrades (rolling back to an older version)

Omniscio migrates your database forward only. If you install an older build than the one that last touched your database — for instance, you roll back after trying a newer release — Omniscio does not undo the migrations. It notices that your database is newer than it expects and opens anyway against the newer database.

Most things keep working in this situation, but a feature here or there can misbehave because the older code doesn't understand the newer database shape. Because that just looks like "the app is acting strange", Omniscio also puts a notice in your inbox — "This version of Omniscio is older than your data" — explaining what happened and what to do, with a one-click button to your Backup settings. It clears itself the moment you are back on a build that understands your data.

Two ways out, either of which removes the notice:

• Update forward again to the newer version — nothing is lost, and this is the safe fix.
• Stay on the older version and restore one of the pre-upgrade backups from the backups folder (the mission-control-vNNN.db copy dated before you upgraded).

Safety — why an upgrade won't lose your data

• A full backup is taken before any migration runs (see above), and the 3 most recent are kept.
• Migrations are additive. They add tables, columns, and indexes; they don't drop your conversations, projects, or settings.
• They run in order and only once each. A version number records what's already been applied, so re-launching never re-runs a completed migration or skips one.
• Omniscio checks the database for corruption at startup. If the file is damaged for reasons unrelated to migrations (a bad disk, an interrupted write), Omniscio detects it and can point you to restoring from a backup rather than running on a broken file.
• A missing piece of structure is rebuilt, not a crash. In the rare case a database is left structurally inconsistent — for example missing a whole table it should have, from an interrupted copy or an external tool — a migration that needs that table would once have stopped Omniscio from opening (a "Database Error" at startup). Omniscio now notices, rebuilds the missing structure automatically (it only ever adds what's absent — it never touches what you already have), and continues starting normally.
• A failed upgrade can't trap the app in a restart loop. In the very rare case an upgrade step itself fails (not just a missing table), older versions of Omniscio would show a generic "Database Error" and then hit the exact same failure on every relaunch — a crash loop with no way out for a non-technical user. Omniscio now recognizes the failed step, refuses to re-run it on the next launch, and offers a one-click Restore from backup that puts back the automatic pre-upgrade copy of your data. Installing the latest version clears the problem automatically, since the fix ships in the new build.

Limits and non-goals

• It's automatic and not optional. You can't decline a migration — the new code requires the new database shape. (You also don't need to: it backs up first.)
• It only moves forward. There is no automatic "downgrade migration." Rolling back is handled by restoring a pre-upgrade backup, not by Omniscio rewriting the database backward.
• It doesn't shrink the file. Migrations change structure, not size. Reclaiming disk space is a separate, opt-in action — see database-compaction.md.
• It isn't a substitute for your own backups. The pre-upgrade copies are a safety net for the upgrade itself, and Omniscio keeps only the most recent few. For long-term safety, use the configuration backup or the cloud-sync mirror.

For agents

Where this lives in the code

• On every startup initDatabase() runs the frozen baseline then the ledger (the frozen baseline now lives in src/main/db/incremental-migrations.ts):
  • Baseline — runIncrementalMigrations() walks its numbered if (needs(N)) blocks up to TARGET_VERSION (currently 261, frozen — never extended again); the highest number your database has reached is tracked in the schema_version table.
  • Ledger — runLedgerMigrations() in src/main/db/ledger-runner.ts discovers every dated step file under src/main/db/migrations/ (named <YYYYMMDDHHmmss>-<slug>.ts), and runs any not yet recorded in the applied_migrations table, in date order, each inside its own transaction. Developers create a new step with npm run db:new-migration "<description>".
• A pre-upgrade backup is taken before either path runs (whenever the baseline OR the ledger has anything to apply): backupBeforeMigration() / backupBeforeMigrationAsync() write mission-control-v<old>.db into <userData>/backups/ and keep MAX_BACKUPS = 3.
• If a dated step ever hits a missing table (a database left structurally inconsistent by something outside Omniscio), the ledger runs through runLedgerMigrationsResilient() in src/main/db/schema-self-heal.ts: it builds a pristine reference of the correct structure in a throwaway in-memory database, recreates the missing tables (with their indexes and triggers) in one transaction, and retries once — so the app recovers at startup instead of failing to open. It only ever adds absent structure, and degrades to the original clear error if a database is damaged in a way it can't rebuild.
• If a migration step itself throws (any failure, not only a missing table), the whole run is wrapped by runMigrationsWithFailureFlag() in src/main/db/migration-failure-flag.ts: it writes a <db>.migration-failed marker (recording which step failed and the app version), the next launch refuses to re-run that step (auto-clearing the marker when a newer app version is installed, so a shipped fix self-heals), and handleFatalStartupError() in src/main/app/diagnostics.ts offers to atomically restore the newest mission-control-v<N>.db pre-upgrade snapshot instead of looping. This backstops any migration throw, complementing the missing-table rebuild above.
• The forward-only migration system, its invariants, and the "add a migration" recipe are documented in .claude/memory/contracts/migration-ledger-contract.md; the non-blocking backup mechanism in .claude/memory/contracts/database-maintenance-contract.md. The full schema and history is in .claude/memory/data-model.md.

Related

Upgrades change the shape of the database and never its size; reclaiming disk space is a separate, opt-in action covered by database compaction. The pre-upgrade copies described here are only a short-term safety net for the upgrade itself — for the long-term ones, see the weekly encrypted setup backup emailing a copy to Gmail and the full encrypted Backup Mirror written to a cloud-sync folder. What a brand-new install does before there is any database at all is on first-time setup.

• database-compaction.md — the separate, opt-in action that physically shrinks mission-control.db (migrations change structure, not size).
• setup-backup.md — the weekly encrypted configuration backup emailed to Gmail.
• backup-mirror.md — the full encrypted snapshot (database included) written to a cloud-sync folder.
• first-time-setup.md — what happens on a fresh install, where the database is created and then migrated up to the current version.