Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Risky Area: Database
Main Files
src/main/db/schema.tssrc/main/db/initialize.tsdrizzle/
Rules
- never hand-edit numbered migrations
- never hand-edit
drizzle/meta/ - use
pnpm exec drizzle-kit generatefor new migrations - treat schema invariants and data migrations as high risk
Current Behavior
- database path is resolved by main-process db path helpers
SWITCHDASH_DB_FILEoverrides the default location- drizzle-kit (
push,migrate,studio) opens the database in the dev data folder:SWITCH_CONSOLE_USER_DATA_DIRwhen it names one,switchdash-devotherwise, andSWITCHDASH_DB_FILEover both; never point it atswitchdash, which stable and Canary share and which refuses to open once it has a migration the app does not know - database initialization happens in
src/main/db/initialize.ts
Development Workflow
Tooling folder
All dev and test infrastructure lives in tooling/ inside apps/switch-console-desktop/.
Nothing in tooling/ is part of the production Electron bundle — the @tooling
alias only exists in vitest.config.ts, not in electron.vite.config.ts.
tooling/
├── fixtures/ committed SQLite snapshots (empty.db, baseline.db)
├── node-deps/ isolated better-sqlite3 compiled for system Node
├── seeds/ seed functions that populate fixtures
├── generate-fixtures.ts fixture generator script (run via vitest)
└── utils/
└── db.ts openFixture() helper for migration tests
Isolated dev database
Point SWITCHDASH_DB_FILE at a scratch path instead of using the default database
when working on migrations, so schema experiments cannot corrupt your real app
data. pnpm run db:reset wipes the default dev databases.
SWITCHDASH_DB_FILE=/tmp/switchdash-scratch.db pnpm run dev # start app with isolated dev database
pnpm run db:reset # wipe the dev databases and start fresh
Fixture databases
Two committed SQLite snapshots live in tooling/fixtures/:
empty.db— all migrations applied, no databaseline.db— projects, sessions across lifecycle statuses, and conversations (see seeds intooling/seeds/)
Regenerate after any schema change:
pnpm run db:fixtures # writes .db files — no rebuild needed
db:fixtures and test:migrations use an isolated copy of better-sqlite3
installed under tooling/node-deps/ (compiled for system Node). The app's
node_modules/better-sqlite3 stays Electron-compiled at all times.
Migration authoring checklist
Isolate your dev DB: run the app with
SWITCHDASH_DB_FILEpointing at a scratch path so you're not working against your personal Switch Console databaseSnapshot the pre-migration baseline:
cp tooling/fixtures/baseline.db tooling/fixtures/pre-XXXX.dbCommit this snapshot. It is the starting state your migration test will run against.
Write the migration: edit
src/main/db/schema.ts, then generate the SQL:pnpm run db:generateWrite a migration test in
src/main/db/tests/migrations/usingopenFixture('pre-XXXX'). Seeexample.test.tsin that directory for the pattern.Regenerate fixtures so
baseline.dbandempty.dbinclude the new schema:pnpm run db:fixturesRun migration tests:
pnpm run test:migrationsCommit everything together: migration SQL (
drizzle/),drizzle/meta/,pre-XXXX.db, updatedtooling/fixtures/*.db, the migration test.
Versioned JSON columns
What they are
Some text() columns store structured JSON that may evolve across app versions.
These columns use versionedJsonColumn() — a Drizzle customType that
transparently handles version detection, upgrade chains, and serialization.
import { versionedJsonColumn } from '@main/db/versioned-column';
import { myConfig } from '@shared/my-config';
export const myTable = sqliteTable('my_table', {
col: versionedJsonColumn(myConfig)('col'),
// inferred type: MyConfig | null
});
Drizzle's fromDriver runs the full upgrade chain on read. toDriver always
serializes the latest version on write. No JSON.parse or JSON.stringify is
needed at call sites.
Schema definitions
Versioned schema definitions live in src/shared/. See
agents/conventions/versioned-schemas.md for the full guide including the
defineVersionedSchema() builder API, upgrade function patterns, and testing
guidance.
Column inventory
| Column | Schema file |
|---|---|
agents.provider_config |
src/shared/core/agents/agent-provider-config.ts |
sessions.config |
src/shared/core/sessions/session-config.ts |
Snapshot columns and raw SQL
versionedJsonColumn only hooks into ORM-level reads and writes. Any column written
via raw SQL bypasses fromDriver/toDriver. Those columns remain text() — call
schema.parseJson(row.col) explicitly on read and JSON.stringify on write.
Risky operations
- Removing a field from a schema: always keep the field as
.optional()or provide an upgrade function that drops it. Removing it silently breaks old rows that still carry the field. - Renaming a field: requires a new version with an upgrade function.
- Changing a field type in place: requires a new version. Never change a field type within an existing version.
- Adding a required field without a default: must either be
.optional()or require an upgrade function that supplies a default value.
Testing utilities
openFixture(name)intooling/utils/db.ts— copies a named fixture to a temp file, applies any pending migrations (via our owninitializeDatabase()), returns aDrizzleClient. Each call is fully isolated;close()deletes the temp file. Import via@tooling/utils/db(alias available in all Vitest projects).- Migration tests live in
src/main/db/tests/migrations/and run viapnpm run test:migrations(separate from the main test suite because they useimport.meta.glob, which requires Vite's transform pipeline).