Prisma 5.4.0 — Release Notes & Engineering Impact

🌟 **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%20v5.4.0%20%F0%9F%9A%80%0D%0A%0D%0Ahttps://github.com/prisma/prisma/releases/tag/5.4.0) about the release.** 🌟 # **Highlights** ## Preview support for PlanetScale and Neon serverless database drivers We’re excited to announce [Preview](https://www.prisma.io/docs/about/prisma/releases#preview) support for the Neon and PlanetScale serverless database drivers. The PlanetScale and Neon serverless database drivers allow Prisma to connect to your database using protocols besides TCP — HTTP (PlanetScale) or WebSockets (Neon). To get started with the serverless database drivers, first enable the `driverAdapters` Preview feature flag in your Prisma schema: ```prisma // schema.prisma generator client { provider = "prisma-client-js" previewFeatures = ["driverAdapters"] } ``` Next, to set up Prisma Client to use the serverless database drivers: ### **PlanetScale** Install the Prisma adapter for PlanetScale and [PlanetScale serverless database driver](https://github.com/planetscale/database-js), and undici: ```bash npm install @prisma/adapter-planetscale @planetscale/database undici ``` > Prisma ORM supports Node 16 and up. In Node 18 and up, `undici` is not needed. Ensure you update the host value in your connection string to `aws.connect.psdb.cloud`. You can learn more about this [here](https://planetscale.com/docs/tutorials/planetscale-serverless-driver#add-and-use-the-planetscale-serverless-driver-for-javascript-to-your-project). ```bash DATABASE_URL='mysql://johndoe:[email protected]/clear_nightsky?sslaccept=strict' ``` Update your Prisma Client instance to use the PlanetScale database driver: ```tsx // Import required dependencies import { connect } from '@planetscale/database'; import { PrismaPlanetScale } from '@prisma/adapter-planetscale'; import { PrismaClient } from '@prisma/client'; import { fetch as undiciFetch } from 'undici'; // Initialize Prisma Client with the PlanetScale serverless database driver const connection = connect({ url: connectionString, fetch: undiciFetch }); const adapter = new PrismaPlanetScale(connection); const prisma = new PrismaClient({ adapter }); ``` **PlanetScale Driver in 5.7.0 and later** In Prisma 5.7.0, usage of the PlanetScale driver adapter changed to the following: ```tsx // For Prisma 5.7.0 and later // Import required dependencies import { Client } from '@planetscale/database'; import { PrismaPlanetScale } from '@prisma/adapter-planetscale'; import { PrismaClient } from '@prisma/client'; // Initialize Prisma Client with the PlanetScale serverless database driver const client = new Client({ url: process.env.DATABASE_URL }); const adapter = new PrismaPlanetScale(client); const prisma = new PrismaClient({ adapter }); ``` ### **Neon** Install the Prisma adapter for Neon, [Neon serverless database driver](https://github.com/neondatabase/serverless) and undici (WebSockets): ```bash npm install @prisma/adapter-neon @neondatabase/serverless undici ``` Update your Prisma Client instance to use the Neon serverless database driver: ```tsx // Import required dependencies import { Pool, neonConfig } from '@neondatabase/serverless'; import { PrismaNeon } from '@prisma/adapter-neon'; import { PrismaClient } from '@prisma/client'; import { WebSocket } from 'undici' neonConfig.webSocketConstructor = WebSocket; // Initialize Prisma Client with the Neon serverless database driver const pool = new Pool({ connectionString: process.env.DATABASE_URL }); const adapter = new PrismaNeon(pool); const prisma = new PrismaClient({ adapter }); ``` Let us know your feedback about the [Neon](https://github.com/prisma/prisma/discussions/21346) or [Planetscale](https://github.com/prisma/prisma/discussions/21347) serverless database drivers in the linked GitHub discussions. Create a [bug report](https://github.com/prisma/prisma/issues/new?assignees=&labels=kind/bug&projects=&template=bug_report.yml) if you run into any issues. ## Early Access support for Turso [Turso](https://turso.tech/) is an edge-hosted, distributed database that's based on [libSQL](https://turso.tech/libsql), an open-source and open-contribution fork of SQLite, enabling you to bring data closer to your application and minimize query latency. Since support for Turso is in Early Access, there may be some rough edges which we’re still working on it to improve the API and overall support. Additionally, it is behind the `driverAdapters` Preview feature flag. Enable it to get started using Turso in your project: ```groovy // schema.prisma generator client { provider = "prisma-client-js" previewFeatures = ["driverAdapters"] } ``` Next, install the Prisma Client adapter for Turso and the `libSQL` database client ```bash npm install @prisma/adapter-libsql @libsql/client ``` Update your Prisma Client instance: ```tsx // Import required dependencies import { PrismaClient } from '@prisma/client' import { PrismaLibSQL } from '@prisma/adapter-libsql' import { createClient } from '@libsql/client' // Create a new instance of the libSQL database client const libsql = createClient({ // @ts-expect-error url: process.env.TURSO_DATABASE_URL, authToken: process.env.TURSO_AUTH_TOKEN }) // Create a Prisma "adapter" for libSQL const adapter = new PrismaLibSQL(libsql) // Pass the adapter option to the Prisma Client instance const prisma = new PrismaClient({ adapter }) ``` You can learn more on how to use Prisma together with Turso in the [announcement blog post](https://www.prisma.io/blog/prisma-turso-ea-support-rXGd_Tmy3UXX). Try it out! [Let us know what you think](https://github.com/prisma/prisma/discussions/21345) and create a [bug report](https://github.com/prisma/prisma/issues/new?assignees=&labels=kind/bug&projects=&template=bug_report.yml) if you run into any issues. ## Query performance improvements In our continued efforts to make Prisma Client faster, we identified and improved the performance of different types of queries. ### Relation filters improvements We made the following improvements to relation filters: - Removed an unnecessary `INNER JOIN` used in relation filter queries (Big thank you to @KhooHaoYit for helping out) - Use of `LEFT JOIN`'s for to-one relations. Previously, Prisma made use of sub-queries to fetch data. **Example Prisma Client query** ```tsx prisma.comment.findMany({ where: { post: { author: { name: "John" } } } }) ``` **Before 5.4.0** ```sql SELECT "Comment"."id" FROM "Comment" WHERE ("Comment"."id") IN ( SELECT "t0"."id" FROM "Comment" AS "t0" INNER JOIN "Post" AS "j0" ON ("j0"."id") = ("t0"."postId") WHERE ( ("j0"."id") IN ( SELECT "t1"."id" FROM "Post" AS "t1" INNER JOIN "User" AS "j1" ON ("j1"."id") = ("t1"."userId") WHERE ( "j1"."name" = $ 1 AND "t1"."id" IS NOT NULL ) ) AND "t0"."id" IS NOT NULL ) ); ``` **After 5.4.0** ```sql SELECT "Comment"."id" FROM "Comment" LEFT JOIN "Post" AS "j1" ON ("j1"."id") = ("Comment"."postId") LEFT JOIN "User" AS "j2" ON ("j2"."id") = ("j1"."userId") WHERE ( "j2"."name" = $ 1 AND ("j2"."id" IS NOT NULL) AND ("j1"."id" IS NOT NULL) ); ``` If you’re interested in more details on the relation query filter improvements, you can take a look at [this pull request](https://github.com/prisma/prisma-engines/pull/4235). ### Enum improvements on PostgreSQL and CockroachDB Previously, when an enum value was used in a query, our Postgres driver would make additional queries to resolve the enum types that were used. In this release, we’re making improvements by casting enums to `TEXT` to avoid the additional roundtrips when resolving the types. This change should have the most impact if you’re using `pgBouncer` or if you’re running Prisma in a serverless environment, where our Postgres driver can’t cache enum types information. **Prisma schema** ```groovy model User { id Int @id @default(cuid()) role Role } enum Role { User Admin } ``` **Prisma Client query** ```tsx await prisma.user.findMany({ where: { role: "Admin" } }) ``` **Before 5.4.0** ```sql -- Internal driver query SELECT t.typname, t.typtype, t.typelem, r.rngsubtype, t.typbasetype, n.nspname, t.typrelid FROM pg_catalog.pg_type t LEFT OUTER JOIN pg_catalog.pg_range r ON r.rngtypid = t.oid INNER JOIN pg_catalog.pg_namespace n ON t.typnamespace = n.oid WHERE t.oid = $1; -- Internal driver query SELECT enumlabel FROM pg_catalog.pg_enum WHERE enumtypid = $1 ORDER BY enumsortorder; -- Prisma Client query SELECT id, role FROM "User" WHERE role = $1; ``` **After 5.4.0** ```sql -- Prisma Client query SELECT id, role::text FROM "User" WHERE role = CAST($1::text AS "Role); ``` ### Bulk delete improvements We optimized the `deleteMany` operation by: - Removing all `SELECT` queries used to fetch data that would be used as input for the `DELETE` operation. In some cases, this also improves index usage. - Removing the transaction previously used as it’s now a single atomic operation. **Prisma Client query** ```tsx await prisma.post.deleteMany({ where: { id: { gt: 1, lt: 10, } } }) ``` **Before 5.4.0** ```sql BEGIN SELECT id FROM "Post" WHERE id > 1 AND id < 10; SELECT id FROM "Post" WHERE id > 1 AND id < 10 AND id IN (<...select ids>); DELETE FROM "Post" WHERE id IN (<...select ids>) AND id > 1 AND id < 10; COMMIT ``` **After 5.4.0** ```sql DELETE FROM "Post" WHERE id > 1 AND id < 10; ``` ### Upsert improvements We improved the `upsert` operation ([non-native database upsert](https://www.prisma.io/docs/reference/api-reference/prisma-client-reference#database-upserts)) by removing a redundant `SELECT` query: **Prisma Client query** ```tsx await prisma.user.upsert({ where: { email: "[email protected]" }, create: { email: "[email protected]", firstName: "John" }, update: { firstName: "Johnny" }, }) ``` **Before 5.4.0** ```sql SELECT `User`.`id` FROM `User` WHERE `User`.`email` = ?; SELECT `User`.`id` FROM `User` WHERE `User`.`email` = ?; UPDATE `prisma`.`User` SET `firstName` = ? WHERE `prisma`.`User`.`id` IN (?) AND `prisma`.`User`.`email` = ?; SELECT `User`.`id` FROM `User` WHERE `User`.`id` = ?; ``` **After 5.4.0** ```sql SELECT `User`.`id` FROM `User` WHERE `User`.`email` = ?; UPDATE `prisma`.`User` SET `firstName` = ? WHERE `prisma`.`User`.`id` IN (?) AND `prisma`.`User`.`email` = ?; SELECT `User`.`id` FROM `User` WHERE `User`.`id` = ?; ``` ## Fixes and improvements ### Prisma Client - [Unnecessary `SELECT` may be generated by `upsert()`](https://github.com/prisma/prisma/issues/5686) - [Inefficient deleteMany query generation](https://github.com/prisma/prisma/issues/7232) - [Prisma can generate an overly complex and inefficient query in some cases](https://github.com/prisma/prisma/issues/7894) - [`deleteMany` optimisation](https://github.com/prisma/prisma/issues/8239) - [CockroachDB: Highly Variable Query Response Times](https://github.com/prisma/prisma/issues/11317) - [Extremely poor relation where clause query](https://github.com/prisma/prisma/issues/14688) - [Enums loaded as part of transaction after `UPDATE`, slowing down transaction.](https://github.com/prisma/prisma/issues/14955) - [ MongoDB `deleteMany` seems to send 2 identical read queries first before triggering the actual delete](https://github.com/prisma/prisma/issues/15085) - [Query validation messages reference color output even if colors are not enabled](https://github.com/prisma/prisma/issues/17706) - [Prisma generates unnecessary subquery, which is inefficient](https://github.com/prisma/prisma/issues/17879) - [Unnecessary INNER JOIN when doing nested queries](https://github.com/prisma/prisma/issues/18343) - [Semver checks for yarn and typescript could potentially fail](https://github.com/prisma/prisma/issues/18751) - [Prisma overrides type caching when in PGBouncer mode, causing 9,000 enum queries per second on a production system](https://github.com/prisma/prisma/issues/19325) - [deleteMany generates double WHERE filter](https://github.com/prisma/prisma/issues/19950) - [Prisma generate command crashes with `RustPanic: RuntimeError: panicked at 'internal error: entered unreachable code', query-engine/prisma-models/src/field/scalar.rs:93:50`](https://github.com/prisma/prisma/issues/20037) - [Duplicated keys in `metrics` properties](https://github.com/prisma/prisma/issues/21069) - [Prisma Client extension with method override and `jest-mock-extended` or `vitest-mock-extended` expects `never` input ](https://github.com/prisma/prisma/issues/21136) ### Language tools (e.g. VS Code) - [Auto-completion suggests attributes already present ](https://github.com/prisma/language-tools/issues/1326) - [Quick Fix: when `@@schema` is defined in a block without the `schemas` attribute](https://github.com/prisma/language-tools/issues/1333) ### Prisma Engines - [CockroachDB: get_columns can hit inefficiency inside pg_class](https://github.com/prisma/prisma-engines/issues/4250) ## Credits Huge thanks to @onichandame, @fqazi, @KhooHaoYit, @alencardc, @Oreilles, @christianledgard, @skyzh, @alula, @michaelpoellath, @RobertCraigie, @icanipa, @jiashengguo, @stephenwade, @darthmaim, @ludralph, @Gerschtli, @andyjy for helping! ## 💼 We're hiring! If you're interested in joining our growing team to help empower developers to build data-intensive applications, Prisma is the place for you. We're currently hiring for the following roles: - [Software Engineer](https://boards.greenhouse.io/prisma/jobs/6948042002) - [Senior Software Engineer (Rust)](https://boards.greenhouse.io/prisma/jobs/6940273002) - [Engineering Manager: Prisma Data Platform](https://boards.greenhouse.io/prisma/jobs/6927046002) Feel free to read the job descriptions and apply using the links provided.