drizzle-sqlite

dot-skills Drizzle SQLite 最佳实践

面向 Drizzle ORM 与 SQLite 系列后端的库参考技能。包含 8 个类别中的 45 条规则，按执行生命周期的影响排序：架构 → 迁移 → 查询 → 关系 → 事务 → 性能 → 连接 → 类型。

适用时机

在以下情况参考这些指南：

• 定义 sqliteTable 架构——选择列类型、主键、索引和外键
• 运行 drizzle-kit generate / migrate / push，或手动编辑迁移 SQL 文件
• 使用 db.select()、db.insert()、db.update()、db.delete() 编写查询
• 使用 db.query.* 和关系查询构建器获取嵌套数据
• 使用 db.transaction() 或 db.batch()（libsql/Turso/D1）封装多语句写入
• 使用 .prepare() + sql.placeholder() 或覆盖索引优化热路径查询
• 设置 Drizzle 客户端（pragmas、驱动选择、单例生命周期）
• 将数据库类型接入应用代码（$inferSelect、drizzle-zod、JSON 结构）

此技能并非针对某个特定驱动——它涵盖 better-sqlite3、libsql、bun:sqlite、expo-sqlite、op-sqlite 和 Cloudflare D1 共通的行为，并在存在差异时指出特定驱动的区别。

架构背景

SQLite 在生产数据库中颇为特殊：

• 没有客户端/服务端。“连接”就是打开一个文件。在本地文件场景中，没有连接池、身份验证或网络。
• **只有一个写入者。**无论有多少连接，同一时间都只能有一个写入者。启用 WAL 后可以并行读取。
• **没有原生布尔值或日期。**所有内容都是 INTEGER、REAL、TEXT、BLOB 或 NULL——其余类型由 Drizzle 列模式编码。
• **ALTER TABLE 功能有限。**仅支持 RENAME COLUMN、ADD COLUMN、DROP COLUMN。更改类型和添加约束都需要重建表。
• 默认关闭外键。PRAGMA foreign_keys = ON 按连接设置，且不会持久保存。

此技能中的许多规则之所以存在，是因为 Drizzle 的 API 对 PostgreSQL/MySQL/SQLite 做了统一抽象——但底层 SQLite 引擎有其限制，如果像使用 Postgres 一样对待它，这些限制会在运行时显现。

按优先级排列的规则类别

优先级	类别	影响	前缀
1	架构定义	严重	schema-
2	迁移与 Drizzle Kit	严重	migrate-
3	查询构建	高	query-
4	关系	高	rel-
5	事务与批处理	中高	tx-
6	预处理语句与热路径	中高	perf-
7	连接与驱动设置	中	conn-
8	类型推断	中	types-

快速参考

1. 架构定义（严重）

• schema-integer-for-booleans — 使用 integer({ mode: 'boolean' })，使推断类型为 boolean，而不是 0 | 1
• schema-timestamp-mode-for-dates — 将日期存储为 integer({ mode: 'timestamp_ms' })，而不是文本
• schema-always-primary-key — 显式声明主键（单列或复合）；不要依赖隐藏的 rowid
• schema-foreign-keys-with-actions — 为每个 .references() 指定 onDelete/onUpdate
• schema-index-foreign-keys-and-lookups — 为外键列和频繁用于 WHERE 的列建索引——SQLite 不会自动为外键建索引
• schema-text-json-not-blob-json — 使用 text({ mode: 'json' })，以便 json_extract 和 JSON 路径索引正常工作
• schema-unique-constraints-for-natural-keys — 为 email/slug/externalId 使用 .unique()，以便 onConflict 有可用的目标

2. 迁移与 Drizzle Kit（关键）

• migrate-generate-not-push-in-prod — 使用 generate + migrate；push 会删除无法协调的列
• migrate-explicit-renames — 回答重命名提示；默认会将重命名视为先删除再新增
• migrate-config-dialect-and-out — 定义 drizzle.config.ts，让命令无需标志参数即可运行
• migrate-apply-with-migrator — 使用 drizzle-kit migrate 或驱动的 migrator 模块应用迁移，而非原始 SQL
• migrate-data-backfill-as-custom-sql — 手动编辑迁移 SQL，与 DDL 一起原子性地回填数据
• migrate-commit-migrations-to-git — 将 drizzle/ SQL 和 drizzle/meta/ 快照提交到 Git；两者缺一不可

3. 查询构建（高优先级）

