1type BasicStorage interface {
 2    Store(event Event) error
 3    Query(filter QueryFilter) ([]Event, error)
 4    Close() error
 5    Downsample() error
 6    Purge() error
 7}
 8
 9type AnalyticsStorage interface {
10    BasicStorage
11    Aggregate(spec AggregateSpec) (AggregateResult, error)
12    Funnel(steps []string, timeWindow Duration) (FunnelResult, error)
13    Cohort(groupBy string, metric string) (CohortResult, error)
14}

SQLite implementation 只實作 BasicStorage。PostgreSQL implementation 實作 AnalyticsStorage。Dashboard 用 Go 的 type assertion（if as, ok := storage.(AnalyticsStorage); ok { ... }）判斷能力 — funnel/cohort 視圖在 SQLite 模式下不顯示入口，而非顯示後報錯。

選擇哪個 backend 取決於部署場景和查詢需求：

SQLite Backend（day-one 預設）

SQLite 是嵌入式資料庫，編譯進 collector binary 中，不需要額外 server。Go 用 modernc.org/sqlite（pure Go、無 CGO 依賴、效能約為 CGO driver mattn/go-sqlite3 的 60-80%，自用規模下足夠），開源使用者 go build && ./collector 就能跑，部署步驟為零。WAL mode 允許讀寫並行 — dashboard 的 SELECT 查詢不會被 ingestion 的 INSERT 阻塞，反之亦然。寫入之間的競爭由 busy_timeout 處理。

能力範圍

• 索引查詢：按 type、name、timestamp 建索引，查詢從全表掃描變成索引查找
• SQL 聚合：SELECT name, COUNT(*) FROM events WHERE type='error' GROUP BY name — 一行 SQL 完成分群計數
• 跨欄位過濾：WHERE type='error' AND name LIKE 'terminal.%' AND ts > '2026-06-18'
• 寫入：WAL mode 下每秒數千筆 append 寫入

Events 主表 DDL

Events 表的欄位從 event.schema.json 的 JSON 結構推導。Source 的 nested object 攤平成獨立 column — 方便 SQL 查詢和索引，不需要每次從 JSON 裡 extract。

 1CREATE TABLE events (
 2    id INTEGER PRIMARY KEY AUTOINCREMENT,
 3    v INTEGER NOT NULL DEFAULT 1,
 4    type TEXT NOT NULL,
 5    name TEXT NOT NULL,
 6    ts TEXT NOT NULL,
 7    source_sdk TEXT,
 8    source_app TEXT,
 9    source_version TEXT,
10    source_platform TEXT,
11    source_os TEXT,
12    session_id TEXT,
13    session_started TEXT,
14    level TEXT,
15    data TEXT,
16    error_message TEXT,
17    error_stack TEXT,
18    error_type TEXT,
19    receive_ts TEXT
20);

source_sdk 獨立成 column 讓「按 SDK 來源篩選」（WHERE source_sdk = 'python'）不需要從 JSON extract。data 用 TEXT 存 JSON。SQLite 沒有原生 JSON 型別，但 3.38+ 支援 json_extract() 函式做查詢（WHERE json_extract(data, '$.duration_ms') > 1000）。session_id 獨立成 column 讓 session 回放的 JOIN 不需要 JSON extract。error_stack 獨立成 column 讓 error 調查時全文搜尋 stack trace 不需要 JSON extract。receive_ts 是 collector 收到事件的時間，和 SDK 端的 ts 對照可估算 clock drift。

PostgreSQL 版本的差異：data 改成 JSONB 型別（原生索引和查詢）、source_* 可保持為 nested JSON（PostgreSQL 的 JSONB 查詢效能足夠）或維持攤平（和 SQLite 版本保持一致）。

建議索引

建表時一起建索引，覆蓋 dashboard 的核心查詢模式：

1CREATE INDEX idx_type_ts ON events(type, ts);    -- 按 type + 時間過濾（error 列表、趨勢圖）
2CREATE INDEX idx_session ON events(session_id);   -- 按 session 回放
3CREATE INDEX idx_name ON events(name);            -- 按 name 分群計數（功能使用排行）

Day-one 建表時就建，不是效能出問題後才加。

適用規模

單日事件量在十萬筆以下、SQLite 資料庫在 1GB 以下。索引查詢在毫秒級完成。自用工具和小型團隊的日常使用通常在這個範圍。

分層保留與降採樣

保留策略從查詢需求反推，每一種查詢需要的資料粒度和回溯深度不同。回溯越深的查詢需要的粒度越粗 — debug 需要最近幾天的逐筆事件，cohort 留存需要一整年的資料但每週一筆聚合數字就夠。

SQLite 中的實作是三張摘要表加定期 job：

 1-- 摘要表
 2CREATE TABLE hourly_summary (
 3    hour TEXT, type TEXT, name TEXT,
 4    count INTEGER, error_count INTEGER,
 5    UNIQUE(hour, type, name)
 6);
 7CREATE TABLE daily_summary (
 8    date TEXT, type TEXT, name TEXT,
 9    count INTEGER, unique_sessions INTEGER,
10    UNIQUE(date, type, name)
11);
12
13-- 降採樣（Downsample，每小時跑一次，幂等 — 重跑只更新不重複）
14INSERT OR REPLACE INTO hourly_summary (hour, type, name, count, error_count)
15SELECT strftime('%Y-%m-%dT%H:00:00', ts), type, name,
16       COUNT(*), SUM(CASE WHEN type='error' THEN 1 ELSE 0 END)
17FROM events
18WHERE ts >= datetime('now', '-1 hour')
19GROUP BY 1, 2, 3;
20
21-- 清理（Purge，每天跑一次，分批刪除避免長時間鎖定）
22DELETE FROM events WHERE rowid IN (
23  SELECT rowid FROM events WHERE ts < datetime('now', '-7 days') LIMIT 10000
24);
25-- 重複執行直到影響行數為 0
26DELETE FROM hourly_summary WHERE hour < datetime('now', '-90 days');
27DELETE FROM daily_summary WHERE date < datetime('now', '-365 days');

保留期限由 collector config 設定，數字的來源是「哪些查詢需要回溯多遠」：

1retention:
2  raw_events: 7d
3  hourly_summary: 90d
4  daily_summary: 365d
5  monthly_summary: forever

Storage interface 的 Downsample() 和 Purge() 由 collector 的定時排程觸發（Go 的 time.Ticker）。每個 storage backend 各自實作 — SQLite 用上述 SQL、PostgreSQL 用相同邏輯但可以加 partial index 加速、時間序列 DB 的 continuous aggregate 和 retention policy 原生支援。

為什麼是聚合而非抽樣

原始事件的保留期到期後，需要決定如何保留歷史統計。降採樣有兩種思路。抽樣保留是同事件名稱（name 欄位）同小時保留一筆原始事件、刪除其餘，保留了逐筆查詢能力但喪失準確計數。聚合摘要是把一小時內的事件壓成一筆計數記錄，喪失逐筆細節但保留準確統計。

Collector 選擇聚合摘要——捨棄逐筆細節，換取準確計數。降採樣後的資料用途是趨勢圖和長期統計，這些查詢需要「過去 30 天每小時的 error 總數」而非「某一筆原始 error 的 stack trace」。

這意味著原始事件 purge（定期清理過期事件）後，超過保留期的逐筆查詢會回傳空結果。Dashboard 在回溯超過原始事件保留期的時間範圍時，應切換到上方的摘要表（hourly_summary/daily_summary）查詢——顯示趨勢圖而非事件列表。設計方向是查詢 API 的 from 參數超過 retention.raw_events 時自動降級到摘要表，或回傳提示告知 client 該時間範圍只有聚合資料（初版 collector 尚未實作此降級邏輯）。

觸發切換到 PostgreSQL 的訊號

寫入爭搶：SQLite 是單寫者模型。高併發寫入（多個 SDK 同時 flush、每秒數百筆以上持續發生）會出現 database is locked 錯誤。WAL mode 能緩解但不能根治。

聚合查詢效能不足：Dashboard 需要的聚合查詢（「過去 30 天每小時的 error 數量趨勢」「funnel 的每步轉換率」）在資料量成長後變慢。SQLite 沒有 parallel query 和 partial index 等進階 OLAP 能力。

跨實例需求：需要多個 collector 實例共用同一個資料庫時，SQLite 的單檔案模型無法跨主機存取。

PostgreSQL Backend（分析觸發）

PostgreSQL 是獨立的資料庫 server，提供多連線並行寫入、進階索引（GIN for JSONB、partial index）和完整的 SQL 分析能力。切換到 PostgreSQL 意味著 collector 從「零依賴單一 binary」變成「binary + 外部 DB」，運維複雜度上升。

觸發條件

SQLite 的寫入爭搶或聚合效能成為瓶頸時切換。具體訊號：database is locked 錯誤頻率超過每分鐘一次、或 dashboard 的聚合查詢超過 3 秒。

切換方式

切換是 config change：把 --storage=sqlite 改成 --storage=postgres --dsn=postgres://...。資料遷移用匯出 + 匯入完成：

1. 從 SQLite 匯出事件為 JSONL（monitor export --format=jsonl）
2. 在 PostgreSQL 建立 events 表（schema 和 SQLite 相同，data 欄位改用 JSONB）
3. 匯入 JSONL 到 PostgreSQL（monitor import --storage=postgres --file=events.jsonl）
4. 切換啟動參數、確認查詢正常後停用 SQLite 檔案

Storage interface 保證 collector 的 ingestion、query、rule engine 邏輯不需要改動 — 只有 storage implementation 層切換。

能力增量

• 並行寫入：多個 SDK 同時 flush 不會 lock
• JSONB 索引：對 data 欄位的特定 key 建索引（CREATE INDEX ON events ((data->>'name'))）
• Window function：funnel 和 cohort 分析的 SQL 基礎
• Read replica：寫入和查詢分離，dashboard 的查詢不影響 ingestion 效能

時間序列 DB Backend（長期演進）

時間序列資料庫（TimescaleDB、InfluxDB、VictoriaMetrics）專門為高頻 append 寫入和時間分桶聚合設計。TimescaleDB 基於 PostgreSQL 擴展，Storage interface 的 PostgreSQL implementation 可以直接複用、加上 hypertable 和 continuous aggregate。

觸發條件

每秒數萬筆以上的持續寫入、或需要自動 downsampling（每分鐘的原始資料保留 7 天、每小時的聚合保留 90 天、每天的聚合永久保留）。多數自用工具和小型團隊不會到達這個規模。

能力增量

• 時間分桶原生操作：time_bucket('1 hour', ts) 替代手動 DATE_TRUNC
• Continuous aggregate：預計算的聚合結果自動更新
• 壓縮：歷史資料自動壓縮，TB 級資料可查詢
• Retention policy：按時間自動清理舊資料

JSONL 匯出（debug 用途）

JSONL 不作為主要 storage backend，而是作為匯出格式保留人類可讀性和 grep 友好性。monitor export --format=jsonl 把 storage 中的事件匯出為每行一個 JSON 物件的檔案，讓開發者可以用 grep / jq 做臨時查詢或把資料搬到其他工具。

JSONL 匯出也是備份和遷移的中介格式 — SQLite 損壞時從 JSONL 重建、切換到 PostgreSQL 時從 JSONL 匯入。

匯出使用 streaming — 從 storage 逐筆讀取、逐行寫出檔案，記憶體使用和事件總量無關。300 萬筆事件（約 900MB JSONL）的匯出不需要載入全部資料到記憶體。匯出的 JSONL 檔案包含事件明文（已 redaction 的欄位除外），匯出後不受 collector 的存取控制保護，應注意存放位置和存取權限。

演進原則

按觀察到的瓶頸切換。database is locked 錯誤頻率、聚合查詢延遲、磁碟使用量 — 這些是可觀察的訊號。「未來可能有百萬筆事件」是預測。按訊號行動，不按預測行動。

切換是 config change。Storage interface 確保切換 backend 時 collector 的其他邏輯（ingestion、query API、rule engine、dashboard）不需要改動。切換的成本是資料遷移，不是程式碼重寫。

SQLite 是安全的起點。多數開源使用者會停留在 SQLite backend — 單日萬筆以下、索引查詢毫秒級、零依賴部署。只有明確的效能瓶頸才值得引入外部 DB 的運維成本。

下一步路由

• Collector 的整體架構 → Collector 架構
• 查詢 API 的設計（跨 backend 統一） → 查詢 API 設計
• 資料庫選型的通用指南 → backend 01 資料庫
• 效能瓶頸的判讀方法 → backend 09 效能容量
• 水平擴展的基礎概念 → DevOps 水平擴展
• Error fingerprint 的 DDL 擴充 → Error Fingerprint 與去重分群

SQLite 層：開發者工具

SQLite 層提供的功能聚焦在「開發者自己 debug 和監控」。所有查詢都是單一維度的 — 按時間、按類型、按名稱過濾，不需要跨事件 JOIN 或跨使用者聚合。

承載的功能

這些功能覆蓋開發者日常 debug 和監控的核心操作 — 查錯誤、看時間軸、回放 session、設規則告警。

對應的 Dashboard 視圖

對應的事件消費

SQLite 層消費所有四類事件，但消費方式是「單筆或單 session 級查詢」：

PostgreSQL 層：行為分析

PostgreSQL 層在 SQLite 層的基礎上加入「跨 session、跨使用者的聚合分析」。這些查詢需要 JOIN 多張表、計算時間窗口、處理大量資料的 GROUP BY — SQLite 的單寫者模型和有限的查詢最佳化器在這些場景下效能不足。

觸發引入 PostgreSQL 的功能需求

判斷公式

1需要 funnel / cohort / RFM 任一 → PostgreSQL
2需要跨使用者聚合（不只看自己的資料） → PostgreSQL
3需要高併發寫入（多個 SDK 同時 flush 且持續出現 database is locked 錯誤） → PostgreSQL
4以上都不需要 → SQLite 足夠

對應的 Dashboard 視圖（SQLite 層不提供）

對應的事件消費

PostgreSQL 層消費的事件和 SQLite 相同（Ingestion 不變），但消費方式從「單筆/單 session」擴展到「跨 session/跨使用者」：

Domain 的分層影響

Ingestion 和 Rule 兩個 domain 和 storage backend 無關 — 事件進來的方式和規則評估的邏輯不因 backend 改變。Query 和 Dashboard 是分層影響最大的兩個 domain — PostgreSQL 層的查詢能力決定了 Dashboard 能提供什麼視圖。

實作邊界

Storage interface 用 Go 的 interface composition 分成兩層：

 1type BasicStorage interface {
 2    Store(event Event) error
 3    Query(filter QueryFilter) ([]Event, error)
 4    Close() error
 5    Downsample() error
 6    Purge() error
 7}
 8
 9type AnalyticsStorage interface {
10    BasicStorage
11    Aggregate(spec AggregateSpec) (AggregateResult, error)
12    Funnel(steps []string, timeWindow Duration) (FunnelResult, error)
13    Cohort(groupBy string, metric string) (CohortResult, error)
14}

SQLite implementation 只實作 BasicStorage。PostgreSQL implementation 實作 AnalyticsStorage。Dashboard 用 Go 的 type assertion（if as, ok := storage.(AnalyticsStorage); ok { ... }）判斷能力 — funnel/cohort 視圖在 SQLite 模式下不顯示入口，而非顯示後報錯。

下一步路由

• 可插拔 Storage Backend 的架構 → 規模演進
• 事件枚舉方法（哪些事件要收） → 事件枚舉與補齊檢查
• 分層保留策略 → 規模演進的分層保留段
• Funnel 分析的完整方法論 → Funnel analysis
• 查詢消費模式（各場景需要什麼事件）→ 查詢消費模式

教學路線：單檔正式狀態與 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

定義 funnel 步驟

Funnel 分析的第一步是列出每一步和對應的事件名稱。以一個透過 WebSocket 連接遠端終端機的 app 連線流程為例：

SQLite 層：每步事件計數

SQLite backend 能做的 funnel 是「每步有多少事件觸發」— 單表 GROUP BY，不需要跨事件 JOIN。

1SELECT name, COUNT(*) as count
2FROM events
3WHERE name IN ('terminal.connect.start', 'auth.biometric.success',
4               'terminal.connect.done', 'terminal.input.submit')
5  AND ts >= datetime('now', '-7 days')
6GROUP BY name;

步驟 N 的轉換率 = 步驟 N 的事件數 / 步驟 N-1 的事件數。流失率 = 1 - 轉換率。

能做的

• 每步事件計數（單表 GROUP BY）
• 按 source.version 或 source.platform 分群（加 WHERE 條件）
• 按天/按週看趨勢（strftime 分桶 + GROUP BY）

做不到的

• Session 級轉換率：「同一個 session 完成步驟 1 到步驟 4 的比例」需要 JOIN 同 session 的多個事件、跨所有 session 聚合。SQLite 能做這個 JOIN，但在大量 session 時效能不足。
• 步驟間耗時：「使用者在步驟 1 和步驟 2 之間等了多久」需要 self-join on session_id + timestamp 差值計算。
• 漏斗順序驗證：確認使用者是按 1→2→3→4 順序完成、不是跳步。

PostgreSQL 層：Session 級 funnel

PostgreSQL backend 提供 window function 和高效 JOIN，能做完整的 session 級 funnel 分析。

 1WITH session_steps AS (
 2  SELECT session_id, name,
 3         ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY ts) as step_order
 4  FROM events
 5  WHERE name IN ('terminal.connect.start', 'auth.biometric.success',
 6                 'terminal.connect.done', 'terminal.input.submit')
 7    AND ts >= NOW() - INTERVAL '7 days'
 8),
 9session_max_step AS (
10  SELECT session_id, MAX(step_order) as reached
11  FROM session_steps
12  GROUP BY session_id
13)
14SELECT reached, COUNT(*) as sessions
15FROM session_max_step
16GROUP BY reached
17ORDER BY reached;

新增能力

• Session 級轉換率：每個 session 到達了哪一步、在哪一步流失
• 步驟間耗時：LAG window function 計算相鄰步驟的 timestamp 差值
• 漏斗順序驗證：用 ROW_NUMBER + CASE 確認步驟順序
• Cohort 分群的 funnel：按使用者註冊日期 / 版本 / 平台分群看不同 cohort 的 funnel 差異

JSONL 匯出後的臨時分析

Collector 的 monitor export --format=jsonl 可以匯出事件為 JSONL 格式。匯出後用 grep + jq 做一次性的臨時分析：

1for step in terminal.connect.start auth.biometric.success terminal.connect.done terminal.input.submit; do
2  count=$(grep "\"name\":\"$step\"" exported-events.jsonl | wc -l)
3  echo "$step: $count"
4done

JSONL 臨時分析適合「快速看一眼大概數字」的場景。持續性的 funnel 監控應該用 SQLite 或 PostgreSQL 的 SQL 查詢，結果穩定且可重現。

自架 vs 商業方案

自用工具場景下，SQLite 層的每步事件計數通常足夠。商業產品需要 session 級分析時，PostgreSQL 層的 SQL 能力和商業方案的分析能力在功能上對等，差異在 UI 和設定便利性。

下一步路由

• Funnel 分析的完整方法論 → Funnel analysis
• 事件設計如何影響分析品質 → 行為事件設計
• 功能分層定義 → 功能分層與 Backend 選擇
• 去識別化是分析的入場條件 → 模組七 資安與隱私

寫入吞吐

寫入吞吐決定 collector 每秒能消化多少事件。SQLite 的寫入效能主要受 fsync 頻率和 WAL checkpoint 影響。

單筆 INSERT

每筆 INSERT 獨立一個 transaction 時，每次 commit 都會 fsync。WAL mode 的 fsync 成本比 journal mode 低（append-only），但仍是寫入的主要瓶頸。

modernc.org/sqlite（pure Go）的效能約為 CGO driver（mattn/go-sqlite3）的 60-80%。上表數字基於 CGO driver，pure Go 需打八折。Go HTTP handler 的開銷（JSON 解碼、schema 驗證、goroutine 調度）再扣 10-20%。

批次 INSERT

一個 transaction 包裹多筆 INSERT，只做一次 fsync。Collector 接收 SDK 的 flush batch（一個 HTTP request 帶一批事件）天然適合批次寫入。

吞吐提升幅度和批次大小的關係：

提升來自 fsync 次數從「每筆一次」降到「每批一次」。超過 100 筆/tx 後邊際收益遞減。

實際預期

結合 pure Go driver、HTTP handler 開銷和批次寫入，不同環境下的預期吞吐：

和事件產生速率的對照

burst 和持續的差異在於：burst 是短暫的高峰（flush batch 到達後數秒內消化完），持續是長時間的穩定高流量。SQLite 的 WAL mode 對 burst 容忍度高（write lock 等待時間短），對持續高流量容忍度有限（write lock 等待累積）。

查詢延遲

查詢延遲決定 dashboard 的刷新體驗。SQLite 的查詢效能取決於索引覆蓋和掃描行數。

有索引的查詢

建議的索引（見 規模演進 的建議索引段）覆蓋 dashboard 的核心查詢模式。有索引時的預期延遲：

無索引的查詢

無索引時 SQLite 做全表掃描。掃描速度約 50-100 MB/sec（SSD）、10-30 MB/sec（HDD）。

超過 100 萬筆無索引查詢會超出 dashboard 可接受的刷新延遲 — 這是 day-one 就建索引的理由。

Dashboard 刷新頻率 vs 查詢延遲

Dashboard 的每個視圖有不同的刷新間隔和可接受延遲。查詢延遲超過可接受值時，dashboard 體驗變差（等待轉圈、資料過時）。

「需要預聚合」代表原始事件的聚合查詢超過可接受延遲，應該依賴分層保留策略中的 hourly_summary / daily_summary 表（見 規模演進 的分層保留段）。

資源消耗

記憶體

Raspberry Pi（1 GB RAM）上建議把 page cache 調小（PRAGMA cache_size = -512 = 512 KB），避免大結果集查詢（加 LIMIT），dashboard 刷新頻率降低。

CPU

磁碟

WAL 檔案通常 < 10 MB（auto-checkpoint 在 WAL 達到 1000 pages 時觸發）。分層保留策略下，原始事件只保留 7 天，長期佔用由聚合摘要表決定（遠小於原始事件）。

邊緣設備場景

Raspberry Pi、低配 VPS（1 核 / 1 GB RAM）、甚至 NAS 上跑 collector 時的特殊考量：

SD card 的隨機寫入：SD card 的隨機寫入 IOPS 極低（100-500 IOPS），WAL mode 的 checkpoint（把 WAL 內容合併回主資料庫檔案）可能卡住 1-5 秒。期間新的寫入等待 checkpoint 完成。建議調高 wal_autocheckpoint 的閾值（如 5000 pages），讓 checkpoint 頻率降低但每次時間更長 — 在非活躍時段（凌晨）手動觸發 PRAGMA wal_checkpoint(TRUNCATE)。

1 GB RAM：cache_size 調小（512 KB）、避免 SELECT * 不帶 LIMIT、GROUP BY 的結果集用 HAVING 條件過濾減少暫存。Dashboard 的長期聚合直接查 hourly_summary 表而非原始事件。

ARM CPU：pure Go SQLite driver（modernc.org/sqlite）在 ARM 上的效能差距可能比 x86 更大（pure Go 的 C-to-Go 翻譯在 ARM 的指令最佳化較少）。實測確認。

建議配置：邊緣設備上 collector 的 dashboard 刷新頻率從預設值降低（即時狀態卡 5 秒 → 30 秒，趨勢圖 30 秒 → 5 分鐘），降採樣 job 頻率從每小時改為每 6 小時。

實測方法指引

教學的預期數字是推導值，實際效能取決於使用者的硬體和 workload。Collector 提供內建的 benchmark 命令讓使用者在自己的環境實測。

寫入 benchmark

1# 單筆寫入：10000 筆，每筆獨立 transaction
2./collector benchmark write --events=10000 --batch=1 --storage=sqlite
3
4# 批次寫入：10000 筆，每 100 筆一個 transaction
5./collector benchmark write --events=10000 --batch=100 --storage=sqlite

輸出：total duration、events/sec、p50/p95/p99 latency per event。

查詢 benchmark

1# 先灌入測試資料
2./collector benchmark seed --events=100000 --storage=sqlite
3
4# 跑查詢 benchmark
5./collector benchmark query --type=error --group-by=name --storage=sqlite
6./collector benchmark query --session-id=random --storage=sqlite

輸出：query duration、rows scanned、rows returned。

Production 觀察指標

部署後用 DevOps dashboard（見 DevOps Dashboard 設計）觀察 collector 自身的效能 metric：

• collector.storage.write_duration_ms：每次寫入的延遲。P95 超過 100ms 是瓶頸訊號。
• collector.storage.query_duration_ms：每次查詢的延遲。P95 超過 dashboard 刷新間隔是瓶頸訊號。
• collector.storage.db_size_bytes：資料庫大小。接近磁碟可用空間的 80% 時觸發 purge 或擴容。
• collector.storage.wal_size_bytes：WAL 檔案大小。持續 > 50 MB 代表 checkpoint 跟不上寫入速度。

下一步路由

• 切換到 PostgreSQL 的觸發條件 → 規模演進
• SQLite 和 PostgreSQL 的功能分層 → 功能分層與 Backend 選擇
• Ingestion 端的擴展設計 → Ingestion Scaling

Dockerfile 設計

Multi-stage build 把編譯環境和執行環境分離。Build stage 用 Go 官方 image 編譯 binary，runtime stage 只包含 binary 和必要的 CA 憑證。

 1FROM golang:1.22-alpine AS build
 2WORKDIR /src
 3COPY go.mod go.sum ./
 4RUN go mod download
 5COPY . .
 6RUN CGO_ENABLED=0 go build -o /collector ./cmd/collector
 7
 8FROM alpine:3.20
 9RUN apk add --no-cache ca-certificates tzdata
10COPY --from=build /collector /usr/local/bin/collector
11RUN adduser -D -u 1000 monitor
12USER monitor
13EXPOSE 8080
14ENTRYPOINT ["collector"]

最終 image 包含 Go binary（~15MB）+ alpine base（~7MB）+ ca-certificates，總大小目標 < 25MB。用 scratch 替代 alpine 可以再小 7MB，但失去 shell debug 能力。

SQLite 在 Container 中的 I/O 考量

Docker 的 overlay2 storage driver 在每次 fsync 時經過 overlay 層。SQLite 的 WAL mode 依賴 fsync 確保寫入持久性 — 每筆 transaction commit 觸發一次 fsync。Overlay 層增加的延遲讓每筆 fsync 慢 20-40%（取決於 host 的 storage driver 和檔案系統）。

Volume mount 繞過 overlay

把 SQLite 的資料目錄掛載為 host volume（-v /host/data:/data），SQLite 直接寫 host 檔案系統、繞過 overlay 層。寫入效能和同機部署的 binary 版本相當。

不用 volume mount 的風險：container 刪除時 overlay 層的資料一起消失。docker rm = 所有事件資料消失。即使只是 docker run 新版本的 image 也會建立新 container，舊 container 的資料不會自動遷移。

Volume Mount 設計

兩個目錄分開掛載，職責和權限不同：

Container 內用非 root user（UID 1000）執行。Host 的 volume 目錄 ownership 需要對應：

1mkdir -p monitor-data monitor-config
2chown 1000:1000 monitor-data

Graceful Shutdown

docker stop 送 SIGTERM → collector 收到後執行 shutdown 序列：

1. 停止接受新的 HTTP request（listener close）
2. 等待 in-flight request 完成（5 秒 context timeout）
3. Flush pending writes（尚未寫入 storage 的事件，5 秒）
4. 停止定期 job（downsample / purge / rule engine 定期評估）
5. SQLite WAL checkpoint（TRUNCATE mode，15 秒）
6. 關閉 DB connection
7. 退出

