Skip to main content

无服务器驱动程序

Prisma Postgres 的无服务器驱动程序是一个轻量级且精简的客户端库，可以使用原始 SQL 与 Prisma Postgres 通信。你可以通过 @prisma/ppg npm 包使用它。

¥The serverless driver for Prisma Postgres is a lightweight and minimal client library that can talk to Prisma Postgres using raw SQL. You can use it via the @prisma/ppg npm package.

警告

Prisma Postgres 无服务器驱动程序目前处于 抢先体验 状态，尚不推荐用于生产场景。

¥The Prisma Postgres serverless driver is currently in Early Access and not yet recommended for production scenarios.

安装​

¥Installation

通过 npm 安装无服务器驱动程序：

¥Install the serverless driver via npm:

npm install @prisma/ppg

用法​

¥Usage

对于大多数用户，推荐使用 ppg 函数，它返回一个以模板字面量标记函数形式实现的高级 SQL 客户端：

¥The recommended API for most users is the ppg function, which returns a high-level SQL client implemented as a template literal tag function:

import { ppg } from "@prisma/ppg";

type Post = {
  id: number;
  title: string;
  content: string | null;
  published: boolean;
  authorId: number | null;
}

const sql = ppg("prisma+postgres://accelerate.prisma-data.net/?api_key=...");

const authorId = 1;
const posts = await sql<Post>`SELECT * FROM "Post" WHERE "authorId" = ${authorId}`;

API 参考​

¥API reference

ppg​

ppg 函数返回一个以模板字面量标记函数实现的高级 SQL 客户端：

¥The ppg function returns a high-level SQL client implemented as a template literal tag function:

function ppg(connectionString: string, deserialize?: Deserialize): Sql;

interface Sql {
    <Record = unknown>(strings: TemplateStringsArray, ...values: unknown[]): Promise<Record[]>;
    /**

     * Executes a raw query defined as a string with placeholders and the list

     * of parameters.

     *      * ```ts

     * const [user] = await sql.query<User>("SELECT * FROM users WHERE id = $1", [id]);

     * ```
     */
    query<Record>(query: string, ...params: unknown[]): Promise<Record[]>;
}
type Deserialize = (value: unknown, oid: unknown) => unknown;

返回的 Sql 对象：

¥The returned Sql object:

  • 接受 SQL 语句作为模板字面量。如果其中包含任何插值，这些值将自动转换为 SQL 参数，以防止 SQL 注入攻击（请参阅下面的示例）。

    ¥Accepts a SQL statement as a template literal. If this contains any interpolated values, these are automatically converted to SQL parameters in order to prevent SQL injection attacks (see below for an example).

  • 以对象数组的形式返回数据，该数组镜像 Prisma 模型的结构。

    ¥Returns the data as an array of objects mirroring the structure of your Prisma models.

  • 提供一个 query 函数，该函数可以：

    ¥Provides a query function which:

    • 分别接受原始字符串和参数列表，允许你自行控制 SQL 参数，或在需要时以不安全的方式连接查询。

      ¥Takes a raw string and a list of params separately, allowing you to control the SQL parameters yourself or concatenate the query unsafely if needed.

    • 返回列类型和原始数据，而不将行转换为对象数组。

      ¥Returns column types and raw data without converting the rows into an array of objects.

参数​

¥Arguments

ppg 函数接受以下参数：

¥The ppg function accepts the following arguments:

名称类型必需的描述
connectionStringstring是的Prisma Postgres 实例的连接字符串。
deserializeDeserialize不自定义反序列化器函数，该函数接受列类型 OID 和原始值并返回映射值。它的类型定义为 type Deserialize = (value: unknown, oid: unknown) => unknown

用法​

¥Usage

import { ppg } from "@prisma/ppg";

type Post = {
  id: number;
  title: string;
  content: string | null;
  published: boolean;
  authorId: number | null;
}

type User = {
  id: number;
  email: string
}

const sql = ppg("prisma+postgres://accelerate.prisma-data.net/?api_key=...");

const posts: Post[] = await sql<Post>`SELECT * FROM "Post"`

const userId = 42;
const user: User[] = await sql<User>`SELECT * FROM "User" WHERE "id" = ${userId}`

Client​

Client 类提供更多底层控制，应谨慎使用：

¥The Client class provides more low-level control and should be used with more care:

class Client implements Queryable {
    constructor(options: ClientOptions);

    /**

     * Executes a query against the Prisma Postgres database.
     */
    query(query: string, parameters: unknown[]): Promise<QueryResponse>;
}

它公开的 query 函数：

¥The query function it exposes:

  • 分别接受原始字符串和参数列表，允许你自行控制 SQL 参数，或在需要时以不安全的方式连接查询。

    ¥Takes a raw string and a list of params separately, allowing you to control the SQL parameters yourself or concatenate the query unsafely if needed.

  • 返回列类型和原始数据，而不将行转换为对象数组。

    ¥Returns column types and raw data without converting the rows into an array of objects.

用法​

¥Usage

import { Client } from "@prisma/ppg";

const client = new Client({
  connectionString: "prisma+postgres://accelerate.prisma-data.net/?api_key=...",
});

const posts = await client.query('SELECT * FROM "Post" WHERE "authorId" = $1', [1]);

此查询返回以下结构的对象：

¥This query returns an object of this structure:

{
  columns: [
    { name: 'id', oid: 23 },
    { name: 'title', oid: 25 },
    { name: 'content', oid: 25 },
    { name: 'published', oid: 16 },
    { name: 'authorId', oid: 23 }
  ],
  rows: [ [ 1, 'Hello World', 'This is the content of the post', true, 1 ] ]
}

局限性​

¥Limitations