数据访问

业务代码如何访问数据库:只经过仓储,同一套契约覆盖 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 家族运行环境连接方式
sqliteSQLiteNode通过 better-sqlite3 访问本地文件
tursoSQLiteNodelibSQL,使用 DATABASE_URL 和 DATABASE_AUTH_TOKEN
d1SQLiteCloudflare WorkersEDGE_DB 绑定
postgresPostgresNodeDATABASE_URL,每个进程一个客户端
hyperdrivePostgresCloudflare WorkersHYPERDRIVE 绑定,每个请求一个客户端

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/sqliteSQLite、Turso、D1pnpm db:migrate;D1 用 pnpm db:migrate:d1:local 和 pnpm db:migrate:d1:remote
drizzle/migrations/postgresPostgres、Hyperdrivepnpm db:migrate,生产镜像里用 pnpm db:migrate:runtime

两条链都由人手工维护。改 schema 意味着同时修改两个 schema 文件,并在两条链里各加一个同名迁移。pnpm db:generate:sqlite 和 pnpm db:generate:postgres 可以分别生成初稿。之后由 pnpm validate:migrations 检查两条链是否一致:日志与文件一致,每条链都能在空库上重放,每个 --> statement-breakpoint 分段只含一条语句,两种方言最终得到相同的表。

pnpm db:migrate 对迁移工具做了一层包装,用来解释一种它原本会静默失败的状态:表已经存在,但迁移记录为空,说明数据库不是通过迁移链建立的。

相关文件

src/server/db/repositories
src/server/db/repositories/repository-dialect.ts
src/server/db/schema/sqlite.ts
src/server/db/schema/postgres.ts
src/server/db/schema/agent-sqlite.ts
src/server/db/schema/agent-postgres.ts
src/server/db/client.ts
src/server/db/adapter-registry.ts
src/server/db/sqlite-transactions.ts
src/server/platform/request-scope.ts
drizzle/migrations/sqlite
drizzle/migrations/postgres
scripts/db/migrate.ts
scripts/db/migrate-runtime.mjs

有三个校验器覆盖这一层:validate:db-adapters(注册表、绑定与服务端入口)、validate:migrations(两条迁移链)和 validate:sqlite-transactions(默认 SQLite 适配器上的提交、回滚、顺序与嵌套)。

下一步