Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`)

Expand Down
27 changes: 19 additions & 8 deletions prisma-postgres-upgrade/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand All @@ -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@<version>
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

Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand Down
29 changes: 16 additions & 13 deletions prisma-postgres-upgrade/references/client-api-mapping.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -53,22 +53,25 @@ Queries start at `db.orm.public.<Model>`. 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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading