SQLite Teaching Structure
SQLite teaching structure 的核心責任是把 SQLite 從單篇 vendor overview 擴成可教學的服務章節群。PostgreSQL / MySQL 的完整度來自 overview、deep article、migration playbook 與案例路由;SQLite 的完整度也要保留同樣層級,但正文重點要貼合它自己的服務語言:single file、embedded process、writer boundary、backup / restore、test fixture、local-first 與 edge SQLite 變體。
完成標準
SQLite 章節群的完成標準是讀者能回答三個問題。第一,SQLite 何時是正式狀態而非臨時檔案;第二,SQLite production 化後要如何處理 WAL、backup、restore、migration、測試與觀測;第三,SQLite 成長後該升到 PostgreSQL / MySQL、Cloudflare D1、Turso / libSQL、Litestream / LiteFS 或 mobile sync。
| 層級 | SQLite 對應文件 | 教學責任 |
|---|---|---|
| Service overview | SQLite | 第一輪服務定位、適用壓力、替代邊界與下一步路由 |
| Core deep article | File lifecycle / backup boundary | WAL sidecar、backup API、restore drill、corruption recovery |
| Hands-on | SQLite Hands-on | local file、backup restore、WAL busy、migration fixture |
| Operations | WAL / locking、PRAGMA tuning、schema migration、observability | 日常設定、排錯、容量訊號與 release gate |
| Application shape | test fixture、mobile / desktop store、local-first sync | SQLite 跟 application process / device / test workflow 的關係 |
| Edge / variants | D1 / Turso / libSQL、Litestream / LiteFS | 分散式或 replicated SQLite 變體的責任邊界 |
| Migration route | SQLite → PostgreSQL、SQLite → D1 / Turso、PostgreSQL → SQLite | 成長、edge 化或降操作成本時的階段化搬遷 |
這份結構的重點是避免把 SQLite 寫成小型 PostgreSQL。SQLite deep article 要先處理檔案、process、filesystem、device、test 與 edge runtime;SQL dialect、index 與 migration 工具只有在這些責任成立後才展開。
推薦撰寫順序
撰寫順序要從正式狀態的最低操作責任開始,再逐步擴到應用形狀、edge 變體與 migration。
| 順序 | 文件 | 狀態 | 為什麼排在這裡 |
|---|---|---|---|
| 1 | File lifecycle / backup boundary | 已有正文 | 先回答 SQLite 如何成為可恢復的正式狀態 |
| 2 | WAL concurrency / locking | 已有正文 | writer boundary 是 SQLite production 判斷的核心 |
| 3 | PRAGMA tuning / performance | 已有正文 | 把 journal、sync、cache、mmap 轉成可驗證的設定 |
| 4 | Schema migration / versioning | 已有正文 | 單檔案 DB 仍需要版本、rollback 與 app release 配合 |
| 5 | Test fixture best practice | 已有正文 | SQLite 最常被語言教材引用,需要明確 production gap |
| 6 | Mobile / desktop embedded store | 已有正文 | 說明 device local state、backup、sync 與 privacy 責任 |
| 7 | Local-first sync boundary | 已有正文 | 把 single-device SQLite 與 multi-device sync 分開 |
| 8 | D1 / Turso / libSQL comparison | 已有正文 | edge SQLite 變體需要獨立比較,和本地 SQLite 分開 |
| 9 | Litestream / LiteFS replication | 已有正文 | backup / read replica / failover 的語意要跟 multi-write 分開 |
| 10 | SQL dialect and index limits | 已有正文 | 對照 PostgreSQL / MySQL 測試與 migration gap |
| 11 | Observability / runbook | 已有正文 | 把 SQLite 的低操作成本補成可交接 evidence |
| 12 | Hands-on 操作路線 | 已有正文 | 把 local file、backup、WAL busy、migration fixture 變成演練 |
| 13 | SQLite to PostgreSQL migration | 已有正文 | 多 tenant、權限、HA、schema governance 出現時的主要升級路徑 |
| 14 | SQLite to D1 / Turso route | 已有正文 | edge / serverless 化時的 migration route |
| 15 | PostgreSQL to SQLite simplification | 已有正文 | 小型工具、single-user app 或 embedded 需求的反向路徑 |
這個順序讓 SQLite 先完成自己的核心語言,再處理相鄰產品。D1、Turso、LiteFS、Litestream 都帶有 SQLite 相容性,但教學上要先問它們承擔的是 backup、replication、edge locality、read replica 還是 distributed write。
文件命名規則
SQLite 章節群的檔名用服務責任命名,product-first 命名只留給 D1 / Turso / libSQL 這類 product boundary 本身就是教學主題的文件。
| 類型 | 命名方式 | 範例 |
|---|---|---|
| Core deep | {mechanism}-{responsibility} | wal-concurrency-locking.md |
| Operation | {operation}-{decision-signal} | pragma-tuning-performance.md |
| Application | {context}-{state-role} | mobile-desktop-embedded-store.md |
| Variant | {products}-comparison | d1-turso-libsql-comparison.md |
| Migration | migrate-to-{target} | migrate-to-postgresql.md |
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 議題 | 主要跨模組路由 |
|---|---|
| Backup / restore | Observability Evidence Package、Incident Decision Log |
| Test fixture | Repository Adapter、語言教材的 contract test |
| Local-first / sync | Data Protection、offline / device privacy |
| Edge SQLite | Global Distributed OLTP、deployment platform |
| Performance | Bottleneck Localization |
後續審查點
SQLite 章節群完稿後要特別審查三個偏誤。第一是把 SQLite 過度美化成 production SQL 替代品;第二是把 edge SQLite 產品跟本地 SQLite 混成同一種能力;第三是把 test fixture 的便利性誤寫成 production equivalence。