步驟 2-5 合計超時上限 25 秒。這個序列對應 Backend 5.6 Platform Lifecycle Contract 的 shutdown → drain 狀態：步驟 1-2 是 drain（停接新工作、等在途完成），步驟 3-6 是 shutdown（flush 狀態和釋放資源）。Collector 屬於短 request API 的 workload 類型（drain 窗口 5-30 秒），但多了 WAL checkpoint 步驟，讓 shutdown 時間可能超過一般 HTTP 服務。PID 1 信號處理的設計考量（exec form、避免 shell 攔截 SIGTERM）見 Backend 5.1 PID 1 與信號處理。

docker stop 預設等 10 秒後送 SIGKILL。如果 WAL checkpoint 在大量未 checkpoint 的資料下需要超過 10 秒，Docker Compose 可以調 stop_grace_period: 30s。

SQLite 的 WAL 設計支援 crash recovery — SIGKILL 後 WAL 檔案仍在，下次開啟 DB 時自動 replay。但非 graceful shutdown 可能丟失 channel 中尚未寫入的事件（已收到 HTTP 202 但還在 buffer 中的事件）。

資源限制

Memory 限制設太緊會觸發 OOMKill — container 突然消失且無 log。設定 memory limit 前先觀察 collector 的 baseline 記憶體使用（docker stats），再乘以 1.5 安全係數。CPU request/limit 的設定策略（guaranteed vs burstable QoS）和 memory limit 與 OOM 的判讀見 Backend 5.1 Resource Limit。

Docker Compose 範例

 1services:
 2  collector:
 3    image: tarrragon/monitor:latest
 4    ports:
 5      - "8080:8080"
 6    volumes:
 7      - ./monitor-data:/data
 8      - ./monitor-config:/config:ro
 9    environment:
10      - MONITOR_STORAGE=sqlite
11      - MONITOR_DB_PATH=/data/events.db
12    restart: unless-stopped
13    stop_grace_period: 30s
14    deploy:
15      resources:
16        limits:
17          memory: 256M
18          cpus: '0.5'
19    healthcheck:
20      test: ["CMD", "wget", "-q", "--spider", "http://localhost:8080/health"]
21      interval: 30s
22      timeout: 5s
23      retries: 3

restart: unless-stopped 讓 container 在 crash 或 host 重啟後自動恢復。healthcheck 讓 Docker 偵測 collector 是否真的在回應 — 只有 process 活著但 HTTP 不回應的場景也會被標記為 unhealthy。

和同機部署的效能對照

Volume mount 後效能差異只有 ~10%（Go HTTP handler 的 overhead 大於 volume mount 的 overhead）。不用 volume mount 時 overlay fs 的 fsync 開銷顯著 — 寫入吞吐降 40%。

何時用 container、何時用 binary

斷網環境的部署考量

Collector 在斷網環境（air-gapped）裡的部署跟連網環境的主要差異有三點。第一，SDK 的 endpoint 從外部 URL（https://collect.example.com）改為內網地址（http://collector.internal:8080），SDK 設定檔裡的 endpoint 要能按環境切換。第二，Collector 的 container image 無法從 Docker Hub 拉取——需要透過 content ferry 搬運映像、推送到內網的 private registry（Harbor 或 Docker Registry），Dockerfile 的 base image 來源也要改指 private registry。第三，Collector 的 storage backend 只能用本地磁碟或 NFS，不能用雲端物件儲存——SQLite backend 在斷網環境反而是優勢（零外部依賴），儲存容量規劃要在部署前就確定，因為斷網環境的磁碟擴容流程可能需要數週。

SDK 的 offline buffer（見SDK 設計：offline-buffer）在斷網環境更重要——如果 Collector 重啟或暫時不可達，SDK 端的 buffer 是唯一能保住事件的機制。

斷網環境的 infra 層監控（Prometheus / Grafana / Loki）設定見斷網環境的監控與可觀測性。

下一步路由

• SQLite 效能基準的詳細數字 → SQLite Backend 效能基準
• 可插拔 Storage Backend 架構 → 規模演進
• Container runtime 通用原則（base image 選擇、build 可重現性、PID 1 信號處理）→ Backend 5.1 Container 與 Runtime
• 生命週期合約（startup / readiness / drain / shutdown 的責任分類）→ Backend 5.6 Platform Lifecycle Contract
• 容器化資源設計的通用原則 → DevOps 容器化資源設計
• 服務探活和自動恢復 → DevOps 服務探活

本文的判讀錨點是：降級到 SQLite 是責任縮小，也是讓資料模型回到 single-process / file-owned / local-state 的工程選擇。只要正式需求從 multi-user server DB 回到這個範圍，SQLite 可以提供更低元件數、更容易搬移與更低維護成本。

Simplification Drivers

Simplification drivers 的核心責任是確認 PostgreSQL 的能力已超過服務需求。若 server DB 的 HA、role、replica、pool、vacuum、PITR、schema governance 都變成維運負擔，而產品只需要單一 process 持有資料，就可以評估 SQLite。

Driver 要連到 ownership。SQLite 適合「這份資料由某個 process / device / artifact 明確持有」；若資料仍屬於多服務共同真相，保留 PostgreSQL 或改成 managed SQL 會更穩定。

No-Go Conditions

No-go condition 的核心責任是保護仍需要 server DB 的服務。若 PostgreSQL 的核心能力仍被業務依賴，遷到 SQLite 會把風險轉移到 application code、file backup 與人工流程。

No-go 條件要寫進 migration proposal。Simplification 的目標是降低操作成本；若降級後要用大量自製機制補回 role、audit、HA 與 concurrent write，成本會回到系統裡。

Diff Audit

Diff audit 的核心責任是把 PostgreSQL 語意縮到 SQLite 可以清楚承擔的範圍。PostgreSQL extension、function、type、index、constraint、sequence、view、trigger、role 與 transaction behavior 都要盤點。

Diff audit 的輸出是一份保留 / 移除 / 改寫清單。每個 PostgreSQL feature 都要回答：這是正式需求、歷史殘留，還是可以移到 application layer 的便利功能。

Phase Plan

Phase plan 的核心責任是把 server DB 退場變成可回復流程。反向 migration 要超過一次性 dump：先收斂寫入、建立 SQLite schema、匯入資料、跑 adapter test、演練 backup，再退役 PostgreSQL。

Scope reduction 是第一關。若資料仍被多個服務寫入，應先拆出 bounded context 或建立 event / export boundary；SQLite file 才能成為明確 owned artifact。

Data Movement

Data movement 的核心責任是把 PostgreSQL snapshot 轉成 SQLite file 並保留驗證。可用 COPY / CSV、application ETL 或 dedicated migration tool；選擇取決於 type conversion 與資料量。

1psql "$DATABASE_URL" -c "\\copy orders TO 'orders.csv' CSV HEADER"
2sqlite3 app.db ".mode csv" ".import --skip 1 orders.csv orders"
3sqlite3 app.db "PRAGMA integrity_check;"

這段命令是教學骨架。正式流程要處理 NULL、delimiter、timezone、numeric precision、FK order、transaction、temporary disk、sensitive data 與 import log。

Import 後要跑三種 evidence：database integrity、row count / checksum、business invariant。Business invariant 例如 active user count、total balance、latest event id、pending job count；這些比單純 row count 更能抓到語意錯誤。

Runbook Shift

Runbook shift 的核心責任是把 PostgreSQL operation 移轉成 SQLite file operation。Server DB 的 backup / role / monitoring 退場後，要補上 SQLite 的 backup、restore、file permission、WAL、migration 與 disk 觀測。

最小 SQLite runbook 包含：

1. Database file path、owner process、filesystem permission。
2. Journal mode、busy timeout、foreign key、schema version。
3. Backup command、restore drill、retention、checksum。
4. Migration command、pre-migration snapshot、rollback path。
5. Observability：busy、WAL size、disk free、backup age。
6. Incident route：disk full、bad migration、corruption signal。

Runbook shift 要同步移除 PostgreSQL credential。Server database 退役時，保留 read-only archive、刪除 application secret、關閉 scheduled job、更新 dashboard 與 incident routing。

Cleanup and Retention

Cleanup and retention 的核心責任是讓舊 PostgreSQL 不再成為影子真相。Migration 後若舊 DB 長期可寫，團隊會在事故中分不清哪份資料有效。

Retention 要和 data protection 對齊。若 PostgreSQL 內有 PII、audit log 或 legal retention，退役流程要依 retention policy 保存或銷毀，而非直接刪除。

Decision Route

Decision route 的核心責任是讓 simplification 保持可逆。若未來 concurrent writer、central audit、PITR 或 multi-service source-of-truth 回來，系統要能沿 SQLite to PostgreSQL migration 重新升級。

Simplification 的完成標準是：SQLite file 可以被重建、備份、恢復、升級與交接。只要這些 evidence 完整，從 PostgreSQL 退到 SQLite 是清楚的工程決策。

下一步路由

PostgreSQL to SQLite simplification 完成後，先讀 file lifecycle / backup boundary 建立 file operation；再讀 SQLite observability / runbook 補 evidence；若之後需求再成長，回到 SQLite to PostgreSQL migration。

本文的驗收標準是：你能從 live app.db 建立 backup，將它還原到隔離路徑，通過 integrity_check 與核心查詢，並記錄 restore duration。

Prepare Source

Prepare source 的核心責任是建立一個有 WAL 與資料變化的 live database。若你已跑過 local file quickstart，可以直接沿用 /tmp/sqlite-lab/app.db。

1mkdir -p /tmp/sqlite-lab/backup /tmp/sqlite-lab/restore
2cd /tmp/sqlite-lab
3sqlite3 app.db "PRAGMA journal_mode = WAL;"
4sqlite3 app.db "INSERT INTO ledger_entries(account_id, amount_cents, idempotency_key, created_at) VALUES (2, 100, 'backup-drill-1', '2026-05-21T01:00:00Z');"

這一步讓 source database 有新的資料。後續會用 backup snapshot 和 source 後續寫入做對照。

Create Backup

Create backup 的核心責任是用 SQLite-aware 方法建立一致 snapshot。SQLite CLI .backup 會透過 SQLite backup API 產出目標檔案。

1sqlite3 app.db ".backup 'backup/app-backup.db'"
2sqlite3 backup/app-backup.db "PRAGMA integrity_check;"

預期 integrity_check 輸出 ok。這是最小 backup evidence。

VACUUM INTO 也可以產出 compact copy，適合想順便整理檔案大小的情境。

1sqlite3 app.db "VACUUM INTO 'backup/app-vacuum-copy.db';"
2sqlite3 backup/app-vacuum-copy.db "PRAGMA integrity_check;"

.backup 與 VACUUM INTO 都要在 runbook 中標明使用條件、耗時、目標路徑與失敗處理。正式環境還要記錄檔案大小、checksum 與 storage retention。

Mutate Source After Backup

Mutate source 的核心責任是確認 backup 是時間點 snapshot。備份後對 source 寫入新資料，再用 restore 驗證 backup 保持原時間點。

1sqlite3 app.db "INSERT INTO ledger_entries(account_id, amount_cents, idempotency_key, created_at) VALUES (1, 777, 'after-backup-write', '2026-05-21T01:05:00Z');"
2sqlite3 app.db "SELECT COUNT(*) FROM ledger_entries;"
3sqlite3 backup/app-backup.db "SELECT COUNT(*) FROM ledger_entries;"

Source count 應比 backup count 多一筆。這個差異讓 RPO 討論具體化：backup 只保護到它建立的時間點。

Restore Isolated Copy

Restore isolated copy 的核心責任是避免把演練和 source 混在一起。把 backup 複製到 restore path，所有 validation 都對 restore file 執行。

 1cp backup/app-backup.db restore/app-restored.db
 2sqlite3 restore/app-restored.db "PRAGMA integrity_check;"
 3sqlite3 restore/app-restored.db <<'SQL'
 4.headers on
 5.mode column
 6SELECT account_id, SUM(amount_cents) AS balance_cents
 7FROM ledger_entries
 8GROUP BY account_id
 9ORDER BY account_id;
10SQL

正式 restore drill 還要啟動 application 指向 restore/app-restored.db，跑核心 read/write smoke test。若 application 需要 migration，也要確認 restore file 的 PRAGMA user_version 與 app version 相容。

RPO / RTO Note

RPO / RTO note 的核心責任是把演練結果轉成服務承諾。RPO 是可接受資料遺失窗口，RTO 是可接受恢復時間。

可以用 shell 的 time 記錄 restore duration。

1time sqlite3 restore/app-restored.db "PRAGMA integrity_check;"

正式服務要把 RPO / RTO 寫進 observability / runbook。

Known Gap

Known gap 的核心責任是讓 lab 結果誠實。這個 drill 驗證 SQLite-aware backup 與 restore path；它尚未覆蓋 object storage credential、remote retention、large database restore time、encrypted disk、user device support flow 與 legal retention。

完成本篇後，下一步可以進入 WAL busy reproduction 觀察 writer boundary，或進入 migration fixture lab 建立 schema change evidence。

本文的判讀錨點是：SQLite compatibility 代表開發入口接近，服務責任仍要重新審查。採用 edge SQLite 前，要先確認 write authority、read freshness、migration limit、backup evidence、observability、cost 與 vendor exit，而非只看 SQL 語法能否執行。

Product Boundary

Product boundary 的核心責任是定義誰持有資料、誰執行 SQL、誰負責恢復。Local SQLite 的資料在你的 filesystem；D1 的資料由 Cloudflare D1 平台管理並和 Workers binding 整合；Turso / libSQL 的資料通常有 remote database 與 client / embedded replica 的分工。

Local SQLite 的判斷重點是 file ownership。若 app 與 database file 位於同一個 host，備份、restore、disk full、permission 與 app upgrade 都在你的 runbook 裡；這條路線承接 file lifecycle / backup boundary。

D1 的判斷重點是 platform integration。Cloudflare 官方 D1 docs 把 D1 放在 Workers 與 Wrangler workflow 內，並公開 D1 limits；因此採用 D1 時要把 database decision 與 Workers deployment、local preview、batch migration、import/export limit 一起審查。

Turso / libSQL 的判斷重點是 replica freshness 與 client semantics。Turso docs 對 embedded replicas 的描述顯示：application 可以持有 local replica 並透過同步取得資料；這會把「讀得快」和「讀到多新」變成同一個設計問題。

