Status: complete on this branch. Every query in src/, scripts/, import/ and prisma/seed.ts runs through the Prisma 8 client in src/lib/prisma8.ts. Prisma 7 packages, config, schema, migrations and generated client are removed. The local database is signed to the contract.
Prisma 8 is not a drop-in major upgrade of the Prisma 7 client. It replaces the generated client and the query API:
- There is no
prisma generate, noPrismaClient, no@prisma/clientruntime, and noPrisma.*generated types. - The schema is a contract (
prisma/contract.prisma), emitted tocontract.json+contract.d.ts. - Queries move from
prisma.user.findMany({ where, include, orderBy })to chains such asdb.orm.public.User.where({...}).include("posts").orderBy(...).all(). findUnique/findFirstbecome.first()/.firstOrThrow(),createManyAndReturnhas no ORM equivalent,count()becomes.aggregate(a => ({ n: a.count() })), and$transaction([...])becomesdb.transaction(async tx => ...).- PostgreSQL
DateTimecolumns are read as strings (TimestampString(3)), notDateobjects. The app parses at the boundary (parseDbTimestamp/formatDbTimestampinsrc/lib/time.ts,parseTimestampFieldsfor whole rows) and keepsDateeverywhere else. - Enums come from the contract as string unions.
src/lib/enums.tskeeps thePhase.DESIGNvalue-and-type shape the app already used; it is generated from the contract byscripts/generate-enums.ts(run viabun run db:generate) and type-checked against it.
| Piece | State |
|---|---|
| Prisma 8 CLI | prisma@8.0.0-rc.29, config prisma.config.ts |
| Prisma 8 runtime | @prisma/orm-postgres@8.0.0-rc.22 |
| Contract source | prisma/contract.prisma – the schema of record |
| Contract artifacts | src/app/generated/prisma8/contract.json and contract.d.ts (gitignored with the rest of src/app/generated) |
| Migration state | migrations/app/refs/db.json + content-addressed snapshots under migrations/snapshots/ |
| Verification | bun run p8:verify exercises the admin, review, feed and shop read paths |
| Auth | better-auth on its Kysely adapter with its own UTC-pinned pg pool (src/lib/auth-db.ts); the Prisma adapter is gone with the v7 client |
Both Prisma versions are pinned exactly rather than with ^, and overrides forces @prisma/orm-toolchain to the runtime's version. Prerelease semver ranks 8.0.0-rc.9-dev.79 above 8.0.0-rc.29, because a non-numeric identifier outranks a numeric one, so a caret range lets bun update walk back to the older rc.9 dev build. The pin also keeps every @prisma/orm-* package on one version, which Prisma 8 refuses to run without.
bun run db:generate # emit contract + regenerate src/lib/enums.ts
bun run db:update # local-dev fast path: apply contract to dev DB
bun run db:plan -- --name x # formal path: write a migration package
bun run db:migrate # apply pending migrations (also the boot command)
bun run db:verify # contract vs live schema
bun run db:sign # adopt a matching database
bun run p8:verify # read-path smoke test over real queriesbun run db:generate,bun run typecheck,bun run lint,bun run buildpass with no Prisma 7 packages installed.bun run p8:verifyreturns the admin counters, review queue, feed, shop and project queries against the signed local database.bun run db:verifypasses against the signed local database.
The contract was rewritten from the Prisma 7 schema rather than inferred, so every field and relation name the app uses is preserved:
- 8 partial indexes carry
where: sql\...`with Postgres's own reprint of the predicate (casts and extra parens included) – byte-identical text is whatdb sign` compares. - 3 indexes lost their
(sort: Desc)field arguments; sort direction lives in queryorderBy, not in the index. cuid()defaults became@onCreate(cuid()); Prisma 8 treats client-generated values as generators, not database defaults.- Native enum member order matches the live database (enum order is significant to verification, not alphabetical).
Complete. No data migration was needed at any point: Prisma 8 reads the same tables, rows and enums as Prisma 7 did. The only write outside the app was the marker row in prisma_contract.marker, which records that the database matches the contract.
What it took, for the record – the first boot could not just run migrate, because migrate is replay-only and a marker-less database replays the baseline:
- The entrypoint temporarily ran
db sign --no-advance-refbeforemigrate. (verifycannot run before the marker exists, and the flag skips the dev-side ref file, which the runtime user cannot write — without it a successful sign still exited non-zero on EACCES.) - The first
signrefused with a native-enum order mismatch: production lists twoAuditActionmember pairs in the opposite order to the dev database the contract was matched to. The contract was rewritten to production's exact order andmigrations/app/20261026T0302_audit_action_enum_orderperforms the swap (new type, move the oneaudit_logcolumn across with aUSINGcast, drop, rename) – validated on scratch and dev databases before deploy. The planner does not reorder enums, so this package is hand-authored. - With the contract matching,
signwrote the marker,migratereported "Already up to date", and the temporary bootstrap was removed. Boot is nowdb migratealone.
The old _prisma_migrations table stays where it is; it is Prisma 7's history and nothing reads it anymore. Its rows remain in git history under prisma/migrations/.