db: prisma init
This commit is contained in:
1 parent
a982980795
commit
8023fa5301
102 files changed
+9762
No files matched your search
@@ -0,0 +1,116 @@
|
||||
---
|
||||
name: prisma-postgres-upgrade
|
||||
description: Upgrade a PostgreSQL app from Prisma ORM 6 or 7 straight to Prisma 8 in one pass, keeping the existing schema.prisma, database and data. Use when a Postgres project on Prisma 6 or 7 wants Prisma 8, including before deploying it on Prisma Compute, which runs only Prisma 8. Triggers on "upgrade prisma 6 to 8", "upgrade prisma 7 to 8", "upgrade to prisma 8 postgres", "prisma7Schema", "migrations/app", "move off @prisma/client", "Console says move to Prisma 8".
|
||||
license: MIT
|
||||
metadata:
|
||||
author: prisma
|
||||
version: "2.0.0"
|
||||
---
|
||||
|
||||
# Prisma Postgres Upgrade: Prisma ORM 6 or 7 to Prisma 8
|
||||
|
||||
Move a Node.js server on Prisma ORM 6 or 7 and PostgreSQL to Prisma 8 in one pass. The schema,
|
||||
the database and its data stay, and the app keeps running wherever it runs today.
|
||||
|
||||
This skill is the bridge. It covers only what is specific to leaving Prisma ORM 6 or 7. Prisma 8
|
||||
itself (the contract, migrations, queries, errors) is covered by the `prisma-8` skill that ships
|
||||
inside `@prisma/orm-postgres`, which step 2 installs. Follow it for anything Prisma 8 specific;
|
||||
it matches the installed version, and this skill does not.
|
||||
|
||||
`prisma-8` says it does not apply to a project that still has `schema.prisma` and
|
||||
`@prisma/client`. That is expected mid-upgrade: this skill keeps both until step 5, and
|
||||
`prisma7Schema(...)` reads that `schema.prisma`. Use `prisma-8` for the Prisma 8 side anyway.
|
||||
|
||||
The [Prisma ORM 6 or 7 to 8 (PostgreSQL) guide](https://www.prisma.io/docs/guides/upgrade-prisma-orm/postgresql)
|
||||
is the source of truth for the steps.
|
||||
|
||||
**Never do either of these:**
|
||||
|
||||
- Never route a PostgreSQL Prisma ORM 6 app through Prisma ORM 7 first. Prisma 8 reads a
|
||||
Prisma ORM 6 `schema.prisma` unchanged, so `prisma-upgrade-v7` is only for apps that stay on 7.
|
||||
- Never install `prisma@latest` or `@prisma/orm-postgres@latest` when the app will deploy on
|
||||
Prisma Compute: the latest pair does not work with the Composer version the Console's setup
|
||||
installs, so the deploy fails.
|
||||
|
||||
## When to Apply
|
||||
|
||||
- A PostgreSQL project on Prisma ORM 6 or 7 asks to upgrade to Prisma 8 in one pass
|
||||
- A Prisma ORM 6 or 7 app wants to deploy on Prisma Compute, or the Console blocked its setup
|
||||
with "move to Prisma 8": upgrade here, then deploy with `prisma-compute`
|
||||
|
||||
Not for: deploying on Compute (use `prisma-compute`, `deploy-existing-app`), MongoDB (use
|
||||
`prisma-mongodb-upgrade`), a Prisma ORM 7 app moving one route at a time beside Prisma 8
|
||||
(follow the [route-by-route guide](https://www.prisma.io/docs/guides/upgrade-prisma-orm/postgresql-incremental)),
|
||||
a project already on Prisma 8 (use the synced `prisma-8` skill), or a new project (use
|
||||
`prisma-orm-setup`).
|
||||
|
||||
## Versions
|
||||
|
||||
Install exact versions with `--save-exact`. For an app headed to Compute, use the versions the
|
||||
Console's setup uses: today `prisma` `8.0.0-rc.27` (dev dependency) and `@prisma/orm-postgres`
|
||||
`8.0.0-rc.20`. If the Console's message or an existing setup pull request names other versions,
|
||||
use those. Use Node.js 24.11 or newer if the app will run under `prisma dev`.
|
||||
|
||||
## The path
|
||||
|
||||
| Step | What happens | Where the detail is |
|
||||
|------|--------------|---------------------|
|
||||
| 0 | Run the repo's own checks and record the results | `verify-upgrade-checklist` |
|
||||
| 1 | Remove `prisma`, install the versions above, remove `prisma generate` from scripts | this file |
|
||||
| 2 | Write the Prisma 8 `prisma.config.ts`, then `npx prisma skills sync` | `adopt-schema-and-migrations` |
|
||||
| 3 | `contract emit`, `db sign`, baseline migration, retire `prisma/migrations` | `adopt-schema-and-migrations` |
|
||||
| 4 | Create the Prisma 8 client and rewrite every query | `client-api-mapping` |
|
||||
| 5 | Remove `@prisma/client`, the adapter and the generated client | this file |
|
||||
| 6 | Run the same checks again and start the app | `verify-upgrade-checklist` |
|
||||
|
||||
In step 1, also remove `prisma generate` from `build`, `postinstall` and any other script: the
|
||||
Prisma 8 CLI has no `generate` and fails with `CLI.UNKNOWN_COMMAND`. Step 1 removes the only
|
||||
command that generated the old client. It keeps working locally, but a fresh install (CI, a new
|
||||
clone) has none, so finish step 4 before pushing to a branch CI builds.
|
||||
|
||||
The sync in step 2 installs `prisma-8`, `prisma-platform-core-concepts` and
|
||||
`prisma-composer-core-concepts` in one go, because the CLI depends on Composer. It writes them
|
||||
for every agent it knows unless `skills.agents` in the config lists only the ones the repository
|
||||
uses. In a Prisma ORM 7 app, replace the old `prisma.config.ts` before syncing: the sync fails
|
||||
with `CLI.CONFIG_UNREADABLE` while the old one is in place.
|
||||
|
||||
Commit what Prisma 8 writes: `src/prisma/contract.json`, `src/prisma/contract.d.ts` and the
|
||||
whole `migrations/` folder. There is no generate step to recreate them in CI.
|
||||
|
||||
In step 5, `npm uninstall @prisma/client` leaves the generated client behind; delete
|
||||
`node_modules/.prisma` too, then run a fresh install and the checks so nothing still imports it.
|
||||
|
||||
## Deploying on Compute
|
||||
|
||||
When the upgrade is done and the checks pass, deploy with the `prisma-compute` skill
|
||||
(`references/deploy-existing-app.md`). Compute runs only Prisma 8, so the upgrade has to be
|
||||
finished first.
|
||||
|
||||
## What the user does
|
||||
|
||||
The agent cannot do these; stop and ask:
|
||||
|
||||
- Decide what to do about a database time zone other than UTC (see `client-api-mapping`).
|
||||
- Sign every other existing database (staging, production) with `npx prisma db sign`. The agent
|
||||
has only the local one.
|
||||
- Review the change before it ships, especially when the repository has no tests.
|
||||
|
||||
## Reference files
|
||||
|
||||
| Reference | What it covers |
|
||||
|-----------|----------------|
|
||||
| `references/adopt-schema-and-migrations.md` | The first `prisma.config.ts`, keeping `schema.prisma` as the contract, CommonJS `tsconfig`, the baseline, retiring the old migration setup |
|
||||
| `references/client-api-mapping.md` | The Prisma 8 client, Prisma ORM 6/7 calls to Prisma 8, and the differences that break rewrites |
|
||||
| `references/verify-upgrade-checklist.md` | Proving the upgrade with the repo's own checks |
|
||||
|
||||
## Verified against
|
||||
|
||||
A Prisma ORM 6.19 app (Express 4, EJS, `tsc`, CommonJS) on PostgreSQL 18, with `prisma`
|
||||
8.0.0-rc.27 and `@prisma/orm-postgres` 8.0.0-rc.20. Two agents with no context and only these
|
||||
skills upgraded it: pages and API output were identical before and after against the same
|
||||
database, and `prisma db verify` passed.
|
||||
|
||||
## Hand-off rule
|
||||
|
||||
Once the app runs on Prisma 8, use the synced `prisma-8` skill for day-to-day work and
|
||||
`prisma-compute` to deploy and operate it on Compute. This skill covers the upgrade only.
|
||||
@@ -0,0 +1,79 @@
|
||||
# adopt-schema-and-migrations
|
||||
|
||||
Keep the Prisma ORM 6 or 7 `schema.prisma` as the contract, and hand migrations to Prisma 8 once.
|
||||
|
||||
## Priority
|
||||
|
||||
CRITICAL
|
||||
|
||||
## Why It Matters
|
||||
|
||||
Porting the schema by hand risks a contract that no longer matches the tables, which makes
|
||||
`db sign` fail or plans a destructive migration. And the Compute deploy builds each database
|
||||
from `migrations/app/`, so without a baseline there, previews and production start with no
|
||||
tables.
|
||||
|
||||
## The first `prisma.config.ts` (step 2)
|
||||
|
||||
```typescript
|
||||
import "dotenv/config"; // only if the app already uses dotenv
|
||||
import { defineConfig as orm, prisma7Schema } from "@prisma/orm-postgres/config";
|
||||
import { definePrismaConfig } from "prisma/config";
|
||||
|
||||
export default definePrismaConfig({
|
||||
orm: orm({
|
||||
contract: prisma7Schema("prisma/schema.prisma"), // the same file, Prisma ORM 6 or 7
|
||||
output: "src/prisma",
|
||||
db: { connection: process.env["DATABASE_URL"]! },
|
||||
}),
|
||||
skills: { agents: ["claude"] }, // only the agents the repository uses
|
||||
});
|
||||
```
|
||||
|
||||
Then run `npx prisma skills sync`. Deploying on Compute later adds a `composer` section to the same
|
||||
config; that belongs to the `prisma-compute` skill, not to this upgrade.
|
||||
|
||||
## What is specific to coming from 6 or 7
|
||||
|
||||
- **`prisma7Schema(...)` also reads a Prisma ORM 6 schema unchanged**, including the
|
||||
`generator client` block and `url = env(...)`. Do not edit `schema.prisma` or port it to a
|
||||
`contract.prisma`. `output: "src/prisma"` puts `contract.json` and `contract.d.ts` where `tsc`
|
||||
and the Compute service find them. In a Prisma ORM 7 app, this file replaces the old
|
||||
`prisma.config.ts`: Prisma 8 reads only its own format under that name.
|
||||
- **A CommonJS app built with `tsc` stays CommonJS.** Set `"module"` and `"moduleResolution"`
|
||||
to `"nodenext"`, add `"resolveJsonModule": true`, keep `include` at `src`, and do not add
|
||||
`"type": "module"`.
|
||||
- **Sign the existing database, then plan the baseline:** `npx prisma contract emit`,
|
||||
`npx prisma db sign`, `npx prisma migration plan`. The first plan on a signed database writes
|
||||
`migrations/app/<timestamp>_baseline/` and ignores `--name`; `db verify` then passes and
|
||||
`db migrate` has nothing to apply, whatever its hint says. Commit `migrations/`. Sign every
|
||||
other existing database (staging) too; databases the Compute deploy creates do not need it.
|
||||
- **Retire the old migration setup:** delete `prisma/migrations` (with `migration_lock.toml`),
|
||||
remove `prisma generate`, `prisma migrate *` and `prisma db seed` from scripts (including
|
||||
`postinstall`), and remove the `"prisma": { "seed": ... }` key. Prisma 8 has no `generate` or
|
||||
seed command; keep the seed script and run it with `tsx` (`client-api-mapping.md` shows its
|
||||
client). The `_prisma_migrations` table stays in the database; dropping it is the user's call.
|
||||
|
||||
For `contract emit`, `db sign`, the migration commands and every later schema change, follow the
|
||||
synced `prisma-8` skill (`references/contract.md`, `references/migration-model.md`,
|
||||
`references/migrations.md`). Where it shows `definePrismaConfig` from another package, use
|
||||
`prisma/config` as above: that is what the installed CLI exports.
|
||||
|
||||
## Bad
|
||||
|
||||
```bash
|
||||
# Rewriting schema.prisma into contract.prisma, or keeping prisma/migrations "for now"
|
||||
npx prisma7 migrate dev
|
||||
```
|
||||
|
||||
## Good
|
||||
|
||||
```bash
|
||||
npx prisma contract emit && npx prisma db sign && npx prisma migration plan
|
||||
rm -r prisma/migrations
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [Guide, steps 2 and 3](https://www.prisma.io/docs/guides/upgrade-prisma-orm/postgresql#2-create-the-contract-from-your-schema)
|
||||
- The synced `prisma-8` skill, authoritative for the installed version
|
||||
@@ -0,0 +1,90 @@
|
||||
# client-api-mapping
|
||||
|
||||
Create the Prisma 8 client, then map each Prisma ORM 6 or 7 call to it; five differences break most rewrites.
|
||||
|
||||
## Priority
|
||||
|
||||
CRITICAL
|
||||
|
||||
## Why It Matters
|
||||
|
||||
The Prisma 8 client chains calls instead of taking one options object, and a schema read
|
||||
through `prisma7Schema(...)` changes a few lookups and types. Some of these compile and then
|
||||
fail at runtime or write wrong data.
|
||||
|
||||
## The client
|
||||
|
||||
One client for the app and the seed script, reading the same `DATABASE_URL` as before:
|
||||
|
||||
```typescript
|
||||
// src/db.ts
|
||||
import postgres from "@prisma/orm-postgres/runtime";
|
||||
import { contractFromJson } from "@prisma/orm-postgres/static";
|
||||
import type { Contract } from "./prisma/contract.js";
|
||||
import contractJson from "./prisma/contract.json";
|
||||
|
||||
export const db = postgres({ contract: contractFromJson<Contract>(contractJson), url: process.env["DATABASE_URL"]! });
|
||||
```
|
||||
|
||||
In a CommonJS `.ts` file, import the JSON without the `with { type: "json" }` attribute the
|
||||
`prisma-8` skill shows: the attribute fails there with TS2856 and is only valid in `.mts` files.
|
||||
On Compute, `prisma-compute` replaces this client with `service.load().db.client`.
|
||||
|
||||
## Old call to new call
|
||||
|
||||
Queries start at `db.orm.public.<Model>`. For anything not listed here, follow the synced
|
||||
`prisma-8` skill (`references/queries.md`, `references/runtime.md`).
|
||||
|
||||
| Prisma ORM 6 / 7 | Prisma 8 |
|
||||
|------------------|----------|
|
||||
| `findMany({ where, orderBy })` | `.where({...}).orderBy((m) => m.field.asc()).all()` |
|
||||
| `include: { _count: { select: { posts: true } } }` | `.include("posts", (p) => p.count())`; the number is `row.posts`, not `row._count.posts` |
|
||||
| `orderBy: { votes: { _count: "desc" } }` | `.orderBy((p) => p.votes.count().desc())` |
|
||||
| `findUnique({ where: { id } })` | `.first({ id })` |
|
||||
| `findUnique` on an `@unique` or `@@unique` field | `.where({...}).first()` |
|
||||
| `create({ data: { ..., votes: { create: {...} } } })` | `.create({ ..., votes: (v) => v.create([{...}]) })` |
|
||||
| `deleteMany({ where })` then `.count` | `.where({...}).deleteAndCount()` |
|
||||
| `deleteMany()` with no filter (seeds, tests) | `.where((m) => m.id.isNotNull()).deleteAll()`: writes need a filter |
|
||||
| `createMany({ data: [...] })` | `.createAll([...])` |
|
||||
| `count({ where })` | `.where({...}).aggregate((a) => ({ total: a.count() }))` |
|
||||
| `Object.values(PostStatus)` from `@prisma/client` | `db.nativeEnums.public.PostStatus.values` |
|
||||
| ``$queryRaw`SELECT 1` `` (health checks) | ``db.execute(db.raw.sql`SELECT 1`.affectedCount().build())`` |
|
||||
|
||||
What has no Prisma 8 form yet, such as `increment` in an update, is listed in
|
||||
[Coming from Prisma ORM 7](https://www.prisma.io/docs/orm/coming-from-prisma-orm-7#queries).
|
||||
|
||||
## The five differences
|
||||
|
||||
1. **Unique lookups use `.first(...)` or `.where(...).first()`.** A 6/7 `@unique` or `@@unique`
|
||||
becomes a unique index, which `whereUnique` does not accept, so do not reach for it.
|
||||
2. **Enums are under `db.nativeEnums`**, not `db.enums`. The values are the same strings.
|
||||
3. **`DateTime` may read as a string** (`"2026-11-06 09:10:48.497"`, UTC, no offset) at
|
||||
`@prisma/orm-postgres@8.0.0-rc.20`. `row.createdAt.toISOString()` then throws at runtime,
|
||||
often in a template `tsc` never checks. Check the installed version's behavior in the
|
||||
`prisma-8` skill before converting.
|
||||
4. **`@default(now())` is filled by the database** at rc.20, so a `timestamp` column gets the
|
||||
database's local time where 6/7 sent UTC. If `SHOW timezone` is not `UTC`, tell the user
|
||||
rather than changing data: new rows will store a different time than before, which is a
|
||||
behavior change the user has to decide on.
|
||||
5. **Templates and other code `tsc` does not check still read the old shapes.** Search views
|
||||
(`.ejs`, `.hbs`, `.pug`) and plain `.js` files for `_count.`, `.toISOString()` on dates, and
|
||||
enum imports, and change them with the queries.
|
||||
|
||||
## Bad
|
||||
|
||||
```text
|
||||
const board = await db.orm.public.Board.whereUnique({ slug }).first(); // does not compile
|
||||
<%= post._count.votes %> <!-- an .ejs view tsc never checks: undefined after the rewrite -->
|
||||
```
|
||||
|
||||
## Good
|
||||
|
||||
```typescript
|
||||
const board = await db.orm.public.Board.where({ slug }).first();
|
||||
const post = await db.orm.public.Post.include("votes", (v) => v.count()).first({ id }); // post.votes
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [Guide, step 5](https://www.prisma.io/docs/guides/upgrade-prisma-orm/postgresql#5-rewrite-your-queries)
|
||||
- The synced `prisma-8` skill, authoritative for the installed client
|
||||
@@ -0,0 +1,61 @@
|
||||
# verify-upgrade-checklist
|
||||
|
||||
Prove the upgrade with the repository's own checks, run the same way before and after.
|
||||
|
||||
## Priority
|
||||
|
||||
CRITICAL
|
||||
|
||||
## Why It Matters
|
||||
|
||||
A query rewrite can compile and still return different data, or fail only at runtime. The only
|
||||
evidence the user can trust is the project's existing checks passing on both sides of the
|
||||
change. Checks the agent writes for itself prove only what the agent expected.
|
||||
|
||||
## Rules
|
||||
|
||||
- **Use what the repo has.** Find the type check, build, lint and test scripts in `package.json`
|
||||
and CI config, and run exactly those.
|
||||
- **Same commands before and after.** Record each command and its result before step 1. Run
|
||||
the identical commands after step 5. A check that was already failing before is reported as
|
||||
such, not fixed silently.
|
||||
- **Do not invent checks.** Do not write or commit new tests or smoke scripts to stand in for
|
||||
missing ones, and do not change existing tests to make them pass.
|
||||
- **Comparing pages by hand is fine, and it is not a test.** Requesting a few read-only pages
|
||||
before and after, against the same database, catches templates `tsc` never checks. Report it
|
||||
as a manual comparison, never as test coverage.
|
||||
- **No tests? Say so.** If the repository has no tests, tell the user plainly that the upgrade
|
||||
is verified only by type check, build and the app starting, and leave the change for them to
|
||||
review before it ships.
|
||||
|
||||
## Checklist
|
||||
|
||||
1. **Baseline:** run the type check (`tsc --noEmit` or the repo's script), the build, and the
|
||||
test script, then start the app with its own start command and confirm it boots and connects.
|
||||
Record `SHOW timezone` on the database.
|
||||
2. **After step 4:** same commands, against the same local database. No file imports
|
||||
`@prisma/client` or the generated client.
|
||||
3. **After step 5:** a fresh install, then the same commands as the baseline, plus
|
||||
`npx prisma db verify` against the signed database. Start the app with its own start command
|
||||
again.
|
||||
4. **Report:** each command, before and after, pass or fail. List what was not verified,
|
||||
including any behavior the tests do not cover, including the rc.20
|
||||
`DateTime` and `now()` notes in `client-api-mapping.md`. If the database's time zone is not
|
||||
UTC, say so first: new rows store a different time than before.
|
||||
|
||||
## Bad
|
||||
|
||||
```text
|
||||
"Added tests/upgrade.test.ts that hits every route; all pass."
|
||||
```
|
||||
|
||||
## Good
|
||||
|
||||
```text
|
||||
Before: tsc ok, build ok, npm test 42 passed. After: tsc ok, build ok, npm test 42 passed,
|
||||
app starts. Not verified: behavior the tests do not cover.
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [Guide, step 5.3](https://www.prisma.io/docs/guides/upgrade-prisma-orm/postgresql#53-run-the-app-locally)
|
||||
Reference in new issue
Block a user