Edge Data Model

Edge data model 的核心責任是把 latency 改善與一致性責任拆開。Edge database 的價值常來自 closer read path、serverless deployment 與較低操作表面；風險則集中在 write authority、replication lag、region routing 與平台限制。

Write authority 是 edge SQLite 的第一個分水嶺。若所有 write 都集中到 remote primary，application 要處理 network error、retry、idempotency 與 read freshness；若 write 發生在 local replica，系統要有 conflict resolution、sync ordering 與 delete propagation。

Read locality 是 edge SQLite 的主要收益。它適合 session-local preference、read-mostly catalog、低風險 personalization、feature flag snapshot、tenant-local small dataset；這些情境的共同點是資料量小、write rate 低、freshness 可以定義。

Global transaction 是 edge SQLite 的高風險區。若產品需求包含跨 region balance transfer、inventory reservation、ledger posting、strongly consistent permission decision，設計應路由到 Global Distributed OLTP 或 PostgreSQL / CockroachDB / Spanner 的 transactional model。

Migration Gap

Migration gap 的核心責任是確認 SQLite file 可以搬到 edge product 後，release workflow 仍可驗證。SQL syntax compatibility 只解決起點；真正會造成事故的是 batch limit、extension 差異、driver API、local preview 與 production platform 行為差異。

D1 migration 要把 Wrangler workflow 納入 release gate。Cloudflare D1 的 limits 文件明確列出 import、query、batch 等限制；因此大型 update / delete 要拆 batch，migration 要有 staging dry run 與 production rollback step。

Turso / libSQL migration 要把 driver semantics 納入 release gate。Local SQLite driver 直連 file；libSQL client 可能連 remote endpoint 或 embedded replica；application 要把 connection lifecycle、sync timing、auth token、network failure 與 local cache freshness 寫進測試。

Operational Model

Operational model 的核心責任是把 managed convenience 轉成 ownership map。Edge SQLite 減少了部分 server operation，但新增 platform limit、billing、region behavior、vendor incident、CLI workflow 與 local preview mismatch。

Production runbook 至少要保存五種證據：

1. Schema migration history 與每次 release 的 dry-run result。
2. Data import / export 指令、檔案大小、row count 與 checksum。
3. Region latency、read freshness、write error rate 與 retry count。
4. Platform limit 命中紀錄、batch policy 與成本警戒線。
5. Vendor exit route：回 local SQLite、PostgreSQL 或另一個 edge database 的最小搬遷步驟。

成本模型要同時看 request、storage、egress、operation time 與工程鎖定。Edge product 常把起步成本壓低，但當資料變大、batch migration 變長、observability 需要外掛、vendor API 滲入 repository layer 時，長期成本會出現在 release 與 incident。

Decision Route

Decision route 的核心責任是把需求送到相符的資料模型。D1 / Turso / libSQL 適合 edge locality 與低操作表面；當需求轉向 high-write OLTP、central audit、role-based permission、global transaction 或跨服務資料治理，應轉向 server SQL 或 distributed OLTP。

D1 的採用條件是 edge runtime 本身就是主平台。若 application 已在 Workers 上、資料量可控、query pattern 清楚、migration 可 batch，D1 可以把 database operation 融入 deployment workflow。

Turso / libSQL 的採用條件是 local read value 高於同步複雜度。若產品可明確定義 stale read window、write path 與 conflict policy，embedded replica 可以降低 latency；若使用者需要立即看見跨裝置變更，就要先設計 freshness evidence。

Production Tripwires

Production tripwires 的核心責任是指出何時重新評估 edge SQLite。這些訊號出現時，系統通常已從「SQLite-compatible convenience」進入正式 database governance。

這些 tripwire 要寫進設計文件與 runbook。Edge SQLite 的優勢在於低摩擦起步；它的長期品質來自早期把 ownership、limits、exit 與 evidence 設計清楚。

下一步路由

D1 / Turso / libSQL comparison 完成後，下一步要依壓力路由。要處理 local file 與 backup，讀 file lifecycle / backup boundary；要處理 replica / restore，讀 Litestream / LiteFS replication；要從 local SQLite 移到 edge product，讀 SQLite to D1 / Turso migration；要處理 global write，回到 Global Distributed OLTP。

本文的驗收標準是：你能從 local SQLite 匯出 schema / seed，匯入 D1 或 Turso preview database，跑相同 query set，記錄 unsupported SQL、latency、error mapping 與 rollback route。

Preview Scope

Preview scope 的核心責任是把 lab 限制在 staging / preview。D1 與 Turso 都是平台產品，實際命令會依 CLI version、帳號、region 與專案設定改變；本文提供操作骨架與 evidence 格式，正式命令以官方文件為準。

官方文件路由：

Preview lab 要先確認資料不含 production PII。若 seed data 來自正式資料，先做 masking 或 synthetic data。

Export Local SQLite

Export local SQLite 的核心責任是建立 target platform 的 seed input。沿用 /tmp/sqlite-lab/app.db 或 migration fixture。

1mkdir -p /tmp/sqlite-edge-lab
2cd /tmp/sqlite-edge-lab
3cp /tmp/sqlite-lab/app.db ./app.db
4sqlite3 app.db ".schema" > schema.sql
5sqlite3 app.db ".dump" > seed.sql
6sqlite3 app.db "SELECT COUNT(*) FROM accounts;"
7sqlite3 app.db "SELECT COUNT(*) FROM ledger_entries;"

schema.sql 用來審查 DDL，seed.sql 用來匯入 preview database。正式 migration 可能要拆 schema / data / index，並處理 target platform limits。

Build Query Matrix

Build query matrix 的核心責任是定義 preview 要驗證什麼。query set 要代表產品行為，而非只跑一個 SELECT 1。

1Q1 list account balances
2Q2 insert ledger entry with unique idempotency key
3Q3 insert duplicate idempotency key and capture error
4Q4 foreign key violation
5Q5 transaction rollback
6Q6 pagination by created_at
7Q7 explain / performance sample if platform supports it

這份 matrix 要保存 expected result。Local SQLite 先跑一次，把 row count、error category、latency baseline 記下來。

1sqlite3 app.db <<'SQL'
2.timer on
3SELECT a.id, a.owner_name, SUM(l.amount_cents) AS balance_cents
4FROM accounts a
5JOIN ledger_entries l ON l.account_id = a.id
6GROUP BY a.id, a.owner_name
7ORDER BY a.id;
8SQL

Import to D1 Preview

Import to D1 preview 的核心責任是驗證 Cloudflare D1 workflow。以下是操作骨架，正式命令與 flags 以 Cloudflare D1 docs 和 Wrangler 版本為準。

1# Example shape only. Use your project naming and official Wrangler docs.
2wrangler d1 create sqlite_edge_preview
3wrangler d1 execute sqlite_edge_preview --file=seed.sql
4wrangler d1 execute sqlite_edge_preview --command="SELECT COUNT(*) FROM accounts;"

D1 preview evidence 要記錄：

若 seed file 太大或某些 SQL 需要改寫，就把 gap 寫進 compatibility matrix，先保留 production migration 的審查邊界。

Import to Turso Preview

Import to Turso preview 的核心責任是驗證 remote database、client SDK 與 embedded replica 行為。以下是操作骨架，正式命令以 Turso docs 與 CLI version 為準。

1# Example shape only. Use your org, group, region and official Turso docs.
2turso db create sqlite-edge-preview
3turso db shell sqlite-edge-preview < seed.sql
4turso db shell sqlite-edge-preview "SELECT COUNT(*) FROM accounts;"

Turso preview evidence 要多記 replica freshness。若使用 embedded replica，測試流程要包含 bootstrap、sync、read query、write delegation 與 sync 後 read。

1embedded replica evidence:
2  bootstrap duration
3  first read latency
4  write path
5  sync command / interval
6  read freshness after write

Freshness 是 product decision。若 query matrix 只測 remote primary，仍需要追加 embedded replica 的使用者體驗驗證。

Compatibility Matrix

Compatibility matrix 的核心責任是把 local SQLite 與 edge target 的差異留下來。建議表格欄位如下：

Decision 欄要寫具體下一步。rewrite workflow 代表 application adapter 要改；split batch 代表 migration runbook 要改；map error 代表 repository error classification 要改。

Latency and Cost Sample

Latency and cost sample 的核心責任是避免只看功能相容。Edge SQLite migration 的收益常來自 region latency 或 managed operation，因此 preview 要量測主要使用者區域的 read / write latency。

最小量測：

1. Local baseline latency。
2. Preview target read latency。
3. Preview target write latency。
4. Error rate / retry count。
5. Estimated request / storage / egress cost。

Latency sample 要搭配 freshness。快速讀到舊資料和稍慢讀到最新資料是不同產品體驗；query matrix 要標註哪個 workflow 可以接受 stale read。

Rollback Route

Rollback route 的核心責任是保留 local SQLite 退路。Preview lab 完成後，要能刪除 preview database、保留 local seed、重跑 local app。

1sqlite3 app.db "PRAGMA integrity_check;"
2sqlite3 app.db "SELECT COUNT(*) FROM accounts;"
3sqlite3 app.db "SELECT COUNT(*) FROM ledger_entries;"

正式 cutover 的 rollback 還要處理 target-only writes。Preview 階段應避免讓真實使用者寫入 target；若需要 shadow traffic，先用 read-only 或 synthetic write。

Completion Note

Completion note 的核心責任是決定是否進入正式 migration。Lab 完成後應輸出四個 artifact：seed.sql、import log、compatibility matrix、rollback note。

進入正式 migration 的條件：

1. Query matrix 主要 workflow 通過或已有 rewrite plan。
2. Platform limits 對資料量與 migration time 可接受。
3. Error mapping 已接到 repository adapter。
4. Freshness / latency 符合產品需求。
5. Export / rollback route 已演練。

完成本篇後，回到 SQLite to D1 / Turso Migration 補正式 phase plan。

本文是 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

章節列表

設計原則

SQLite hands-on 章節要以檔案生命週期為中心。操作指令只在能產出 evidence 時出現；每篇都要回答 database file 在哪裡、sidecar file 如何處理、restore 如何驗證，以及 application release 如何知道它仍相容。

引用路徑

• 上游：SQLite overview
• Structure：SQLite Teaching Structure
• Deep article：File lifecycle / backup boundary

本文的判讀錨點是：replicated SQLite 要先說明 replica 的服務責任。它可能是 continuous backup、warm restore source、read replica、primary failover helper 或 deployment topology；每一種責任都有不同的 RPO、RTO、freshness 與 incident runbook。

Replication Taxonomy

Replication taxonomy 的核心責任是把「有複本」拆成可操作的幾種能力。SQLite 周邊工具常用 replication 這個字，但 operator 需要知道它到底保護哪個風險。

Continuous backup 的語言是 RPO 與 RTO。它關心最近一次成功送出的 WAL、snapshot freshness、object storage credential、restore 指令與演練結果。

Read replica 的語言是 freshness。Replica 能降低 read latency 或保護 primary workload，但讀者要知道 stale window、read-after-write policy、fallback to primary 與 cache invalidation。

Primary lease 的語言是 writer ownership。SQLite 的服務形狀仍適合 single writer；工具可以協助 deployment 切換，但 application 要配合 fencing、retry 與 promotion evidence。

Litestream Boundary

Litestream boundary 的核心責任是把 SQLite WAL 變成可持續複製的 backup stream。Litestream 官方說明把它定位為 SQLite streaming replication tool，並在 How it works 與 restore command 文件中強調 replica 與 restore workflow。

Litestream 適合下列情境：

1. 單節點 SQLite app 要降低資料遺失窗口。
2. 系統可接受 restore 後重新啟動 service。
3. Object storage credential、retention、restore drill 可以被管理。
4. Write pattern 適中，WAL stream 與 snapshot 維護成本可控。

Litestream 的設計重點是 backup evidence。Runbook 要記錄 replica destination、last replicated generation、last restore test、expected RPO、expected RTO、restore target path、credential rotation 與 corruption triage。

1litestream restore -o /var/lib/app/restored.db s3://example-bucket/app.db
2sqlite3 /var/lib/app/restored.db "PRAGMA integrity_check;"

這段命令是 restore drill 的最小骨架。正式 runbook 要補上 service stop、database path、sidecar file、permission、checksum、application smoke test 與 rollback decision。

Litestream 的風險集中在 restore path。備份存在和服務可恢復是兩件事；每次 release 或 schema migration 後，都應用 staging data 跑一次 restore、integrity check、row count 與 application smoke test。

LiteFS Boundary

LiteFS boundary 的核心責任是支援 replicated deployment topology，而非只做 backup。LiteFS 在 Fly.io 文件中被定位為 SQLite replication layer，透過 FUSE filesystem 與 primary lease 模型協助應用在多個 instance 間運作。

LiteFS 適合下列情境：

1. App 仍希望使用 SQLite file 與 local SQL path。
2. Deployment 有多個 instance，但 write authority 可以集中到 primary。
3. Read replica freshness 可以被產品接受。
4. Team 願意把 filesystem layer、primary lease、promotion 與 platform operation 納入 runbook。

LiteFS 的設計重點是 primary ownership。Application 要知道 write request 到哪裡執行、primary 切換時如何重試、read replica 讀到舊資料時如何回應，以及 promotion 完成前哪些 endpoint 要進入 degraded mode。

LiteFS 的 incident route 要從 writer ownership 開始查。若出現 write error、stale read 或 suspected split brain，先查看 primary lease、instance health、replication lag、pending writes 與 platform network，再處理 application retry。

Failure Modes

Failure modes 的核心責任是把 replicated SQLite 的事故從「資料庫壞了」拆成可排查訊號。SQLite file、WAL、object storage、filesystem layer、deployment platform 與 application retry 都可能是問題來源。

Replica lag 要接到 alert。對 Litestream，它意味著 RPO 正在擴大；對 LiteFS，它可能同時影響 read freshness 與 failover confidence。

Restore lag 要接到 release gate。若 restore time 已超過目標 RTO，就要調整 snapshot frequency、資料保留策略或搬到 server database。

