Rusqlite Migration

https://docs.rs/rusqlite_migration/
Admin
Rusqlite Migration is a performant and simple schema migration library for rusqlite that uses...
Tokens:20,889
Snippets:207
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Result::ok Examples

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Examples demonstrating conversion to Option via ok.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.ok(), Some(2));

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.ok(), None);
```

--------------------------------

### Migration Error Handling Example

Source: https://docs.rs/rusqlite_migration/latest/src/rusqlite_migration/lib.rs.html

Shows the setup for defining migrations that may trigger errors during execution.

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

let migrations = Migrations::new(vec![
    M::up("CREATE TABLE t1 (c);"),
```

--------------------------------

### Result::map Examples

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Examples demonstrating mapping over a Result.

```rust
let line = "1\n2\n3\n4\n";

for num in line.lines() {
    match num.parse::<i32>().map(|i| i * 2) {
        Ok(n) => println!("{n}"),
        Err(..) => {}
    }
}
```

--------------------------------

### Result::as_ref Examples

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Examples demonstrating conversion to a reference result via as_ref.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

--------------------------------

### Result::err Examples

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Examples demonstrating conversion to Option via err.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.err(), None);

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.err(), Some("Nothing here"));
```

--------------------------------

### Result::is_ok Examples

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Examples demonstrating the use of is_ok to check for success.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

--------------------------------

### Result::is_ok_and Examples

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Examples demonstrating the use of is_ok_and to check for success with a predicate.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.is_ok_and(|x| x > 1), true);

let x: Result<u32, &str> = Ok(0);
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<u32, &str> = Err("hey");
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<String, &str> = Ok("ownership".to_string());
assert_eq!(x.as_ref().is_ok_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

--------------------------------

### Result::as_mut Examples

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Examples demonstrating conversion to a mutable reference result via as_mut.

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

--------------------------------

### Result::is_err Examples

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Examples demonstrating the use of is_err to check for failure.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);
```

--------------------------------

### Result::is_err_and Examples

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Examples demonstrating the use of is_err_and to check for failure with a predicate.

```rust
use std::io::{Error, ErrorKind};

let x: Result<u32, Error> = Err(Error::new(ErrorKind::NotFound, "!"));
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), true);

let x: Result<u32, Error> = Err(Error::new(ErrorKind::PermissionDenied, "!"));
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);

let x: Result<u32, Error> = Ok(123);
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);

let x: Result<u32, String> = Err("ownership".to_string());
assert_eq!(x.as_ref().is_err_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

--------------------------------

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

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.Migrations.html

Migrates the database to a specified schema version. Migrations are applied atomically, and the version corresponds to the index in the migrations vector starting from 1.

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

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

### Parameters
- **conn** (&mut Connection) - The rusqlite database connection.
- **version** (usize) - The target schema version to migrate to.

### Errors
- Attempts to migrate to a higher version than supported result in an error.
- When migrating downwards, all reversed migrations must have a .down() variant, otherwise the function returns an error.
```

--------------------------------

### Copying Result Contents

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.Result.html

Examples of using the copied method to copy the contents of an Ok variant.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

--------------------------------

### Cloning Result Contents

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.Result.html

Examples of using the cloned method to clone the contents of an Ok variant.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

--------------------------------

### Flattening Nested Results

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.Result.html

Examples of flattening nested Result types.

```rust
let x: Result<Result<&'static str, u32>, u32> = Ok(Ok("hello"));
assert_eq!(Ok("hello"), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Ok(Err(6));
assert_eq!(Err(6), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Err(6);
assert_eq!(Err(6), x.flatten());
```

```rust
let x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok("hello")));
assert_eq!(Ok(Ok("hello")), x.flatten());
assert_eq!(Ok("hello"), x.flatten().flatten());
```

--------------------------------

### Checking Result Status

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.Result.html

Examples of checking if a Result is Ok or Err.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.is_ok_and(|x| x > 1), true);

