Handle legacy DB schema mismatch at startup

[rabanspiegel]

Summary

• add a strict post-migration schema contract check during DB initialization
• throw a typed DB_SCHEMA_MISMATCH error when required invariants are missing
• show a startup recovery dialog that lets users reset local DB files and relaunch before any project actions fail
• support EMDASH_DB_FILE override to make local DB-path testing safe and deterministic

Contract checks

• projects.base_ref exists
• tasks table exists
• conversations.task_id exists

Tests

• src/test/main/DatabaseService.schemaContract.test.ts
• src/test/main/DatabaseService.initializeSchemaMismatch.test.ts
• src/test/main/DatabasePath.test.ts

Validation

• pnpm run type-check
• pnpm exec vitest run src/test/main/DatabaseService.schemaContract.test.ts src/test/main/DatabaseService.initializeSchemaMismatch.test.ts src/test/main/DatabasePath.test.ts

---

Note

Medium Risk
Changes core startup/database initialization behavior and adds a destructive “reset local data” path; mistakes could block app launch or delete the wrong DB file if the resolved path is unexpected.

Overview
Adds an explicit EMDASH_DB_FILE override for database path resolution to make local DB selection deterministic (and testable).

Tightens DB startup by validating a post-migration schema contract and throwing a typed DatabaseSchemaMismatchError when required invariants are missing; app startup now catches this error and prompts the user to reset local DB files (including -wal/-shm) and relaunch or quit.

Includes new Vitest coverage for DB path override behavior and for distinguishing schema-contract failures from migration failures during DatabaseService.initialize().

^{Written by Cursor Bugbot for commit f9fb4ec. This will update automatically on new commits. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Feb 22, 2026 1:59am

[greptile-apps]

Greptile Summary

This PR adds schema validation to detect and handle legacy database files that lack required columns. It introduces a typed DatabaseSchemaMismatchError that is thrown when critical schema invariants (projects.base_ref, tasks table, conversations.task_id) are missing after migrations complete.

Key Changes:

• Added EMDASH_DB_FILE environment variable support for deterministic DB path override during testing
• Introduced post-migration schema contract validation that checks for 3 required invariants
• Added user-friendly startup recovery dialog that offers to reset local database and relaunch when schema mismatch is detected
• Comprehensive test coverage for DB path override, schema validation, and initialization error handling

Impact:
Users with legacy databases from very old versions will see a clear dialog explaining the issue and offering a one-click reset solution, preventing silent failures or cryptic errors during normal operation.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The implementation is well-structured with proper error handling, comprehensive test coverage, and follows existing patterns in the codebase. The schema validation logic is straightforward and defensive. The user-facing error dialog provides clear options without data loss risk.
• No files require special attention

Important Files Changed

Filename	Overview
src/main/db/path.ts	Added EMDASH_DB_FILE environment variable override support with absolute path resolution
src/main/services/DatabaseService.ts	Added DatabaseSchemaMismatchError class and validateSchemaContract() to check for required schema invariants after migrations
src/main/main.ts	Added startup recovery dialog for schema mismatch errors with database reset and relaunch functionality

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    Start[App Startup] --> Init[databaseService.initialize]
    Init --> Migrate[ensureMigrations]
    Migrate --> Validate[validateSchemaContract]
    
    Validate -->|Check 1| CheckBaseRef{projects.base_ref exists?}
    CheckBaseRef -->|No| AddMissing1[Add to missingInvariants]
    CheckBaseRef -->|Yes| CheckTasks
    AddMissing1 --> CheckTasks
    
    CheckTasks{tasks table exists?} -->|No| AddMissing2[Add to missingInvariants]
    CheckTasks -->|Yes| CheckTaskId
    AddMissing2 --> CheckTaskId
    
    CheckTaskId{conversations.task_id exists?} -->|No| AddMissing3[Add to missingInvariants]
    CheckTaskId -->|Yes| CheckList
    AddMissing3 --> CheckList
    
    CheckList{missingInvariants.length > 0?} -->|Yes| ThrowError[Throw DatabaseSchemaMismatchError]
    CheckList -->|No| Success[Initialization Complete]
    
    ThrowError --> ShowDialog[Show Recovery Dialog]
    ShowDialog -->|User: Reset & Relaunch| DeleteDB[Delete DB files WAL SHM]
    ShowDialog -->|User: Quit| AppQuit[app.quit]
    
    DeleteDB --> Relaunch[app.relaunch + app.exit]
    DeleteDB -->|Delete fails| ErrorBox[Show error dialog]
    ErrorBox --> AppQuit
    
    Success --> ContinueStartup[Continue app startup]

Loading

_{Last reviewed commit: 3a79a7a}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}