spin-migrate

A lightweight database migration library for Spin WASM applications.

Installation

[dependencies]
spin-migrate = "0.0.1"

Usage

use spin_migrate::{migrations, run_migrations};
use spin_sdk::sqlite::Connection;

const MIGRATIONS: &[spin_migrate::Migration] = migrations! {
    "001_create_users" => "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL)",
    "002_create_posts" => "CREATE TABLE posts (id INTEGER PRIMARY KEY, user_id INTEGER)",
    "003_add_index" => "CREATE INDEX idx_posts_user ON posts(user_id)",
};

fn setup_database() -> Result<(), spin_migrate::MigrationError> {
    let conn = Connection::open_default()?;
    let applied = run_migrations(&conn, MIGRATIONS)?;
    println!("Applied {applied} migrations");
    Ok(())
}

One Migration = One SQL Statement

Due to limitations in Spin's SQLite API (single-statement execution only), each migration must contain exactly one SQL statement. Create separate migrations for multiple statements:

// Correct: separate migrations
migrations! {
    "001_create_users" => "CREATE TABLE users (id INTEGER PRIMARY KEY)",
    "002_create_posts" => "CREATE TABLE posts (id INTEGER PRIMARY KEY)",
}

// Wrong: multiple statements in one migration
migrations! {
    "001_create_tables" => "CREATE TABLE users (...); CREATE TABLE posts (...)",
}

API

Testing

The crate supports rusqlite for testing outside of Spin:

[dev-dependencies]
spin-migrate = { version = "0.0.1", features = ["rusqlite"] }
rusqlite = "0.37"

#[test]
fn test_migrations() {
    let conn = rusqlite::Connection::open_in_memory().unwrap();
    run_migrations(&conn, MIGRATIONS).unwrap();
    assert!(all_migrations_applied(&conn, MIGRATIONS).unwrap());
}

Limitations

• Each migration must be a single SQL statement
• No transaction support (Spin SDK limitation - see issue #2286)
• No down migrations / rollback

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.