Change8

v0.17.0

Breaking Changes
📦 prismaView on GitHub →
9 breaking3 features🐛 2 fixes🔧 27 symbols

Summary

This release introduces a namespace change, publishing Prisma Next as 17 packages under the `@prisma` scope. It also standardizes error handling with structured envelopes and completes relation-loading for lossless data handling.

⚠️ Breaking Changes

  • One `@prisma` package per application: The `@prisma-next/*` scope is retired. Applications should now depend on exactly one database facade (e.g., `@prisma/orm-postgres`) and any extension packs. Regenerating your contract will rewrite generated imports to facade entrypoints. See the [0.16-to-0.17 upgrade recipe](https://github.com/prisma/prisma/blob/v0.17.0/skills/upgrade/prisma-next-upgrade/upgrades/0.16-to-0.17/) and the [extension-author recipe](https://github.com/prisma/prisma/blob/v0.17.0/skills/extension-author/prisma-8-extension-upgrade/upgrades/0.16-to-0.17/).
  • Every published error is a structured envelope with a dotted code: Legacy error systems are consolidated into a single scheme with `NAMESPACE.SUBCODE` codes, recognized by the `isStructuredError` type predicate instead of `instanceof`. Legacy error classes like `PslFormatError` are deleted. Prisma 7's `P1001`-style codes are not carried over. Example: `if (error instanceof PslFormatError)` becomes `if (isStructuredError(error) && error.code === 'PSL.PARSE_FAILED')`.
  • Content hashes are bare hex: The `sha256:` prefix is removed from all content hashes. Loaders will reject the prefixed form. A codemod in the [0.16-to-0.17 recipe](https://github.com/prisma/prisma/blob/v0.17.0/skills/upgrade/prisma-next-upgrade/upgrades/0.16-to-0.17/) converts migration trees.
  • Migration contract snapshots move into a content-addressed store: Per-migration sibling snapshot files are replaced by a single `migrations/snapshots/<hex>/` store. A one-shot migrator (`scripts/migrate-migrations-layout.mjs`) converts existing trees.
  • PostgreSQL native types are authored in type position; the `@db.*` attribute channel is removed: Write native types directly (e.g., `VarChar(255)`, `Uuid`) instead of using `@db.*` attributes. `Json` now binds to native `json` storage, and `Jsonb` is a new scalar for jsonb. Example: `model User { id String @id @db.Uuid }` becomes `model User { id Uuid @id }`.
  • Relation-loading and aggregates are lossless: Values read through `.include()` no longer pass through lossy Aggregate result types change: `count()` is a `bigint`, and decimal sums are strings. Regenerate your contract after upgrading.
  • SQL indexes and RLS policies are name-identified: Every index and RLS policy has an exact name in the contract, which can be adopted by exact name (`@@map`).
  • `extensionPacks` config key renamed to `extensions`: In `prisma-next.config.ts`, the TS builder, client options, and the emitted contract's top-level key have been renamed. The old key fails loudly. Contract hashes will change, requiring re-emission and re-anchoring of migrations. `contract.source.sourceFormat` is now `format`, and the facade `defineConfig` option `outputPath` is now `output`.
  • Count-only mutation terminals renamed: `createCount(...)`, `updateCount(...)`, and `deleteCount()` are now `createAndCount(...)`, `updateAndCount(...)`, and `deleteAndCount()`. Behavior and results are unchanged.

Migration Steps

  1. Regenerate your contract to update generated imports to facade entrypoints.
  2. Run the codemod in the [0.16-to-0.17 recipe](https://github.com/prisma/prisma/blob/v0.17.0/skills/upgrade/prisma-next-upgrade/upgrades/0.16-to-0.17/) to convert checked-in migration trees with bare hex content hashes.
  3. Run `scripts/migrate-migrations-layout.mjs` to convert existing migration trees to the content-addressed snapshot store.
  4. Switch `Json` fields to `Jsonb` if they were previously intended to store jsonb data.
  5. Regenerate your contract after upgrading to account for lossless relation-loading and aggregate changes.
  6. Re-emit and re-anchor migrations due to contract hash changes from the `extensionPacks` to `extensions` rename.

✨ New Features

  • Expression, partial, and unique indexes are authorable in both PSL and the TypeScript builder.
  • `contract infer` reaches full fidelity, capturing indexes, policy blocks, and `@@rls`, and signs the database for end-to-end introspection and verification. It also infers 1:1 relations from unique indexes.
  • Every error code is documented on an in-repo reference page (221 codes), kept complete by a CI check, and error envelopes carry a `docsUrl` pointing at their per-code anchor.

🐛 Bug Fixes

  • MongoDB write results decode through their type codecs instead of returning raw wire values.
  • The Postgres runtime driver serializes queries per pinned client, fixing interleaved-query failures on a shared connection.

Affected Symbols