db: prisma init

This commit is contained in:
arswarog committed 2026-11-16 17:26:19 +03:00
1 parent a982980795
commit 8023fa5301
102 files changed
+9762

No files matched your search

@@ -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)