Prisma

Prisma Documentation Audit

The docs are broad, current in places, and machine-friendly on paper (llms.txt, llms-full.txt, a changelog.md index) — but they carry several years of un-regenerated example output and, more damaging, no single canonical answer for the two things every developer does first: where the generated client lives and how prisma init behaves. Two reference pages for the same command disagree, one CLI page contradicts itself about v7, and the core PrismaClient import path differs page to page.

1. No canonical generated-client path — output dir and import differ page to page (critical)

Location: /docs/orm/prisma-client, /docs/cli/init, /docs/orm/prisma-client/setup-and-configuration/introduction, /docs/postgres/database/connecting-to-your-database, /docs/orm/prisma-client/deployment/serverless/deploy-to-vercel

Problem: The single most-copied snippet in these docs — the output in the generator block and the matching PrismaClient import — has no consistent value. prisma init generates output = "../generated/prisma"; the Prisma Client overview uses output = "./generated" with import { PrismaClient } from "./generated/client"; the Client "Introduction" uses output = "../src/generated/prisma"; the connection-management page imports from "../prisma/generated/client"; the Prisma Postgres connecting page imports from "./generated/prisma/client"; and the Vercel guide imports from "./generated/client". Per the research over llms-full.txt, import forms count from "../prisma/generated/client" ×97, from "./generated/prisma/client" ×47, and from "./generated/client" ×27, while output values count ../generated/prisma ×62, ./generated ×53, ../src/generated/prisma ×24, and ../app/generated/prisma ×13.

Consequence: With the prisma-client generator, the import path is whatever output was set to — so a developer or coding agent who takes the output from the init/quickstart page but the import { PrismaClient } from ... line from a deployment or connection page gets a module-not-found error on their very first run, with no obvious cause. There is no one path an agent can trust.

The fix: Pick one canonical output directory (e.g. ../generated/prisma) and one matching import path, use it in every example across the ORM, Postgres, and deployment sections, and add a one-line note explaining that the import path always mirrors the generator output.

2. Two prisma init reference pages disagree on supported datasource providers (critical)

Location: /docs/orm/reference/prisma-cli-reference#init and /docs/cli/init