Stale read 要接到產品語言。使用者看到舊資料時，系統可以顯示 sync state、重讀 primary、限制 critical action 或提供 refresh；這些策略要在設計階段決定。

No-Go Conditions

No-go condition 的核心責任是避免把 replicated SQLite 推到 distributed OLTP 的位置。SQLite 周邊 replication 工具可以強化單節點與 read replica，但高寫入、多 writer、強一致跨 region transaction 需要不同資料庫模型。

No-go 條件要在 design review 階段列出。SQLite replication 的好處是低成本與低元件數；當核心需求變成跨節點一致性寫入，繼續調工具會把風險藏在 incident 時刻。

Decision Route

Decision route 的核心責任是把資料保護、讀擴展與高可用分開選型。Litestream / LiteFS 位置清楚時，SQLite 可以保持簡潔；位置混淆時，系統會同時缺 backup evidence 與 transaction guarantee。

選擇 Litestream 時，完成標準是能在 staging 從 replica restore 出可用 DB。選擇 LiteFS 時，完成標準是能演練 primary 切換、read freshness、write retry 與 degraded mode。

下一步路由

Litestream / LiteFS replication 完成後，下一步要回到 SQLite operation evidence。File copy、backup API 與 WAL sidecar 請讀 file lifecycle / backup boundary；busy、lock 與 writer 壓力請讀 WAL concurrency / locking；完整 runbook 請讀 SQLite observability / runbook。

本文的驗收標準是：你能建立一個可重建的 app.db，知道它的 schema version、journal mode、foreign key 設定、seed data 與 cleanup 路徑。

Lab Directory

Lab directory 的核心責任是把 SQLite artifact 放在隔離資料夾，避免和正式檔案混淆。以下命令建立一個可刪除的本地工作區。

1mkdir -p /tmp/sqlite-lab
2cd /tmp/sqlite-lab
3rm -f app.db app.db-wal app.db-shm

驗收 artifact 是 /tmp/sqlite-lab/app.db。後續 lab 可以沿用這個路徑，也可以每次從頭建立。

Baseline Schema

Baseline schema 的核心責任是建立一組能測 transaction、constraint、index 與 query 的小型資料模型。這裡使用 accounts 與 ledger_entries，因為它們能清楚展示 foreign key 與金額 invariant。

 1sqlite3 app.db <<'SQL'
 2PRAGMA journal_mode = WAL;
 3PRAGMA foreign_keys = ON;
 4PRAGMA user_version = 1;
 5
 6CREATE TABLE accounts (
 7  id INTEGER PRIMARY KEY,
 8  owner_name TEXT NOT NULL,
 9  status TEXT NOT NULL CHECK (status IN ('active', 'closed')),
10  created_at TEXT NOT NULL
11) STRICT;
12
13CREATE TABLE ledger_entries (
14  id INTEGER PRIMARY KEY,
15  account_id INTEGER NOT NULL REFERENCES accounts(id),
16  amount_cents INTEGER NOT NULL CHECK (amount_cents != 0),
17  idempotency_key TEXT NOT NULL UNIQUE,
18  created_at TEXT NOT NULL
19) STRICT;
20
21CREATE INDEX idx_ledger_entries_account_created
22ON ledger_entries(account_id, created_at);
23SQL

這段 schema 的重點是明確資料合約。STRICT、CHECK、FOREIGN KEY 與 UNIQUE 讓 fixture 更接近正式資料責任，也讓後續 migration lab 有可驗證的 invariant。

Seed Data

Seed data 的核心責任是建立可重跑的測試資料。每筆 ledger entry 都有 idempotency key，讓後續 edge / retry 設計可以沿用。

 1sqlite3 app.db <<'SQL'
 2PRAGMA foreign_keys = ON;
 3
 4BEGIN;
 5INSERT INTO accounts(id, owner_name, status, created_at)
 6VALUES
 7  (1, 'Ada', 'active', '2026-05-21T00:00:00Z'),
 8  (2, 'Lin', 'active', '2026-05-21T00:05:00Z');
 9
10INSERT INTO ledger_entries(account_id, amount_cents, idempotency_key, created_at)
11VALUES
12  (1, 1200, 'seed-ada-credit-1', '2026-05-21T00:10:00Z'),
13  (1, -200, 'seed-ada-debit-1', '2026-05-21T00:12:00Z'),
14  (2, 900, 'seed-lin-credit-1', '2026-05-21T00:15:00Z');
15COMMIT;
16SQL

Seed 完成後先跑基本查詢。這一步確認 schema、constraint 與 index 入口都可用。

1sqlite3 app.db <<'SQL'
2.headers on
3.mode column
4SELECT a.id, a.owner_name, SUM(l.amount_cents) AS balance_cents
5FROM accounts a
6JOIN ledger_entries l ON l.account_id = a.id
7GROUP BY a.id, a.owner_name
8ORDER BY a.id;
9SQL

預期輸出應顯示 Ada 餘額 1000，Lin 餘額 900。

PRAGMA Snapshot

PRAGMA snapshot 的核心責任是把連線設定變成 evidence。SQLite 的部分設定與 connection 有關，因此 lab 要明確查出當前狀態。

1sqlite3 app.db <<'SQL'
2.headers on
3.mode column
4PRAGMA journal_mode;
5PRAGMA foreign_keys;
6PRAGMA user_version;
7PRAGMA integrity_check;
8SQL

驗收重點如下：

Transaction Sample

Transaction sample 的核心責任是建立後續 busy / migration lab 的共同語言。SQLite transaction 成功時要同時更新資料與保護 invariant。

1sqlite3 app.db <<'SQL'
2PRAGMA foreign_keys = ON;
3BEGIN IMMEDIATE;
4INSERT INTO ledger_entries(account_id, amount_cents, idempotency_key, created_at)
5VALUES (1, 300, 'manual-ada-credit-1', '2026-05-21T00:20:00Z');
6COMMIT;
7SQL

BEGIN IMMEDIATE 會提早取得 write lock。這讓後續 WAL busy reproduction 可以直接展示 single writer boundary。

File Artifact Check

File artifact check 的核心責任是讓讀者看到 SQLite 由 .db 與可能存在的 sidecar 共同構成。WAL mode 可能建立 -wal 與 -shm sidecar，backup / copy / restore runbook 要理解這些檔案。

1ls -lh app.db app.db-wal app.db-shm

若 sidecar 暫時未出現，可以再寫入一筆資料或保持連線開啟。Sidecar 是否存在取決於 WAL 狀態、checkpoint 與 connection lifecycle。

Cleanup

Cleanup 的核心責任是讓 lab 可以重跑。若要重新開始，刪除 database 與 sidecar。

1rm -f /tmp/sqlite-lab/app.db /tmp/sqlite-lab/app.db-wal /tmp/sqlite-lab/app.db-shm

完成本篇後，下一步可以進入 backup restore drill 或 WAL busy reproduction。

本文是 SQLite overview 的 implementation-layer deep article。Overview 已說明 SQLite 適合 local-first / offline-first 場景；本文聚焦 SQLite local store 與 multi-device sync protocol 的責任分界。

SQLite local-first sync boundary 的核心責任是把「本機可用」和「多端一致」分成兩個問題。SQLite 很適合保存 device-local state；但它不提供 identity、transport、conflict resolution、delete propagation、server authority 或 audit trail。當資料要跨裝置、跨使用者或跨服務同步時，SQLite 只是 local replica / working copy。

本文的判讀錨點是：local-first 的產品價值來自離線可用，工程成本來自同步語意。SQLite 解的是 local durability；sync layer 解的是資料合併、順序、權威來源與錯誤修復。

Local state taxonomy

Local-first 設計的第一步是標記本機資料角色。不同資料角色對 sync、backup、conflict 與 delete 的要求不同。

這張表的重點是資料角色先於 sync 工具。若所有資料都只是 cache，SQLite + TTL 足夠；若有 pending mutation 或 multi-device edit，就需要 sync protocol。

Authority boundary

Authority boundary 的核心責任是決定衝突時誰說了算。Local-first app 可以讓 device、server、field-level merge 或 CRDT 成為不同層的 authority；SQLite 本身只保存狀態，不替系統決策。

Authority model 要和 product semantics 對齊。庫存、付款、權限這類資料通常需要 server authority；notes、draft、local settings 可以接受更偏 local 的權威模型。

Sync transport 與 local log

Sync transport 的核心責任是把 SQLite local state 轉成可重送、可去重、可驗證的資料流。最常見做法是本地維護 pending mutation table 或 change log，再由 background sync worker 送到 server。

 1CREATE TABLE pending_mutations (
 2  id TEXT PRIMARY KEY,
 3  entity_type TEXT NOT NULL,
 4  entity_id TEXT NOT NULL,
 5  operation TEXT NOT NULL,
 6  payload TEXT NOT NULL,
 7  created_at TEXT NOT NULL,
 8  retry_count INTEGER NOT NULL DEFAULT 0,
 9  last_error TEXT
10);

這裡和 backend queue 概念相通：pending mutation table 是本機版 durable queue。它需要 idempotency、retry 與 replay 思維，而不只是「存一張表」。

Conflict resolution

Conflict resolution 的核心責任是讓兩個合法 local write 合併成可接受狀態。SQLite 可以保存 local write；sync layer 要決定衝突偵測、呈現與合併。

Conflict policy 要在資料模型設計時決定。等衝突發生後才補策略，通常會導致資料修復、客服流程與 audit evidence 同時缺位。

Delete propagation 與 privacy

Delete propagation 的核心責任是讓 server、device、backup 與 sync queue 對「刪除」有一致語意。Local-first app 常見風險是 server 已刪，但 device local DB、pending queue 或 OS backup 還留著資料。

刪除在同步系統裡是一個跨裝置生命週期。若資料跨裝置同步，delete 需要 tombstone、ack、retry、backup retention 與 evidence；這些責任要接到 Data Protection。

Production 踩雷

Case 1：pending mutation 沒有 idempotency key

Pending mutation 沒有 idempotency key 的核心風險是重送造成重複副作用。網路 timeout 後 worker 重送，server 已經處理第一次請求，第二次又建立一筆資料或扣一次庫存。

修正方向是每個 mutation 生成 stable id，server 以 idempotency key 去重，local SQLite 保存 retry state 與 server ack。

Case 2：LWW 覆蓋使用者資料

Last-write-wins 的核心風險是把衝突靜默變成資料遺失。Preference 類資料可接受；草稿、文件、表單、付款資料通常需要更清楚的 conflict handling。

修正方向是依資料價值分層。低價值設定用 LWW；高價值內容用 field merge、manual conflict 或 operation log。

Case 3：delete 沒傳到離線裝置

Delete propagation 失敗的核心風險是 privacy / compliance 失效。使用者刪除 server 資料後，一台長期離線裝置重新上線又把舊資料同步回來。

修正方向是 tombstone + server authority。Server 要能拒絕過期 mutation，device 要能接收 delete tombstone 並 purge local state。

操作檢查清單

Local-first SQLite 設計要回答：

1. 哪些 table 是 local source of truth，哪些是 server replica。
2. Pending mutation 是否有 idempotency key 與 retry state。
3. Conflict policy 是 LWW、field merge、manual merge 還是 operation log。
4. Delete 是否有 tombstone、ack 與 local purge。
5. Sync worker 是否有 backoff、dead-letter、reconciliation。
6. Device backup 是否會保存已刪資料。
7. Server 是否能拒絕過期 local write。

下一步路由

• 上游：Mobile / Desktop Embedded Store
• Sibling：SQLite to D1 / Turso、D1 / Turso / libSQL Comparison
• 卡片：Idempotency、Eventual Consistency、Stale Read
• 跨模組：Data Protection

本文的驗收標準是：你能建立 v1 fixture、套用 v2 migration、產生 v2 snapshot，並用 validation query 證明資料合約仍成立。

Create Fixture

Create fixture 的核心責任是建立乾淨、可重建的 source fixture。沿用 quickstart schema，或重新建立一份 fixture DB。

 1mkdir -p /tmp/sqlite-fixture-lab
 2cd /tmp/sqlite-fixture-lab
 3rm -f fixture-v1.db fixture-v2.db
 4sqlite3 fixture-v1.db <<'SQL'
 5PRAGMA foreign_keys = ON;
 6PRAGMA user_version = 1;
 7
 8CREATE TABLE accounts (
 9  id INTEGER PRIMARY KEY,
10  owner_name TEXT NOT NULL,
11  status TEXT NOT NULL CHECK (status IN ('active', 'closed')),
12  created_at TEXT NOT NULL
13) STRICT;
14
15CREATE TABLE ledger_entries (
16  id INTEGER PRIMARY KEY,
17  account_id INTEGER NOT NULL REFERENCES accounts(id),
18  amount_cents INTEGER NOT NULL CHECK (amount_cents != 0),
19  idempotency_key TEXT NOT NULL UNIQUE,
20  created_at TEXT NOT NULL
21) STRICT;
22
23INSERT INTO accounts VALUES (1, 'Ada', 'active', '2026-05-21T00:00:00Z');
24INSERT INTO ledger_entries(account_id, amount_cents, idempotency_key, created_at)
25VALUES (1, 1000, 'fixture-v1-ada', '2026-05-21T00:10:00Z');
26SQL

這個 fixture 是 v1 source of truth。CI 可以每次從 SQL 重建，也可以保存 fixture-v1.db 作為 binary fixture；兩者都要有版本與 checksum。

Pre-Migration Snapshot

Pre-migration snapshot 的核心責任是建立 rollback 起點。正式 migration 前應先保存 source DB。

1sqlite3 fixture-v1.db ".backup 'fixture-v1-before-migration.db'"
2sqlite3 fixture-v1-before-migration.db "PRAGMA integrity_check;"

這份 snapshot 代表 migration 失敗時的回退點。CI log 要保留 snapshot path、schema version 與 migration id。

Apply Add Column Migration

Apply add column migration 的核心責任是展示低風險 schema change。先複製 v1，再套用 v2。

