数据库
编写自定义数据库适配器
为 Postgres 或 SQLite schema 家族注册自己的连接方式,并用 DATABASE_ADAPTER 选择它。
数据库连接通过适配器注册表解析。内置适配器有 sqlite、postgres、turso 和 d1;你可以注册自己的适配器,例如使用公司内部的 Postgres 驱动或连接池。
准备工作
- 面向已有 schema 家族(
postgres或sqlite)的 Drizzle 兼容数据库客户端。 - 服务端代码中一个在首次访问数据库之前执行的位置。
同一 schema,不同连接
适配器只改变应用的连接方式。全新的 SQL 方言(例如 MySQL)还需要自己的 schema 文件、迁移链和仓储分支。
注册适配器
调用 registerDatabaseAdapter
在第一次调用 getDatabase() 之前注册:
import { registerDatabaseAdapter } from "./client";
registerDatabaseAdapter({
id: "my-company-postgres",
dialect: "postgres",
runtime: "my-company-postgres",
canHandle: ({ config }) => Boolean(config.database.url),
create: ({ config }) => ({
adapter: "my-company-postgres",
dialect: "postgres",
runtime: "my-company-postgres",
db: createMyDrizzlePostgresClient(config.database.url),
}),
missingPackageHint: "Set DATABASE_URL to use my-company-postgres.",
});canHandle 返回适配器能否在当前环境运行。create 返回 Drizzle 数据库对象。missingPackageHint 可选,canHandle 返回 false 时会附加在错误信息后面。
选择它
DATABASE_DIALECT=postgres
DATABASE_ADAPTER=my-company-postgres
DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/postgresDATABASE_DIALECT 必须与适配器的 dialect 一致,迁移才会使用正确的迁移链。
迁移
pnpm db:migrate适配器注册与解析入口在 adapter-registry.ts:registerDatabaseAdapter、listDatabaseAdapters 和 resolveDatabaseAdapter。
验证
- 选择该适配器后应用可以启动,
/admin能正常加载。 pnpm validate:db-adapters通过。
常见问题
出现 DATABASE_ADAPTER="…" is not registered.
适配器在首次访问数据库之后才注册,或没有注册。错误信息会列出已注册的 id。把注册提前。
出现 Database adapter "…" cannot run in this environment.
canHandle 返回了 false,例如 DATABASE_URL 为空。消息末尾附有你的 missingPackageHint。
出现 Database adapter "…" is already registered
已有同 id 的适配器。换一个 id。
参考
- 运行时与数据库适配器
- 环境变量
- Drizzle ORM:
create返回的客户端 - Drizzle 迁移:为什么方言决定迁移链