let x: Result<u32, &str> = Ok(0);
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<u32, &str> = Err("hey");
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<String, &str> = Ok("ownership".to_string());
assert_eq!(x.as_ref().is_ok_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);
```

--------------------------------

### Collect Result from Iterator

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Examples showing how FromIterator handles Results, stopping at the first Err encountered.

```rust
let v = vec![1, 2];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_add(1).ok_or("Overflow!")
).collect();
assert_eq!(res, Ok(vec![2, 3]));
```

```rust
let v = vec![1, 2, 0];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_sub(1).ok_or("Underflow!")
).collect();
assert_eq!(res, Err("Underflow!"));
```

```rust
let v = vec![3, 2, 1, 10];
let mut shared = 0;
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| {
    shared += x;
    x.checked_sub(2).ok_or("Underflow!")
}).collect();
assert_eq!(res, Err("Underflow!"));
assert_eq!(shared, 6);
```

--------------------------------

### Transposing Result

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.Result.html

Example of transposing a Result of an Option into an Option of a Result.

```rust
#[derive(Debug, Eq, PartialEq)]
struct SomeErr;

let x: Result<Option<i32>, SomeErr> = Ok(Some(5));
let y: Option<Result<i32, SomeErr>> = Some(Ok(5));
assert_eq!(x.transpose(), y);
```

--------------------------------

### Migrating database versions

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.Migrations.html

Demonstrates how to define migrations and transition the database to specific versions using to_version.

```rust
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();
```

--------------------------------

### Initialize Migrations from a Directory

Source: https://docs.rs/rusqlite_migration/latest/src/rusqlite_migration/lib.rs.html

Load migrations from a directory structure containing up.sql and down.sql files.

```rust
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();
```

--------------------------------

### Create a basic schema update

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.M.html

Defines a simple SQL migration using M::up.

```rust
use rusqlite_migration::M;

M::up("CREATE TABLE animals (name TEXT);");
```

--------------------------------

### Create Migrations from Directory

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.MigrationsBuilder.html

Initializes a Migrations object by scanning a directory for migration files using the from_directory method.

```rust
use rusqlite_migration::{Migrations, MigrationsBuilder};
use include_dir::{Dir, include_dir};

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

--------------------------------

### Migrations::goto

Source: https://docs.rs/rusqlite_migration/latest/src/rusqlite_migration/lib.rs.html

Navigates the database to a specific target version, performing either upgrades or rollbacks as necessary.

```APIDOC
## fn goto(&self, conn: &mut Connection, target_db_version: usize) -> Result<()>

### Description
Transitions the database schema to the specified target version. If the target is less than the current version, it performs a rollback; if greater, it performs an upgrade.

### Parameters
- **conn** (&mut Connection) - Required - The rusqlite database connection.
- **target_db_version** (usize) - Required - The target schema version to reach.
```

--------------------------------

### M::set_up_hook / M::set_down_hook

Source: https://docs.rs/rusqlite_migration/latest/src/rusqlite_migration/builder.rs.html

Methods to attach custom hooks to migration steps during the build process.

```APIDOC
## M::set_up_hook(hook: impl MigrationHook + 'static) -> Self
## M::set_down_hook(hook: impl MigrationHook + 'static) -> Self

### Description
Replaces the `up_hook` or `down_hook` in the given migration with the provided one. These methods are intended for editing existing migrations when using the `MigrationsBuilder`.
```

--------------------------------

### Create Migrations from a Directory

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.Migrations.html

Loads migrations from a directory structure using the from-directory feature. Requires subdirectories formatted as {id}-{name} containing up.sql and optionally down.sql files.

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

```rust
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();
```

--------------------------------

### Migrations::from_directory

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.Migrations.html

Creates a set of migrations by scanning a directory structure.

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

### Description
Creates a set of migrations from a given directory by scanning subdirectories. Requires the 'from-directory' feature flag.

### Requirements
Subdirectories must follow the pattern `{usize id}-{name}` and contain at least an `up.sql` file.

