Omniscio

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

What happens to your data the first time you run a newer version of the app: the database upgrades itself silently behind the splash screen, a full backup is taken first, and nothing you have written is ever deleted. Also covers rolling back to an older version, the restart-loop guard, and what migrations deliberately do not do.

On this page

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 makes sure a rollback copy exists: usually a fresh complete copy taken right then, or — with automatic backups on — a recent one from the last few hours (see "Your data is backed up first").

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"). Almost all of them only add structure. A migration can be flagged as destructive when it has to drop an index, a column, or rows the app no longer uses, and such a step may delete data (for example the 2026-10-11 step that purged AI-coaching memories you had already deleted, which still sat in the database). A destructive step is rare, is written to touch only what the feature has already discarded, and always forces a fresh pre-upgrade copy (see below) — but "migrations never delete anything" is not a guarantee the code makes.

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 for the version it's leaving and the moment it was taken — mission-control-v261-1750000000000.db (version, then the millisecond timestamp). This copy is taken only when there's actually an upgrade to perform, and Omniscio keeps ONE pre-upgrade backup, pruning the previous one.

So if an upgrade ever went wrong, a rollback copy is sitting right there in the backups folder. It is not always the exact instant before the upgrade, though: with automatic backups on (the default), startup reuses a rollback point it already has when one is no more than 6 hours old — either a pre-upgrade snapshot or an automatic backup of the same database version, which it links in under the standard snapshot name. In that case the copy is up to ~6 hours older than the upgrade, so anything written in those hours is not in it. A fresh copy is always taken (no reuse) when automatic backups are off, and whenever a pending migration is flagged destructive. (Taking the 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.

The notice keys only on an update step that is newer than the newest one your build ships. A leftover record of an older step that was later renamed or withdrawn does not count, so a fully up-to-date install never shows it.

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 the pre-upgrade backup from the backups folder — the mission-control-vNNN-<milliseconds>.db copy dated before you upgraded. Pick it by date, never by the vNNN in its name: since the numbered baseline froze at 261 every copy carries the same version number, so the version cannot identify one.

The installed app opened on newer data (for example, Omniscio Dev's)

If you open the installed Omniscio on data a newer version wrote, the notice depends on whether this computer has a second, newer copy of Omniscio:

  • You develop Omniscio and the installed app is your fallback while Omniscio Dev is broken — the notice reads "You are using the installed Omniscio on newer data — reopen Omniscio Dev when it works again", and says to reopen Omniscio Dev as soon as it works again.
  • You don't — the newer data came from a newer release than the copy now installed (an update you rolled back, say). The notice reads "This installed Omniscio is older than your data" and says to update Omniscio, because naming a Dev build you have never installed would send you looking for something that isn't there — that is exactly what a version 0.1.125 install was told in November 2026, on data a 0.1.129 release had written.

Either way it opens normally: nothing is deleted, rolled back or blocked, and it tells you some newer features may misbehave here. (Whether a Dev copy exists is recorded by that copy the first time it opens your profile; a computer that has never run one is never told about it.)

On an installed build the notice is also shown once per launch as a banner across the top of the window, not only as an inbox row, so it cannot sit unnoticed. Open jumps to the full card (on this banner it never sends you to Backup settings, because restoring an older backup would roll back the newer data); × hides the banner until the next launch. A copy of Omniscio run from source (npm run dev) shows no banner and keeps the older wording, because a developer build behind the data is routine there.

Safety — why an upgrade won't lose your data

  • A rollback copy always exists before any migration runs (see above) — a fresh full copy, or with automatic backups on a reused one no more than ~6 hours old — and only the most recent pre-upgrade backup is kept (a new upgrade replaces the previous one).
  • Migrations are almost always additive. They add tables, columns, and indexes; they don't drop your conversations, projects, or settings. The rare destructive step (dropping an index, or rows a feature has already discarded) is flagged, forces a fresh rollback copy, and is built not to touch live content.
  • 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 copy is a safety net for the upgrade itself, and Omniscio keeps only the most recent one. For long-term safety, use the configuration backup or the cloud-sync mirror.

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.

Last verified 2026-10-21