本文是 SQLite overview 的 implementation-layer deep article。Overview 已說明 SQLite 適合 embedded、local-first、edge 與低操作成本場景；本文聚焦 SQLite 檔案生命週期 + backup / restore 邊界。

SQLite 的 file lifecycle 是把「一個資料庫檔案」升級成正式狀態的操作契約。SQLite 省掉 server process、帳號管理與網路連線，但它把 durability、backup、restore、locking 與 corruption recovery 放回 application process、filesystem 與 runbook；讀者要判斷的是這些責任是否已經有人承擔。

這篇文章適合三種情境。第一種是 CLI、desktop、mobile 或 edge service 已經用 SQLite 保存正式資料；第二種是 single-instance backend 想用 SQLite 降低操作成本；第三種是 test fixture 用 SQLite，但需要知道哪些差異會讓 production database 的 bug 漏掉。

核心模型：資料庫檔案是一組受 SQLite 管理的狀態檔

SQLite 的資料庫狀態由 main database file 與 journal / WAL sidecar 共同構成。Rollback journal mode 會在寫入期間產生 journal file；WAL mode 會讓寫入先進入 -wal 檔，並用 -shm 檔協調 reader / writer。操作上看似「一個 .db 檔」，production runbook 要把 sidecar file、checkpoint、backup API 與 restore test 一起納入。

這張表的讀法是先找「誰有權改檔案」。SQLite 的核心風險多半來自繞過 SQLite library 的檔案操作，例如直接 copy 活躍 WAL database、把 database 放在 lock 語意不可靠的 filesystem、或讓多個不協調的 process 同時寫同一份檔案。

WAL mode：讀取並發提升後，writer boundary 仍然存在

WAL mode 的工程價值是讓 reader 與 writer 的衝突下降。讀取可以看 main database 加上 WAL 中的 snapshot，寫入則 append 到 WAL；這讓 read-heavy workload 比 rollback journal mode 更容易撐住互動式服務。

WAL mode 同時保留 single writer boundary。SQLite 仍以檔案鎖與 transaction serialisation 控制寫入；寫入交易越長，其他 writer 等待時間越長，application 看到的訊號通常是 SQLITE_BUSY、latency spike 或 background job 卡住。

WAL mode 的 capacity gate 是「寫入是否仍能用一個 writer 排隊」。如果服務壓力來自大量並行寫入、多 instance active write 或跨 region 寫入，SQLite 的簡單性開始變成排隊與恢復成本；這時候要回到 PostgreSQL、MySQL 或 global distributed OLTP。

Backup boundary：複製檔案與取得一致 snapshot 是兩件事

SQLite backup 的核心責任是取得某一時間點的一致 snapshot。當 database live 且 WAL mode 開啟時，直接複製 .db 檔容易漏掉 -wal 中尚未 checkpoint 的寫入；即使同時複製 sidecar file，也要面對複製期間狀態變動的 race。正式服務應使用 SQLite 提供的 backup path 或可驗證的 filesystem snapshot。

Backup method 的選擇要先回到 RPO 與 RTO。如果產品可以接受每天一次快照，VACUUM INTO 或 scheduled backup 足夠；如果資料損失窗口要降到分鐘級或秒級，就要看 Litestream 類連續複製，或直接升級到 server database 的 PITR / replica 模型。

Restore drill：SQLite production readiness 看還原，不只看備份成功

Restore drill 的責任是證明備份能在事故時接回服務。SQLite 的備份檔通常只有一個 target file，表面上比 PostgreSQL PITR 或 MySQL binlog recovery 簡單；真正的風險在 application binary、schema migration version、file permission、deployment path 與舊 WAL sidecar 是否一起對齊。

一個最小 restore drill 應保留五個檢查點：

1. 從備份產出新的 database file，不覆蓋 production path。
2. 用 application binary 啟動 read-only smoke test，確認 schema version 與 migration table。
3. 跑 row count、critical query、checksum 或 domain validation query。
4. 驗證 file owner、permission、disk path、SELinux / container mount 或 volume 設定。
5. 以 incident decision log 記錄 restore time、data freshness、known gap 與 owner。

Restore drill 的交付物應接回 Observability Evidence Package 與 Incident Decision Log。SQLite 的低操作成本來自日常元件少；事故時仍需要 evidence、owner 與 rollback condition。

Corruption recovery：先保全證據，再決定修復或還原

SQLite corruption recovery 的核心責任是區分「資料庫檔案本身受損」與「application 寫入了錯誤資料」。前者要走 file-level evidence、.recover、backup restore 與 filesystem / hardware investigation；後者要走資料修復、migration rollback 或 business reconciliation。

Corruption 事件的第一個操作是保存原始檔案與 sidecar。直接在疑似受損檔案上跑修復、vacuum 或 application migration，會讓後續 root cause analysis 失去證據；比較穩定的流程是複製原檔、在副本上嘗試 .recover，同時從備份恢復服務路徑。

Anti-recommendation：維持 SQLite 的條件要可被操作驗證

SQLite 的合理使用條件是「單一 writer、檔案生命週期清楚、restore drill 成立」。只要這三件事能被 runbook 驗證，SQLite 在 embedded、desktop、mobile、edge-local 或 small backend 場景可以是 production state。

升級條件則來自操作責任外溢。需要 database user / role、中心化 audit、多人同時寫、跨 instance failover、online schema migration、PITR、read replica 或跨 region transaction 時，server SQL 或 managed SQL 的操作模型會比繼續包裝 SQLite 清楚。

這張表的核心是把操作責任具體化，而非替 SQLite 設流量天花板。小型服務可能用 SQLite 長期穩定運作；同樣流量下，一旦合規、稽核、多人操作或 HA 需求進來，server database 的長期成本會更容易被治理。

操作檢查清單

SQLite production runbook 至少要能回答下列問題：

1. Database file、WAL sidecar 與 backup target 在哪個 volume、由誰擁有。
2. journal_mode、synchronous、busy timeout、checkpoint cadence 與 migration policy 如何設定。
3. Backup 用 .backup / backup API / VACUUM INTO / Litestream 的哪一條路徑。
4. Restore drill 最近一次何時執行，RPO / RTO 是否符合產品承諾。
5. SQLITE_BUSY、WAL growth、disk full、backup failure 與 restore failure 如何告警。
6. Corruption recovery 時誰保存原檔、誰啟動 restore、誰決定修復或 fail-forward。

這份清單要接到服務 ownership，而非留在工程師個人習慣。SQLite 的優勢是 deployment surface 小；production 化的代價是把檔案、備份與恢復流程寫進同一份可交接 runbook。

引用路徑

• 上游 overview：SQLite vendor page
• 服務責任：Source of Truth、Database
• 恢復目標：RPO、RTO
• 證據交接：Observability Evidence Package、Incident Decision Log
• 官方文件：SQLite Write-Ahead Logging、SQLite Backup API、How To Corrupt An SQLite Database File、Recovering Data From A Corrupt SQLite Database、Appropriate Uses For SQLite、Most Widely Deployed SQL Database Engine
• 延伸工具：Litestream restore reference、Litestream getting started

本文的驗收標準是：你能用兩個 sqlite3 session 重現 writer contention，觀察 busy timeout 行為，並用 WAL size 與 checkpoint result 連回 production runbook。

Prepare Database

Prepare database 的核心責任是建立可重現的 WAL mode database。若已跑過 local file quickstart，可以沿用 /tmp/sqlite-lab/app.db。

1cd /tmp/sqlite-lab
2sqlite3 app.db "PRAGMA journal_mode = WAL;"
3sqlite3 app.db "PRAGMA busy_timeout = 1000;"

確認 WAL mode：

1sqlite3 app.db "PRAGMA journal_mode;"

預期輸出是 wal。

Session A: Hold Writer Lock

Session A 的核心責任是刻意持有 write transaction。開第一個 terminal，執行：

1sqlite3 app.db

在 sqlite prompt 內輸入：

1PRAGMA foreign_keys = ON;
2BEGIN IMMEDIATE;
3INSERT INTO ledger_entries(account_id, amount_cents, idempotency_key, created_at)
4VALUES (1, 11, 'busy-session-a', '2026-05-21T02:00:00Z');

先保持 transaction 開啟，暫時延後 COMMIT。BEGIN IMMEDIATE 會取得 writer lock，讓第二個 writer 需要等待或失敗。

Session B: Observe Busy

Session B 的核心責任是用第二個 connection 觀察 single writer boundary。開第二個 terminal，執行：

1cd /tmp/sqlite-lab
2sqlite3 app.db "PRAGMA busy_timeout = 1000; INSERT INTO ledger_entries(account_id, amount_cents, idempotency_key, created_at) VALUES (1, 22, 'busy-session-b', '2026-05-21T02:01:00Z');"

預期結果是等待約 1 秒後出現 busy / locked 類錯誤。不同 sqlite3 版本的錯誤文字可能略有差異，核心訊號是第二個 writer 在 Session A commit 前拿不到 write lock。