### Example
```rust
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();
```
```

--------------------------------

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

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.Migrations.html

Migrates the database to the latest schema version atomically.

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

### Description
Migrates the database to the latest schema version. The migrations are applied atomically.

### Parameters
- **conn** (&mut Connection) - Required - The mutable rusqlite connection to the database.

### Returns
- **Result<()>** - Returns Ok(()) on success, or an Error if migration definition is missing or a SQL error occurs.
```

--------------------------------

### Enabling foreign key checks during migration

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.M.html

Demonstrates how to use foreign_key_check while manually toggling PRAGMA foreign_keys to ensure constraints are handled correctly during the migration process.

```rust
use rusqlite::{params, Connection};
use rusqlite_migration::{Migrations, M};

let migrations = Migrations::new(vec![
    M::up("CREATE TABLE animals (name TEXT);")
        .foreign_key_check(), // Let’s pretend this is necessary here
]);

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

// Turn foreign key constraints off for the duration of the migration
conn.pragma_update(None, "foreign_keys", &"OFF").unwrap();

migrations.to_latest(&mut conn).unwrap();

// Restore foreign key constraints checks
conn.pragma_update(None, "foreign_keys", &"ON").unwrap();

conn.execute("INSERT INTO animals (name) VALUES (?1)", params!["dog"])
    .unwrap();
```

--------------------------------

### into_ok

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.Result.html

Returns the contained Ok value without panicking.

```APIDOC
## pub const fn into_ok(self) -> T

### Description
Returns the contained `Ok` value, but never panics. This is a maintainability safeguard that will fail to compile if the error type of the `Result` is later changed to an error that can actually occur.
```

--------------------------------

### Handle Migration Errors

Source: https://docs.rs/rusqlite_migration/latest/src/rusqlite_migration/lib.rs.html

Demonstrates how to verify that a migration failure correctly returns a RusqliteError when invalid SQL is provided.

```rust
    M::up("SYNTAX ERROR"),         // This won’t be applied
    M::up("CREATE TABLE t2 (c);"), // This won’t be applied either because the migration above
                                   // failed
]);

assert!(matches!(
    migrations.to_latest(&mut conn),
    Err(rusqlite_migration::Error::RusqliteError {
        query: _,
        err: rusqlite::Error::SqliteFailure(_, _),
    })
));
```

--------------------------------

### Define and Apply Migrations

Source: https://docs.rs/rusqlite_migration

Defines a set of SQL migrations and applies them to a database connection using Migrations::to_latest.

```rust
use rusqlite::{params, Connection};
use rusqlite_migration::{Migrations, M};

// 1️⃣ Define migrations
const MIGRATIONS_SLICE: &[M<'_>] = &[
    M::up("CREATE TABLE friend(name TEXT NOT NULL);"),
    // In the future, add more migrations here:
    //M::up("ALTER TABLE friend ADD COLUMN email TEXT;"),
];
const MIGRATIONS: Migrations<'_> = Migrations::from_slice(MIGRATIONS_SLICE);

fn main() {
    let mut conn = Connection::open_in_memory().unwrap();

    // Apply some PRAGMA, often better to do it outside of migrations
    conn.pragma_update_and_check(None, "journal_mode", &"WAL", |_| Ok(()))
        .unwrap();

    // 2️⃣ Update the database schema, atomically
    MIGRATIONS.to_latest(&mut conn).unwrap();

    // 3️⃣ Use the database 🥳
    conn.execute("INSERT INTO friend (name) VALUES (?1)", params!["John"])
        .unwrap();
}
```

--------------------------------

### Create a migration with a Rust hook

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.M.html

Defines a migration that executes SQL followed by a custom Rust closure for data processing.

```rust
use rusqlite_migration::{M, Migrations};
use rusqlite::Transaction;

let migrations = Migrations::new(vec![
    // This table will later be filled with some novel content
    M::up("CREATE TABLE novels (text TEXT);"),
    M::up_with_hook(
        "ALTER TABLE novels ADD compressed TEXT;",
        |tx: &Transaction| {
            let mut stmt = tx.prepare("SELECT rowid, text FROM novels")?;
            let rows = stmt
                .query_map([], |row| {
                    Ok((row.get_unwrap::<_, i64>(0), row.get_unwrap::<_, String>(1)))
                })?;

            for row in rows {
                let row = row?;
                let rowid = row.0;
                let text = row.1;
                // Replace with a proper compression strategy ...
                let compressed = &text[..text.len() / 2];
                tx.execute(
                    "UPDATE novels SET compressed = ?1 WHERE rowid = ?2;",
                    rusqlite::params![compressed, rowid],
                )?;
            }

            Ok(())
        },
    ),
]);
```

