@prisma/client

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 Posts 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

• No way to cascade delete when the foreign key is non-nullable
• Delete to use the include attribute to cascade deletes
• Delete of "parent" should not be prevented if it will cascade delete "children" on required relations
• Enable cascading delete behavior with onDelete: CASCADE
• Add TypeScript version check
• Error when using join raw query helper with SQL Server
• Using current CLI and older Client generate gives TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be of type string. Received an instance of Object or TypeError: outputDir.endsWith is not a function error and no helpful output
• Prisma 2.24.0 throws error Query engine exited with code 101 - thread 'main' panicked at 'Could not open datamodel file "/schema.prisma"...'
• Fully test Node-API libraries
• Flaky Engine is not yet connected. CI test with Node-API
• Internal: client fixtures fail to generate
• Latest Prisma (2.24.x) version breaks some pnpm projects when generating models
• Review all tests for engine types

Prisma Migrate

• Cascade deletes doesn't work on many to many relations
• Support for configuring referential actions (on delete, on cascade) in Prisma Schema Language
• Implicit relation tables always have onDelete CASCADE, this should be configurable.
• Failure creating a migration with MSSQL: Introducing FOREIGN KEY constraint '...' on table '...' may cause cycles or multiple cascade paths. Specify ON DELETE NO ACTION or ON UPDATE NO ACTION, or modify other FOREIGN KEY constraints.
• Introspection migration adds ON UPDATE CASCADE ON DELETE SET NULL to foreign key constraints
• The meaning of "arity" in Migrate drift summaries is not clear
• Display the position of migration errors in the script on Postgres

Prisma

• Proposal: onDelete and onUpdate relation properties
• 2.23.0 can not recognize binaryTargets: env("..") inside generator client section

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.