Release Lock

Release lock 的核心責任是確認 contention 來自 writer transaction。回到 Session A，輸入：

1COMMIT;
2.quit

再次執行 Session B 的 insert，這次應成功。

1sqlite3 app.db "PRAGMA foreign_keys = ON; INSERT INTO ledger_entries(account_id, amount_cents, idempotency_key, created_at) VALUES (1, 22, 'busy-session-b', '2026-05-21T02:01:00Z');"

若 idempotency key 已在前一次嘗試中寫入，改成新的 key。這個細節也提醒 production write 要有 idempotency 設計。

Busy Timeout Comparison

Busy timeout comparison 的核心責任是區分「等一下」和「解決 writer contention」。Timeout 可以讓短暫鎖等待更平滑，但長交易仍會造成延遲或失敗。

重開 Session A 並持有 transaction：

1BEGIN IMMEDIATE;
2INSERT INTO ledger_entries(account_id, amount_cents, idempotency_key, created_at)
3VALUES (1, 33, 'busy-session-a-long', '2026-05-21T02:10:00Z');

在 Session B 測不同 timeout：

1time sqlite3 app.db "PRAGMA busy_timeout = 5000; INSERT INTO ledger_entries(account_id, amount_cents, idempotency_key, created_at) VALUES (1, 44, 'busy-session-b-long', '2026-05-21T02:11:00Z');"

若 Session A 在 5 秒內 commit，Session B 可能成功；若持續持有 transaction，Session B 會在 timeout 後失敗。這就是 production 裡 busy timeout 的邊界：它緩衝短鎖，長 transaction 仍要被設計移除。

WAL and Checkpoint

WAL and checkpoint 的核心責任是把 writer activity 和 file artifact 連起來。多做幾次寫入後觀察 sidecar。

1ls -lh app.db app.db-wal app.db-shm
2sqlite3 app.db "PRAGMA wal_checkpoint(PASSIVE);"

wal_checkpoint 會回傳 checkpoint 狀態。正式 runbook 要記錄 WAL size、checkpoint duration、reader age 與 checkpoint failure。

可以手動觸發 truncate checkpoint：

1sqlite3 app.db "PRAGMA wal_checkpoint(TRUNCATE);"
2ls -lh app.db app.db-wal app.db-shm

TRUNCATE 適合 lab 觀察。Production 使用時要評估 reader、latency 與維護窗口。

Mitigation Note

Mitigation note 的核心責任是把 lab 結果轉成設計策略。看到 SQLITE_BUSY 後，優先檢查 long transaction、未關閉 cursor、背景 job、write burst、parallel test 共用 DB 與 checkpoint pressure。

常見策略包含：

1. 縮短 transaction，將外部 API call 移到 transaction 外。
2. 設定合理 busy timeout 與 retry backoff。
3. 把 write queue 序列化，讓高風險 workflow 先排隊。
4. 將 heavy read 移到 snapshot 或 replica。
5. 當 concurrent writer 成為常態，評估 PostgreSQL / MySQL。

完成本篇後，下一步讀 observability / runbook 把 busy、WAL 與 checkpoint 變成正式監控訊號。

本文是 SQLite overview 的 implementation-layer deep article。Overview 已說明 SQLite 的 single-file / embedded 定位；本文聚焦 WAL concurrency、single writer boundary、SQLITE_BUSY 與 checkpoint strategy。

SQLite WAL concurrency 的核心責任是讓 reader / writer 衝突下降，同時保留單檔案資料庫的寫入邊界。WAL mode 把寫入 append 到 -wal sidecar file，reader 可以從 main database file 加 WAL snapshot 讀取一致視圖；這讓 read-heavy workload 能比 rollback journal mode 更順。但 SQLite 仍遵循 single writer model、只有一條 writer path，長交易、背景 migration、慢 disk 或多 process 寫入都會在這條 path 上排隊。

本文的判讀錨點是：WAL 提升的是 reader concurrency，治理的是 writer queue。當服務看到 SQLITE_BUSY、WAL file 持續變大、checkpoint duration 變長或偶發 commit latency spike，問題通常在 transaction duration、checkpoint cadence、filesystem lock 或 process ownership，而非單純「資料庫太小」。

WAL mode 的服務責任

WAL mode 的服務責任是把「寫入直接改 main database file」改成「寫入先 append 到 WAL，再由 checkpoint 合併回 main database」。SQLite 官方文件把 WAL 模型拆成 reading、writing、checkpointing 三個 primitive；這個 framing 對 production runbook 很重要，因為 checkpoint 會變成獨立的操作訊號。

