Skip to main content

ORM releases and maturity levels

This page explains the release process of Prisma ORM, how it's versioned and how to deal with breaking changes that might happen throughout releases.

Releases​

Prisma ORM releases typically happen every three weeks. Note that this is not a hard rule – releases might be postponed for internal reasons.

Check out all the releases notes in GitHub.

Product maturity levels​

A release can include products or features at different maturity levels. Maturity level describes a product or feature's completeness and what users can expect in terms of breaking changes.

Note: As of version 2.13.0, 'Experimental' is no longer part of the product maturity scale.

Early Access​

If a feature or product is Early Access:

  • We have validated a problem and are considering a solution to it but are not certain whether that solution is complete or a perfect fit.
  • We want to gather more feedback and adjust the solution as necessary, knowing that users are prepared for significant breaking changes

We don't recommend using Early Access features or products in production.

Preview​

If a feature or product is a Preview:

  • We have validated the feature or product in terms of direction and surface.
  • Users can count on the feature or product and associated API to be mostly stable unless stated otherwise in the release notes and documentation.
  • There are no significant known issues, although minor bugs may exist.
  • We welcome feedback on these to make the solution stable as quickly as possible.

Previews are typically available behind a feature flag or require some form of opt-in (for example, by providing a --preview-feature flag in the CLI or adding them to a previewFeatures property in the generator block for Prisma Client in your Prisma schema).

We don't recommend using Preview features or products in production.

See also: All currently available Preview features.

Generally Available (GA)​

If a feature or product is Generally Available:

  • The solution has been tested for some time and we received enough feedback to consider it stable and ready for production use.
  • There should be no bugs in 99% of cases (completely bug-free software cannot be guaranteed)

Versioning​

Prisma ORM's release scheme adheres to Semantic Versioning (SemVer) starting with version 3.x.x.

Prisma ORM and Semantic Versioning (SemVer)​

How does SemVer versioning work?​

Semantic Versioning (SemVer) uses the following rules for version upgrade (quoted from the SemVer spec):

Given a version number MAJOR.MINOR.PATCH, increment the:

  1. MAJOR version when you make incompatible API changes,
  2. MINOR version when you add functionality in a backward compatible manner, and
  3. PATCH version when you make backward compatible bug fixes.

How does Prisma ORM versioning follow SemVer?​

Beginning with version 3.x.x, Prisma ORM adheres strictly to the SemVer versioning scheme.

Here is a brief overview of how Prisma ORM's follows SemVer:

  • Breaking changes in stable surface (i.e. General Availability) will only be introduced in new MAJOR releases.
  • Breaking changes can still be rolled out in MINOR but only for opt-in Preview and Early Access features that are not active by default (e.g. via a Preview feature flag or a specific opt-in option or new CLI command).
  • Opt-in breaking changes, i.e. Preview and Early Access, released in MINOR, will only be promoted to General Availability (no requirement for opt-in) in new MAJOR releases.

Given a version number MAJOR.MINOR.PATCH, Prisma ORM's version number is incremented as follows:

  1. MAJOR version is incremented when major product updates with breaking changes are released to General Availability.
  2. MINOR version is incremented when product updates adding backward compatible new functionality are released. Features with breaking changes may only be introduced if they are opt-in, i.e. Early Access and Preview.
  3. PATCH version is incremented when functionality bugs are fixed and are always backward compatible.

Note: Up until version 2.28.0, Prisma ORM did not follow SemVer versioning strictly. This means that releases in the 2.MINOR.PATCH range, MINOR versions may have included breaking changes. To learn more about Prisma ORM's adoption of SemVer, check out the blog post.