教學路線：單檔正式狀態與 local-first

SQLite 服務頁的教學目標是把單機、單檔案、edge、desktop、test fixture 的正式狀態責任說清楚。讀者讀完後要能判斷 SQLite 何時是 production state，何時要轉向 server database、edge KV 或分散式 SQLite 變體。

定位：單檔案 embedded + 新興分散式 SQLite 生態

SQLite 跟 PostgreSQL / MySQL 承擔不同層級的資料責任：

• 以 function-call API 使用，省掉 server process
• 單一檔案（含 schema、data、index、metadata）
• 無 user / role / connection 概念
• 同 process 同時 read / write 受 file lock 限制

傳統定位：test fixture、CLI tool data store、mobile app（iOS / Android 內建）、edge device。

新興定位：edge serverless（Cloudflare D1）、distributed SQLite（Turso、rqlite）、replicated SQLite（Litestream）。

容量特性

單檔案上限：

• DB 最大 281 TB（理論）
• 實務上單表 > 100 GB 開始有 vacuum / index 問題

並發寫：

• WAL mode：可同時多 reader + 1 writer
• 寫入仍由 single writer boundary 控制
• 寫吞吐受 disk fsync 限制（通常 < 1K WPS）

並發讀：

• WAL mode 多 reader 可同時跑
• read-only workload 可以撐高吞吐

Cross-process / cross-instance：

• 多個 process / instance 同時寫同一檔案會破壞 single writer boundary
• 需要分散時用 Litestream（replication）或 Turso（distributed）

適用場景

1. Test fixture / CI 用 DB：

• 整合測試需要的 fixed DB
• 比 spin up PostgreSQL container 快
• 對應 1.4 Repository Adapter 的 contract test 模式

2. CLI tool / desktop app 內建 store：

• Chrome / Firefox（cookies、history、bookmark）、Fossil SCM、iOS app
• 省掉 server、單檔案攜帶

3. Mobile app（iOS / Android）：

• iOS Core Data 底層用 SQLite
• Android 自帶 SQLite API
• offline-first app 的標準

4. Single-instance backend（特殊場景）：

• 流量小 + HA 由備份 / restore / redeploy 流程承擔
• 例：Sidekick / 個人 SaaS / family-scale app
• 配合 Litestream 做 backup / DR

5. Edge / serverless（新興）：

• Cloudflare D1：edge SQLite、跟 Workers 整合
• Turso：distributed SQLite、跨 region replication
• 跟傳統 SQLite 不同等級、是 新的 product

6. Embedded device / IoT：

• 沒網路或要降低 server 依賴
• SQLite 內建、無 external dependency

不適用場景

1. 多 instance / 多 region web service：

• SQLite 的單檔模型以單 instance writer 為主要邊界
• 替代：PostgreSQL、Aurora、Spanner、CockroachDB

2. 高寫入吞吐（> 1K WPS）：

• fsync 限制
• 替代：任何 server-based RDBMS

3. Multi-user 權限管理：

• 無 user / role 概念
• 替代：PostgreSQL / MySQL

4. 跨機器 transaction：

• SQLite 是 single-machine
• 替代：分散式 SQL

5. 大規模 production OLTP：

• 大規模 production OLTP 需要 server database 的 HA、replica、權限與操作邊界
• 替代：MySQL / PostgreSQL / Aurora

跟其他 vendor 的取捨

vs PostgreSQL（作為 test DB）：

• SQLite：快 spin up、SQL dialect 接近但有差異
• PostgreSQL：跟 production 一致、發現的 bug 真實
• 選 SQLite：speed of iteration、簡單 query
• 選 PostgreSQL：catch production-like bug、PostgreSQL-specific 特性測試

vs Cloudflare D1：

• SQLite（local）：單機、自管
• D1：edge serverless、跟 Workers 整合
• 選 SQLite：embedded / CLI / app 場景
• 選 D1：edge web service、跟 Cloudflare 生態整合

vs Turso（distributed SQLite）：

• SQLite：單機、單檔案
• Turso：distributed、跨 region replication、SQLite-compatible
• 選 SQLite：simple use case
• 選 Turso：需要 SQLite simplicity + 全球分散

vs Litestream（replicated SQLite）：

• SQLite：單檔案
• Litestream：把 SQLite 變成 streaming replicated 到 S3
• 選 Litestream：想要 SQLite simplicity + DR

vs Firebase / Firestore（mobile app）：

• SQLite：embedded、offline-first、無 sync
• Firestore：realtime、自動 sync、雲端 store
• 選 SQLite：offline-first、單機
• 選 Firestore：multi-device sync、realtime