這張表的讀法是先看服務是否主要受 read / write 衝突影響。Read-heavy CLI、desktop、mobile、edge-local API 或 small backend 往往能從 WAL mode 受益；write-heavy queue consumer、batch import、multi-process writer 或 high-concurrency OLTP 則會先撞到 single writer boundary。

Locking model：多 reader 與單 writer 是同時成立的

SQLite locking model 的核心責任是保護單一 database file 的 ACID 邊界。Rollback journal mode 的官方 locking 文件描述了 SHARED、RESERVED、PENDING、EXCLUSIVE 等狀態；WAL mode 的細節另由 WAL 文件說明，但服務判讀上仍要記住同一件事：跨 connection / process 的寫入要被序列化。

多 reader 與單 writer 的組合是 SQLite 的正常設計。讀者在查問題時，要避免把 SQLITE_BUSY 直接解讀成資料毀損；它多半代表某個 connection 正在持有 writer 所需的 lock，或 checkpoint / transaction 正在等待可前進的窗口。

SQLITE_BUSY 的第一輪排查

SQLITE_BUSY 的核心意義是某個 connection 當下拿不到需要的 lock。SQLite 提供 busy_timeout 讓 connection 等待一段時間；這能吸收短暫 writer queue，但它只是等待策略，single writer boundary 仍然存在。

這張表的重點是先找「誰持有 writer path」。如果問題來自單一長 transaction，修 transaction boundary；如果問題來自多個 process 同時寫同檔，修 process ownership；如果問題來自真實高寫入吞吐，SQLite 已經接近服務邊界。

Busy timeout 是緩衝器，容量邊界仍在 writer path

Busy timeout 的服務責任是吸收短時間 lock collision。它適合 desktop app autosave、mobile local store、短 API write、測試 fixture 或偶發 background job；它不適合作為高寫入吞吐的主要容量策略。

1PRAGMA busy_timeout = 5000;

這個設定代表 connection 最多等待 5000 ms。Production runbook 要同時記錄三個訊號：busy 次數、等待時間分布、等待後成功率。若等待後成功率高且 p99 可接受，代表 writer queue 仍在服務邊界內；若等待常超時，代表 transaction duration 或 writer 並發已經超出單檔模型。

Checkpoint strategy：WAL growth 是操作訊號

Checkpoint 的核心責任是把 WAL 中的 committed frames 合併回 main database file。SQLite 預設會在 WAL file 達到約 1000 pages 後自動 checkpoint；這個預設適合多數小型場景，但 production 服務要把 checkpoint 視為獨立操作。

1PRAGMA wal_checkpoint(PASSIVE);
2PRAGMA wal_checkpoint(FULL);
3PRAGMA wal_checkpoint(RESTART);
4PRAGMA wal_checkpoint(TRUNCATE);

Checkpoint 策略的判讀要看 workload cadence。互動式服務通常保留 auto-checkpoint，再加上低流量時段的 background checkpoint；長查詢或 reporting workload 需要避免讓 long reader 長期佔住 snapshot；batch import 則要把 transaction 切小，避免 WAL file 在單一交易期間快速膨脹。

Checkpoint starvation：長 reader 會讓 WAL 持續長大

Checkpoint starvation 的核心概念是：只要總有 reader 還在使用舊 snapshot，checkpoint 就可能停在 reset 之前。SQLite 官方 WAL 文件明確指出，checkpoint 可以和 reader 並行，但遇到仍被 reader 使用的 WAL 位置時要停下來；如果長時間沒有 reader gap，WAL file 會持續成長。

這些情境的共同點是 reader lifecycle 沒有被 application 控制。SQLite 的 concurrency 問題常發生在 application boundary，而非 database engine 本身；修法也應回到 handler、worker、test runner 或 UI lifecycle。

Filesystem 與 deployment boundary

SQLite WAL 的 deployment boundary 是 local filesystem 與可靠 shared-memory / file-locking primitive。官方 WAL 文件指出 wal-index 使用 shared memory，所有 reader 要位於同一台機器；這也是 WAL mode 不適合放在一般 network filesystem 上的主要原因。

Deployment review 要問的第一個問題是「同一時間誰會寫這個檔案」。如果答案是多個 instance、跨機器 process 或不受控 job，SQLite 的服務邊界已經需要重新評估。

Production 踩雷

