nitr-std 0.0.0-beta.7

The built-in `nitr.*` standard library for Nitr: dbg, fetch, template, json, http, log, crypto, and the SQLite driver.
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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
// SPDX-License-Identifier: MIT OR Apache-2.0
// This file is part of Nitr.
// See https://nitrweb.com/ for more information
// Copyright (C) 2024-present Jose Quintana <joseluisq.net>

//! Schema migrations: plain SQL files applied in order and recorded.
//!
//! No DSL, no ORM, no down-migrations. A migration is a `.sql` file whose
//! name starts with a number; they run in numeric order, each inside a
//! transaction, and each is recorded in `_nitr_migrations` so it never runs
//! twice. Rolling a production schema back by script is a decision, not
//! something a framework should do on your behalf.
//!
//! The checksum stored alongside each applied migration is not paranoia:
//! editing a file that already ran is the single easiest way to make two
//! deployments disagree about what the schema is, and it is invisible
//! without one.

use std::path::{Path, PathBuf};

use rusqlite::Connection;

use nitr_core::{Error, Result};

/// Table recording what has been applied.
pub(crate) const TABLE: &str = "_nitr_migrations";

/// One migration file on disk.
#[derive(Debug, Clone)]
pub struct Migration {
    /// Leading number, which defines the order.
    pub version: i64,
    /// File name, used in messages and stored in the ledger.
    pub name: String,
    /// Full path of the migration file on disk.
    pub path: PathBuf,
    sql: String,
}

impl Migration {
    /// Hex SHA-256 of the file contents.
    fn checksum(&self) -> String {
        use sha2::Digest as _;
        let digest = sha2::Sha256::digest(self.sql.as_bytes());
        digest.iter().fold(String::new(), |mut acc, byte| {
            use std::fmt::Write as _;
            let _ = write!(acc, "{byte:02x}");
            acc
        })
    }
}

/// What `--status` reports about one migration.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum State {
    /// Recorded in the ledger with a matching checksum.
    Applied,
    /// Not yet applied.
    Pending,
    /// Applied, but the file has changed since — the database and the
    /// repository no longer agree.
    Modified,
}

/// Reads the migrations directory, sorted by version.
///
/// A directory that does not exist is not an error: migrations are opt-in,
/// and an application without a schema should not have to say so.
pub fn discover(dir: &Path) -> Result<Vec<Migration>> {
    if !dir.is_dir() {
        return Ok(Vec::new());
    }
    let entries = std::fs::read_dir(dir).map_err(|err| {
        Error::Config(format!(
            "cannot read the migrations directory {}: {err}",
            dir.display()
        ))
    })?;

    let mut found: Vec<Migration> = Vec::new();
    for entry in entries.flatten() {
        let path = entry.path();
        if path.extension().is_none_or(|ext| ext != "sql") {
            continue;
        }
        let name = path
            .file_name()
            .map(|n| n.to_string_lossy().into_owned())
            .unwrap_or_default();
        // `001_create_users.sql` → 1. The number is what orders the set, so
        // a file without one is a mistake worth reporting rather than
        // silently skipping.
        let digits: String = name.chars().take_while(char::is_ascii_digit).collect();
        let version = digits.parse::<i64>().map_err(|_| {
            Error::Config(format!(
                "migration `{name}` must start with a version number, e.g. `001_{name}`"
            ))
        })?;
        let sql = std::fs::read_to_string(&path).map_err(|err| {
            Error::Config(format!("cannot read migration {}: {err}", path.display()))
        })?;
        found.push(Migration {
            version,
            name,
            path,
            sql,
        });
    }
    found.sort_by(|a, b| a.version.cmp(&b.version).then_with(|| a.name.cmp(&b.name)));

    if let Some(dup) = found.windows(2).find(|w| w[0].version == w[1].version) {
        return Err(Error::Config(format!(
            "migrations `{}` and `{}` share version {}: the order between them is undefined",
            dup[0].name, dup[1].name, dup[0].version
        )));
    }
    Ok(found)
}

/// Creates the ledger table if it is missing.
fn ensure_table(conn: &Connection) -> Result {
    conn.execute_batch(&format!(
        "CREATE TABLE IF NOT EXISTS {TABLE} (
             version    INTEGER PRIMARY KEY,
             name       TEXT NOT NULL,
             checksum   TEXT NOT NULL,
             applied_at TEXT NOT NULL DEFAULT (datetime('now'))
         )"
    ))
    .map_err(|err| Error::Config(format!("cannot create the {TABLE} table: {err}")))?;
    Ok(())
}

