数据库

使用 Turso

通过 SQLite schema 分支和 turso 适配器,在 Turso libSQL 数据库上运行应用。

Turso 提供的 libSQL 兼容 SQLite。应用仍然使用 SQLite 的 schema 和 SQLite 的迁移链,只更换客户端。DATABASE_DIALECT 保持 sqlite,另外设置 DATABASE_ADAPTER=turso。

准备工作

  • 一个 Turso 数据库,拿到它的地址和令牌:turso db show --url <name> 和 turso db tokens create <name>。
  • @libsql/client,项目已经把它列为依赖。数据库层用 require.resolve 探测它,只有选了 turso 适配器才加载,所以 SQLite 或 Postgres 部署不会加载它。
  • 后台不用配任何东西。数据库连接是少数几个仍然留在环境变量里的设置之一。见配置模型。

在 Turso 创建数据库

按 Turso CLI 文档安装并登录 CLI,然后执行 turso db create <数据库名>。从 turso db show --url <数据库名> 复制 libsql:// 地址,再用 turso db tokens create <数据库名> 创建应用令牌。将这两个值分别填入下面的 DATABASE_URL 和 DATABASE_AUTH_TOKEN。CLI 的登录凭据不是应用数据库令牌。令牌只在服务端保存,部署环境也要设置同样两个值。见 Turso 令牌说明。

连接数据库

设置连接

.env
DATABASE_DIALECT=sqlite
DATABASE_ADAPTER=turso
DATABASE_URL=libsql://YOUR-DATABASE.turso.io
DATABASE_AUTH_TOKEN=YOUR-TURSO-TOKEN

两个值缺任何一个,适配器都会在启动时报错。它不会退回本地文件,所以配错的部署不会写入错误的数据库。

构建 schema

pnpm db:migrate

它应用的是 drizzle/migrations/sqlite,和本地 SQLite 文件、Cloudflare D1 用的是同一条链。Turso 不需要单独的迁移。

创建管理员

SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<password>' pnpm db:bootstrap-super-admin

它同时写入角色、权限和默认限流规则。可以重复执行。它只补充缺失的数据,不覆盖运营修改过的内容。

适配器如何选择

DATABASE_DIALECT=sqlite 选择 SQLite schema 与迁移链,DATABASE_ADAPTER=turso 选择 libSQL 客户端。缺少 libsql:// 地址、令牌或 @libsql/client 依赖时,适配器会在启动时报错。启动字段见环境变量。

内置的 sqlite、postgres、d1 和 turso 适配器与自定义适配器一样,通过 registerDatabaseAdapter 注册。

验证

pnpm validate:db-adapters

然后启动应用,用管理员登录并打开 /admin。另外再做两项检查:

  1. 去掉 DATABASE_AUTH_TOKEN 再启动。它会抛 DATABASE_AUTH_TOKEN is required when DATABASE_ADAPTER=turso,不会打开本地文件。
  2. 在后台写入一条数据(比如发放一张许可证),然后用 Turso CLI 读这一行。CLI 读到的就是应用写入的那一行。

故障排查

DATABASE_AUTH_TOKEN is required when DATABASE_ADAPTER=turso

用 turso db tokens create <name> 创建令牌并设置它。

DATABASE_URL is required when DATABASE_ADAPTER=turso

把 DATABASE_URL 设为 turso db show --url <name> 给出的 libsql:// 地址。

适配器根本没被选中

canHandle 还要求 @libsql/client 能被解析到。刚克隆完的仓库先运行 pnpm install。

参考

下一步