Prisma FAQ & Answers

The recommended connection_limit for Prisma Client in AWS Lambda serverless functions is 1.

This recommendation exists because:

1. Connection multiplication: Each Lambda instance creates its own PrismaClient with its own connection pool. During traffic spikes, AWS Lambda spawns multiple instances, rapidly multiplying total database connections.

2. Idle connections: Paused Lambda functions keep connections open, blocking them from other instances.

3. Preventing exhaustion: Multiple concurrent functions with higher connection limits can quickly exhaust your database's maximum connection limit.

Configuration example:

// In your schema.prisma or connection URL
datasource db {
  provider = "postgresql"
  url      = "postgresql://user:password@host:5432/database?connection_limit=1"
}

Additional strategies:

• Set your AWS Lambda concurrency limit below your database's max connections
• Consider using an external connection pooler like PgBouncer or Prisma Accelerate
• Start with connection_limit=1 and optimize based on your specific needs

Sources:

• Database connections | Prisma Documentation
• Deploy your application using Prisma ORM to AWS Lambda | Prisma Documentation
• Connection pool | Prisma Documentation

Based on the official Prisma documentation, I have the authoritative answer:

Default Connection Pool Size Formula

num_physical_cpus * 2 + 1

Where num_physical_cpus is the number of physical CPU cores on the machine running your application.

When to Override

Override for Long-Running Processes:

• Recommended starting point: (num_physical_cpus * 2 + 1) ÷ number of application instances
• This distributes the connection pool across multiple instances

Override for Serverless/Short-Lived Functions:

• Start with connection_limit = 1 if not using an external connection pooler
• Serverless environments benefit from minimal connections per function instance

Override Based on Traffic:

• The default formula is a starting point, not a production recommendation
• Prisma cannot know your traffic patterns, application requirements, server capacity, or database limits
• You must tune based on actual load testing and monitoring

Configuration:

datasource db {
  provider = "postgresql"
  url      = "postgresql://user:password@localhost:5432/db?connection_limit=10&pool_timeout=20"
}

Important Note for Prisma ORM v7+:
Starting with v7, relational datasources use driver adapters by default. Connection pooling configuration now comes from the Node.js driver itself, not Prisma's internal pooling.

Sources:

• Connection pool | Prisma Documentation
• Database connections | Prisma Documentation

Based on the official Prisma documentation, here is the authoritative answer:

Transaction mode is the required PgBouncer pool mode for Prisma Client to work reliably.

Prisma Client requires transaction mode because it needs a dedicated connection for every transaction. Session mode and statement mode are not compatible with Prisma Client's architecture.

Key configuration requirements:

1. PgBouncer configuration: Set pool_mode = transaction in your pgbouncer.ini file

2. Connection string: Add the ?pgbouncer=true flag to your database URL:

   postgresql://user:password@host:6432/db?pgbouncer=true
   

   Note: This flag is not needed if using PgBouncer 1.21.0 or later

3. Prepared statements: Configure max_prepared_statements to a value greater than 0 in PgBouncer to enable prepared statement support

4. Migrations limitation: Prisma Migrate and introspection require a direct database connection (not through PgBouncer) because the Schema Engine doesn't support connection pooling

Sources:

• Configure Prisma Client with PgBouncer | Prisma Documentation

Based on the official Prisma documentation, the connection string parameter is:

pgbouncer=true

Add this parameter to your PostgreSQL connection URL:

postgresql://USER:PASSWORD@HOST:PORT/DATABASE?pgbouncer=true

Important notes:

• This parameter disables prepared statement caching, which is required for PgBouncer compatibility
• PgBouncer must run in Transaction mode for Prisma to work reliably
• For PgBouncer 1.21.0 or later, Prisma recommends NOT setting this parameter (the pooler handles it)
• You'll also need a directUrl in your Prisma schema for migrations and introspection, since these commands require direct database access

Sources:

• Configure Prisma Client with PgBouncer | Prisma Documentation

Based on the official Prisma documentation, I can provide you with the authoritative answer:

---

Prisma doesn't benefit from AWS RDS Proxy for connection pooling because Prisma uses prepared statements for all queries, which causes RDS Proxy to pin connections.

When RDS Proxy pins a connection:

• Each transaction uses the same underlying database connection until the session ends
• Other client connections cannot reuse that database connection until the session ends
• The session only ends when Prisma Client's connection is dropped

This connection pinning behavior completely negates the connection pooling benefits that RDS Proxy is designed to provide.

Why pinning occurs:

• Prepared statements (of any size) trigger connection pinning in RDS Proxy
• Query statements greater than 16 KB also trigger pinning
• Prisma sets search_path and names when creating connections, which further causes pinning

Result: There is no benefit in using RDS Proxy for connection pooling with Prisma ORM.

Sources:

• Caveats when deploying to AWS platforms | Prisma Documentation
• RDS Proxy connection considerations - Amazon RDS

Based on the official Prisma documentation search results, I can provide you with the authoritative answer:

Prisma interactive transactions have two timeout parameters:

1. maxWait - The maximum time Prisma Client will wait to acquire a transaction from the database

   • Default: 2000ms (2 seconds)

2. timeout - The maximum time the interactive transaction can run before being canceled and rolled back

   • Default: 5000ms (5 seconds)

These can be configured per-transaction or globally:

// Per-transaction configuration
await prisma.$transaction(
  async (tx) => {
    // transaction code
  },
  {
    maxWait: 5000,  // wait up to 5s to acquire transaction
    timeout: 10000, // allow transaction to run for up to 10s
  }
);

// Global configuration
const prisma = new PrismaClient({
  transactionOptions: {
    maxWait: 5000,
    timeout: 10000,
  },
});

Sources:

• Transactions and batch queries (Reference) | Prisma Documentation

The directUrl field provides a direct database connection that bypasses PgBouncer for Prisma CLI commands that require direct database access.

Why it's needed:

When using PgBouncer in the url field (for connection pooling in your application runtime), certain Prisma operations cannot work through the pooler:

• Prisma Migrate (prisma migrate dev, prisma migrate deploy) - Uses database transactions to check the current state of the database and migrations table, requiring a direct connection
• Schema operations (prisma db push, prisma db pull) - Need direct database access to modify/read schema

The Schema Engine is designed to use a single connection and doesn't support connection pooling.

Configuration example:

datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")        // PgBouncer pooled connection
  directUrl = env("DIRECT_DATABASE_URL") // Direct database connection
}

With this setup:

• Runtime queries (Prisma Client) → use url (PgBouncer pooled)
• CLI commands (migrations, schema ops) → use directUrl (direct connection)

Important: In Prisma ORM v7, the directUrl property was removed. With PgBouncer 1.22.0+ and Prisma Client 5.10.0+, the directUrl is no longer required due to improved support for prepared statements.

Sources:

• Configure Prisma Client with PgBouncer | Prisma Documentation

During a cold start, each Vercel serverless function creates a new instance of PrismaClient, which establishes its own connection pool to the database. This means:

New connections are opened - The function must establish fresh database connections, which is an expensive operation involving TLS termination and resource allocation at the database level. This significantly adds to cold start latency.

Connection pool per instance - Each function instance maintains its own separate connection pool, not shared across instances.

Connection exhaustion risk - During traffic spikes, hundreds of parallel functions can spawn simultaneously. If each opens multiple connections (default pool size), you can quickly exhaust your database's connection limit. For example, 200 concurrent functions with a default pool of 3 connections each = 600 connections, which can exceed typical PostgreSQL/MySQL limits.

Connection churn - Serverless functions that spin up and down create rapid open/close cycles of database connections, degrading performance.

Recommended configuration for serverless:

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
  relationMode = "prisma"
  // Set connection limit to 1 for serverless
  connection_limit = 1
}

Setting connection_limit = 1 is the recommended starting point for serverless environments to prevent connection exhaustion, though this value can be tuned based on your specific needs.

Sources:

• Database connections | Prisma Documentation
• Deploy to Vercel | Prisma Documentation
• Introduction to common serverless challenges - Prisma

Based on the authoritative search results from Prisma's official documentation, I can provide the verified answer:

What is Prisma Accelerate?

Prisma Accelerate is a fully managed global connection pool and caching layer for your existing database. It operates across 15+ global regions and is specifically designed to scale applications for serverless deployments.

How it Solves Serverless Connection Pooling Issues

The Core Problem: Serverless environments create ephemeral function instances that each attempt to open database connections. This leads to:

• Connection exhaustion during traffic spikes
• Connection timeouts during peak times
• Inability to reuse connections across function invocations

Prisma Accelerate's Solution:

1. Dynamic, Serverless Connection Pooling: Accelerate employs a dynamic connection pooling infrastructure that provisions connection pools on-demand in your assigned region when requests are made.

2. Centralized Connection Management: All Prisma queries are routed through Accelerate's connection pooler using a special Accelerate connection string with the withAccelerate() extension.

3. Automatic Traffic Scaling: The managed connection pool handles high volumes of connections and adapts to traffic spikes automatically, preventing connection exhaustion.

4. Global Distribution: With 15+ global regions, connections are pooled closer to your serverless functions, reducing latency.

Implementation: You enable Accelerate by using the withAccelerate() extension and an Accelerate connection string. This automatically routes all database queries through the connection pooler.

Sources:

• Prisma Accelerate | Prisma Documentation
• Prisma Accelerate: Connection Pooling | Prisma Documentation
• Getting started with Prisma Accelerate | Prisma Documentation

Based on the official Prisma documentation, to enable prepared statements in PgBouncer for use with Prisma, set:

max_prepared_statements=100 (or higher)

Any value greater than 0 enables prepared statements in PgBouncer. Setting it to 0 disables prepared statements entirely.

Important context:

• This feature requires PgBouncer 1.21.0 or later
• When max_prepared_statements > 0, you do NOT need the pgbouncer=true flag in your Prisma connection string
• PgBouncer must run in transaction mode for Prisma to work correctly
• Prisma automatically runs DEALLOCATE ALL before preparing statements to clean up the connection

For older PgBouncer versions (< 1.21.0):
You must set max_prepared_statements=0 and add ?pgbouncer=true to your Prisma connection string to disable prepared statements.

Sources:

• Configure Prisma Client with PgBouncer | Prisma Documentation
• Fully support prepared statements with pgbouncer 1.21.0 · Issue #21531 · prisma/prisma

Based on the official Prisma documentation search results, here's the authoritative answer:

Connection Limit Configuration

Without an external connection pooler:
Set connection_limit=1 as a starting point, then optimize from there. This is especially important in serverless environments to prevent connection exhaustion.

With an external connection pooler (like PgBouncer):
Use the default pool size which is (num_physical_cpus * 2) + 1 as a starting point, then tune as needed. The external pooler prevents traffic spikes from overwhelming the database, so you can safely use higher connection limits.

Configuration Examples

Without external pooler (serverless):

postgresql://user:password@host:5432/db?connection_limit=1

With external pooler:

postgresql://user:password@host:5432/db?pgbouncer=true

(Uses default connection_limit formula)

Or explicitly set:

postgresql://user:password@host:5432/db?pgbouncer=true&connection_limit=10

Key difference: External poolers handle connection management at a higher level, allowing each Prisma Client instance to maintain more connections safely without overwhelming the database.

Sources:

• Configure Prisma Client with PgBouncer | Prisma Documentation
• Connection pool | Prisma Documentation
• Configure Prisma Client with an external connection pooler

Based on the official Prisma documentation, the recommended approaches to prevent connection exhaustion in high-traffic serverless environments are:

1. Use Prisma Accelerate (Recommended)

Prisma Accelerate provides connection pooling as a managed service. It maintains a persistent connection pool between your serverless functions and the database, preventing connection exhaustion by reusing connections rather than creating new ones for each function invocation.

2. Use External Connection Pooler (PgBouncer)

For PostgreSQL, deploy an external connection pooler like PgBouncer. It sits between Prisma Client and the database, maintaining a limited pool of connections and queuing additional requests. This prevents each serverless function from opening its own connections.

3. Set Serverless Concurrency Limits

Configure your serverless platform's concurrency limit to be lower than your database's maximum connections divided by the connection pool size. Formula:

Max Concurrency = Database Max Connections / Connection Pool Size per Instance

4. Configure Connection Pool Size

Explicitly set a smaller connection_limit in your database URL to reduce connections per function instance:

postgresql://user:password@host:port/database?connection_limit=5

5. Use Prisma Postgres

Prisma Postgres includes built-in connection pooling optimized for serverless environments, eliminating the need for manual configuration.

The primary recommendation from Prisma is using Prisma Accelerate or an external connection pooler, combined with appropriate connection pool sizing and concurrency limits.

Sources:

• Deploy Prisma ORM apps to serverless function (FaaS) providers | Prisma Documentation
• Database connections | Prisma Documentation
• Connection pool | Prisma Documentation

Based on the search results from Prisma's official documentation:

Increase the pool_timeout parameter if Prisma is experiencing connection allocation delays.

Default value: 10 seconds

What it does: The pool_timeout defines the maximum number of seconds a query will wait in the queue for an available connection from the connection pool. If a connection cannot be allocated within this time, Prisma throws error code P2024.

When to increase it: When you have connection allocation delays due to high concurrent request volume exceeding your connection limit, causing queries to queue. Increasing pool_timeout gives the query engine more time to process queued queries before timing out.

Configuration example:

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

generator client {
  provider = "prisma-client-js"
  previewFeatures = ["pool_timeout=20"]
}

Or via connection string:

postgresql://user:password@localhost:5432/db?pool_timeout=20

Sources:

• Connection pool | Prisma Documentation
• Database connections | Prisma Documentation

Colocating your database close to serverless functions reduces cold start duration in Prisma because it minimizes the network latency during the TLS handshake and PostgreSQL connection establishment.