--------------------------------

### Snapshot Migrations with Insta

Source: https://docs.rs/rusqlite_migration

Serializes the migrations object for snapshot testing using the insta crate.

```rust
#[test]
fn migrations_insta_snapshot() {
    let migrations = Migrations::new(vec![
        // ...
    ]);
    insta::assert_debug_snapshot!(migrations);
}
```

--------------------------------

### M::up

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.M.html

Creates a new schema update migration. The provided SQL command is executed only if the migration has not been previously applied.

```APIDOC
## M::up(sql: &str) -> Self

### Description
Creates a schema update. The SQL command will be executed only when the migration has not been executed on the underlying database.

### Parameters
- **sql** (&str) - Required - The SQL command to execute.
```

--------------------------------

### M::up_with_hook

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.M.html

Creates a schema update that includes both an SQL command and a Rust hook to be executed after the SQL succeeds.

```APIDOC
## M::up_with_hook(sql: &str, hook: impl MigrationHook) -> Self

### Description
Create a schema update running additional Rust code. The SQL command will be executed only when the migration has not been executed on the underlying database. The hook code will be executed after the SQL command executed successfully.
```

--------------------------------

### Apply migrations to latest version

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.Migrations.html

Use to_latest to atomically apply all pending migrations to the database.

```rust
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();
```

--------------------------------

### Migration File Structure and Loading

Source: https://docs.rs/rusqlite_migration/latest/src/rusqlite_migration/loader.rs.html

Defines the internal MigrationFile struct and helper functions to extract metadata and SQL content from directory entries.

```rust
// SPDX-License-Identifier: Apache-2.0
// Copyright Clément Joly and contributors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

use std::{convert::TryFrom, num::NonZeroUsize};

use crate::{Error, Result, M};
use include_dir::Dir;

#[derive(Debug, Clone)]
struct MigrationFile {
    id: NonZeroUsize,
    name: &'static str,
    up: &'static str,
    down: Option<&'static str>,
}

fn get_name(value: &'static Dir<'static>) -> Result<&'static str> {
    value
        .path()
        .file_name()
        .and_then(|name| name.to_str())
        .ok_or(Error::FileLoad(format!(
            "Could not extract file name from {:?}",
            value.path()
        )))
}

#[cfg_attr(test, mutants::skip)] // Tested at a high level
fn get_migrations(
    name: &'static str,
    value: &'static Dir<'static>,
) -> Result<(&'static str, Option<&'static str>)> {
    let up = value
        .files()
        .find(|f| f.path().ends_with("up.sql"))
        .ok_or(Error::FileLoad(format!(
            "Missing upward migration file for migration {name}"
        )))?
        .contents_utf8()
        .ok_or(Error::FileLoad(format!(
            "Could not load contents from {name}/up.sql"
        )))?;

    let down = value
        .files()
        .find(|f| f.path().ends_with("down.sql"))
        .map(|down| {
            down.contents_utf8().ok_or(Error::FileLoad(format!(
                "Could not load contents from {name}/down.sql"
            )))
        })
        .transpose()?;

    Ok((up, down))
}

fn get_id(file_name: &'static str) -> Result<NonZeroUsize> {
    file_name
        .split_once('-')
        .ok_or(Error::FileLoad(format!(
            "Could not extract migration id from file name {file_name}"
        )))?
        .0
        .parse::<usize>()
        .map_err(|e| {
            Error::FileLoad(format!(
                "Could not parse migration id from file name {file_name} as usize: {e}"
            ))
        })
        .and_then(|v| {
            NonZeroUsize::new(v).ok_or(Error::FileLoad(format!(
                "{file_name} has an incorrect migration id: migration id cannot be 0"
            )))
        })
}

impl TryFrom<&'static Dir<'static>> for MigrationFile {
    type Error = Error;

    fn try_from(value: &'static Dir<'static>) -> std::result::Result<Self, Self::Error> {
        let name = get_name(value)?;
        let (up, down) = get_migrations(name, value)?;
        let id = get_id(name)?;

        Ok(MigrationFile { id, name, up, down })
    }
}

impl From<&MigrationFile> for M<'_> {
    fn from(value: &MigrationFile) -> Self {
        M::up(value.up)
            .comment(value.name)
            .down(value.down.unwrap_or_default())
    }
}

#[cfg_attr(test, mutants::skip)] // Tested at a high level
pub(crate) fn from_directory(dir: &'static Dir<'static>) -> Result<Vec<Option<M<'static>>>> {
    let mut migrations: Vec<Option<M>> = vec![None; dir.dirs().count()];

    for dir in dir.dirs() {
        let migration_file = MigrationFile::try_from(dir)?;

        let id = usize::from(migration_file.id) - 1;

        if migrations.len() <= id {
            return Err(Error::FileLoad(
                "Migration ids must be consecutive numbers".to_string(),
            ));
        }

        if migrations[id].is_some() {
            return Err(Error::FileLoad(format!(
                "Multiple migrations detected for migration id: {}",
                migration_file.id
            )));
        }

        migrations[id] = Some((&migration_file).into());
    }

    if migrations.iter().all(Option::is_none) {
        return Err(Error::FileLoad(
            "Directory does not contain any migration files".to_string(),
        ));
    }

    if migrations.iter().any(Option::is_none) {
        return Err(Error::FileLoad(
            "Migration ids must be consecutive numbers".to_string(),
        ));
    }

    // The values are returned in the order of the keys, i.e. of IDs
    Ok(migrations)
}
```