/// `version → checksum` for everything already applied; nothing before
/// the ledger exists. Reading never creates it: `status` and the boot
/// check must leave a database as they found it.
fn applied(conn: &Connection) -> Result<std::collections::HashMap<i64, String>> {
    let ledger: i64 = conn
        .query_row(
            "SELECT count(*) FROM sqlite_master WHERE type = 'table' AND name = ?1",
            [TABLE],
            |row| row.get(0),
        )
        .map_err(|err| Error::Config(format!("cannot read {TABLE}: {err}")))?;
    if ledger == 0 {
        return Ok(std::collections::HashMap::new());
    }
    let mut stmt = conn
        .prepare(&format!("SELECT version, checksum FROM {TABLE}"))
        .map_err(|err| Error::Config(format!("cannot read {TABLE}: {err}")))?;
    let rows = stmt
        .query_map([], |row| {
            Ok((row.get::<_, i64>(0)?, row.get::<_, String>(1)?))
        })
        .map_err(|err| Error::Config(format!("cannot read {TABLE}: {err}")))?;
    let mut out = std::collections::HashMap::new();
    for row in rows {
        let (version, checksum) =
            row.map_err(|err| Error::Config(format!("cannot read {TABLE}: {err}")))?;
        out.insert(version, checksum);
    }
    Ok(out)
}

/// The state of every discovered migration.
pub fn status(conn: &Connection, dir: &Path) -> Result<Vec<(Migration, State)>> {
    let applied = applied(conn)?;
    Ok(discover(dir)?
        .into_iter()
        .map(|migration| {
            let state = match applied.get(&migration.version) {
                None => State::Pending,
                Some(recorded) if *recorded == migration.checksum() => State::Applied,
                Some(_) => State::Modified,
            };
            (migration, state)
        })
        .collect())
}

/// [`status`] for the database at `path` without touching it: a missing
/// file is a database where nothing has run, and an existing one is
/// opened read-only, with none of the pragmas a live connection sets.
pub fn status_at(path: &Path, dir: &Path) -> Result<Vec<(Migration, State)>> {
    if !path.exists() {
        return Ok(discover(dir)?
            .into_iter()
            .map(|migration| (migration, State::Pending))
            .collect());
    }
    let conn = Connection::open_with_flags(
        path,
        rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY | rusqlite::OpenFlags::SQLITE_OPEN_NO_MUTEX,
    )
    .map_err(|err| {
        Error::Config(format!(
            "failed to open database at {}: {err}",
            path.display()
        ))
    })?;
    status(&conn, dir)
}

/// Names of the migrations that have not run yet.
///
/// A migration whose file changed after being applied counts as an error,
/// not as pending: re-running it is as likely to be wrong as skipping it,
/// so the only safe move is to stop and let a human decide.
pub fn pending(conn: &Connection, dir: &Path) -> Result<Vec<String>> {
    let mut names = Vec::new();
    for (migration, state) in status(conn, dir)? {
        match state {
            State::Pending => names.push(migration.name),
            State::Modified => {
                return Err(Error::Config(format!(
                    "migration `{}` has changed since it was applied: the database and \
                     {} no longer agree. Restore the file, or write a new migration for \
                     the change.",
                    migration.name,
                    migration.path.display()
                )));
            }
            State::Applied => {}
        }
    }
    Ok(names)
}

/// Applies every pending migration in order, returning their names.
///
/// Each runs inside its own transaction, so a failure leaves the earlier
/// migrations applied and the failing one entirely undone — the database is
/// always at some version that actually ran, never half of one.
pub fn run(conn: &Connection, dir: &Path) -> Result<Vec<String>> {
    ensure_table(conn)?;
    let applied = applied(conn)?;
    let mut done = Vec::new();

    for migration in discover(dir)? {
        match applied.get(&migration.version) {
            Some(recorded) if *recorded == migration.checksum() => continue,
            Some(_) => {
                return Err(Error::Config(format!(
                    "migration `{}` has changed since it was applied; refusing to continue",
                    migration.name
                )));
            }
            None => {}
        }

        // The file name, never the file's SQL — and through `redact`,
        // because `SqlInputError`'s own `Display` would otherwise put the
        // whole failing statement back into the message. A migration is
        // operator-authored rather than request-shaped, but it is exactly
        // the kind of file that carries a seeded credential in a literal,
        // and this error reaches the boot log.
        let fail = |err: rusqlite::Error| {
            Error::Config(format!(
                "migration `{}` failed: {}",
                migration.name,
                super::redact(&err)
            ))
        };
        conn.execute_batch("BEGIN").map_err(fail)?;
        let result = conn
            .execute_batch(&migration.sql)
            .and_then(|()| {
                conn.execute(
                    &format!("INSERT INTO {TABLE} (version, name, checksum) VALUES (?1, ?2, ?3)"),
                    rusqlite::params![migration.version, &migration.name, migration.checksum()],
                )
                .map(|_| ())
            })
            .and_then(|()| conn.execute_batch("COMMIT"));

        if let Err(err) = result {
            if let Err(rollback) = conn.execute_batch("ROLLBACK") {
                tracing::error!(
                    "failed to roll back migration `{}`: {rollback}",
                    migration.name
                );
            }
            return Err(fail(err));
        }
        tracing::info!("applied migration `{}`", migration.name);
        done.push(migration.name);
    }
    Ok(done)
}

