数据库驱动程序

默认内置驱动程序

¥Default built-in drivers

Prisma 客户端的组件之一是 查询引擎。查询引擎负责将 Prisma Client 查询转换为 SQL 语句。它使用不需要额外设置的内置驱动程序通过 TCP 连接到你的数据库。

¥One of Prisma Client's components is the Query Engine. The Query Engine is responsible for transforming Prisma Client queries into SQL statements. It connects to your database via TCP using built-in drivers that don't require additional setup.

注意

从 v6.7.0 开始，Prisma ORM 具有 queryCompiler 预览功能。

¥As of v6.7.0, Prisma ORM has the queryCompiler Preview feature.

启用后，你的 Prisma 客户端将生成 无需基于 Rust 的查询引擎二进制文件：

¥When enabled, your Prisma Client will be generated without a Rust-based query engine binary:

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

请注意，驱动适配器 预览功能与 queryCompiler 功能同时启用。

¥Note that the driver adapters Preview feature is required alongside queryCompiler.

驱动适配器

¥Driver adapters

Prisma 客户端可以使用 JavaScript 数据库驱动程序（使用驱动程序适配器）连接数据库并运行查询。适配器充当 Prisma 客户端和 JavaScript 数据库驱动程序之间的转换器。

¥Prisma Client can connect and run queries against your database using JavaScript database drivers using driver adapters. Adapters act as translators between Prisma Client and the JavaScript database driver.

Prisma 客户端将使用查询引擎将 Prisma 客户端查询转换为 SQL，并通过 JavaScript 数据库驱动程序运行生成的 SQL 查询。

¥Prisma Client will use the Query Engine to transform the Prisma Client query to SQL and run the generated SQL queries via the JavaScript database driver.

有两种不同类型的驱动程序适配器：

¥There are two different types of driver adapters:

• 数据库驱动适配器

  ¥Database driver adapters

• 无服务器驱动程序适配器

  ¥Serverless driver adapters

注意：驱动程序适配器支持 边缘部署 个使用 Prisma ORM 的应用。

¥Note: Driver adapters enable edge deployments of applications that use Prisma ORM.

数据库驱动适配器

¥Database driver adapters

你可以使用数据库驱动程序适配器从 Prisma 客户端使用基于 Node.js 的驱动程序连接到数据库。Prisma 维护以下数据库驱动程序适配器：

¥You can connect to your database using a Node.js-based driver from Prisma Client using a database driver adapter. Prisma maintains the following database driver adapters:

• PostgreSQL

  • pg

• SQLite

  • better-sqlite3

  • libSQL(Turso)

• MSSQL

  • node-mssql

无服务器驱动程序适配器

¥Serverless driver adapters

数据库提供程序（例如 Neon 和 PlanetScale）允许你使用 TCP 之外的其他协议（例如 HTTP 和 WebSockets）连接到数据库。这些数据库驱动程序针对连接到无服务器和边缘环境中的数据库进行了优化。

¥Database providers, such as Neon and PlanetScale, allow you to connect to your database using other protocols besides TCP, such as HTTP and WebSockets. These database drivers are optimized for connecting to your database in serverless and edge environments.

Prisma ORM 维护以下无服务器驱动程序适配器：

¥Prisma ORM maintains the following serverless driver adapters:

• Neon（和 Vercel Postgres）

  ¥Neon (and Vercel Postgres)

• PlanetScale

• Cloudflare D1

社区维护的数据库驱动程序适配器

¥Community-maintained database driver adapters

你还可以为你正在使用的数据库构建自己的驱动程序适配器。以下是社区维护的驱动程序适配器列表：

¥You can also build your own driver adapter for the database you're using. The following is a list of community-maintained driver adapters:

• TiDB Cloud Serverless 驱动程序

  ¥TiDB Cloud Serverless Driver

• PGlite - WASM 中的 Postgres

  ¥PGlite - Postgres in WASM

如何使用驱动适配器

¥How to use driver adapters

要使用此功能：

¥To use this feature:

1. 更新架构中的 previewFeatures 块以包含 driverAdapters 预览功能：

   ¥Update the previewFeatures block in your schema to include the driverAdapters Preview feature:

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

2. 生成 Prisma 客户端：

   ¥Generate Prisma Client:

   npx prisma generate

3. 请参阅以下页面，了解有关如何将特定驱动程序适配器与特定数据库提供程序一起使用的更多信息：

   ¥Refer to the following pages to learn more about how to use the specific driver adapters with the specific database providers:

   • PostgreSQL

   • Neon

   • PlanetScale

   • Turso

   • Cloudflare D1

