sqlite-skill

# SQLite Skill ## 意图 帮助 Agent 独立处理 SQLite 相关的数据层问题：数据库设计、SQL 编写、迁移、事务、索引、同步、性能、安全和可靠性。 本 skill **只负责 SQLite 与离线数据工程本身**。如果业务项目还涉及具体框架、端平台、插件封装或 UI 工程，由用户主动指定或另行调用对应能力；本 skill 不主动耦合其他 skill。 如果用户明确指定要做 uni-app / UTS 的三端 SQLite 插件，可另行使用 `sqlite-uniapp-uts` 处理插件工程与平台 Adapter；本 skill 只提供 SQLite 数据层规则。 ## 触发场景 - SQLite 建表、查询、索引、事务、迁移、`PRAGMA`、`EXPLAIN QUERY PLAN`。 - 本地数据库、离线缓存、offline-first、同步队列、软删除、冲突处理。 - SQLite 性能、安全、SQL 注入、敏感数据、数据库文件、备份恢复、多账号隔离。 - 需要设计 DAO、Repository、LocalDatabase adapter、QueryBuilder、sync engine、migration runner、health check。 - 需要判断 SQLite 与 IndexedDB、WebSQL、localStorage、文件存储或服务端数据库的边界。 ## 非目标 - 不负责具体业务框架的页面、组件、路由、构建、插件封装或平台 API 细节。 - 不默认任何运行端支持 SQLite；只给 SQLite 数据层方案与能力核查清单。 - 不把浏览器、移动端、桌面端、后端脚本、嵌入式设备混为同一运行环境。 - 不写完整 SQLite 教程；细节按需读取 references。 ## 维护与复用约定 本 skill 遵循仓库 README 的通用规范：中文优先、自包含、渐进式披露、验证再交付。修改或分发本 skill 时读取 `references/repository-usage.md`；只复制/打包整个 `skills/sqlite-skill/` 目录，不只复制 `SKILL.md`。 ## 核心原则 1. 先确认运行环境：SQLite CLI、Node、移动端 wrapper、桌面端、浏览器 WASM、后端脚本或其他宿主。 2. 先确认 SQLite 版本、编译选项、wrapper 暴露能力、文件系统限制和测试环境。 3. 先确认数据规模、读写频率、同步方式、账号/租户隔离、隐私等级和冲突策略。 4. SQL 示例必须使用 SQLite 兼容语法；不确定宿主 API 时只给通用 SQL 与架构，并说明以具体 wrapper 文档为准。 5. 外部输入必须参数化；动态表名、列名、排序字段必须白名单化。 6. 离线功能必须同时考虑初始化、迁移、事务、同步队列、软删除、重试、冲突和状态恢复。 7. SQLite 不是加密存储；敏感数据默认不明文落库。 8. `PRAGMA foreign_keys = ON` 需每个连接启用并查询确认；PRAGMA 拼错可能被静默忽略。 9. 不把 `INSERT OR REPLACE` / `REPLACE INTO` 当安全 upsert；优先考虑 `ON CONFLICT DO UPDATE` 并确认 SQLite 版本。 10. 不滥用 `AUTOINCREMENT`；先理解 `INTEGER PRIMARY KEY`、rowid、NULL、布尔值和类型亲和性。 11. WAL、FTS5、JSON1/JSONB、SQLCipher、STRICT table、`RETURNING`、backup API 不承诺在所有运行环境可用，必须检测版本/编译选项/wrapper 能力。 12. 对跨宿主项目，只定义平台中立 Adapter 契约；具体平台 API、插件封装和条件编译由用户另行指定。 ## 工作流 ### 1. 运行环境与能力核查 读取 `references/overview.md`、`references/runtime-boundaries.md`、`references/pragmas-and-diagnostics.md`。 1. 确认宿主环境、SQLite 版本、扩展支持和 wrapper API。 2. 区分 SQLite、IndexedDB、WebSQL、key-value storage、文件存储、服务端 RDBMS。 3. 确认数据库文件路径、沙盒/权限、备份、升级、低磁盘空间和崩溃恢复限制。 4. 执行或规划能力探测：SQLite 版本、编译选项、关键 PRAGMA、扩展模块和 wrapper 限制。 ### 2. Schema / 建表设计 读取 `references/schema-design.md`、`references/data-types-and-affinity.md`、`references/constraints-and-indexes.md`。 1. 明确实体、字段、主键、唯一约束、外键、时间格式和生命周期。 2. 离线同步场景区分本地 id、服务端 id、客户端幂等 key。 3. 设计 `sync_status`、`deleted_at`、`version`、`created_at`、`updated_at` 等字段。 4. 为高频 `WHERE`、`JOIN`、`ORDER BY` 字段添加索引。 5. 输出 `CREATE TABLE`、`CREATE INDEX` 和迁移说明。 ### 3. Adapter / DAO / SQL 编写与优化 读取 `references/adapters-and-api-contracts.md`、`references/querybuilder-and-dao.md`、`references/sql-basics.md`、`references/performance.md`。涉及全文搜索、JSON 或批处理时再读取 `references/fts5-and-search.md`、`references/json-and-generated-columns.md`、`references/limits-and-batching.md`。 1. 判断 SQL 类型：DDL、DML、查询、事务或诊断。 2. 需要跨宿主时，先给最小 `LocalDatabase` 契约，再实现 DAO / Repository。 3. 使用参数绑定占位符，不拼接用户输入。 4. 动态排序、列名和表名必须白名单化；QueryBuilder 只生成受控 SQL 片段。 5. 对复杂查询说明索引、分页和查询计划。 6. 批量写入必须放在事务中。 7. 警惕 `LIKE '%xxx%'`、大偏移 `OFFSET`、未分页全表读。 ### 4. 数据迁移 读取 `references/migrations.md`。 1. 用 `PRAGMA user_version` 或 `schema_migrations` 管理版本。 2. 从旧版本顺序升级到最新版，迁移放事务中。 3. 复杂表结构变更使用建新表、复制、删旧表、重命名、重建索引模式。 4. 覆盖新装建库、旧库升级、重复启动、迁移失败恢复。 ### 5. 离线同步 读取 `references/sync-patterns.md`、`references/common-recipes.md`。 1. 明确同步方向、同步粒度、幂等 key、软删除和冲突策略。 2. 本地业务写入和 outbox/sync queue 状态更新放在同一事务。 3. 网络恢复后先处理待上传，再拉取远端增量，避免覆盖本地未同步数据。 4. 设计失败重试、重复提交、部分成功、崩溃恢复和用户可见状态。 ### 6. 安全与可靠性 读取 `references/security.md`、`references/transactions-and-concurrency.md`、`references/backup-and-restore.md`、`references/pitfalls.md`。 1. 参数化查询、防注入、动态标识符白名单、日志脱敏。 2. 多用户/多租户数据隔离，退出登录和切换账号时清理敏感缓存。 3. 需要加密时调研 SQLCipher、系统安全存储或宿主平台安全能力。 4. 关注 SQLite 单写多读、WAL、锁等待、崩溃恢复和备份一致性。 ## References | 场景 | 读取 | |---|---| | SQLite 总览 | `references/overview.md` | | 运行环境边界 | `references/runtime-boundaries.md` | | Adapter 与 API 契约 | `references/adapters-and-api-contracts.md` | | 连接生命周期 | `references/connection-lifecycle.md` | | Statement 与参数绑定 | `references/statement-and-binding.md` | | 结果集映射 | `references/result-set-mapping.md` | | 统一错误模型 | `references/error-model.md` | | DAO / QueryBuilder | `references/querybuilder-and-dao.md` | | PRAGMA 与诊断 | `references/pragmas-and-diagnostics.md` | | SQL 基础 | `references/sql-basics.md` | | 表结构设计 | `references/schema-design.md` | | 数据类型 | `references/data-types-and-affinity.md` | | 约束与索引 | `references/constraints-and-indexes.md` | | 事务与并发 | `references/transactions-and-concurrency.md` | | 备份与恢复 | `references/backup-and-restore.md` | | 数据库迁移 | `references/migrations.md` | | 性能优化 | `references/performance.md` | | FTS5 与搜索 | `references/fts5-and-search.md` | | JSON 与生成列 | `references/json-and-generated-columns.md` | | Limits 与批处理 | `references/limits-and-batching.md` | | 同步模式与冲突 | `references/sync-patterns.md` | | 安全 | `references/security.md` | | 常用模板 | `references/common-recipes.md` | | 避坑 | `references/pitfalls.md` | | 官方文档索引 | `references/official-docs-map.md` | | 能力检测 | `references/capability-detection.md` | | C API 与 wrapper 映射 | `references/c-api-and-wrappers.md` | | sqlite3 CLI | `references/cli.md` | | 错误码与诊断 | `references/errors-and-diagnostics.md` | | 功能版本矩阵 | `references/feature-matrix.md` | | 测试检查清单 | `references/testing.md` | | 仓库复用与维护 | `references/repository-usage.md` | ## 交付检查清单 - [ ] 已确认宿主环境、SQLite wrapper/API、版本、编译选项和扩展支持。 - [ ] 跨宿主项目已隔离平台中立 Adapter 契约与具体平台实现。 - [ ] 已区分 SQLite、IndexedDB、WebSQL、key-value storage、文件存储、服务端数据库。 - [ ] 已覆盖新装建库、旧库升级、重复启动、迁移失败恢复。 - [ ] 已验证事务回滚、同步重复提交、软删除、冲突和网络失败重试。 - [ ] 已评估数据库文件路径、权限、备份、卸载/清理、升级、低磁盘空间。 - [ ] 已确认 SQL 参数绑定、动态标识符白名单、DAO 事务边界和日志脱敏。 - [ ] 已规划健康检查：`integrity_check` / `quick_check`、数据库大小、关键 PRAGMA、慢查询和最近同步错误。 - [ ] 已评估备份恢复、WAL/checkpoint、limits/批处理、FTS5/JSON 等能力是否被宿主支持。 - [ ] 已规划目标宿主的真实环境验证，不用模拟环境替代关键端侧验证。