The Technical Reason:

During a cold start, Prisma Client must establish a new database connection, which involves:

1. TLS Handshake Round-Trips: Prisma enables TLS by default for security. The TLS handshake requires a round trip to and from your database, which is extremely fast when your database is in the same region as your function, but very slow if they are geographically separated.

2. PostgreSQL Connection Handshake: The PostgreSQL connection handshake involves 18 messages with approximately 5 round-trips necessary to complete the handshake.

3. Geographic Distance Impact: For example, a user in Tokyo connecting to a database in Virginia (us-east-1) experiences approximately 460ms just to establish a connection. Each database query can take about 300ms per round-trip due to trans-Pacific network latency, TLS handshakes, and DNS resolution.

The shorter the distance your request has to travel, the faster the connection will be established. When the serverless function and database are in different regions, this network latency is added directly to your cold start time.

Sources:

• Make Your Applications Fast Globally
• Best Practices To Speed Up Your Serverless Applications
• Introduction to common serverless challenges

Based on the official Prisma documentation, here are the key differences between Prisma Accelerate's connection pooling and PgBouncer:

Architecture & Management

Prisma Accelerate: Fully managed, globally distributed connection pooler that sits between Prisma Client and your database. No infrastructure management required.

PgBouncer: Self-managed external connection pooler that you deploy and maintain yourself. You're responsible for uptime, recovery, and configuration.

Location & Performance

Prisma Accelerate: Globally distributed across multiple regions. Automatically routes connections to the nearest geographic location, reducing cross-region latency for global applications.

PgBouncer: Typically deployed in a single region. Cross-region TCP handshakes between application servers and PgBouncer can be costly and time-consuming, reducing the efficiency of connection reuse.

Scaling

Prisma Accelerate: Automatically scales up and down based on workload. You never run out of compute resources.

PgBouncer: Manual scaling required. You must provision and configure capacity yourself.

Reliability

Prisma Accelerate: Automatic failover and recovery. Infrastructure issues are handled transparently without interruption.

PgBouncer: You manage redundancy and recovery. If PgBouncer fails, you're responsible for bringing it back online.

Configuration Requirements

Prisma Accelerate: Works out of the box with both Prisma Client and migrations.

PgBouncer: Must run in Transaction mode for Prisma Client. Does not support Prisma migrations (Schema Engine requires direct database connections).

Additional Features

Prisma Accelerate: Includes query-level caching in addition to connection pooling.

PgBouncer: Connection pooling only.

Sources:

• Comparing Prisma Accelerate to other connection pooling options | Prisma Documentation
• Configure Prisma Client with PgBouncer | Prisma Documentation

Based on the authoritative Prisma documentation, the error code returned when a transaction fails due to a deadlock is:

P2034

The full error message is: "Transaction failed due to a write conflict or a deadlock. Please retry your transaction"

This error occurs when:

• Two or more transactions run concurrently
• Timing issues cause write conflicts or deadlocks
• Unique constraints are violated during concurrent operations

The error is returned as a PrismaClientKnownRequestError with error.code === 'P2034', allowing you to programmatically catch and retry failed transactions.

Sources:

• Errors | Prisma Documentation
• Transactions and batch queries (Reference) | Prisma Documentation

Based on the official Prisma documentation, Prisma Client supports three types of transactions, not four:

1. Sequential operations transactions - Execute an array of Prisma Client operations sequentially within a transaction using $transaction([operation1, operation2, ...])

2. Interactive transactions - Execute a function containing custom logic and multiple Prisma Client queries using $transaction(async (tx) => { ... })

3. Nested writes - Perform operations on multiple related records in a single Prisma Client query (e.g., creating a user and their posts in one operation)

There is no fourth type of transaction in the current Prisma Client documentation. The three types above are the officially supported transaction mechanisms.

Sources:

• Transactions and batch queries (Reference) | Prisma Documentation
• Learn How Prisma Supports Database Transactions | Prisma

Based on the authoritative sources found, here's the answer:

Read Committed is the default transaction isolation level in PostgreSQL when using Prisma.

This is PostgreSQL's default isolation level, and Prisma inherits this default behavior. PostgreSQL supports four isolation levels defined by the SQL standard: Read Uncommitted, Read Committed, Repeatable Read, and Serializable. When you don't specify an isolation level, PostgreSQL (and therefore Prisma) uses Read Committed.

Starting with Prisma ORM version 4.4.0, you can override this default on a per-transaction basis by specifying a custom isolation level:

await prisma.$transaction(
  async (tx) => {
    // your transaction operations
  },
  {
    isolationLevel: 'RepeatableRead' // or 'Serializable'
  }
)

Sources:

• Transactions and batch queries - Prisma Documentation
• PostgreSQL Documentation: Transaction Isolation

Based on the official Prisma documentation, you set the transaction isolation level to Serializable in an interactive transaction using the isolationLevel option in the second parameter of $transaction:

await prisma.$transaction(
  async (prisma) => {
    // Your transaction code here
  },
  {
    isolationLevel: Prisma.TransactionIsolationLevel.Serializable
  }
)

Key details:

• The isolationLevel is passed as an option in the second parameter object
• Use the enum value Prisma.TransactionIsolationLevel.Serializable
• Available from Prisma version 4.2.0+
• Not available on MongoDB (no isolation level support)
• CockroachDB and SQLite only support Serializable isolation level

Complete example with all options:

await prisma.$transaction(
  async (prisma) => {
    // Transaction operations
  },
  {
    isolationLevel: Prisma.TransactionIsolationLevel.Serializable,
    maxWait: 5000,  // default: 2000ms
    timeout: 10000  // default: 5000ms
  }
)

Sources:

• Transactions and batch queries (Reference) | Prisma Documentation

Based on the web search results from the official Prisma documentation and GitHub repository:

No, you cannot nest interactive transactions within other interactive transactions in Prisma.

The $transaction method is not available on the transaction client that is passed to the interactive transaction callback. The TransactionClient type explicitly omits the $transaction property, preventing nested transactions.

If you attempt to call prisma.$transaction() inside an interactive transaction callback, it will fail because the transaction client instance doesn't have that method.

