資料庫驅動程式

預設內建驅動程式

Prisma Client 的組件之一是 查詢引擎 (Query Engine)（以 Rust 實作）。查詢引擎負責將 Prisma Client 的查詢轉換為 SQL 語句。它透過內建驅動程式使用 TCP 連接到您的資料庫，無需額外設定。

注意

從 Prisma ORM 7 開始，查詢編譯器 (query compiler，即 client engine) 成為預設值，這意味著產生的 Prisma Client 不再包含基於 Rust 的查詢引擎二進位檔。這提供了更好的效能與開發者體驗。了解更多資訊請點擊此處。

在 Prisma ORM 7 中，預設的產生器 (generator) 設定為

generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
}

請注意，在使用查詢編譯器時必須使用 驅動程式轉接器 (driver adapters)。

您可以在我們的部落格上閱讀關於此變更的效能與開發體驗提升。

驅動程式轉接器

Prisma Client 可以使用 JavaScript 資料庫驅動程式，透過驅動程式轉接器來連接並對您的資料庫執行查詢。轉接器在 Prisma Client 與 JavaScript 資料庫驅動程式之間充當翻譯者的角色。

Prisma Client 會使用查詢引擎將 Prisma Client 查詢轉換為 SQL，並透過 JavaScript 資料庫驅動程式執行產生的 SQL 查詢。

驅動程式轉接器分為兩種類型：

• 資料庫驅動程式轉接器
• 無伺服器 (Serverless) 驅動程式轉接器

注意：驅動程式轉接器支援使用 Prisma ORM 的應用程式進行 邊緣部署 (edge deployments)。

資料庫驅動程式轉接器

您可以透過資料庫驅動程式轉接器，從 Prisma Client 使用基於 Node.js 的驅動程式連接到您的資料庫。Prisma 為以下驅動程式維護轉接器：

• PostgreSQL
  • pg
• Prisma Postgres
  • @prisma/adapter-ppg
• MySQL/MariaDB
  • mariadb
• SQLite
  • better-sqlite3
  • libSQL (Turso)
• MS SQL Server
  • node-mssql

無伺服器驅動程式轉接器

資料庫提供商（例如 Neon 和 PlanetScale）允許您使用 TCP 以外的其他協定（例如 HTTP 和 WebSockets）連接到資料庫。這些資料庫驅動程式針對無伺服器和邊緣環境中的資料庫連線進行了最佳化。

Prisma ORM 維護以下無伺服器驅動程式轉接器：

• Prisma Postgres
• Neon (以及 Vercel Postgres)
• PlanetScale
• Cloudflare D1

社群維護的資料庫驅動程式轉接器

您也可以為您使用的資料庫建立自己的驅動程式轉接器。以下是社群維護的驅動程式轉接器列表：

• TiDB Cloud Serverless Driver
• PGlite - Postgres in WASM

如何使用驅動程式轉接器

請參閱以下頁面，了解如何針對特定資料庫提供商使用特定的驅動程式轉接器。

• PostgreSQL
• Prisma Postgres
• MySQL/MariaDB
• MS SQL Server
• Neon
• PlanetScale
• Turso
• Cloudflare D1

關於使用驅動程式轉接器的注意事項

v6.6.0 中的新驅動程式轉接器 API

在 v6.6.0 中，我們引入了在使用驅動程式轉接器時初始化 Prisma Client 的簡化版本。您現在無需先建立驅動程式/用戶端的實例來傳遞給驅動程式轉接器，而是可以直接建立驅動程式轉接器（必要時可將驅動程式選項傳遞給它）。

以下是使用 @prisma/adapter-libsql 轉接器的範例：

6.6.0 之前

舊版本的 Prisma ORM 要求您先初始化驅動程式本身，然後使用該實例來建立 Prisma 驅動程式轉接器。以下是針對 LibSQL 使用 @libsql/client 驅動程式的範例：

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

// Old way of using driver adapters (before 6.6.0)
const driver = createClient({
  url: env.LIBSQL_DATABASE_URL,
  authToken: env.LIBSQL_DATABASE_TOKEN,
})
const adapter = new PrismaLibSQL(driver)

const prisma = new PrismaClient({ adapter })

6.6.0 及更高版本

從 6.6.0 版本開始，您可以直接使用您偏好的 JS 原生驅動程式選項來初始化驅動程式轉接器。

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

const adapter = new PrismaLibSQL({
  url: env.LIBSQL_DATABASE_URL,
  authToken: env.LIBSQL_DATABASE_TOKEN,
})

const prisma = new PrismaClient({ adapter })

驅動程式轉接器與資料庫連線設定

在 Prisma ORM 7 中，資料庫連線 URL 設定在 prisma.config.ts 中。然而，使用驅動程式轉接器時，連線字串需要在初始設定驅動程式轉接器時，於您的應用程式程式碼中提供。

以下是針對 pg 驅動程式和 @prisma/adapter-pg 轉接器的實作方式：

import 'dotenv/config'
import { PrismaClient } from '../generated/prisma/client'
import { PrismaPg } from '@prisma/adapter-pg'

const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
const prisma = new PrismaClient({ adapter })

請查看您所使用之驅動程式轉接器的文件以獲取具體的設定說明。

調整連線池大小、逾時或其他連線參數

請參閱 連線池指南，了解 Prisma ORM v7 驅動程式轉接器的預設值，以及它們如何從 Prisma ORM v6 URL 參數進行映射。

Prisma 逾時 (timeouts)

Prisma ORM 也有其可設定的逾時限制，這些限制獨立於資料庫驅動程式逾時。如果您看到逾時錯誤，但不確定它是來自驅動程式還是 Prisma Client，請參閱 Prisma Client 逾時與交易選項文件。

驅動程式轉接器與自訂輸出路徑

在 Prisma ORM 7 中，建議的做法是為 Prisma Client 使用自訂輸出路徑。預設輸出路徑為 ../generated/prisma。

假設您在 Prisma schema 中將 output 設定為 ../generated/prisma

generator client {
  provider = "prisma-client"
  output   = "../src/generated/client"
}

您可以從應用程式程式碼中使用相對路徑來參照 Prisma Client

import { PrismaClient } from '../generated/prisma/client'

const client = new PrismaClient()

或者，您可以使用連結相依性 (linked dependency) 以獲得更整潔的引入方式。

npm add db@./generated/prisma

pnpm add db@link:./generated/prisma

yarn add db@link:./generated/prisma

現在，您應該可以使用 db 來參照您產生的用戶端了！

import { PrismaClient } from 'db'

const client = new PrismaClient()

驅動程式轉接器與特定框架

Nuxt

使用驅動程式轉接器並結合 Nuxt 部署到邊緣函式環境無法直接開箱即用，但加入 nitro.experimental.wasm 設定選項即可解決。

export default defineNuxtConfig({
  // ...
  nitro: {
    // ...
    experimental: {
      wasm: true,
    },
  },
  // ...
})

驅動程式轉接器與 TypedSQL

TypedSQL 讓您可以編寫與 Prisma Client 直接整合且完全型別安全的 SQL 查詢。如果您既想擁有編寫 SQL 的靈活性，又想受益於 Prisma 的型別安全，這個功能非常實用。

您也可以將驅動程式轉接器與 TypedSQL 搭配使用，透過 JavaScript 資料庫驅動程式進行連線。TypedSQL 適用於所有支援的驅動程式轉接器，但 @prisma/adapter-better-sqlite3 除外。若要使用 SQLite 支援，請改用 @prisma/adapter-libsql。