• query-select-columns-not-star — 使用 db.select({ ... }) 仅选择所需的列
• query-avoid-n-plus-one-with-inarray — 用 inArray() 替代循环查询
• query-always-limit-listings — 每个列表查询都需要 .limit()（最好还使用游标）
• query-bind-parameters-not-concat — 使用 eq() / sql 模板，绝不要拼接字符串值
• query-upsert-with-onconflict — 使用 .onConflictDoUpdate() 原子性地执行插入或更新，而非先查询再写入
• query-returning-instead-of-reselect — 在插入、更新或删除时使用 .returning()，可省去一次往返
• query-toSQL-and-explain — 检查生成的 SQL，并在热点路径上使用 EXPLAIN QUERY PLAN

4. 关系（高优先级）

• rel-declare-relations-for-rqb — 声明 relations() 可启用 db.query.* 和 with
• rel-prefer-with-over-manual-joins — 嵌套获取使用 with；手动联接会失去类型信息并增加代码量
• rel-partial-columns-in-with — 在 with 中使用 columns: { ... }，以限制载荷并避免数据泄露
• rel-filter-with-where-inside-with — 将关联行筛选条件放入 with.where，而非 JS
• rel-leftjoin-for-flat-aggregates — 需要聚合时，改用 leftJoin + groupBy

5. 事务与批处理（中高优先级）

• tx-wrap-multi-statement-writes — 将相关写入封装在 db.transaction() 中，以保证原子性并提升吞吐量
• tx-batch-for-libsql-roundtrips — 在 libsql/Turso/D1 上使用 db.batch()，将 N 次往返合并为 1 次
• tx-no-network-io-inside-transaction — 不要在事务中等待 HTTP / FS / Stripe 调用
• tx-handle-busy-with-retry — 对 SQLITE_BUSY 进行有次数上限的重试；仅针对暂时性错误
• tx-single-writer-no-parallel-writes — 使用 Promise.all 并行写入会产生争用；应串行执行

6. 预编译语句与热点路径（中高）

• perf-prepare-hot-paths — 对每次请求都会运行的查询使用 .prepare() + sql.placeholder()
• perf-bulk-insert-multi-row-values — 使用一次 values([...rows])，而不是在循环中执行 N 次插入
• perf-avoid-count-star-on-large-tables — 使用计数器行或键集分页，而不是 count(*)
• perf-keyset-not-offset-for-deep-pages — 键集分页可让各页的开销保持恒定
• perf-covering-index-for-hot-queries — 覆盖投影列，让查询规划器跳过读取行

7. 连接与驱动设置（中）

• conn-enable-wal — 设置 journal_mode = WAL，支持并发读取和单写入者
• conn-set-busy-timeout — 设置 busy_timeout = 5000，让锁竞争转为等待
• conn-foreign-keys-pragma — 按连接设置 foreign_keys = ON；默认关闭
• conn-singleton-client — 在模块作用域创建单例；绝不为每个请求单独构建
• conn-pick-driver-deliberately — 同步、异步还是 HTTP——根据部署目标选择

8. 类型推断（中）

• types-infer-select-insert — 使用 $inferSelect / $inferInsert 推导行类型
• types-narrow-json-with-dollartype — 使用 .$type<Shape>()，避免 JSON 列类型为 unknown
• types-getTableColumns-for-reuse — 使用 getTableColumns() + 展开语法共享投影
• types-drizzle-zod-for-runtime-validation — createInsertSchema(table) 可根据架构推导 Zod 验证器
• types-bigint-mode-for-large-integers — 对大于 Number.MAX_SAFE_INTEGER 的 ID 使用 mode: 'bigint'

使用方法

先阅读 references/_sections.md 中相关类别的概览，再阅读具体规则文件，了解详细说明和代码示例。每条规则都包含错误与正确示例——请在审查的代码中应用正确模式。

对于复杂更改（架构重新设计、迁移策略、性能优化），请先阅读受影响类别中的所有规则，再作决定。

• 章节定义 — 类别结构和影响级别
• 规则模板 — 添加新规则的模板

参考文件

文件	说明
references/_sections.md	类别定义和顺序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息

相关技能

• effect-ts — 当应用基于 Effect 时使用；Drizzle 通过 Effect.tryPromise 集成。
• nextjs-bundle-optimizer — 适用于将 SQLite 用作数据层的 Next.js 应用。
• better-auth — 常与 Drizzle SQLite 搭配用于身份验证表；有关表生成，请参阅 better-auth-scaffold。