跳至主要内容

Turso

本指南讨论了使用 Prisma ORM 和 Turso 背后的概念，解释了 Turso 与其他数据库提供商之间的共性和差异，并引导您完成将应用程序与 Turso 集成的配置过程。

Prisma ORM 对 Turso 的支持目前处于 抢先体验 阶段。我们感谢您在此 GitHub 讨论 中提供反馈。

什么是 Turso？​

Turso's logo

Turso 是一个基于 libSQL 的边缘托管分布式数据库，libSQL 是 SQLite 的开源和开放贡献分支，使您能够将数据更靠近应用程序并最大限度地减少查询延迟。Turso 也可以托管在远程服务器上。

警告

从 Prisma ORM 版本 5.4.2 及更高版本开始，对 Turso 的支持已在 抢先体验 中提供。

与其他数据库提供商的共性​

libSQL 与 SQLite 100% 兼容。libSQL 扩展了 SQLite，并添加了以下功能和特性

  • 支持复制
  • 支持自动备份
  • 能够将 Turso 嵌入到其他程序中，例如 Linux 内核
  • 支持用户定义函数
  • 支持异步 I/O

要了解有关 libSQL 与 SQLite 的区别以及它与 SQLite 的区别，请参见 libSQL 宣言.

使用 Prisma ORM 与 Turso 的许多方面与使用 Prisma ORM 与任何其他关系型数据库一样。您仍然可以

需要考虑的差异​

Turso 与 SQLite 之间存在一些需要考虑的差异。在决定使用 Turso 和 Prisma ORM 时，您应该注意以下事项

  • **远程和嵌入式 SQLite 数据库**。libSQL 使用 HTTP 连接到远程 SQLite 数据库。libSQL 还支持远程数据库副本和嵌入式副本。嵌入式副本使您能够在应用程序中复制主数据库。
  • **进行模式更改**。由于 libSQL 使用 HTTP 连接到远程数据库，因此它与 Prisma Migrate 不兼容。但是，您可以使用 prisma migrate diff 创建模式迁移，然后使用 Turso 的 CLI 将更改应用于您的数据库。

如何连接和查询 Turso 数据库​

后续部分介绍了如何创建 Turso 数据库、检索您的数据库凭据以及连接到您的数据库。

如何配置数据库并检索数据库凭据​

信息

确保您已安装 Turso CLI 来管理您的数据库。

如果您没有现有的数据库，可以通过运行以下命令配置数据库

turso db create turso-prisma-db

以上命令将在最靠近您的位置的区域创建数据库。

运行以下命令来检索您的数据库的连接字符串

turso db show turso-prisma-db

接下来，创建一个身份验证令牌，它将允许您连接到数据库

turso db tokens create turso-prisma-db

使用身份验证令牌和连接字符串更新您的 .env 文件

.env
TURSO_AUTH_TOKEN="eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
TURSO_DATABASE_URL="libsql://turso-prisma-db-user.turso.io"

如何连接到 Turso 数据库​

要开始使用，请启用 driverAdapters 预览功能标志

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"]
}

datasource db {
  provider = "sqlite"
  url      = "file:./dev.db"
}

生成 Prisma Client

npx prisma generate

安装 libSQL 数据库客户端和 Prisma ORM 针对 libSQL 的驱动程序适配器软件包

npm install @libsql/client @prisma/adapter-libsql

更新您的 Prisma Client 实例

import { PrismaClient } from '@prisma/client'
import { PrismaLibSQL } from '@prisma/adapter-libsql'
import { createClient } from '@libsql/client'

const libsql = createClient({
  url: `${process.env.TURSO_DATABASE_URL}`,
  authToken: `${process.env.TURSO_AUTH_TOKEN}`,
})

const adapter = new PrismaLibSQL(libsql)
const prisma = new PrismaClient({ adapter })

您可以在项目中像往常一样使用 Prisma Client，并享受完全的类型安全性。

如何管理模式更改​

在使用 Turso 时，目前不支持 Prisma Migrate 和内省工作流程。这是因为 Turso 使用 HTTP 连接到您的数据库，而 Prisma Migrate 不支持 HTTP 连接。

要更新您的数据库模式

  1. 使用 prisma migrate dev 针对本地 SQLite 数据库生成迁移文件

    npx prisma migrate dev --name init

  2. 使用 Turso 的 CLI 应用迁移

    turso db shell turso-prisma-db < ./prisma/migrations/20230922132717_init/migration.sql
    信息

    将 20230922132717_init 替换为您的迁移的名称。

对于后续迁移，重复上述步骤以将更改应用于您的数据库。此工作流程不支持跟踪应用到您的远程数据库的迁移历史记录。

嵌入式 Turso 数据库副本​

Turso 支持 嵌入式副本。Turso 的嵌入式副本使您能够在应用程序内部拥有主远程数据库的副本。嵌入式副本的行为类似于本地 SQLite 数据库。数据库查询更快，因为您的数据库位于应用程序内部。

嵌入式数据库副本的工作原理​

当您的应用程序最初与您的数据库建立连接时，主数据库将满足查询

Embedded Replica: First remote read

Turso 将 (1) 在您的应用程序中创建一个嵌入式副本，以及 (2) 将数据从您的主数据库复制到副本，以便它可以在本地使用

Embedded Replica: Remote DB Copy

嵌入式副本将满足随后的读取查询。libSQL 客户端提供了一个 sync() 方法，您可以调用它来确保嵌入式副本的数据保持最新。

Embedded Replica: Local DB reads

使用嵌入式副本，这种设置保证了应用程序的响应能力，因为数据可以随时在本地获取，并且访问速度更快。

就像您可能熟悉的只读副本设置一样，写操作会转发到主远程数据库并执行，然后再传播到所有嵌入式副本。

Embedded Replica: Write operation propagation

  1. 写操作传播会转发到数据库。
  2. 数据库会将 1 中的更新响应到服务器。
  3. 写操作会传播到数据库副本。

您的应用程序的数据需求将决定您应该多久同步一次远程数据库和嵌入式数据库副本之间的数据。例如，您可以使用中间件函数（例如 Express 和 Fastify）或 cron 作业来同步数据。

如何同步远程数据库和嵌入式副本之间的数据​

要开始使用 Prisma ORM 的嵌入式副本，请在您的应用程序中添加 libSQL 的 sync() 方法。以下示例展示了如何使用 Express 中间件同步数据。

import express from 'express'
const app = express()

// ... the rest of your application code
app.use(async (req, res, next) => {
  await libsql.sync()
  next()
})

app.listen(3000, () => console.log(`Server ready at https://127.0.0.1:3000`))