db: prisma init

This commit is contained in:
arswarog committed 2026-11-16 17:30:51 +03:00
1 parent 414e7b8a37
commit e43db517d9
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)