--------------------------------

### Into Ok value

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Retrieve the Ok value without panicking, useful for infallible results.

```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}
```

--------------------------------

### MigrationsBuilder::from_directory

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.MigrationsBuilder.html

Creates a new MigrationsBuilder instance by scanning a directory for migration files. This method is available only when the 'from-directory' feature is enabled.

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

### Description
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.

### Parameters
- **dir** (&'static Dir<'static>) - Required - The directory containing migration subdirectories.

### Errors
Returns `crate::Error::FileLoad` if subdirectory names are incorrect or do not contain a valid `up.sql` file.
```

--------------------------------

### Create Migrations from a Slice

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.Migrations.html

Useful for defining migrations in constant contexts at compile time.

```rust
use rusqlite_migration::{Migrations, M};

const MIGRATION_ARRAY: &[M] = &[
    M::up("CREATE TABLE animals (name TEXT);"),
    M::up("CREATE TABLE food (name TEXT);"),
];
const MIGRATIONS: Migrations = Migrations::from_slice(MIGRATION_ARRAY);
```

--------------------------------

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

Source: https://docs.rs/rusqlite_migration/latest/src/rusqlite_migration/lib.rs.html

Runs upward migrations on a temporary in-memory database from first to last, one by one. This is a convenience method intended for testing purposes.

```APIDOC
## fn validate(&self) -> Result<()>

### Description
Runs upward migrations on a temporary in-memory database from first to last, one by one. This is a convenience method intended for testing purposes.

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

--------------------------------

### Unwrapping with default

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Returns the contained Ok value or a provided default.

```rust
let default = 2;
let x: Result<u32, &str> = Ok(9);
assert_eq!(x.unwrap_or(default), 9);

let x: Result<u32, &str> = Err("error");
assert_eq!(x.unwrap_or(default), default);
```

--------------------------------

### to_latest

Source: https://docs.rs/rusqlite_migration/latest/src/rusqlite_migration/lib.rs.html

Migrates the database to the latest defined schema version.

```APIDOC
## fn to_latest(&self, conn: &mut Connection) -> Result<()>

### Description
Migrates the database to the latest schema version defined in the Migrations object. This operation is performed atomically.

### Parameters
- **conn** (&mut Connection) - Required - A mutable reference to the rusqlite Connection.

### Errors
Returns an error if no migrations are defined or if a migration fails to apply.
```

