Prisma 2.26.0 — Release Notes & Engineering Impact

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](https://twitter.com/intent/tweet?text=Check%20out%20the%20latest%20@prisma%20release%20v2.26.0%20%F0%9F%9A%80%0D%0A%0D%0Ahttps://github.com/prisma/prisma/releases/tag/2.26.0) 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: ```prisma 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: ```prisma 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`. ```prisma 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](https://www.prisma.io/docs/concepts/components/prisma-schema/referential-actions). ---> If you run into any questions or have any feedback, we're available in [this issue](https://github.com/prisma/prisma/issues/7816). #### 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](https://www.prisma.io/docs/concepts/components/prisma-schema/relations#implicit-many-to-many-relations). This limitation can be worked around by switching to [explicit many-to-many](https://www.prisma.io/docs/concepts/components/prisma-schema/relations#explicit-many-to-many-relations) relations and specifying the referential actions on the relations in the [relations table](https://www.prisma.io/docs/concepts/components/prisma-schema/relations#relation-tables). ### `prisma init` now accepts a `--datasource-provider` argument The [`prisma init`](https://www.prisma.io/docs/reference/api-reference/command-reference#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](https://www.prisma.io/docs/reference/api-reference/prisma-schema-reference#fields) for the `provider` field on `datasource` blocks: - `postgresql` (default) - `mysql` - `sqlite` - `sqlserver` ([Preview](https://github.com/prisma/prisma/issues/4039), 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](https://nodejs.org/api/n-api.html), 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: ```prisma 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](https://github.com/prisma/prisma/issues/6301) if you run into anything! ## Fixes and improvements ### Prisma Client - [No way to cascade delete when the foreign key is non-nullable](https://github.com/prisma/prisma/issues/2057) - [Delete to use the include attribute to cascade deletes](https://github.com/prisma/prisma/issues/2092) - [Delete of "parent" should not be prevented if it will cascade delete "children" on required relations](https://github.com/prisma/prisma/issues/4650) - [Enable cascading delete behavior with onDelete: CASCADE](https://github.com/prisma/prisma/issues/4711) - [Add TypeScript version check](https://github.com/prisma/prisma/issues/5728) - [Error when using `join` raw query helper with SQL Server](https://github.com/prisma/prisma/issues/6276) - [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](https://github.com/prisma/prisma/issues/6535) - [Prisma 2.24.0 throws error `Query engine exited with code 101 - thread 'main' panicked at 'Could not open datamodel file "/schema.prisma"...'`](https://github.com/prisma/prisma/issues/7439) - [Fully test Node-API libraries](https://github.com/prisma/prisma/issues/7564) - [Flaky `Engine is not yet connected.` CI test with Node-API](https://github.com/prisma/prisma/issues/7569) - [Internal: client fixtures fail to generate](https://github.com/prisma/prisma/issues/7652) - [Latest Prisma (2.24.x) version breaks some pnpm projects when generating models](https://github.com/prisma/prisma/issues/7661) - [Review all tests for engine types](https://github.com/prisma/prisma/issues/7695) ### Prisma Migrate - [Cascade deletes doesn't work on many to many relations](https://github.com/prisma/prisma/issues/2328) - [Support for configuring referential actions (on delete, on cascade) in Prisma Schema Language](https://github.com/prisma/prisma/issues/2810) - [Implicit relation tables always have `onDelete CASCADE`, this should be configurable.](https://github.com/prisma/prisma/issues/4166) - [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.`](https://github.com/prisma/prisma/issues/5782) - [Introspection migration adds ON UPDATE CASCADE ON DELETE SET NULL to foreign key constraints](https://github.com/prisma/prisma/issues/6999) - [The meaning of "arity" in Migrate drift summaries is not clear](https://github.com/prisma/prisma/issues/7675) - [Display the position of migration errors in the script on Postgres](https://github.com/prisma/prisma/issues/7908) ### Prisma - [Proposal: onDelete and onUpdate relation properties](https://github.com/prisma/prisma/issues/6996) - [2.23.0 can not recognize `binaryTargets: env("..")` inside `generator client` section](https://github.com/prisma/prisma/issues/7295) ## Credits Huge thanks to @B2o5T for helping! ## 🌎 Prisma Day is happening today! [Prisma Day](https://prisma.io/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"](https://www.youtube.com/watch?v=i8TqB5ofVaM) livestream. The stream takes place [on Youtube](https://www.youtube.com/watch?v=i8TqB5ofVaM) on **Thursday, July 01** at **5pm Berlin | 8am San Francisco**.