1cp fixture-v1.db fixture-v2.db
2sqlite3 fixture-v2.db <<'SQL'
3PRAGMA foreign_keys = ON;
4BEGIN;
5ALTER TABLE accounts ADD COLUMN email TEXT;
6PRAGMA user_version = 2;
7COMMIT;
8SQL

驗證 schema version 與新欄位：

1sqlite3 fixture-v2.db <<'SQL'
2PRAGMA user_version;
3PRAGMA table_info(accounts);
4SQL

Add column 是較簡單的 migration。涉及 drop column、rename、constraint 重建或資料 reshape 時，應改用 table rebuild 策略。

Table Rebuild Example

Table rebuild 的核心責任是展示 SQLite schema migration 的高風險路徑。以下範例把 accounts.status 的 allowed value 加入 suspended，透過新表重建 constraint。

 1sqlite3 fixture-v2.db <<'SQL'
 2PRAGMA foreign_keys = OFF;
 3BEGIN;
 4
 5CREATE TABLE accounts_new (
 6  id INTEGER PRIMARY KEY,
 7  owner_name TEXT NOT NULL,
 8  status TEXT NOT NULL CHECK (status IN ('active', 'closed', 'suspended')),
 9  created_at TEXT NOT NULL,
10  email TEXT
11) STRICT;
12
13INSERT INTO accounts_new(id, owner_name, status, created_at, email)
14SELECT id, owner_name, status, created_at, email
15FROM accounts;
16
17DROP TABLE accounts;
18ALTER TABLE accounts_new RENAME TO accounts;
19
20PRAGMA user_version = 3;
21COMMIT;
22PRAGMA foreign_keys = ON;
23SQL

Table rebuild 要保存 index、trigger、view 與 FK reference。這個 lab 只有小型 schema；正式 migration 要先列出所有 dependent object。

Validation Query

Validation query 的核心責任是證明 migration 後資料仍符合 domain invariant。

1sqlite3 fixture-v2.db <<'SQL'
2PRAGMA integrity_check;
3PRAGMA foreign_key_check;
4SELECT COUNT(*) AS account_count FROM accounts;
5SELECT COUNT(*) AS ledger_count FROM ledger_entries;
6SELECT SUM(amount_cents) AS total_balance FROM ledger_entries;
7PRAGMA user_version;
8SQL

驗收結果應包含 integrity ok、foreign key check 空結果、account count 1、ledger count 1、total balance 1000、user version 3。

Contract Test Hook

Contract test hook 的核心責任是讓 fixture 進入 CI。語言與 framework 可以不同，但測試要固定做三件事：開啟 FK、確認 schema version、跑 repository contract。

1test setup:
2  copy fixture-v2.db to temp path
3  open SQLite connection
4  execute PRAGMA foreign_keys = ON
5  assert PRAGMA user_version = 3
6  run repository contract tests

每個 test 使用 temp copy 可以避免資料污染。需要測 concurrency 時，改用 WAL busy reproduction。

Rollback Note

Rollback note 的核心責任是把 migration 失敗時的處理寫清楚。這個 lab 的 rollback 是保留 fixture-v1-before-migration.db，在 migration validation 失敗時停止 release 並保存 failed DB。

正式 runbook 要記錄：

1. Migration id 與 source / target user_version。
2. Pre-migration backup path。
3. Validation query 與結果。
4. Failed DB 保存路徑。
5. Release block / rollback 條件。

完成本篇後，下一步可以讀 SQLite to PostgreSQL migration 或 SQLite to D1 / Turso migration。

本文是 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

本文的判讀錨點是：SQLite 的 observability 要貼近 file、process、filesystem 與 application。它通常沒有 server DB 那種長駐監控平面，因此 runbook 要把 signal 從 app metrics、log、scheduled job、file metadata 與 restore evidence 裡組出來。

Signal Inventory

Signal inventory 的核心責任是列出 SQLite production 化後最能預告事故的訊號。這些訊號要放進 dashboard、log search 或 scheduled report，讓事故前後都能直接查。

SQLITE_BUSY 是 writer boundary 的最直接訊號。它可能代表長交易、read cursor 未關、parallel test 共用 DB、checkpoint 壓力或 write burst；runbook 要先查 query duration 與 transaction boundary，再調 busy timeout。

WAL size 是 checkpoint 與 reader 壓力的綜合訊號。WAL 持續成長時，先確認是否有長 reader、backup process、未完成 transaction 或 checkpoint 失敗；接著才考慮手動 checkpoint。

Backup age 是 RPO 的可觀測版本。若目標 RPO 是 5 分鐘，dashboard 就要顯示 last successful backup / replica time 與警戒線。

Backup Evidence

Backup evidence 的核心責任是證明資料可被拿回來。SQLite backup 的完成標準包含成功建立備份、保存 sidecar 語意、恢復到新路徑、通過 integrity check、跑 application smoke test。

SQLite 官方 backup API 與 CLI .backup 是備份設計的基礎路由。WAL mode 下，直接複製單一 .db 檔容易漏掉 sidecar file 的時序；runbook 應使用 SQLite-aware backup 或經過 checkpoint / stop-the-world 的 snapshot。

1sqlite3 app.db ".backup 'backup/app-2026-05-21.db'"
2sqlite3 backup/app-2026-05-21.db "PRAGMA integrity_check;"

這段命令提供最小 restore evidence 的起點。正式演練要把備份檔複製到隔離路徑，使用相同 application version 啟動，跑核心 read/write smoke test，再記錄耗時與失敗條件。

Migration Evidence

Migration evidence 的核心責任是讓 SQLite schema change 可回退、可審查、可交接。單檔 DB 在使用者裝置或服務節點上升級時，migration 失敗會直接影響啟動、資料讀取與同步。

Migration log 要包含版本、耗時、row count、錯誤、validation result 與 rollback decision。若 SQLite file 位於 end-user device，log 還要能被使用者支援流程收集，避免事故只停在「app 開不起來」。

1PRAGMA user_version;
2PRAGMA foreign_key_check;
3SELECT COUNT(*) FROM orders;

這些 query 是 migration 後的最小 evidence。正式服務要再補 domain-specific invariant，例如「所有 active subscription 都有 owner」、「所有 pending mutation 都有 idempotency key」。

Incident Runbook

Incident runbook 的核心責任是把 SQLite 事故分流到正確處置。SQLite 常見事故包含 disk full、busy storm、WAL growth、bad migration、corruption suspicion、backup failure 與 permission error。

Busy storm 要先保護使用者操作。可以降低 write endpoint、停用背景 job、延長 retry backoff，然後用 log 查最長 transaction 與最多重試的 query。

Disk full 要先停止寫入。SQLite 在 disk full 時可能讓 write / checkpoint / backup 同時失敗；runbook 要保留剩餘空間、DB file、WAL file、backup directory 與 tmp directory 的大小。

Bad migration 要保留 failed artifact。先複製 failed DB 到 evidence path，記錄 schema version、app version、migration id、validation error，再執行 rollback。

Dashboard and Alert Route

Dashboard and alert route 的核心責任是讓 SQLite 被納入正式服務的可觀測系統。SQLite signal 常來自 application，因此 metric 命名要接近操作問題。

Alert 要連到 runbook，並提供可執行的第一步。每個 alert 至少要有 owner、severity、first query、rollback condition 與 escalation route。

Log schema 要保留 query category，而非只記原始 SQL。正式服務通常應避免把完整 SQL 與 PII 直接寫入 log；可以記 operation name、duration、row count、error code、busy retry count 與 correlation id。

Handoff

Handoff 的核心責任是讓下一個維護者知道 SQLite service 的邊界。交接文件要把「誰負責檔案」、「誰負責備份」、「誰能執行 restore」、「何時升級資料庫」寫清楚。

最小 handoff 包含：

1. Database file path、sidecar file policy、journal mode 與 PRAGMA baseline。
2. Backup command、destination、retention、last restore drill。
3. Migration command、schema version、rollback route。
4. Alert list、dashboard link、incident owner。
5. Known limits：writer concurrency、file size、edge / sync boundary。
6. Next route：PostgreSQL、D1 / Turso、Litestream / LiteFS 的評估條件。

Handoff 的重點是把低操作成本保留下來。SQLite 的好處來自少元件；可交接文件讓少元件不等於少 evidence。

下一步路由

Observability / runbook 完成後，下一步要接到具體演練。Backup 與 restore 讀 SQLite backup restore drill；WAL 與 busy 讀 WAL busy reproduction；正式服務的 evidence 可對齊 Observability Evidence Package 與 Incident Decision Log。

本文是 SQLite overview 的 implementation-layer deep article。Overview 已說明 SQLite 的容量規劃要點；本文聚焦 PRAGMA 設定如何變成 durability、latency、檔案大小與 restore risk 的取捨。

SQLite PRAGMA tuning 的核心責任是把單檔資料庫的行為固定成可重複、可觀測、可回退的操作契約。SQLite 的許多重要行為由 connection-level 或 database-level PRAGMA 控制；這些設定看起來像小開關，實際上會影響 crash recovery、commit latency、reader / writer 衝突、檔案大小與測試一致性。

本文的判讀錨點是：PRAGMA 是 durability / latency / maintenance 的顯性取捨，而非效能魔法。Production runbook 要記錄設定值、設定時機、驗證 query 與回退條件，避免不同 process、test runner 或 migration tool 用不同 SQLite 行為。

Baseline PRAGMA

SQLite baseline PRAGMA 的責任是讓 application 每次啟動都進入同一個資料庫模式。對 production-like local store、small backend 或 test fixture，建議把 journal、sync、foreign key、busy timeout 與 checkpoint 明確設定，而非依賴語言 binding 預設值。

1PRAGMA journal_mode = WAL;
2PRAGMA synchronous = NORMAL;
3PRAGMA foreign_keys = ON;
4PRAGMA busy_timeout = 5000;
5PRAGMA wal_autocheckpoint = 1000;

這張表的重點是把設定與 evidence 綁在一起。若某個 PRAGMA 缺少成功訊號與失敗訊號，就先維持保守預設；盲目追求「最快」通常會把風險推到 power loss、restore 或長尾 latency。

journal_mode 與 WAL boundary

journal_mode 的核心責任是決定 transaction 如何保護原始資料。SQLite 預設 rollback journal 對簡單場景合理；WAL mode 則讓 reader 可以在 writer append WAL 時保有 snapshot，適合多 reader、短寫入、互動式 workload。

WAL mode 是多數 production-like SQLite 的 baseline，但它也引入 sidecar file 與 checkpoint 責任。完整判讀見 WAL concurrency / locking。

synchronous：commit latency 與資料損失窗口

synchronous 的核心責任是控制 SQLite 在關鍵時刻要求 storage flush 的強度。官方 PRAGMA 文件說明 WAL mode 下 NORMAL 會把 sync 主要放在 checkpoint 路徑；這通常讓 commit 更快，但 crash durability 的語意要由 service owner 接受。

synchronous=OFF 要被視為明確風險接受。若資料是 source of truth，設定檔、runbook 與 review 都應避免把 staging 的快速設定帶進 production。

Cache、mmap 與 memory pressure

SQLite memory tuning 的核心責任是降低 read path I/O，同時避免把 device / container memory 壓到不可控。cache_size 控制 SQLite page cache；mmap_size 讓讀取可透過 memory-mapped I/O 加速，但仍受平台、檔案大小與 memory budget 影響。

1PRAGMA cache_size = -64000;
2PRAGMA mmap_size = 268435456;

Memory 設定要和 workload size 一起看。Desktop app、mobile app、edge worker、container service 的 memory ceiling 不同；把 server 上的設定複製到 mobile 或 edge runtime 會讓風險轉移到 OOM 或 OS reclaim。

Vacuum 與檔案大小治理

Vacuum 設定的核心責任是控制 delete 後的空間回收。SQLite delete row 後，database file 不會自然縮小；auto_vacuum 要在 database 建立早期決定，後續切換通常需要 VACUUM 重整整個 database。

檔案大小治理要接到 backup 成本。Database file 長期膨脹會放大備份時間、restore 時間與 edge deploy artifact size；若服務有大量 delete / churn，vacuum policy 要被寫進 runbook。

Production 踩雷

Case 1：PRAGMA 只在某個 connection 設定

Connection-level PRAGMA 的核心風險是不同程式路徑行為不一致。Application 啟動時設了 foreign_keys=ON，migration tool 或 test runner 沒設，就會出現 production / migration / test 三種語意。

修正方向是把 baseline PRAGMA 放進 shared DB open path，並在 startup health check 印出設定值。Migration CLI、background worker、test fixture 都要共用同一份 connection initialization。

Case 2：synchronous=OFF 從測試環境流到正式資料

快速測試設定外流的核心風險是資料損失只在 crash 後出現。平常 query 都正常，直到 power loss、container kill 或 host crash 後，資料庫出現落差。

修正方向是設定分層。Test / benchmark 可以用 faster profile；formal state profile 要用 NORMAL 或 FULL，並要求 restore drill。

Case 3：WAL growth 被誤判成資料成長

WAL growth 的核心風險是 checkpoint 問題被當成容量問題。Disk alert 看到 db-wal 變大，若只擴 disk，長 reader 或 checkpoint starvation 仍會持續。

修正方向是把 WAL size、checkpoint return 與 long reader 一起看。先找 reader lifecycle，再調 checkpoint cadence。

Case 4：Vacuum 在高峰期執行

Vacuum 的核心風險是把 maintenance I/O 放到使用者路徑。檔案縮小是好事，但 full vacuum 會消耗 I/O 與時間，對 mobile / desktop / small backend 都可能造成卡頓。

修正方向是把 vacuum 當 maintenance job。大檔案用 incremental_vacuum 或低流量窗口；備份前的 compact copy 可考慮 VACUUM INTO。

操作檢查清單

SQLite PRAGMA runbook 至少要記錄：

1. 所有 connection 初始化時執行的 baseline PRAGMA。
2. journal_mode 實際回傳值與 sidecar file 位置。
3. synchronous profile 與資料風險接受者。
4. busy_timeout 值、busy wait metric、timeout threshold。
5. wal_autocheckpoint、manual checkpoint cadence 與 WAL size alert。
6. cache_size / mmap_size 對 memory budget 的影響。
7. auto_vacuum / VACUUM / VACUUM INTO 的 maintenance window。

