agent-orchestrator/docs/SWITCHING.md

Switching from Tauri to Electrobun

This guide covers migrating your data when switching from the Tauri v2/v3 build to the Electrobun build of AGOR.

Overview

Both stacks use SQLite for persistence but store databases in different locations with slightly different schemas. The migrate-db tool copies data from a Tauri source database into an Electrobun target database using the canonical schema as the contract.

This is a one-way migration. The source database is opened read-only and never modified. The target database receives copies of all compatible data. Running the tool multiple times is safe (uses INSERT OR IGNORE).

Prerequisites

• Bun >= 1.0 (ships with bun:sqlite)
• A working Tauri installation with existing data in ~/.local/share/agor/sessions.db
• The Electrobun build installed (creates ~/.config/agor/settings.db on first run)

Database Locations

Database	Tauri path	Electrobun path
Settings + sessions	~/.local/share/agor/sessions.db	~/.config/agor/settings.db
btmsg + bttask	~/.local/share/agor/btmsg.db	~/.local/share/agor/btmsg.db (shared)
FTS5 search	~/.local/share/agor/search.db	~/.local/share/agor/search.db (shared)

The btmsg and search databases are already shared between stacks -- no migration needed for those.

Steps

1. Stop both applications

Close the Tauri app and the Electrobun app if either is running. SQLite WAL mode handles concurrent reads, but stopping both avoids partial writes.

2. Back up your data

cp ~/.local/share/agor/sessions.db ~/.local/share/agor/sessions.db.bak
cp ~/.config/agor/settings.db ~/.config/agor/settings.db.bak 2>/dev/null

3. Run the migration

# Migrate settings/sessions from Tauri to Electrobun
bun tools/migrate-db.ts \
  --from ~/.local/share/agor/sessions.db \
  --to   ~/.config/agor/settings.db

The tool will:

• Open the source database read-only
• Apply the canonical schema to the target if needed
• Copy all matching tables using INSERT OR IGNORE (existing rows are preserved)
• Report per-table row counts
• Write a version fence to schema_version

4. Verify

Launch the Electrobun app and confirm your projects, settings, and session history appear correctly.

5. (Optional) Validate the schema

bun tools/validate-schema.ts | jq '.tableCount'
# Should output the number of tables defined in canonical.sql

Version Fence

After migration, the target database's schema_version table contains:

Column	Value
version	1
migration_source	migrate-db
migration_timestamp	ISO-8601 timestamp of the migration

This fence prevents accidental re-application of older schemas and provides an audit trail.

Troubleshooting

"Source database not found" -- Verify the Tauri data directory path. On some systems, XDG_DATA_HOME may override ~/.local/share.

"Schema application failed" -- The canonical.sql file may be out of sync with a newer database. Pull the latest version and retry.

"Migration failed on table X" -- The migration runs inside a single transaction. If any table fails, all changes are rolled back. Check the error message for column mismatches, which typically mean the canonical schema needs updating.

What is NOT Migrated

• FTS5 search indexes -- These are virtual tables that cannot be copied via SELECT *. Rebuild the index from the Electrobun app (Ctrl+Shift+F, then rebuild).
• Layout state -- The Electrobun UI uses a different layout system. Your layout preferences will reset.
• SSH key files -- Only the SSH connection metadata (host, port, username) is migrated. Private key files remain on disk at their original paths.