Crate ic_sql_migrate 

A lightweight database migration library for Internet Computer (ICP) canisters.

This library provides automatic database schema management and version control for SQLite (via ic-rusqlite) and Turso databases in ICP canisters. Migrations are embedded at compile time and executed during canister initialization and upgrades.

Features

IMPORTANT: You must enable exactly one database feature for this library to work:

• SQLite support via ic-rusqlite (feature: sqlite)
• Turso support for distributed SQLite (feature: turso)

Additional capabilities:

• Automatic migration execution on canister init and post_upgrade
• Compile-time migration embedding via include!() macro
• Transaction-based execution for atomicity

The library has no default features. Attempting to use it without enabling either sqlite or turso will result in compilation errors when trying to access the database modules.

Quick Start for ICP Canisters

1. Prerequisites

For SQLite (via ic-rusqlite)

SQLite support requires the WASI SDK toolchain. Follow the setup instructions at ic-rusqlite or run:

curl -fsSL https://raw.githubusercontent.com/wasm-forge/ic-rusqlite/main/prepare.sh | sh

For Turso

No additional toolchain setup required beyond Rust and DFX.

2. Add to Cargo.toml

[dependencies]
ic-sql-migrate = { version = "0.0.1", features = ["sqlite"] }
ic-rusqlite = "0.37.0"  # or turso = "0.1.4" for Turso
ic-cdk = "0.16"

[build-dependencies]
ic-sql-migrate = "0.0.1"

3. Create build.rs

fn main() {
    ic_sql_migrate::list(Some("migrations")).unwrap();
}

4. Use in canister

use ic_cdk::{init, post_upgrade, pre_upgrade};
use ic_rusqlite::{close_connection, with_connection, Connection};

static MIGRATIONS: &[ic_sql_migrate::Migration] = ic_sql_migrate::include!();

fn run_migrations() {
    with_connection(|mut conn| {
        let conn: &mut Connection = &mut conn;
        ic_sql_migrate::sqlite::up(conn, MIGRATIONS).unwrap();
    });
}

#[init]
fn init() {
    run_migrations();
}

#[pre_upgrade]
fn pre_upgrade() {
    close_connection();
}

#[post_upgrade]
fn post_upgrade() {
    run_migrations();
}

Macros

include

Includes all migration files discovered by the list function at compile time.

Structs

Migration

Represents a single database migration with its unique identifier and SQL content.

Enums

Error

Custom error type for migration operations.

Functions

list

Discovers and lists all SQL migration files for inclusion at compile time.

Type Aliases

MigrateResult

Type alias for Result<T, Error> used throughout the library.