使用驱动适配器的注意事项

¥Notes about using driver adapters

v6.6.0 中的新驱动程序适配器 API

¥New driver adapters API in v6.6.0

在 v6.6.0 中，我们引入了一个简化版本，用于在使用驱动程序适配器时实例化 Prisma Client。现在你无需创建驱动程序/客户端实例来传递给驱动程序适配器，而是可以直接创建驱动程序适配器（并在需要时将驱动程序的选项传递给它）。

¥In v6.6.0, we introduced a simplified version for instantiating Prisma Client when using driver adapters. You now don't need to create an instance of the driver/client to pass to a driver adapter, instead you can just create the driver adapter directly (and pass the driver's options to it if needed).

以下是使用 @prisma/adapter-libsql 适配器的示例：

¥Here is an example using the @prisma/adapter-libsql adapter:

6.6.0 之前版本

¥Before 6.6.0

早期版本的 Prisma ORM 要求你首先实例化驱动程序本身，然后使用该实例创建 Prisma 驱动程序适配器。以下是使用 LibSQL 的 @libsql/client 驱动程序的示例：

¥Earlier versions of Prisma ORM required you to first instantiate the driver itself, and then use that instance to create the Prisma driver adapter. Here is an example using the @libsql/client driver for LibSQL:

import { createClient } from '@libsql/client'
import { PrismaLibSQL } from '@prisma/adapter-libsql'
import { PrismaClient } from '@prisma/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 and later

从 6.6.0 版本开始，你可以使用你首选的 JS 原生驱动程序的选项直接实例化驱动程序适配器。

¥As of the 6.6.0 release, you instantiate the driver adapter directly with the options of your preferred JS-native driver.:

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

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

const prisma = new PrismaClient({ adapter })

驱动程序适配器不会从 Prisma 架构中读取连接字符串

¥Driver adapters don't read the connection string from the Prisma schema

使用 Prisma ORM 的内置驱动程序时，将从 Prisma 架构中的 datasource 块的 url 字段读取连接字符串。

¥When using Prisma ORM's built-in drivers, the connection string is read from the url field of the datasource block in your Prisma schema.

另一方面，当使用驱动程序适配器时，在最初设置驱动程序适配器时，需要在应用代码中提供连接字符串。以下是对 pg 驱动程序和 @prisma/adapter-pg 适配器执行此操作的方法：

¥On the other hand, when using a driver adapter, the connection string needs to be provided in your application code when the driver adapter is set up initially. Here is how this is done for the pg driver and the @prisma/adapter-pg adapter:

import { PrismaClient } from '@prisma/client'
import { PrismaPg } from '@prisma/adapter-pg'

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

有关具体设置说明，请参阅你正在使用的驱动程序适配器的文档。

¥See the docs for the driver adapter you're using for concrete setup instructions.

驱动适配器和自定义输出路径

¥Driver adapters and custom output paths

从 Prisma 5.9.0 开始，当将驱动程序适配器预览功能与 Prisma 客户端的自定义输出路径 一起使用时，你无法使用相对路径引用 Prisma 客户端。

¥Since Prisma 5.9.0, when using the driver adapters Preview feature along with a custom output path for Prisma Client, you cannot reference Prisma Client using a relative path.

假设你的 Prisma 架构中的 output 设置为 ../src/generated/client：

¥Let's assume you had output in your Prisma schema set to ../src/generated/client:

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

你不应该做的是相对引用该路径：

¥What you should not do is reference that path relatively:

// what not to do!
import { PrismaClient } from './src/generated/client'

const client = new PrismaClient()

相反，你将需要使用链接的依赖。

¥Instead, you will need to use a linked dependency.

npm

npm add db@./src/generated/client

pnpm

pnpm add db@link:./src/generated/client

yarn

yarn add db@link:./src/generated/client

现在，你应该能够使用 db 引用生成的客户端！

¥Now, you should be able to reference your generated client using db!

import { PrismaClient } from 'db'

const client = new PrismaClient()

驱动程序适配器和特定框架

¥Driver adapters and specific frameworks

Nuxt

使用带有 Nuxt 的驱动程序适配器部署到边缘功能环境无法开箱即用，但添加 nitro.experimental.wasm 配置选项可以解决此问题：

¥Using a driver adapter with Nuxt to deploy to an edge function environment does not work out of the box, but adding the nitro.experimental.wasm configuration option fixes that:

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