下一步路由

• 上游：SQLite overview
• 前置：WAL concurrency / locking
• 操作：SQLite Hands-on
• 平行：Observability / runbook
• 官方：SQLite PRAGMA、SQLite VACUUM、SQLite WAL

本文是 SQLite overview 的 implementation-layer deep article。Overview 已說明 SQLite 的 embedded / single-file 定位；本文聚焦 schema version、ALTER TABLE boundary、table rebuild migration 與 application release compatibility。

SQLite schema migration 的核心責任是讓單檔資料庫隨 application release 安全演進。SQLite 沒有獨立 database server，也沒有 DBA 在 server 端統一套 migration；migration 常在 application startup、CLI command、mobile app upgrade 或 desktop app launch 時發生，因此 schema version、binary compatibility、backup 與 rollback 要放在同一個 release contract 中設計。

本文的判讀錨點是：SQLite migration 同時改資料庫檔案與 application 能讀的資料格式。只要使用者或服務可能拿舊 binary 打開新 database，或新 binary 打開舊 database，migration 就要處理 forward / backward compatibility，而不只是 SQL 成功執行。

Version model

SQLite schema versioning 的服務責任是讓 application 能判斷 database file 目前處於哪個契約。SQLite 提供 PRAGMA user_version 作為 application-controlled integer；更複雜的服務也可以用 migration table 記錄多步驟版本、checksum 與執行時間。

1PRAGMA user_version;
2PRAGMA user_version = 2026052101;

Version model 要在第一版就定義。沒有版本欄位的 SQLite file 仍可 migration，但 application 只能靠 introspection 猜 schema，會讓 upgrade / downgrade runbook 複雜化。

ALTER TABLE boundary

SQLite ALTER TABLE 的核心責任是處理有限集合的 schema 變更。官方文件說明 SQLite 支援 rename table、rename column、add column、drop column；更複雜的變更要走 table rebuild pattern。

SQLite schema 存在 sqlite_schema 的 SQL text 中；這讓檔案格式簡潔，但也讓 ALTER TABLE 的安全條件和 server SQL 不同。Production migration 應優先用官方建議的 rebuild procedure，而非直接修改 sqlite_schema。

Table rebuild migration

Table rebuild migration 的服務責任是安全完成 SQLite 直接 ALTER 難以表達的變更。官方 ALTER TABLE 文件建議的 generalized procedure 是建立新 table、copy data、drop old、rename new、重建 index / trigger / view、跑 foreign key check、commit。

 1BEGIN;
 2PRAGMA foreign_keys = OFF;
 3
 4CREATE TABLE new_orders (
 5  id INTEGER PRIMARY KEY,
 6  status TEXT NOT NULL,
 7  paid_at TEXT
 8);
 9
10INSERT INTO new_orders (id, status, paid_at)
11SELECT id, status, paid_at
12FROM orders;
13
14DROP TABLE orders;
15ALTER TABLE new_orders RENAME TO orders;
16
17PRAGMA foreign_key_check;
18PRAGMA user_version = 2026052101;
19COMMIT;
20PRAGMA foreign_keys = ON;

這段範例是教學骨架，而非可直接複製到所有 schema 的萬用腳本。真實 migration 要先保存 index、trigger、view 與 FK reference，再依 schema 重建；有資料量時還要考慮 copy duration、disk 空間與 rollback snapshot。

App release compatibility

SQLite migration 的 application compatibility 來自 binary 與 DB file 的同步問題。Server SQL migration 通常有 central deploy order；SQLite file 可能跟著使用者裝置、desktop profile、CLI artifact 或 edge deploy 留在不同版本。

Compatibility 的核心是先決定支援範圍。Mobile app 常要支援舊版資料庫升級；internal CLI 可能只支援最新版本；test fixture 則需要每次 migration 後重新產生。

Migration evidence

Migration evidence 的責任是證明 schema 變更已完成且資料仍可用。SQLite migration evidence 比 server DB 簡單，但更依賴 application-level validation。

這些 evidence 應接到 Observability Evidence Package 或 release note。SQLite migration 失敗時，最清楚的 rollback 通常是回到 migration 前 snapshot，而非在同一檔案上繼續試錯。

Production 踩雷

Case 1：startup migration 讓 app 啟動卡住

Startup migration 的核心風險是把長時間 table rebuild 放在使用者啟動路徑。小表新增 column 可能很快；大表 rebuild、index 重建或 vacuum 類操作會讓 app 啟動、CLI command 或 API cold start 變慢。

修正方向是先估資料量。短 migration 可在 startup；長 migration 要有 explicit command、progress、backup 與 rollback route。

Case 2：fixture schema 升級漏掉 production gap

Fixture schema drift 的核心風險是測試 DB 和 production DB 的 dialect / constraint 不一致。SQLite fixture 很快，但 production 若是 PostgreSQL / MySQL，type、date、NULL、constraint 與 transaction 行為都可能不同。

修正方向是把 SQLite fixture 明確標成 contract test 層。Repository error mapping、domain invariant 可以用 SQLite；production-specific SQL 要用 production database container 驗證。

Case 3：直接改 sqlite_schema

直接改 sqlite_schema 的核心風險是產生語法正確但語意破壞的 database file。SQLite 官方文件提供 writable schema route，但同時強調錯誤修改可能讓 database corrupt / unreadable。

修正方向是讓 writable schema 成為最後手段。一般 migration 優先用 ALTER TABLE 或 table rebuild；需要特殊修復時先複製原檔，在副本驗證。

操作檢查清單

SQLite migration runbook 至少要記錄：

1. DB file 目前 user_version 與 application release version。
2. Migration 是否可重入、是否可中斷後恢復。
3. Migration 前 backup / snapshot 位置。
4. 需要 table rebuild 的 table、資料量、index / trigger / view 清單。
5. Validation query、row count、foreign key check、integrity check。
6. 舊 binary / 新 binary 的相容策略。
7. Fixture DB 是否已重新產生並被 contract test 使用。

下一步路由

• 上游：SQLite overview
• 操作：Migration fixture lab
• 平行：Test Fixture Best Practice
• 遷移：SQLite to PostgreSQL
• 官方：SQLite ALTER TABLE、SQLite PRAGMA

本文的判讀錨點是：SQLite 測過代表某個 repository contract 在 SQLite 語意下成立。當 production target 是 PostgreSQL、MySQL、D1、Turso 或其他 server database 時，測試與 migration 要補上 dialect gap evidence。

Type Affinity

Type affinity 的核心責任是定義資料寫入時如何被保存與比較。SQLite 官方 Datatypes 文件說明 SQLite 使用 dynamic typing，型別關聯在 value 層與 column affinity 層共同作用；STRICT tables 則提供較嚴格的型別檢查。

Type affinity 的教學重點是把資料合約放在 application boundary。若 domain 說 created_at 是 timestamp，就要定義 storage format、timezone、precision、comparison query 與 serialization，而非只讓 SQLite 接受任意 value。

1CREATE TABLE orders (
2  id INTEGER PRIMARY KEY,
3  created_at TEXT NOT NULL,
4  total_cents INTEGER NOT NULL CHECK (total_cents >= 0)
5) STRICT;

這段 schema 用 STRICT、NOT NULL 與 CHECK 讓 fixture 更接近正式資料合約。Production target 仍要跑 PostgreSQL / MySQL container test，確認 timestamp、integer range 與 constraint error mapping。

Constraint Behavior

Constraint behavior 的核心責任是確保資料完整性由 database 和 application 共同維護。SQLite 支援 primary key、unique、check、foreign key 與 deferred constraint，但 foreign key enforcement 需要明確啟用，migration / test runner 也要確認連線設定。

Foreign key 是 SQLite fixture 最常漏掉的設定。每個測試連線開啟後應立刻查 PRAGMA foreign_keys;，並用一個故意違反 FK 的 fixture case 確認錯誤會出現。

1PRAGMA foreign_keys = ON;
2SELECT foreign_keys FROM pragma_foreign_keys;

Constraint error 要在 repository adapter 層被歸類。若 production target 會把 duplicate key、foreign key、check violation 映射成不同 error code，SQLite fixture 也要至少保留 domain-level classification test。

Transaction Behavior

Transaction behavior 的核心責任是定義讀寫隔離、savepoint、nested workflow 與 retry。SQLite 官方 isolation 文件說明 connection 之間的隔離語意；WAL mode 下 reader / writer behavior 也會影響 concurrent test。

Savepoint 可以讓 application 實作可組合的 transaction helper。若上層 workflow 已在 transaction 內，內層 repository 可以使用 savepoint 承接局部 rollback，而非開另一個 database transaction。

1SAVEPOINT create_order;
2INSERT INTO orders(id, created_at, total_cents) VALUES (1, '2026-05-21T00:00:00Z', 1200);
3RELEASE create_order;

Busy timeout 是測試穩定性的關鍵設定。若 fixture 會平行跑測試，應每個 temp DB 獨立，或在專門 concurrency lab 裡測 SQLITE_BUSY；一般 contract test 要追求 deterministic result。

Index Model

Index model 的核心責任是把查詢形狀與資料量變成可觀測的計畫。SQLite 支援 B-tree index、covering index、partial index、expression index 與 query planner；但 planner choice、統計資訊與 function support 會和 target DB 不同。

Index review 要從 query pattern 開始，而非從「常用欄位」開始。SQLite 可以用 EXPLAIN QUERY PLAN 檢查是否掃 index；production target 要用自己的 explain 工具重跑。

1EXPLAIN QUERY PLAN
2SELECT id, total_cents
3FROM orders
4WHERE created_at >= '2026-05-01T00:00:00Z'
5ORDER BY created_at DESC
6LIMIT 50;

Index drift 是 migration 的常見風險。SQLite fixture 裡的 index 可以讓測試變快，但若 production schema 缺少同等 index，正式服務會在資料量成長後出現 latency spike；因此 index 要進入 schema diff audit。

Dialect Gap

Dialect gap 的核心責任是把 SQLite 與 target database 的差異寫成 matrix。這份 matrix 應跟 repository adapter、migration plan 與 CI test suite 綁定。

Dialect matrix 要以 query contract 為單位。每個 repository method 至少列出 SQL feature、SQLite behavior、production behavior、test layer 與 fallback strategy。

1Contract: Search active documents by tenant and prefix
2SQLite: FTS5 virtual table in fixture
3PostgreSQL: tsvector + GIN index
4Risk: ranking / tokenizer / collation differ
5Evidence: golden result set + production container explain

這種寫法讓測試負責驗證 domain contract，避免把兩個 SQL engine 的搜尋語意視為完全一致。

Test / Migration Impact

Test / migration impact 的核心責任是決定哪些東西可以用 SQLite 快速驗證，哪些東西要交給 production-like database。SQLite 很適合 repository contract、migration fixture、local development 與 file lifecycle drill；涉及 planner、extension、collation、locking、permission、role 與 HA 時，需要追加 target DB evidence。

SQLite fixture 的價值在於快、穩、便宜。它應承擔「資料合約是否被 repository 保護」；production container 或 staging database 承擔「正式 engine 是否用同樣方式執行」。

下一步路由

SQL dialect and index limits 完成後，下一步要把 gap 接到實作層。測試設計讀 Test Fixture Best Practice；migration 實作讀 Schema migration / versioning；要升級到 PostgreSQL，讀 SQLite to PostgreSQL migration。

完成標準

SQLite 章節群的完成標準是讀者能回答三個問題。第一，SQLite 何時是正式狀態而非臨時檔案；第二，SQLite production 化後要如何處理 WAL、backup、restore、migration、測試與觀測；第三，SQLite 成長後該升到 PostgreSQL / MySQL、Cloudflare D1、Turso / libSQL、Litestream / LiteFS 或 mobile sync。

這份結構的重點是避免把 SQLite 寫成小型 PostgreSQL。SQLite deep article 要先處理檔案、process、filesystem、device、test 與 edge runtime；SQL dialect、index 與 migration 工具只有在這些責任成立後才展開。

推薦撰寫順序

撰寫順序要從正式狀態的最低操作責任開始，再逐步擴到應用形狀、edge 變體與 migration。

這個順序讓 SQLite 先完成自己的核心語言，再處理相鄰產品。D1、Turso、LiteFS、Litestream 都帶有 SQLite 相容性，但教學上要先問它們承擔的是 backup、replication、edge locality、read replica 還是 distributed write。

文件命名規則

SQLite 章節群的檔名用服務責任命名，product-first 命名只留給 D1 / Turso / libSQL 這類 product boundary 本身就是教學主題的文件。

Cross-module 路由

SQLite 章節群要固定連到四個 backend 模組。Backup / restore 連到 04 evidence 與 08 incident；test fixture 連到語言教材與 repository adapter；edge / local-first 連到 05 deployment / 07 data protection；performance tuning 連到 09 capacity。

後續審查點

SQLite 章節群完稿後要特別審查三個偏誤。第一是把 SQLite 過度美化成 production SQL 替代品；第二是把 edge SQLite 產品跟本地 SQLite 混成同一種能力；第三是把 test fixture 的便利性誤寫成 production equivalence。

本文是 SQLite overview 的 implementation-layer deep article。Overview 已說明 SQLite 適合作為 test fixture；本文聚焦 如何用 SQLite 加速測試，同時保留 production database 的語意邊界。

SQLite test fixture 的核心責任是讓 repository / adapter 測試快速、可重複、可攜帶。SQLite 的單檔特性讓 CI 可以快速建立 DB、載入 seed、跑 contract test；但它的 type affinity、SQL dialect、locking 與 constraint behavior 和 PostgreSQL / MySQL 不完全相同，因此 fixture 要被定位為一層測試工具，而非 production equivalence。

本文的判讀錨點是：SQLite fixture 適合驗證 application contract，不適合取代 production database compatibility test。若測試目標是 repository error mapping、domain invariant、migration fixture 或 deterministic seed，SQLite 很划算；若測試目標是 PostgreSQL extension、MySQL lock、query planner 或 SQL dialect，應使用 production-like container。

Test fixture 的位置

