---
title: "@playstack/prisma-runtime"
description: "Explicit runtime selection for application-owned generated Prisma clients."
tags: ["package","foundation","prisma","adapter","free"]
---

{/* package-access:start */}

> **Free.** MIT licensed. Check preview availability before installing. See [package access](/docs/packages#access-policy).

{/* package-access:end */}

`@playstack/prisma-runtime` selects the correct application-owned generated Prisma client for the current deployment runtime without wrapping Prisma.

## Install

```sh
npm install @playstack/core @playstack/prisma-runtime
```

Install the generated Prisma clients and database adapters required by your application separately.

## Compose runtime-specific clients

```ts
import { resolvePrismaClient, type PrismaRuntime } from '@playstack/prisma-runtime'
import { PrismaClient as NodePrismaClient } from '../generated/node/client'
import { PrismaClient as EdgePrismaClient } from '../generated/edge/client'

export function createDatabase(runtime: PrismaRuntime) {
  return resolvePrismaClient({
    runtime,
    node: () => new NodePrismaClient(),
    serverless: () => new EdgePrismaClient({ adapter: neonAdapter }),
    test: () => createEphemeralTestClient(),
  })
}

export const prisma = createDatabase(resolveApplicationRuntime())
```

Pass the selected native client directly to Prisma-backed package adapters:

```ts
const eventStore = createPrismaEventStore({ prisma })
const rateLimits = createPrismaRateLimitStore({ prisma })
```

## Configuration reference

| `ResolvePrismaClientOptions` property | Type | Required | Purpose |
| --- | --- | --- | --- |
| `runtime` | `edge \| node \| test \| worker` | Yes | Explicit runtime selected by the application. |
| `node` | `() => TClient` | For `node` | Creates the pooled standard client. |
| `serverless` | `() => TClient` | For `edge` and `worker` | Creates the HTTP or serverless-adapter client. |
| `test` | `() => TClient` | For `test` | Creates an isolated test client. |

The function returns `TClient` unchanged. A missing factory fails with `PrismaRuntimeError('invalid_config')`; a factory failure is wrapped as `client_creation_failed` with its original cause.

## Adapter boundary

This package defines no custom client bridge. The generic return type preserves the exact generated Prisma client, including extensions, transaction types, and native methods. Each `@playstack/*/prisma` adapter declares the smaller structural surface it consumes.

## Node PrismaPg dispatch fence

The optional `@playstack/prisma-runtime/prisma-pg` export `fencePrismaPgFactory`
fences transaction dispatch/closure for exact matching Prisma/client/adapter-pg
versions, independently of the portable root selector:

| Exact version | Qualified engine | Shutdown contract |
| --- | --- | --- |
| 6.19.3, 6.19.0 | Rust `library` | Stop admission, drain complete operations, await factory disposal, then disconnect. |
| 7.9.0, 7.9.1, 7.10.0 | `client` | Closure/late-dispatch fence with explicit factory disposal. |

Ranges, mismatched versions, other drivers, Workers/edge and migration/shadow
databases are outside this contract. Verify actual installed versions and generated
engine; configuration values are host attestations, not automatic discovery.
Use one factory and exclusively owned pool per generated-client lifetime. Do not
retain unwrapped driver/transaction references or bypass closure with raw SQL.

Commit drains admitted work; rollback cancels queued work and waits for started
work. Unknown closure or lease-release outcomes quarantine admission. An exception
does not authorize replay or another provider send. Reconcile the original durable
identity instead of retrying every connection/commit failure.

For Prisma 6, attest `engineType: 'library'`,
`shutdownPolicy: 'drain-before-disconnect'` and `poolOwnership: 'exclusive'`.
`$disconnect()` is not cancellation and can hide disposal failure: the explicit
`factory.dispose()` result is authoritative. Supervise an owner whose disposal
fails; do not reopen its pool. Restart requires a fresh client/factory.

The 7.9.1 lane has native and packed ESM/CJS PostgreSQL qualification, including
lost commit acknowledgment and process termination. That does not establish an
unfenced defect on 7.9.1 from a warning observed on 7.10.0, or certify a consumer's
deployment. The fence supplies no tenant policy, outbox or automatic retries.

## Lifecycle ownership

The application resolves runtime configuration, memoizes clients where appropriate, owns connection pools, registers shutdown, generates schemas and clients, and manages migrations. The package reads no globals or environment variables and never calls `$disconnect`.

{/* package-reference:start */}

## API entry points and requirements

Reference snapshot: `@playstack/prisma-runtime@0.1.0-beta.1`. Import only the entry point your runtime needs. Paths below are relative to the installed package; use **Go to Definition** in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

| Public entry point | Declaration file |
| --- | --- |
| `@playstack/prisma-runtime` | `./dist/index.d.ts` |
| `@playstack/prisma-runtime/prisma-pg` | `./dist/prisma-pg.d.ts` |
| `@playstack/prisma-runtime/errors` | `./dist/errors.d.ts` |
| `@playstack/prisma-runtime/package.json` | No TypeScript declaration (asset or metadata export). |

Node.js engine requirement: `>=20`. This is not a claim that every entry point works in browsers or Workers.

### Peer dependencies

This package declares no peer dependencies. Its ordinary dependencies are resolved by the package manager.

For a complete first program, start with [Getting started](/docs/getting-started). For API lookup and partial-example conventions, see [Reading the reference](/docs/packages#reading-the-reference). Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.

{/* package-reference:end */}