Prisma 2.12.0 — Release Notes & Engineering Impact

Today, we are excited to share the `2.12.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%20Prisma%20release%202.12.0%20%F0%9F%9A%80%0D%0A%0D%0Ahttps://github.com/prisma/prisma/releases/tag/2.12.0) about the release.** ## Major improvements ### Standalone Prisma Studio app for macOS We have repackaged Prisma Studio to work also as a standalone macOS application. This should help you run Studio with just a double click and without opening your terminal, just in case you quickly want to browse or edit your data. Download the installation files from the [Studio release page](https://github.com/prisma/studio/releases). Support for more platforms (Windows and Linux) will come soon. Let us know if which one you would want first! ### Prisma codemods help upgrading your codebase With today's release, we took the opportunity to cleanup some rough edges in the Prisma Client API which partially results in _breaking changes_. To help you with upgrading your codebase to `2.12.0`, we're introducing [`@prisma/codemods`](https://github.com/prisma/codemods). The `@prisma/codemods` package provides a powerful CLI that scans your codebase and automatically updates the code to the new API calls from the provided version. The upgrade workflow looks like this: ```bash cd my-app npm install @prisma/cli @prisma/client npx @prisma/codemods update-2.12 ./ ``` ### Microsoft SQL Server now supports native database types (Preview) Hot off the presses: You can now use database native types with Microsoft SQL Server! You'll need to specify both `previewFeatures = ["microsoftSqlServer", "nativeTypes"]` to get started: ```prisma generator js { provider = "prisma-client-js" previewFeatures = ["microsoftSqlServer", "nativeTypes"] } datasource ms { provider = "sqlserver" url = env("DATABASE_URL") } model User { id BigInt @id @default(autoincrement()) @ms.BigInt name String? @ms.VarChar(255) } model Post { id BigInt @id @default(autoincrement()) @ms.BigInt title String @ms.VarChar(100) views BigInt @default(0) @ms.BigInt wordCount Int @default(0) @ms.SmallInt } ``` Note that Prisma Migrate does not yet work with Microsoft SQL Server, nor does Prisma Client Go. ### Upcoming Prisma Migrate Preview Release We’ve got a Preview release of Prisma Migrate nearing up with a large set of changes. You can test it in Early Access, see the upcoming changes, and provide feedback! Get started with the Early Access version [here](http://pris.ly/migrate-early-access). To join the conversation, join the [`#product-feedback`](https://app.slack.com/client/T0MQBS8JG/C01739JGFCM) channel on our [Slack](https://slack.prisma.io). ## Breaking changes As mentioned before, we're cleaning up the Prisma Client API which partially results in breaking changes. You can upgrade to the latest version using the new `@prisma/codemods` package as explained above. ### Remove non-`$` methods A few months back, we began prefixing our top-level Prisma methods with `$`. For example, `prisma.transaction` became `prisma.$transaction`. We did this to avoid clashes with your application's model names. The non-`$` methods were deprecated but continued to work until this release. In this release, we removed the deprecated methods. This means **if you are still using calls like `prisma.transaction` or `prisma.disconnect` instead of `prisma.$transaction` or `prisma.$disconnect` in your code, your app is going to break after upgrading to `2.12.0`**. The `@prisma/codemods` workflow describe above will automatically fix any remaining non-$ methods in your codebase. You can read more about this change in on [Github](https://github.com/prisma/prisma/issues/4206). ### 1-1-relations must now have an optional side In this version, we're adding a new requirement for [1-1-relations](https://www.prisma.io/docs/concepts/components/prisma-schema/relations#one-to-one-relations) that you define in your Prisma schema. In previous versions, it used to be allowed to have both sides of the relation _required_. As of this release, the _virtual_ side of the relation (i.e. the side that does _not_ store the foreign key in the underlying database) must be optional. **Before** ```prisma model User { id Int @id @default(autoincrement()) name String? profile Profile // ❌ this is not allowed as of 2.12.0 } model Profile { id Int @id @default(autoincrement()) user User @relation(fields: [userId], references: [id]) userId Int } ``` **After** ```prisma model User { id Int @id @default(autoincrement()) profile Profile? // ✅ the virtual side of the relation needs to be optional } model Profile { id Int @id @default(autoincrement()) user User @relation(fields: [userId], references: [id]) userId Int } ``` The easiest way to adjust your schema to these new requirements is by running the `introspect` command which will automatically make the virtual relation fields optional on 1-1-relations: ``` npx prisma introspect ``` ### Fix how data for `Json[]` fields is stored We fixed how the `Json[]` type is stored in `2.12.0`. Previously, we were storing JSON arrays as a string inside a your database's `JSON` column. Now, we properly encode JSON arrays as `JSON` in the database. This fix will allow us to add database native JSON operations down the line. If you are using the `Json[]` type in your schema, you'll need to migrate your data. We anticipate this breaking change will only affect a handful of folks. Please reach out to us in [this issue](https://github.com/prisma/prisma/issues/4346) and we'll help you with the migration. Here is an overview of how the behaviour changes in `2.12.0`: | Given | `2.11.0` | `2.12.0` | | :-------------------------------------- | :-------------------------------------------------- | :------------------------------------- | | `[]` | `[[]]` | `[]` | | `[{test:"test"}]` | `["{\"test\":\"test\"}"]` | `[{"test":"test"}]` | | `[{ test: "test" }, { test: "test2" }]` | `["[{\"test\": \"test\"}, {\"test\": \"test2\"}]"]` | `[{"test": "test"},{"test": "test2"}]` | | `[3]` | `3` | `[3]` | ## Deprecations ### Rename `findOne` to `findUnique` This release renames `findOne` to `findUnique` and deprecates `findOne`. We made this change to reduce confusion. Many people expected `findOne` to be more loose, e.g: "Find the first record that matches my conditions.". The `@prisma/codemods` workflow describe above will automatically rename `findOne` to `findUnique` across your codebase. ### Move most types under the `Prisma` namespace We moved most of the generated types under a new `Prisma` namespace and are deprecating the top-level exports. This change also resolves some existing namespace clashes. **Before** ```ts import { PrismaClient, User, UserCreateInput } from '@prisma/client' async function createUser(input: UserCreateInput): Promise<User> { return prisma.user.create(input) } ``` **After** ```ts import { PrismaClient, User, Prisma } from '@prisma/client' async function createUser(input: Prisma.UserCreateInput): Promise<User> { return prisma.user.create(input) } ``` This means that with this release, there are exactly three kinds of exports in `@prisma/client`: 1. `PrismaClient` is the constructor your Prisma Client instance 1. Model types, e.g. `User` and `Post` 1. `Prisma` as the new namespace under which you can now access the remaining generarted types The `@prisma/codemods` workflow describe above will automatically fix the type names in your code! With this change, we've greatly reduced the number of *reserved words* that could clash with your application's names. Go forth and add models with names like `Transaction` or `Aggregate`! ## Fixes and improvements ### [`prisma`](https://github.com/prisma/prisma) - [Improve .raw`` template literal API with helpers](https://github.com/prisma/prisma/issues/1749) - [Remove GraphQL related reserved words](https://github.com/prisma/prisma/issues/3223) - [Collect `dbgenerated()` values in an issue via "warning" output in Introspection](https://github.com/prisma/prisma/issues/3290) - [Json arrays are not properly stored in underlying postgres jsonb array type ](https://github.com/prisma/prisma/issues/3603) - [Replace `findOne` with `findUnique`](https://github.com/prisma/prisma/issues/3697) - [Schema validator is not validating optionality of relations on both ends](https://github.com/prisma/prisma/issues/3747) - [Use TypeScript namespaces to separate Prisma & Application types](https://github.com/prisma/prisma/issues/3755) - [Enable updating foreign keys in updateMany](https://github.com/prisma/prisma/issues/3887) - [Json[] isn't working anymore](https://github.com/prisma/prisma/issues/3897) - [Fields are ignored in WHERE clause](https://github.com/prisma/prisma/issues/3985) - [Native Types Postgres: Creating a record with empty arrays for field types json[], jsonb[] not working](https://github.com/prisma/prisma/issues/4053) - [Create codemod for namespace change](https://github.com/prisma/prisma/issues/4150) - [Prisma2 blocks prisma generate on unsupported platforms, even when providing custom binaries](https://github.com/prisma/prisma/issues/4205) - [Cleanup old non-$ methods](https://github.com/prisma/prisma/issues/4206) - [Fix version pinning logic](https://github.com/prisma/prisma/issues/4213) - [Warn, if more than `n` Prisma Client instances are instantiated](https://github.com/prisma/prisma/issues/4222) - [Add codemod for $ deprecation](https://github.com/prisma/prisma/issues/4300) - [SQL Server raw queries panic when having multiple result sets](https://github.com/prisma/prisma/issues/4332) ### [`prisma-client-js`](https://github.com/prisma/prisma-client-js) - [Improve debug output of array values](https://github.com/prisma/prisma-client-js/issues/312) - [[Javascript] Better error message than `TypeError: Cannot read property 'findMany' of undefined` for non existing model?](https://github.com/prisma/prisma-client-js/issues/585) - [Remove Aggregate as reserved word](https://github.com/prisma/prisma-client-js/issues/811) - [Test and stabilize Unix Domain Sockets](https://github.com/prisma/prisma-client-js/issues/837) ### [`migrate`](https://github.com/prisma/migrate) - [ERROR: there is no unique constraint matching given keys for referenced table "User"](https://github.com/prisma/migrate/issues/418) - [Suggest using `name` on index when creation fails because of length](https://github.com/prisma/migrate/issues/472) ### [`language-tools`](https://github.com/prisma/language-tools) - [Display relation fields differently than scalar fields](https://github.com/prisma/language-tools/issues/41) - [Warn about provider array deprecation in the VSCode plugin](https://github.com/prisma/language-tools/issues/522) - [Improve logging of language server](https://github.com/prisma/language-tools/issues/627) ### [`studio`](https://github.com/prisma/studio) - [When saving changes to the database, do it one transaction](https://github.com/prisma/studio/issues/578) - [Studio server does not resolve environment variables correctly](https://github.com/prisma/studio/issues/579) - [Focus first cell of a newly created record](https://github.com/prisma/studio/issues/580) - [When you start typing in a number cell directly, it is considered an invalid change](https://github.com/prisma/studio/issues/581) ### [`prisma-engines`](https://github.com/prisma/prisma-engines) - [Send the "server listening" message only after the server has started](https://github.com/prisma/prisma-engines/issues/1173) - [Supporting native types on SQL Server](https://github.com/prisma/prisma-engines/issues/1183) ## Credits Huge thanks to @matt-eric, @muxahuk for helping!