Case 1：多個 worker 同時寫同一個 SQLite 檔

多 worker 寫入同一個 SQLite 檔的核心風險是 writer ownership 消失。常見情境是小型服務從單 instance 擴到多 instance，但仍把 database file 放在 shared volume；早期看起來可運作，流量上升後開始出現 busy timeout、WAL growth 與偶發資料修復壓力。

修正方向是重新定義 writer。若服務仍是 small backend，可以收斂到單 writer process + queue；若 multi-instance 是長期需求，應遷移到 PostgreSQL 或 MySQL。

Case 2：長讀取卡住 checkpoint，磁碟被 WAL 吃滿

長讀取卡 checkpoint 的核心風險是 WAL file 成為隱性容量消耗。讀者可能只看到 disk usage 增長，誤以為是資料量變大；實際上 main database file 沒有明顯增長，-wal sidecar 持續膨脹。

修正方向是先找到長 reader，再調整 query lifecycle。Reporting query、background sync、streaming response、互動式 UI 大列表都要有 pagination、timeout 或低流量窗口；checkpoint 只負責收斂 WAL，application 仍要主動結束長讀取。

Case 3：把 busy timeout 當成擴容策略

Busy timeout 被當成擴容策略的核心風險是延遲被隱藏到使用者路徑。短暫 lock collision 可以等待；長期 write queue 則會把 API p99、UI freeze 或 worker backlog 拉高。

修正方向是把 busy wait 當 metric。設定 timeout 後要記錄等待時間與超時率；當 busy wait 成為常態，下一步是拆交易、調整 writer process、移走 batch job，或升級到 server database。

Case 4：checkpoint 放在高流量 commit path

Checkpoint 放在高流量 commit path 的核心風險是少數 commit 變得很慢。SQLite 預設 auto-checkpoint 對多數場景合理，但互動式服務可能看到偶發 latency spike；這時可以把 checkpoint 移到背景 thread / process 或低流量窗口。

修正方向是把 checkpoint duration 變成 evidence。觀察 WAL size、checkpoint return、commit latency 與 disk sync；若尖峰可接受，維持預設；若尖峰影響 UX，調整 checkpoint cadence。

Case 5：WAL mode 版本與部署條件未納入維護

WAL mode 的維護責任包含 SQLite runtime version、filesystem、sidecar file 與 release notes。SQLite 官方 WAL 文件記錄 2026-03 修正過罕見 WAL-reset bug；雖然觸發條件很窄，production runbook 仍應記錄 SQLite version、runtime package 與更新策略。

修正方向是把 SQLite runtime 當成 dependency。Mobile、desktop、embedded、language binding、OS bundled SQLite 可能各自帶不同版本；需要在 support matrix 中標明版本來源、WAL mode 行為與升級路徑。

操作檢查清單

SQLite WAL / locking runbook 至少要能回答下列問題：

1. Database file、-wal、-shm 是否位於 local durable filesystem。
2. 同一時間哪些 process / thread 會寫入 database file。
3. PRAGMA journal_mode、busy_timeout、wal_autocheckpoint 如何設定。
4. SQLITE_BUSY 次數、等待時間、超時率是否被記錄。
5. WAL file size、checkpoint duration、disk usage 是否被觀測。
6. 長 read transaction 的來源與 timeout 如何治理。
7. Batch import、migration、background sync 是否避開互動式高峰。
8. SQLite runtime version 與 WAL 相關 release notes 如何追蹤。

這份清單要接到 Observability / runbook 與 SQLite Hands-on；正文教判讀，hands-on 負責讓讀者重現 SQLITE_BUSY、WAL growth 與 checkpoint 行為。

何時維持 SQLite，何時升級

SQLite WAL mode 適合單機、短交易、read-heavy、writer ownership 清楚的服務。只要 busy wait 可控、checkpoint 能完成、backup / restore drill 成立，SQLite 可以承擔正式狀態。

升級訊號來自 writer boundary 外溢。多 instance write、多 region write、high-write OLTP、集中權限治理、read replica、PITR、DB account / role 與 audit requirement 都會把服務推向 server SQL、edge SQLite product 或 distributed SQL。

下一步路由

• 上游：SQLite overview
• 前置：File lifecycle / backup boundary
• 操作：SQLite Hands-on 與 WAL busy reproduction
• 平行：PRAGMA tuning / performance、Observability / runbook
• 遷移：SQLite to PostgreSQL
• 官方：SQLite Write-Ahead Logging、SQLite File Locking、SQLite Isolation、SQLite PRAGMA