feat: support schema migrations

Author: pmorris-dev

Cargo.lock

@@ -7,8 +7,11 @@ edition = "2024"
 rust-version = "1.89"
 
 [dependencies]
-sqlx = { version = "0.8.6", features = ["runtime-tokio", "sqlite"] }
+sqlx = { version = "0.8.6", features = ["runtime-tokio", "sqlite", "migrate"] }
 thiserror = "2.0.17"
 tokio = { version = "1.48.0", features = ["full"] }
 tracing = { version = "0.1.41", default-features = false, features = ["std", "release_max_level_off"] }
 serde = { version = "1.0.228", features = ["derive"] }
+
+[dev-dependencies]
+tempfile = "3.23.0"

crates/sqlx-sqlite-conn-mgr/Cargo.toml

@@ -268,6 +268,62 @@ impl SqliteDatabase {
       Ok(WriteGuard::new(conn))
    }
 
+   /// Run database migrations using the provided migrator
+   ///
+   /// This method runs all pending migrations from the provided `Migrator`.
+   /// Migrations are executed using the write connection to ensure exclusive access.
+   /// WAL mode is enabled automatically before running migrations.
+   ///
+   /// SQLx tracks applied migrations in a `_sqlx_migrations` table, so calling
+   /// this method multiple times is safe - already-applied migrations are skipped.
+   ///
+   /// # Arguments
+   ///
+   /// * `migrator` - A reference to a `Migrator` containing the migrations to run.
+   ///   Typically created using `sqlx::migrate!()` macro.
+   ///
+   /// # Example
+   ///
+   /// ```ignore
+   /// use sqlx_sqlite_conn_mgr::SqliteDatabase;
+   ///
+   /// // sqlx::migrate! is evaluated at compile time
+   /// static MIGRATOR: sqlx::migrate::Migrator = sqlx::migrate!("./migrations");
+   ///
+   /// let db = SqliteDatabase::connect("test.db", None).await?;
+   /// db.run_migrations(&MIGRATOR).await?;
+   /// ```
+   pub async fn run_migrations(&self, migrator: &sqlx::migrate::Migrator) -> Result<()> {
+      if self.closed.load(Ordering::SeqCst) {
+         return Err(Error::DatabaseClosed);
+      }
+
+      // Initialize WAL mode before running migrations (migrations are writes)
+      // Acquire writer to ensure WAL is set up
+      let mut conn = self.write_conn.acquire().await?;
+
+      if !self.wal_initialized.load(Ordering::SeqCst) {
+         sqlx::query("PRAGMA journal_mode = WAL")
+            .execute(&mut *conn)
+            .await?;
+
+         sqlx::query("PRAGMA synchronous = NORMAL")
+            .execute(&mut *conn)
+            .await?;
+
+         self.wal_initialized.store(true, Ordering::SeqCst);
+      }
+
+      // Drop the connection back to pool before running migrator
+      // (migrator.run() will acquire its own connection)
+      drop(conn);
+
+      // Run migrations using the write pool
+      migrator.run(&self.write_conn).await?;
+
+      Ok(())
+   }
+
    /// Close the database and clean up resources
    ///
    /// This closes all connections in the pool and removes the database from the cache.

crates/sqlx-sqlite-conn-mgr/src/database.rs

