Upgrade to Prisma ORM 3
Prisma ORM 3 introduces a number of breaking changes if you are upgrading from an earlier version (any 2.x version), therefore, it is important to understand how this upgrade might affect your application and make any needed adjustments to ensure a smooth transition.
Below you will find a list of the breaking changes and how to handle them.
Breaking changes
Referential actions
The introduction of referential actions in version 3.x removes the safety net in Prisma Client that had previously prevented cascading deletes at runtime.
As a result, depending on which workflow you are using to work on your application, you could be impacted. We advise you to check your schema and decide if you need to define referential actions explicitly.
See Referential action upgrade path to understand how to proceed.
Named constraints
We changed the convention followed by Prisma ORM to name constraints and indexes. We also introduced a clear distinction between the map
attribute (database-level name) and name
attribute (Prisma Client API name) in the PSL to explicitly control how constraints are defined in the Prisma schema.
This means that you will notice an impact when running Prisma migrate
or db pull
which will follow this new convention. We advise you to adjust your schema to reflect the names of your constraints and indexes appropriately.
You can check out the Named constraints upgrade path for more information on how to proceed.
$queryRaw
From version 3.x onwards, the $queryRaw
method now only supports a template literal.
This means that if your application relied on $queryRaw
calls using strings, those calls will not work anymore. We advise you to use template literals wherever possible for security reasons or resort to $queryRawUnsafe
otherwise, after carefully escaping queries to prevent SQL injections.
You can learn more about the new $queryRaw
and $queryRawUnsafe
methods in the Raw database access section of the docs.
Json Null Equality
You cannot filter a Json
field by a null value. See this GitHub issue.
This is because { equals: null }
checks if the column value in the database is NULL
, not if the JSON value inside the column equals null
.
To fix this problem, we decided to split null on Json fields into JsonNull
, DbNull
and AnyNull
.
- JsonNull: Selects the null value in JSON.
- DbNull: Selects the NULL value in the database.
- AnyNull: Selects both null JSON values and NULL database values.
Given the following model in your Prisma Schema:
model Log {
id Int @id
meta Json
}
Starting in 3.0.1, you'll see a TypeError if you try to filter by null on a Json
field:
prisma.log.findMany({
where: {
data: {
meta: {
equals: null
^ TypeError: Type 'null' is not assignable to type
}
},
},
});
To fix this, you'll import and use one of the new null types:
import { Prisma } from '@prisma/client'
prisma.log.findMany({
where: {
data: {
meta: {
equals: Prisma.AnyNull,
},
},
},
})
This also applies to create
, update
and upsert
. To insert a null
value
into a Json
field, you would write:
import { Prisma } from '@prisma/client'
prisma.log.create({
data: {
meta: Prisma.JsonNull,
},
})
And to insert a database NULL
into a Json field, you would write:
import { Prisma } from '@prisma/client'
prisma.log.create({
data: {
meta: Prisma.DbNull,
},
})
This API change does not apply to the MongoDB connector where there is not a difference between a JSON null and a database NULL.
They also do not apply to the array_contains
operator because there can only be a JSON null within an JSON array. Since there cannot be a database NULL within a JSON array, { array_contains: null }
is not ambiguous.
Specific upgrade paths
Named constraints upgrade path
Referential actions upgrade path
Upgrading the prisma
and @prisma/client
packages to Prisma ORM 3
To upgrade from version 2.x to 3.x, you need to update both the prisma
and @prisma/client
packages. Both the prisma
and @prisma/client
packages install with a caret ^
in their version number to safe guard against breaking changes.
To ignore the caret ^
and upgrade across major versions, you can use the @3
tag when upgrading with npm
, or yarn
.
Before upgrading, check each breaking change to see how the upgrade might affect your application.
- npm
- yarn
npm install prisma@3 @prisma/client@3
yarn up prisma@3 @prisma/client@3