--------------------------------

### Create Migrations from a Vector

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.Migrations.html

Initializes a new set of migrations using a vector of migration definitions.

```rust
use rusqlite_migration::{Migrations, M};

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

--------------------------------

### Create references with as_ref and as_mut

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.Result.html

Converts a Result to a Result containing references to the original values.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

--------------------------------

### Migrations::from_slice

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.Migrations.html

Creates a set of migrations from a slice, useful for constant contexts.

```APIDOC
## pub const fn from_slice(ms: &'m [M<'m>]) -> Self

### Description
Creates a set of migrations from a slice of migration definitions. This is particularly useful in const contexts when migrations are known at compile time.

### Example
```rust
use rusqlite_migration::{Migrations, M};

const MIGRATION_ARRAY: &[M] = &[
    M::up("CREATE TABLE animals (name TEXT);"),
    M::up("CREATE TABLE food (name TEXT);"),
];
const MIGRATIONS: Migrations = Migrations::from_slice(MIGRATION_ARRAY);
```
```

--------------------------------

### Handle migration errors

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.Migrations.html

Demonstrates that to_latest stops applying migrations immediately if a statement fails.

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

let migrations = Migrations::new(vec![
    M::up("CREATE TABLE t1 (c);"),
    M::up("SYNTAX ERROR"),         // This won’t be applied
    M::up("CREATE TABLE t2 (c);"), // This won’t be applied either because the migration above
                                   // failed
]);

assert!(matches!(
    migrations.to_latest(&mut conn),
    Err(rusqlite_migration::Error::RusqliteError {
        query: _,
        err: rusqlite::Error::SqliteFailure(_, _),
    })
));
```

--------------------------------

### M::down_with_hook

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.M.html

Defines a down-migration that includes both an SQL command and a Rust hook to be executed before the SQL.

```APIDOC
## M::down_with_hook(sql: &str, hook: impl MigrationHook) -> Self

### Description
Define a down-migration running additional Rust code. This SQL statement should exactly reverse the changes performed in up_with_hook(). The hook will run before the SQL statement is executed.
```

--------------------------------

### fn optional

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.Result.html

Converts a Result<T> into a Result<Option<T>>.

```APIDOC
## fn optional(self) -> Result<Option<T>, Error>

### Description
Converts a `Result<T>` into a `Result<Option<T>>`.
```

--------------------------------

### Migrations::new

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.Migrations.html

Creates a new set of migrations from a vector of migration definitions.

```APIDOC
## pub const fn new(ms: Vec<M<'m>>) -> Self

### Description
Creates a set of migrations from a provided vector of migration definitions.

### Example
```rust
use rusqlite_migration::{Migrations, M};

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

--------------------------------

### unwrap

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.Result.html

Returns the contained Ok value, consuming the self value. Panics if the value is an Err.

```APIDOC
## pub fn unwrap(self) -> T

### Description
Returns the contained `Ok` value, consuming the `self` value. Because this function may panic, its use is generally discouraged.
```

--------------------------------

### Chaining Results with or

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Returns the second result if the first is Err, otherwise returns the Ok value.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("early error");
let y: Result<u32, &str> = Ok(2);
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Err("late error"));

let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Ok(100);
assert_eq!(x.or(y), Ok(2));
```

--------------------------------

### Chaining Results with and

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Returns the second result if the first is Ok, otherwise returns the Err value.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("late error"));

let x: Result<u32, &str> = Err("early error");
let y: Result<&str, &str> = Ok("foo");
assert_eq!(x.and(y), Err("early error"));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("not a 2"));

let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Ok("different result type");
assert_eq!(x.and(y), Ok("different result type"));
```

--------------------------------

### Check pending migrations before backup

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.Migrations.html

Use pending_migrations to determine if any migrations are required before performing a database backup.