容量規劃要點

1. WAL mode 是 production baseline：

• default journal mode 是 rollback journal（每寫都 lock）
• WAL（Write-Ahead Log）讓多 reader 可同時跑
• PRAGMA journal_mode = WAL

2. fsync 配置：

• PRAGMA synchronous = FULL（durable、慢）
• PRAGMA synchronous = NORMAL（faster、少數情況可能掉資料）
• PRAGMA synchronous = OFF（最快、不安全）

3. mmap 加速 read：

• PRAGMA mmap_size = 268435456（256 MB）
• 把 DB 部分內容 mmap 進 RAM、加速 read

4. Cache size：

• PRAGMA cache_size = -64000（64 MB cache）
• 大 cache 對 read-heavy workload 有幫助

5. Auto-vacuum：

• 預設 off、delete 後檔案不縮小
• PRAGMA auto_vacuum = INCREMENTAL + 定期 PRAGMA incremental_vacuum

章節群結構

SQLite 章節群的責任是把單檔正式狀態、embedded process、writer boundary、backup / restore、test fixture、local-first 與 edge SQLite 變體拆成可教學路線。完整結構見 SQLite Teaching Structure；下表列出目前已建立的 deep article、hands-on 與 migration route。

章節群的讀法是先讀 file lifecycle，再按壓力選 deep article。若問題是 write contention，讀 WAL locking；若問題是測試，讀 test fixture；若問題是 edge / serverless，讀 D1 / Turso comparison；若問題是服務長大，讀 SQLite to PostgreSQL migration。

Anti-recommendation 與升級路由

SQLite 的低操作成本容易讓團隊忽略它的 writer boundary。這一段先說何時維持 SQLite，再說何時升級到 server SQL、edge SQLite 變體或 managed KV。

SQLite 的簡單路徑是讓檔案生命週期成為正式操作流程。只要單一 writer、備份、restore、migration 與 file ownership 都能被 runbook 控制，SQLite 可以是正式狀態，而非臨時 cache。

升級到 server SQL 的訊號是操作責任超過檔案邊界。當團隊需要資料庫帳號、權限分層、read replica、線上 schema migration、集中 audit 或跨 instance failover 時，PostgreSQL / MySQL / Aurora 會比繼續包裝 SQLite 更清楚。

已知 limitation 與後續路由

SQLite overview 目前已完成服務判斷與章節群正文路由。File lifecycle、WAL locking、PRAGMA tuning、schema migration、test fixture、local-first sync、edge product 差異、observability、hands-on 與 migration route 都已有對應正文；下一輪審查可集中在案例補強、引用精度與跨章重複整理。

案例對照

SQLite 不在 09 case 庫的「規模化 vendor」類別、但作為 embedded 跟 test 廣泛使用：

• iOS Core Data：所有 iOS app 的 default DB
• Chrome / Firefox：cookie、history、bookmark
• Fossil SCM：repository metadata 與 application-file use case
• Cloudflare D1：edge serverless（新興 production 場景）
• Turso：distributed SQLite（新興 production 場景）

常見陷阱

• default journal mode 不改 WAL：read 跟 write 互相 block、performance 差
• 多 process / instance 同時寫同檔：corruption
• delete 後檔案沒縮小：忘了 vacuum
• synchronous=OFF 給 production：power loss 可能掉資料
• SQLite 跟 PostgreSQL 行為差異測試不足：SQLite test 過、PostgreSQL production 出 bug（特別是 date / time、NULL 處理、type coercion）

下一步路由

• 完整 T1 對照：01-database vendors index
• 平行：PostgreSQL vendor / MySQL vendor（production server-based RDBMS）
• 上游：1.4 Repository Adapter（test fixture 模式）
• 結構：SQLite Teaching Structure（完整章節群與寫作順序）
• 操作：SQLite Hands-on（local file、backup restore、WAL busy reproduction、migration fixture、D1 / Turso preview）
• 深入：SQLite file lifecycle 與 backup boundary（WAL、backup、restore、file ownership）
• 官方：SQLite Documentation、Litestream、Turso、Cloudflare D1

本文是 SQLite overview 的 implementation-layer deep article。Overview 已說明 SQLite 適合 mobile、desktop、CLI 與 embedded device；本文聚焦 device-local formal state 的資料責任、backup、privacy 與 sync boundary。

