From 1d4a1c0589ae7b4b250e4d208098275985879e89 Mon Sep 17 00:00:00 2001 From: Kristof Siket Date: Tue, 10 Nov 2026 16:06:28 +0000 Subject: [PATCH] fix(prisma-postgres-upgrade): read versions from the Console, update the date notes for rc.23 The skill pinned prisma 8.0.0-rc.27 and @prisma/orm-postgres 8.0.0-rc.20 as "today's" Console versions. The Console now installs rc.33 and rc.23, and its date notes described rc.20 behavior that no longer holds. - Versions: use the exact versions the Console's message or setup pull request names; rc.33 / rc.23 is only an example. For apps not headed to Compute, match the pair through prisma's @prisma/orm-toolchain. - client-api-mapping: from rc.22, DateTime, @db.Timestamp and @db.Timestamptz read and write a Date again; @db.Date and @db.Time read as strings. From rc.21, @default(now()) and @updatedAt are written by the client in UTC, so the database's time zone no longer matters. - Drop the time zone decision from "What the user does" and the checklist; README topic line to match. - Verified against: what was checked at rc.33 / rc.23. - version 2.0.1 Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- prisma-postgres-upgrade/SKILL.md | 27 ++++++++++++----- .../references/client-api-mapping.md | 29 ++++++++++--------- .../references/verify-upgrade-checklist.md | 6 ++-- 4 files changed, 38 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 9c66cf9..448335a 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,7 @@ Upgrade a PostgreSQL app from Prisma ORM 6 or 7 straight to Prisma 8 in one pass - Exact versions, and why not `@latest` for apps headed to Compute - Reading the existing `schema.prisma` with `prisma7Schema(...)`, `contract emit` and `db sign` - Prisma 8 owning migrations in `migrations/app/` -- The Prisma 8 client, query rewrites and the `@prisma/orm-postgres@8.0.0-rc.20` gotchas, including a database time zone other than UTC +- The Prisma 8 client, query rewrites and the differences that break them, such as `@db.Date` fields reading as strings - Verifying with the repository's own checks, before and after - Handing Prisma 8 details to the `prisma-8` skill that ships in `@prisma/orm-postgres` (`npx prisma skills sync`) diff --git a/prisma-postgres-upgrade/SKILL.md b/prisma-postgres-upgrade/SKILL.md index de0fde3..ea35571 100644 --- a/prisma-postgres-upgrade/SKILL.md +++ b/prisma-postgres-upgrade/SKILL.md @@ -4,7 +4,7 @@ description: Upgrade a PostgreSQL app from Prisma ORM 6 or 7 straight to Prisma license: MIT metadata: author: prisma - version: "2.0.0" + version: "2.0.1" --- # Prisma Postgres Upgrade: Prisma ORM 6 or 7 to Prisma 8 @@ -29,8 +29,8 @@ is the source of truth for the steps. - 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. + Prisma Compute: `latest` can move past the Composer version the Console's setup installs, and + then the deploy fails. ## When to Apply @@ -46,10 +46,17 @@ a project already on Prisma 8 (use the synced `prisma-8` skill), or a new projec ## 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`. +Install exact versions with `--save-exact`. For an app headed to Compute, use the exact versions +the Console's setup installs. Its message or its setup pull request names them, for example +`prisma` `8.0.0-rc.33` (dev dependency) and `@prisma/orm-postgres` `8.0.0-rc.23`. These are only +an example: the Console moves to newer versions, so read them from the Console each time. + +For an app that will not deploy on Compute, use a matching pair: `npm view prisma@ +dependencies` names the `@prisma/orm-toolchain` version, and `@prisma/orm-postgres` takes the +same one. Use Node.js 24.11 or newer if the app will run under `prisma dev`. + +The date notes in `client-api-mapping` hold for `@prisma/orm-postgres` 8.0.0-rc.22 and later. On +an older version, follow the synced `prisma-8` skill instead. ## The path @@ -90,7 +97,6 @@ finished first. 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. @@ -110,6 +116,11 @@ A Prisma ORM 6.19 app (Express 4, EJS, `tsc`, CommonJS) on PostgreSQL 18, with ` skills upgraded it: pages and API output were identical before and after against the same database, and `prisma db verify` passed. +With `prisma` 8.0.0-rc.33 and `@prisma/orm-postgres` 8.0.0-rc.23, a smaller check on Node.js 24 +and PostgreSQL 18: `contract emit` and `db sign` on a Prisma ORM 6 schema, the client file in +`client-api-mapping` under TypeScript 5.9 and CommonJS, and the date notes there, with the +database's time zone set to something other than UTC. The full agent run was not repeated. + ## Hand-off rule Once the app runs on Prisma 8, use the synced `prisma-8` skill for day-to-day work and diff --git a/prisma-postgres-upgrade/references/client-api-mapping.md b/prisma-postgres-upgrade/references/client-api-mapping.md index 75175c8..365a86e 100644 --- a/prisma-postgres-upgrade/references/client-api-mapping.md +++ b/prisma-postgres-upgrade/references/client-api-mapping.md @@ -1,6 +1,6 @@ # client-api-mapping -Create the Prisma 8 client, then map each Prisma ORM 6 or 7 call to it; five differences break most rewrites. +Create the Prisma 8 client, then map each Prisma ORM 6 or 7 call to it; four differences break most rewrites. ## Priority @@ -53,22 +53,25 @@ Queries start at `db.orm.public.`. For anything not listed here, follow t 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 +## The four 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. +3. **`@db.Date` and `@db.Time` fields read as strings**, such as `"2026-11-10"` and + `"10:00:00.5"`, where 6/7 read a `Date`. Write them as strings too. `.toISOString()` or + `.getTime()` on them throws at runtime, often in a template `tsc` never checks. `DateTime`, + `@db.Timestamp` and `@db.Timestamptz` still read and write a JavaScript `Date`, in UTC. +4. **Templates and other code `tsc` does not check still read the old shapes.** Search views + (`.ejs`, `.hbs`, `.pug`) and plain `.js` files for `_count.`, date methods on `@db.Date` and + `@db.Time` fields, and enum imports, and change them with the queries. + +`@default(now())` and `@updatedAt` work as in 6/7: the client writes the current time in UTC on +create, and `@updatedAt` again on update, whatever the database's time zone. An `INSERT` from +outside Prisma still gets the column default. + +These date notes hold for `@prisma/orm-postgres` 8.0.0-rc.22 and later. Earlier versions read +`DateTime` differently, so on those, follow the synced `prisma-8` skill. ## Bad diff --git a/prisma-postgres-upgrade/references/verify-upgrade-checklist.md b/prisma-postgres-upgrade/references/verify-upgrade-checklist.md index 5d2dc57..5765cf8 100644 --- a/prisma-postgres-upgrade/references/verify-upgrade-checklist.md +++ b/prisma-postgres-upgrade/references/verify-upgrade-checklist.md @@ -32,16 +32,14 @@ change. Checks the agent writes for itself prove only what the agent expected. 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. + including any behavior the tests do not cover, such as `@db.Date` and `@db.Time` fields that + now read as strings (`client-api-mapping.md`). ## Bad