```rust
use rusqlite_migration::{Migrations, M};

let mut conn = rusqlite::Connection::open_in_memory().unwrap();
let mut migrations: Migrations = Migrations::new(vec![
    M::up("CREATE TABLE animals (name TEXT);"),
    M::up("CREATE TABLE food (name TEXT);"),
]);

if migrations.pending_migrations(&conn).unwrap() != 0 {
    // Backup the database

    migrations.to_latest(&mut conn).unwrap()
}
```

--------------------------------

### Extracting Ok value

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Demonstrates extracting the contained Ok value from a Result.

```rust
let s: String = only_good_news().into_ok();
println!("{s}");
```

--------------------------------

### Implement From conversions for HookError

Source: https://docs.rs/rusqlite_migration/latest/src/rusqlite_migration/errors.rs.html

Provides conversion logic from rusqlite::Error to HookError and from HookError to the crate's main Error type.

```rust
impl From<rusqlite::Error> for HookError {
    fn from(e: rusqlite::Error) -> HookError {
        HookError::RusqliteError(e)
    }
}

impl From<HookError> for Error {
    fn from(e: HookError) -> Error {
        match e {
            HookError::RusqliteError(err) => Error::with_sql(err, ""),
            HookError::Hook(s) => Error::Hook(s),
        }
    }
}
```

--------------------------------

### Handle negative pending migrations

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.Migrations.html

Demonstrates how pending_migrations returns negative values when a database has been modified by a newer version of the application.

```rust
use rusqlite_migration::{Error, Migrations, M, MigrationDefinitionError};

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

// Initial set of migrations in, say, version 1 of the program
let mut ms = vec![
    M::up("CREATE TABLE animals (name TEXT);"),
    M::up("CREATE TABLE food (name TEXT);"),
];
let migrations_v1 = Migrations::new(ms.clone());

migrations_v1.to_latest(&mut conn).unwrap();
assert_eq!(migrations_v1.pending_migrations(&conn), Ok(0));

// More migrations are added in, say, version 2
ms.push(M::up("CREATE TABLE plants (name TEXT);"));
let migrations_v2 =  Migrations::new(ms);

migrations_v2.to_latest(&mut conn).unwrap();
// From the perspective of the old version of the program, one migration would need to be
// reversed.
assert_eq!(migrations_v1.pending_migrations(&conn), Ok(-1));
// Note that in this situation, to_latest will return an error, which you can handle how
// you see fit (maybe restoring one of those backups or prompting the user)
assert_eq!(migrations_v1.to_latest(&mut conn), Err(Error::MigrationDefinition(
    MigrationDefinitionError::DatabaseTooFarAhead
)));
```

--------------------------------

### Convert Result to Option with ok and err

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.Result.html

Converts a Result into an Option, consuming the original Result.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.ok(), Some(2));

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.ok(), None);
```

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.err(), None);

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.err(), Some("Nothing here"));
```

--------------------------------

### Unwrap a Result value

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Retrieve the Ok value or panic if the result is Err.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.unwrap(), 2);
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
x.unwrap(); // panics with `emergency failure`
```

--------------------------------

### unwrap_or_default

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.Result.html

Returns the contained Ok value or a default value if the result is an Err.

```APIDOC
## pub fn unwrap_or_default(self) -> T

### Description
Consumes the `self` argument then, if `Ok`, returns the contained value, otherwise if `Err`, returns the default value for that type.
```

--------------------------------

### with_sql

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/enum.Error.html

Associates the specific SQL request that caused the error with the error instance.

```APIDOC
## pub fn with_sql(e: Error, sql: &str) -> Error

### Description
Associates the SQL request that caused the error with the provided Error instance.

