使用 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 令牌说明。
连接数据库
设置连接
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。另外再做两项检查:
- 去掉
DATABASE_AUTH_TOKEN再启动。它会抛DATABASE_AUTH_TOKEN is required when DATABASE_ADAPTER=turso,不会打开本地文件。 - 在后台写入一条数据(比如发放一张许可证),然后用 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。