schema.rs
schema.rs
//! migration replay + schema 快照 + 把每一句寫死的 SQL 拿去 prepare。
//!
//! ## 補的是哪個洞
//!
//! 這個後端有 153 次 `sqlx::query*`、**零個編譯期檢查巨集**(`query!`)、也沒有
//! `.sqlx/` 離線資料。意思是:migration 把欄位改名或刪掉時,**編譯器完全不會出聲**,
//! 要等到那條路徑在線上真的被走到才會炸。而覆蓋率只有兩成,多數路徑不會在測試裡被走到。
//!
//! ## 三層
//!
//! 1. `migrations_replay_on_an_empty_database` —— 11 支 migration 從空白重放得過。
//! 2. `schema_matches_snapshot` —— 重放後的 schema 對committed 快照。schema 一動就要
//! 有人明確更新快照,不會靜悄悄地改掉。
//! 3. `every_literal_sql_prepares_against_the_migrated_schema` —— 把原始碼裡每一句
//! **寫死的** SQL 丟給 SQLite prepare。prepare 會驗表名與欄位名,這正是 `query!`
//! 巨集會做而我們現在沒做的事。
//!
//! 第 3 項抓不到動態拼出來的 SQL(`format!` / `AssertSqlSafe(sql.as_str())`)。
//! 目前是 **131 句寫死的有檢查、22 句動態的檢查不到**。那 22 句會被計數並逐條印出來
//! ——**不靜靜地跳過**,不然「131 句全過」看起來會像「全部都過」。
use std::fmt::Write as _;
use std::path::{Path, PathBuf};
use std::str::FromStr;
use sqlx::Executor;
use sqlx::sqlite::{SqliteConnectOptions, SqlitePoolOptions};
const SNAPSHOT: &str = "tests/schema.snapshot.sql";
/// 空白 DB + 跑完全部 migration。與正式啟動、與 tests/api.rs 走同一條 `sqlx::migrate!`。
async fn migrated_pool() -> sqlx::SqlitePool {
let opts =
SqliteConnectOptions::from_str("sqlite::memory:").expect("in-memory sqlite URL").foreign_keys(true);
let pool = SqlitePoolOptions::new()
.max_connections(1)
.connect_with(opts)
.await
.expect("connect in-memory sqlite");
sqlx::migrate!("./migrations").run(&pool).await.expect("migration 從空白重放失敗");
pool
}
fn manifest_dir() -> PathBuf {
PathBuf::from(env!("CARGO_MANIFEST_DIR"))
}
#[tokio::test]
async fn migrations_replay_on_an_empty_database() {
let pool = migrated_pool().await;
let applied: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM _sqlx_migrations")
.fetch_one(&pool)
.await
.expect("讀 _sqlx_migrations");
let on_disk = std::fs::read_dir(manifest_dir().join("migrations"))
.expect("讀 migrations 目錄")
.filter_map(Result::ok)
.filter(|e| e.path().extension().is_some_and(|x| x == "sql"))
.count();
let on_disk = i64::try_from(on_disk).expect("migration 檔數不可能超過 i64");
assert_eq!(applied, on_disk, "跑掉的 migration 數與目錄裡的 .sql 數對不上");
assert!(on_disk > 0, "一支 migration 都沒有,這個測試就沒有意義了");
}
// ── schema 快照 ───────────────────────────────────────────────────────────
/// `sqlite_master` 正規化成穩定的文字。空白壓成單一空格,讓「只是重排版」不算變更,
/// 但欄位增刪改名一定會顯示出來。
async fn schema_text(pool: &sqlx::SqlitePool) -> String {
let rows: Vec<(String, String, Option<String>)> = sqlx::query_as(
"SELECT type, name, sql FROM sqlite_master \
WHERE name NOT LIKE 'sqlite_%' AND name != '_sqlx_migrations' \
ORDER BY type, name",
)
.fetch_all(pool)
.await
.expect("讀 sqlite_master");
let mut out = String::from(
"-- 由 backend/tests/schema.rs 產生,不要手改。\n\
-- 要更新:UPDATE_SCHEMA_SNAPSHOT=1 cargo test --test schema\n\
-- 這份快照的用途是「schema 變了就要有人明說」——後端沒有編譯期 SQL 檢查,\n\
-- 欄位靜悄悄改名的話只有線上會知道。\n\n",
);
for (kind, name, sql) in rows {
let normalized = sql.unwrap_or_default().split_whitespace().collect::<Vec<_>>().join(" ");
if normalized.is_empty() {
continue; // 自動索引(sqlite_autoindex_*)沒有 sql,已被上面過濾掉
}
let _ = write!(out, "{kind} {name}\n {normalized}\n\n");
}
out
}
#[tokio::test]
async fn schema_matches_snapshot() {
let pool = migrated_pool().await;
let actual = schema_text(&pool).await;
let path = manifest_dir().join(SNAPSHOT);
if std::env::var("UPDATE_SCHEMA_SNAPSHOT").is_ok() {
std::fs::write(&path, &actual).expect("寫快照");
eprintln!("已更新 {}", path.display());
return;
}
let expected = std::fs::read_to_string(&path).unwrap_or_else(|e| {
panic!(
"讀不到 schema 快照 {}({e})。第一次建立請跑:\n \
UPDATE_SCHEMA_SNAPSHOT=1 cargo test --test schema",
path.display()
)
});
if actual != expected {
// 印出差在哪一行,不然 assert_eq! 會吐兩大段文字要人自己對
let a: Vec<&str> = actual.lines().collect();
let b: Vec<&str> = expected.lines().collect();
let mut diff = String::new();
for i in 0..a.len().max(b.len()) {
let (x, y) = (a.get(i).copied().unwrap_or(""), b.get(i).copied().unwrap_or(""));
if x != y {
let _ = write!(diff, " 第 {} 行\n 快照: {y}\n 實際: {x}\n", i + 1);
}
}
panic!(
"migration 改動了 schema,但快照沒跟上。\n{diff}\n\
確認這是有意的改動之後,跑:\n UPDATE_SCHEMA_SNAPSHOT=1 cargo test --test schema\n\
並且**檢查所有查到這些欄位的 sqlx::query 有沒有一起改**——\
這個後端沒有編譯期 SQL 檢查,改錯了編譯器不會說話。"
);
}
}
// ── 把寫死的 SQL 拿去 prepare ─────────────────────────────────────────────
/// 讀一個 Rust 字串字面值(`"..."`、`r"..."`、`r#"..."#`),回傳 (內容, 結束位置)。
/// 不是字面值就回 None——刻意不猜,猜錯會變成假紅。
fn read_rust_string(src: &str, start: usize) -> Option<(String, usize)> {
let b = src.as_bytes();
let mut i = start;
// raw string:r"..." / r#"..."# / r##"..."##
if b.get(i) == Some(&b'r') {
let mut hashes = 0;
let mut j = i + 1;
while b.get(j) == Some(&b'#') {
hashes += 1;
j += 1;
}
if b.get(j) != Some(&b'"') {
return None;
}
let close = format!("\"{}", "#".repeat(hashes));
let body_start = j + 1;
let end = src[body_start..].find(&close)? + body_start;
return Some((src[body_start..end].to_string(), end + close.len()));
}
if b.get(i) != Some(&b'"') {
return None;
}
i += 1;
let mut out = String::new();
while i < src.len() {
match b[i] {
b'"' => return Some((out, i + 1)),
b'\\' => {
i += 1;
match b.get(i) {
// 行接續:吃掉換行與下一行的前導空白(Rust 的規則)
Some(b'\n') => {
i += 1;
while b.get(i).is_some_and(u8::is_ascii_whitespace) {
i += 1;
}
// 補一個分隔,不然 `SELECT a\<換行>FROM t` 會黏成 `aFROM`。
// 前面已經有空白就不再補——雙空格不影響 SQL,但會讓這個函式的
// 輸出不等於原始 SQL,之後拿它做比對或雜湊時會踩到。
if !out.ends_with(char::is_whitespace) {
out.push(' ');
}
continue;
}
Some(b'n') => out.push('\n'),
Some(b't') => out.push('\t'),
Some(b'r') => out.push('\r'),
Some(b'0') => out.push('\0'),
Some(&c) => out.push(c as char),
None => return None,
}
i += 1;
}
_ => {
// 多位元組字元原樣搬過去
let ch = src[i..].chars().next()?;
out.push(ch);
i += ch.len_utf8();
}
}
}
None
}
struct Extracted {
literals: Vec<(String, String)>, // (檔名, SQL)
dynamic: Vec<String>, // 抓不動的,記下來回報
}
/// 掃 `sqlx::query` / `query_as` / `query_scalar`,只取第一個引數是字串字面值的。
/// 允許外面包一層 `sqlx::AssertSqlSafe(...)`。
fn extract(src: &str, file: &str) -> Extracted {
let mut out = Extracted { literals: Vec::new(), dynamic: Vec::new() };
let mut cursor = 0;
while let Some(rel) = src[cursor..].find("sqlx::query") {
let hit = cursor + rel;
cursor = hit + "sqlx::query".len();
let mut j = cursor;
// 吃掉 `_as` / `_scalar`
for suffix in ["_as", "_scalar"] {
if src[j..].starts_with(suffix) {
j += suffix.len();
break;
}
}
while src[j..].starts_with(char::is_whitespace) {
j += 1;
}
// turbofish 要整段跳過,不能直接找第一個 '('——
// `query_as::<_, (i64, Option<String>)>("SELECT …")` 的第一個 '(' 在型別裡面,
// 直接找會抓到 tuple type,那句 SQL 就被誤判成「動態拼的」而漏檢。
if src[j..].starts_with("::<") {
j += 3;
let mut depth = 1usize;
for ch in src[j..].chars() {
j += ch.len_utf8();
match ch {
'<' => depth += 1,
'>' => {
depth -= 1;
if depth == 0 {
break;
}
}
_ => {}
}
}
while src[j..].starts_with(char::is_whitespace) {
j += 1;
}
}
if !src[j..].starts_with('(') {
continue;
}
j += 1;
// 跳過空白,允許一層 AssertSqlSafe(
while src[j..].starts_with(char::is_whitespace) {
j += 1;
}
for wrapper in ["sqlx::AssertSqlSafe(", "AssertSqlSafe("] {
if src[j..].starts_with(wrapper) {
j += wrapper.len();
while src[j..].starts_with(char::is_whitespace) {
j += 1;
}
break;
}
}
if let Some((sql, _)) = read_rust_string(src, j) {
out.literals.push((file.to_string(), sql));
} else {
let snippet = src[j..].chars().take(60).collect::<String>();
out.dynamic.push(format!("{file}: {}", snippet.split_whitespace().collect::<Vec<_>>().join(" ")));
}
}
out
}
fn rust_files(dir: &Path, into: &mut Vec<PathBuf>) {
for e in std::fs::read_dir(dir).expect("讀 src 目錄").filter_map(Result::ok) {
let p = e.path();
if p.is_dir() {
rust_files(&p, into);
} else if p.extension().is_some_and(|x| x == "rs") {
into.push(p);
}
}
}
/// SQLite 的 prepare 會驗表名與欄位名——這就是 `sqlx::query!` 會做、而我們沒做的檢查。
///
/// 弄壞任何一支 migration 的欄位名(或改錯一句 SQL),這個測試會指名道姓地紅在
/// 那一句上,而不是等線上某條冷路徑被走到。
#[tokio::test]
async fn every_literal_sql_prepares_against_the_migrated_schema() {
let pool = migrated_pool().await;
let mut files = Vec::new();
rust_files(&manifest_dir().join("src"), &mut files);
files.sort();
let mut literals = Vec::new();
let mut dynamic = Vec::new();
for f in &files {
let src = std::fs::read_to_string(f).expect("讀原始碼");
let name = f.strip_prefix(manifest_dir()).unwrap_or(f).display().to_string();
let mut e = extract(&src, &name);
literals.append(&mut e.literals);
dynamic.append(&mut e.dynamic);
}
assert!(
literals.len() >= 100,
"只抽到 {} 句寫死的 SQL,比預期少太多——抽取邏輯大概壞了,\
而一個抽不到東西的檢查會安靜地永遠是綠的",
literals.len()
);
let mut conn = pool.acquire().await.expect("取連線");
let mut failures = Vec::new();
for (file, sql) in &literals {
// PRAGMA 之類的非查詢語句 prepare 得過但沒有意義,一併跑無妨
// sqlx 0.9 的 describe 收 SqlStr;SQL 來源是本 repo 的原始碼,不是外部輸入。
let stmt = sqlx::SqlSafeStr::into_sql_str(sqlx::AssertSqlSafe(sql.as_str()));
if let Err(e) = conn.describe(stmt).await {
failures.push(format!(
" {file}\n SQL: {}\n 錯誤: {e}",
sql.split_whitespace().collect::<Vec<_>>().join(" ")
));
}
}
// 沒有靜靜跳過:抓不動的動態 SQL 一律印出來,讓「檢查了幾句」是誠實的數字
eprintln!(
"prepare 檢查:{} 句寫死的 SQL 全數通過;另有 {} 句是動態拼的,這個測試涵蓋不到:",
literals.len(),
dynamic.len()
);
for d in &dynamic {
eprintln!(" 略過(動態): {d}");
}
assert!(
failures.is_empty(),
"有 {} 句 SQL 對不上 migration 後的 schema(表或欄位不存在):\n{}",
failures.len(),
failures.join("\n")
);
}
#[test]
fn rust_string_reader_handles_the_shapes_that_appear_in_this_codebase() {
// 一般字串
assert_eq!(read_rust_string(r#""SELECT 1""#, 0).unwrap().0, "SELECT 1");
// 跳脫的引號
assert_eq!(read_rust_string(r#""a\"b""#, 0).unwrap().0, "a\"b");
// 行接續:換行與下一行前導空白都吃掉,補一個空格(不然 token 會黏起來)
let cont = "\"SELECT a \\\n FROM t\"";
assert_eq!(read_rust_string(cont, 0).unwrap().0, "SELECT a FROM t");
// raw string
// ⚠️ clippy 的 needless_raw_string_hashes 會叫你把這裡的 `r##` 減成 `r#`——那是錯的。
// 這串字面值的**內容**就是 `r#"SELECT "x""#`,裡面帶著 `"#`,少一層 hash 字串會在
// 那裡提早結束(實測:unclosed delimiter,直接編不過)。
#[allow(clippy::needless_raw_string_hashes, reason = "內容本身含 \"#,減 hash 會提早結束")]
{
assert_eq!(read_rust_string(r##"r#"SELECT "x""#"##, 0).unwrap().0, "SELECT \"x\"");
}
// 不是字面值 → None(呼叫端會計為動態,不會誤判成通過)
assert!(read_rust_string("sql.as_str()", 0).is_none());
assert!(read_rust_string("format!(\"x\")", 0).is_none());
}