Skip to main content

Serverless driver

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.

Installation​

Install the serverless driver via npm:

npm install @prisma/ppg

Usage​

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 reference​

ppg​

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;

The returned Sql object:

  • 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).
  • Returns the data as an array of objects mirroring the structure of your Prisma models.
  • Provides a query function which:
    • 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​

The ppg function accepts the following arguments:

NameTypeRequiredDescription
connectionStringstringYesThe connection string for your Prisma Postgres instance.
deserializeDeserializeNoCustom deserializer function which takes a column type OID and a raw value and returns a mapped value. It's type is defined as 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​

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>;
}

The query function it exposes:

  • 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​