Add database management API and automatic migration backups

[wpfleger96]

Summary

This PR adds a database management API that enables users to backup, restore, and monitor their session database, along with automatic safety backups before schema migrations. This protects users from data loss during upgrades and provides easy recovery options if migrations fail.

Users previously had no visibility into their database state and no easy way to recover from failed migrations or accidental data loss. The database file location was opaque, backups required manual file copying, and schema migrations happened silently without safety nets. This created risk during upgrades and made troubleshooting difficult.

Implementation adds 6 new CLI commands and comprehensive backup infrastructure:

• goose db status - shows database location, size, schema version, session/message counts, and backup information
• goose db backup [--output <NAME>] - creates validated manual backups with optional custom output paths
• goose db restore <FILENAME|PATH> [--force] - restores from backups using either filename (e.g., backup_20251030_202327.db) or full path, with confirmation prompts and safety backups
• goose db list-backups [--format <json|table>] - displays all available backups with size and age in table or JSON format
• goose db delete-backup [FILES...] [--all] [--cleanup] [--force] - removes backup files (supports multi-file deletion, --all flag, and --cleanup for orphaned SQLite wal/shm auxiliary files)
• goose db path - prints the database file location for scripting

Implementation details:

• Modified SessionManager::run_migrations() to automatically create validated backups before applying schema migrations using format pre_migration_v{old}_to_v{new}_{timestamp}.db
  • Automatic backups are best-effort and will allow migrations to proceed if backup fails (e.g. in case of filesystem error)
• Added backup validation with file size verification and SQLite integrity checks (PRAGMA quick_check)
• Created backup directory management in Paths::backup_dir() using platform-specific data directories
• Added REST API endpoints (GET /database/status, GET /database/backups, POST /database/backup, POST /database/restore, DELETE /database/backups/delete) for desktop app integration with full OpenAPI spec generation
  • API endpoints include operation locking (409 Conflict response) to prevent concurrent database operations

Type of Change

• Feature
• Bug fix
• Refactor / Code quality
• Performance improvement
• Documentation
• Tests
• Security fix
• Build / Release
• Other (specify below)

Testing

Manually tested, and also added new test test_backup_restore_round_trip

[github-actions]

PR Preview Action v1.6.0
🚀 View preview at https://block.github.io/goose/pr-preview/pr-5490/
Built to branch gh-pages at 2025-10-31 19:21 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[Copilot]

Pull Request Overview

This PR adds comprehensive database backup and restore functionality to Goose, replacing the previous manual shell script (goose-db-helper.sh) with native CLI commands and REST API endpoints. The implementation provides automatic backup creation before migrations, manual backup/restore operations, and backup management capabilities.

Key Changes

• Adds database backup/restore management commands (goose db) to the CLI with status, backup, restore, list-backups, and delete-backup subcommands
• Implements REST API endpoints (/database/backup, /database/restore, /database/backups, /database/status) for database operations
• Removes the deprecated scripts/goose-db-helper.sh script in favor of the new native implementation
• Updates documentation with database recovery instructions and command references

Reviewed Changes

Copilot reviewed 17 out of 18 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
ui/desktop/src/api/types.gen.ts	Generated TypeScript types for new database management API endpoints
ui/desktop/src/api/sdk.gen.ts	Generated TypeScript SDK functions for database operations
ui/desktop/openapi.json	OpenAPI specification for database management endpoints
scripts/goose-db-helper.sh	Removed deprecated shell script
documentation/docs/troubleshooting.md	Added database recovery documentation
documentation/docs/guides/goose-cli-commands.md	Documentation for new goose db commands
crates/goose/src/session/session_manager.rs	Core database backup/restore implementation with validation
crates/goose/src/scheduler.rs	Updated to use async ensure_session_dir()
crates/goose/src/config/paths.rs	Added backup_dir() helper method
crates/goose-server/src/routes/mod.rs	Registered database routes module
crates/goose-server/src/routes/database.rs	New REST API handlers for database operations
crates/goose-server/src/openapi.rs	Added database endpoints to OpenAPI documentation
crates/goose-server/Cargo.toml	Added once_cell dependency for mutexes
crates/goose-cli/src/commands/mod.rs	Registered db commands module
crates/goose-cli/src/commands/db.rs	New CLI handlers for database operations
crates/goose-cli/src/cli.rs	Added db command and subcommands to CLI
crates/goose-cli/Cargo.toml	Added dependencies for table formatting and humanization
Cargo.lock	Lock file updates for new dependencies

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.