SQLite fixture 的服務責任是提供快、穩定、可重建的本地資料狀態。它通常位於 unit test 與 full integration test 之間，承擔 repository adapter 的 contract test。

這張表的重點是把測試目的說清楚。SQLite fixture 讓語言教材與 backend 教材接起來；語言端測 interface / adapter，backend 端保留 production database 的深度文章與 migration playbook。

Fixture lifecycle

Fixture lifecycle 的核心責任是讓每次測試拿到已知資料狀態。常見策略有三種：每 test 建新 in-memory DB、每 suite 複製 template file、每 CI job 產生 versioned fixture。

Fixture file 應和 schema version 綁定。檔名、metadata 或 user_version 要能回答「這個 fixture 對應哪個 migration 版本」，避免測試資料在多次 schema 變更後變成隱性技術債。

Production dialect gap

Production dialect gap 的核心責任是避免 SQLite 測試通過後，PostgreSQL / MySQL production 出現不同語意。SQLite 的 dynamic typing、date / time representation、foreign key pragma、ALTER TABLE 支援與 lock model 都會影響測試可信度。

這張表的用法是決定哪些測試留在 SQLite，哪些要升級到 production-like DB。Repository contract 可用 SQLite；query optimization、vendor SQL、online schema change、CDC、replication、pooling 都應回到 PostgreSQL / MySQL 章節。

Contract test 設計

Contract test 的核心責任是讓不同 DB adapter 對 application 呈現同一組語意。SQLite fixture 測的是 application port 的行為，例如 duplicate key、not found、transaction rollback、pagination、domain invariant，而非底層 engine 的所有細節。

1Repository contract
2├── Create / read / update / delete
3├── Unique conflict → ErrAlreadyExists
4├── Missing row → ErrNotFound
5├── Transaction rollback restores domain invariant
6├── Pagination order stable
7└── Migration version matches fixture

如果 production adapter 是 PostgreSQL / MySQL，contract test 應至少在 nightly 或 CI matrix 裡跑一輪 production-like database。SQLite 提供快速回饋，production-like test 提供 dialect confidence。

CI evidence

SQLite fixture 的 CI evidence 要證明資料狀態和 schema version 一致。測試失敗時，讀者要能知道是 application contract 失效、fixture 過期、migration 漏跑，還是 SQLite / production dialect gap。

CI 產物不一定要很複雜，但要能被下一個維護者重建。SQLite fixture 的優勢是可攜帶；若 fixture 只能靠某個人的本機狀態生成，就失去教學與維護價值。

Production 踩雷

Case 1：共用同一個 .db 檔跑平行測試

平行測試共用檔案的核心風險是 test runner 製造和 production 不同的 writer collision。測試偶發 SQLITE_BUSY，團隊可能以為 application 有 race；實際上是測試隔離不足。

修正方向是 per-test temp DB 或 read-only template copy。需要測 WAL / busy 行為時，用專門 hands-on lab，讓一般 contract test 專注在 repository contract。

Case 2：忘記開 foreign keys

Foreign key pragma 漏開的核心風險是 constraint bug 被 fixture 隱藏。SQLite foreign key enforcement 需要明確啟用；若 production DB 一定 enforce FK，fixture 也要在 connection initialization 中開啟。

修正方向是 baseline PRAGMA 和 startup assertion。每個 test DB open 後都跑 PRAGMA foreign_keys 並驗證結果。

Case 3：SQLite fixture 掩蓋 vendor-specific SQL

Vendor-specific SQL 被 SQLite 掩蓋的核心風險是 query 到 production 才失敗。例如 PostgreSQL JSONB、partial index、full-text search 或 MySQL generated column、optimizer hint 都應在 vendor DB 測。

修正方向是把 SQL 分層。Portable repository contract 可以用 SQLite；vendor-specific query 要有 PostgreSQL / MySQL test container。

操作檢查清單

SQLite fixture 設計前要回答：

1. 這個測試驗證 application contract 還是 production dialect。
2. Fixture 是 in-memory、template copy、generated file 還是 read-only。
3. PRAGMA foreign_keys、journal_mode、busy_timeout 是否固定。
4. Fixture version 如何對齊 migration version。
5. Parallel test 是否每個 worker 有獨立 DB file。
6. 哪些 query 必須在 PostgreSQL / MySQL container 再跑。
7. CI artifact 是否保留 migration log 與 dialect gap note。

下一步路由

• 上游：Repository Adapter
• Sibling：Schema Migration / Versioning、SQL Dialect and Index Limits
• 操作：Migration Fixture Lab
• 平行：PostgreSQL、MySQL
• 官方：SQLite Datatypes、SQLite STRICT Tables、SQLite PRAGMA

本文的判讀錨點是：D1 / Turso migration 是 runtime boundary 變更。Local file 直連變成 platform binding、remote endpoint 或 embedded replica；因此 migration 要同時審查 SQL support、data movement、driver API、auth、latency、freshness、backup 與 vendor exit。

Migration Drivers

Migration drivers 的核心責任是確認 edge SQLite 產品解決的是哪個服務壓力。D1 與 Turso / libSQL 都接近 SQLite experience，但它們的採用理由應寫成具體 workload。

D1 的 migration driver 要和 Cloudflare platform 綁定。若 app 已用 Workers routing、KV、Queues 或 Pages，D1 可以降低跨平台整合成本；若 app 不在 Cloudflare 生態，D1 的價值要用 latency、operation 與成本證明。

Turso / libSQL 的 migration driver 要和 replica freshness 綁定。若使用者需要 local read speed，embedded replica 有價值；若產品要求每次讀都立即看到最新 global state，就要先設計 read-after-write path。

Compatibility Audit

Compatibility audit 的核心責任是確認 local SQLite schema、query 與 migration workflow 可在 target product 上運作。官方文件要作為 limits 與 feature 的單一來源：D1 參考 Cloudflare D1 docs 與 D1 limits；Turso 參考 Turso docs 與 libSQL client reference。

Compatibility audit 要以 production query 為單位。只跑 CREATE TABLE 會漏掉最重要的差異；query suite 要包含 list page、pagination、unique violation、FK violation、transaction rollback、large batch 與 slow query。

Data Movement

Data movement 的核心責任是把 SQLite file 轉成 target platform 可接受的 seed。Local SQLite 可以先 export 成 SQL dump、CSV 或 platform CLI 支援的 import format，再進 target product。

1sqlite3 app.db ".dump" > seed.sql

這段命令只是 seed 起點。正式流程要處理 schema ordering、unsupported SQL、large transaction、batch split、sensitive data masking、import duration、row count 與 checksum。

D1 migration 要把 Wrangler / platform workflow 納入 runbook。Cloudflare D1 的 limits 文件列出 import 與 query 限制；大型資料變更應切 batch，並在 preview / staging database 跑完整 dry run。

Turso migration 要把 remote database 與 embedded replica 分開驗證。Seed 完 remote primary 後，要測 local embedded replica 的 bootstrap、sync、read freshness、write delegation 與 offline behavior。

Application Change

Application change 的核心責任是把 database access 從 file path 改成可替換 adapter。Local SQLite 常用 file path 與 process-local connection；D1 / Turso 會加入 binding、endpoint、token、client SDK、network failure 與 platform runtime。

Repository adapter 要承擔 driver 差異。Domain layer 應看到穩定的 repository contract，例如 duplicate key、stale read、temporary unavailable、retryable write；底層才處理 D1 binding 或 libSQL client。

Idempotency 是 edge migration 的關鍵。Write request 進入 network / serverless runtime 後，retry 可能在 client、platform 或 application 層發生；每個 critical write 都應有 idempotency key 或 natural unique key。

Evidence

Evidence 的核心責任是證明 edge migration 帶來的收益大於新風險。D1 / Turso 的成功要同時看功能可用、region latency、freshness、error rate、cost、migration time 與 exit route。

Freshness evidence 要用產品語言寫。若 UI 可以顯示「同步中」，freshness window 可被使用者理解；若是付款、庫存、權限決策，讀舊資料會直接造成業務錯誤，這類 workflow 要走 primary read 或 server SQL。

Exit route 要被演練。Edge product 的 adoption cost 低，exit cost 會出現在 driver API、migration workflow、platform binding 與 data export；至少要能把 staging data export 回 SQLite file 並通過 smoke test。

Rollback

Rollback 的核心責任是保留 local SQLite snapshot 與 read-only fallback。Edge migration 若在 cutover 後遇到 auth、latency、limit 或 query error，團隊要能快速回到上一個可用資料狀態。

Local snapshot 要保存到 cutover 後的觀察窗口結束。若 cutover 期間已有 target-only writes，要設計回放或 reconciliation；高風險 workflow 可以先進 read-only cutover，再逐步開寫。

Decision Route

Decision route 的核心責任是把 edge migration 和 server DB migration 分開。D1 / Turso 適合 edge runtime 與 SQLite-like workflow；當需求轉向 central audit、server role、high-write OLTP 或 distributed transaction，應改走 PostgreSQL / CockroachDB / Spanner。

下一步路由

SQLite to D1 / Turso migration 完成後，先讀 D1 / Turso / libSQL comparison 釐清 product boundary；再用 SQL dialect and index limits 做 compatibility audit；需要操作演練時讀 D1 / Turso preview lab。

本文的判讀錨點是：升級到 PostgreSQL 是服務責任擴大，而非單純換 driver。Migration 要同時處理 schema 語意、資料搬遷、application adapter、backup / PITR、role、observability、cutover 與 rollback。

Migration Drivers

Migration drivers 的核心責任是確認 PostgreSQL 真的承擔新增責任。SQLite 在 single-node、single-file、low-concurrency 場景很強；PostgreSQL 的價值出現在 server database governance。

Driver 要被量化。若問題只是單一 CLI 檔案變大，先改善 backup、VACUUM、index 與 WAL runbook；若問題是多 instance 同時寫、權限分離、audit 與 PITR，PostgreSQL 才是正確路由。

Diff Audit

Diff audit 的核心責任是把 SQLite 語意轉成 PostgreSQL 語意。SQLite 的 type affinity、date / time convention、auto-increment、foreign key、index、JSON、transaction 與 extension 都要逐項審查。

Type mapping 要先保護 domain invariant。金額欄位用 integer cents 或 numeric、時間欄位用 timestamptz 或明確 UTC text、boolean 用 boolean；每個轉換都要有 invalid sample 與 round-trip test。

Index mapping 要用 production query 重跑 explain。SQLite 的 EXPLAIN QUERY PLAN 只能說明 SQLite planner；PostgreSQL 需要自己的 EXPLAIN (ANALYZE, BUFFERS)，並使用接近真實分布的資料量。

Phase Plan

Phase plan 的核心責任是降低一次性 cutover 風險。SQLite to PostgreSQL migration 通常可以分成 schema 建模、資料匯出、adapter 切換、shadow read、freeze / cutover 與 cleanup。

Adapter layer 是風險控制點。Repository 應把 SQLite 與 PostgreSQL driver 差異藏在 infrastructure layer，domain 不直接依賴 vendor-specific SQL exception 或 connection object。

Shadow read 適合先驗證 read contract。正式寫入仍留在 SQLite 時，background job 可以把相同 query 跑到 PostgreSQL mirror，記錄 row count、field diff、排序差異與 latency。

Data Movement

Data movement 的核心責任是讓搬遷結果可驗證。SQLite database file 可以透過 .dump、CSV export、application-level export 或 custom ETL 搬入 PostgreSQL；選擇取決於資料量、型別轉換、FK order 與 downtime window。

1sqlite3 app.db ".mode csv" ".headers on" ".once orders.csv" "SELECT * FROM orders ORDER BY id;"
2psql "$DATABASE_URL" -c "\\copy orders FROM 'orders.csv' CSV HEADER"

這段命令是教學骨架。正式 migration 要處理 quoting、NULL、timezone、large object、FK order、batch size、transaction size、retry、import log 與 sensitive data handling。

Row count 是基本證據，checksum 是更強證據。可以針對每張表計算穩定排序後的 hash，或在 application layer 對 domain key 與重要欄位做 checksum。

1SELECT COUNT(*) FROM orders;
2SELECT SUM(total_cents) FROM orders;

Aggregate checksum 適合快速抓大錯。正式驗證還要補抽樣 row diff、edge case row、foreign key check 與 business invariant。

Cutover

Cutover 的核心責任是控制最後一次寫入切換。SQLite source 在 cutover 前應進入 read-only 或 writer freeze，確保最後 snapshot、import 與 validation 對齊。

Rollback 要保存 source snapshot。若 cutover 後發現 PostgreSQL error mapping、permission 或 performance 問題，可以切回 SQLite read/write snapshot；前提是 cutover window 內所有新寫入都能回放或被阻擋。

PostgreSQL Operation Gate

PostgreSQL operation gate 的核心責任是確認團隊準備好接手 server DB。Migration 成功要包含資料進入 target 與 operation readiness；PostgreSQL 需要 connection pool、backup / PITR、vacuum、index bloat、role、migration lock review 與 alert。

最小 operation checklist：

1. Connection pool 設計：max connections、pool size、timeout、transaction pooling policy。
2. Backup / PITR：restore drill、retention、RPO / RTO。
3. Role / grant：application role、migration role、read-only role。
4. Migration lock review：DDL impact、online migration strategy。
5. Observability：slow query、lock wait、deadlock、replica lag、disk。
6. Incident route：rollback、restore、read-only mode、on-call owner。

這個 gate 要在 cutover 前完成。SQLite 讓 operation surface 很小；PostgreSQL 擴大能力的同時，也擴大維護責任。

No-Go Conditions

No-go condition 的核心責任是阻止過早升級。若服務仍是 single-user、local-first、low-write、可用簡單 backup 解決，PostgreSQL 可能引入比問題更大的 operation cost。

No-go 條件要轉成 tripwire。當 writer concurrency、audit、PITR、role 或 HA 需求跨過明確門檻，再啟動 migration。

下一步路由

SQLite to PostgreSQL migration 完成後，下一步要看 target operation。PostgreSQL 能力讀 PostgreSQL；migration 方法讀 Database Migration Playbook；若需求只是 edge platform，改讀 SQLite to D1 / Turso migration。