miden-node-db 0.15.0-rc.3

Shared database capabilities for Miden node
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

use std::fmt;

use anyhow::{Context, Result, ensure};
use rusqlite::{Connection, Transaction};

use super::schema::{self, SchemaHash};

/// A migration entry that can be executed inside a SQLite transaction.
pub(super) trait MigrationEntry {
    /// Returns the migration name used in diagnostics.
    fn name(&self) -> &'static str;

    /// Executes the migration body inside `tx`.
    fn execute_migration(&self, tx: &Transaction<'_>) -> Result<()>;
}

/// A pure SQL migration.
pub(super) struct SqlMigration {
    name: &'static str,
    sql: &'static str,
}

impl SqlMigration {
    pub(super) fn new(name: &'static str, sql: &'static str) -> Self {
        Self { name, sql }
    }
}

impl MigrationEntry for SqlMigration {
    fn name(&self) -> &'static str {
        self.name
    }

    fn execute_migration(&self, tx: &Transaction<'_>) -> Result<()> {
        tx.execute_batch(self.sql).map_err(Into::into)
    }
}

impl fmt::Debug for SqlMigration {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("SqlMigration").field("name", &self.name).finish_non_exhaustive()
    }
}

/// A Rust migration function.
pub(super) struct CodeMigration {
    name: &'static str,
    apply: CodeMigrationFn,
}

impl CodeMigration {
    pub(super) fn new(name: &'static str, apply: CodeMigrationFn) -> Self {
        Self { name, apply }
    }
}

impl MigrationEntry for CodeMigration {
    fn name(&self) -> &'static str {
        self.name
    }

    fn execute_migration(&self, tx: &Transaction<'_>) -> Result<()> {
        (self.apply)(tx)
    }
}

impl fmt::Debug for CodeMigration {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("CodeMigration")
            .field("name", &self.name)
            .finish_non_exhaustive()
    }
}

/// An active migration that remains supported for existing databases.
pub(super) enum Migration {
    Sql(SqlMigration),
    Code(CodeMigration),
}

impl Migration {
    pub(super) fn sql(name: &'static str, sql: &'static str) -> Self {
        Self::Sql(SqlMigration::new(name, sql))
    }

    pub(super) fn code(name: &'static str, apply: CodeMigrationFn) -> Self {
        Self::Code(CodeMigration::new(name, apply))
    }
}

impl MigrationEntry for Migration {
    fn name(&self) -> &'static str {
        match self {
            Self::Sql(migration) => migration.name(),
            Self::Code(migration) => migration.name(),
        }
    }

    fn execute_migration(&self, tx: &Transaction<'_>) -> Result<()> {
        match self {
            Self::Sql(migration) => migration.execute_migration(tx),
            Self::Code(migration) => migration.execute_migration(tx),
        }
    }
}

impl fmt::Debug for Migration {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Sql(migration) => fmt::Debug::fmt(migration, f),
            Self::Code(migration) => fmt::Debug::fmt(migration, f),
        }
    }
}

/// Applies `migration`, sets `user_version`, commits, and returns the resulting schema hash.
pub(super) fn apply_migration(
    conn: &mut Connection,
    version: usize,
    migration: &impl MigrationEntry,
) -> Result<SchemaHash> {
    apply_migration_transaction(conn, version, migration, Ok::<SchemaHash, anyhow::Error>)
}

/// Applies `migration`, verifies the resulting schema hash, sets `user_version`, and commits.
pub(super) fn apply_migration_and_verify_schema(
    conn: &mut Connection,
    version: usize,
    migration: &impl MigrationEntry,
    expected: SchemaHash,
) -> Result<()> {
    apply_migration_transaction(conn, version, migration, |actual| {
        ensure!(actual == expected, "schema hash mismatch: expected {expected}, got {actual}");
        Ok(())
    })
}

fn apply_migration_transaction<T>(
    conn: &mut Connection,
    version: usize,
    migration: &impl MigrationEntry,
    verify_hash: impl FnOnce(SchemaHash) -> Result<T>,
) -> Result<T> {
    let tx = conn.transaction().context("failed to start transaction")?;

    migration.execute_migration(&tx).context("failed to execute migration")?;
    let schema_hash = SchemaHash::new(&tx).context("failed to compute schema hash")?;
    let result = verify_hash(schema_hash)?;
    schema::set_version(&tx, version).context("failed to update user_version")?;
    tx.commit().context("failed to commit transaction")?;

    Ok(result)
}

/// A Rust migration function executed inside a SQLite transaction.
pub type CodeMigrationFn = for<'conn> fn(&Transaction<'conn>) -> Result<()>;