数据访问
业务代码如何访问数据库:只经过仓储,同一套契约覆盖 SQLite、D1 和 Postgres,事务在每种数据库上意味着什么,以及为什么迁移按方言分别维护。
同一套业务代码可以运行在 SQLite、Cloudflare D1 和 Postgres 上。所有数据库访问都经过 src/server/db/repositories/*,数据库之间的差异都放在下层的 schema、迁移和适配器层。切换数据库见使用 Postgres。
仓储是唯一的入口
服务端函数、服务和 API 路由调用仓储函数。它们不导入 Drizzle 表、不写 SQL,也不按方言分支。仓储通过 withRepositoryDialect 获得三个值:
| 值 | 含义 |
|---|---|
db | 当前适配器的 Drizzle 数据库 |
schema | 该数据库对应的表定义:schema/postgres.ts 或 schema/sqlite.ts |
dialect | "postgres"、"sqlite" 或 "d1" |
两个 schema 文件定义了同名、同列的表,所以仓储针对 schema.billingOrders 写一条查询,在两边都能运行。某一列的存储方式不同时(最常见的是时间戳),仓储就在那一处根据 dialect 做转换。Agent 的表在 agent-sqlite.ts 和 agent-postgres.ts 中遵循同样的做法。
两个 schema 家族,五个适配器
适配器决定应用如何连接,schema 家族决定执行哪种 SQL。
| 适配器 | Schema 家族 | 运行环境 | 连接方式 |
|---|---|---|---|
sqlite | SQLite | Node | 通过 better-sqlite3 访问本地文件 |
turso | SQLite | Node | libSQL,使用 DATABASE_URL 和 DATABASE_AUTH_TOKEN |
d1 | SQLite | Cloudflare Workers | EDGE_DB 绑定 |
postgres | Postgres | Node | DATABASE_URL,每个进程一个客户端 |
hyperdrive | Postgres | Cloudflare Workers | HYPERDRIVE 绑定,每个请求一个客户端 |
DATABASE_ADAPTER 选择其中之一,默认与 DATABASE_DIALECT 相同。两个家族都可以注册自己的适配器,见编写自定义数据库适配器。
Worker 不能复用在处理另一个请求时打开的 socket。因此 hyperdrive 适配器把 Postgres 客户端创建在按请求划分的作用域里:Worker 入口用 runInRequestScope 包住每个请求和每次定时事件,客户端的生命周期与该作用域相同。真正的连接由 Hyperdrive 池化。Node 上没有这个作用域,postgres 适配器始终保留一个客户端。
事务在每种数据库上意味着什么
仓储只写一遍,使用异步事务回调:db.transaction(async (tx) => { ... })。实际执行方式取决于数据库。
| 数据库 | 行为 |
|---|---|
| Postgres、Hyperdrive、Turso | 驱动把回调作为交互式事务执行 |
SQLite(better-sqlite3) | 驱动是同步的,拒绝异步回调,所以仓储门面在同一个连接上把它作为真正的事务执行:BEGIN IMMEDIATE,然后 COMMIT,失败则 ROLLBACK 并抛出原始错误。同一进程内的事务按顺序一个一个执行,嵌套调用会加入已打开的事务 |
| D1 | 没有交互式事务。仓储上下文报告 d1,本来要开事务的代码改为把同样的语句逐条执行 |
在 SQLite 上,事务回调里只应做数据库操作并保持简短,因为进程里其它已排队的工作可能在它的语句之间执行。在 D1 上,多步写入不是原子的,所以必须能安全地重复执行或中途停下。需要事务来保存运行状态的 Agent 也因此不使用 D1。
一条语句就够的地方,代码就只用一条。定时任务的锁是一条带条件的更新,履约的认领是唯一键下的一次插入,所以它们在三种数据库上行为一致。
迁移按方言分别维护
迁移链有两条,每个 schema 家族一条,文件名相同:
| 迁移链 | 用于 | 执行方式 |
|---|---|---|
drizzle/migrations/sqlite | SQLite、Turso、D1 | pnpm db:migrate;D1 用 pnpm db:migrate:d1:local 和 pnpm db:migrate:d1:remote |
drizzle/migrations/postgres | Postgres、Hyperdrive | pnpm db:migrate,生产镜像里用 pnpm db:migrate:runtime |
两条链都由人手工维护。改 schema 意味着同时修改两个 schema 文件,并在两条链里各加一个同名迁移。pnpm db:generate:sqlite 和 pnpm db:generate:postgres 可以分别生成初稿。之后由 pnpm validate:migrations 检查两条链是否一致:日志与文件一致,每条链都能在空库上重放,每个 --> statement-breakpoint 分段只含一条语句,两种方言最终得到相同的表。
pnpm db:migrate 对迁移工具做了一层包装,用来解释一种它原本会静默失败的状态:表已经存在,但迁移记录为空,说明数据库不是通过迁移链建立的。
相关文件
有三个校验器覆盖这一层:validate:db-adapters(注册表、绑定与服务端入口)、validate:migrations(两条迁移链)和 validate:sqlite-transactions(默认 SQLite 适配器上的提交、回滚、顺序与嵌套)。