#[cfg(test)]
mod tests {
    use super::*;

    fn scratch(name: &str) -> PathBuf {
        // The counter keeps every call on its own directory, so no two
        // tests can ever write into (or wipe) the same tree.
        static NEXT: std::sync::atomic::AtomicU32 = std::sync::atomic::AtomicU32::new(0);
        let id = NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        let dir = std::env::temp_dir()
            .join(format!("nitr-migrate-{}-{id}", std::process::id()))
            .join(name);
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).expect("scratch dir");
        dir
    }

    fn write(dir: &Path, name: &str, sql: &str) {
        std::fs::write(dir.join(name), sql).expect("write migration");
    }

    fn memory() -> Connection {
        Connection::open_in_memory().expect("in-memory db")
    }

    #[test]
    fn migrations_apply_in_order_and_only_once() {
        let dir = scratch("in-order");
        write(
            &dir,
            "002_add_email.sql",
            "ALTER TABLE users ADD COLUMN email TEXT;",
        );
        write(
            &dir,
            "001_create_users.sql",
            "CREATE TABLE users (id INTEGER PRIMARY KEY);",
        );

        let conn = memory();
        let applied = run(&conn, &dir).expect("first run");
        assert_eq!(applied, vec!["001_create_users.sql", "002_add_email.sql"]);

        // The column exists, so the two really ran in numeric order rather
        // than the order the directory happened to list them.
        conn.execute("INSERT INTO users (id, email) VALUES (1, 'a@b.c')", [])
            .expect("insert");

        // A second run is a no-op.
        assert!(run(&conn, &dir).expect("second run").is_empty());
        assert!(pending(&conn, &dir).expect("pending").is_empty());
    }

    #[test]
    fn a_failing_migration_leaves_nothing_half_applied() {
        let dir = scratch("failing");
        write(&dir, "001_ok.sql", "CREATE TABLE a (id INTEGER);");
        write(
            &dir,
            "002_broken.sql",
            "CREATE TABLE b (id INTEGER); THIS IS NOT SQL;",
        );

        let conn = memory();
        let err = run(&conn, &dir).expect_err("must fail");
        assert!(err.to_string().contains("002_broken.sql"), "{err}");

        // The first migration stands; nothing from the second does.
        conn.execute("INSERT INTO a (id) VALUES (1)", [])
            .expect("table a exists");
        assert!(
            conn.execute("INSERT INTO b (id) VALUES (1)", []).is_err(),
            "table b must not exist"
        );
        // And it is still pending, so a fixed file will run.
        assert_eq!(
            pending(&conn, &dir).expect("pending"),
            vec!["002_broken.sql"]
        );
    }

    #[test]
    fn editing_an_applied_migration_is_an_error() {
        let dir = scratch("edited");
        write(&dir, "001_users.sql", "CREATE TABLE users (id INTEGER);");
        let conn = memory();
        run(&conn, &dir).expect("apply");

        write(
            &dir,
            "001_users.sql",
            "CREATE TABLE users (id INTEGER, name TEXT);",
        );
        assert_eq!(status(&conn, &dir).expect("status")[0].1, State::Modified);
        let err = pending(&conn, &dir).expect_err("must refuse");
        assert!(err.to_string().contains("has changed"), "{err}");
    }

    #[test]
    fn a_file_without_a_version_is_reported() {
        let dir = scratch("unversioned");
        write(&dir, "create_users.sql", "CREATE TABLE users (id INTEGER);");
        let err = discover(&dir).expect_err("must fail");
        assert!(err.to_string().contains("version number"), "{err}");
    }

    #[test]
    fn duplicate_versions_are_reported() {
        let dir = scratch("duplicate");
        write(&dir, "001_a.sql", "CREATE TABLE a (id INTEGER);");
        write(&dir, "001_b.sql", "CREATE TABLE b (id INTEGER);");
        let err = discover(&dir).expect_err("must fail");
        assert!(err.to_string().contains("share version"), "{err}");
    }

    #[test]
    fn a_missing_directory_is_not_an_error() {
        let missing = std::env::temp_dir().join("nitr-migrate-does-not-exist");
        assert!(discover(&missing).expect("no error").is_empty());
    }
}