SQLite embedded store 的核心責任是讓 application process 在本機持有正式狀態。Mobile app、desktop app、browser profile、CLI tool 與 embedded device 常用 SQLite 保存 local data；這些資料可能只是 cache，也可能是使用者唯一資料來源。教學上要先判斷它是否承擔 source of truth，再決定 backup、sync、privacy 與 migration 責任。

本文的判讀錨點是：embedded SQLite 的 production boundary 在 device lifecycle，database server 層的邊界在這裡不適用。OS backup、app upgrade、device loss、profile corruption、local PII、multi-device sync 與 user export / delete 都是資料庫責任的一部分。

Embedded state model

Embedded state model 的核心責任是把 local database file 放回 application lifecycle。SQLite 是典型的 embedded database：database file 通常跟著 app sandbox、user profile、CLI config directory 或 device storage 存在，它的 owner 是 application，而非獨立 DBA。

這張表的重點是資料角色而非產品名稱。同樣是 SQLite file，cache 可以清掉重建；draft、local-only note、sensor event 或 user history 可能需要正式 backup / export / delete。

Backup 與 export

Embedded backup 的核心責任是讓使用者或服務能從 device / profile failure 復原。Mobile / desktop / CLI 的 backup 路徑常和 OS backup、app export、cloud sync 或手動複製混在一起；SQLite file lifecycle 要明確。

Backup 設計要先決定 restore target。Restore 到同 app version、未來 app version、或不同 device，會帶來不同 schema compatibility 與 privacy requirement。

Privacy 與 local PII

Embedded SQLite 的 privacy 責任是治理 device-local data。資料在 server DB 中通常有 access log、IAM、DLP 與 retention policy；進入 SQLite file 後，風險轉到 device encryption、app sandbox、backup retention、debug export 與 support bundle。

SQLite file 要進入資料保護盤點。若 local DB 保存敏感資料，應連到 Data Protection 與 Audit Log 的相同問題，只是控制面改在 device / app。

App upgrade 與 schema compatibility

App upgrade 的核心責任是保證新版 binary 能安全打開舊 database file。Mobile / desktop app 的使用者不會按照 backend deployment order 升級；同一時間可能存在多個 app version 與多個 DB schema version。

這些策略要和 Schema Migration / Versioning 對齊。Embedded app 的 migration failure 通常直接影響使用者啟動體驗，因此 migration 要能快速、可恢復、可診斷。

Sync boundary

Sync boundary 的核心責任是把 single-device SQLite 和 multi-device state 分開。SQLite 保存本地狀態；跨裝置同步需要 transport、identity、conflict resolution、delete propagation 與 server authority。

當 sync 需求出現時，SQLite 仍可作為 local store，但不再單獨承擔完整資料一致性。完整性要由 sync protocol 與 server-side validation 補上。

Production 踩雷

Case 1：把 cache 當正式資料

Cache 被誤當正式資料的核心風險是清除 local DB 會造成不可恢復資料損失。許多 app 初期把 SQLite 當 cache；後來加入 draft、offline action 或 local-only setting，資料責任就改變了。

修正方向是逐 table 標示資料角色。Cache table 可清；formal state table 要 backup、migration、export 與 delete policy。

Case 2：OS backup 帶走敏感資料

OS backup 的核心風險是 device-local PII 進入使用者或平台雲端備份。Server 端已刪除的資料，可能仍存在 device backup。

修正方向是決定哪些資料可被備份。Token、secret、敏感 PII 可排除或加密；user-owned content 則要提供 export / restore 語意。

Case 3：App upgrade migration 失敗讓使用者卡在啟動頁

Startup migration 失敗的核心風險是使用者卡在 app 啟動前，且修復能力有限。SQLite file 在使用者裝置上，SRE 通常需要透過 app update、support bundle 或 restore flow 處理。

修正方向是保留 pre-migration snapshot、提供 safe mode、收集匿名 schema / error evidence，並避免長 migration 放在 cold start。

操作檢查清單

Embedded SQLite 設計要回答：

1. 每張 table 是 cache、formal state、derived state 還是 sync queue。
2. Database file 在 app / OS 的哪個 storage boundary。
3. OS backup 是否包含 database file。
4. 敏感欄位是否加密、排除或可清除。
5. App upgrade migration 是否有 pre-migration backup。
6. 使用者 export / delete / support bundle 如何處理 SQLite data。
7. Multi-device sync 是否有 conflict 與 server authority 設計。

下一步路由

• 上游：SQLite overview
• Sibling：Local-first Sync Boundary、Schema Migration / Versioning
• 操作：SQLite Hands-on
• 跨模組：Data Protection
• 官方：SQLite Appropriate Uses、SQLite Backup API