Important distinction: Nested writes (like creating related records using Prisma's relation syntax) within an interactive transaction work correctly and don't create separate transactions - Prisma ensures only one transaction is opened.

Sources:

• Transactions and batch queries (Reference) | Prisma Documentation
• Support "nested" transactions in interactive transactions · Issue #15212
• Transactions inside transactions, is that possible? · Discussion #12373

Based on the official Prisma documentation found in the web search, the default maxWait timeout for interactive transactions in Prisma is 2 seconds (2000 milliseconds).

maxWait represents the maximum amount of time Prisma Client will wait to acquire a transaction from the database connection pool before timing out.

await prisma.$transaction(
  async (tx) => {
    // transaction code
  },
  {
    maxWait: 2000, // default value in milliseconds
    timeout: 5000, // separate parameter for transaction execution timeout
  }
)

Sources:

• Transactions and batch queries (Reference) | Prisma Documentation

The default timeout for interactive transactions in Prisma is 5 seconds (5000ms).

There are two timeout-related parameters for interactive transactions:

1. timeout: Maximum time the transaction can run before being rolled back (default: 5000ms)
2. maxWait: Maximum time Prisma Client will wait to acquire a transaction from the database (default: 2000ms)

You can override these defaults when calling $transaction():

await prisma.$transaction(
  async (tx) => {
    // Your transaction code
  },
  {
    maxWait: 5000, // default: 2000
    timeout: 10000, // default: 5000
  }
)

Sources:

• Transactions and batch queries (Reference) | Prisma Documentation

Based on the web search results, I found the authoritative information from the official Prisma documentation.

Interactive transactions keep a database connection open and hold a transaction open on the database. Each query inside the transaction makes a separate network call to the database. This means:

1. Connection blocking: The transaction holds a database connection for its entire duration, preventing other operations from using it
2. Performance degradation: Long-running transactions hurt database performance
3. Deadlock risk: Keeping transactions open for extended periods can cause deadlocks
4. Sequential network overhead: Each query in the transaction requires its own network roundtrip to the database

Network requests (like API calls) and slow queries inside transactions dramatically extend how long the connection and transaction remain open, multiplying these problems.

Best practice: Get in and out of transactions as quickly as possible. Perform external API calls or slow operations outside the transaction block, only including the essential database operations that need atomicity.

Sources:

• Transactions and batch queries (Reference) | Prisma Documentation
• How many network requests does a sequential transaction take? · prisma/prisma · Discussion #24343

Based on the web search results, I found the authoritative information from Prisma's official documentation.

Retry Pattern for Prisma P2034 Error

Implement an exponential backoff retry loop with a maximum retry limit. The P2034 error indicates "Transaction failed due to a write conflict or a deadlock" and requires retrying the transaction.

Recommended pattern:

import { Prisma, PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()

const MAX_RETRIES = 5
let retries = 0
let result

while (retries < MAX_RETRIES) {
  try {
    result = await prisma.$transaction(
      [
        prisma.user.deleteMany({ where: { /* args */ } }),
        prisma.post.createMany({ data: { /* args */ } })
      ],
      {
        isolationLevel: Prisma.TransactionIsolationLevel.Serializable
      }
    )
    break // Success - exit loop
  } catch (error) {
    if (error.code === 'P2034') {
      retries++
      continue // Retry the transaction
    }
    throw error // Re-throw non-P2034 errors
  }
}

Key points:

• Set a maximum retry limit (typically 5 retries)
• Catch errors and check for code 'P2034'
• Continue the loop to retry, or throw if it's a different error
• P2034 errors are more common with higher isolation levels (Serializable, Repeatable Read)

Sources:

• Transactions and batch queries | Prisma Documentation
• Errors | Prisma Documentation

Yes. Prisma Client ensures that only one transaction is opened when nested writes are used inside interactive transactions. Nested writes do not create additional nested database transactions - they collapse into the single interactive transaction.

When you use a nested write (like create with nested connect or create operations) inside an interactive transaction ($transaction), Prisma Client handles this intelligently by executing all operations within the same database transaction context, rather than attempting to open a new transaction for the nested write.

This means code like this uses only one transaction:

await prisma.$transaction(async (tx) => {
  await tx.user.create({
    data: {
      name: "Alice",
      posts: {
        create: { title: "Hello World" }  // nested write
      }
    }
  });
});

All operations execute atomically within a single database transaction.

Sources:

• Does a nested write inside an interactive transaction collapse the transactions? · prisma/prisma · Discussion #15213
• Transactions and batch queries (Reference) | Prisma Documentation
• Support "nested" transactions in interactive transactions · Issue #15212 · prisma/prisma

Based on the official Prisma documentation, the primary benefit of using sequential $transaction operations over Promise.all is automatic rollback on failure.

When you use $transaction with an array of operations:

• All queries execute sequentially on the same database connection
• If any query fails, all previous operations are automatically rolled back
• This ensures atomicity: either all operations succeed or none do

When you use Promise.all without a transaction:

• Queries execute independently (potentially in parallel)
• If one fails, previous queries remain committed to the database
• No automatic rollback occurs

Key distinction: $transaction guarantees that all queries succeed or fail together as a single atomic unit. Promise.all only handles promise resolution/rejection but provides no transactional guarantees.

Note: Using Promise.all inside an interactive transaction still executes queries sequentially because a database connection can only run one query at a time. The transaction blocks the connection, so Promise.all offers no parallelization benefit in this context.

Example:

// With $transaction - atomicity guaranteed
await prisma.$transaction([
  prisma.user.create({ data: { name: 'Alice' } }),
  prisma.post.create({ data: { title: 'Post' } })
])
// If post creation fails, user creation rolls back

// With Promise.all - no rollback
await Promise.all([
  prisma.user.create({ data: { name: 'Alice' } }),
  prisma.post.create({ data: { title: 'Post' } })
])
// If post creation fails, user remains in database

Sources:

• Transactions and batch queries (Reference) | Prisma Documentation

To prevent deadlocks when updating multiple records in a Prisma transaction:

1. Update records in a consistent order (by ID or another deterministic field)

// Sort IDs before updating to ensure consistent lock acquisition order
const ids = [5, 2, 8, 1].sort((a, b) => a - b); // [1, 2, 5, 8]

await prisma.$transaction(
  ids.map(id => 
    prisma.user.update({
      where: { id },
      data: { /* updates */ }
    })
  )
);

2. Implement retry logic for P2034 errors

import { Prisma, PrismaClient } from '@prisma/client'

const MAX_RETRIES = 5
let retries = 0

while (retries < MAX_RETRIES) {
  try {
    await prisma.$transaction([
      prisma.user.update({ where: { id: 1 }, data: { /* ... */ } }),
      prisma.user.update({ where: { id: 2 }, data: { /* ... */ } }),
    ])
    break
  } catch (error) {
    if (error.code === 'P2034') {  // Transaction failed due to deadlock
      retries++
      continue
    }
    throw error
  }
}

3. Use higher isolation levels when needed

await prisma.$transaction(
  [/* operations */],
  {
    isolationLevel: Prisma.TransactionIsolationLevel.Serializable
  }
)

4. Keep transactions short

Avoid network requests and slow queries inside transactions. Long-running transactions hold locks longer, increasing deadlock probability.

Sources:

• Transactions and batch queries (Reference) | Prisma Documentation
• Handling exceptions and errors (Reference) | Prisma Documentation
• Errors | Prisma Documentation

When a Prisma interactive transaction exceeds the timeout, the transaction is automatically rolled back and an error is thrown.

The default timeout is 5000ms (5 seconds). When this timeout is exceeded, Prisma cancels the transaction and rolls back all changes made within it.

You can configure the timeout when calling $transaction:

await prisma.$transaction(
  async (tx) => {
    // your transaction operations
  },
  {
    timeout: 10000, // 10 seconds
    maxWait: 2000,  // time to wait for connection from pool
  }
)

Key parameters:

• timeout: Maximum time the transaction can run before being canceled and rolled back (default: 5000ms)
• maxWait: Maximum time to wait to acquire a connection from the pool (default: 2000ms)

Handle timeout errors with try-catch:

try {
  await prisma.$transaction(async (tx) => {
    // operations
  });
} catch (error) {
  // Transaction was rolled back due to timeout or other error
}

Note: Long-running transactions hurt database performance and can cause deadlocks. Avoid network requests and slow queries inside transactions. If transactions consistently exceed 15 seconds, optimize your queries rather than just increasing the timeout.

Sources:

• Transactions and batch queries (Reference) | Prisma Documentation

Based on my search of official Prisma documentation and community resources, here's the verified answer:

Yes, you can use cls-hooked for cross-module transaction propagation with Prisma, but it's a community-developed pattern, not officially documented by Prisma.

Prisma's official transaction API ($transaction) does not natively support automatic transaction propagation across modules. The official approach requires explicitly passing the transaction client instance to each module/service that needs to participate in the transaction.

The cls-hooked pattern works by:

1. Storing the Prisma TransactionClient in continuation-local storage when a transaction starts
2. Retrieving that client from CLS in other modules/services without explicit parameter passing
3. Automatically reusing the existing transaction context when already inside a transaction

Modern alternatives:

• @nestjs-cls/transactional (for NestJS): Provides a @Transactional() decorator that uses CLS under the hood to automatically propagate transaction context across service calls with Spring-like propagation options (Required, RequiresNew, etc.)
• prisma-transactions library: Adds Java-style @Transactional annotations with propagation types to Prisma

Official Prisma approach:
Pass the transaction client explicitly:

await prisma.$transaction(async (tx) => {
  await userService.create(tx, data);
  await orderService.create(tx, data);
});

Sources:

• Transactions and batch queries (Reference) | Prisma Documentation
• Cross Module Transaction with Prisma - DEV Community
• @nestjs-cls/transactional | NestJS CLS
• Does Prisma offer Transactions across multiple files? · Issue #12975

Based on the official Prisma documentation search results, I need to provide an important clarification:

UNABLE_TO_VERIFY: Prisma does not prescribe a specific isolation level to prevent write conflicts.

Here's what the authoritative documentation actually says:

Prisma acknowledges that write conflicts and deadlocks can occur in concurrent transactions depending on the isolation level, but:

1. Before Prisma ORM 4.4.0: You could NOT set isolation levels in Prisma - the database's configured isolation level always applied.

2. From Prisma 4.2.0+: Support was added to SET isolation levels on interactive transactions (as a Preview feature), but Prisma does not mandate which level to use.

3. Prisma's actual recommendation: Handle write conflicts through retry logic using the P2034 error code ("Transaction failed due to a write conflict or a deadlock"), NOT by prescribing a specific isolation level.

The isolation level choice depends on your database system's defaults and requirements, not Prisma itself. Prisma provides the mechanism to set isolation levels but leaves the choice to developers based on their specific use case and database.

The correct answer for "preventing write conflicts": Use Serializable isolation level (the strictest level supported by most databases), but be aware this comes with performance trade-offs. However, this is a database-level best practice, not a Prisma-specific recommendation.

Sources:

• Transactions and batch queries (Reference) | Prisma Documentation
• Release 4.4.0 · prisma/prisma

The N+1 query problem in Prisma occurs when you fetch a list of records and then loop through them to fetch related data, resulting in 1 initial query + N additional queries (one per record).

Cause:
The N+1 problem happens when you:

1. Query for a list of records (e.g., fetch all users)
2. Loop through results and query related data for each record (e.g., fetch posts for each user individually)

This results in inefficient database access - if you have 100 users, you execute 101 queries total (1 for users + 100 for posts).

Detection:
Enable query logging in Prisma Client to see generated queries, parameters, and durations:

const prisma = new PrismaClient({
  log: ['query'],
})

This shows each database query executed, making it obvious when you're running multiple queries in a loop.

You can also use Prisma Optimize (query optimization tool) or Prisma Metrics (observability) to identify performance bottlenecks and slow queries.

Solution:
Use include or select to eager-load related data in a single query:

// N+1 Problem (multiple queries)
const users = await prisma.user.findMany()
for (const user of users) {
  const posts = await prisma.post.findMany({ where: { userId: user.id } })
}

// Fixed (single query with include)
const users = await prisma.user.findMany({
  include: { posts: true }
})

Relation Load Strategy (v5.8.0+):
Control how Prisma executes relation queries with relationLoadStrategy:

const users = await prisma.user.findMany({
  include: { posts: true },
  relationLoadStrategy: 'join' // or 'query'
})

• join (default): Uses database-level LATERAL JOIN (PostgreSQL) or correlated subqueries (MySQL) - single query
• query: Sends multiple queries (one per table), joins data at application level

The join strategy is more efficient in most cases, but profile your specific use case.

Sources:

• Relation queries (Concepts) | Prisma Documentation
• Query optimization using Prisma Optimize | Prisma Documentation
• Prisma ORM Now Lets You Choose the Best Join Strategy
• Metrics (Preview) | Prisma Documentation

Based on the authoritative Prisma documentation, here's the verified answer:

relationLoadStrategy Option

The relationLoadStrategy option (available since v5.8.0 for PostgreSQL, v5.10.0 for MySQL) lets you control how Prisma Client executes relation queries on a per-query basis.

Two strategies available:

1. join (default) - Uses a database-level LATERAL JOIN (PostgreSQL) or correlated subqueries (MySQL) to fetch all data with a single query

2. query - Sends multiple queries to the database (one per table) and joins them on the application level

How It Solves N+1 Problems

N+1 problem: When you query N records and then make 1 additional query for each record's relations, resulting in N+1 total queries.

Solution: By setting relationLoadStrategy: 'join', Prisma performs a database-level join that fetches all data (parent records + related records) in a single SQL query instead of N+1 queries.

Example:

const users = await prisma.user.findMany({
  relationLoadStrategy: 'join', // One SQL query total
  include: {
    posts: true,
  },
})

Without relationLoadStrategy: 'join', the default behavior would execute 2 queries (one for users, one for posts). With deeply nested relations, the join strategy becomes even more beneficial by preventing multiple round-trips to the database.

Sources:

• Relation queries (Concepts) | Prisma Documentation
• Query optimization using Prisma Optimize | Prisma Documentation
• Prisma ORM Now Lets You Choose the Best Join Strategy

Yes. Prisma Client automatically batches findUnique() queries to prevent N+1 issues using an internal dataloader.

How it works:

• Multiple findUnique() queries executed in the same tick are automatically batched into a single database query
• This happens when queries have the same where and include parameters
• All where criteria must be on scalar fields (unique or non-unique) of the same model
• All criteria must use the equal filter only (no boolean operators or relation filters)

Example - N+1 prevention in GraphQL:

// These get automatically batched into one query
const user1 = await prisma.user.findUnique({ where: { email: '[email protected]' } })
const user2 = await prisma.user.findUnique({ where: { email: '[email protected]' } })
const user3 = await prisma.user.findUnique({ where: { email: '[email protected]' } })

Fluent API also benefits:

// This gets batched by the dataloader
await prisma.user.findUnique({ where: { email: '[email protected]' } }).posts()

The dataloader is built-in and enabled by default—no configuration required.

Sources:

• Query optimization using Prisma Optimize | Prisma Documentation
• Relation queries (Concepts) | Prisma Documentation

Prisma's automatic query batching (via the dataloader) works for findUnique() queries when these three conditions are met:

1. All where filter criteria must be on scalar fields (unique or non-unique) of the same model being queried
2. All criteria must use the equals filter (either shorthand where: { field: value } or explicit where: { field: { equals: value } })
3. No boolean operators or relation filters are present in the where clause

Additionally, queries must occur in the same tick and have identical where and include/select parameters to be batched together. The dataloader groups these matching findUnique queries and optimizes them into a single findMany query.

Sources:

• Query optimization using Prisma Optimize | Prisma Documentation
• Relation queries (Concepts) | Prisma Documentation

Cursor-based pagination is more scalable than offset-based pagination because offset-based pagination forces the database to traverse all skipped records before returning results.

When you use offset pagination (e.g., skip: 200000, take: 10), the database must still scan through the first 200,000 records internally before it can return the 10 records you requested. This creates a performance penalty that grows linearly with the offset size.

In contrast, cursor-based pagination uses a WHERE clause to query records directly (e.g., WHERE id > cursor_value), allowing the database to leverage indexes and jump directly to the relevant records without traversing skipped rows.

Example:

// Offset-based (doesn't scale)
const results = await prisma.post.findMany({
  skip: 200000,  // Database must traverse 200k records
  take: 10
})

// Cursor-based (scales better)
const results = await prisma.post.findMany({
  take: 10,
  cursor: {
    id: lastSeenId  // Database jumps directly using index
  },
  skip: 1  // Skip the cursor itself
})

Trade-off: Cursor-based pagination requires sorting by a unique, sequential column and doesn't allow jumping to arbitrary pages (e.g., page 400), while offset pagination supports random page access but degrades with large offsets.

Sources:

• Pagination (Reference) | Prisma Documentation

Based on the official Prisma documentation, add the @unique attribute to your cursor field.

Cursor-based pagination performs best when the field you're using as a cursor (such as id or createdAt) has the @unique attribute in your Prisma schema. Without this attribute, Prisma generates less efficient queries that degrade in performance after the first page.

Example:

model Post {
  id        Int      @id @default(autoincrement())
  createdAt DateTime @default(now()) @unique  // Add @unique for better performance
  title     String
}

The cursor field must be both unique and sequential. While you can technically use a non-unique field for cursor pagination, the database query will be significantly less efficient because Prisma cannot optimize the WHERE clause as effectively without the uniqueness guarantee.

Sources:

• Pagination (Reference) | Prisma Documentation
• Cursor-based pagination without sequential cursor - Prisma GitHub Discussion #4888

Based on the search results, I now have authoritative information from the Prisma GitHub issue tracker and official documentation. Let me provide the answer.

Performance Impact of DESC Order with Cursor Pagination in Prisma + PostgreSQL

DESC order causes a ~1000x performance degradation compared to ASC order in Prisma cursor pagination on large PostgreSQL tables.

Concrete measurements (from a table with 1,000,000 rows):

• ASC cursor pagination: ~0.3ms
• DESC cursor pagination: ~300ms

Root Cause

This is a known bug in Prisma's query generation for PostgreSQL. The issue stems from how Prisma constructs queries for descending cursor pagination, which fails to leverage indexes efficiently.

Index Optimization

Even with proper DESC indexes, the performance issue persists due to Prisma's query generation. The recommended index pattern would be:

CREATE INDEX idx_table_id_desc ON table(id DESC);

However, this alone does not resolve Prisma's DESC cursor performance issue.

Workarounds

1. Use ASC order when possible - Reverse the sort order in your application layer
2. Implement custom SQL queries - Bypass Prisma for performance-critical pagination endpoints
3. Use negative take for backward pagination - Prisma supports take: -10 for paging backwards

Why Cursor Pagination is Still Better Than Offset

Despite the DESC issue, cursor pagination avoids the fundamental OFFSET problem where PostgreSQL must traverse and discard rows. Cursor pagination queries use WHERE id > cursor instead of OFFSET, maintaining O(log n) performance for page depth (except when using DESC order due to the bug).

Sources:

• Cursor-based pagination postgresql performance issue with desc order · Issue #12650
• Pagination (Reference) | Prisma Documentation
• Prisma is not using LIMIT for cursor based pagination · Issue #15710

Perfect! I found the authoritative answer in the Prisma GitHub discussion. Let me provide the verified solution:

---

Add a unique field as a secondary sort criterion. When sorting by a non-unique field (like createdAt, name, or price), you must include a unique field (typically id) as a tiebreaker in your orderBy clause.

Example with single non-unique field:

// ❌ Unstable - can return inconsistent results
const results = await prisma.post.findMany({
  take: 10,
  cursor: { id: cursorId },
  orderBy: { createdAt: 'desc' }
});

// ✅ Stable - always deterministic
const results = await prisma.post.findMany({
  take: 10,
  cursor: { id: cursorId },
  orderBy: [
    { createdAt: 'desc' },
    { id: 'desc' }  // Secondary sort on unique field
  ]
});

Why this works: When multiple records have identical values in the primary sort field, the database returns them in an unpredictable order. Adding a unique field as a secondary sort ensures consistent, deterministic ordering across pagination requests.

For compound cursors (more advanced): The ideal solution would be to include all orderBy column values in the cursor itself (e.g., { createdAt, id } instead of just { id }), allowing the database to use tuple comparison. However, Prisma's current API only supports single-field cursors, so you must ensure your cursor field alone (or combined with orderBy) produces unique ordering.

Sources:

• Cursor-based pagination without sequential cursor · prisma/prisma · Discussion #4888
• Pagination (Reference) | Prisma Documentation

Prisma does not use LIMIT in the generated SQL for cursor-based pagination due to a long-standing bug in how it implements the feature.

The Problem:
When you use cursor-based pagination with cursor, take, and orderBy parameters, Prisma generates a SQL query with only a WHERE clause filter (e.g., WHERE id > cursor_value) but omits the LIMIT clause. This causes Prisma to fetch potentially all rows matching the WHERE condition from the database, then prune the results in-memory to the take amount.

Impact:

• Entire tables can be fetched into memory
• Can cause out-of-memory errors
• Extremely high latency on large datasets
• Defeats the performance purpose of cursor pagination

Why it happens:
Prisma's cursor pagination implementation filters using the cursor value in a WHERE clause but fails to apply the take parameter as a SQL LIMIT. If you use take and orderBy without a cursor, Prisma correctly adds LIMIT to the query. The bug only occurs when a cursor is present.

Workaround:
The community has created workaround libraries and some developers resort to raw SQL queries to properly implement cursor pagination with LIMIT.

Sources:

• Prisma is not using LIMIT for cursor based pagination - Issue #15710
• Using cursor causes LIMIT not to be used, can cause Out of Memory - Issue #27094
• Pagination (Reference) | Prisma Documentation

Based on the search results from Prisma's official documentation, here's the authoritative answer:

Performance Difference

select can improve performance by reducing response size, but both include and select use the same underlying query strategies.

Key Performance Facts:

1. Data Transfer: Using select to choose only required fields reduces the size of the response, which improves query speed compared to fetching all fields.

2. Database Queries: Both include and select work with the same relationLoadStrategy option, meaning they both:

   • Can use database-level JOINs
   • Can use application-level queries (N+1 pattern)
   • Generate similar underlying SQL

3. No Inherent Performance Difference: The performance difference isn't between include vs select themselves, but rather:

   • How much data you're fetching (fewer fields = better performance)
   • How many relations you're loading
   • The depth of nested relations

4. Best Practice: Select only the fields and relations you require rather than relying on the default selection set to reduce response size and improve speed.

Example:

// More performant - only fetches needed fields
const user = await prisma.user.findUnique({
  where: { id: 1 },
  select: {
    id: true,
    email: true,
    posts: { select: { title: true } }
  }
})

// Less performant - fetches all user fields + all post fields
const user = await prisma.user.findUnique({
  where: { id: 1 },
  include: { posts: true }
})

Sources:

• Select fields | Prisma Documentation
• Relation queries | Prisma Documentation

Based on the official Prisma documentation, here's when you should use $queryRaw:

Use $queryRaw instead of Prisma Client's type-safe queries when:

1. Performance optimization - You need to optimize a specific query that can't be efficiently expressed with Prisma's query API
2. Complex query requirements - Your data requirements cannot be expressed by Prisma Client's query API
3. Dynamically generated WHERE clauses - When you need runtime-dynamic query construction that TypedSQL cannot handle statically
4. Advanced SQL features - When you need database-specific features or SQL constructs not supported by Prisma's query builder

Key distinction: Use $queryRaw for SELECT queries that return records. Use $executeRaw for UPDATE/DELETE queries that return affected row counts.

Safety note: Use $queryRaw (template tag version) for safe parameterized queries. Only use $queryRawUnsafe when absolutely necessary, as it's vulnerable to SQL injection.

Sources:

• Raw queries | Prisma Documentation
• Write Your Own SQL in Prisma Client | Prisma Documentation

Based on the web search results, I have found authoritative information from official Prisma sources. Let me provide the answer:

Without Indexes: O(n) - Linear Scan

When a database table has no index on a queried field, the database performs a full table scan, examining every row sequentially until it finds matching records. This is O(n) time complexity - as your table grows, query time increases proportionally.

With B-tree Indexes: O(log n) - Logarithmic Search

Adding an index (default B-tree type) creates a sorted tree structure that enables binary search. The database can quickly navigate the tree by eliminating half the remaining data at each step, achieving O(log n) time complexity. As data grows, query time increases much slower - a table with 1 million rows requires only ~20 comparisons instead of up to 1 million.

Adding Indexes in Prisma Schema

model User {
  id    Int    @id @default(autoincrement())
  email String
  name  String

  @@index([email])  // Single-field index
  @@index([name, email])  // Composite index
}

Or on a single field:

model User {
  id    Int    @id @default(autoincrement())
  email String @unique  // Unique constraint creates index
}

Performance Impact

The official Prisma blog demonstrates a query on 1 million records:

• Without index: 504ms (full table scan)
• With index: 8ms (B-tree lookup)

Index fields that appear frequently in WHERE, ORDER BY, or JOIN clauses for maximum performance gains.

Sources:

• Improving query performance with database indexes using Prisma: B-tree indexes
• Indexes | Prisma Documentation
• Improving query performance with database indexes using Prisma: Introduction

Poor performance with distinct in Prisma's findMany is caused by in-memory filtering. By default, Prisma Client does not use SQL's SELECT DISTINCT. Instead, it fetches records from the database and applies distinct filtering in memory within the Node.js process.

This design choice was made to support select and include (relation loading) as part of distinct queries, which SQL's DISTINCT cannot handle directly. However, this approach becomes inefficient with large datasets because:

1. All matching records are fetched before filtering, consuming memory and network bandwidth
2. Filtering happens in application memory rather than at the database level
3. LIMIT is not applied at the SQL level with distinct, causing full result sets to be processed

Solution: Enable the nativeDistinct preview feature in your Prisma schema:

generator client {
  provider = "prisma-client-js"
  previewFeatures = ["nativeDistinct"]
}

This pushes the distinct operation to the database layer (where supported), significantly improving performance by using SQL's native DISTINCT capability.

Note: Some databases may not fully support DISTINCT on all field combinations, and behavior can vary between database providers.

Sources:

• Prisma Client API Reference
• Query Optimization Documentation
• GitHub Issue #14765 - SQL-level DISTINCT support

Prisma's internal buffering mechanism uses a FIFO (First In First Out) queue in memory to buffer queries when all database connections in the connection pool are busy. This can cause poor performance for several reasons:

1. Memory exhaustion: If queries accumulate faster than they can be processed, the in-memory queue grows unbounded and can eventually exhaust available RAM.

2. Cascading timeouts: Queries wait in the queue for an available connection. If a query waits longer than the pool_timeout (default: 10 seconds), it throws a P2024 error and is discarded, but the queue continues growing with new incoming queries.

3. Head-of-line blocking: The FIFO queue processes queries strictly in order. A slow query at the front of the queue blocks all subsequent queries, even if they could execute quickly.

4. False scarcity: If your application creates more concurrent requests than the connection_limit allows, queries buffer in memory rather than being rejected immediately, creating the illusion that your application can handle the load when it actually cannot.

The performance issue arises because buffering masks the problem rather than solving it. Queries appear to be "in flight" but are actually waiting in RAM, consuming memory without making progress until a connection becomes available.

Configuration example:

postgresql://user:password@localhost:5432/db?connection_limit=10&pool_timeout=20

Sources:

• Connection pool | Prisma Documentation
• Connection management (Guide)
• Database connections | Prisma Documentation

Based on the official Prisma documentation search results, I can provide you with the verified answer:

Prisma Optimize

Prisma Optimize is a performance monitoring and optimization tool that helps generate insights and provides recommendations to make database queries faster.

Performance Insights Provided

Query Performance Metrics:

• Average duration - Mean execution time across all query executions
• 50th percentile (P50) - Median query execution time
• 99th percentile (P99) - 99th percentile latency for identifying outliers
• Maximum execution time - Slowest query execution time
• Query latencies - Detailed timing information for executed queries

Optimization Recommendations:
Prisma Optimize identifies and provides recommendations for:

• Indexing issues - Missing or inefficient database indexes
• Excessive data retrieval - Queries fetching more data than needed
• Inefficient query patterns - Suboptimal query structures

AI-Powered Analysis:
Includes an AI assistant to enhance query performance analysis and provide actionable optimization guidance.

Recording Sessions:
Optimize captures performance data during recording sessions, allowing you to analyze query behavior over time and identify performance bottlenecks.

Sources:

• Prisma Optimize | Prisma Documentation
• Optimize: Query performance metrics | Prisma Documentation
• Query optimization using Prisma Optimize | Prisma Documentation

Based on the official Prisma documentation, I can provide the authoritative answer:

What is the Shadow Database?

The shadow database is a temporary, second database that Prisma Migrate creates and deletes automatically. It's used to detect problems such as:

• Schema drift
• Potential data loss in generated migrations

How It Works

When you run prisma migrate dev, Prisma Migrate uses the shadow database to:

1. Create a fresh copy of the shadow database
2. Rerun the current migration history
3. Introspect the shadow database to generate the current state of your Prisma schema
4. Compare the end state of the current migration history to the development database

When Is It Required?

The shadow database is required for development workflows only:

• ✅ Required: prisma migrate dev (development command)
• ❌ NOT required: Production-focused commands like prisma migrate deploy and prisma migrate resolve

Permission Requirements

To use the shadow database, your database user must have permission to create and drop databases. If your environment doesn't allow this, you can manually configure a shadow database URL.

Key Point: The shadow database is purely a development tool and is never needed in production environments.

Sources:

• About the shadow database | Prisma Documentation

Based on the official Prisma documentation, the following Prisma Migrate commands do NOT require a shadow database:

• prisma migrate deploy - Production command that applies pending migrations
• prisma migrate resolve - Resolves migration history issues
• prisma migrate status - Checks migration status

These commands work directly with your main database and migration history without needing a temporary shadow database.

Commands that DO require a shadow database:

• prisma migrate dev - Development workflow command
• prisma migrate diff - When using --from-migrations or --to-migrations flags

The shadow database is specifically a development environment requirement. Production-focused commands (deploy, resolve) explicitly do not use or require a shadow database.

Sources:

• About the shadow database | Prisma Documentation
• Development and production | Prisma Documentation

Based on the official Prisma documentation, here's how to create a baseline migration for an existing production database:

Steps to Baseline an Existing Database

1. Create a migrations directory and generate the baseline migration:

mkdir -p prisma/migrations/0_init

2. Generate a migration from your current database schema:

npx prisma migrate diff \
  --from-empty \
  --to-schema-datamodel prisma/schema.prisma \
  --script > prisma/migrations/0_init/migration.sql

This creates a SQL file containing all the DDL statements to recreate your existing database structure.

3. Mark the baseline migration as applied:

npx prisma migrate resolve --applied 0_init

This adds the 0_init migration to the _prisma_migrations table without executing it, since your database already has these structures.

4. Future migrations work normally:

After baselining, any new schema changes you make can be applied using:

npx prisma migrate dev
npx prisma migrate deploy  # for production

Prisma will skip the baseline migration (since it's marked as applied) and only run new migrations created after the baseline.

Why This Works

Baselining tells Prisma Migrate to assume the initial migration has already been applied. This prevents Prisma from trying to recreate existing tables, which would fail in production. The baseline migration serves as the starting point for all future migrations.

Sources:

• Baselining a database | Prisma Documentation
• Getting started with Prisma Migrate | Prisma Documentation

Based on the official Prisma documentation, here's the authoritative answer:

Prisma does not have a single dedicated "down migration" command. Instead, you use prisma migrate diff to generate down migration SQL files.

Command syntax:

npx prisma migrate diff \
  --from-migrations ./prisma/migrations/<migration_folder> \
  --to-migrations ./prisma/migrations/<previous_migration_folder> \
  --script > down.sql

Or comparing against your database state (no shadow database required):

npx prisma migrate diff \
  --from-schema-datamodel ./prisma/schema.prisma \
  --to-schema-datasource ./prisma/schema.prisma \
  --script > down.sql

To apply the down migration:

npx prisma db execute --file ./down.sql --schema ./prisma/schema.prisma

Then mark it as rolled back:

npx prisma migrate resolve --rolled-back <migration_name>

Important: Prisma Migrate doesn't automatically generate down migrations. You must manually create them using migrate diff when needed. Down migrations only revert schema changes, not data changes.

Sources:

• Generating down migrations | Prisma Documentation

Use prisma migrate deploy to apply migrations in production without resetting the database.

npx prisma migrate deploy

What it does:

• Applies all pending migrations from the prisma/migrations folder to the production database
• Compares applied migrations against the migration history table to determine which migrations are pending
• Does NOT reset or drop the database
• Does NOT require interactive input (safe for CI/CD pipelines)

Key differences from development commands:

• prisma migrate dev - Used in development, can reset the database, requires interactive prompts
• prisma migrate reset - Drops and recreates the database (never use in production)
• prisma migrate deploy - Production-safe, only applies pending migrations, no resets

Best practices:

• Run as part of your CI/CD pipeline
• Execute before deploying application code that depends on schema changes
• Use in staging, testing, and production environments only

For existing production databases:
Use baselining (prisma migrate resolve --applied <migration_name>) to mark existing migrations as already applied before running migrate deploy.

Sources:

• Development and production | Prisma Documentation
• Deploying database changes with Prisma Migrate | Prisma Documentation

Based on the official Prisma documentation search results, I can provide the authoritative answer:

Schema Drift in Prisma

Schema drift occurs when your database schema is out of sync with your migration history—the database schema has "drifted away" from the source of truth (your Prisma schema and migrations).

How Drift is Detected

Prisma Migrate detects schema drift automatically when you run prisma migrate dev using a shadow database:

1. Shadow Database Creation: A temporary, second database is created automatically
2. Migration Replay: Prisma applies all migrations from your migration history to the shadow database to determine the expected end state
3. Comparison: The shadow database schema (expected state) is compared against your actual development database schema
4. Drift Detection: If the schemas don't match, Prisma reports detailed information about which parts have drifted

Common Causes of Drift

• Making manual changes directly to the database
• Using prisma db push to modify the database schema
• Applying schema changes outside the migration workflow

Important Limitations

• Drift detection only works in development (requires shadow database access)
• prisma migrate deploy (used in production) does not detect drift
• The shadow database must be accessible and creatable for drift detection to work

Sources:

• Troubleshooting | Prisma Documentation
• About the shadow database | Prisma Documentation
• A mental model for Prisma Migrate | Prisma Documentation

To resolve a failed migration in production using prisma migrate resolve, you mark the migration as either applied or rolled back:

Mark as rolled back (migration failed and you want to record it as rolled back):

npx prisma migrate resolve --rolled-back "20201127134938_migration_name"

Mark as applied (migration actually succeeded or you manually completed it):

npx prisma migrate resolve --applied "20201127134938_migration_name"

When to use each option:

• --rolled-back: Use when a migration failed partway through and you need to manually fix the database state, then mark the migration as rolled back so you can retry it
• --applied: Use when a migration failed but actually completed successfully in the database, or when you manually completed the migration steps and want to mark it as done

Key constraints:

• Only works on migrations currently in a failed state
• Requires the exact migration name (folder name from prisma/migrations/)
• Not supported on MongoDB (use db push instead)
• Until resolved, no further migrations can be deployed with prisma migrate deploy

Sources:

• Prisma CLI Reference
• Production Troubleshooting
• Generating Down Migrations

Based on the search results from official Prisma documentation, here's the verified answer:

---

shadowDatabaseUrl is a configuration option that specifies the connection URL for a temporary "shadow database" used by Prisma Migrate during development.

What It Does

Prisma Migrate uses the shadow database to:

1. Detect schema drift (differences between migration history and actual database state)
2. Generate new migrations
3. Verify that migrations can be applied from scratch

The shadow database is created automatically, used temporarily, and then dropped after the migration operation completes.

When You Should Use It

You must configure shadowDatabaseUrl when:

1. You lack database privileges to create/drop databases (required for automatic shadow database creation)
2. Your cloud provider restricts database creation/deletion permissions
3. You're using a managed database service that doesn't allow CREATE DATABASE/DROP DATABASE commands
4. Your development environment requires explicit database provisioning

Configuration

Prisma ORM v7+ (in prisma.config.ts):

import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  datasource: {
    url: env('DATABASE_URL'),
    shadowDatabaseUrl: env('SHADOW_DATABASE_URL'),
  },
})

Prisma ORM v6.19 and earlier (in schema.prisma):

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

Critical Warning

Never set shadowDatabaseUrl to the same value as url — this will cause Prisma Migrate to delete all data in your main database.

Sources:

• About the shadow database | Prisma Documentation
• Prisma Schema Reference | Prisma Documentation
• Upgrade to Prisma ORM 7 | Prisma Documentation

When prisma migrate dev detects schema drift, it prompts you to reset your database. The command displays a message like:

We need to reset the [database_type] database "[database_name]" at "[host:port]"

What happens:

1. Drift Detection: Prisma Migrate uses a shadow database to replay your migration history and compare it against your current database schema
2. Prompt for Reset: If drift is detected (e.g., manual database changes, deleted/edited migrations, or using prisma db push), the command prompts you to reset the database
3. Database Reset: If you accept, Prisma Migrate will:
   • Drop and recreate the database
   • Reapply all migrations from the migration history
   • Sync the database schema with your migration history

Schema drift occurs when:

• You manually changed the database schema outside of migrations
• You used prisma db push instead of migrations
• Migration files were edited or deleted after being applied
• There are discrepancies between your migration history and actual database state

Note: This reset behavior only happens in development environments with migrate dev. In production, you use migrate deploy which will error if drift is detected rather than prompting for a reset.

Sources:

• Development and production | Prisma Documentation
• Troubleshooting | Prisma Documentation
• Prototyping your schema | Prisma Documentation

Based on the authoritative Prisma documentation, here are the key differences:

prisma migrate dev

• Creates migration history: Generates SQL migration files in prisma/migrations/ folder
• Uses shadow database: Creates a temporary database to detect schema drift and validate migrations
• Applies migrations sequentially: Reruns existing migrations, then generates and applies new ones
• Preserves data migration logic: You can edit migration files to add custom SQL for data transformations
• For production use: Migration history can be deployed to staging/production environments

db push

• No migration history: Does NOT generate migration files - changes are not preserved
• No shadow database: Directly syncs schema to database without validation layer
• Immediate sync: Pushes current Prisma schema state to database immediately
• Cannot preserve data: No way to customize migrations or handle data transformations
• For prototyping only: Not suitable for production deployments

When to use each

Use migrate dev when:

• Building features for production
• You need migration history for other environments
• You need to control how schema changes affect existing data
• Working in a team (migrations provide audit trail)

Use db push when:

• Rapidly prototyping schema designs locally
• Experimenting with schema iterations
• You don't care about migration history
• Working in early development stages

Critical limitation

If you use db push throughout development, you must continue using db push in staging/production since there's no migration history. You cannot switch to migrate deploy later without creating a baseline migration.

Sources:

• Prototyping your schema | Prisma Documentation
• Development and production | Prisma Documentation
• Prisma Migrate Overview | Prisma Documentation

Based on the official Prisma documentation, here's how to handle hotfixes applied directly to production:

Handling Production Hotfixes in Prisma

When a hotfix has been applied directly to a production database (bypassing Prisma Migrate), you need to reconcile the migration history using prisma migrate resolve:

Step 1: Create a migration file that matches the hotfix

Create a migration file in your development environment that contains the exact same SQL changes that were applied to production:

npx prisma migrate dev --create-only --name hotfix_description

Step 2: Manually verify the migration SQL

Edit the generated migration file to ensure it exactly matches what was applied to production.

Step 3: Mark the migration as applied in production

Use prisma migrate resolve to mark the migration as already applied without executing it:

npx prisma migrate resolve --applied "20201127134938_hotfix_description"

This tells Prisma Migrate that this migration has already been applied to the database, preventing it from attempting to re-run the changes.

Step 4: Deploy normally going forward

Future deployments using prisma migrate deploy will skip the resolved migration and only apply new ones.

Key Points

• prisma migrate resolve reconciles migration history without re-executing SQL
• The migration file in source control must exactly match what was manually applied
• This prevents schema drift between your migration history and actual database state
• prisma migrate deploy does not detect drift in production (requires shadow database)

Sources:

• Patching & hotfixing | Prisma Documentation
• Development and production | Prisma Documentation

Based on the official Prisma documentation, for a failed migration in production:

npx prisma migrate diff \
  --from-schema-datamodel prisma/schema.prisma \
  --to-schema-datasource prisma/schema.prisma \
  --script > rollback.sql

This generates a SQL script that rolls back the database from its current failed state to match the migration history state defined in your Prisma schema.

After generating the rollback SQL, you apply it with:

npx prisma db execute --file rollback.sql --schema prisma/schema.prisma

Then mark the failed migration as rolled back:

npx prisma migrate resolve --rolled-back <migration_name>

Important: prisma migrate diff compares the current database state against your schema to generate the necessary SQL to align them. This is specifically for handling failed migrations that left the database in an inconsistent state.

Sources:

• Patching & hotfixing | Prisma Documentation
• Generating down migrations | Prisma Documentation
• Prisma CLI reference | Prisma Documentation

Based on the official Prisma documentation, here's the verified answer:

Purpose

The _prisma_migrations table is a metadata table created in your database that tracks which migrations have been applied and stores the complete migration history.

How It Works

• When Prisma Migrate applies a migration to your database, it records that migration in the _prisma_migrations table
• Prisma Migrate compares applied migrations (stored in _prisma_migrations) against the migration history in your filesystem (/prisma/migrations folder) to determine which migrations still need to be applied
• Commands like prisma migrate dev and prisma migrate deploy use this table to ensure migrations are applied only once and in the correct order

What It Stores

Each row in _prisma_migrations represents one applied migration and contains metadata such as:

• Migration name/identifier
• Checksum (to detect if migration files were modified)
• Timestamp of when the migration was applied
• Migration logs and status

This enables Prisma Migrate to maintain consistency between your database schema, your Prisma schema file, and your migration history.

Sources:

• A mental model for Prisma Migrate | Prisma Documentation
• About migration histories | Prisma Documentation
• Development and production | Prisma Documentation

Use the --create-only flag with prisma migrate dev:

npx prisma migrate dev --name your_migration_name --create-only

This generates a migration SQL file in your prisma/migrations directory based on your schema changes, but does not apply it to the database.

When to use this:

• You need to customize the generated SQL before applying it
• You want to add custom data transformations or preserve data during schema changes
• You need to review the migration before execution

Typical workflow:

1. Run npx prisma migrate dev --create-only --name your_migration_name
2. Edit the generated .sql file in prisma/migrations/
3. Run npx prisma migrate dev to apply the edited migration

Sources:

• Customizing migrations | Prisma Documentation
• Development and production | Prisma Documentation

The three main approaches to implementing multi-tenancy with Prisma are:

1. Database-per-tenant: Each tenant has their own separate database instance. Prisma supports connecting to multiple databases using multiple Prisma Client instances or dynamic client instantiation.

2. Schema-per-tenant: Multiple tenants share the same database but each has their own schema (namespace). Prisma's multi-schema feature allows you to designate models to specific schemas using the @@schema attribute. Supported on PostgreSQL, CockroachDB, and SQL Server.

3. Shared database with Row-Level Security (RLS): All tenants share the same database and tables, with tenant isolation achieved through a tenant_id column and Row-Level Security policies. Implemented using Prisma Client Extensions to automatically filter queries by tenant.

Sources:

• How to use multiple databases in a single app | Prisma Documentation
• How to use Prisma ORM with multiple database schemas | Prisma Documentation
• Prisma Client Extensions (Preview) - Multi-tenancy with RLS

Row Level Security (RLS) with Prisma Client extensions is implemented using the query component to wrap queries in transactions that set session variables for PostgreSQL RLS policies.

Implementation Pattern

Use $extends() with the query component to intercept all operations and execute them within a transaction that sets the RLS context:

import { Prisma } from '@prisma/client'

function rlsExtension(userId: string) {
  return Prisma.defineExtension((prisma) =>
    prisma.$extends({
      query: {
        $allModels: {
          async $allOperations({ args, query }) {
            const [, result] = await prisma.$transaction([
              prisma.$executeRaw`SELECT set_config('app.current_user_id', ${userId}, TRUE)`,
              query(args),
            ])
            return result
          },
        },
      },
    })
  )
}

// Usage per-request
const prisma = new PrismaClient().$extends(rlsExtension(currentUserId))

PostgreSQL Setup Required

Your database needs RLS policies that reference the session variable:

ALTER TABLE "User" ENABLE ROW LEVEL SECURITY;
ALTER TABLE "User" FORCE ROW LEVEL SECURITY;

CREATE POLICY user_isolation_policy ON "User"
  USING (id = current_setting('app.current_user_id')::text);

How It Works

1. The extension intercepts every query through $allOperations
2. Wraps it in a $transaction that first sets the PostgreSQL session variable with set_config(..., TRUE) (TRUE makes it transaction-scoped)
3. The RLS policy checks this variable to filter rows
4. Each request gets its own extended client instance with its own user context

Note: Prisma's official example is for demonstration only, not production use.

Sources:

• Prisma Client Extensions: Query Component
• Prisma Client Extensions Documentation
• Official RLS Example Repository

Based on the authoritative sources, here's what I found:

Database User Permissions Required for Prisma Client with RLS

Critical requirement: Your database user must NOT have the BYPASSRLS attribute or superuser privileges. Superusers and roles with BYPASSRLS always bypass the row security system in PostgreSQL, which defeats the purpose of RLS.

Required permissions for the Prisma database user:

1. LOGIN - Allow the role to connect to the database
2. GRANT USAGE ON SCHEMA public - Access to the schema
3. GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public - Access to sequences for auto-incrementing IDs
4. GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public - Standard CRUD operations on tables

Example setup:

-- Create a limited-privilege user
CREATE ROLE prisma_user WITH LOGIN PASSWORD 'your_password';

-- Grant necessary permissions
GRANT USAGE ON SCHEMA public TO prisma_user;
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO prisma_user;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO prisma_user;

-- Ensure the role does NOT have BYPASSRLS
-- (by default it won't, but verify)

Important: The user must be a regular role without elevated privileges so that RLS policies are enforced on all queries made by Prisma Client.

Sources:

• Prisma Client Extensions - Row-Level Security
• Support for row-level security (RLS) - Issue #12735
• Managing privileges in PostgreSQL with grant and revoke

Based on my search, I found discussions in the Prisma community but I cannot find a clear statement from Prisma's official documentation that explicitly defines "the main limitation" of schema-per-tenant at scale.

The community discussions (GitHub issues and third-party sources) suggest that connection pool proliferation is a significant challenge - where each PrismaClient instance per tenant/schema creates its own connection pool, leading to resource exhaustion. However, this information comes from community discussions rather than Prisma's official documentation stating this as "the main limitation."

UNABLE_TO_VERIFY: Could not find Prisma's official documentation explicitly stating the main limitation of schema-per-tenant approach at scale. While community discussions indicate connection pool management as a significant challenge, I cannot cite an authoritative Prisma source that definitively identifies this as "the main limitation."

Sources:

• How to use Prisma ORM with multiple database schemas | Prisma Documentation
• Connection pool | Prisma Documentation
• Isolating multi-tenant data via database schemas · Issue #12420 · prisma/prisma

Prisma does not natively support RLS policies in schema definitions. To enable RLS in Prisma migrations for multi-tenant applications, use this workflow:

1. Create migration without applying:

npx prisma migrate dev --create-only

2. Edit the generated migration file in prisma/migrations/[timestamp]_[name]/migration.sql to add RLS SQL:

-- Enable RLS on tables
ALTER TABLE "users" ENABLE ROW LEVEL SECURITY;
ALTER TABLE "posts" ENABLE ROW LEVEL SECURITY;

-- Force RLS even for table owner (important if same user runs migrations and app)
ALTER TABLE "users" FORCE ROW LEVEL SECURITY;
ALTER TABLE "posts" FORCE ROW LEVEL SECURITY;

-- Create tenant isolation policy
CREATE POLICY tenant_isolation_policy ON "users"
  USING (tenant_id = current_setting('app.tenant_id')::uuid);

CREATE POLICY tenant_isolation_policy ON "posts"
  USING (tenant_id = current_setting('app.tenant_id')::uuid);

3. Apply the migration:

npx prisma migrate dev

4. Use Prisma Client Extension to set the tenant context at runtime:

const prisma = new PrismaClient().$extends({
  query: {
    $allModels: {
      async $allOperations({ args, query }) {
        const [, result] = await prisma.$transaction([
          prisma.$executeRaw`SELECT set_config('app.tenant_id', ${tenantId}, TRUE)`,
          query(args),
        ])
        return result
      },
    },
  },
})

Important: Your database user must NOT have BYPASSRLS attribute or superuser privileges, as these bypass RLS entirely.

Alternative: Use @shoito/prismarls CLI tool to automatically generate RLS SQL and append it to migration files.

Sources:

• Prisma Client Extensions - Row Level Security Example
• Using Row-Level Security in Prisma - Atlas Guides
• Support for row-level security (RLS) - Prisma Issue #12735
• @shoito/prismarls - npm

Based on the authoritative sources, here are the common pitfalls when implementing RLS with Prisma:

1. No Native RLS Support

Prisma doesn't have built-in RLS support. You must use Prisma Client Extensions as a workaround, which adds complexity and requires manual implementation of RLS patterns.

2. Database User Permissions

By default, Prisma connects using a postgres superuser that bypasses all RLS policies. You must configure your DATABASE_URL to use a non-superuser role without the BYPASSRLS attribute, or RLS policies will be silently ignored.

3. Transaction Wrapping Issues

The RLS extension wraps every query in a batch transaction. This means:

• Explicit $transaction() calls may not work as intended
• Nested transactions can fail or behave unexpectedly
• No current way to detect if a query is already inside a transaction

4. SQL Injection Risks

RLS implementations often use executeRawUnsafe or $queryRawUnsafe to set session variables (like SET LOCAL app.user_id). These methods are vulnerable to SQL injection if user input isn't properly sanitized.

5. Example-Only Status

Prisma's official RLS extension is marked as "provided as an example only and is not intended to be used in production environments" - you need to thoroughly test and potentially modify it for production use.

6. Session Variable Management

Setting Postgres session variables (SET LOCAL) for RLS requires raw SQL execution, which:

• Must be done per-request with proper connection pooling
• Can leak between requests if not properly scoped
• Requires careful coordination with Prisma's connection management

7. Per-Request Client Instances

Effective RLS requires creating a new Prisma Client instance per HTTP request (with user-specific context), which increases memory overhead and connection pool pressure compared to singleton clients.

Sources:

• Prisma Client Extensions - Row Level Security Example
• Prisma Client Extensions Documentation
• Support for row-level security (RLS) · Issue #12735

ZenStack simplifies multi-tenancy implementation by eliminating manual tenant filtering that you must write with raw Prisma. Here's how:

With Raw Prisma:
You must manually add tenant filters to every database query:

// Every query needs manual tenant filtering
const posts = await prisma.post.findMany({
  where: { tenantId: currentUser.tenantId }
});

const post = await prisma.post.update({
  where: { 
    id: postId,
    tenantId: currentUser.tenantId // Easy to forget!
  },
  data: { ... }
});

With ZenStack:
You define access policies once in your schema, then automatic enforcement everywhere:

model Post {
  id String @id
  orgId String
  ownerId String
  
  // Define policies once in schema
  @@deny('all', auth() == null)
  @@deny('all', auth().currentOrgId != orgId)
  @@allow('all', auth().userId == ownerId || auth().currentOrgRole == 'org:admin')
  @@allow('create', ownerId == auth().userId)
}

Then use the enhanced Prisma client:

const db = enhance(prisma, { user: currentUser });

// Automatic tenant filtering - no manual where clauses needed
const posts = await db.post.findMany(); // Only returns accessible posts

// Automatic authorization - rejects if unauthorized
await db.post.update({ where: { id }, data: { ... } });

Key Advantages:

1. Single source of truth - Access policies live with your data model
2. Automatic enforcement - No manual filtering in every query
3. Works everywhere - React hooks, tRPC routers, API routes all get automatic protection
4. Prevents mistakes - Impossible to forget tenant filters
5. Evolves with schema - Policies update automatically when models change

Sources:

• Multi-Tenancy Implementation Approaches With Prisma and ZenStack | ZenStack
• Enhanced Prisma Client | ZenStack
• GitHub - zenstackhq/zenstack

Based on my search of Prisma's official documentation, I found information about multi-tenancy approaches but no explicit recommendation specifically labeled "for highly regulated industries."

However, Prisma's Data Guide indicates that database-per-tenant provides the strongest data isolation when compliance is a concern:

For applications requiring very high levels of privacy as a feature or to conform to standards/regulations, traditional databases give you the most control. Data for different clients can be placed in different databases, on different servers, or in different physical locations to maintain strict separation.

Prisma supports three main multi-tenancy patterns:

1. Database-per-tenant - Highest isolation, separate databases for each tenant
2. Schema-per-tenant - Multiple schemas within one database (PostgreSQL, CockroachDB, SQL Server)
3. Shared schema with Row-Level Security (RLS) - Single schema with tenant isolation via policies

While not explicitly stated as "the recommendation for highly regulated industries," the documentation's emphasis on maximum control and strict separation through database-per-tenant architecture aligns with regulatory requirements for data isolation.

Note: I could not find a specific official statement from Prisma that says "use database-per-tenant for highly regulated industries." The inference is based on their guidance about privacy and compliance requirements.

Sources:

• How to use multiple databases in a single app | Prisma Documentation
• Data Modeling | Know Your Problem Space | Prisma's Data Guide
• How to use Prisma ORM with multiple database schemas | Prisma Documentation

Based on my search of the official Prisma documentation, I can now provide you with the authoritative answer:

Connection Switching Between Tenant Schemas in Prisma

Prisma supports two primary approaches for implementing connection switching between tenant schemas:

1. Using the schema Query Parameter in Connection URL

For PostgreSQL, you can specify the schema directly in the connection string:

postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=SCHEMA_NAME

If omitted, Prisma defaults to the public schema.

2. Using the PrismaPg Driver Adapter with Dynamic Schema Option

The recommended approach for runtime schema switching uses the @prisma/adapter-pg driver adapter:

import { PrismaClient } from '@prisma/client'
import { PrismaPg } from '@prisma/adapter-pg'

const adapter = new PrismaPg(
  { connectionString },
  { schema: 'tenant_schema_name' }  // Specify schema at runtime
)

const prisma = new PrismaClient({ adapter })

This allows you to dynamically instantiate separate PrismaClient instances for different tenant schemas.

3. Multi-Schema Declaration in Prisma Schema File

For PostgreSQL, CockroachDB, and SQL Server, you can declare multiple schemas in your schema.prisma file:

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
  schemas  = ["public", "tenant1", "tenant2"]
}

model User {
  id   Int    @id
  name String
  @@schema("tenant1")
}

Important Limitation: Each PrismaClient instance requires its own database connection, so you typically cache and reuse client instances per tenant to avoid connection pool exhaustion.

Sources:

• How to use Prisma ORM with multiple database schemas | Prisma Documentation
• PostgreSQL database connector | Prisma Documentation
• Connection URLs (Reference) | Prisma Documentation
• How to use multiple Prisma Clients in a single app | Prisma Documentation

The enhance() API wraps a Prisma Client to automatically enforce access policies and field validations defined in your ZenStack schema. When you call enhance(prisma, context), it returns an enhanced client that has the same API as Prisma Client but applies runtime authorization rules based on the user context you provide.

How It Works

Function signature:

enhance<DbClient>(prisma: DbClient, context?: EnhancementContext, options?: EnhancementOptions): DbClient

Parameters:

• prisma: The PrismaClient instance to enhance
• context: Optional object with user information, typically { user: { id, role, currentOrgId, ... } }
• options: Optional configuration (e.g., { kinds: ['policy', 'validation'] })

What it does:

1. Creates a wrapper around PrismaClient that intercepts all database operations
2. Evaluates access policy rules (defined with @@allow and @@deny in your schema) using the provided context
3. Automatically filters read operations to exclude inaccessible records
4. Rejects write operations that violate access policies
5. Applies field validation, omission, and other enhancements

Tenant Isolation Application

The enhance() API applies tenant isolation through access policy rules in your schema:

model Post {
  id     String @id
  orgId  String
  title  String
  
  @@deny('all', auth().currentOrgId != orgId)
}

At runtime:

const enhanced = enhance(prisma, { 
  user: { id: userId, currentOrgId: orgId } 
});

// Only returns posts where orgId matches user's currentOrgId
const posts = await enhanced.post.findMany();

The enhanced client automatically injects tenant filtering into all queries and validates tenant ownership on mutations, ensuring users can only access data belonging to their organization. This happens transparently—no manual WHERE clauses needed.

Sources:

• Runtime API Reference | ZenStack
• Multi-Tenancy Implementation Approaches With Prisma and ZenStack | ZenStack
• Access Policy | ZenStack
• When Embedded AuthN Meets Embedded AuthZ - Building Multi-Tenant Apps With Better-Auth and ZenStack | ZenStack

Use Prisma Client extensions with the $allModels query component to automatically set tenantId on all create operations across all models:

const prisma = new PrismaClient().$extends({
  query: {
    $allModels: {
      async create({ args, query }) {
        args.data = { 
          ...args.data, 
          tenantId: getCurrentTenantId() // your tenant ID logic
        }
        return query(args)
      },
      async createMany({ args, query }) {
        args.data = args.data.map(item => ({
          ...item,
          tenantId: getCurrentTenantId()
        }))
        return query(args)
      }
    }
  }
})

Key points:

1. $allModels applies the extension to all models in your schema
2. Hook into specific operations (create, createMany, update, etc.) or use $allOperations for all operations
3. Modify args.data before passing to query(args)
4. Maintain type safety - extensions are fully typed
5. Can also filter queries automatically:

const prisma = new PrismaClient().$extends({
  query: {
    $allModels: {
      async $allOperations({ operation, args, query }) {
        if (['findMany', 'findFirst', 'findUnique'].includes(operation)) {
          args.where = { ...args.where, tenantId: getCurrentTenantId() }
        }
        if (['create', 'update'].includes(operation)) {
          args.data = { ...args.data, tenantId: getCurrentTenantId() }
        }
        return query(args)
      }
    }
  }
})

Note: Middleware was deprecated in v4.16.0 and removed in v6.14.0. Client extensions are the modern, type-safe replacement.

Sources:

• Prisma Client extensions: query component | Prisma Documentation
• Middleware (Reference) | Prisma Documentation

Based on my search, I was unable to find official Prisma documentation that specifically addresses tenant size recommendations for shared schema with RLS.

What I Found:

Prisma's official documentation covers:

• How to implement RLS using Prisma Client extensions
• Multi-database support for multi-tenant applications
• Row-level security implementation examples

However, Prisma does not provide official guidance on when shared schema with RLS is best suited based on tenant size in their documentation.

The information about tenant size recommendations (e.g., "shared schema is best for small to medium tenants") comes from third-party blog posts and community discussions, not from authoritative Prisma documentation.

UNABLE_TO_VERIFY: Prisma's official documentation does not contain specific recommendations about which tenant sizes are best suited for shared schema with RLS approach. This guidance appears only in community sources and third-party blogs, not in authoritative Prisma documentation.

Sources:

• Prisma Client extensions | Prisma Documentation
• Prisma Client Just Became a Lot More Flexible: Prisma Client Extensions
• How to use multiple databases in a single app | Prisma Documentation

For database-per-tenant architecture, you need to create one PrismaClient instance per tenant database and manage them in a connection pool or registry.

Key Approach

1. Maintain a client registry: Store PrismaClient instances in a Map or cache, keyed by tenant identifier
2. Lazy instantiation: Create a new PrismaClient only when a tenant is first accessed
3. Reuse instances: Always retrieve and reuse the existing client for a tenant rather than creating new ones

Connection Pool Considerations

• Each PrismaClient instance creates its own connection pool with size: num_physical_cpus * 2 + 1
• Multiple clients can exhaust database connection limits quickly
• Each client increases memory usage

Recommended Pattern

const clients = new Map<string, PrismaClient>();

function getPrismaClient(tenantId: string): PrismaClient {
  if (!clients.has(tenantId)) {
    const databaseUrl = getTenantDatabaseUrl(tenantId);
    clients.set(tenantId, new PrismaClient({
      datasources: { db: { url: databaseUrl } }
    }));
  }
  return clients.get(tenantId)!;
}

Mitigations for Connection Exhaustion

• Use an external connection pooler like PgBouncer to manage connections across multiple PrismaClient instances
• Implement client eviction strategies if supporting many tenants
• Monitor total connection count across all tenant databases

Important: Prisma is not optimized for many-client scenarios but typically handles moderate numbers of tenants well.

Sources:

• Connection pool | Prisma Documentation
• Instantiating Prisma Client | Prisma Documentation
• How to use multiple databases in a single app | Prisma Documentation
• Database connections | Prisma Documentation

The Exact<Input, Shape> type utility in Prisma Client enforces strict type safety by ensuring that a generic type Input strictly complies with the type specified in Shape and narrows Input down to the most precise types.

Purpose

Exact is primarily used in Prisma Client extensions to prevent type widening and ensure that arguments passed to custom methods strictly match the expected type structure. It provides compile-time type checking and prevents excess properties from being passed.

Usage Example

type CacheStrategy = { swr: number; ttl: number }

const prisma = new PrismaClient().$extends({
  model: {
    $allModels: {
      findMany<T, A>(
        this: T,
        args: Prisma.Exact<
          A,
          Prisma.Args<T, 'findMany'> & CacheStrategy
        >
      ): Prisma.Result<T, A, 'findMany'> {
        // method implementation with cache strategy
      },
    },
  },
})

// Usage with strict type checking
await prisma.post.findMany({
  cacheStrategy: {
    ttl: 360,
    swr: 60,
  },
})

In this example, Exact ensures that the args parameter strictly matches the intersection of standard findMany arguments and the CacheStrategy type, providing type safety when extending Prisma Client functionality.

Sources:

• Prisma Client Extensions: Type utilities
• Type safety | Prisma Documentation

Based on the official Prisma documentation, here's how to extract types for included relations using GetPayload:

Use the Prisma.validator() pattern combined with Prisma.ModelGetPayload:

import { Prisma } from '@prisma/client'

// 1. Define a validator with the include/select options
const userWithPosts = Prisma.validator<Prisma.UserDefaultArgs>()({
  include: { posts: true },
})

// 2. Extract the type using GetPayload
type UserWithPosts = Prisma.UserGetPayload<typeof userWithPosts>

This works for any model in your schema. The pattern is:

• Prisma.validator<Prisma.{Model}DefaultArgs>() - validates your query options
• Prisma.{Model}GetPayload<typeof validator> - extracts the resulting type

You can also use select for partial types:

const userPersonalData = Prisma.validator<Prisma.UserDefaultArgs>()({
  select: { email: true, name: true },
})

type UserPersonalData = Prisma.UserGetPayload<typeof userPersonalData>

The key advantage: this type automatically stays synchronized with your Prisma schema, eliminating manual type maintenance.

Sources:

• Operating against partial structures of your model types | Prisma Documentation

Args<Type, Operation> is a Prisma type utility that retrieves the input arguments for any given model and operation.

Purpose:

• Enables type-safe access to operation argument types (like where, select, include, etc.)
• Primarily used by extension authors to reuse and extend existing Prisma types
• Provides IDE auto-completion for operation arguments

Type Parameters:

• Type: The Prisma model name (e.g., Prisma.UserDelegate)
• Operation: The operation name (e.g., 'findFirst', 'create', 'update')

Common Usage:
Access specific argument properties like Args<T, 'findFirst'>['where'] to extract the where clause type for a findFirst operation, or use the entire Args<T, 'create'> to get all create operation arguments.

Related Utilities:

• Result<Type, Arguments, Operation> - Returns the result type for given arguments and operation
• Payload<Type, Operation> - Retrieves the complete result structure including scalars and relations

Sources:

• Prisma Client Extensions: Type utilities | Prisma Documentation

To create strongly typed JSON fields in Prisma using prisma-json-types-generator:

Installation

npm install -D prisma-json-types-generator

Configuration

Add the generator to your schema.prisma file:

generator client {
  provider = "prisma-client-js"
}

generator json {
  provider = "prisma-json-types-generator"
  namespace = "PrismaJson"  // optional, defaults to "PrismaJson"
}

Usage

1. Define your TypeScript types

Create a type declaration file (e.g., src/types.ts) and declare your types in the global PrismaJson namespace:

// src/types.ts
export {};

declare global {
  namespace PrismaJson {
    type UserProfile = {
      theme: 'dark' | 'light';
      twitterHandle?: string;
    };
  }
}

Ensure this file is included in your tsconfig.json.

2. Annotate your schema

Use a triple-slash comment /// [TypeName] above the JSON field to link it to your custom type:

model User {
  id      Int    @id @default(autoincrement())
  email   String @unique
  /// [UserProfile]
  profile Json
}

3. Generate

Run:

npx prisma generate

The profile field will now be strongly typed as UserProfile instead of Prisma's default JsonValue.

Result

const user = await prisma.user.update({
  where: { id: 1 },
  data: {
    profile: {
      theme: 'dark',  // autocomplete and type checking!
      twitterHandle: '@example'
    }
  }
});

// Fully typed access
console.log(user.profile.theme); // TypeScript knows this is 'dark' | 'light'

Sources:

• prisma-json-types-generator - npm
• prisma-json-types-generator - GitHub

Based on the search results, I can see there are references to model, client, query, and result components. However, the question specifically asks for "three components" which conflicts with the documentation showing four component types. Let me verify the exact count from the authoritative source.

The official Prisma documentation shows that Prisma Client extensions have four component types, not three:

1. client - Adds custom methods at the top level of Prisma Client
2. model - Adds custom methods to specific models in your schema
3. query - Hooks into the query lifecycle to modify queries or results
4. result - Adds computed fields to query results

If the question assumes there are only three components, this may be outdated information. The current official documentation clearly lists four distinct component types.

Sources:

• Prisma Client extensions | Prisma Documentation
• Prisma Client extensions: client component | Prisma Documentation
• Prisma Client extensions: model component | Prisma Documentation
• Prisma Client extensions: query component | Prisma Documentation

Based on the official Prisma documentation found in the web search, here's how to add custom methods to Prisma models using model extensions:

Use prisma.$extends() with the model component to add custom methods to specific models:

const prisma = new PrismaClient().$extends({
  model: {
    user: {
      async signUp(email: string) {
        await prisma.user.create({ data: { email } })
      },
    },
  },
})

// Call the custom method
await prisma.user.signUp('[email protected]')

Key capabilities:

1. Add methods to specific models - Target individual models by name (e.g., user, post)

2. Access Prisma Client operations - Custom methods can call standard Prisma operations like create, findMany, etc.

3. Call custom methods from other custom methods - Use Prisma.getExtensionContext(this).methodName

4. Get model name at runtime - Use Prisma.getExtensionContext(this).$name

Common use cases:

• Encapsulate business logic
• Create reusable operations
• Add model-specific utilities
• Define custom operations alongside built-in Prisma methods

The extended Prisma Client instance includes both the custom methods and all standard Prisma Client operations.

Sources:

• Prisma Client extensions: model component | Prisma Documentation
• Prisma Client extensions | Prisma Documentation

Yes. You can use typeof to infer the type of a Prisma Client singleton with extensions.

For a direct extended client instance:

const extendedPrismaClient = new PrismaClient().$extends({ 
  // your extension
})
type ExtendedPrismaClient = typeof extendedPrismaClient

For a singleton pattern (factory function):

function getExtendedClient() {
  return new PrismaClient().$extends({ /* extension */ })
}
type ExtendedPrismaClient = ReturnType<typeof getExtendedClient>

When using a singleton pattern, combine typeof with ReturnType to extract the type of the extended client returned by your factory function. This preserves all extension types including custom models, methods, and result modifications.

Sources:

• Prisma Client extensions | Prisma Documentation
• Prisma Client Extensions: Type utilities | Prisma Documentation

Based on the official Prisma documentation search results, I can provide you with the verified answer:

TypeScript 5.1.0 is the minimum required version for Prisma ORM 6.

Sources:

• Upgrade to Prisma ORM 6 | Prisma Documentation
• System requirements (Reference) | Prisma Documentation

Based on the official Prisma documentation, here's how to create type-safe result extensions with computed fields:

Creating Type-Safe Result Extensions

Use the $extends() method with the result component to add computed fields to query results:

const prisma = new PrismaClient().$extends({
  result: {
    user: {
      fullName: {
        needs: { firstName: true, lastName: true },
        compute(user) {
          return `${user.firstName} ${user.lastName}`
        },
      },
    },
  },
})

const user = await prisma.user.findFirst()
console.log(user.fullName) // Type-safe access to computed field

Type Safety Mechanism

1. needs object: Declares which fields must be fetched from the database
2. compute function: Receives an automatically typed parameter based on needs
   • The user parameter is typed with only the fields specified in needs
   • Fields not in needs cannot be accessed in compute
3. Return value: Can be any type (string, number, object, function)

Important Constraints

• Computed fields can only be used with select
• You cannot aggregate computed fields
• If you omit a dependency field in your query, Prisma still fetches it from the database (but excludes it from results)

Advanced Type Utilities

For reusing types: Result<Type, Arguments, Operation> provides the result type for a given model and operation when building complex extensions.

Sources:

• Prisma Client extensions: result component | Prisma Documentation
• Computed fields | Prisma Documentation

Based on the official Prisma documentation, here are the key differences:

Query extensions are the modern replacement for middleware. Middleware was deprecated in v4.16.0 and removed in v6.14.0.

Key Differences:

1. Scope & Isolation

• Middleware: Always applies globally to the same Prisma Client instance
• Query Extensions: Isolated to specific extended clients, allowing multiple variants

2. Type Safety

• Middleware: No end-to-end type safety or inference
• Query Extensions: Full type safety and TypeScript inference

3. Flexibility

• Middleware: Single global client only - you cannot choose which client to use
• Query Extensions: Choose between standard client, one extended client, or multiple extended clients at runtime

4. Execution Order
When both exist, Prisma Client executes middleware first, then query extensions, in the order they were instantiated with $use() or $extends().

Migration Path:

Query extensions cover all middleware use cases. Prisma officially recommends migrating from middleware to the query component type of Client extensions for better type safety, isolation, and flexibility.

Sources:

• Middleware (Reference) | Prisma Documentation
• Prisma Client extensions: query component | Prisma Documentation
• Prisma Client extensions | Prisma Documentation

Prisma generates TypeScript types for your models that you can import directly from @prisma/client.

Basic model types:

import { User, Post, Product } from '@prisma/client'

const user: User = {
  id: 1,
  email: '[email protected]',
  name: 'John'
}

Each model in your schema becomes an importable type with the same name.

Accessing types via the Prisma namespace:

import { Prisma } from '@prisma/client'

// For input types, helper types, etc.
type UserCreateInput = Prisma.UserCreateInput
type UserWhereInput = Prisma.UserWhereInput

For custom types with relations or partial fields:

import { Prisma } from '@prisma/client'

// Define the shape
const userWithPosts = Prisma.validator<Prisma.UserDefaultArgs>()({
  include: { posts: true }
})

// Extract the type
type UserWithPosts = Prisma.UserGetPayload<typeof userWithPosts>

All generated types are located in node_modules/.prisma/client/index.d.ts after running prisma generate.

Sources:

• Type safety | Prisma Documentation
• Operating against partial structures of your model types | Prisma Documentation
• Models | Prisma Documentation

Based on the official Prisma documentation search results, here's the authoritative answer:

For Cloudflare Workers with Prisma Accelerate:

Use @prisma/client/edge:

import { PrismaClient } from '@prisma/client/edge'
import { withAccelerate } from '@prisma/extension-accelerate'

For Cloudflare Workers with Driver Adapters (D1, PostgreSQL):

Use the standard import @prisma/client:

import { PrismaClient } from '@prisma/client'

Or if using a custom output directory:

import { PrismaClient } from './generated/client'

Key distinction: The /edge import path is specifically for Prisma Accelerate deployments. When using driver adapters (like @prisma/adapter-d1 for Cloudflare D1 or @prisma/adapter-pg for PostgreSQL), use the standard @prisma/client import instead.

Sources:

• Deploy to Cloudflare Workers & Pages | Prisma Documentation
• How to use Prisma ORM and Prisma Postgres with Cloudflare Workers | Prisma Documentation

Prisma cannot connect directly to traditional PostgreSQL/MySQL databases from edge functions because edge runtimes (like Cloudflare Workers and Vercel Edge Functions) do not support traditional TCP connections.

Traditional PostgreSQL and MySQL databases require long-lived TCP connections to communicate with clients. However, edge functions run on V8 isolates or restricted JavaScript runtimes that only support HTTP-based connections, not arbitrary TCP socket connections.

Technical limitations:

1. No TCP socket support - Edge runtimes restrict network access to HTTP/HTTPS protocols only
2. Connection model mismatch - Traditional databases expect stateful, persistent TCP connections, but edge functions are stateless and ephemeral
3. V8 engine constraints - The underlying V8 engine in edge runtimes doesn't provide TCP socket APIs

Workarounds:

• Use HTTP-based database drivers (Neon Serverless, PlanetScale Serverless)
• Use Prisma Accelerate as a connection proxy
• Use databases designed for edge runtimes (Prisma Postgres, Cloudflare D1)
• Use driver adapters with edge-compatible database drivers

Sources:

• Overview: Deploy Prisma ORM at the Edge | Prisma Documentation
• Prisma ORM Support for Edge Functions is Now in Preview
• Database Access in Serverless Environments with the Prisma Data Proxy

Based on the official documentation from my web search, I can provide the authoritative answer:

Cloudflare Workers Free Plan Bundle Size Limit

1 MB after compression for the Free plan (3 MB for Paid plan).

How This Affects Prisma

Prisma's traditional deployment approach bundles the Query Engine with the Prisma Client, which creates bundle size challenges:

1. Engine Size Issue: Prisma Client with bundled engines frequently exceeds the 1 MB limit on Cloudflare Workers free plan
2. Deployment Blocker: This makes standard Prisma ORM incompatible with Cloudflare Workers free tier without workarounds

Solutions

Prisma Accelerate: Use Prisma's edge-optimized client that doesn't bundle the query engine. The engine runs remotely via Prisma Accelerate, dramatically reducing bundle size to fit within the 1 MB constraint.

Paid Plan: Upgrade to Cloudflare Workers Paid plan (3 MB limit after compression, 10 MB for newer accounts) to accommodate the full Prisma Client with bundled engines.

Sources:

• Limits · Cloudflare Workers docs
• Deploy to Cloudflare Workers & Pages | Prisma Documentation

Based on the official Prisma documentation, I have the authoritative answer:

engineType = "client" removes Rust binaries from the Prisma bundle.

This configuration enables Prisma ORM without Rust engines, eliminating the need to download or ship the Rust query engine binary. It reduces bundle size by approximately 90% (from ~14MB to 1.6MB).

Configuration:

generator client {
  provider   = "prisma-client-js"
  engineType = "client"
}

Requirements:

• Available since Prisma v6.16.0 (Generally Available)
• Requires driver adapters to be configured
• The engine runs entirely in TypeScript and WebAssembly instead of native Rust binaries

Sources:

• Use Prisma ORM without Rust engines | Prisma Documentation
• Engines | Prisma Documentation

Prisma version 6.16.0 made engineType = "client" generally available for edge deployments.

This release marked the Rust-free version of Prisma ORM as production-ready, allowing developers to use Prisma without Rust engine binaries. Key benefits include:

• No binary overhead (eliminates Rust binary dependencies)
• Smaller bundle sizes for edge deployments
• Better support for edge runtimes (Cloudflare Workers, Vercel Edge, Deno, Bun)

To use it, configure your Prisma schema:

generator client {
  provider = "prisma-client"
  engineType = "client"
}

Note: You must install a driver adapter manually (since the Rust engine that previously bundled database drivers has been removed).

Sources:

• Release 6.16.0 · prisma/prisma
• Rust-free Prisma ORM is Ready for Production
• Overview: Deploy Prisma ORM at the Edge

Based on the search results from official Prisma documentation, the primary challenge when developing edge functions locally with Prisma is:

Prisma Accelerate does not work with local databases. This creates a development workflow issue because developers typically want to use local databases during development to minimize costs, but Accelerate (which provides connection pooling and global caching for edge environments) only works with hosted databases.

Additional underlying challenges include:

• No TCP connection support: Edge runtimes lack native support for TCP-based database connections that traditional databases require
• Runtime limitations: Edge functions run in constrained environments (V8 isolates, Deno) with limited Node.js APIs and restricted CPU/memory
• Stateless architecture: Edge functions are stateless, conflicting with the stateful nature of relational databases where each request needs a connection

The recommended workaround is to conditionally extend Prisma Client with the Accelerate extension only in production, allowing local database usage in development while enabling Accelerate's pooling and caching in production edge environments.

Sources:

• Accelerate: Local development | Prisma Documentation
• Overcoming Database Challenges in Serverless and Edge Applications
• Overview: Deploy Prisma ORM at the Edge | Prisma Documentation

Driver adapters in Prisma are translators that sit between Prisma Client and JavaScript-native database drivers, enabling Prisma to communicate with databases using HTTP or WebSocket connections instead of direct TCP connections.

Why they're needed for edge runtimes:

Edge runtimes (Vercel Edge Functions, Cloudflare Workers, Deno Deploy) run in constrained JavaScript environments (V8 isolates) that:

1. Don't support the full Node.js runtime
2. Cannot freely open TCP connections to traditional databases
3. Have limited CPU and memory resources

Traditional Prisma requires direct TCP connections to databases, which edge runtimes don't provide. Driver adapters solve this by allowing Prisma to use edge-compatible JavaScript drivers that communicate over HTTP/WebSocket instead.

How they work:

import { PrismaClient } from '@prisma/client'
import { PrismaPg } from '@prisma/adapter-pg'
import { Pool } from 'pg'

const pool = new Pool({ connectionString: url })
const adapter = new PrismaPg(pool)
const prisma = new PrismaClient({ adapter })

The adapter maintains the connection pool through the native JS driver, transforming Prisma queries to SQL and executing them via the edge-compatible driver.

Available adapters: @prisma/adapter-neon, @prisma/adapter-planetscale, @prisma/adapter-pg, @prisma/adapter-libsql, among others.

Sources:

• Overview: Deploy Prisma ORM at the Edge | Prisma Documentation
• Database drivers | Prisma Documentation
• Deploy to Vercel Edge Functions & Middleware | Prisma Documentation

Based on the official documentation I've found, here's the verified answer:

Neon provides @neondatabase/serverless (also available as @neon/serverless on JSR) - a low-latency Postgres driver for JavaScript and TypeScript that works over HTTP or WebSockets instead of TCP, compatible with Vercel Edge Functions, Cloudflare Workers, and other V8 isolate-based runtimes.

PlanetScale provides @planetscale/database - a Fetch API-compatible MySQL database driver that operates over HTTP connections, enabling use in Cloudflare Workers, Vercel Edge Functions, and Netlify Edge Functions.

Both drivers solve the same problem: traditional database drivers use TCP connections which are blocked in many edge environments. These serverless drivers use HTTP/WebSockets instead, making them compatible with constrained edge runtimes.

For Prisma ORM integration, use the corresponding adapter packages:

• @prisma/adapter-neon for Neon
• @prisma/adapter-planetscale for PlanetScale

Sources:

• Neon serverless driver - Neon Docs
• GitHub - neondatabase/serverless
• Introducing the PlanetScale serverless driver for JavaScript
• PlanetScale serverless driver documentation
• GitHub - planetscale/database-js
• Database drivers | Prisma Documentation

Yes. Prisma Postgres is fully supported on edge runtimes without requiring Accelerate.

Prisma Postgres has native edge runtime compatibility and does not require a specialized edge-compatible driver or Prisma Accelerate. This makes it directly deployable to edge environments like:

• Vercel Edge Functions & Middleware
• Cloudflare Workers & Pages
• Deno Deploy
• AWS Lambda
• Bun

The Prisma Postgres serverless client library includes built-in features for edge environments:

• Row-by-row result streaming
• Query pipelining for reduced latency
• Full TypeScript support

Note: For other PostgreSQL providers (not Prisma Postgres), you would need either:

1. Driver adapters (Preview feature as of v5.11.0+), or
2. Prisma Accelerate for full edge compatibility

Prisma Postgres is specifically designed for edge deployments and requires no additional configuration or adapters.

Sources:

• Overview: Deploy Prisma ORM at the Edge | Prisma Documentation
• Deploy to Vercel Edge Functions & Middleware | Prisma Documentation
• Prisma ORM Support for Edge Functions is Now in Preview

Based on the official Prisma documentation search results, here's the authoritative answer:

In Prisma schema, you define a one-to-many relation by:

1. On the "many" side: Add a relation field and a relation scalar field (foreign key)
2. On the "one" side: Add a relation field with an array type

Example:

model User {
  id    Int    @id @default(autoincrement())
  posts Post[]
}

model Post {
  id       Int  @id @default(autoincrement())
  author   User @relation(fields: [authorId], references: [id])
  authorId Int
}

Key components:

• Post[] - Array syntax on the "one" side (User can have many Posts)
• author User @relation(fields: [authorId], references: [id]) - Relation field on the "many" side with @relation attribute
• authorId Int - Foreign key scalar field that stores the actual reference
• fields: [authorId] - Points to the foreign key field in the current model
• references: [id] - Points to the referenced field in the related model

The foreign key (authorId) is always stored on the "many" side of the relation.

Sources:

• One-to-many relations | Prisma Documentation

Based on the official Prisma documentation, here are the key differences:

Implicit Many-to-Many Relations

Implicit relations do not have a relation table in your Prisma schema - Prisma manages the join table automatically in the database. You define the relation by simply referencing arrays of the related model on both sides.

• No explicit relation/join table model in schema
• Simpler Prisma Client API (fewer nesting levels in queries)
• Both models must have a single @id
• No @relation attribute needed
• Use when: You don't need to store metadata in the join table

Example:

model Post {
  id         Int        @id @default(autoincrement())
  categories Category[]
}

model Category {
  id    Int    @id @default(autoincrement())
  posts Post[]
}

Explicit Many-to-Many Relations

Explicit relations define the join table as an actual model in your Prisma schema with foreign keys to both related models.

• Join table appears as a model in schema
• Can store additional fields (metadata like timestamps, order, etc.)
• Requires three models total
• More verbose queries (additional nesting level)
• Use when: You need to store extra data in the relation table

Example:

model Post {
  id         Int                 @id @default(autoincrement())
  categories CategoriesOnPosts[]
}

model Category {
  id    Int                 @id @default(autoincrement())
  posts CategoriesOnPosts[]
}

model CategoriesOnPosts {
  post       Post     @relation(fields: [postId], references: [id])
  postId     Int
  category   Category @relation(fields: [categoryId], references: [id])
  categoryId Int
  assignedAt DateTime @default(now())

  @@id([postId, categoryId])
}

Sources:

• Many-to-many relations | Prisma Documentation

Define a composite primary key using @@id at the model level with an array of field names:

model User {
  firstName String
  lastName  String
  email     String @unique
  
  @@id([firstName, lastName])
}

For many-to-many join tables, a common pattern:

model PostToCategory {
  postId     Int
  categoryId Int
  post       Post     @relation(fields: [postId], references: [id])
  category   Category @relation(fields: [categoryId], references: [id])

  @@id([postId, categoryId])
}

You can optionally name the composite ID:

model User {
  firstName String
  lastName  String
  
  @@id(name: "userCompoundId", [firstName, lastName])
}

Important: MongoDB does not support @@id - use @id on a single field instead.

In Prisma Client, the composite key is accessible as firstName_lastName and can be used with findUnique():

await prisma.user.findUnique({
  where: {
    firstName_lastName: {
      firstName: "John",
      lastName: "Doe"
    }
  }
})

Sources:

• Prisma Schema API Reference
• Working with Compound IDs and Unique Constraints
• Models Documentation

No, the MongoDB connector does not support composite IDs (@@id) in Prisma.

MongoDB's primary key is always the _id field, which must be a single field with an @id attribute. You cannot use @@id to define a multi-field ID on MongoDB models.

What IS supported:

• Composite unique constraints (@@unique) - you can define unique constraints across multiple fields
• Composite types (embedded documents) - allows nesting records within records

Example of what doesn't work:

model User {
  firstName String
  lastName  String
  
  @@id([firstName, lastName]) // ❌ Not supported on MongoDB
}

What you must use instead:

model User {
  id        String @id @default(auto()) @map("_id") @db.ObjectId
  firstName String
  lastName  String
  
  @@unique([firstName, lastName]) // ✅ Composite unique constraint works
}

Sources:

• Working with compound IDs and unique constraints (Concepts) | Prisma Documentation
• MongoDB database connector | Prisma Documentation

Use the @@index attribute on your model with an array of field names:

model User {
  id    Int    @id @default(autoincrement())
  email String
  phone String
  
  @@index([email, phone])
}

You can optionally name the index:

model User {
  id    Int    @id @default(autoincrement())
  email String
  phone String
  
  @@index([email, phone], name: "email_phone_idx")
}

The @@index attribute creates a non-unique compound index. For field order, the first field in the array becomes the leading column in the index, which affects query performance when using subsets of the indexed columns.

If you need uniqueness on multiple fields, use @@unique instead:

@@unique([email, phone])

Sources:

• Indexes | Prisma Documentation
• Prisma Schema API Reference

Based on the official Prisma documentation, when you don't add an index on relation fields with relationMode = "prisma":

Performance Impact:
Queries on those relation fields may require full table scans, which are slow and expensive (especially on database providers that bill per accessed row).

Why This Happens:
When relationMode = "prisma", Prisma emulates foreign key constraints at the ORM level instead of using database-level foreign keys. This means the database won't automatically create indexes on relation fields, unlike with standard foreign key constraints.

Warning Behavior:
Starting in Prisma ORM version 4.7.0+, you'll receive a warning when your schema contains relation fields without a corresponding index.

Example:

// ⚠️ Will trigger warning - missing index
datasource db {
  provider     = "mysql"
  relationMode = "prisma"
}

model Post {
  id     Int  @id
  userId Int
  user   User @relation(fields: [userId], references: [id])
}

// ✅ Correct - index added
model Post {
  id     Int  @id
  userId Int
  user   User @relation(fields: [userId], references: [id])
  
  @@index([userId])
}

Sources:

• Manage relations between records with relation modes in Prisma | Prisma Documentation

Based on the official Prisma documentation, here's how to specify index sort order:

In Prisma schema, use the sort parameter within index definitions with Asc or Desc values:

model Post {
  id     Int    @id @default(autoincrement())
  title  String
  author String
  
  @@index([title(sort: Asc), author(sort: Desc)])
}

For unique constraints:

model User {
  id        Int    @id @default(autoincrement())
  email     String
  username  String
  
  @@unique([email(sort: Desc), username(sort: Asc)])
}

Key details:

• Available on @@index, @unique, and @@unique for all databases
• Also available on @id and @@id for SQL Server
• Generally available since Prisma 4.0.0 (preview in 3.5.0+ with extendedIndexes feature flag)
• PostgreSQL: sort order only works on indexes, not unique constraints
• MySQL/MariaDB: works on both indexes and unique constraints

Sources:

• Indexes | Prisma Documentation

Based on the official Prisma documentation, here's how to define an enum and set a default value:

Enum Definition with Default Value

Define the enum using an enum block, then reference it in your model with the @default attribute:

model User {
  id    Int    @id @default(autoincrement())
  email String @unique
  name  String?
  role  Role   @default(USER)
}

enum Role {
  USER
  ADMIN
  MODERATOR
}

Syntax:

• enum EnumName { VALUE1 VALUE2 VALUE3 } - Define enum values (one per line or space-separated)
• fieldName EnumType @default(VALUE) - Set default value on the field

Database Support:

• Native support: PostgreSQL, MySQL
• Not supported: Microsoft SQL Server

Additional Options:

• Use @map to map enum values to different database names
• Use @@map to map the entire enum name

enum Role {
  USER      @map("user")
  ADMIN     @map("admin")
  @@map("user_role")
}

Sources:

• Prisma Schema API Reference
• Models | Prisma Documentation