@@ -14,6 +14,10 @@ pub enum Error {
    #[error("Sqlx error: {0}")]
    Sqlx(#[from] sqlx::Error),
 
+   /// Migration error from the sqlx migrate framework
+   #[error("Migration error: {0}")]
+   Migration(#[from] sqlx::migrate::MigrateError),
+
    /// Database has been closed and cannot be used
    #[error("Database has been closed")]
    DatabaseClosed,

crates/sqlx-sqlite-conn-mgr/src/error.rs

@@ -8,6 +8,7 @@
 //! - **[`SqliteDatabase`]**: Main database type with separate read and write connection pools
 //! - **[`SqliteDatabaseConfig`]**: Configuration for connection pool settings
 //! - **[`WriteGuard`]**: RAII guard ensuring exclusive write access
+//! - **[`Migrator`]**: Re-exported from sqlx for running database migrations
 //! - **[`Error`]**: Error type for database operations
 //!
 //! ## Architecture
@@ -71,5 +72,8 @@ pub use database::SqliteDatabase;
 pub use error::Error;
 pub use write_guard::WriteGuard;
 
+// Re-export sqlx migrate types for convenience
+pub use sqlx::migrate::Migrator;
+
 /// A type alias for Results with our custom Error type
 pub type Result<T> = std::result::Result<T, Error>;

crates/sqlx-sqlite-conn-mgr/src/lib.rs

@@ -1,5 +1,7 @@
+use sqlx::migrate::Migrator;
 use sqlx_sqlite_conn_mgr::{Error, SqliteDatabase, SqliteDatabaseConfig};
 use std::sync::Arc;
+use tempfile::TempDir;
 
 #[tokio::test]
 async fn test_concurrent_reads() {
@@ -383,3 +385,175 @@ async fn test_concurrent_reads_and_writes() {
 
    db.remove().await.unwrap();
 }
+
+/// Helper to create a temp directory with migration files.
+/// Returns (TempDir, Migrator) - TempDir must be kept alive for Migrator to work.
+async fn create_migrations(migrations: &[(&str, &str)]) -> (TempDir, Migrator) {
+   let dir = TempDir::new().unwrap();
+
+   for (i, (name, sql)) in migrations.iter().enumerate() {
+      let filename = format!("{:04}_{}.sql", i + 1, name.replace(' ', "_"));
+      std::fs::write(dir.path().join(filename), sql).unwrap();
+   }
+
+   let migrator = Migrator::new(dir.path()).await.unwrap();
+   (dir, migrator)
+}
+
+#[tokio::test]
+async fn test_run_migrations_creates_tables() {
+   let path = std::env::current_dir()
+      .unwrap()
+      .join("test_migrations_creates.db");
+   let db = SqliteDatabase::connect(&path, None).await.unwrap();
+
+   let (_dir, migrator) = create_migrations(&[(
+      "create_users",
+      "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL);",
+   )])
+   .await;
+
+   db.run_migrations(&migrator).await.unwrap();
+
+   // Verify table exists
+   let (count,): (i64,) = sqlx::query_as("SELECT COUNT(*) FROM sqlite_master WHERE name = 'users'")
+      .fetch_one(db.read_pool().unwrap())
+      .await
+      .unwrap();
+
+   assert_eq!(count, 1, "users table should exist");
+
+   db.remove().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_run_migrations_multiple() {
+   let path = std::env::current_dir()
+      .unwrap()
+      .join("test_migrations_multi.db");
+   let db = SqliteDatabase::connect(&path, None).await.unwrap();
+
+   let (_dir, migrator) = create_migrations(&[
+      (
+         "create_users",
+         "CREATE TABLE users (id INTEGER PRIMARY KEY);",
+      ),
+      (
+         "create_posts",
+         "CREATE TABLE posts (id INTEGER PRIMARY KEY, user_id INTEGER);",
+      ),
+      (
+         "add_index",
+         "CREATE INDEX idx_posts_user ON posts(user_id);",
+      ),
+   ])
+   .await;
+
+   db.run_migrations(&migrator).await.unwrap();
+
+   // Verify all migrations applied
+   let (count,): (i64,) = sqlx::query_as(
+      "SELECT COUNT(*) FROM sqlite_master WHERE type IN ('table', 'index') AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '_sqlx_%'",
+   )
+   .fetch_one(db.read_pool().unwrap())
+   .await
+   .unwrap();
+
+   assert_eq!(count, 3, "should have 2 tables + 1 index");
+
+   db.remove().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_run_migrations_idempotent() {
+   let path = std::env::current_dir()
+      .unwrap()
+      .join("test_migrations_idempotent.db");
+   let db = SqliteDatabase::connect(&path, None).await.unwrap();
+
+   let (_dir, migrator) = create_migrations(&[(
+      "create_items",
+      "CREATE TABLE items (id INTEGER PRIMARY KEY);",
+   )])
+   .await;
+
+   // Run twice - second should be no-op
+   db.run_migrations(&migrator).await.unwrap();
+   db.run_migrations(&migrator).await.unwrap();
+
+   // Verify table exists (no duplicate error)
+   let (count,): (i64,) = sqlx::query_as("SELECT COUNT(*) FROM sqlite_master WHERE name = 'items'")
+      .fetch_one(db.read_pool().unwrap())
+      .await
+      .unwrap();
+
+   assert_eq!(count, 1);
+
+   db.remove().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_run_migrations_tracks_in_sqlx_table() {
+   let path = std::env::current_dir()
+      .unwrap()
+      .join("test_migrations_tracking.db");
+   let db = SqliteDatabase::connect(&path, None).await.unwrap();
+
+   let (_dir, migrator) = create_migrations(&[
+      ("first", "CREATE TABLE t1 (id INTEGER);"),
+      ("second", "CREATE TABLE t2 (id INTEGER);"),
+   ])
+   .await;
+
+   db.run_migrations(&migrator).await.unwrap();
+
+   // Verify _sqlx_migrations table has 2 records
+   let (count,): (i64,) = sqlx::query_as("SELECT COUNT(*) FROM _sqlx_migrations")
+      .fetch_one(db.read_pool().unwrap())
+      .await
+      .unwrap();
+
+   assert_eq!(count, 2, "should track 2 applied migrations");
+
+   db.remove().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_run_migrations_on_closed_db_errors() {
+   let path = std::env::current_dir()
+      .unwrap()
+      .join("test_migrations_closed.db");
+   let db = SqliteDatabase::connect(&path, None).await.unwrap();
+   let db_ref = Arc::clone(&db);
+
+   db.close().await.unwrap();
+
+   let (_dir, migrator) = create_migrations(&[("noop", "SELECT 1;")]).await;
+   let result = db_ref.run_migrations(&migrator).await;
+
+   assert!(result.is_err());
+   assert!(matches!(result.unwrap_err(), Error::DatabaseClosed));
+
+   let _ = std::fs::remove_file(&path);
+}
+
+#[tokio::test]
+async fn test_run_migrations_initializes_wal() {
+   let path = std::env::current_dir()
+      .unwrap()
+      .join("test_migrations_wal.db");
+   let db = SqliteDatabase::connect(&path, None).await.unwrap();
+
+   let (_dir, migrator) = create_migrations(&[("init", "CREATE TABLE t (id INTEGER);")]).await;
+   db.run_migrations(&migrator).await.unwrap();
+
+   // Check WAL mode is set
+   let (mode,): (String,) = sqlx::query_as("PRAGMA journal_mode")
+      .fetch_one(db.read_pool().unwrap())
+      .await
+      .unwrap();
+
+   assert_eq!(mode.to_lowercase(), "wal");
+
+   db.remove().await.unwrap();
+}

crates/sqlx-sqlite-conn-mgr/tests/database_tests.rs

@@ -3,7 +3,7 @@
  */
 import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { mockIPC, clearMocks } from '@tauri-apps/api/mocks'
-import Database from './index'
+import Database, { MigrationEvent } from './index'
 
 let lastCmd = ''
 let lastArgs: Record<string, unknown> = {}
@@ -81,3 +81,35 @@ describe('Database commands', () => {
       await expect(Database.get('t.db').execute('SELECT 1', [])).rejects.toThrow('Database error')
    })
 })
+
+describe('MigrationEvent type', () => {
+   it('accepts running status', () => {
+      const event: MigrationEvent = {
+         dbPath: 'test.db',
+         status: 'running',
+      }
+      expect(event.status).toBe('running')
+      expect(event.migrationCount).toBeUndefined()
+      expect(event.error).toBeUndefined()
+   })
+
+   it('accepts completed status with migrationCount', () => {
+      const event: MigrationEvent = {
+         dbPath: 'test.db',
+         status: 'completed',
+         migrationCount: 3,
+      }
+      expect(event.status).toBe('completed')
+      expect(event.migrationCount).toBe(3)
+   })
+
+   it('accepts failed status with error', () => {
+      const event: MigrationEvent = {
+         dbPath: 'test.db',
+         status: 'failed',
+         error: 'Migration failed: syntax error',
+      }
+      expect(event.status).toBe('failed')
+      expect(event.error).toBe('Migration failed: syntax error')
+   })
+})

guest-js/index.test.ts

@@ -48,6 +48,44 @@ export interface CustomConfig {
    idleTimeoutSecs?: number
 }
 
+/**
+ * Event payload emitted during database migration operations.
+ *
+ * Listen for these events to track migration progress:
+ *
+ * @example
+ * ```ts
+ * import { listen } from '@tauri-apps/api/event'
+ * import type { MigrationEvent } from '@silvermine/tauri-plugin-sqlite'
+ *
+ * await listen<MigrationEvent>('sqlite:migration', (event) => {
+ *    const { dbPath, status, migrationCount, error } = event.payload
+ *
+ *    switch (status) {
+ *       case 'running':
+ *          console.log(`Running migrations for ${dbPath}`)
+ *          break
+ *       case 'completed':
+ *          console.log(`Completed ${migrationCount} migrations for ${dbPath}`)
+ *          break
+ *       case 'failed':
+ *          console.error(`Migration failed for ${dbPath}: ${error}`)
+ *          break
+ *    }
+ * })
+ * ```
+ */
+export interface MigrationEvent {
+   /** Database path (relative, as registered with the plugin) */
+   dbPath: string
+   /** Status: "running", "completed", "failed" */
+   status: 'running' | 'completed' | 'failed'
+   /** Number of migrations in the migrator (on "completed") */
+   migrationCount?: number
+   /** Error message (on "failed") */
+   error?: string
+}
+
 /**
  * **Database**
  *