docs: update local development guide for Prisma 7 Accelerate #7421
Conversation
- Add Prisma 7 section explaining Accelerate URL requirements - Show workaround using @prisma/adapter-pg for local development - Provide conditional setup for dev/prod environments
WalkthroughThis documentation update addresses Prisma 7 compatibility for local Accelerate development. It clarifies that Accelerate requires URLs starting with Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Pre-merge checks✅ Passed checks (5 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
content/300-accelerate/580-local-development.mdx
🔇 Additional comments (2)
content/300-accelerate/580-local-development.mdx (2)
30-34: Clear explanation of Prisma 7 requirements.The note effectively communicates the constraint and introduces the conditional adapter approach as a solution.
50-50: Accurate step description.The updated heading correctly describes the conditional setup being demonstrated.
| import { PrismaPg } from '@prisma/adapter-pg' | ||
| import { Pool } from 'pg' | ||
|
|
||
| const pool = new Pool({ connectionString: process.env.DATABASE_URL }) | ||
|
|
||
| const adapter = process.env.ACCELERATE_URL | ||
| ? withAccelerate() // Production: Use Accelerate | ||
| : new PrismaPg(pool) // Development: Use pg adapter | ||
|
|
||
| const prisma = new PrismaClient().$extends(withAccelerate()) | ||
| const prisma = new PrismaClient().$extends(adapter) | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Prisma 7 withAccelerate extension API documentation
💡 Result:
You can find the Prisma 7 withAccelerate extension API docs and usage examples here:
- Official Accelerate overview and examples (includes using withAccelerate and query caching). [1]
- Guide: using Prisma Accelerate (Neon connection-pool + how to apply withAccelerate to PrismaClient). [2]
- npm package for @prisma/extension-accelerate (install, version, brief usage snippet). [3]
Minimal usage example:
import { PrismaClient } from '@prisma/client'
import { withAccelerate } from '@prisma/extension-accelerate'
const prisma = new PrismaClient().$extends(withAccelerate())
await prisma.user.findMany({ cacheStrategy: { ttl: 30, swr: 60 } })
Sources:
[1] Prisma Docs — Accelerate overview & examples.
[2] Prisma Docs — Guides: Neon + Accelerate (setup & generate client).
[3] npm — @prisma/extension-accelerate package (install and README).
🌐 Web query:
Prisma 7 PrismaPg driver adapter API constructor vs extends
💡 Result:
Short answer: Prisma 7 requires passing a driver adapter (e.g. PrismaPg) into PrismaClient. You can either instantiate PrismaClient with the adapter, or subclass/extend PrismaClient and forward the adapter to super — both are equivalent; the difference is just where you construct/hold the adapter and how you type the constructor.
Examples and tips
- Plain instantiation (recommended when you don't need custom subclass behavior)
- Create adapter, pass into PrismaClient:
import { PrismaClient } from '@prisma/client'
import { PrismaPg } from '@prisma/adapter-pg'
const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
const prisma = new PrismaClient({ adapter })
(Prisma docs show this pattern). [1][2]
- Extending PrismaClient (useful for framework services, lifecycle hooks, or adding methods)
-
Define an options interface that includes adapter, then forward to super. You may need to cast to satisfy TypeScript because PrismaClient's built-in options don't declare the adapter property yet:
import { PrismaClient } from '@prisma/client'
import { PrismaPg } from '@prisma/adapter-pg'interface CustomPrismaOptions extends Omit<Prisma.PrismaClientOptions, 'datasources'> {
adapter: PrismaPg
}class CustomPrismaClient extends PrismaClient {
constructor(options: CustomPrismaOptions) {
super(options as unknown as Prisma.PrismaClientOptions) // forward adapter to base ctor
}
}const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
const prisma = new CustomPrismaClient({ adapter })
Notes
- Functionally there’s no hidden magic: PrismaClient needs adapter in its options (or accelerateUrl). Passing it via new PrismaClient({ adapter }) or via super(...) is the same—just ensure TypeScript typing/casting when extending.
- Documentation shows the adapter-first pattern and gives the PrismaPg options (connectionString, optional schema). [1][2]
Sources
[1] Prisma docs — Database drivers / PostgreSQL driver + adapter examples.
[2] Prisma discussion and examples showing extending PrismaClient with PrismaPg adapter.
🌐 Web query:
Prisma Accelerate datasourceUrl connection configuration
💡 Result:
Short summary — how to configure Prisma Accelerate connection in your schema:
-
Use the Accelerate HTTP connection string as your datasource url (env var). Example .env and schema:
- .env:
DATABASE_URL="prisma://accelerate.prisma-data.net/?api_key=YOUR_API_KEY" - schema.prisma:
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
}
(Prisma will route queries through Accelerate.) [1][2][3]
- .env:
-
If you need Prisma CLI commands that require a direct DB TCP connection (migrate, introspect, Studio), add a direct connection env var and set directUrl in the datasource:
- .env:
DIRECT_DATABASE_URL="postgresql://user:pass@host:port/db?schema=public" - schema.prisma:
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
directUrl = env("DIRECT_DATABASE_URL")
}
Migrations/introspection use directUrl while runtime uses the accelerate url. [1][2][4]
- .env:
-
Notes/tips:
- For Prisma Postgres, Prisma Migrate/introspection can work with prisma+postgres:// (so directUrl may not be required). [3]
- When generating client for Accelerate production builds, use npx prisma generate --no-engine and apply the withAccelerate extension in code (withAccelerate()/@prisma/extension-accelerate). [2]
Sources: Prisma Accelerate docs and connection-URL/schema references. [1][2][3][4]
Critical: Driver adapter and extension patterns are incompatible in this code.
The code mixes two fundamentally different Prisma APIs:
withAccelerate()returns a Prisma Client extension (used with.$extends())new PrismaPg(pool)returns a driver adapter (required in thePrismaClientconstructor)
These cannot be used interchangeably. The code will fail at runtime in development because driver adapters must be passed to the PrismaClient constructor, not to .$extends().
The correct patterns are:
- Accelerate:
new PrismaClient().$extends(withAccelerate()) - pg adapter:
new PrismaClient({ adapter: new PrismaPg(pool) })
Rewrite the example to conditionally instantiate PrismaClient differently for each case—not to apply the same .$extends() call to both. Also add the missing installation step for @prisma/adapter-pg and pg.
🤖 Prompt for AI Agents
In content/300-accelerate/580-local-development.mdx around lines 55 to 65, the
example incorrectly mixes a Prisma Client extension and a driver adapter (using
the same pattern for both), which will fail at runtime; change the code so that
when process.env.ACCELERATE_URL is set you instantiate the client with new
PrismaClient().$extends(withAccelerate()) and when not set you instantiate with
new PrismaClient({ adapter: new PrismaPg(pool) }), i.e., pass the PrismaPg
driver into the PrismaClient constructor rather than to .$extends(); also add a
note to the doc showing the required install command for the pg adapter packages
(install @prisma/adapter-pg and pg).
| ``` | ||
|
|
||
| > The extended instance of Prisma Client will use the local database. Hence, Prisma Accelerate will not be used in your development environment to respond to your Prisma Client queries. | ||
| > In production, set `ACCELERATE_URL` to your Prisma Accelerate connection string. In development, omit this environment variable to use the local database via the pg adapter. |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Clarify environment variable configuration.
The note mentions setting ACCELERATE_URL in production but doesn't explain:
- That
ACCELERATE_URLshould contain your Prisma Accelerate connection string (starting withprisma://orprisma+postgres://) - How this differs from
DATABASE_URL(which contains the direct database URL) - The complete environment setup for both scenarios
Consider expanding this note to be more explicit:
Production setup:
DATABASE_URL: Your direct database connection string (used for migrations, introspection)ACCELERATE_URL: Your Prisma Accelerate connection string (prisma://...)Development setup:
DATABASE_URL: Your local PostgreSQL connection stringACCELERATE_URL: Omit this variable to use the local database via the pg adapter
🤖 Prompt for AI Agents
In content/300-accelerate/580-local-development.mdx around line 67, the note
about ACCELERATE_URL is ambiguous; update it to explicitly state that
ACCELERATE_URL is the Prisma Accelerate connection string (e.g., starting with
prisma:// or prisma+postgres://), explain that DATABASE_URL is the direct
database connection used for migrations/introspection, and replace the single
sentence with a short, explicit block showing both setups: Production
(DATABASE_URL = direct DB connection, ACCELERATE_URL = Prisma Accelerate
connection string) and Development (DATABASE_URL = local Postgres connection,
ACCELERATE_URL omitted to use local pg adapter).
1 participant
What this PR does
Updates the "Local development for Prisma Accelerate" guide to reflect Prisma 7 changes where the Accelerate extension requires a connection string starting with
prisma://orprisma+postgres://.Changes
@prisma/adapter-pgfor local developmentCloses #7377
Summary by CodeRabbit
Release Notes
✏️ Tip: You can customize this high-level summary in your review settings.