Struct rusqlite_migration::Migrations

pub struct Migrations<'m> { /* private fields */ }

Set of migrations

Implementations

impl<'m> Migrations<'m>

pub fn new(ms: Vec<M<'m>>) -> Self

Create a set of migrations.

Example

use rusqlite_migration::{Migrations, M};

let migrations = Migrations::new(vec![
    M::up("CREATE TABLE animals (name TEXT);"),
    M::up("CREATE TABLE food (name TEXT);"),
]);

pub fn from_directory(dir: &'static Dir<'static>) -> Result<Self>

Available on crate feature from-directory only.

Creates a set of migrations from a given directory by scanning subdirectories with a specified name pattern. The migrations are loaded and stored in the binary.

Directory Structure Requirements

The migration directory pointed to by include_dir!() must contain subdirectories in accordance with the given pattern: {usize id indicating the order}-{convenient migration name}

Those directories must contain at lest an up.sql file containing a valid upward migration. They can also contain a down.sql file containing a downward migration.

Example structure

migrations
├── 01-friend_car
│  └── up.sql
├── 02-add_birthday_column
│  └── up.sql
└── 03-add_animal_table
   ├── down.sql
   └── up.sql

Example

use rusqlite_migration::Migrations;
use include_dir::{Dir, include_dir};

static MIGRATION_DIR: Dir = include_dir!("$CARGO_MANIFEST_DIR/../examples/from-directory/migrations");
let migrations = Migrations::from_directory(&MIGRATION_DIR).unwrap();

Errors

Returns Error::FileLoad in case the subdirectory names are incorrect, or don’t contain at least a valid up.sql file.

pub fn new_iter<I: IntoIterator<Item = M<'m>>>(ms: I) -> Self

👎Deprecated: Use the FromIterator trait implementation instead. For instance, you can call Migrations::from_iter.

Deprecated: Migrations now implements FromIterator, so use Migrations::from_iter instead.

Performs allocations transparently.

pub fn current_version(&self, conn: &Connection) -> Result<SchemaVersion>

Get the current schema version

Example

use rusqlite_migration::{Migrations, M, SchemaVersion};
use std::num::NonZeroUsize;

let mut conn = rusqlite::Connection::open_in_memory().unwrap();

let migrations = Migrations::new(vec![
    M::up("CREATE TABLE animals (name TEXT);"),
    M::up("CREATE TABLE food (name TEXT);"),
]);

assert_eq!(SchemaVersion::NoneSet, migrations.current_version(&conn).unwrap());

// Go to the latest version
migrations.to_latest(&mut conn).unwrap();

assert_eq!(SchemaVersion::Inside(NonZeroUsize::new(2).unwrap()), migrations.current_version(&conn).unwrap());

Errors

Returns Error::RusqliteError in case the user version cannot be queried.

pub fn to_latest(&self, conn: &mut Connection) -> Result<()>

Migrate the database to latest schema version. The migrations are applied atomically.

Example

use rusqlite_migration::{Migrations, M};
let mut conn = rusqlite::Connection::open_in_memory().unwrap();

let migrations = Migrations::new(vec![
    M::up("CREATE TABLE animals (name TEXT);"),
    M::up("CREATE TABLE food (name TEXT);"),
]);

// Go to the latest version
migrations.to_latest(&mut conn).unwrap();

// You can then insert values in the database
conn.execute("INSERT INTO animals (name) VALUES (?)", ["dog"]).unwrap();
conn.execute("INSERT INTO food (name) VALUES (?)", ["carrot"]).unwrap();

Errors

Returns Error::MigrationDefinition if no migration is defined.

pub fn to_version(&self, conn: &mut Connection, version: usize) -> Result<()>

Migrate the database to a given schema version. The migrations are applied atomically.

Specifying versions

• Empty database (no migrations run yet) has version 0.
• The version increases after each migration, so after the first migration has run, the schema version is 1. For instance, if there are 3 migrations, version 3 is after all migrations have run.

Note: As a result, the version is the index in the migrations vector starting from 1.

Example

use rusqlite_migration::{Migrations, M};
let mut conn = rusqlite::Connection::open_in_memory().unwrap();
let migrations = Migrations::new(vec![
    // 0: version 0, before having run any migration
    M::up("CREATE TABLE animals (name TEXT);").down("DROP TABLE animals;"),
    // 1: version 1, after having created the “animals” table
    M::up("CREATE TABLE food (name TEXT);").down("DROP TABLE food;"),
    // 2: version 2, after having created the food table
]);

migrations.to_latest(&mut conn).unwrap(); // Create all tables

// Go back to version 1, i.e. after running the first migration
migrations.to_version(&mut conn, 1);
conn.execute("INSERT INTO animals (name) VALUES (?)", ["dog"]).unwrap();
conn.execute("INSERT INTO food (name) VALUES (?)", ["carrot"]).unwrap_err();

// Go back to an empty database
migrations.to_version(&mut conn, 0);
conn.execute("INSERT INTO animals (name) VALUES (?)", ["cat"]).unwrap_err();
conn.execute("INSERT INTO food (name) VALUES (?)", ["milk"]).unwrap_err();

Errors

Attempts to migrate to a higher version than is supported will result in an error.

When migrating downwards, all the reversed migrations must have a .down() variant, otherwise no migrations are run and the function returns an error.

pub fn validate(&self) -> Result<()>

Run upward migrations on a temporary in-memory database from first to last, one by one. Convenience method for testing.

Example

#[cfg(test)]
mod tests {

    // … Other tests …

    #[test]
    fn migrations_test() {
        migrations.validate().unwrap();
    }
}

Errors

Returns Error::RusqliteError if the underlying sqlite database open call fails.

Trait Implementations

impl<'m> Clone for Migrations<'m>

fn clone(&self) -> Migrations<'m>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'m> Debug for Migrations<'m>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'u> FromIterator<M<'u>> for Migrations<'u>

fn from_iter<T: IntoIterator<Item = M<'u>>>(iter: T) -> Self

Creates a value from an iterator.

impl<'m> PartialEq for Migrations<'m>

fn eq(&self, other: &Migrations<'m>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'m> Eq for Migrations<'m>

impl<'m> StructuralPartialEq for Migrations<'m>