Today, we are excited to share theĀ 2.26.0
Ā stable releaseĀ š
šĀ Help us spread the word about Prisma by starring the repoĀ orĀ tweetingĀ about the release. šĀ
Major improvements & new features
Referential Actions now enable cascading deletes and updates (Preview)
In this release we are introducing a new feature in Preview which enables fine-grained control over referential actions ON DELETE
and ON UPDATE
for the foreign keys supporting relations in Prisma models.
Current behavior
Until now, Prisma created a foreign key for each relation between Prisma models with the following defaults: ON DELETE CASCADE ON UPDATE CASCADE
. In addition, when invoking the delete()
or deleteAll()
methods, Prisma Client performs runtime checks and will prevent the deletion of records on required relations if there are related objects referencing it, effectively preventing the cascade delete behavior. When using raw SQL queries for deletion, Prisma Client won't perform any checks, and deleting a referenced object will effectively cause the deletion of the referencing objects.
Example:
model User {
id String @id
posts Post[]
}
model Post {
id String @id
authorId String
author User @relation(fields: [authorId])
}
prisma.user.delete(...)
and prisma.user.deleteAll()
will fail if the user has posts.
Using raw SQL, e.g. using $queryRaw()
to delete the user will trigger the deletion of its posts.
New behavior
ā ļø Turning on this feature could, when using delete()
and deleteMany()
operations, delete more data than before under certain circumstances. Make sure you read down below to understand why and anticipate these changes.
The feature can be enabled by setting the preview feature flag referentialActions
in the generator
block of Prisma Client in your Prisma schema file:
generator client {
provider = "prisma-client-js"
previewFeatures = ["referentialActions"]
}
With the feature enabled, the behavior is now the following:
- It's possible to choose specific referential actions for the foreign keys in relations. Prisma Migrate,
prisma db push
, and introspection will set these in the database schema, e.g. @relation(... onDelete: SetNull)
will set translate to ON DELETE SET NULL
on the corresponding foreign key. See Syntax section below.
- When the
onDelete
or onUpdate
attributes in @relation
are not present, default values are used:
ON DELETE RESTRICT
(NO ACTION
on SQL Server) for required relations
ON DELETE SET NULL
for optional relations
ON UPDATE CASCADE
for all relations regardless if optional or required.
- Prisma Migrate,
prisma db push
, and introspection will rely on the syntax and default values above to keep the referential actions between Prisma schema and database schema in sync.
- Prisma Client no longer performs any checks before deleting records when invoking
delete()
or deleteAll()
methods. Deleting referenced objects will succeed or not depending on the underlying foreign keys of relations, e.g. by default deletion will be prevented by the database because it's set to ON DELETE RESTRICT
, but will succeed if set to ON DELETE CASCADE
.
- Upgrade path: If developers don't specify custom
onDelete
or onUpdate
attributes in the Prisma schema, the next time the database is updated with Prisma Migrate or prisma db push
, the database schema will be updated to use the default values on all foreign keys, ON DELETE RESTRICT ON UPDATE CASCADE
(ON DELETE NO ACTION ON UPDATE CASCADE
on SQL Server).
Please note that until then, if the database schema is managed using Prisma Migrate or prisma db push
, the existing defaults are probably in place (ON DELETE CASCADE ON UPDATE CASCADE
), and this could lead to deletion of records in conditions where a deletion was previously prevented by Prisma Client until the foreign key constraints are updated.
Syntax
The semantics ofĀ onDelete
Ā andĀ onUpdate
Ā are almost exactly how SQL expresses ON UPDATE
and ON DELETE
. For the example below:
- If the related author (
User
) of aĀ Post
Ā is deleted (onDelete
), delete allĀ Post
Ā rows that are referencing the deletedĀ User
Ā (Cascade
).
- If theĀ
id
Ā field of the relatedĀ User
Ā is updated, also updateĀ authorId
Ā of allĀ Post
s that reference thatĀ User
.
model User {
id String @id
posts Post[]
}
model Post {
id String @id
authorId String
author User @relation(fields: [authorId], onDelete: Cascade, onUpdate: Cascade)
}
Possible keywords forĀ onDelete
Ā andĀ onUpdate
Ā are: Cascade
, Restrict
(except SQL Server), NoAction
, SetNull
, SetDefault
.
<!--- For a detailed reference, please read our docs. --->
If you run into any questions or have any feedback, we're available in this issue.
Limitations
- Certain combinations of referential actions and required/optional relations are incompatible. Example: Using
SetNull
on a required relation will lead to database errors when deleting referenced records because the non-nullable constraint would be violated.
- Referential actions can not be specified on relations in implicit many-to-many relations. This limitation can be worked around by switching to explicit many-to-many relations and specifying the referential actions on the relations in the relations table.
prisma init
now accepts a --datasource-provider
argument
The prisma init
command now accepts a --datasource-provider
argument that lets you configure the default provider
for the initially generated datasource
block in your Prisma schema. The possible values for this argument are equivalent to the allowed values for the provider
field on datasource
blocks:
postgresql
(default)
mysql
sqlite
sqlserver
(Preview, needs the microsoftSqlServer
preview feature flag)
Here's an example that shows how to configure the initial Prisma schema skeleton with a SQLite database:
npx prisma init --datasource-provider sqlite
Node-API Improvements
The Prisma Client currently communicates to Prisma's Query Engine over either HTTP or Unix domain sockets. After some experimentation, we realized we can improve this communication overhead by using Node-API, which provides direct memory access across processes.
We've been working the last couple of weeks to get ready to make Node-API the default way we communicate with the Query Engine. To prepare for this change, we fixed a bunch of bugs and we'd love for you to give it another try:
generator client {
provider = "prisma-client-js"
previewFeatures = ["nApi"]
}
Right now we're still compiling benchmarks, but you should see a nice speed boost by opting into Node-API. You can reach us in this issue if you run into anything!
Fixes and improvements
Prisma Client
Prisma Migrate
Prisma
Credits
Huge thanks to @B2o5T for helping!
š Prisma Day is happening today!
Prisma Day is a two-day event of talks and workshops by members of the Prisma community, on modern application development and databases. It's taking place June 29-30th and is entirely online.
- June 29th: Workshops
- June 30th: Talks
We look forward to seeing you there!
šŗ Join us for another "What's new in Prisma" livestream
Learn about the latest release and other news from the Prisma community by joining us for another "What's new in Prisma" livestream.
The stream takes place on Youtube on Thursday, July 01 at 5pm Berlin | 8am San Francisco.