Skip to content

feat(prisma-postgres-upgrade): add the Prisma ORM 6 or 7 to Prisma 8 upgrade skill, and deploying an existing app to prisma-compute - #38

Merged
ankur-arch merged 5 commits into
mainfrom
feat/prisma-postgres-upgrade
Nov 9, 2026
Merged

ankur-arch merged 5 commits into
mainfrom
feat/prisma-postgres-upgrade

Conversation

@kristof-siket

@kristof-siket kristof-siket commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

What this adds

A new skill, prisma-postgres-upgrade, that takes a PostgreSQL app on Prisma ORM 6 or 7 straight to Prisma 8 in one pass. The existing schema.prisma, database and data stay, and the app keeps running wherever it runs today. It also adds a deploy-existing-app reference to prisma-compute, for deploying an existing Prisma 8 app on Compute, including through the Console's setup pull request.

Upgrading and deploying are separate on purpose. Most people come to upgrade to Prisma 8, or to deploy an app they already have, not to do both as one task. Compute runs only Prisma 8, so the link between the two is a rule: finish the upgrade before deploying. Each skill owns one job, and they hand off to each other.

They mirror the restructured docs in prisma/web#8751:

Tracked in PRS-850.

How it relates to the prisma-8 skill

The prisma-8 skill that ships inside @prisma/orm-postgres already covers Prisma 8 itself: the contract, migrations, queries and errors, matched to the installed version. Its quickstart says it does not cover migrating from Prisma 6/7, and that those are separately installable skills. This is that skill.

It's a bridge. It covers only what is specific to leaving Prisma ORM 6 or 7. It writes the first Prisma 8 config, runs npx prisma skills sync, and hands every Prisma 8 detail to prisma-8. It lives in this registry, not in the package, because a Prisma 6 or 7 project needs it before any Prisma 8 package is installed. prisma-mongodb-upgrade lives here for the same reason.

What's in it

  • prisma-postgres-upgrade/SKILL.md:
    • when to apply it, and the hand-offs to prisma-8 and prisma-compute
    • exact versions
    • the path, and what the user decides
    • two "never" rules: never route a Postgres Prisma 6 app through Prisma 7 first, and never install @latest for an app headed to Compute
  • prisma-postgres-upgrade/references/:
    • adopt-schema-and-migrations.md: the first prisma.config.ts, keeping the Prisma 6 or 7 schema.prisma as the contract (prisma7Schema(...) reads both), a CommonJS tsconfig, the baseline migration, and retiring prisma/migrations, generate and seed scripts
    • client-api-mapping.md: the Prisma 8 client, old calls mapped to new ones, and five differences that break rewrites. One of them is a database time zone other than UTC, which changes the time stored for new rows.
    • verify-upgrade-checklist.md: the result is proven with the repository's own checks, run the same way before and after. Comparing a few pages by hand is allowed but reported as manual, never as tests. A repo without tests is left for the user to review.
  • prisma-compute/references/deploy-existing-app.md: what the Console's setup PR adds and gets wrong (the service in the build, entry, dependencies: "external", the client from service.load().db.client because DATABASE_URL is a placeholder on Compute, runtime files, env vars as service inputs), and the same files written by hand without a setup PR.
  • prisma-compute/SKILL.md:
    • a deploy-existing-app rule
    • Composer pinned to the installed ORM version
    • a note that prisma dev needs Node 24.11
  • prisma-orm-setup/SKILL.md and README.md: routing to the new skill, and the listing.

How it was checked

  • The repo's skill validator passes.
  • Every step was validated on a real Prisma 6 app (Express, EJS, Prisma 6.19, tsc), up to the app serving its routes from the Prisma 8 client.
  • Two blind agent runs. Each time, an agent with no context and only the skill installed in a copy of that app was asked to "upgrade it to Prisma 8 and get it ready to deploy on Prisma Compute". Both finished the upgrade and reached dev: ready under prisma dev. Pages and API output were identical to the Prisma 6 run against the same database, and prisma db verify passed. The gaps each run found are fixed in the commits after it. The second run's remaining conflicts were between this skill and prisma-compute, which is why the deploy guidance now lives in one place.
  • The Compute deploy itself wasn't run end to end with these skills.

