The database and migrations
All state lives in one SQLite file, comfyui-desktop.db in the data folder, opened
by main with better-sqlite3 (src/main/database.ts). The window never opens it.
Tables
| Table | Holds |
|---|---|
settings | One row: the non-secret settings (provider, model, addresses, language, motion) and preferences_json, the validated preferences. |
secret_records | Saved keys and tokens, encrypted by the system password store. |
projects | Projects and the version each one shows (current_revision_id). |
graph_revisions | Every version of every graph: nodes, links, the ComfyUI document, components, title and notes, and who made it. |
applied_commands | Every command applied: its actionId, actor, run, payload and result. |
runs | The assistant's runs and their state. |
proposals | The assistant's drafts. |
explanations | Explanations of node types, models, links and objects of a graph, with their source. |
chat_messages | The chat, while Keep chat history in the project is on. |
node_catalog, node_packs, model_catalog | What was read from ComfyUI, with model metadata and web lookups. |
sync_state | The state of the sync as keys and values: the last sync, auto-sync and its interval. |
schema_migrations | Which schema versions were applied, and when. |
Opening
openDatabase in src/main/database.ts:
- A file whose schema version is newer than this app knows is refused before anything is written ("Your data was saved by a newer version…").
- The journal is WAL;
secure_deleteis on, so a forgotten key is overwritten, not left in free pages. - Before an upgrade, the file is copied to
comfyui-desktop.db.before-v<N>.bak(only the newest copy is kept) (src/main/settings/databaseSafety.ts). migratebrings the schema toSCHEMA_VERSION(src/main/settings/migrate.ts).- A failure is classified (damaged, newer, read-only, full, busy) and shown in words; a damaged file can be renamed
to
comfyui-desktop.db.damaged-<date>and the app starts with empty data.
Adding a migration
- Raise
SCHEMA_VERSIONinsrc/main/settings/migrate.tsand describe the new version in the comment above it, in one sentence: what it adds and why. - Write
applyVersionN(db). Make it safe to run on any database of the previous version: check withcolumnNames/tableNamesbeforeALTER TABLE, useCREATE … IF NOT EXISTS, give new columns a default. - Add the step to
migrate, in its own transaction that also writes theschema_migrationsrow, like the steps before it. - Never change an older
applyVersion…: databases out there already went through it. - Test it in
tests/unit/settingsMigration.test.ts: a database at the previous version with real rows upgrades, keeps its rows, and a failure before the version stamp leaves it as it was.
A newer database is never opened by an older app, so plan a change that people can live with when they go back: the app refuses and says so; their data stays untouched.