Problem: The CLI reference lists --datasource-provider options as prisma+postgres, sqlite, postgresql, mysql, sqlserver, mongodb and cockroachdb, and documents --prompt (or --vibe) and --with-model. The separate /docs/cli/init page lists only postgresql, mysql, sqlite, sqlserver, mongodb, or cockroachdb — omitting prisma+postgres entirely and dropping --prompt/--vibe. Only the CLI reference (/docs/orm/reference/prisma-cli-reference#init) defines --db as "Shorthand syntax for --datasource-provider prisma+postgres"; /docs/cli/init describes --db merely as "Provision a fully managed Prisma Postgres database on the Prisma Data Platform" and never ties it to — or even lists — the prisma+postgres provider value. So the one page that documents --db in that way still never tells the reader that prisma+postgres is a valid provider.

Consequence: A developer or agent reading /docs/cli/init will conclude prisma+postgres is not a valid provider — even though the CLI-reference page defines --db as expanding to exactly that value — and won't discover --prompt/--vibe or --with-model at all. Which page is authoritative is unknowable from the docs.

The fix: Make one page the single source of truth for prisma init, redirect the other to it, and ensure both the --datasource-provider option list and the --db description consistently present prisma+postgres as a supported provider value.

3. The CLI reference contradicts itself on whether --skip-generate/--skip-seed exist in v7 (significant)

Location: /docs/orm/reference/prisma-cli-reference#migrate

Problem: Under migrate dev, a warning states "The --skip-generate and --skip-seed flags were removed in Prisma v7." Under db push, a warning states --skip-generate "was removed in Prisma v7." But migrate reset, on the same page, still lists both --skip-generate and --skip-seed as valid options and describes step 4 as "Runs seed scripts."

Consequence: A reader cannot tell whether these flags still work in v7. An agent generating a migrate reset --skip-seed command from this page has a 50/50 chance the flag was removed and the command errors.

The fix: State the v7 behavior once and consistently — if the flags were removed for all migrate/db subcommands, remove them from the migrate reset options table; if migrate reset still supports them, correct the blanket "removed in Prisma v7" warnings.

4. Stale prisma version example output contradicts the Error Reference (significant)

Location: /docs/orm/reference/prisma-cli-reference#version (vs /docs/orm/reference/error-reference)

Problem: The prisma version example still prints prisma : 2.21.0-dev.4, @prisma/client : 2.21.0-dev.4, and a Migration Engine line, with Studio : 0.365.0. Current Prisma is v7.7.0. Meanwhile the Error Reference warns that "The Schema Engine was previously called Migration Engine. This change was introduced in version 5.0.0." So the version example prints a component name the docs themselves say was renamed five major versions ago. The research notes the 2.21.0-dev.4 string appears 16 times and Studio : 0.365.0 five times across the corpus.

Consequence: Developers and agents infer that "Migration Engine" is still a real component and that a dev-tagged 2.x build is representative, then get confused when their v7 output shows a Schema Engine and different version strings.

The fix: Regenerate the version sample output against a current release, rename Migration Engine to Schema Engine, and sweep the corpus for the stale 2.21.0-dev.4 / Studio : 0.365.0 strings.

5. Stale prisma generate example uses a client location the current generator no longer produces (significant)

Location: /docs/orm/reference/prisma-cli-reference#generate

Problem: The example reads "✔ Generated Prisma Client to ./node_modules/.prisma/client" and then tells users import { PrismaClient } from '../prisma/generated/client' "or const { PrismaClient } = require('@prisma/client')". This mixes three different client locations (./node_modules/.prisma/client, ../prisma/generated/client, and @prisma/client) in a few lines, while the current prisma-client generator requires an explicit output path and the default prisma init schema generates to ../generated/prisma.

Consequence: Copying either import from this page fails against a project created by the current prisma init, and the @prisma/client / node_modules/.prisma/client guidance points developers at a legacy layout that the rest of the docs no longer use.

The fix: Update the generate example to show the current generator writing to the configured output path and import from that same path, dropping the node_modules/.prisma/client and bare @prisma/client references.

6. "Default is local Prisma Postgres" contradicts the files prisma init actually generates — and the config it never scaffolds (significant)

Location: /docs/cli/init, /docs/orm/reference/prisma-cli-reference#init, and /docs/orm/prisma-client/setup-and-configuration/introduction

Problem: Both init pages state that by default the project "sets up a local Prisma Postgres instance" / "is configured for local Prisma Postgres." But the generated artifacts shown on the same pages use a generic Postgres: datasource db { provider = "postgresql" } and .env DATABASE_URL="postgresql://user:password@localhost:5432/mydb", with --datasource-provider defaulting to postgresql (not prisma+postgres). Compounding the onboarding gap, the Prisma Client "Introduction" page requires a prisma.config.ts (with defineConfig and datasource: { url: env('DATABASE_URL') }) plus a driver-adapter install step, yet neither init page scaffolds a prisma.config.ts or even mentions one.

Consequence: A developer expecting a ready-to-use local Prisma Postgres instance instead gets a plain postgresql://...localhost placeholder pointing at a database that doesn't exist — and then, following the Client "Introduction", is told to rely on a prisma.config.ts that prisma init never created, with no guidance on where it comes from. The onboarding path from init to a working client is broken in two places.

The fix: Align the description with the actual default output — either change the generated schema/.env to reflect Prisma Postgres, or correct the prose to say the default provider is postgresql and that --db/prisma+postgres is required for a managed Prisma Postgres instance — and have prisma init scaffold (or the init pages document) the prisma.config.ts the Client "Introduction" depends on.

7. Error Reference P2024 message still embeds connection_limit, contradicting the v7 per-adapter pool model (significant)

Location: /docs/orm/reference/error-reference (vs /docs/orm/prisma-client/setup-and-configuration/databases-connections)

Problem: The Error Reference P2024 message still reads "Timed out fetching a new connection from the connection pool. (More info: http://pris.ly/d/connection-pool (Current connection pool timeout: {timeout}, connection limit: {connection_limit})", exposing a connection_limit parameter. But the databases-connections page states that in Prisma ORM v7 pool size and timeout are "configured per driver adapter—there are no connection URL parameters for these in Prisma ORM v7." The Error Reference does append a v7 caveat ("In Prisma ORM v7, pool size and timeout are configured per driver adapter"), but leaves the old {connection_limit} template embedded in the message itself, so the same screen describes two different pooling models.

Consequence: A developer hitting P2024 sees a connection_limit value and goes looking for the URL/connection-string parameter that used to control it — a knob the v7 docs say no longer exists — instead of the per-adapter pool setting (e.g. max for pg) that actually governs the pool. The mixed message wastes debugging time and points at the wrong fix.

The fix: Update the P2024 message (or the explanation around it) to reflect the v7 per-adapter pool model — describe the limit in terms of the adapter's pool settings rather than a connection_limit URL parameter — and cross-link to the per-adapter connection pool reference the databases-connections page already points to.

8. llms.txt returns 404 at the documentation's own root (significant)

Location: docs.prisma.io/llms.txt and docs.prisma.io/llms-full.txt (both 404)

Problem: docs.prisma.io/llms.txt and docs.prisma.io/llms-full.txt return HTTP 404. The files only resolve one path segment deeper, at docs.prisma.io/docs/llms.txt and www.prisma.io/docs/llms.txt. The llms.txt convention places the file at the domain root, which is where an agent points at the docs site will look first.

Consequence: Coding agents and crawlers that follow the llms.txt convention against the surfaced docs host (docs.prisma.io) hit a 404 and never discover the index that does exist — defeating the purpose of publishing one.

The fix: Serve llms.txt and llms-full.txt at the docs domain root (or redirect the root paths to the /docs-prefixed files) so the convention-standard location resolves.

9. Duplicate parallel page versions with identical titles pollute search and agent indexes (significant)

Location: sitemap / /docs/llms.txt (/docs/orm/... Latest vs /docs/orm/v6/... legacy vs /docs/orm/next/...)

Problem: The sitemap contains 629 URLs, including 191 /docs/orm/v6/... legacy pages and 32 /docs/orm/next/... forward-looking pages, and many titles are duplicated across namespaces (e.g. "About the shadow database" and "Aggregation, grouping, and summarizing" each appear twice). The llms.txt itself notes it "covers the current docs plus legacy v6 pages" and asks readers to "Prefer the Latest ORM section."

Consequence: Search results and agent indexes surface multiple same-titled pages for one topic, and a reader or agent can land on a v6 or next page without realizing it isn't the current recommendation — exactly the ambiguity the "prefer Latest" note tries to paper over.

The fix: Add canonical link tags pointing legacy/next pages at their Latest equivalents, visibly badge non-Latest pages, and keep legacy and preview namespaces out of the primary machine-readable index (or clearly segregate them).

10. Error Reference clientVersion example is pinned to a years-old version (minor)

Location: /docs/orm/reference/error-reference

Problem: Every exception's clientVersion example is documented as 2.19.0 ("Version of Prisma Client (for example, 2.19.0)"), while the current release is v7.7.0.

Consequence: It's a cosmetic placeholder, but combined with the stale version/generate outputs it reinforces the impression that the reference section hasn't been regenerated in a long time, undermining trust in its currency.

The fix: Use a current example version string (or a clearly generic placeholder like x.y.z) in the clientVersion documentation.

11. Quickstarts live under a different URL namespace than the rest of the ORM docs (minor)

Location: /docs/getting-started (and /docs/llms.txt)

Problem: The "Choose a setup path" hub and llms.txt link the "Quickstart with Prisma Postgres" under /docs/prisma-orm/quickstart/..., while the rest of the ORM documentation lives under /docs/orm/.... Two namespaces (prisma-orm vs orm) describe the same product area.

Consequence: Deep links and agent path-inference break, and readers can't reliably guess a page's URL from the product name, since the entry point and the reference material use different prefixes.

The fix: Standardize on one namespace for ORM content and redirect the other, so quickstarts and reference share a consistent path structure.

12. A second CLI package (@prisma/cli) is introduced without explaining how it differs from prisma (minor)

Location: /docs/getting-started

Problem: The deploy flow uses a distinct package — npx @prisma/cli@latest auth login then npx @prisma/cli@latest app deploy for Prisma Compute (Public Beta) — separate from the prisma CLI used everywhere else for init, generate, and migrate. The page introduces @prisma/cli as a separate CLI but never explains the relationship, overlap, or when to use which.

Consequence: Developers and agents can't tell whether @prisma/cli supersedes or complements prisma, and may install the wrong one or run @prisma/cli subcommands against the prisma binary (or vice versa).

The fix: Add a short note distinguishing the two CLIs — what each is for (ORM/local vs Prisma Compute/platform), and whether @prisma/cli is intended to eventually replace prisma.

What they do well

• Machine-readable surfaces exist and are honest about their limits — llms.txt, llms-full.txt, and a changelog.md index are published, and the llms.txt explicitly tells agents to verify against the changelog rather than trust training data.
• Connection guidance for Prisma Postgres is concrete and verifiable — pooled vs direct connection strings, sslmode=require, port 5432, per-plan connection limits, and the 10-minute pooled query timeout are stated clearly and consistently across the connecting and connection-pooling pages.
• CRUD and deployment references are current and caveat-aware — the CRUD reference flags database-specific support (skipDuplicates unsupported on MongoDB/SQLServer/SQLite; createManyAndReturn limited to PostgreSQL/CockroachDB/SQLite), and the Vercel guide covers postinstall generate, vercel-build migrate deploy, and Fluid compute.

Top 3 recommendations

1. Establish one canonical generated-client path (matching output and PrismaClient import) and propagate it to every ORM, Postgres, and deployment example — this is the highest-impact, most-copied snippet in the docs.
2. Collapse the two prisma init reference pages into a single source of truth so the supported --datasource-provider values, the --db shorthand, and --prompt/--vibe options agree, reconcile the v7 --skip-generate/--skip-seed warnings, and make sure the prisma.config.ts the Client "Introduction" needs is scaffolded or documented at init time.
3. Regenerate stale example output and fix machine-readable discoverability — refresh the version, generate, and clientVersion samples to a current release (renaming Migration Engine to Schema Engine), align the P2024 message with the v7 per-adapter pool model, and serve llms.txt/llms-full.txt at the docs domain root.