Merge order

  1. docs(docs): split upgrading to Prisma 8 from deploying on Compute web#8751 first, or together with this. Until it's merged, this PR's guide links return 404.
  2. This PR.

Console's blocked-setup message already links /docs/guides/upgrade-prisma-orm/postgresql, which becomes the one-pass guide, so no Console change is needed.

… the prisma-8 skill

The prisma-8 skill shipped in @prisma/orm-postgres already covers the
contract, migrations and queries for the installed version. This skill
now covers only what is specific to leaving Prisma ORM 6 or 7 and
landing on Compute, and tells the agent to sync and follow prisma-8
for everything Prisma 8 specific.

- Merge schema-contract-mapping and migrations-mapping into
  adopt-schema-and-migrations, keeping only the 6/7-specific parts
- Trim client-api-mapping to the old-to-new call table and the four
  differences that break rewrites
- Note that the setup pull request fixes work around current Console
  gaps, so the agent reads the PR before changing it
- Renumber the path and the verify checklist
- Write the first Prisma 8 config in this skill and sync right after it; one sync installs all three skills
- Explain that prisma-8's 'does not apply' check is expected mid-upgrade
- Use .first({ id }) for primary-key lookups, matching prisma-8
- Document the auto-named baseline, the CommonJS JSON import, the seed client and start-command change
- Add the files to write without a Console setup pull request, including module: module.mjs in the workflow
- Pass env vars as service inputs; flag a non-UTC database time zone as a behavior change
@kristof-siket
kristof-siket marked this pull request as ready for review November 9, 2026 07:48
@kristof-siket

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@kristof-siket

Copy link
Copy Markdown
Contributor Author

@prisma-gizmo review

- prisma-postgres-upgrade covers only the upgrade and keeps the app runnable on any host
- Move the setup-PR fixes into prisma-compute as references/deploy-existing-app.md
- prisma-compute: pin Composer to the installed ORM, note prisma dev needs Node 24.11
- Fold in the second blind run: drop prisma generate in step 1, commit contract and migrations,
  client setup, delete-all, createAll and raw SELECT 1, manual page comparison is not a test
- Point links at the restructured guides (/postgresql, /postgresql-incremental, /guides/compute/deploy-existing-app)
@kristof-siket kristof-siket changed the title feat(prisma-postgres-upgrade): add the Prisma ORM 6 or 7 to Prisma 8 on Compute upgrade skill feat(prisma-postgres-upgrade): add the Prisma ORM 6 or 7 to Prisma 8 upgrade skill, and deploying an existing app to prisma-compute Nov 9, 2026
…pute deploy, not step 5

Step 5 of this skill removes @prisma/client. The composer section is added
when the app deploys on Compute, which prisma-compute owns since the split.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

@ankur-arch ankur-arch left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read all nine files against the docs in prisma/web#8751. Approving.

Checked

  • The three guide anchors the references link to (#2-create-the-contract-from-your-schema, #5-rewrite-your-queries, #53-run-the-app-locally) exist in the new all-at-once guide, and so does coming-from-prisma-orm-7#queries.
  • Versions match the docs pages: prisma@8.0.0-rc.27, @prisma/orm-postgres@8.0.0-rc.20, Composer 0.34.0.
  • The hand-offs line up in both directions: prisma-postgres-upgrade stops at a running Prisma 8 app, prisma-compute/deploy-existing-app starts there, and prisma-orm-setup routes to the right one.

One fix pushed (0d6fde5)
adopt-schema-and-migrations.md said "Step 5 adds a composer section to the same config". Since the split, step 5 of this skill removes @prisma/client, and the composer section comes from the Compute deploy. The sentence now points at prisma-compute.

Not verified here
I did not rerun the upgrade or the deploy end to end. The API details (service.load().db.client, dependencies: "external", the module.mjs shape) rest on the blind agent runs described in the PR body.

@ankur-arch
ankur-arch merged commit a6f1929 into main Nov 9, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants