SQLite 多線程模式完整解析：單線程、多線程、串行化模式選擇指南

三種線程安全模式

模式選擇優先級

運行時指定 > 啟動時指定 > 編譯時指定。單線程模式一旦確定不可覆蓋。

編譯時選擇

// 編譯 SQLite 時定義宏
-DSQLITE_THREADSAFE=1  // 串行化 (預設)
-DSQLITE_THREADSAFE=0  // 單線程
-DSQLITE_THREADSAFE=2  // 多線程

可用 sqlite3_threadsafe() 查詢編譯時設定：返回 0 表單線程，1 表多線程/串行化（無法區分）。

啟動時選擇

// 在 sqlite3_initialize() 前呼叫（通常在應用啟動早期）
sqlite3_config(SQLITE_CONFIG_SINGLETHREAD); // 單線程
sqlite3_config(SQLITE_CONFIG_MULTITHREAD);  // 多線程
sqlite3_config(SQLITE_CONFIG_SERIALIZED);   // 串行化

運行時選擇（每個連線獨立）

// 使用 sqlite3_open_v2() 第三個參數
sqlite3_open_v2("db.sqlite", &db, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE | SQLITE_OPEN_NOMUTEX, NULL);  // 多線程模式連線
sqlite3_open_v2("db.sqlite", &db, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE | SQLITE_OPEN_FULLMUTEX, NULL); // 串行化模式連線

若不指定旗標，則沿用編譯/啟動時的預設模式。

實戰建議

1. 高併發讀寫：使用 WAL 模式（PRAGMA journal_mode=WAL）搭配多線程模式，每線程持有獨立連線，讀寫不阻塞。
2. 簡單應用/共用連線：直接用預設串行化模式，代碼簡單無需管理連線池。
3. 唯讀/嵌入式：可考慮單線程模式榨乾效能。
4. 連線池框架：確保池化連線不被多線程同時使用，或啟用 SQLITE_OPEN_FULLMUTEX。

驗證當前模式

// 編譯時
int compileMode = sqlite3_threadsafe(); // 0=單線程, 1=其他

// 運行時無直接 API 查詢，建議應用層記錄開啟時的旗標

常見誤區

• 以為預設模式就是「多線程安全」→ 實際是「串行化」，高併發效能差。
• 多線程模式下跨線程共用同一 sqlite3* 連線 → 會崩潰或資料損壞。
• 在單線程編譯的庫上嘗試啟用多線程 → 不可能，互斥邏輯已被編譯器優化移除。