Prisma

Connect your Prisma application to PgBeam by updating the DATABASE_URL environment variable. No changes to your Prisma schema, queries, or application code are required.

Setup

DATABASE_URL="postgresql://user:pass@abc.aws.pgbeam.app:5432/mydb"

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

DATABASE_URL="postgresql://user:pass@abc.aws.pgbeam.app:5432/mydb?connection_limit=5"

const users = await prisma.user.findMany();

Connection pool sizing

By default, Prisma creates a pool of num_cpus * 2 + 1 connections. Since PgBeam manages upstream pooling, you should reduce this to avoid holding unnecessary upstream connections:

Prisma Migrate

Set a separate environment variable for migrations or override inline:

DATABASE_URL="postgresql://user:pass@db.example.com:5432/mydb" npx prisma migrate deploy

This applies to both prisma migrate deploy (production) and prisma migrate dev (development).

Caching with Prisma

Prisma Client queries (recommended)

For standard Prisma Client queries (findMany, findUnique, etc.), PgBeam automatically tracks the generated SQL shapes. Enable caching for these shapes through Cache Rules in the dashboard — no code changes needed.

Raw queries with annotations

For Prisma raw queries, you can use inline SQL annotations for fine-grained cache control:

// Cache for 5 minutes
const products = await prisma.$queryRaw`
  /* @pgbeam:cache maxAge=300 */ SELECT * FROM products WHERE category = ${category}
`;

// Disable caching for a specific query
const balance = await prisma.$queryRaw`
  /* @pgbeam:cache noCache */ SELECT balance FROM accounts WHERE id = ${accountId}
`;

Read replicas with Prisma

Route read queries to replicas using the /* @pgbeam:replica */ annotation in raw queries:

// Route to a read replica
const products = await prisma.$queryRaw`
  /* @pgbeam:replica */ SELECT * FROM products WHERE active = true
`;

// Combine replica routing with caching
const categories = await prisma.$queryRaw`
  /* @pgbeam:replica */ /* @pgbeam:cache maxAge=600 */ SELECT * FROM categories
`;

Standard Prisma Client queries (findMany, etc.) always go to the primary database. To use replica routing, use raw queries with the annotation.

See Read Replicas for details on replica setup and routing behavior.

Debugging

Enable PgBeam debug output to verify caching and routing behavior from within Prisma:

await prisma.$executeRaw`SET pgbeam.debug = on`;

const result = await prisma.$queryRaw`SELECT * FROM users WHERE id = ${userId}`;
// Check server logs for: NOTICE: pgbeam: cache=hit age=12s ttl=60s swr=30s

Common issues

Further reading

• Connection Pooling — Pool modes and sizing guidance
• Caching — How PgBeam caching works, TTL, and SWR
• Read Replicas — Replica setup and routing