### Parameters
- **e** (Error) - The original error instance.
- **sql** (&str) - The SQL string that triggered the error.
```

--------------------------------

### Implement PartialEq for Error

Source: https://docs.rs/rusqlite_migration/latest/src/rusqlite_migration/errors.rs.html

Custom equality implementation for Error, where Unrecognized errors are treated as non-comparable (similar to NaN).

```rust
impl PartialEq for Error {
    fn eq(&self, other: &Self) -> bool {
        match (self, other) {
            (
                Self::RusqliteError { query: q1, err: e1 },
                Self::RusqliteError { query: q2, err: e2 },
            ) => q1 == q2 && e1 == e2,
            (Self::SpecifiedSchemaVersion(a), Self::SpecifiedSchemaVersion(b)) => a == b,
            (Self::MigrationDefinition(a), Self::MigrationDefinition(b)) => a == b,
            (Self::ForeignKeyCheck(e1), Self::ForeignKeyCheck(e2)) => e1 == e2,
            (Self::Hook(a), Self::Hook(b)) | (Self::FileLoad(a), Self::FileLoad(b)) => a == b,
            (Self::Unrecognized(_), Self::Unrecognized(_)) => false,
            _ => core::mem::discriminant(self) == core::mem::discriminant(other),
        }
    }
}
```

--------------------------------

### Expect a Result value

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Retrieve the Ok value or panic with a custom message if the result is Err.

```rust
let x: Result<u32, &str> = Err("emergency failure");
x.expect("Testing expect"); // panics with `Testing expect: emergency failure`
```

```rust
let path = std::env::var("IMPORTANT_PATH")
    .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`");
```

--------------------------------

### Unwrap with default value

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Return the Ok value or the default value for the type if the result is Err.

```rust
let good_year_from_input = "1909";
let bad_year_from_input = "190blarg";
let good_year = good_year_from_input.parse().unwrap_or_default();
let bad_year = bad_year_from_input.parse().unwrap_or_default();

assert_eq!(1909, good_year);
assert_eq!(0, bad_year);
```

--------------------------------

### Query Current Schema Version

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.Migrations.html

Retrieves the current version of the database schema applied to the connection.

```rust
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());
```

--------------------------------

### Calculate Product of Result Iterator

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Demonstrates using the product method on an iterator of Results, which returns an Err if any element fails to parse.

```rust
let nums = vec!["5", "10", "1", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert_eq!(total, Ok(100));
let nums = vec!["5", "10", "one", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert!(total.is_err());
```

--------------------------------

### Expect an error

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Retrieve the Err value or panic if the result is Ok.

```rust
let x: Result<u32, &str> = Ok(10);
x.expect_err("Testing expect_err"); // panics with `Testing expect_err: 10`
```

--------------------------------

### fn product

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.Result.html

Calculates the product of an iterator of Results, returning the first Err encountered or the product.

```APIDOC
## fn product<I>(iter: I) -> Result<T, E>

### Description
Takes each element in the `Iterator`: if it is an `Err`, no further elements are taken, and the `Err` is returned. Should no `Err` occur, the product of all elements is returned.
```

--------------------------------

### Inspect Ok variant with inspect

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Executes a function with a reference to the Ok value without modifying the result.

```rust
let x: u8 = "4"
    .parse::<u8>()
    .inspect(|x| println!("original: {x}"))
    .map(|x| x.pow(3))
    .expect("failed to parse number");
```

--------------------------------

### Convert Result to Iterator

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.HookResult.html

Demonstrates converting a Result into an iterator that yields the contained value if Ok, or nothing if Err.

```rust
let x: Result<u32, &str> = Ok(5);
let v: Vec<u32> = x.into_iter().collect();
assert_eq!(v, [5]);

let x: Result<u32, &str> = Err("nothing!");
let v: Vec<u32> = x.into_iter().collect();
assert_eq!(v, []);
```

--------------------------------

### Define an up and down migration

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.M.html

Pairs an up-migration with a corresponding down-migration to allow for schema reversal.

```rust
use rusqlite_migration::M;

M::up("CREATE TABLE animals (name TEXT);").down("DROP TABLE animals;");
```

--------------------------------

### and_then

Source: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/type.Result.html

Calls op if the result is Ok, otherwise returns the Err value of self.

```APIDOC
## pub fn and_then<U, F>(self, op: F) -> Result<U, E>

### Description
Calls `op` if the result is `Ok`, otherwise returns the `Err` value of `self`. This function can be used for control flow based on `Result` values.
```
Tokens:
Raw