This page explains the release process of the Prisma ORM, how it's versioned and how to deal with breaking changes that might happen throughout releases.
Prisma releases typically happen every two weeks. Note that this is not a hard rule – releases might be postponed for internal reasons.
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.
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.
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)
Prisma's release scheme adheres to Semantic Versioning (SemVer) starting with version
Prisma 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:
MAJORversion when you make incompatible API changes,
MINORversion when you add functionality in a backward compatible manner, and
PATCHversion when you make backward compatible bug fixes.
How does Prisma versioning follow SemVer?
Beginning with version
3.x.x, Prisma adheres strictly to the SemVer versioning scheme.
Here is a brief overview of how Prisma's follows SemVer:
- Breaking changes in stable surface (i.e. General Availability) will only be introduced in new
- Breaking changes can still be rolled out in
MINORbut 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
Given a version number
MAJOR.MINOR.PATCH, Prisma's version number is incremented as follows:
MAJORversion is incremented when major product updates with breaking changes are released to General Availability.
MINORversion 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.
PATCHversion is incremented when functionality bugs are fixed and are always backward compatible.
Note: Up until version version
2.28.0, Prisma did not follow SemVer versioning strictly. This means that releases in the
MINORversions may have included breaking changes. To learn more about Prisma's adoption of SemVer, check out the blog post.