On this page
  1. Install
  2. Compose runtime-specific clients
  3. Configuration reference
  4. Adapter boundary
  5. Node PrismaPg dispatch fence
  6. Qualification and maintainer checks
  7. Lifecycle ownership
  8. API entry points and requirements
  9. Peer dependencies

This guide describes upcoming source contracts, not a publication receipt. Check release availability and keep your complete Playstack graph on one verified version.

@playstack/prisma-runtime

Explicit runtime selection for application-owned generated Prisma clients.

Reference: @playstack/prisma-runtime@0.1.0-beta.5 · TypeScript · MIT licence

Free. MIT licensed. Check preview availability before installing. See package access.

@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 propertyTypeRequiredPurpose
runtimeedge | node | test | workerYesExplicit runtime selected by the application.
node() => TClientFor nodeCreates the pooled standard client.
serverless() => TClientFor edge and workerCreates the HTTP or serverless-adapter client.
test() => TClientFor testCreates 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 versionQualified engineShutdown contract
6.19.3, 6.19.0Rust libraryStop admission, drain complete operations, await factory disposal, then disconnect.
7.9.0, 7.9.1, 7.10.0, 7.10.1clientClosure/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.

Qualification and maintainer checks

The exact version/engine lanes above are independent qualification targets. The maintainer command npm run test:prisma:matrix:postgres in a Playstack checkout runs native disposable PostgreSQL checks; append -- --packed for frozen ESM/ CommonJS consumers or -- --version=6.19.3 to select that exact lane. Set PLAYSTACK_TEST_POSTGRES_BIN when the owned harness needs an explicit binary. The runner and its repository scripts are not installed package APIs.

Checks cover delayed-dispatch rollback, commits/savepoints, lost commit acknowledgment, startup/disposal and supervised quarantine. The retained unfenced comparison is a negative control, not another supported worker configuration. These checks do not certify a consumer's generated client, pool ownership, shutdown supervision, database grants or deployed provider effects. Qualify that complete composition before worker activation; no local pass authorizes forced connection release or replay after unknown closure.

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.

The exact 7.10.1 client/adapter pair also has native and packed ESM/CommonJS PostgreSQL 18 fence and Delivery qualification, with strict types and an offline frozen reinstall. It preserves delayed-write rollback, connection closure, quarantine, shutdown and original dispatch authority. This does not extend the separate transaction-abort classifier beyond its documented 7.9.1 profile or qualify every Prisma patch. Publish and pin the refreshed runtime artifact before adopting this addition; a beta.4 version label alone does not identify its bytes.

API entry points and requirements

Reference snapshot: @playstack/prisma-runtime@0.1.0-beta.5. 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 pointDeclaration file
@playstack/prisma-runtime./dist/index.d.ts
@playstack/prisma-runtime/prisma-pg./dist/prisma-pg.d.ts
@playstack/prisma-runtime/transaction-aborts./dist/transaction-aborts.d.ts
@playstack/prisma-runtime/errors./dist/errors.d.ts
@playstack/prisma-runtime/package.jsonNo 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. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.

Go

Playstack Pro tag
OriginsPricingBlogChangelogStatus

© 2026 Playstack. All rights reserved.

With OSS

By

Commune Software