631fc2efc8
- schema/canonical.sql: 29 tables across 3 databases, CHECK constraints, foreign keys, 13 indexes, WAL mode, schema_version tracking - tools/validate-schema.ts: applies DDL to in-memory SQLite, extracts PRAGMA table_info + sqlite_master metadata as JSON - tools/migrate-db.ts: CLI for Tauri→Electrobun data migration with atomic transaction, version fencing, INSERT OR IGNORE - docs/SWITCHING.md: migration guide with prerequisites and troubleshooting
91 lines
3.7 KiB
Markdown
91 lines
3.7 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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.
|