feat: support schema migrations

- Any registered migrations are run during plugin setup,
to get a jump on that work. Calls to load() await migrations
 so the db is ready once it's returned to the app.
- Migration events can be observed from Typescript in case
we need more details about progress

Author: pmorris-dev

Cargo.lock

@@ -19,8 +19,8 @@ SQLite database interface for Tauri applications using
      > "_SQLite ... will only allow one writer at any instant in time._"
    * **WAL Mode**: Enabled automatically on first write operation
    * **Type Safety**: Full TypeScript bindings
-   * **Migration Support**: SQLx's migration framework (coming soon)
-   * **Resource Management**: Proper cleanup on application exit (coming soon)
+   * **Migration Support**: SQLx's migration framework
+   * **Resource Management**: Proper cleanup on application exit
 
 ## Architecture
 
@@ -96,6 +96,54 @@ fn main() {
 }
 ```
 
+### Migrations
+
+This plugin uses [SQLx's migration system][sqlx-migrate]. Create numbered `.sql`
+files in a migrations directory:
+
+[sqlx-migrate]: https://docs.rs/sqlx/latest/sqlx/macro.migrate.html
+
+```text
+src-tauri/migrations/
+├── 0001_create_users.sql
+├── 0002_add_email_column.sql
+└── 0003_create_posts.sql
+```
+
+Register migrations using SQLx's `migrate!()` macro, which embeds them at compile time:
+
+```rust
+use tauri_plugin_sqlite::Builder;
+
+fn main() {
+    tauri::Builder::default()
+        .plugin(
+            Builder::new()
+                .add_migrations("main.db", sqlx::migrate!("./migrations"))
+                .build()
+        )
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+**Timing:** Migrations start automatically at plugin setup (non-blocking). When
+TypeScript calls `Database.load()`, it waits for migrations to complete before
+returning. If migrations fail, `load()` returns an error. Applied migrations are
+tracked in `_sqlx_migrations` — re-running is safe and idempotent.
+
+#### Listening for Migration Events
+
+```typescript
+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
+   // status: 'running' | 'completed' | 'failed'
+})
+```
+
 ### Connecting
 
 ```typescript

README.md

@@ -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

@@ -66,6 +66,32 @@ let config = SqliteDatabaseConfig {
 let db = SqliteDatabase::connect("example.db", Some(config)).await?;
 ```
 
+### Migrations
+
+Run [SQLx migrations][sqlx-migrate] directly:
+
+[sqlx-migrate]: https://docs.rs/sqlx/latest/sqlx/macro.migrate.html
+
+```rust
+use sqlx_sqlite_conn_mgr::SqliteDatabase;
+
+// Embed migrations at compile time (reads ./migrations/*.sql)
+static MIGRATOR: sqlx::migrate::Migrator = sqlx::migrate!("./migrations");
+
+async fn run() -> Result<(), sqlx_sqlite_conn_mgr::Error> {
+    let db = SqliteDatabase::connect("example.db", None).await?;
+    db.run_migrations(&MIGRATOR).await?;
+    Ok(())
+}
+```
+
+Migrations are tracked in `_sqlx_migrations` — calling `run_migrations()` multiple
+times is safe (already-applied migrations are skipped).
+
+> **Note:** When using the Tauri plugin, migrations are handled automatically via
+> `Builder::add_migrations()`. The plugin starts migrations at setup and waits for
+> completion when `load()` is called.
+
 ## API Reference
 
 ### `SqliteDatabase`
@@ -75,8 +101,9 @@ let db = SqliteDatabase::connect("example.db", Some(config)).await?;
 | `connect(path, config)` | Connect/create database, returns cached `Arc` if already open |
 | `read_pool()` | Get read-only pool reference |
 | `acquire_writer()` | Acquire exclusive `WriteGuard` (enables WAL on first call) |
+| `run_migrations(migrator)` | Run pending migrations from a `Migrator` |
 | `close()` | Close and remove from cache |
-| `close_and_remove()` | Close and delete database files (.db, .db-wal, .db-shm) |
+| `remove()` | Close and delete database files (.db, .db-wal, .db-shm) |
 
 ### `WriteGuard`
 

crates/sqlx-sqlite-conn-mgr/README.md

@@ -268,6 +268,44 @@ 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<()> {
+      // Ensure WAL mode is initialized via acquire_writer
+      // (WriteGuard dropped immediately, returning connection to pool)
+      {
+         let _writer = self.acquire_writer().await?;
+      }
+
+      // Migrator acquires its own connection from 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() {
@@ -30,6 +32,7 @@ async fn test_concurrent_reads() {
                .fetch_one(db.read_pool().unwrap())
                .await
                .unwrap();
+
             assert_eq!(count, 12);
 
             active.fetch_sub(1, Ordering::SeqCst);
@@ -292,6 +295,7 @@ async fn test_write_serialization() {
                .execute(&mut *w)
                .await
                .unwrap();
+
             active.fetch_sub(1, Ordering::SeqCst);
          })
       })
@@ -348,6 +352,7 @@ async fn test_concurrent_reads_and_writes() {
             .execute(&mut *w)
             .await
             .unwrap();
+
          write_active.store(false, Ordering::SeqCst);
       })
    };
@@ -366,6 +371,7 @@ async fn test_concurrent_reads_and_writes() {
             .fetch_one(db.read_pool().unwrap())
             .await
             .unwrap();
+
          if write_active.load(Ordering::SeqCst) {
             read_during_write.store(true, Ordering::SeqCst);
          }
@@ -383,3 +389,155 @@ 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_schema() {
+   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_with_invalid_sql_fails() {
+   let path = std::env::current_dir()
+      .unwrap()
+      .join("test_migrations_invalid.db");
+
+   let db = SqliteDatabase::connect(&path, None).await.unwrap();
+
+   // Create migration with invalid SQL syntax
+   let (_dir, migrator) = create_migrations(&[
+      ("valid", "CREATE TABLE users (id INTEGER PRIMARY KEY);"),
+      ("invalid", "THIS IS NOT VALID SQL SYNTAX"),
+   ])
+   .await;
+
+   let result = db.run_migrations(&migrator).await;
+
+   assert!(result.is_err());
+   assert!(matches!(result.unwrap_err(), Error::Migration(_)));
+
+   db.remove().await.unwrap();
+}