数据库

编写自定义数据库适配器

为 Postgres 或 SQLite schema 家族注册自己的连接方式,并用 DATABASE_ADAPTER 选择它。

数据库连接通过适配器注册表解析。内置适配器有 sqlite、postgres、turso 和 d1;你可以注册自己的适配器,例如使用公司内部的 Postgres 驱动或连接池。

准备工作

  • 面向已有 schema 家族(postgres 或 sqlite)的 Drizzle 兼容数据库客户端。
  • 服务端代码中一个在首次访问数据库之前执行的位置。

同一 schema,不同连接

适配器只改变应用的连接方式。全新的 SQL 方言(例如 MySQL)还需要自己的 schema 文件、迁移链和仓储分支。

注册适配器

调用 registerDatabaseAdapter

在第一次调用 getDatabase() 之前注册:

src/server/db/my-company-postgres.ts
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 时会附加在错误信息后面。

选择它

.env
DATABASE_DIALECT=postgres
DATABASE_ADAPTER=my-company-postgres
DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/postgres

DATABASE_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。

参考

下一步