Macro sql_migration

Source

macro_rules! sql_migration {
    ($name:ident, $version:expr, $migration_name:expr,
        up: [$($up_sql:expr),* $(,)?],
        down: [$($down_sql:expr),* $(,)?]
    ) => { ... };
    ($name:ident, $version:expr, $migration_name:expr,
        up: $up_sql:expr,
        down: $down_sql:expr
    ) => { ... };
    ($name:ident, $version:expr, $migration_name:expr,
        up: [$($up_sql:expr),* $(,)?]
    ) => { ... };
    ($name:ident, $version:expr, $migration_name:expr,
        up: $up_sql:expr
    ) => { ... };
    ($name:ident, $version:expr, $migration_name:expr,
        sqlite_up: $sqlite_up:expr,
        sqlite_down: $sqlite_down:expr,
        mysql_up: $mysql_up:expr,
        mysql_down: $mysql_down:expr,
        postgres_up: $postgres_up:expr,
        postgres_down: $postgres_down:expr
    ) => { ... };
    ($name:ident, $version:expr, $migration_name:expr,
        sqlite_up: $sqlite_up:expr,
        sqlite_down: $sqlite_down:expr,
        mysql_up: $mysql_up:expr,
        mysql_down: $mysql_down:expr
    ) => { ... };
    ($name:ident, $version:expr, $migration_name:expr,
        sqlite_up: $sqlite_up:expr,
        mysql_up: $mysql_up:expr,
        postgres_up: $postgres_up:expr
    ) => { ... };
    ($name:ident, $version:expr, $migration_name:expr,
        sqlite_up: $sqlite_up:expr,
        mysql_up: $mysql_up:expr
    ) => { ... };
}

Expand description

Define a simple SQL-only migration.

This macro reduces boilerplate for migrations that consist of simple SQL statements that work identically across SQLite, MySQL, and PostgreSQL (or with minor dialect differences).

§Basic Usage

use migratio::sql_migration;

// Define a migration struct with SQL
sql_migration!(CreateUsersTable, 1, "Create users table",
    up: "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL)",
    down: "DROP TABLE users"
);

This expands to a struct CreateUsersTable that implements the Migration trait with sqlite_up/sqlite_down, mysql_up/mysql_down, and postgres_up/postgres_down methods.

§Database-Specific SQL

When databases require different SQL syntax, provide separate statements:

use migratio::sql_migration;

sql_migration!(CreateUsersTable, 1, "Create users table",
    sqlite_up: "CREATE TABLE users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT)",
    sqlite_down: "DROP TABLE users",
    mysql_up: "CREATE TABLE users (id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(255))",
    mysql_down: "DROP TABLE users",
    postgres_up: "CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT)",
    postgres_down: "DROP TABLE users"
);

For backwards compatibility, you can also specify just SQLite and MySQL - PostgreSQL will use the SQLite SQL since they share most syntax:

use migratio::sql_migration;

sql_migration!(CreateUsersTable, 1, "Create users table",
    sqlite_up: "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)",
    sqlite_down: "DROP TABLE users",
    mysql_up: "CREATE TABLE users (id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(255))",
    mysql_down: "DROP TABLE users"
);

§Up-Only Migrations

If your migration doesn’t need a down implementation (common for production systems), omit the down clauses:

use migratio::sql_migration;

sql_migration!(CreateUsersTable, 1, "Create users table",
    up: "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL)"
);

Calling downgrade() on such a migration will panic with a helpful error message.

§Multiple Statements

For migrations with multiple SQL statements, use an array:

use migratio::sql_migration;

sql_migration!(InitialSchema, 1, "Create initial schema",
    up: [
        "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)",
        "CREATE TABLE posts (id INTEGER PRIMARY KEY, user_id INTEGER, title TEXT)",
        "CREATE INDEX idx_posts_user ON posts(user_id)"
    ],
    down: [
        "DROP INDEX idx_posts_user",
        "DROP TABLE posts",
        "DROP TABLE users"
    ]
);

§When to Use This Macro

Use sql_migration! when:

Your migration is pure SQL with no Rust logic
The SQL works on all databases (or you provide dialect-specific versions)
You don’t need to query data and transform it in Rust

For complex migrations that need to query data, transform it in Rust, and write it back, implement the Migration trait directly instead.

sql_migration