Turso
本指南討論使用 Prisma ORM 和 Turso 背後的概念，解釋 Turso 與其他資料庫供應商之間的共同點和差異，並引導您完成設定應用程式以與 Turso 整合的過程。
Prisma ORM 對 Turso 的支援目前處於Early Access階段。我們感謝您在這個GitHub 討論中提供您的意見回饋。
什麼是 Turso？
Turso 是一個邊緣託管的分散式資料庫，它基於 libSQL，這是 SQLite 的開源和開放貢獻分支，使您能夠將資料更靠近您的應用程式並最大限度地減少查詢延遲。Turso 也可以託管在遠端伺服器上。
從 Prisma ORM 5.4.2 及更高版本開始，Turso 的支援在 Early Access 中提供。
與其他資料庫供應商的共同點
libSQL 與 SQLite 100% 相容。libSQL 擴展了 SQLite 並添加了以下功能和特性
- 支援複製
- 支援自動備份
- 能夠將 Turso 作為其他程式（例如 Linux 核心）的一部分嵌入
- 支援使用者定義函數
- 支援非同步 I/O
要了解有關 libSQL 與 SQLite 之間差異的更多資訊，請參閱 libSQL 宣言。
將 Prisma ORM 與 Turso 一起使用的許多方面與將 Prisma ORM 與任何其他關聯式資料庫一起使用非常相似。您仍然可以
- 使用 Prisma Schema Language 建模您的資料庫
- 在您的 schema 中使用 Prisma ORM 現有的
sqlite資料庫連接器 - 在您的應用程式中使用 Prisma Client 來與 Turso 上的資料庫伺服器通訊
需要考慮的差異
Turso 和 SQLite 之間存在許多需要考慮的差異。當您決定使用 Turso 和 Prisma ORM 時，您應該注意以下事項
- 遠端和嵌入式 SQLite 資料庫。libSQL 使用 HTTP 連線到遠端 SQLite 資料庫。libSQL 也支援遠端資料庫副本和嵌入式副本。嵌入式副本使您能夠在應用程式內部複製您的主要資料庫。
- 進行 schema 變更。由於 libSQL 使用 HTTP 連線到遠端資料庫，這使其與 Prisma Migrate 不相容。但是，您可以使用
prisma migrate diff建立 schema 遷移，然後使用 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 檔案
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 資料庫用戶端和適用於 libSQL 套件的 Prisma ORM 驅動程式介面卡
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，並具有完整的類型安全。
如何管理 schema 變更
目前在使用 Turso 時，不支援 Prisma Migrate 和 Introspection 工作流程。這是因為 Turso 使用 HTTP 連線到您的資料庫，而 Prisma Migrate 不支援 HTTP 連線。
要更新您的資料庫 schema
-
針對本機 SQLite 資料庫使用
prisma migrate dev產生遷移檔案npx prisma migrate dev --name init -
使用 Turso 的 CLI 應用遷移
turso db shell turso-prisma-db < ./prisma/migrations/20230922132717_init/migration.sql資訊將
20230922132717_init替換為您的遷移名稱。
對於後續遷移，重複上述步驟以將變更應用於您的資料庫。此工作流程不支援追蹤應用於遠端資料庫的遷移歷史記錄。
嵌入式 Turso 資料庫副本
Turso 支援 嵌入式副本。Turso 的嵌入式副本使您能夠在您的應用程式內部擁有主要遠端資料庫的副本。嵌入式副本的行為類似於本機 SQLite 資料庫。資料庫查詢速度更快，因為您的資料庫位於您的應用程式內部。
嵌入式資料庫副本如何運作
當您的應用程式最初建立與資料庫的連線時，主要資料庫將滿足查詢
Turso 將 (1) 在您的應用程式內部建立嵌入式副本，並 (2) 將資料從您的主要資料庫複製到副本，以便在本地可用
嵌入式副本將滿足後續的讀取查詢。libSQL 用戶端提供了一個 sync() 方法，您可以調用該方法以確保嵌入式副本的資料保持新鮮。
使用嵌入式副本，此設定可保證應用程式的反應靈敏，因為資料將在本地隨時可用且更易於存取。
就像您可能熟悉的讀取副本設定一樣，寫入操作會轉發到主要遠端資料庫並在傳播到所有嵌入式副本之前執行。
- 寫入操作傳播會轉發到資料庫。
- 資料庫使用來自 1 的更新回應伺服器。
- 寫入操作會傳播到資料庫副本。
您的應用程式的資料需求將決定您應該多久同步一次遠端資料庫和嵌入式資料庫副本之間的資料。例如，您可以使用中介軟體函數（例如 Express 和 Fastify）或 cron job 來同步資料。
如何在您的遠端資料庫和嵌入式副本之間同步資料
要開始將嵌入式副本與 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`))
它也可以作為 Prisma Client 擴充功能 實作。下面的範例顯示在執行建立、更新或刪除操作後自動同步。
const prisma = new PrismaClient().$extends({
query: {
$allModels: {
async $allOperations({ operation, model, args, query }) {
const result = await query(args)
// Synchronize the embedded replica after any write operation
if (['create', 'update', 'delete'].includes(operation)) {
await libsql.sync()
}
return result
}
}
}
})