主题

SQLite

SQLite 表示项目把 SQLite 作为默认持久层、ledger、audit log、content/settings store 或低运维 embedded database,并围绕它建立路径、schema、迁移、volume、备份和运行时 ownership 约定。它不是“依赖树里有 sqlite”这么宽,而是数据库文件本身已经成为系统 contract 的一部分。

  • 服务

目录

Definition

SQLite 表示项目把 SQLite 作为默认持久层、ledger、audit log、content/settings store 或低运维 embedded database,并围绕它建立路径、schema、迁移、volume、备份和运行时 ownership 约定。它不是“依赖树里有 sqlite”这么宽,而是数据库文件本身已经成为系统 contract 的一部分。

这个 Topic 的维护重点是数据边界,而不是 SQL 语法细节。项目快照必须说明 SQLite 保存的是产品数据、审计日志、generation history、key pool、内容设置还是 session/config,谁读写它,迁移怎么做,容器或本地运行如何保留它,以及哪些信息仍然必须回写到 checked-in 文档(projects/style-playbook-skills.md、projects/tavily-hikari.md、projects/blog-26.md)。

When to use

当项目有 drizzle.config.ts、SQLx SQLite features、.sql migrations、DB path env、ledger DB 或 README 中明确的 SQLite persistence 时使用。

如果改动涉及 schema migration、DB path、Docker volume、audit retention、generation records、content/settings、proxy ledger 或本地低运维部署,就应使用本 Topic。若 SQLite 只是 transitive dependency、测试 fixture 或可选示例存储,不应自动标记(projects/codex-vibe-monitor.md)。

当页面摘要、部署文档或 release workflow 提到 SQLite 路径、迁移、备份、volume 或运行状态,也应回到本 Topic 核对;这些信息往往比依赖名更能证明 SQLite 是 current runtime contract(projects/blog-26.md)。

Habits / defaults

  • 单节点个人/小团队服务默认优先 SQLite,减少额外数据库运维;projects/proxy-broker.md 和 projects/codex-vibe-monitor.md 都是 Rust service + SQLite。
  • 路径必须明确区分 dev/test/prod;projects/blog-26.md 记录 DB_PATH、dev data、Docker data path。
  • 自动化/注册类工具用 SQLite 做 ledger,比临时 JSON 更适合重试、审计和错误复盘;projects/tavreg-hikari.md 是代表。
  • 站点/知识库工具使用 SQLite 保存 generation history 时,Markdown 仍是知识真相源,DB 只保存运行状态;projects/style-playbook-skills.md 保留这个边界。
  • 项目摘要要写清 DB ownership:是单服务独占、CLI ledger、后台任务记录,还是 Web app runtime state。不同 ownership 决定备份、并发和迁移策略(projects/proxy-broker.md、projects/tavily-hikari.md)。
  • 对 Dockerized 服务,SQLite 必须和 volume/data dir 一起记录;容器镜像可重建,DB 文件不可随容器删除(projects/blog-26.md、projects/tavily-hikari.md)。
  • 默认把 migration 机制与 DB path 一起看。Drizzle + SQLite、SQLx + migrations/、直接 .sql 文件都可能成立,但 Topic 里要写清哪一套才是当前真相;否则维护者只知道“用了 SQLite”,却不知道该改哪里(projects/blog-26.md、projects/octo-rill.md)。
  • SQLite 的 release-to-release state compatibility、migration rollout、forward repair 与验证应交给 Persistent-state migrations;本 Topic 保留 SQLite-specific schema location、DB path、volume、backup 与 runtime ownership,不能把某个 SQLite 工具或操作方式推广为通用 migration policy。
  • 先分清 SQLite 是“产品主存储”还是“运营/审计附属存储”。projects/blog-26.md 的 content/settings、projects/codex-vibe-monitor.md 的 audit/history、projects/style-playbook-skills.md 的 generation/state,其回写、备份和变更审查标准都不同。
  • 对带 Web UI 的单节点服务,要把 SQLite 对前端行为的影响写出来。很多页面展示的历史数据、session 状态、统计图或配置表单,本质上都依赖 DB schema 和保留策略,不是纯后端内部实现(projects/proxy-broker.md、projects/codex-vibe-monitor.md)。

Reference implementations

  • projects/blog-26.md:Drizzle + SQLite content/settings。
  • projects/proxy-broker.md:operator service/session/config persistence。
  • projects/tavily-hikari.md:MCP proxy key pool 和 audit log。
  • projects/style-playbook-skills.md:generation run 与站点状态 DB,不替代 Markdown。
  • projects/proxy-broker.md:operator service/session/config persistence,适合检查 admin UI 与 backend state 如何共享 SQLite。
  • projects/codex-vibe-monitor.md:代理调用记录、CRS 日统计和历史只读数据共同进入 SQLite,适合检查 audit log 与 dashboard 查询的边界。

Failure modes

  • 把 SQLite 当作无 schema 文件存储,会导致 migration 和备份策略缺失。
  • Docker 部署不挂载 volume 会丢数据。
  • 把 DB 状态当 knowledge truth,会让人工 project/topic docs 与站点显示漂移。
  • 把 DB path 写死到开发环境会让生产/测试互相污染;应通过 env、config 或部署文档区分 dev/test/prod,并在项目快照中记录默认路径(projects/blog-26.md)。
  • 自动生成内容若只写入 SQLite 而不回写 Markdown,会造成站点短期可见但知识库不可复用;style playbook 的长期真相仍应落到 skills/style-playbook/references/**(projects/style-playbook-skills.md)。
  • 只记“用了 SQLite”不记 ownership,会让后续回答没有审查抓手。修正方式是写清谁创建 schema、谁持有写权限、谁消费只读历史、哪些数据可以丢、哪些不能丢(projects/tavily-hikari.md、projects/proxy-broker.md)。
  • 把 SQLite 看成“以后再上 PostgreSQL 的临时方案”也会弱化当前事实。只要当前部署、备份、恢复、volume 和 UI 行为都围绕 SQLite 设计,它就是正式 contract,不应在 Topic 里被轻描淡写。
  • 以 SQLite 的具体 migration tool、单一事务能力或文件路径替代 release-to-release compatibility evidence,会把 storage implementation 和跨版本政策混淆;应引用 Persistent-state migrations 并保留本 Topic 的 SQLite operational facts。

Evidence index

  • projects/blog-26.md
  • projects/style-playbook-skills.md
  • projects/codex-vibe-monitor.md
  • projects/tavily-hikari.md
  • projects/tavreg-hikari.md
  • skills/style-playbook/references/topics/persistent-state-migrations/TOPIC.md