Skip to content

docs: update local development guide for Prisma 7 Accelerate #7421

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
therbta wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: update local development guide for Prisma 7 Accelerate #7421

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 17 additions & 3 deletions content/300-accelerate/580-local-development.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,12 @@ Accelerate does not work with a local database. However, in a development enviro

The following steps outline how to use Prisma ORM and Prisma Accelerate with a local PostgreSQL database.

### Prisma 7

**Note:** In Prisma 7, the Accelerate extension requires a connection string starting with `prisma://` or `prisma+postgres://`. Using a local database connection string with the Accelerate extension will cause an error.

To use a local database in development with Prisma 7, use the `@prisma/adapter-pg` adapter conditionally:

1. Update the `DATABASE_URL` environment variable with your local database's connection string:

```.env
Expand All @@ -41,16 +47,24 @@ The following steps outline how to use Prisma ORM and Prisma Accelerate with a l

> Note: The `--no-engine` flag should only be used in preview and production environments. The command generates Prisma Client artifacts without a [Query Engine](/orm/more/under-the-hood/engines) file, which requires an Accelerate connection string.

3. Set up Prisma Client with the Accelerate client extension:
3. Set up Prisma Client with conditional logic for development and production:

```typescript
import { PrismaClient } from '@prisma/client'
import { withAccelerate } from '@prisma/extension-accelerate'
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)
```
Comment on lines +55 to 65
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 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

  1. 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]

  1. 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]

  • 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]

  • 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:

  1. withAccelerate() returns a Prisma Client extension (used with .$extends())
  2. new PrismaPg(pool) returns a driver adapter (required in the PrismaClient constructor)

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.
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion | 🟠 Major

Clarify environment variable configuration.

The note mentions setting ACCELERATE_URL in production but doesn't explain:

  1. That ACCELERATE_URL should contain your Prisma Accelerate connection string (starting with prisma:// or prisma+postgres://)
  2. How this differs from DATABASE_URL (which contains the direct database URL)
  3. 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 string
  • ACCELERATE_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).


![Using Prisma Accelerate client extension in production](/img/accelerate/accelerate-in-prod.png)

Expand Down