diff --git a/content/200-orm/050-overview/500-databases/300-postgresql.mdx b/content/200-orm/050-overview/500-databases/300-postgresql.mdx index 664b821e70..a9985c59fc 100644 --- a/content/200-orm/050-overview/500-databases/300-postgresql.mdx +++ b/content/200-orm/050-overview/500-databases/300-postgresql.mdx @@ -161,10 +161,10 @@ The following arguments can be used: | `host` | No | | Points to a directory that contains a socket to be used for the connection | | `socket_timeout` | No | | Maximum number of seconds to wait until a single query terminates | | `pgbouncer` | No | `false` | Configure the Engine to [enable PgBouncer compatibility mode](/orm/prisma-client/setup-and-configuration/databases-connections/pgbouncer) | -| `statement_cache_size` | No | `100` | Since 2.1.0: Specifies the number of [prepared statements](#prepared-statement-caching) cached per connection | -| `application_name` | No | | Since 3.3.0: Specifies a value for the application_name configuration parameter | -| `channel_binding` | No | `prefer` | Since 4.8.0: Specifies a value for the channel_binding configuration parameter | -| `options` | No | | Since 3.8.0: Specifies command line options to send to the server at connection start | +| `statement_cache_size` | No | `100` | Specifies the number of [prepared statements](#prepared-statement-caching) cached per connection | +| `application_name` | No | | Specifies a value for the application_name configuration parameter | +| `channel_binding` | No | `prefer` | Specifies a value for the channel_binding configuration parameter | +| `options` | No | | Specifies command line options to send to the server at connection start | As an example, if you want to connect to a schema called `myschema`, set the connection pool size to `5` and configure a timeout for queries of `3` seconds. You can use the following arguments: diff --git a/content/200-orm/050-overview/500-databases/500-sqlite.mdx b/content/200-orm/050-overview/500-databases/500-sqlite.mdx index 6218a8b124..2393683418 100644 --- a/content/200-orm/050-overview/500-databases/500-sqlite.mdx +++ b/content/200-orm/050-overview/500-databases/500-sqlite.mdx @@ -65,7 +65,7 @@ When using `enum` fields in SQLite, be aware of the following: SQLite is a loosely-typed database. If your Schema has a field of type `Int`, then Prisma ORM prevents you from inserting a value larger than an integer. However, nothing prevents the database from directly accepting a bigger number. These manually-inserted big numbers cause rounding errors when queried. -To avoid this problem, Prisma ORM 4.0.0 and later checks numbers on the way out of the database to verify that they fit within the boundaries of an integer. If a number does not fit, then Prisma ORM throws a P2023 error, such as: +To avoid this problem, Prisma ORM checks numbers on the way out of the database to verify that they fit within the boundaries of an integer. If a number does not fit, then Prisma ORM throws a P2023 error, such as: ``` Inconsistent column data: Conversion failed: diff --git a/content/200-orm/050-overview/500-databases/800-sql-server/index.mdx b/content/200-orm/050-overview/500-databases/800-sql-server/index.mdx index 50138a1066..7c765ae3e6 100644 --- a/content/200-orm/050-overview/500-databases/800-sql-server/index.mdx +++ b/content/200-orm/050-overview/500-databases/800-sql-server/index.mdx @@ -70,7 +70,7 @@ sqlserver://HOST[:PORT];database=DATABASE;user={MyServer/MyUser};password={ThisI | `socketTimeout` | No | | Number of seconds to wait for each query to succeed. | | `isolationLevel` | No | | Sets [transaction isolation level](https://learn.microsoft.com/en-us/sql/t-sql/statements/set-transaction-isolation-level-transact-sql?view=sql-server-ver15). | | `poolTimeout` | No | `10` | Maximum number of seconds to wait for a new connection from the pool. If all connections are in use, the database will return a `PoolTimeout` error after waiting for the given time. | -| (case insensitive) | No | | Sets the application name for the connection. Since version 2.28.0. | +| (case insensitive) | No | | Sets the application name for the connection. | | `trustServerCertificate` | No | `false` | Configures whether to trust the server certificate. | | `trustServerCertificateCA` | No | | A path to a certificate authority file to be used instead of the system certificates to authorize the server certificate. Must be either in `pem`, `crt` or `der` format. Cannot be used together with `trustServerCertificate` parameter. | @@ -108,7 +108,7 @@ See [Supported databases](/orm/reference/supported-databases). ### Prisma Migrate caveats -Prisma Migrate is supported in [2.13.0](https://github.com/prisma/prisma/releases/tag/2.13.0) and later with the following caveats: +Prisma Migrate is supported with the following caveats: #### Database schema names diff --git a/content/200-orm/050-overview/500-databases/840-cockroachdb.mdx b/content/200-orm/050-overview/500-databases/840-cockroachdb.mdx index 846f1401d4..ac6408c4bc 100644 --- a/content/200-orm/050-overview/500-databases/840-cockroachdb.mdx +++ b/content/200-orm/050-overview/500-databases/840-cockroachdb.mdx @@ -6,18 +6,8 @@ tocDepth: 3 toc: true --- - - This guide discusses the concepts behind using Prisma ORM and CockroachDB, explains the commonalities and differences between CockroachDB and other database providers, and leads you through the process for configuring your application to integrate with CockroachDB. - - - - -The CockroachDB connector is generally available in versions `3.14.0` and later. It was first added as a [Preview feature](/orm/reference/preview-features) in version [`3.9.0`](https://github.com/prisma/prisma/releases/tag/3.9.0) with support for Introspection, and Prisma Migrate support was added in [`3.11.0`](https://github.com/prisma/prisma/releases/tag/3.11.0). - - - ## What is CockroachDB? CockroachDB is a distributed database that is designed for scalability and high availability. Features include: @@ -110,7 +100,7 @@ The fields passed to the `datasource` block are: -While `cockroachdb` and `postgresql` connectors are similar, it is mandatory to use the `cockroachdb` connector instead of `postgresql` when connecting to a CockroachDB database from version 5.0.0. +While `cockroachdb` and `postgresql` connectors are similar, it is mandatory to use the `cockroachdb` connector instead of `postgresql` when connecting to a CockroachDB database. diff --git a/content/200-orm/050-overview/500-databases/850-planetscale.mdx b/content/200-orm/050-overview/500-databases/850-planetscale.mdx index 51c8cda807..f6c6c2a795 100644 --- a/content/200-orm/050-overview/500-databases/850-planetscale.mdx +++ b/content/200-orm/050-overview/500-databases/850-planetscale.mdx @@ -65,9 +65,7 @@ If you try to push to a production branch, you will get the [error message](/orm #### 1. Set `relationMode = "prisma"` -PlanetScale does not use foreign key constraints in its database schema by default. However, Prisma ORM relies on foreign key constraints in the underlying database to enforce referential integrity between models in your Prisma schema. - -In Prisma ORM versions 3.1.1 and later, you can [emulate relations in Prisma Client with the `prisma` relation mode](/orm/prisma-schema/data-model/relations/relation-mode#emulate-relations-in-prisma-orm-with-the-prisma-relation-mode), which avoids the need for foreign key constraints in the database. +PlanetScale does not use foreign key constraints in its database schema by default. However, Prisma ORM relies on foreign key constraints in the underlying database to enforce referential integrity between models in your Prisma schema. You can [emulate relations in Prisma Client with the `prisma` relation mode](/orm/prisma-schema/data-model/relations/relation-mode#emulate-relations-in-prisma-orm-with-the-prisma-relation-mode), which avoids the need for foreign key constraints in the database. To enable emulation of relations in Prisma Client, set the `relationMode` field to `"prisma"` in the `datasource` block: @@ -79,13 +77,7 @@ datasource db { } ``` - - -The ability to set the relation mode was introduced as part of the `referentialIntegrity` preview feature in Prisma ORM version 3.1.1, and is generally available in Prisma ORM versions 4.8.0 and later.

The `relationMode` field was renamed in Prisma ORM version 4.5.0, and was previously named `referentialIntegrity`. - - - -If you use relations in your Prisma schema with the default `"foreignKeys"` option for the `relationMode` field, PlanetScale will error and Prisma ORM output the [P3021 error message](/orm/reference/error-reference#p3021) when it tries to create foreign keys. (In versions before 2.27.0 it will output a raw database error.) +If you use relations in your Prisma schema with the default `"foreignKeys"` option for the `relationMode` field, PlanetScale will error and Prisma ORM output the [P3021 error message](/orm/reference/error-reference#p3021) when it tries to create foreign keys. #### 2. Create indexes on foreign keys @@ -134,7 +126,7 @@ model Comment { You can then add this change to your schema [using `db push`](#how-to-make-schema-changes-with-db-push). -In versions 4.7.0 and later, Prisma ORM warns you if you have a relation with no index on the relation scalar field. For more information, see [Index validation](/orm/prisma-schema/data-model/relations/relation-mode#index-validation). +Prisma ORM will warn you if you have a relation with no index on the relation scalar field. For more information, see [Index validation](/orm/prisma-schema/data-model/relations/relation-mode#index-validation). diff --git a/content/200-orm/100-prisma-schema/10-overview/02-data-sources.mdx b/content/200-orm/100-prisma-schema/10-overview/02-data-sources.mdx index fc97d81577..d2fc1377ee 100644 --- a/content/200-orm/100-prisma-schema/10-overview/02-data-sources.mdx +++ b/content/200-orm/100-prisma-schema/10-overview/02-data-sources.mdx @@ -4,8 +4,6 @@ metaTitle: 'Data sources (Reference)' metaDescription: 'Data sources enable Prisma to connect to your database. This page explains how to configure data sources in your Prisma schema.' --- - - A data source determines how Prisma ORM connects your database, and is represented by the [`datasource`](/orm/reference/prisma-schema-reference#datasource) block in the Prisma schema. The following data source uses the `postgresql` provider and includes a connection URL: ```prisma @@ -20,10 +18,6 @@ A Prisma schema can only have _one_ data source. However, you can: - [Programmatically override a data source `url` when creating your `PrismaClient`](/orm/reference/prisma-client-reference#programmatically-override-a-datasource-url) - [Specify a different URL for Prisma Migrate's shadow database if you are working with cloud-hosted development databases](/orm/prisma-migrate/understanding-prisma-migrate/shadow-database#cloud-hosted-shadow-databases-must-be-created-manually) -> **Note**: Multiple provider support was removed in 2.22.0. Please see [Deprecation of provider array notation](https://github.com/prisma/prisma/issues/3834) for more information. - - - ## Securing database connections Some data source `provider`s allow you to configure your connection with SSL/TLS, and provide parameters for the `url` to specify the location of certificates. diff --git a/content/200-orm/100-prisma-schema/10-overview/04-location.mdx b/content/200-orm/100-prisma-schema/10-overview/04-location.mdx index ce40444b4f..0a8dfd2852 100644 --- a/content/200-orm/100-prisma-schema/10-overview/04-location.mdx +++ b/content/200-orm/100-prisma-schema/10-overview/04-location.mdx @@ -18,7 +18,7 @@ The Prisma CLI looks for the Prisma Schema in the following locations, in the fo prisma generate --schema=./alternative/schema.prisma ``` -2. The location specified in the `package.json` file (version 2.7.0 and later): +2. The location specified in the `package.json` file: ```json "prisma": { diff --git a/content/200-orm/100-prisma-schema/20-data-model/10-models.mdx b/content/200-orm/100-prisma-schema/20-data-model/10-models.mdx index f8b2711c3e..821892e885 100644 --- a/content/200-orm/100-prisma-schema/20-data-model/10-models.mdx +++ b/content/200-orm/100-prisma-schema/20-data-model/10-models.mdx @@ -439,7 +439,7 @@ Refer to the [relations documentation](/orm/prisma-schema/data-model/relations) ### Native types mapping -Version [2.17.0](https://github.com/prisma/prisma/releases/tag/2.17.0) and later support **native database type attributes** (type attributes) that describe the underlying database type: +Prisma ORM supports **native database type attributes** (type attributes) that describe the underlying database type: ```prisma highlight=3;normal model Post { @@ -795,7 +795,7 @@ model Post { Default values can be: - Static values that correspond to the field type, such as `5` (`Int`), `Hello` (`String`), or `false` (`Boolean`) -- [Lists](/orm/reference/prisma-schema-reference#-modifier) of static values, such as `[5, 6, 8]` (`Int[]`) or `["Hello", "Goodbye"]` (`String`[]). These are available in Prisma ORM versions `4.0.0` and later, when using supported databases (PostgreSQL, CockroachDB and MongoDB) +- [Lists](/orm/reference/prisma-schema-reference#-modifier) of static values, such as `[5, 6, 8]` (`Int[]`) or `["Hello", "Goodbye"]` (`String`[]). These are available when using supported databases (PostgreSQL, CockroachDB and MongoDB) - [Functions](#using-functions), such as [`now()`](/orm/reference/prisma-schema-reference#now) or [`uuid()`](/orm/reference/prisma-schema-reference#uuid) - JSON data. Note that JSON needs to be enclosed with double-quotes inside the `@default` attribute, e.g.: `@default("[]")`. If you want to provide a JSON object, you need to enclose it with double-quotes and then escape any internal double quotes using a backslash, e.g.: `@default("{ \"hello\": \"world\" }")`. @@ -913,7 +913,7 @@ Refer to the documentation on [working with composite unique identifiers](/orm/p #### Composite type unique constraints -When using the MongoDB provider in version `3.12.0` and later, you can define a unique constraint on a field of a [composite type](#defining-composite-types) using the syntax `@@unique([compositeType.field])`. As with other fields, composite type fields can be used as part of a multi-column unique constraint. +When using the MongoDB provider you can define a unique constraint on a field of a [composite type](#defining-composite-types) using the syntax `@@unique([compositeType.field])`. As with other fields, composite type fields can be used as part of a multi-column unique constraint. The following example defines a multi-column unique constraint based on the `email` field of the `User` model and the `number` field of the `Address` composite type which is used in `User.address`: @@ -975,7 +975,7 @@ You can optionally define a [custom index name](/orm/prisma-schema/data-model/da #### Defining composite type indexes -When using the MongoDB provider in version `3.12.0` and later, you can define an index on a field of a [composite type](#defining-composite-types) using the syntax `@@index([compositeType.field])`. As with other fields, composite type fields can be used as part of a multi-column index. +When using the MongoDB provider you can define an index on a field of a [composite type](#defining-composite-types) using the syntax `@@index([compositeType.field])`. As with other fields, composite type fields can be used as part of a multi-column index. The following example defines a multi-column index based on the `email` field of the `User` model and the `number` field of the `Address` composite type: @@ -1067,12 +1067,6 @@ enum Role { ## Defining composite types - - -Composite types were added in version `3.10.0` under the `mongodb` Preview feature flag and are in General Availability since version `3.12.0`. - - - Composite types are currently only available on MongoDB. diff --git a/content/200-orm/100-prisma-schema/20-data-model/20-relations/100-one-to-one-relations.mdx b/content/200-orm/100-prisma-schema/20-data-model/20-relations/100-one-to-one-relations.mdx index 577a7a80e8..6b7fe30f42 100644 --- a/content/200-orm/100-prisma-schema/20-data-model/20-relations/100-one-to-one-relations.mdx +++ b/content/200-orm/100-prisma-schema/20-data-model/20-relations/100-one-to-one-relations.mdx @@ -95,7 +95,7 @@ model Profile { -In MySQL, you can create a foreign key with only an index on the referenced side, and not a unique constraint. In Prisma ORM versions 4.0.0 and later, if you introspect a relation of this type it will trigger a validation error. To fix this, you will need to add a `@unique` constraint to the referenced field. +In MySQL, you can create a foreign key with only an index on the referenced side, and not a unique constraint. If you introspect a relation of this type it will trigger a validation error. To fix this, you will need to add a `@unique` constraint to the referenced field. @@ -190,8 +190,6 @@ model User { } ``` -This restriction was introduced in 2.12.0. - However, you can choose if the side of the relation _with_ a relation scalar should be optional or mandatory. ### Mandatory 1-1 relation diff --git a/content/200-orm/100-prisma-schema/20-data-model/20-relations/200-one-to-many-relations.mdx b/content/200-orm/100-prisma-schema/20-data-model/20-relations/200-one-to-many-relations.mdx index 8a46de8dec..48cff7ae91 100644 --- a/content/200-orm/100-prisma-schema/20-data-model/20-relations/200-one-to-many-relations.mdx +++ b/content/200-orm/100-prisma-schema/20-data-model/20-relations/200-one-to-many-relations.mdx @@ -93,7 +93,7 @@ model Post { -In MySQL, you can create a foreign key with only an index on the referenced side, and not a unique constraint. In Prisma ORM versions 4.0.0 and later, if you introspect a relation of this type it will trigger a validation error. To fix this, you will need to add a `@unique` constraint to the referenced field. +In MySQL, you can create a foreign key with only an index on the referenced side, and not a unique constraint. If you introspect a relation of this type it will trigger a validation error. To fix this, you will need to add a `@unique` constraint to the referenced field. diff --git a/content/200-orm/100-prisma-schema/20-data-model/20-relations/410-referential-actions/index.mdx b/content/200-orm/100-prisma-schema/20-data-model/20-relations/410-referential-actions/index.mdx index 2e0d6ccc7f..d635b61a60 100644 --- a/content/200-orm/100-prisma-schema/20-data-model/20-relations/410-referential-actions/index.mdx +++ b/content/200-orm/100-prisma-schema/20-data-model/20-relations/410-referential-actions/index.mdx @@ -5,21 +5,7 @@ metaDescription: 'Referential actions let you define the update and delete behav tocDepth: 3 --- - - -Referential actions determine what happens to a record when your application deletes or updates a related record. - -From version 2.26.0, you can define referential actions on the relation fields in your Prisma schema. This allows you to define referential actions like cascading deletes and cascading updates at a Prisma ORM level. - - - -**Version differences** - -- If you use version 3.0.1 or later, you can use referential actions as described on this page. -- If you use a version between 2.26.0 and 3.0.0, you can use referential actions as described on this page, but you must [enable the preview feature flag](/orm/reference/preview-features/client-preview-features#enabling-a-prisma-client-preview-feature) `referentialActions`. -- If you use version 2.25.0 or earlier, you can configure cascading deletes manually in your database. - - +Referential actions determine what happens to a record when your application deletes or updates a related record. You can define referential actions on the relation fields in your Prisma schema. This allows you to define referential actions like cascading deletes and cascading updates at a Prisma ORM level. In the following example, adding `onDelete: Cascade` to the `author` field on the `Post` model means that deleting the `User` record will also delete all related `Post` records. @@ -39,15 +25,6 @@ model User { If you do not specify a referential action, Prisma ORM [uses a default](#referential-action-defaults). - - - - -If you upgrade from a version earlier than 2.26.0: -It is extremely important that you check the [upgrade paths for referential actions](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-3/referential-actions) section. Prisma ORM's support of referential actions **removes the safety net in Prisma Client that prevents cascading deletes at runtime**. If you use the feature _without upgrading your database_, the [old default action](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-3/referential-actions#prisma-orm-2x-default-referential-actions) - `ON DELETE CASCADE` - becomes active. This might result in cascading deletes that you did not expect. - - - ## What are referential actions? Referential actions are policies that define how a referenced record is handled by the database when you run an [`update`](/orm/prisma-client/queries/crud#update) or [`delete`](/orm/prisma-client/queries/crud#delete) query. @@ -160,12 +137,11 @@ The following table shows which referential action each database supports. | SQLite | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | | SQL Server | ✔️ | ❌‡ | ✔️ | ✔️ | ✔️ | | CockroachDB | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | -| MongoDB†† | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | +| MongoDB | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | - † See [special cases for MySQL](#mysqlmariadb). - ⌘ See [special cases for PostgreSQL](#postgresql). - ‡ See [special cases for SQL Server](#sql-server). -- †† Referential actions for MongoDB are available in Prisma ORM versions 3.7.0 and later. ### Special cases for referential actions @@ -270,7 +246,7 @@ The `NoAction` action is similar to `Restrict`, the difference between the two i - **MySQL**: `NoAction` behaves exactly the same as `Restrict`. See [the MySQL docs](https://dev.mysql.com/doc/refman/8.0/en/create-table-foreign-keys.html#foreign-key-referential-actions) for more information. - **SQLite**: When a related primary key is modified or deleted, no action is taken. See [the SQLite docs](https://www.sqlite.org/foreignkeys.html#fk_actions) for more information. - **SQL Server**: When a referenced record is deleted or modified, an error is raised. See [the SQL Server docs](https://learn.microsoft.com/en-us/sql/relational-databases/tables/graph-edge-constraints?view=sql-server-ver15#on-delete-referential-actions-on-edge-constraints) for more information. -- **MongoDB** (in preview from version 3.6.0): When a record is modified or deleted, nothing is done to any related records. +- **MongoDB**: When a record is modified or deleted, nothing is done to any related records. @@ -361,158 +337,3 @@ When the `username` of a `User` changes, its existing posts' `authorUsername` fi ### Database-specific requirements MongoDB and SQL Server have specific requirements for referential actions if you have [self-relations](/orm/prisma-schema/data-model/relations/referential-actions/special-rules-for-referential-actions#self-relation-sql-server-and-mongodb) or [cyclic relations](/orm/prisma-schema/data-model/relations/referential-actions/special-rules-for-referential-actions#cyclic-relation-between-three-tables-sql-server-and-mongodb) in your data model. SQL Server also has specific requirements if you have relations with [multiple cascade paths](/orm/prisma-schema/data-model/relations/referential-actions/special-rules-for-referential-actions#multiple-cascade-paths-between-two-models-sql-server-only). - -## Upgrade paths from versions 2.25.0 and earlier - -There are a couple of paths you can take when upgrading which will give different results depending on the desired outcome. - -If you currently use the migration workflow, you can run an introspection to check how the defaults are reflected in your schema. You can then manually update your database if you need to. - -You can also decide to skip checking the defaults and run a migration to update your database with the [new default values](#referential-action-defaults). - -The following assumes you have upgraded to 2.26.0 or newer and enabled the preview feature flag, or upgraded to 3.0.0 or newer: - -### Using Introspection - -If you [Introspect](/orm/prisma-schema/introspection) your database, the referential actions configured at the database level will be reflected in your Prisma Schema. If you have been using Prisma Migrate or `prisma db push` to manage the database schema, these are likely to be the [default values](#referential-action-defaults) from 2.25.0 and earlier. - -When you run an Introspection, Prisma ORM compares all the foreign keys in the database with the schema, if the SQL statements `ON DELETE` and `ON UPDATE` do **not** match the default values, they will be explicitly set in the schema file. - -After introspecting, you can review the non-default clauses in your schema. The most important clause to review is `onDelete`, which defaults to `Cascade` in 2.25.0 and earlier. - - - -If you are using either the [`delete()`](/orm/prisma-client/queries/crud#delete-a-single-record) or [`deleteMany()`](/orm/prisma-client/queries/crud#delete-all-records) methods, **[cascading deletes](#how-to-use-cascading-deletes) will now be performed** as the `referentialActions` preview feature **removed the safety net in Prisma Client that previously prevented cascading deletes at runtime**. Be sure to check your code and make any adjustments accordingly. - - - -Make sure you are happy with every case of `onDelete: Cascade` in your schema. If not, either: - -- Modify your Prisma schema and `db push` or `dev migrate` to change the database - -_or_ - -- Manually update the underlying database if you use an introspection-only workflow - -The following example would result in a cascading delete, if the `User` is deleted then all of their `Post`'s will be deleted too. - -#### A blog schema example - -```prisma showLineNumbers -model Post { - id Int @id @default(autoincrement()) - title String - //add-next-line - author User @relation(fields: [authorId], references: [id], onDelete: Cascade) - authorId Int -} - -model User { - id Int @id @default(autoincrement()) - posts Post[] -} -``` - -### Using Migration - -When running a [Migration](/orm/prisma-migrate) (or the [`prisma db push`](/orm/prisma-migrate/workflows/prototyping-your-schema) command) the [new defaults](#referential-action-defaults) will be applied to your database. - - - -Unlike when you run an Introspect for the first time, the new referential actions clause and property, will **not** automatically be added to your prisma schema by the Prisma VSCode extension. -You will have to manually add them if you wish to use anything other than the new defaults. - - - -Explicitly defining referential actions in your Prisma schema is optional. If you do not explicitly define a referential action for a relation, Prisma ORM uses the [new defaults](#referential-action-defaults). - -Note that referential actions can be added on a case by case basis. This means that you can add them to one single relation and leave the rest set to the defaults by not manually specifying anything. - -### Checking for errors - -**Before** upgrading to 2.26.0 and enabling the referential actions **preview feature**, Prisma ORM prevented the deletion of records while using `delete()` or `deleteMany()` to preserve referential integrity. A custom runtime error would be thrown by Prisma Client with the error code `P2014`. - -**After** upgrading and enabling the referential actions **preview feature**, Prisma ORM no longer performs runtime checks. You can instead specify a custom referential action to preserve the referential integrity between relations. - -When you use [`NoAction`](#noaction) or [`Restrict`](#restrict) to prevent the deletion of records, the error messages will be different post 2.26.0 compared to pre 2.26.0. This is because they are now triggered by the database and **not** Prisma Client. The new error code that can be expected is `P2003`. - -To make sure you catch these new errors you can adjust your code accordingly. - -#### Example of catching errors - -The following example uses the below blog schema with a one-to-many relationship between `Post` and `User` and sets a [`Restrict`](#restrict) referential actions on the `author` field. - -This means that if a user has a post, that user (and their posts) **cannot** be deleted. - -```prisma file=schema.prisma showLineNumbers -model Post { - id Int @id @default(autoincrement()) - title String - author User @relation(fields: [authorId], references: [id], onDelete: Restrict) - authorId String -} - -model User { - id Int @id @default(autoincrement()) - posts Post[] -} -``` - -Prior to upgrading and enabling the referential actions **preview feature**, the error code you would receive when trying to delete a user which has posts would be `P2014` and it's message: - -> "The change you are trying to make would violate the required relation '\{relation_name}' between the \{model_a_name\} and \{model_b_name\} models." - -```ts -import { PrismaClient } from '@prisma/client' - -const prisma = new PrismaClient() - -async function main() { - try { - await prisma.user.delete({ - where: { - id: 'some-long-id', - }, - }) - } catch (error) { - if (error instanceof Prisma.PrismaClientKnownRequestError) { - if (error.code === 'P2014') { - console.log(error.message) - } - } - } -} - -main() -``` - -To make sure you are checking for the correct errors in your code, modify your check to look for `P2003`, which will deliver the message: - -> "Foreign key constraint failed on the field: \{field_name\}" - -```ts highlight=14;delete|15;add -import { PrismaClient } from '@prisma/client' - -const prisma = new PrismaClient() - -async function main() { - try { - await prisma.user.delete({ - where: { - id: 'some-long-id' - } - }) - } catch (error) { - if (error instanceof Prisma.PrismaClientKnownRequestError) { - //delete-next-line - if (error.code === 'P2014') { - //add-next-line - if (error.code === 'P2003') { - console.log(error.message) - } - } - } -} - -main() -``` diff --git a/content/200-orm/100-prisma-schema/20-data-model/20-relations/420-relation-mode.mdx b/content/200-orm/100-prisma-schema/20-data-model/20-relations/420-relation-mode.mdx index a054e7d778..6ab732cc97 100644 --- a/content/200-orm/100-prisma-schema/20-data-model/20-relations/420-relation-mode.mdx +++ b/content/200-orm/100-prisma-schema/20-data-model/20-relations/420-relation-mode.mdx @@ -85,12 +85,6 @@ datasource db { } ``` - - -The ability to set the relation mode was introduced as part of the `referentialIntegrity` preview feature in Prisma ORM version 3.1.1, and is generally available in Prisma ORM versions 4.8.0 and later.

The `relationMode` field was renamed in Prisma ORM version 4.5.0, and was previously named `referentialIntegrity`. - - - For relational databases, the available options are: - `foreignKeys`: this handles relations in the database with foreign keys. This is the default option for all relational database connectors and is active if no `relationMode` is explicitly set in the `datasource` block. diff --git a/content/200-orm/100-prisma-schema/20-data-model/30-indexes.mdx b/content/200-orm/100-prisma-schema/20-data-model/30-indexes.mdx index 958ad1c732..20aa325ec4 100644 --- a/content/200-orm/100-prisma-schema/20-data-model/30-indexes.mdx +++ b/content/200-orm/100-prisma-schema/20-data-model/30-indexes.mdx @@ -5,19 +5,9 @@ hidePage: false tocDepth: 3 --- - +Prisma ORM allows configuration of database indexes, unique constraints and primary key constraints. -Prisma ORM allows configuration of database indexes, unique constraints and primary key constraints. This is in General Availability in versions `4.0.0` and later. You can enable this with the `extendedIndexes` Preview feature in versions `3.5.0` and later. - -Version `3.6.0` also introduces support for introspection and migration of full text indexes in MySQL and MongoDB through a new `@@fulltext` attribute, available through the `fullTextIndex` Preview feature. - - - -If you are upgrading from a version earlier than 4.0.0, these changes to index configuration and full text indexes might be **breaking changes** if you have a database that already uses these features. See [Upgrading from previous versions](#upgrading-from-previous-versions) for more information on how to upgrade. - - - - +Prisma ORM has also introduced support for introspection and migration of full text indexes in MySQL and MongoDB through a new `@@fulltext` attribute, available through the `fullTextIndex` Preview feature. ## Index configuration @@ -48,7 +38,7 @@ See the linked sections for details of which version each feature was first intr The `length` argument is specific to MySQL and allows you to define indexes and constraints on columns of `String` and `Byte` types. For these types, MySQL requires you to specify a maximum length for the subpart of the value to be indexed in cases where the full value would exceed MySQL's limits for index sizes. See [the MySQL documentation](https://dev.mysql.com/doc/refman/8.0/en/innodb-limits.html) for more details. -The `length` argument is available on the `@id`, `@@id`, `@unique`, `@@unique` and `@@index` attributes. It is generally available in versions 4.0.0 and later, and available as part of the `extendedIndexes` preview feature in versions 3.5.0 and later. +The `length` argument is available on the `@id`, `@@id`, `@unique`, `@@unique` and `@@index` attributes. As an example, the following data model declares an `id` field with a maximum length of 3000 characters: @@ -95,7 +85,7 @@ A similar syntax can be used for the `@@unique` and `@@index` attributes. The `sort` argument is available for all databases supported by Prisma ORM. It allows you to specify the order that the entries of the index or constraint are stored in the database. This can have an effect on whether the database is able to use an index for specific queries. -The `sort` argument is available for all databases on `@unique`, `@@unique` and `@@index`. Additionally, SQL Server also allows it on `@id` and `@@id`. It is generally available in versions 4.0.0 and later, and available as part of the `extendedIndexes` preview feature in versions 3.5.0 and later. +The `sort` argument is available for all databases on `@unique`, `@@unique` and `@@index`. Additionally, SQL Server also allows it on `@id` and `@@id`. As an example, the following table @@ -144,7 +134,7 @@ model Post { ### Configuring the access type of indexes with `type` (PostgreSQL) -The `type` argument is available for configuring the index type in PostgreSQL with the `@@index` attribute. The index access methods available are `Hash`, `Gist`, `Gin`, `SpGist` and `Brin`, as well as the default `BTree` index access method. The `type` argument is generally available in versions 4.0.0 and later. The `Hash` index access method is available as part of the `extendedIndexes` preview feature in versions 3.6.0 and later, and the `Gist`, `Gin`, `SpGist` and `Brin` index access methods are available in preview in versions 3.14.0 and later. +The `type` argument is available for configuring the index type in PostgreSQL with the `@@index` attribute. The index access methods available are `Hash`, `Gist`, `Gin`, `SpGist` and `Brin`, as well as the default `BTree` index access method. #### Hash @@ -414,7 +404,7 @@ Read more about built-in operator classes in the [official PostgreSQL documentat ### Configuring if indexes are clustered or non-clustered with `clustered` (SQL Server) -The `clustered` argument is available to configure (non)clustered indexes in SQL Server. It can be used on the `@id`, `@@id`, `@unique`, `@@unique` and `@@index` attributes. It is generally available in versions 4.0.0 and later, and available as part of the `extendedIndexes` preview feature in versions 3.13.0 and later. +The `clustered` argument is available to configure (non)clustered indexes in SQL Server. It can be used on the `@id`, `@@id`, `@unique`, `@@unique` and `@@index` attributes. As an example, the following model configures the `@id` to be non-clustered (instead of the clustered default): @@ -466,13 +456,13 @@ In each of the cases above unwanted changes to your database can be prevented by ## Full text indexes (MySQL and MongoDB) -The `fullTextIndex` preview feature provides support for introspection and migration of full text indexes in MySQL and MongoDB in version 3.6.0 and later. This can be configured using the `@@fulltext` attribute. Existing full text indexes in the database are added to your Prisma schema after introspecting with `db pull`, and new full text indexes added in the Prisma schema are created in the database when using Prisma Migrate. This also prevents validation errors in some database schemas that were not working before. +The `fullTextIndex` preview feature provides support for introspection and migration of full text indexes in MySQL and MongoDB. This can be configured using the `@@fulltext` attribute. Existing full text indexes in the database are added to your Prisma schema after introspecting with `db pull`, and new full text indexes added in the Prisma schema are created in the database when using Prisma Migrate. This also prevents validation errors in some database schemas that were not working before. - +:::warning For now we do not enable the full text search commands in Prisma Client for MongoDB; the progress can be followed in the [MongoDB](https://github.com/prisma/prisma/issues/9413) issue. - +::: ### Enabling the `fullTextIndex` preview feature @@ -520,13 +510,3 @@ model Post { @@fulltext([title(sort: Desc), content]) } ``` - -### Upgrading from previous versions - - - -This can be a **breaking change** when activating the functionality for certain, existing Prisma schemas for existing databases. After enabling the preview features required to use them, run `prisma db pull` to introspect the existing database to update your Prisma schema before using Prisma Migrate again. - - - -Earlier versions of Prisma ORM converted full text indexes using the `@@index` attribute rather than the `@@fulltext` attribute. After enabling the `fullTextIndex` preview feature, run `prisma db pull` to convert these indexes to `@@fulltext` before migrating again with Prisma Migrate. If you do not do this, the existing indexes will be dropped instead and normal indexes will be created in their place. diff --git a/content/200-orm/100-prisma-schema/20-data-model/40-views.mdx b/content/200-orm/100-prisma-schema/20-data-model/40-views.mdx index f78802b4ef..f4cfa54db3 100644 --- a/content/200-orm/100-prisma-schema/20-data-model/40-views.mdx +++ b/content/200-orm/100-prisma-schema/20-data-model/40-views.mdx @@ -294,7 +294,7 @@ When re-introspecting your database, any custom changes to your view definitions #### The `views` directory -Introspection of a database with one or more existing views will also create a new `views` directory within your `prisma` directory (starting with Prisma version 4.12.0). This directory will contain a subdirectory named after your database's schema which contains a `.sql` file for each view that was introspected in that schema. Each file will be named after an individual view and will contain the query the related view defines. +Introspection of a database with one or more existing views will also create a new `views` directory within your `prisma` directory. This directory will contain a subdirectory named after your database's schema which contains a `.sql` file for each view that was introspected in that schema. Each file will be named after an individual view and will contain the query the related view defines. For example, after introspecting a database with the default `public` schema using the model used above you will find a `prisma/views/public/UserInfo.sql` file was created with the following contents: diff --git a/content/200-orm/100-prisma-schema/20-data-model/50-database-mapping.mdx b/content/200-orm/100-prisma-schema/20-data-model/50-database-mapping.mdx index 7ace185004..fd21aa713b 100644 --- a/content/200-orm/100-prisma-schema/20-data-model/50-database-mapping.mdx +++ b/content/200-orm/100-prisma-schema/20-data-model/50-database-mapping.mdx @@ -80,16 +80,10 @@ enum Type { ## Constraint and index names -You can optionally use the `map` argument to explicitly define the **underlying constraint and index names** in the Prisma schema for the attributes [`@id`](/orm/reference/prisma-schema-reference#id), [`@@id`](/orm/reference/prisma-schema-reference#id-1), [`@unique`](/orm/reference/prisma-schema-reference#unique), [`@@unique`](/orm/reference/prisma-schema-reference#unique-1), [`@@index`](/orm/reference/prisma-schema-reference#index) and [`@relation`](/orm/reference/prisma-schema-reference#relation). (This is available in Prisma ORM version [2.29.0](https://github.com/prisma/prisma/releases/tag/2.29.0) and later.) +You can optionally use the `map` argument to explicitly define the **underlying constraint and index names** in the Prisma schema for the attributes [`@id`](/orm/reference/prisma-schema-reference#id), [`@@id`](/orm/reference/prisma-schema-reference#id-1), [`@unique`](/orm/reference/prisma-schema-reference#unique), [`@@unique`](/orm/reference/prisma-schema-reference#unique-1), [`@@index`](/orm/reference/prisma-schema-reference#index) and [`@relation`](/orm/reference/prisma-schema-reference#relation). When introspecting a database, the `map` argument will _only_ be rendered in the schema if the name _differs_ from Prisma ORM's [default constraint naming convention for indexes and constraints](#prisma-orms-default-naming-conventions-for-indexes-and-constraints). - - -If you use Prisma Migrate in a version earlier than 2.29.0 and want to maintain your existing constraint and index names after upgrading to a newer version, **do not** immediately run `prisma migrate` or `prisma db push`. This will **change any underlying constraint name that does not follow Prisma ORM's convention**. Follow the [upgrade path that allows you to maintain existing constraint and index names](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-3/named-constraints#option-1-i-want-to-maintain-my-existing-constraint-and-index-names). - - - ### Use cases for named constraints Some use cases for explicitly named constraints include: diff --git a/content/200-orm/100-prisma-schema/20-data-model/70-unsupported-database-features.mdx b/content/200-orm/100-prisma-schema/20-data-model/70-unsupported-database-features.mdx index a620d29f68..5c3be56c34 100644 --- a/content/200-orm/100-prisma-schema/20-data-model/70-unsupported-database-features.mdx +++ b/content/200-orm/100-prisma-schema/20-data-model/70-unsupported-database-features.mdx @@ -53,24 +53,7 @@ In PostgreSQL, some native database functions are part of an extension. For exam To use a PostgreSQL extension, you must first install it on the file system of your database server. -In Prisma ORM versions 4.5.0 and later, you can then activate the extension by declaring it in your Prisma schema with the [`postgresqlExtensions` preview feature](/orm/prisma-schema/postgresql-extensions): - -```prisma file=schema.prisma highlight=3,9;add showLineNumbers -generator client { - provider = "prisma-client-js" - //add-next-line - previewFeatures = ["postgresqlExtensions"] -} - -datasource db { - provider = "postgresql" - url = env("DATABASE_URL") - //add-next-line - extensions = [pgcrypto] -} -``` - -In earlier versions of Prisma ORM, you must instead run a SQL command to activate the extension: +You must instead run a SQL command to activate the extension: ```sql CREATE EXTENSION IF NOT EXISTS pgcrypto; diff --git a/content/200-orm/100-prisma-schema/50-introspection.mdx b/content/200-orm/100-prisma-schema/50-introspection.mdx index 0e76630d80..29fd04cadc 100644 --- a/content/200-orm/100-prisma-schema/50-introspection.mdx +++ b/content/200-orm/100-prisma-schema/50-introspection.mdx @@ -315,7 +315,7 @@ Note that you can rename the [Prisma-ORM level](/orm/prisma-schema/data-model/re ## Introspection with an existing schema -Running `prisma db pull` for relational databases with an existing Prisma Schema merges manual changes made to the schema, with changes made in the database. (This functionality has been added for the first time with version 2.6.0.) For MongoDB, Introspection for now is meant to be done only once for the initial data model. Running it repeatedly will lead to loss of custom changes, as the ones listed below. +Running `prisma db pull` for relational databases with an existing Prisma Schema merges manual changes made to the schema, with changes made in the database. For MongoDB, Introspection is meant to be done only once for the initial data model. Running it repeatedly will lead to loss of custom changes, as the ones listed below. Introspection for relational databases maintains the following manual changes: @@ -365,19 +365,15 @@ The Prisma Schema Language (PSL) can express a majority of the database features For these features, the Prisma CLI will surface detect usage of the feature in your database and return a warning. The Prisma CLI will also add a comment in the models and fields the features are in use in the Prisma schema. The warnings will also contain a workaround suggestion. The `prisma db pull` command will surface the following unsupported features: - -- From version [4.13.0](https://github.com/prisma/prisma/releases/tag/4.13.0): - [Partitioned tables](https://github.com/prisma/prisma/issues/1708) - [PostgreSQL Row Level Security](https://github.com/prisma/prisma/issues/12735) - [Index sort order, `NULLS FIRST` / `NULLS LAST`](https://github.com/prisma/prisma/issues/15466) - [CockroachDB row-level TTL](https://github.com/prisma/prisma/issues/13982) - [Comments](https://github.com/prisma/prisma/issues/8703) - [PostgreSQL deferred constraints](https://github.com/prisma/prisma/issues/8807) -- From version [4.14.0](https://github.com/prisma/prisma/releases/tag/4.14.0): - [Check Constraints](https://github.com/prisma/prisma/issues/3388) (MySQL + PostgreSQL) - [Exclusion Constraints](https://github.com/prisma/prisma/issues/17514) - [MongoDB $jsonSchema](https://github.com/prisma/prisma/issues/8135) -- From version [4.16.0](https://github.com/prisma/prisma/releases/tag/4.16.0): - [Expression indexes](https://github.com/prisma/prisma/issues/2504) You can find the list of features we intend to support on [GitHub (labeled with `topic:database-functionality`)](https://github.com/prisma/prisma/issues?q=is%3Aopen+label%3A%22topic%3A+database-functionality%22+label%3Ateam%2Fschema+sort%3Aupdated-desc+). diff --git a/content/200-orm/100-prisma-schema/80-postgresql-extensions.mdx b/content/200-orm/100-prisma-schema/80-postgresql-extensions.mdx index 56fb3cf0b1..c6cedb0099 100644 --- a/content/200-orm/100-prisma-schema/80-postgresql-extensions.mdx +++ b/content/200-orm/100-prisma-schema/80-postgresql-extensions.mdx @@ -8,12 +8,6 @@ tocDepth: 3 This page introduces PostgreSQL extensions and describes how to represent extensions in your Prisma schema, how to introspect existing extensions in your database, and how to apply changes to your extensions to your database with Prisma Migrate. - - -Support for declaring PostgreSQL extensions in your schema is available in preview for the PostgreSQL connector only in Prisma versions 4.5.0 and later. - - - ## What are PostgreSQL extensions? PostgreSQL allows you to extend your database functionality by installing and activating packages known as _extensions_. For example, the `citext` extension adds a case-insensitive string data type. Some extensions, such as `citext`, are supplied directly by PostgreSQL, while other extensions are developed externally. For more information on extensions, see [the PostgreSQL documentation](https://www.postgresql.org/docs/current/sql-createextension.html). diff --git a/content/200-orm/200-prisma-client/000-setup-and-configuration/050-databases-connections/100-connection-management.mdx b/content/200-orm/200-prisma-client/000-setup-and-configuration/050-databases-connections/100-connection-management.mdx index 023aba982d..3ac1f3b1b0 100644 --- a/content/200-orm/200-prisma-client/000-setup-and-configuration/050-databases-connections/100-connection-management.mdx +++ b/content/200-orm/200-prisma-client/000-setup-and-configuration/050-databases-connections/100-connection-management.mdx @@ -85,11 +85,11 @@ If the above script runs multiple times in the context of a long-running applica ## Exit hooks - +:::info -From Prisma ORM 5.0.0, the `beforeExit` hook only applies to the [binary Query Engine](/orm/more/under-the-hood/engines#configuring-the-query-engine). +The `beforeExit` hook only applies to the [binary Query Engine](/orm/more/under-the-hood/engines#configuring-the-query-engine). - +::: The `beforeExit` hook runs when Prisma ORM is triggered externally (e.g. via a `SIGINT` signal) to shut down, and allows you to run code _before_ Prisma Client disconnects - for example, to issue queries as part of a graceful shutdown of a service: diff --git a/content/200-orm/200-prisma-client/100-queries/030-crud.mdx b/content/200-orm/200-prisma-client/100-queries/030-crud.mdx index 09dba52754..2d6750a321 100644 --- a/content/200-orm/200-prisma-client/100-queries/030-crud.mdx +++ b/content/200-orm/200-prisma-client/100-queries/030-crud.mdx @@ -228,9 +228,7 @@ For more information about working with generated types, see: [Generated types]( ### Create multiple records -Prisma Client supports bulk inserts as a GA feature in [2.20.0](https://github.com/prisma/prisma/releases/2.20.0) and later. - -The following [`createMany()`](/orm/reference/prisma-client-reference#createmany) query creates multiple users and skips any duplicates (`email` must be unique): +Prisma Client supports bulk inserts. The following [`createMany()`](/orm/reference/prisma-client-reference#createmany) query creates multiple users and skips any duplicates (`email` must be unique): @@ -790,7 +788,7 @@ const upsertUser = await prisma.user.upsert({ -From version 4.6.0, Prisma Client carries out upserts with database native SQL commands where possible. [Learn more](/orm/reference/prisma-client-reference#database-upserts). +Prisma Client carries out upserts with database native SQL commands where possible. [Learn more](/orm/reference/prisma-client-reference#database-upserts). @@ -867,12 +865,6 @@ Be aware that this query will fail if the user has any related records (such as ### Cascading deletes (deleting related records) - - -In [2.26.0](https://github.com/prisma/prisma/releases/tag/2.26.0) and later it is possible to do cascading deletes using the **preview feature** [referential actions](/orm/prisma-schema/data-model/relations/referential-actions). - - - The following query uses [`delete()`](/orm/reference/prisma-client-reference#delete) to delete a single `User` record: ```ts diff --git a/content/200-orm/200-prisma-client/100-queries/035-select-fields.mdx b/content/200-orm/200-prisma-client/100-queries/035-select-fields.mdx index c6b290300a..cb721d7001 100644 --- a/content/200-orm/200-prisma-client/100-queries/035-select-fields.mdx +++ b/content/200-orm/200-prisma-client/100-queries/035-select-fields.mdx @@ -332,4 +332,4 @@ Notice how the returned object does _not_ contain the `password` field. ## Relation count -In [3.0.1](https://github.com/prisma/prisma/releases/3.0.1) and later, you can `include` or `select` a [count of relations](/orm/prisma-client/queries/aggregation-grouping-summarizing#count-relations) alongside fields. For example, a user's post count. +You can `include` or `select` a [count of relations](/orm/prisma-client/queries/aggregation-grouping-summarizing#count-relations) alongside fields. For example, a user's post count. diff --git a/content/200-orm/200-prisma-client/100-queries/037-relation-queries.mdx b/content/200-orm/200-prisma-client/100-queries/037-relation-queries.mdx index b7a14af3ec..d02ae7ca86 100644 --- a/content/200-orm/200-prisma-client/100-queries/037-relation-queries.mdx +++ b/content/200-orm/200-prisma-client/100-queries/037-relation-queries.mdx @@ -381,7 +381,7 @@ const user = await prisma.user.findFirst({ ## Relation count -In [3.0.1](https://github.com/prisma/prisma/releases/3.0.1) and later, you can [`include` or `select` a count of relations](/orm/prisma-client/queries/aggregation-grouping-summarizing#count-relations) alongside fields - for example, a user's post count. +You can [`include` or `select` a count of relations](/orm/prisma-client/queries/aggregation-grouping-summarizing#count-relations) alongside fields - for example, a user's post count. diff --git a/content/200-orm/200-prisma-client/100-queries/050-filtering-and-sorting.mdx b/content/200-orm/200-prisma-client/100-queries/050-filtering-and-sorting.mdx index 813f6605b6..32c6e70ad7 100644 --- a/content/200-orm/200-prisma-client/100-queries/050-filtering-and-sorting.mdx +++ b/content/200-orm/200-prisma-client/100-queries/050-filtering-and-sorting.mdx @@ -367,7 +367,7 @@ const posts = await prisma.post.findMany({ ### Sort by relation aggregate value -In [2.19.0](https://github.com/prisma/prisma/releases/2.19.0) and later, you can sort by the **count of related records**. +You can sort by the **count of related records**. For example, the following query sorts users by the number of related posts: @@ -386,7 +386,7 @@ const getActiveUsers = await prisma.user.findMany({ ### Sort by relevance (PostgreSQL and MySQL) -In [3.5.0+](https://github.com/prisma/prisma/releases/3.5.0) for PostgreSQL and [3.8.0+](https://github.com/prisma/prisma/releases/3.8.0) for MySQL, you can sort records by relevance to the query using the `_relevance` keyword. This uses the relevance ranking functions from full text search features. +You can sort records by relevance to the query using the `_relevance` keyword. This uses the relevance ranking functions from full text search features. This feature is further explain in [the PostgreSQL documentation](https://www.postgresql.org/docs/12/textsearch-controls.html) and [the MySQL documentation](https://dev.mysql.com/doc/refman/8.0/en/fulltext-search.html). @@ -431,7 +431,6 @@ Prior to Prisma ORM 5.16.0, enabling the `fullTextSearch` preview feature would Notes: -- This feature is generally available in version `4.16.0` and later. To use this feature in versions [`4.1.0`](https://github.com/prisma/prisma/releases/tag/4.1.0) to [`4.15.0`](https://github.com/prisma/prisma/releases/tag/4.15.0) the [Preview feature](/orm/reference/preview-features/client-preview-features#enabling-a-prisma-client-preview-feature) `orderByNulls` will need to be enabled. - This feature is not available for MongoDB. - You can only sort by nulls on optional [scalar](/orm/prisma-schema/data-model/models#scalar-fields) fields. If you try to sort by nulls on a required or [relation](/orm/prisma-schema/data-model/models#relation-fields) field, Prisma Client throws a [P2009 error](/orm/reference/error-reference#p2009). diff --git a/content/200-orm/200-prisma-client/100-queries/056-aggregation-grouping-summarizing.mdx b/content/200-orm/200-prisma-client/100-queries/056-aggregation-grouping-summarizing.mdx index c0695ef1ab..645346657f 100644 --- a/content/200-orm/200-prisma-client/100-queries/056-aggregation-grouping-summarizing.mdx +++ b/content/200-orm/200-prisma-client/100-queries/056-aggregation-grouping-summarizing.mdx @@ -53,7 +53,7 @@ console.log('Average age:' + aggregations._avg.age) ### Aggregate values are nullable -In [2.21.0](https://github.com/prisma/prisma/releases/tag/2.21.0) and later, aggregations on **nullable fields** can return a `number` or `null`. This excludes `count`, which always returns 0 if no records are found. +Aggregations on **nullable fields** can return a `number` or `null`. This excludes `count`, which always returns 0 if no records are found. Consider the following query, where `age` is nullable in the schema: @@ -97,7 +97,7 @@ This allows you to differentiate between the true aggregate value (which could b ## Group by -Prisma Client's [`groupBy()`](/orm/reference/prisma-client-reference#groupby) allows you to **group records** by one or more field values - such as `country`, or `country` and `city` and **perform aggregations** on each group, such as finding the average age of people living in a particular city. `groupBy()` is a GA in [2.20.0](https://github.com/prisma/prisma/releases/2.20.0) and later. +Prisma Client's [`groupBy()`](/orm/reference/prisma-client-reference#groupby) allows you to **group records** by one or more field values - such as `country`, or `country` and `city` and **perform aggregations** on each group, such as finding the average age of people living in a particular city. The following video uses `groupBy()` to summarize total COVID-19 cases by continent: @@ -265,13 +265,13 @@ const groupUsers = await prisma.user.groupBy({ The following constraints apply when you combine `groupBy()` and `orderBy`: -- You can `orderBy` fields that are present in `by` -- You can `orderBy` aggregate (Preview in 2.21.0 and later) -- If you use `skip` and/or `take` with `groupBy()`, you must also include `orderBy` in the query +- You can `orderBy` fields that are present in `by`. +- You can `orderBy` aggregates. +- If you use `skip` and/or `take` with `groupBy()`, you must also include `orderBy` in the query. #### Order by aggregate group -You can **order by aggregate group**. Prisma ORM added support for using `orderBy` with aggregated groups in relational databases in version [2.21.0](https://github.com/prisma/prisma/releases/2.21.0) and support for MongoDB in [3.4.0](https://github.com/prisma/prisma/releases/3.4.0). +You can **order by aggregate group**. The following example sorts each `city` group by the number of users in that group (largest group first): @@ -350,12 +350,6 @@ const userCount = await prisma.user.count() ### Count relations - - -This feature is generally available in version [3.0.1](https://github.com/prisma/prisma/releases/3.0.1) and later. To use this feature in versions before 3.0.1 the [Preview feature](/orm/reference/preview-features/client-preview-features#enabling-a-prisma-client-preview-feature) `selectRelationCount` will need to be enabled. - - - To return a count of relations (for example, a user's post count), use the `_count` parameter with a nested `select` as shown: @@ -390,7 +384,7 @@ The `_count` parameter: - Can be used inside a top-level `include` _or_ `select` - Can be used with any query that returns records (including `delete`, `update`, and `findFirst`) - Can return [multiple relation counts](#return-multiple-relation-counts) -- Can [filter relation counts](#filter-the-relation-count) (from version 4.3.0) +- Can [filter relation counts](#filter-the-relation-count) #### Return a relations count with `include` @@ -491,12 +485,6 @@ const usersWithCount = await prisma.user.findMany({ #### Filter the relation count - - -This feature is generally available in version `4.16.0` and later. To use this feature in versions [`4.3.0`](https://github.com/prisma/prisma/releases/tag/4.3.0) to [`4.15.0`](https://github.com/prisma/prisma/releases/tag/4.15.0) the [Preview feature](/orm/reference/preview-features/client-preview-features#enabling-a-prisma-client-preview-feature) `filteredRelationCount` will need to be enabled. - - - Use `where` to filter the fields returned by the `_count` output type. You can do this on [scalar fields](/orm/prisma-schema/data-model/models#scalar-fields), [relation fields](/orm/prisma-schema/data-model/models#relation-fields) and fields of a [composite type](/orm/prisma-schema/data-model/models#defining-composite-types). For example, the following query returns all user posts with the title "Hello!": @@ -534,7 +522,7 @@ await prisma.user.findMany({ ### Count non-`null` field values -In [2.15.0](https://github.com/prisma/prisma/releases/2.15.0) and later, you can count all records as well as all instances of non-`null` field values. The following query returns a count of: +You can count all records as well as all instances of non-`null` field values. The following query returns a count of: - All `User` records (`_all`) - All non-`null` `name` values (not distinct values, just values that are not `null`) diff --git a/content/200-orm/200-prisma-client/100-queries/058-transactions.mdx b/content/200-orm/200-prisma-client/100-queries/058-transactions.mdx index 63b93505b5..f9009ce132 100644 --- a/content/200-orm/200-prisma-client/100-queries/058-transactions.mdx +++ b/content/200-orm/200-prisma-client/100-queries/058-transactions.mdx @@ -13,12 +13,6 @@ A database transaction refers to a sequence of read/write operations that are _g ## Transactions overview - - -Before Prisma ORM version 4.4.0, you could not set isolation levels on transactions. The isolation level in your database configuration always applied. - - - Developers take advantage of the safety guarantees provided by the database by wrapping the operations in a transaction. These guarantees are often summarized using the ACID acronym: - **Atomic**: Ensures that either _all_ or _none_ operations of the transactions succeed. The transaction is either _committed_ successfully or _aborted_ and _rolled back_. @@ -175,7 +169,7 @@ Instead of immediately awaiting the result of each operation when it's performed > > Refer to the section about the [transactions API](#transaction-api) for more examples. -From version 4.4.0, the sequential operations transaction API has a second parameter. You can use the following optional configuration option in this parameter: +You can use the following optional configuration option in this parameter: - `isolationLevel`: Sets the [transaction isolation level](#transaction-isolation-level). By default this is set to the value currently configured in your database. @@ -199,14 +193,6 @@ await prisma.$transaction( Sometimes you need more control over what queries execute within a transaction. Interactive transactions are meant to provide you with an escape hatch. - - -Interactive transactions have been generally available from version 4.7.0. - -If you use interactive transactions in preview from version 2.29.0 to 4.6.1 (inclusive), you need to add the `interactiveTransactions` preview feature to the generator block of your Prisma schema. - - - To use interactive transactions, you can pass an async function into [`$transaction`](#transaction-api). The first argument passed into this async function is an instance of Prisma Client. Below, we will call this instance `tx`. Any Prisma Client call invoked on this `tx` instance is encapsulated into the transaction. @@ -344,14 +330,6 @@ This feature is not available on MongoDB, because MongoDB does not support isola You can set the transaction [isolation level](https://www.prisma.io/dataguide/intro/database-glossary#isolation-levels) for transactions. - - -This is available in the following Prisma ORM versions for interactive transactions from version 4.2.0, for sequential operations from version 4.4.0. - -In versions before 4.2.0 (for interactive transactions), or 4.4.0 (for sequential operations), you cannot configure the transaction isolation level at a Prisma ORM level. Prisma ORM does not explicitly set the isolation level, so the [isolation level configured in your database](#database-specific-information-on-isolation-levels) is used. - - - #### Set the isolation level To set the transaction isolation level, use the `isolationLevel` option in the second parameter of the API. @@ -1170,13 +1148,11 @@ If a ❌ conflict occurs (someone else has changed the record since you read it) This section describes how to build your own optimistic concurrency control. See also: Plans for [application-level optimistic concurrency control on GitHub](https://github.com/prisma/prisma/issues/4988) - - -- If you use version 4.4.0 or earlier, you cannot use optimistic concurrency control on `update` operations, because you cannot filter on non-unique fields. The `version` field you need to use with optimistic concurrency control is a non-unique field. +:::info -- Since version 5.0.0 you are able to [filter on non-unique fields in `update` operations](/orm/reference/prisma-client-reference#filter-on-non-unique-fields-with-userwhereuniqueinput) so that optimistic concurrency control is being used. The feature was also available via the Preview flag `extendedWhereUnique` from versions 4.5.0 to 4.16.2. +- Since Prisma ORM version 5.0.0 you are able to [filter on non-unique fields in `update` operations](/orm/reference/prisma-client-reference#filter-on-non-unique-fields-with-userwhereuniqueinput) so that optimistic concurrency control is being used. - +::: #### When to use optimistic concurrency control diff --git a/content/200-orm/200-prisma-client/100-queries/060-full-text-search.mdx b/content/200-orm/200-prisma-client/100-queries/060-full-text-search.mdx index ef473c95b8..e2f7ba9a06 100644 --- a/content/200-orm/200-prisma-client/100-queries/060-full-text-search.mdx +++ b/content/200-orm/200-prisma-client/100-queries/060-full-text-search.mdx @@ -5,7 +5,7 @@ metaDescription: 'This page explains how to search for text within a field.' sidebar_class_name: preview-badge --- -Prisma Client supports full-text search for **PostgreSQL** databases in versions 2.30.0 and later, and **MySQL** databases in versions 3.8.0 and later. With full-text search (FTS) enabled, you can add search functionality to your application by searching for text within a database column. +Prisma Client supports full-text search for **PostgreSQL** and **MySQL** database. With full-text search (FTS) enabled, you can add search functionality to your application by searching for text within a database column. :::info diff --git a/content/200-orm/200-prisma-client/100-queries/062-computed-fields.mdx b/content/200-orm/200-prisma-client/100-queries/062-computed-fields.mdx index c1e69e2dcd..31b8115e31 100644 --- a/content/200-orm/200-prisma-client/100-queries/062-computed-fields.mdx +++ b/content/200-orm/200-prisma-client/100-queries/062-computed-fields.mdx @@ -99,80 +99,6 @@ model Post { The computed fields are type-safe and can return anything from a concatenated value to complex objects or functions that can act as an instance method for your models. -
- -Instructions prior to Prisma ORM 4.16.0 - -:::warning - -With Prisma Client extensions Generally Available as of Prisma ORM version 4.16.0, the following steps are not recommended. Please use [a client extension](#using-a-prisma-client-extension) to accomplish this. - -::: - -Prisma Client does not yet natively support computed fields, but, you can define a function that accepts a generic type as an input then extend that generic to ensure it conforms to a specific structure. Finally, you can return that generic with additional computed fields. Let's see how that might look: - - - - - -```tsx -// Define a type that needs a first and last name -type FirstLastName = { - firstName: string - lastName: string -} - -// Extend the T generic with the fullName attribute -type WithFullName = T & { - fullName: string -} - -// Take objects that satisfy FirstLastName and computes a full name -function computeFullName( - user: User -): WithFullName { - return { - ...user, - fullName: user.firstName + ' ' + user.lastName, - } -} - -async function main() { - const user = await prisma.user.findUnique({ where: 1 }) - const userWithFullName = computeFullName(user) -} -``` - - - - - -```js -function computeFullName(user) { - return { - ...user, - fullName: user.firstName + ' ' + user.lastName, - } -} - -async function main() { - const user = await prisma.user.findUnique({ where: 1 }) - const userWithFullName = computeFullName(user) -} -``` - - - - - -In the TypeScript example above, a `User` generic has been defined that extends the `FirstLastName` type. This means that whatever you pass into `computeFullName` must contain `firstName` and `lastName` keys. - -A `WithFullName` return type has also been defined, which takes whatever `User` is and tacks on a `fullName` string attribute. - -With this function, any object that contains `firstName` and `lastName` keys can compute a `fullName`. Pretty neat, right? - -
- ### Going further - Learn how you can use [Prisma Client extensions](/orm/prisma-client/client-extensions) to add a computed field to your schema — [example](https://github.com/prisma/prisma-client-extensions/tree/main/computed-fields). diff --git a/content/200-orm/200-prisma-client/150-using-raw-sql/200-raw-queries.mdx b/content/200-orm/200-prisma-client/150-using-raw-sql/200-raw-queries.mdx index e0ff6126d1..8f7506bffc 100644 --- a/content/200-orm/200-prisma-client/150-using-raw-sql/200-raw-queries.mdx +++ b/content/200-orm/200-prisma-client/150-using-raw-sql/200-raw-queries.mdx @@ -17,7 +17,7 @@ Prisma Client supports the option of sending raw queries to your database. You m - you want to run a heavily optimized query - you require a feature that Prisma Client does not yet support (please [consider raising an issue](https://github.com/prisma/prisma/issues/new/choose)) -Raw queries are available for all relational databases Prisma ORM supports. In addition, from version `3.9.0` raw queries are supported in MongoDB. For more details, see the relevant sections: +Raw queries are available for all databases Prisma ORM supports. - [Raw queries with relational databases](#raw-queries-with-relational-databases) - [Raw queries with MongoDB](#raw-queries-with-mongodb) @@ -333,15 +333,6 @@ $executeRawUnsafe(query: string, ...values: any[]): PrismaPromise - -**Feature availability:** - -- In v3.14.x and v3.15.x, raw query type mapping was available with the preview feature `improvedQueryRaw`. We made raw query type mapping [Generally Available](/orm/more/releases#generally-available-ga) in version 4.0.0, so you do not need to use `improvedQueryRaw` in version 4.0.0 or later. -- Before version 4.0.0, raw query type mapping was not available for SQLite. - - - As an example, take a raw query that selects columns with `BigInt`, `Bytes`, `Decimal` and `Date` types from a table: @@ -412,26 +403,9 @@ The solution in this case is to explicitly cast `42` to the `text` type: await prisma.$queryRaw`SELECT LENGTH(${42}::text);`; ``` -:::info - -**Feature availability:** This funtionality is [Generally Available](/orm/more/releases#generally-available-ga) since version 4.0.0. In v3.14.x and v3.15.x, it was available with the preview feature `improvedQueryRaw`. - -For the example above before version 4.0.0, Prisma ORM silently coerces `42` to `text` and does not require the explicit cast. - -On the other hand the following raw query now works correctly, returning an integer result, and failed before: - -```ts -await prisma.$queryRaw`SELECT ${1.5}::int as int`; - -// Now: [{ int: 2 }] -// Before: db error: ERROR: incorrect binary data format in bind parameter 1 -``` - -::: - ### Transactions -In 2.10.0 and later, you can use `.$executeRaw()` and `.$queryRaw()` inside a [transaction](/orm/prisma-client/queries/transactions). +You can use `.$executeRaw()` and `.$queryRaw()` inside a [transaction](/orm/prisma-client/queries/transactions). ### Using variables @@ -743,7 +717,7 @@ const result = await prisma.$queryRawUnsafe( ## Raw queries with MongoDB -For MongoDB in versions `3.9.0` and later, Prisma Client exposes three methods that allow you to send raw queries. You can use: +For MongoDB, Prisma Client exposes three methods that allow you to send raw queries. You can use: - `$runCommandRaw` to run a command against the database - `.findRaw` to find zero or more documents that match the filter. diff --git a/content/200-orm/200-prisma-client/150-using-raw-sql/index.mdx b/content/200-orm/200-prisma-client/150-using-raw-sql/index.mdx index b598c28e4c..1b102dccce 100644 --- a/content/200-orm/200-prisma-client/150-using-raw-sql/index.mdx +++ b/content/200-orm/200-prisma-client/150-using-raw-sql/index.mdx @@ -66,6 +66,6 @@ For MongoDB, Prisma ORM supports three methods to execute raw queries: These methods allow you to execute raw MongoDB commands and queries, providing flexibility when you need to use MongoDB-specific features or optimizations. -`$runCommandRaw` is used to execute database commands, `.findRaw` is used to find documents that match a filter, and `.aggregateRaw` is used for aggregation operations. All three methods are available from Prisma version 3.9.0 and later. +`$runCommandRaw` is used to execute database commands, `.findRaw` is used to find documents that match a filter, and `.aggregateRaw` is used for aggregation operations. Similar to raw queries in relational databases, these methods are not type-safe and require manual handling of the query results. \ No newline at end of file diff --git a/content/200-orm/200-prisma-client/200-special-fields-and-types/057-composite-types.mdx b/content/200-orm/200-prisma-client/200-special-fields-and-types/057-composite-types.mdx index fb67569058..47fee42e38 100644 --- a/content/200-orm/200-prisma-client/200-special-fields-and-types/057-composite-types.mdx +++ b/content/200-orm/200-prisma-client/200-special-fields-and-types/057-composite-types.mdx @@ -15,8 +15,6 @@ Composite types are only available with MongoDB. [Composite types](/orm/prisma-schema/data-model/models#defining-composite-types), known as [embedded documents](https://www.mongodb.com/docs/manual/data-modeling/#embedded-data) in MongoDB, allow you to embed records within other records. -We made composite types [Generally Available](/orm/more/releases#generally-available-ga) in v3.12.0. They were previously available in [Preview](/orm/reference/preview-features) from v3.10.0. - This page explains how to: - [find](#finding-records-that-contain-composite-types-with-find-and-findmany) records that contain composite types using `findFirst` and `findMany` @@ -97,7 +95,7 @@ There are currently some limitations when using composite types in Prisma Client ## Default values for required fields on composite types -From version 4.0.0, if you carry out a database read on a composite type when all of the following conditions are true, then Prisma Client inserts the default value into the result. +If you carry out a database read on a composite type when all of the following conditions are true, then Prisma Client inserts the default value into the result. Conditions: @@ -131,15 +129,6 @@ console.dir(await prisma.product.findMany({}), { depth: Infinity }) The `bitDepth` field has no content because you have only just added this field, so the query returns the default value of `8`. -** Earlier versions ** - -Before version 4.0.0, Prisma ORM threw a P2032 error as follows: - -``` -Error converting field "bitDepth" of expected non-nullable -type "int", found incompatible value of "null". -``` - ## Finding records that contain composite types with `find` and `findMany` Records can be filtered by a composite type within the `where` operation. diff --git a/content/200-orm/200-prisma-client/200-special-fields-and-types/100-working-with-json-fields.mdx b/content/200-orm/200-prisma-client/200-special-fields-and-types/100-working-with-json-fields.mdx index c8591a7f59..faed63123f 100644 --- a/content/200-orm/200-prisma-client/200-special-fields-and-types/100-working-with-json-fields.mdx +++ b/content/200-orm/200-prisma-client/200-special-fields-and-types/100-working-with-json-fields.mdx @@ -144,21 +144,11 @@ const getUsers = await prisma.user.findMany({ You can also filter rows by the data inside a `Json` field. We call this **advanced `Json` filtering**. This functionality is supported by [PostgreSQL](/orm/overview/databases/postgresql) and [MySQL](/orm/overview/databases/mysql) only with [different syntaxes for the `path` option](#path-syntax-depending-on-database). - +:::warning PostgreSQL does not support [filtering on object key values in arrays](#filtering-on-object-key-value-inside-array). - - - - -The availability of advanced `Json` filtering depends on your Prisma version: - -- v4.0.0 or later: advanced `Json` filtering is [generally available](/orm/more/releases#generally-available-ga). -- From v2.23.0, but before v4.0.0: advanced `Json` filtering is a [preview feature](/orm/reference/preview-features/client-preview-features). Add `previewFeatures = ["filterJson"]` to your schema. [Learn more](/orm/reference/preview-features/client-preview-features#enabling-a-prisma-client-preview-feature). -- Before v2.23.0: you can [filter on the exact `Json` field value](#filter-on-exact-field-value), but you cannot use the other features described in this section. - - +::: ### `path` syntax depending on database @@ -890,12 +880,6 @@ To differentiate between these possibilities, we've introduced three _null enums -From v4.0.0, `JsonNull`, `DbNull`, and `AnyNull` are objects. Before v4.0.0, they were strings. - - - - - - When filtering using any of the _null enums_ you can not use a shorthand and leave the `equals` operator off. - These _null enums_ do not apply to MongoDB because there the difference between a JSON `null` and a database `NULL` does not exist. - The _null enums_ do not apply to the `array_contains` operator in all databases because there can only be a JSON `null` within a JSON array. Since there cannot be a database `NULL` within a JSON array, `{ array_contains: null }` is not ambiguous. diff --git a/content/200-orm/200-prisma-client/200-special-fields-and-types/200-working-with-scalar-lists-arrays.mdx b/content/200-orm/200-prisma-client/200-special-fields-and-types/200-working-with-scalar-lists-arrays.mdx index 6682d03c9d..978aa45116 100644 --- a/content/200-orm/200-prisma-client/200-special-fields-and-types/200-working-with-scalar-lists-arrays.mdx +++ b/content/200-orm/200-prisma-client/200-special-fields-and-types/200-working-with-scalar-lists-arrays.mdx @@ -59,13 +59,6 @@ const createdUser = await prisma.user.create({ ## Unsetting the value of a scalar list - - -This method is available on MongoDB only in versions -[3.11.1](https://github.com/prisma/prisma/releases/tag/3.11.1) and later. - - - The following example demonstrates how to [`unset`](/orm/reference/prisma-client-reference#unset) the value of a scalar list (`coinflips`): ```ts @@ -83,15 +76,11 @@ Unlike `set: null`, `unset` removes the list entirely. ## Adding items to a scalar list - - -Available for: +:::warning -- PostgreSQL in versions [2.15.0](https://github.com/prisma/prisma/releases/tag/2.15.0) and later -- CockroachDB in versions [3.9.0](https://github.com/prisma/prisma/releases/tag/3.9.0) and later -- MongoDB in versions [3.11.0](https://github.com/prisma/prisma/releases/tag/3.11.0) and later +Available for: PostgreSQL, CockroachDB, and MongoDB. - +::: Use the [`push`](/orm/reference/prisma-client-reference#push) method to add a single value to a scalar list: @@ -139,11 +128,7 @@ if (user) { -Available for: - -- PostgreSQL in versions [2.15.0](https://github.com/prisma/prisma/releases/tag/2.15.0) and later -- CockroachDB in versions [3.9.0](https://github.com/prisma/prisma/releases/tag/3.9.0) and later -- MongoDB in versions [3.11.0](https://github.com/prisma/prisma/releases/tag/3.11.0) and later +Available for PostgreSQL, CockroachDB, and MongoDB. @@ -163,10 +148,7 @@ const posts = await prisma.post.findMany({ -This section applies to: - -- PostgreSQL in versions [2.15.0](https://github.com/prisma/prisma/releases/tag/2.15.0) and later -- CockroachDB in versions [3.9.0](https://github.com/prisma/prisma/releases/tag/3.9.0) and later +This information applies to PostgreSQL and CockroachDB. diff --git a/content/200-orm/200-prisma-client/300-client-extensions/100-model.mdx b/content/200-orm/200-prisma-client/300-client-extensions/100-model.mdx index f245f1ba7e..f7e0c71364 100644 --- a/content/200-orm/200-prisma-client/300-client-extensions/100-model.mdx +++ b/content/200-orm/200-prisma-client/300-client-extensions/100-model.mdx @@ -5,14 +5,6 @@ metaDescription: 'Extend the functionality of Prisma Client, model component' toc_max_heading_level: 4 --- - - - - -Prisma Client extensions are Generally Available from versions 4.16.0 and later. They were introduced in Preview in version 4.7.0. Make sure you enable the `clientExtensions` Preview feature flag if you are running on a version earlier than 4.16.0. - - - You can use the `model` [Prisma Client extensions](/orm/prisma-client/client-extensions) component type to add custom methods to your models. Possible uses for the `model` component include the following: @@ -22,8 +14,6 @@ Possible uses for the `model` component include the following: - Repetitive operations - Model-specific utilities - - ## Add a custom method Use the `$extends` [client-level method](/orm/reference/prisma-client-reference#client-methods) to create an _extended client_. An extended client is a variant of the standard Prisma Client that is wrapped by one or more extensions. Use the `model` extension component to add methods to models in your schema. @@ -134,12 +124,6 @@ const prisma = new PrismaClient().$extends({ ## Get the current model name at runtime - - -This feature is available from version 4.9.0. - - - You can get the name of the current model at runtime with `Prisma.getExtensionContext(this).$name`. You might use this to write out the model name to a log, to send the name to another service, or to branch your code based on the model. For example: diff --git a/content/200-orm/200-prisma-client/300-client-extensions/110-client.mdx b/content/200-orm/200-prisma-client/300-client-extensions/110-client.mdx index 5aad99108e..0955104a33 100644 --- a/content/200-orm/200-prisma-client/300-client-extensions/110-client.mdx +++ b/content/200-orm/200-prisma-client/300-client-extensions/110-client.mdx @@ -5,18 +5,8 @@ metaDescription: 'Extend the functionality of Prisma Client, client component' toc_max_heading_level: 4 --- - - - - -Prisma Client extensions are Generally Available from versions 4.16.0 and later. They were introduced in Preview in version 4.7.0. Make sure you enable the `clientExtensions` Preview feature flag if you are running on a version earlier than 4.16.0. - - - You can use the `client` [Prisma Client extensions](/orm/prisma-client/client-extensions) component to add top-level methods to Prisma Client. - - ## Extend Prisma Client Use the `$extends` [client-level method](/orm/reference/prisma-client-reference#client-methods) to create an _extended client_. An extended client is a variant of the standard Prisma Client that is wrapped by one or more extensions. Use the `client` extension component to add top-level methods to Prisma Client. diff --git a/content/200-orm/200-prisma-client/300-client-extensions/120-query.mdx b/content/200-orm/200-prisma-client/300-client-extensions/120-query.mdx index 733c03041b..3e6c7b69a4 100644 --- a/content/200-orm/200-prisma-client/300-client-extensions/120-query.mdx +++ b/content/200-orm/200-prisma-client/300-client-extensions/120-query.mdx @@ -5,20 +5,10 @@ metaDescription: 'Extend the functionality of Prisma Client, query component' toc_max_heading_level: 4 --- - - - - -Prisma Client extensions are Generally Available from versions 4.16.0 and later. They were introduced in Preview in version 4.7.0. Make sure you enable the `clientExtensions` Preview feature flag if you are running on a version earlier than 4.16.0. - - - You can use the `query` [Prisma Client extensions](/orm/prisma-client/client-extensions) component type to hook into the query life-cycle and modify an incoming query or its result. You can use Prisma Client extensions `query` component to create independent clients. This provides an alternative to [middlewares](/orm/prisma-client/client-extensions/middleware). You can bind one client to a specific filter or user, and another client to another filter or user. For example, you might do this to get [user isolation](/orm/prisma-client/client-extensions#extended-clients) in a row-level security (RLS) extension. In addition, unlike middlewares the `query` extension component gives you end-to-end type safety. [Learn more about `query` extensions versus middlewares](#query-extensions-versus-middlewares). - - ## Extend Prisma Client query operations Use the `$extends` [client-level method](/orm/reference/prisma-client-reference#client-methods) to create an [extended client](/orm/prisma-client/client-extensions#about-prisma-client-extensions). An extended client is a variant of the standard Prisma Client that is wrapped by one or more extensions. diff --git a/content/200-orm/200-prisma-client/300-client-extensions/130-result.mdx b/content/200-orm/200-prisma-client/300-client-extensions/130-result.mdx index a413790ec3..c0a5b98f51 100644 --- a/content/200-orm/200-prisma-client/300-client-extensions/130-result.mdx +++ b/content/200-orm/200-prisma-client/300-client-extensions/130-result.mdx @@ -5,18 +5,8 @@ metaDescription: 'Extend the functionality of Prisma Client, result component' toc_max_heading_level: 4 --- - - - - -Prisma Client extensions are Generally Available from versions 4.16.0 and later. They were introduced in Preview in version 4.7.0. Make sure you enable the `clientExtensions` Preview feature flag if you are running on a version earlier than 4.16.0. - - - You can use the `result` [Prisma Client extensions](/orm/prisma-client/client-extensions) component type to add custom fields and methods to query results. - - Use the `$extends` [client-level method](/orm/reference/prisma-client-reference#client-methods) to create an _extended client_. An extended client is a variant of the standard Prisma Client that is wrapped by one or more extensions. To add a custom [field](#add-a-custom-field-to-query-results) or [method](#add-a-custom-method-to-the-result-object) to query results, use the following structure. In this example, we add the custom field `myComputedField` to the result of a `user` model query. diff --git a/content/200-orm/200-prisma-client/300-client-extensions/140-shared-extensions.mdx b/content/200-orm/200-prisma-client/300-client-extensions/140-shared-extensions.mdx index 88922a36dc..6ee74b07ea 100644 --- a/content/200-orm/200-prisma-client/300-client-extensions/140-shared-extensions.mdx +++ b/content/200-orm/200-prisma-client/300-client-extensions/140-shared-extensions.mdx @@ -80,21 +80,6 @@ Refer to the following pages to learn the different ways you can modify Prisma C - [Modify a specific operation in all models of your schema](/orm/prisma-client/client-extensions/query#modify-a-specific-operation-in-all-models-of-your-schema) - [Modify all operations in all models of your schema](/orm/prisma-client/client-extensions/query#modify-all-operations-in-all-models-of-your-schema) -
- For versions earlier than 4.16.0 - -The `Prisma` import is available from a different path shown in the snippet below: - -```ts -import { Prisma } from '@prisma/client/scripts/default-index' - -export default Prisma.defineExtension({ - name: 'prisma-extension-', -}) -``` - -
- ### Publishing the shareable extension to npm You can then share the extension on `npm`. When you choose a package name, we recommend that you use the `prisma-extension-` convention, to make it easier to find and install. diff --git a/content/200-orm/200-prisma-client/300-client-extensions/500-middleware/index.mdx b/content/200-orm/200-prisma-client/300-client-extensions/500-middleware/index.mdx index 35fd2675e1..a94a35e5a4 100644 --- a/content/200-orm/200-prisma-client/300-client-extensions/500-middleware/index.mdx +++ b/content/200-orm/200-prisma-client/300-client-extensions/500-middleware/index.mdx @@ -4,17 +4,15 @@ metaTitle: 'Middleware (Reference)' metaDescription: 'Prisma Client middleware allows you to perform actions before or after any query on any model with the prisma.$use method.' --- - +:::warning Deprecation warning - - -**Deprecated**: Middleware is deprecated in version 4.16.0. +Middleware was deprecated in Prisma ORM version 4.16.0. -We recommend using the [Prisma Client extensions `query` component type](/orm/prisma-client/client-extensions/query) as an alternative to middleware. Prisma Client extensions were first introduced into Preview in version 4.7.0 and made Generally Available in 4.16.0. +We recommend using the [Prisma Client extensions `query` component type](/orm/prisma-client/client-extensions/query) as an alternative to middleware. Prisma Client extensions allow you to create independent Prisma Client instances and bind each client to a specific filter or user. For example, you could bind clients to specific users to provide user isolation. Prisma Client extensions also provide end-to-end type safety. - +::: Middlewares act as query-level lifecycle hooks, which allow you to perform an action before or after a query runs. Use the [`prisma.$use`](/orm/reference/prisma-client-reference#use) method to add middleware, as follows: @@ -61,8 +59,6 @@ Possible use cases for middleware include: There are many more use cases for middleware - this list serves as inspiration for the types of problems that middleware is designed to address. - - ## Samples The following sample scenarios show how to use middleware in practice: diff --git a/content/200-orm/200-prisma-client/300-client-extensions/index.mdx b/content/200-orm/200-prisma-client/300-client-extensions/index.mdx index cfcf31b5e2..bf90015336 100644 --- a/content/200-orm/200-prisma-client/300-client-extensions/index.mdx +++ b/content/200-orm/200-prisma-client/300-client-extensions/index.mdx @@ -5,14 +5,6 @@ metaDescription: 'Extend the functionality of Prisma Client' toc_max_heading_level: 4 --- - - - - -Prisma Client extensions are Generally Available from versions 4.16.0 and later. They were introduced in Preview in version 4.7.0. Make sure you enable the `clientExtensions` Preview feature flag if you are running on a version earlier than 4.16.0. - - - You can use Prisma Client extensions to add functionality to your models, result objects, and queries, or to add client-level methods. You can create an extension with one or more of the following component types: @@ -24,8 +16,6 @@ You can create an extension with one or more of the following component types: For example, you might create an extension that uses the `model` and `client` component types. - - ## About Prisma Client extensions When you use a Prisma Client extension, you create an _extended client_. An extended client is a lightweight variant of the standard Prisma Client that is wrapped by one or more extensions. The standard client is not mutated. You can add as many extended clients as you want to your project. [Learn more about extended clients](#extended-clients). diff --git a/content/200-orm/200-prisma-client/400-type-safety/index.mdx b/content/200-orm/200-prisma-client/400-type-safety/index.mdx index caa214ec6e..9fa1ceacb1 100644 --- a/content/200-orm/200-prisma-client/400-type-safety/index.mdx +++ b/content/200-orm/200-prisma-client/400-type-safety/index.mdx @@ -233,12 +233,6 @@ We recommend using the "safe" `Input` types whenever possible. ## Type utilities - - -This feature is available from Prisma ORM version 4.9.0 upwards. - - - To help you create highly type-safe applications, Prisma Client provides a set of type utilities that tap into input and output types. These types are fully dynamic, which means that they adapt to any given model and schema. You can use them to improve the auto-completion and developer experience of your projects. This is especially useful in [validating inputs](/orm/prisma-client/type-safety/prisma-validator) and [shared Prisma Client extensions](/orm/prisma-client/client-extensions/shared-extensions). diff --git a/content/200-orm/200-prisma-client/600-observability-and-logging/240-metrics.mdx b/content/200-orm/200-prisma-client/600-observability-and-logging/240-metrics.mdx index 27db92374b..87d8be0888 100644 --- a/content/200-orm/200-prisma-client/600-observability-and-logging/240-metrics.mdx +++ b/content/200-orm/200-prisma-client/600-observability-and-logging/240-metrics.mdx @@ -57,8 +57,6 @@ To use Prisma Client metrics, you must do the following: ### 1. Install up-to-date Prisma ORM dependencies -Use version `3.15.0` or higher of the `prisma` and `@prisma/client` npm packages. - ```terminal npm install prisma@latest --save-dev npm install @prisma/client@latest --save diff --git a/content/200-orm/200-prisma-client/600-observability-and-logging/250-opentelemetry-tracing.mdx b/content/200-orm/200-prisma-client/600-observability-and-logging/250-opentelemetry-tracing.mdx index fb1a954c10..457c166092 100644 --- a/content/200-orm/200-prisma-client/600-observability-and-logging/250-opentelemetry-tracing.mdx +++ b/content/200-orm/200-prisma-client/600-observability-and-logging/250-opentelemetry-tracing.mdx @@ -80,7 +80,7 @@ This section explains how to install and register tracing in your application. ### Step 1. Install up-to-date Prisma ORM dependencies -Use version `6.1.0` or later of the `prisma`, `@prisma/client`, and `@prisma/instrumentation` npm packages. You will also need to install the `@opentelemetry/api` package as it's a peer dependency. +Use the latest versions of the `prisma`, `@prisma/client`, and `@prisma/instrumentation` npm packages. You will also need to install the `@opentelemetry/api` package as it's a peer dependency. ```terminal npm install prisma@latest --save-dev @@ -92,7 +92,7 @@ npm install @opentelemetry/api@latest --save
Tracing on previous versions of Prisma ORM -Tracing was added in version `4.2.0` of Prisma ORM as a Preview feature. For versions of Prisma ORM between `4.2.0` and `6.1.0`, you need to enable the `tracing` Preview feature in your Prisma schema file. +For versions before Prisma ORM 6.1.0, you will also need to enable the `tracing` Preview feature in your Prisma schema file. ```prisma generator client { diff --git a/content/200-orm/300-prisma-migrate/200-understanding-prisma-migrate/300-limitations-and-known-issues.mdx b/content/200-orm/300-prisma-migrate/200-understanding-prisma-migrate/300-limitations-and-known-issues.mdx index 49be07a481..be2d76cc27 100644 --- a/content/200-orm/300-prisma-migrate/200-understanding-prisma-migrate/300-limitations-and-known-issues.mdx +++ b/content/200-orm/300-prisma-migrate/200-understanding-prisma-migrate/300-limitations-and-known-issues.mdx @@ -18,7 +18,7 @@ Prisma Migrate does not currently support the MongoDB connector. Prisma Migrate generates SQL files that are specific to your provider. This means that you cannot use the same migration files for PostgreSQL in production and SQLite in development, because the syntax in the migrations will be incompatible. -In [2.15.0](https://github.com/prisma/prisma/releases/2.15.0) and later, Prisma Migrate detects when the migrations do not match the configured provider and prints a helpful error message. For example, if your migrations are for a PostgreSQL database but you are using a `provider` is set to `mysql`: +Prisma Migrate detects when the migrations do not match the configured provider and prints a helpful error message. For example, if your migrations are for a PostgreSQL database but you are using a `provider` is set to `mysql`: ``` Error: P3014 diff --git a/content/200-orm/300-prisma-migrate/200-understanding-prisma-migrate/600-legacy-migrate.mdx b/content/200-orm/300-prisma-migrate/200-understanding-prisma-migrate/600-legacy-migrate.mdx deleted file mode 100644 index 272a15e8ad..0000000000 --- a/content/200-orm/300-prisma-migrate/200-understanding-prisma-migrate/600-legacy-migrate.mdx +++ /dev/null @@ -1,466 +0,0 @@ ---- -title: 'Legacy Prisma Migrate' -metaTitle: 'Legacy Prisma Migrate (Reference)' -metaDescription: 'Legacy Prisma Migrate is a declarative data modeling and schema migration tool that is available via the Prisma CLI.' -tocDepth: 3 -unlisted: true ---- - - - -> **Important!** This page documents legacy Prisma Migrate (Experimental) available in version 2.12.0 and earlier. [Prisma Migrate](/orm/prisma-migrate) is available in version [2.13.0](https://github.com/prisma/prisma/releases/tag/2.13.0) and Generally Available in [2.19.0](https://github.com/prisma/prisma/releases/tag/2.19.0). - -Legacy Prisma Migrate is a tool that lets you _change your database schema_, e.g. by creating new tables or adding columns to existing tables. These changes are called _schema migrations_. legacy Prisma Migrate is available as part of the [Prisma CLI](/orm/tools/prisma-cli#installation) via the `legacy Prisma Migrate` command. - - - -## Documentation - -### Legacy Prisma Migrate vs the `db push` command - -If you want to prototype or iterate on a schema design in a development environment, consider the [`db push` command](/orm/reference/prisma-cli-reference#db-push). - -### Legacy Prisma Migrate vs SQL migrations - -Legacy Prisma Migrate is a _declarative_ migration system, as opposed to SQL which can be considered _imperative_: - -- **SQL (imperative)**: Provide the individual _steps_ to get from the current schema to the desired schema. -- **legacy Prisma Migrate (declarative)**: Define the desired schema as a [Prisma schema data model](/orm/prisma-schema/data-model/models) (legacy Prisma Migrate takes care of generating the necessary _steps_). - -Here's a quick comparison. Assume you have the following scenario: - -1. You need to create the `User` table to store user information (name, email, ...) -1. Create two new tables `Post` and `Profile` with foreign keys to `User` -1. Add a new column with a default value to the `Post` table - -#### SQL - -In SQL, you'd have to send three subsequent SQL statements to account for this scenario: - -##### 1. Create the `User` table to store user information (name, email, ...) - -```sql -CREATE TABLE "User" ( - id SERIAL PRIMARY KEY, - name VARCHAR(255), - email VARCHAR(255) NOT NULL -); -``` - -##### 2. Create two new tables `Post` and `Profile` with foreign keys to `User` - -```sql -CREATE TABLE "Profile" ( - id SERIAL PRIMARY KEY, - bio TEXT NOT NULL, - "user" integer NOT NULL UNIQUE, - FOREIGN KEY ("user") REFERENCES "User"(id) -); -CREATE TABLE "Post" ( - id SERIAL PRIMARY KEY, - title VARCHAR(255) NOT NULL, - author integer NOT NULL, - FOREIGN KEY (author) REFERENCES "User"(id) -); -``` - -##### 3. Add a new column with a default value to the `Post` table - -```sql -ALTER TABLE "Post" -ADD COLUMN published BOOLEAN DEFAULT false; -``` - -#### legacy Prisma Migrate - -With legacy Prisma Migrate, you write the desired database schema in the form of a [Prisma schema data model](/orm/prisma-schema/data-model/models) inside your [Prisma schema file](/orm/prisma-schema). To map the data model to your database schema, you then have to run these two commands: - -```terminal -prisma migrate save --experimental -prisma migrate up --experimental -``` - -The first command _saves_ a new migration to the `prisma/migrations` directory in the file system of your project and updates the `_Migration` table in your database. Each time you run this command to save a new migration, it creates a dedicated directory inside of `prisma/migrations` for that specific migration, which will have its own `README.md` file containing detailed information about the migration (e.g. the generated SQL statements which will be executed when you run `legacy Prisma Migrate up`). - -The second command _executes_ the migration against your database. - -##### 1. Create the `User` table to store user information (name, email, ...) - -Add the model to your Prisma schema: - -```prisma -model User { - id Int @id @default(autoincrement()) - name String? - email String @unique -} -``` - -Now run the two commands mentioned above: - -```terminal -prisma migrate save --experimental -prisma migrate up --experimental -``` - -##### 2. Create two new tables `Post` and `Profile` with foreign keys to `User` - -Add two models with [relation fields](/orm/prisma-schema/data-model/relations#relation-fields) to your Prisma schema: - -```prisma -model User { - id Int @id @default(autoincrement()) - name String? - email String @unique - posts Post[] - profile Profile? -} - -model Profile { - id Int @id @default(autoincrement()) - bio String - user User @relation(fields: [userId], references: [id]) - userId Int -} - -model Post { - id Int @id @default(autoincrement()) - title String - author User @relation(fields: [authorId], references: [id]) - authorId Int -} -``` - -Notice that in addition to the [annotated relation fields](/orm/prisma-schema/data-model/relations#annotated-relation-fields) and its relation scalar field (which represent the foreign keys), you must also specify the Prisma-level [relation fields](/orm/prisma-schema/data-model/relations#relation-fields) on the other side of the relation. - -Now run the two commands mentioned above: - -```terminal -prisma migrate save --experimental -prisma migrate up --experimental -``` - -##### 3. Add a new column with default value to the `Post` table - -Add a [field](/orm/prisma-schema/data-model/models#defining-fields) to the `Post` model: - -```prisma -model User { - id Int @id @default(autoincrement()) - name String? - email String @unique - posts Post[] - profile Profile? -} - -model Profile { - id Int @id @default(autoincrement()) - bio String - user User @relation(fields: [userId], references: [id]) - userId Int -} - -model Post { - id Int @id @default(autoincrement()) - title String - published Boolean @default(false) - authorId Int - author User @relation(fields: [authorId], references: [id]) -} -``` - -Now run the two commands mentioned above: - -```terminal -prisma migrate save --experimental -prisma migrate up --experimental -``` - -### Supported operations - -The following table shows which SQL operations are currently supported by legacy Prisma Migrate. - -| Operation | SQL | Supported | -| :-------------------------------- | :------------------------------ | :-----------------------------------------------------------------------------------: | -| Create a new table | `CREATE TABLE` | ✔️ | -| Rename an existing table | `ALTER TABLE` + `RENAME` | No | -| Delete an existing table | `DROP TABLE` | ✔️ | -| Add a column to an existing table | `ALTER TABLE` + `ADD COLUMN` | ✔️ | -| Rename an existing column | `ALTER TABLE` + `RENAME COLUMN` | No | -| Delete an existing column | `ALTER TABLE` + `DROP COLUMN` | ✔️ | -| Set primary keys (IDs) | `PRIMARY KEY` | ✔️ | -| Define relations (foreign keys) | `FOREIGN KEY` + `REFERENCES` | ✔️ | -| Make columns optional/required | `NOT NULL` | ✔️ | -| Set unique constraints | `UNIQUE` | ✔️ | -| Set default values | `DEFAULT` | ✔️ | -| Define enums | `ENUM` | ✔️ | -| Create indexes | `CREATE INDEX` | ✔️ | -| Cascading deletes | `ON DELETE` | No (workaround: manually add in SQL and introspect) | -| Cascading updates | `ON UPDATE` | No | -| Data validation | `CHECK` | No ([workaround](/orm/more/help-and-troubleshooting/check-constraints)) | - -Note that this table assumes that the operation is also supported by the underlying database. For example, `ENUM` is not supported in SQLite. This means that you also can't use `enum` when using legacy Prisma Migrate. - -### Migration history - -legacy Prisma Migrate stores the migration history of your project in two places: - -- A directory called `migrations` on your file system -- A table called `_Migration` in your database - -#### The `migrations` directory - -The `migrations` directory stores information about the migrations that have been or will be executed against your database. You should never make any manual changes to the files in `migrations`. The only way to change the content of this directory should be using the `legacy Prisma Migrate save` command. - -The `migrations` directory should be checked into version control (e.g. Git). - -#### The `_Migration` table - -The `_Migration` table additionally stores information about each migration that was ever executed against the database by legacy Prisma Migrate. - -### Typical workflow - -With **legacy Prisma Migrate**, the workflow looks slightly different: - -1. Manually adjust your [Prisma schema data model](/orm/prisma-schema/data-model/models) -1. Migrate your database using the `legacy Prisma Migrate` CLI commands -1. (Re-)generate Prisma Client -1. Use Prisma Client in your application code to access your database - -### Troubleshooting - -Since legacy Prisma Migrate is currently Experimental, you might end up in a state where the `migrations` directory and/or the `_Migrations` table are out of sync with the actual state of the database. In these cases, it often helps to "reset" legacy Prisma Migrate by deleting the `migrations` folder and deleting all entries from the `_Migration` table. - -#### Delete the `migrations` directory - -```terminal -rm -rf migrations -``` - -#### Delete all entries from the `_Migration` table - -```sql -TRUNCATE _Migration; -``` - -## CLI Reference - -> Warning: The `migrate` command is still considered Experimental. As such, there are no guarantees about API stability or production-readiness. Access to this command is provided for evaluation and experimentation. To access Experimental commands, you must add the `--experimental` flag. - -The `migrate` command creates and manages database migrations. It can be used to create, apply, and rollback database schema updates in a controlled manner. - -The `migrate` command includes a number of subcommands to specify the desired action. - -### `migrate save` - -Saves a migration that defines the steps necessary to update your current schema. - -#### Prerequisites - -Before using the `migrate save` command, you must define a valid [`datasource`](/orm/prisma-schema/overview/data-sources) within your `schema.prisma` file. - -For example, the following `datasource` defines a SQLite database file within the current directory: - -```prisma -datasource db { - provider = "sqlite" - url = "file:my-database.db" -} -``` - -#### Options - -The `migrate save` command recognizes the following options to modify its behavior: - -| Option | Required | Description | Default | -| ------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | -| `--experimental` | Yes | Enables use of Experimental commands. | | -| `-n`, `--name` | No | The name of the migration. If not provided, `migrate save` will prompt you for a name. | Timestamp `20200618145356` | -| `-c`, `--create-db` | No | Create the database if it does not exist. | | -| `-p`, `--preview` | No | Preview the migration that would be created without writing any changes to the filesystem. | | -| `--schema` | No | Specifies the path to the desired `schema.prisma` file to be processed instead of the default path. Both absolute and relative paths are supported. | `./schema.prisma`, `./prisma/schema.prisma` | - -#### Generated Assets - -The `migrate save` command generates the following directories and files as necessary: - -- `migrations`: A directory within the current project to store migrations. This directory will be created if it does not exist. -- `migrations/migrate.lock`: A lock file created specifying the current migration applied to the database. This file will be created if it does not exist. -- `migrations/`: A directory for a specific migration. The migration name is derived from the timestamp when it was created followed by a hyphen and the migration name provided by the user. -- `migrations//README.md`: A human-readable description of the migration including metadata like when the migration was created and by who, a list of the actual migration changes and a diff of the changes that are made to the `schema.prisma` file. -- `migrations//schema.prisma`: The schema that will be created if the migration is applied to the project. -- `migrations//steps.json`: An [alternative representation](https://github.com/prisma/specs/tree/master/migrate#step) of the migration steps that will be applied. - -#### Examples - -##### Create a new migration - -```terminal -prisma migrate save --experimental -``` - -The command will prompt you for a name for the migration since one was not provided on the command line. After creating the migration, the contents of the generated `schema.prisma` file are displayed. - -##### Create a migration with a specific name - -```terminal -prisma migrate save --name "First migration" --experimental -``` - -##### Create the database if it does not already exist - -```terminal -prisma migrate save --create-db --experimental -``` - -##### Preview the migration that would be created by running the `migrate save` command - -```terminal -prisma migrate save --preview --experimental -``` - -### `migrate up` - -Migrate the database up to a specific state. - -#### Prerequisites - -Before using the `migrate up` command, you must define a valid [`datasource`](/orm/prisma-schema/overview/data-sources) within your `schema.prisma` file. - -For example, the following `datasource` defines a SQLite database file within the current directory: - -```prisma -datasource db { - provider = "sqlite" - url = "file:my-database.db" -} -``` - -#### Arguments - -The point to migrate the database up to can be defined in any of the following three ways: - -| Argument | Required | Description | Default | -| --------- | -------- | ---------------------------------------------------------------------------------- | ------- | -| increment | No | Specifies the number of forward migrations to apply. | latest | -| name | No | Specifies where to migrate to using the name of the final migration to apply. | latest | -| timestamp | No | Specifies where to migrate to using the timestamp of the final migration to apply. | latest | - -#### Options - -Additionally, the following options modify the behavior of the `migrate up` command: - -| Option | Required | Description | Default | -| ------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | -| `--experimental` | Yes | Enables use of Experimental commands | | -| `-c`, `--create-db` | No | Create the database if it does not exist. | | -| `-p`, `--preview` | No | Preview the migration that would be created without writing any changes to the filesystem. | | -| `--schema` | No | Specifies the path to the desired `schema.prisma` file to be processed instead of the default path. Both absolute and relative paths are supported. | `./schema.prisma`, `./prisma/schema.prisma` | -| `--auto-approve` | No | Skip interactive approval before migrating. | | - -#### Examples - -##### Migrate the database up to the latest available migration - -```terminal -prisma migrate up --experimental -``` - -##### Apply the next two migrations to the database - -```terminal -prisma migrate up 2 --experimental -``` - -##### Apply all migrations necessary up to and including a migration by name - -```terminal -prisma migrate up "First migration" --experimental -``` - -##### Apply all migrations necessary up to and including a migration by timestamp - -```terminal -prisma migrate up 20200223181448 --experimental -``` - -##### Create the database if it does not already exist before applying the migrations - -```terminal -prisma migrate up --create-db --experimental -``` - -##### Preview the migration that would be applied by running the `migrate up` command - -```terminal -prisma migrate up --preview --experimental -``` - -### `migrate down` - -Migrate the database down to a specific state. - -#### Prerequisites - -Before using the `migrate down` command, you must define a valid [`datasource`](/orm/prisma-schema/overview/data-sources) within your `schema.prisma` file. - -For example, the following `datasource` defines a SQLite database file within the current directory: - -```prisma -datasource db { - provider = "sqlite" - url = "file:my-database.db" -} -``` - -#### Arguments - -The point to migrate back to can be defined in any of the following three ways: - -| Argument | Required | Description | Default | -| --------- | -------- | --------------------------------------------------------------------------------------- | ------- | -| decrement | No | Specifies the number of backwards migrations to apply. | 1 | -| name | No | Specifies where to migrate back to using the name of the final migration to apply. | -| timestamp | No | Specifies where to migrate back to using the timestamp of the final migration to apply. | - -#### Options - -Additionally, the following options modify the behavior of the `migrate down` command: - -| Option | Required | Description | Default | -| ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | -| `--experimental` | Yes | Enables use of Experimental commands | | -| `-p`, `--preview` | No | Preview the migration that would be created without writing any changes to the filesystem. | | -| `--schema` | No | Specifies the path to the desired `schema.prisma` file to be processed instead of the default path. Both absolute and relative paths are supported. | `./schema.prisma`, `./prisma/schema.prisma` | - -#### Examples - -##### Migrate the database backwards by a single migration - -```terminal -prisma migrate down --experimental -``` - -##### Migrate the database backwards by two migrations - -```terminal -prisma migrate down 2 --experimental -``` - -##### Migrate backwards through all migrations up to and including a migration by name - -```terminal -prisma migrate down "First migration" --experimental -``` - -##### Migrate backwards through all migrations up to and including a migration by timestamp - -```terminal -prisma migrate down 20200223181448 --experimental -``` - -##### Preview the migration that would be applied by running the `migrate down` command - -```terminal -prisma migrate down --preview --experimental -``` diff --git a/content/200-orm/300-prisma-migrate/300-workflows/10-seeding.mdx b/content/200-orm/300-prisma-migrate/300-workflows/10-seeding.mdx index 55092c5559..d352045f51 100644 --- a/content/200-orm/300-prisma-migrate/300-workflows/10-seeding.mdx +++ b/content/200-orm/300-prisma-migrate/300-workflows/10-seeding.mdx @@ -385,8 +385,6 @@ psql file.sql ### User-defined arguments -> This feature is available from version 4.15.0 and later. - `prisma db seed` allows you to define custom arguments in your seed file that you can pass to the `prisma db seed` command. For example, you could define your own arguments to seed different data for different environments or partially seeding data in some tables. Here is an example seed file that defines a custom argument to seed different data in different environments: diff --git a/content/200-orm/300-prisma-migrate/300-workflows/120-native-database-functions.mdx b/content/200-orm/300-prisma-migrate/300-workflows/120-native-database-functions.mdx index f9a6f18728..98ae838786 100644 --- a/content/200-orm/300-prisma-migrate/300-workflows/120-native-database-functions.mdx +++ b/content/200-orm/300-prisma-migrate/300-workflows/120-native-database-functions.mdx @@ -4,44 +4,23 @@ metaTitle: Native database functions metaDescription: How to enable PostgreSQL native database functions for projects that use Prisma Migrate. --- - - In PostgreSQL, some [native database functions](/orm/prisma-schema/data-model/unsupported-database-features#native-database-functions) are part of optional extensions. For example, in PostgreSQL versions 12.13 and earlier the `gen_random_uuid()` function is part of the [`pgcrypto`](https://www.postgresql.org/docs/10/pgcrypto.html) extension. To use a PostgreSQL extension, you must install it on the file system of your database server and then activate the extension. If you use Prisma Migrate, this must be done as part of a migration. - +:::warning Do not activate extensions outside a migration file if you use Prisma Migrate. The [shadow database](/orm/prisma-migrate/understanding-prisma-migrate/shadow-database) requires the same extensions. Prisma Migrate creates and deletes the shadow database automatically, so the only way to activate an extension is to include it in a migration file. - - -In Prisma ORM versions 4.5.0 and later, you can activate the extension by declaring it in your Prisma schema with the [`postgresqlExtensions` preview feature](/orm/prisma-schema/postgresql-extensions): - -```prisma file=schema.prisma highlight=3,9;add showLineNumbers -generator client { - provider = "prisma-client-js" - //add-next-line - previewFeatures = ["postgresqlExtensions"] -} +::: -datasource db { - provider = "postgresql" - url = env("DATABASE_URL") - //add-next-line - extensions = [pgcrypto] -} -``` +You can activate the extension by adding a SQL command to your migration file. See [How to install a PostgreSQL extension as part of a migration](#how-to-install-a-postgresql-extension-as-part-of-a-migration). You can then apply these changes to your database with Prisma Migrate. See [How to migrate PostgreSQL extensions](/orm/prisma-schema/postgresql-extensions#how-to-migrate-postgresql-extensions) for details. -In earlier versions of Prisma ORM, you must instead add a SQL command to your migration file to activate the extension. See [How to install a PostgreSQL extension as part of a migration](#how-to-install-a-postgresql-extension-as-part-of-a-migration). - - - ## How to install a PostgreSQL extension as part of a migration -This section describes how to add a SQL command to a migration file to activate a PostgreSQL extension. If you manage PostgreSQL extensions in your Prisma Schema with the `postgresqlExtensions` preview feature instead, see [How to migrate PostgreSQL extensions](/orm/prisma-schema/postgresql-extensions#how-to-migrate-postgresql-extensions). +This section describes how to add a SQL command to a migration file to activate a PostgreSQL extension. The following example demonstrates how to install the `pgcrypto` extension as part of a migration: diff --git a/content/200-orm/300-prisma-migrate/300-workflows/60-generating-down-migrations.mdx b/content/200-orm/300-prisma-migrate/300-workflows/60-generating-down-migrations.mdx index 5f20a17429..509c924948 100644 --- a/content/200-orm/300-prisma-migrate/300-workflows/60-generating-down-migrations.mdx +++ b/content/200-orm/300-prisma-migrate/300-workflows/60-generating-down-migrations.mdx @@ -23,12 +23,6 @@ This guide applies to generating SQL down migrations for relational databases on - - -The `migrate diff` and `db execute` commands are available in Preview in versions `3.9.0` and later, and are generally available in versions `3.13.0` and later. - - - ## Considerations when generating down migrations When generating a down migration file, there are some considerations to be aware of: diff --git a/content/200-orm/300-prisma-migrate/300-workflows/70-patching-and-hotfixing.mdx b/content/200-orm/300-prisma-migrate/300-workflows/70-patching-and-hotfixing.mdx index 9f8a5addad..b849aaaf0c 100644 --- a/content/200-orm/300-prisma-migrate/300-workflows/70-patching-and-hotfixing.mdx +++ b/content/200-orm/300-prisma-migrate/300-workflows/70-patching-and-hotfixing.mdx @@ -128,8 +128,6 @@ To help with fixing a failed migration, Prisma ORM provides the following comman - [`prisma migrate diff`](/orm/reference/prisma-cli-reference#migrate-diff) which diffs two database schema sources to create a migration taking one to the state of the second. You can output either a summary of the difference or a sql script. The script can be output into a file via `> file_name.sql` or be piped to the `db execute --stdin` command. - [`prisma db execute`](/orm/reference/prisma-cli-reference#db-execute) which applies a SQL script to the database without interacting with the Prisma migrations table. -These commands are available in Preview in versions `3.9.0` and later (with the `--preview-feature` CLI flag), and generally available in versions `3.13.0` and later. - This section gives an example scenario of a failed migration, and explains how to use `migrate diff` and `db execute` to fix it. ### Example of a failed migration @@ -252,12 +250,6 @@ Your local migration history now yields the same result as the state your produc ## Migration history conflicts - - -This does not apply from version [3.12.0](https://github.com/prisma/prisma/releases/tag/3.12.0) upwards. - - - `prisma migrate deploy` issues a warning if an already applied migration has been edited - however, it does not stop the migration process. To remove the warnings, restore the original migration from source control. ## Prisma Migrate and PgBouncer diff --git a/content/200-orm/400-tools/05-prisma-cli.mdx b/content/200-orm/400-tools/05-prisma-cli.mdx index f1af30fe00..5991be70ec 100644 --- a/content/200-orm/400-tools/05-prisma-cli.mdx +++ b/content/200-orm/400-tools/05-prisma-cli.mdx @@ -193,7 +193,7 @@ All `prisma` CLI commands return the following codes when they exit: - exit code 0 when a command runs successfully - exit code 1 when a command errors -- exit code 130 when the CLI receives a signal interrupt (SIGINT) message or if the user cancels a prompt. This exit code is available in Prisma ORM versions 4.3.0 and later. +- exit code 130 when the CLI receives a signal interrupt (SIGINT) message or if the user cancels a prompt. ## Telemetry diff --git a/content/200-orm/500-reference/050-prisma-client-reference.mdx b/content/200-orm/500-reference/050-prisma-client-reference.mdx index ca62e82ef3..52d23c8ffd 100644 --- a/content/200-orm/500-reference/050-prisma-client-reference.mdx +++ b/content/200-orm/500-reference/050-prisma-client-reference.mdx @@ -407,66 +407,6 @@ const adapter = new PrismaNeon(pool); const prisma = new PrismaClient({ adapter }); ``` -### `rejectOnNotFound` - - - -**Note**: `rejectOnNotFound` was removed in v5.0.0. - -**Deprecated:** `rejectOnNotFound` is deprecated in v4.0.0. From v4.0.0, use the queries [`findUniqueOrThrow`](#finduniqueorthrow) or [`findFirstOrThrow`](#findfirstorthrow). - - - -Use the `rejectOnNotFound` parameter to configure `findUnique()` and/or `findFirst` to throw an error if the record was not found. By default, both operations return `null` if the record is not found. - -#### Remarks - -- You can configure `rejectOnNotFound` on a per-request level for both [`findUnique()`](#findunique) and [`findFirst`](#findfirst) - -#### Options - -| Option | Description | -| -------------------- | ------------------------------------------------------------------------------------------- | -| `RejectOnNotFound` | Enable globally (`true` / `false`) _or_ throw a custom error. | -| `RejectPerOperation` | Enable per operation (`true` / `false`) _or_ throw a custom error per operation, per model. | - -#### Examples - -##### Enable globally for `findUnique()` and `findFirst` - -```ts -const prisma = new PrismaClient({ - rejectOnNotFound: true, -}); -``` - -##### Enable globally for a specific operation - -```ts -const prisma = new PrismaClient({ - rejectOnNotFound: { - findUnique: true, - }, -}); -``` - -##### Throw a custom error per model and operation if record is not found - -```ts -const prisma = new PrismaClient({ - rejectOnNotFound: { - findFirst: { - User: (err) => new Error('User error'), - Post: (err) => new Error('Post error!'), - }, - findUnique: { - User: (err) => new Error('User error'), - Post: (err) => new Error('Post error!'), - }, - }, -}); -``` - ### `transactionOptions` @@ -527,7 +467,7 @@ Use model queries to perform CRUD operations on your models. See also: [CRUD](/o | Name | Example type (`User`) | Required | Description | | ------------------------------- | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `where` | `UserWhereUniqueInput` | **Yes** | Wraps all fields of a model so that a record can be selected ([learn more](#filter-on-non-unique-fields-with-userwhereuniqueinput)).

Before version 4.5.0, this type only wraps _unique_ fields of a model. | +| `where` | `UserWhereUniqueInput` | **Yes** | Wraps all fields of a model so that a record can be selected ([learn more](#filter-on-non-unique-fields-with-userwhereuniqueinput)). | | `select` | `XOR` | No | [Specifies which properties to include](/orm/prisma-client/queries/select-fields) on the returned object. | | `include` | `XOR` | No | [Specifies which relations should be eagerly loaded](/orm/prisma-client/queries/relation-queries) on the returned object. | | `omit` | `XOR` | No | Specifies which properties to exclude on the returned object. In [Preview](/orm/more/releases#preview) since 5.13.0 | @@ -899,7 +839,7 @@ prisma:query COMMIT | Name | Type | Required | Description | | ----------------------- | ------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data` | `XOR`UserUncheckedUpdateInput>` | **Yes** | Wraps all the fields of the model so that they can be provided when updating an existing record. Fields that are marked as optional or have default values in the datamodel are optional. | -| `where` | `UserWhereUniqueInput` | **Yes** | Wraps all fields of a model so that a record can be selected ([learn more](#filter-on-non-unique-fields-with-userwhereuniqueinput)).

Before version 4.5.0, this type only wraps _unique_ fields of a model. | +| `where` | `UserWhereUniqueInput` | **Yes** | Wraps all fields of a model so that a record can be selected ([learn more](#filter-on-non-unique-fields-with-userwhereuniqueinput)). | | [`select`](#select) | `XOR` | No | [Specifies which properties to include](/orm/prisma-client/queries/select-fields) on the returned object. | | [`include`](#include) | `XOR` | No | [Specifies which relations should be eagerly loaded](/orm/prisma-client/queries/relation-queries) on the returned object. | | [`omit`](#omit) | `XOR` | No | Specifies which properties to exclude on the returned object. In [Preview](/orm/more/releases#preview) since 5.13.0. | @@ -948,7 +888,7 @@ This section covers the usage of the `upsert()` operation. To learn about using | ----------------------- | ------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `create` | `XOR`UserUncheckedCreateInput>` | **Yes** | Wraps all the fields of the model so that they can be provided when creating new records. It also includes relation fields which lets you perform (transactional) nested inserts. Fields that are marked as optional or have default values in the datamodel are optional. | | `update` | `XOR`UserUncheckedUpdateInput>` | **Yes** | Wraps all the fields of the model so that they can be provided when updating an existing record. Fields that are marked as optional or have default values in the datamodel are optional. | -| `where` | `UserWhereUniqueInput` | **Yes** | Wraps all fields of a model so that a record can be selected ([learn more](#filter-on-non-unique-fields-with-userwhereuniqueinput)).

Before version 4.5.0, this type only wraps _unique_ fields of a model. | +| `where` | `UserWhereUniqueInput` | **Yes** | Wraps all fields of a model so that a record can be selected ([learn more](#filter-on-non-unique-fields-with-userwhereuniqueinput)). | | [`select`](#select) | `XOR` | No | [Specifies which properties to include](/orm/prisma-client/queries/select-fields) on the returned object. | | [`include`](#include) | `XOR` | No | [Specifies which relations should be eagerly loaded](/orm/prisma-client/queries/relation-queries) on the returned object. | | [`omit`](#omit) | `XOR` | No | Specifies which properties to exclude on the returned object. In [Preview](/orm/more/releases#preview) since 5.13.0 | @@ -965,7 +905,7 @@ This section covers the usage of the `upsert()` operation. To learn about using - To perform arithmetic operations on update (add, subtract, multiply, divide), use [atomic updates](#atomic-number-operations) to prevent race conditions. - If two or more upsert operations happen at the same time and the record doesn't already exist, then a race condition might happen. As a result, one or more of the upsert operations might throw a unique key constraint error. Your application code can catch this error and retry the operation. [Learn more](#unique-key-constraint-errors-on-upserts). -- From version 4.6.0, Prisma ORM hands over upsert queries to the database where possible. [Learn more](#database-upserts). +- Prisma ORM hands over upsert queries to the database where possible. [Learn more](#database-upserts). #### Examples @@ -1002,24 +942,13 @@ Handle the P2002 error in your application code. When it occurs, retry the upser Where possible, Prisma Client hands over an `upsert` query to the database. This is called a _database upsert_. +Prisma Client can use database upserts if your application uses a CockroachDB, PostgreSQL, or SQLite data source. + Database upserts have the following advantages: - They are faster than upserts handled by Prisma Client - [Unique key constraint errors](#unique-key-constraint-errors-on-upserts) cannot happen -Prisma Client uses a database upsert automatically when [specific criteria](#database-upsert-query-criteria) are met. When these criteria are not met, Prisma Client handles the `upsert`. - -To use a database upsert, Prisma Client sends the SQL construction [`INSERT ... ON CONFLICT SET .. WHERE`](https://www.prisma.io/dataguide/postgresql/inserting-and-modifying-data/insert-on-conflict) to the database. - -##### Database upsert prerequisites - -Prisma Client can use database upserts if your stack meets the following criteria: - -- You use Prisma ORM version 4.6.0 or later -- Your application uses a CockroachDB, PostgreSQL, or SQLite data source - -##### Database upsert query criteria - Prisma Client uses a database upsert for an `upsert` query when the query meets the following criteria: - There are no nested queries in the `upsert`'s `create` and `update` [options](#options-7) @@ -1030,6 +959,8 @@ Prisma Client uses a database upsert for an `upsert` query when the query meets If your query does not meet these criteria, then Prisma Client handles the upsert itself. +To use a database upsert, Prisma Client sends the SQL construction [`INSERT ... ON CONFLICT SET .. WHERE`](https://www.prisma.io/dataguide/postgresql/inserting-and-modifying-data/insert-on-conflict) to the database. + ##### Database upsert examples The following examples use this schema: @@ -1154,7 +1085,7 @@ To delete records that match a certain criteria, use [`deleteMany`](#deletemany) | Name | Type | Required | Description | | ----------------------- | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `where` | `UserWhereUniqueInput` | **Yes** | Wraps all fields of a model so that a record can be selected ([learn more](#filter-on-non-unique-fields-with-userwhereuniqueinput)).

Before version 4.5.0, this type only wraps _unique_ fields of a model. | +| `where` | `UserWhereUniqueInput` | **Yes** | Wraps all fields of a model so that a record can be selected ([learn more](#filter-on-non-unique-fields-with-userwhereuniqueinput)). | | [`select`](#select) | `XOR` | No | [Specifies which properties to include](/orm/prisma-client/queries/select-fields) on the returned object. | | [`include`](#include) | `XOR` | No | [Specifies which relations should be eagerly loaded](/orm/prisma-client/queries/relation-queries) on the returned object. | | [`omit`](#omit) | `XOR` | No | Specifies which properties to exclude on the returned object. In [Preview](/orm/more/releases#preview) since 5.13.0 | @@ -1743,7 +1674,7 @@ See: [Using Raw SQL (`aggregateRaw()`)](/orm/prisma-client/using-raw-sql/raw-que #### Remarks - You cannot combine `select` and `include` on the same level. -- In [3.0.1](https://github.com/prisma/prisma/releases/3.0.1) and later, you can [select a `_count` of relations](#select-a-_count-of-relations). +- You can [select a `_count` of relations](#select-a-_count-of-relations). #### Examples @@ -1961,7 +1892,7 @@ const selectNameEmailNotPosts = Prisma.validator()({ #### Remarks -- In [3.0.1](https://github.com/prisma/prisma/releases/3.0.1) and later, you can [`include` a `_count` of relations](#include-a-_count-of-relations) +- You can [`include` a `_count` of relations](#include-a-_count-of-relations) #### Examples @@ -2236,10 +2167,11 @@ The following examples demonstrate how to use the [`validator`](/orm/prisma-clie }); ``` -- `UserWhereUniqueInput` This type works by exposing any unique fields on the model. A field assigned `@id` is considered unique, - as is one assigned `@unique`. +- `UserWhereUniqueInput` - From version 4.5.0, this type exposes all fields on the model. This means that when you filter for a single record based on a unique field, you can check additional non-unique and unique fields at the same time. [Learn more](#filter-on-non-unique-fields-with-userwhereuniqueinput). + A field assigned `@id` is considered unique, as is one assigned `@unique`. + + This type exposes all fields on the model. This means that when you filter for a single record based on a unique field, you can check additional non-unique and unique fields at the same time. [Learn more](#filter-on-non-unique-fields-with-userwhereuniqueinput). ```ts // UserWhereUniqueInput @@ -2256,8 +2188,9 @@ The following examples demonstrate how to use the [`validator`](/orm/prisma-clie }); ``` -- `PostUpdateWithWhereUniqueWithoutAuthorInput` - This type accepts a unique `where` field (an `@id` or another assigned `@unique`) - and updates any field on the `Post` model except the `Author`. The `Author` is the scalar field on the `Post` model. +- `PostUpdateWithWhereUniqueWithoutAuthorInput` + + This type accepts a unique `where` field (an `@id` or another assigned `@unique`) and updates any field on the `Post` model except the `Author`. The `Author` is the scalar field on the `Post` model. ```ts const updatePostByIdWithoutAuthor = @@ -2312,11 +2245,9 @@ Sorts a list of records. See also: [Sorting](/orm/prisma-client/queries/filterin #### Remarks -- In [2.16.0](https://github.com/prisma/prisma/releases/2.16.0) and later, you can [order by relation fields](#sort-post-by-the-related-user-records-name) - for example, order posts by the author's name. - -- In [3.5.0](https://github.com/prisma/prisma/releases/3.5.0) and later, in PostgreSQL you can [order by relevance](#sort-post-by-relevance-of-the-title). For details, see [Sort by relevance](/orm/prisma-client/queries/filtering-and-sorting#sort-by-relevance-postgresql-and-mysql). - -- In [4.1.0](https://github.com/prisma/prisma/releases/4.1.0) and later, you can [sort `null` records first or last](#sort-post-by-the-related-user-records-name-with-null-records-first). For details, see [Sort with nulls first or last](/orm/prisma-client/queries/filtering-and-sorting#sort-with-null-records-first-or-last). +- You can [order by relation fields](#sort-post-by-the-related-user-records-name) - for example, order posts by the author's name. +- With PostgreSQL you can [order by relevance](#sort-post-by-relevance-of-the-title). For details, see [Sort by relevance](/orm/prisma-client/queries/filtering-and-sorting#sort-by-relevance-postgresql-and-mysql). +- You can [sort `null` records first or last](#sort-post-by-the-related-user-records-name-with-null-records-first). For details, see [Sort with nulls first or last](/orm/prisma-client/queries/filtering-and-sorting#sort-with-null-records-first-or-last). #### Inputs for `sort` argument @@ -2331,7 +2262,7 @@ Note: - This argument is optional. - It is for use on optional [scalar](/orm/prisma-schema/data-model/models#scalar-fields) fields only. If you try to sort by nulls on a required or [relation](/orm/prisma-schema/data-model/models#relation-fields) field, Prisma Client throws a [P2009 error](/orm/reference/error-reference#p2009). -- It is available in version 4.1.0 and later, as a preview feature. See [sort with nulls first or last](/orm/prisma-client/queries/filtering-and-sorting#sort-with-null-records-first-or-last) for details of how to enable the feature. +- It is available as a preview feature. See [sort with nulls first or last](/orm/prisma-client/queries/filtering-and-sorting#sort-with-null-records-first-or-last) for details of how to enable the feature. | Name | Description | | ------- | ------------------------------ | @@ -3148,7 +3079,7 @@ const user = await prisma.profile.create({ }); ``` -In [2.11.0](https://github.com/prisma/prisma/releases/2.11.0) and later, you can set the foreign key directly: +You can also set the foreign key directly: ```ts const user = await prisma.profile.create({ @@ -3373,14 +3304,7 @@ A nested `disconnect` query breaks the connection between a parent record and a #### Remarks - `disconnect` is only available if the relation is optional. -- If the relationship you are attempting to disconnect does not exist: - - - ([In 2.21.0 and later](https://github.com/prisma/prisma/releases/tag/2.21.0)), the operation does nothing - - (Before [2.21.0](https://github.com/prisma/prisma/releases/tag/2.21.0)) Prisma Client throws an exception if the provided ID or unique identifier is not connected: - - ``` - The records for relation `PostToUser` between the `User` and `Post` models are not connected. - ``` +- If the relationship you are attempting to disconnect does not exist, the operation does nothing. #### Examples @@ -3606,13 +3530,6 @@ const result = await prisma.user.update({ ## Filter conditions and operators - - -- From version 4.3.0, you can also use these operators to compare _fields_ in the same model [with the `.fields` property](#compare-columns-in-the-same-table). -- In versions before 4.3.0, you can compare fields in the same model [with raw queries](/orm/more/help-and-troubleshooting/comparing-columns-through-raw-queries). - - - ### `equals` Value equals `n`. @@ -3643,8 +3560,6 @@ const result = await prisma.user.findMany({ ##### Return all products with a quantity lower than the "warn quantity" threshold -This example compares fields of the same model which is available as of version 4.3.0. - ```ts const productsWithLowQuantity = await prisma.product.findMany({ where: { @@ -4390,7 +4305,7 @@ const setTags = await prisma.post.update({ ### `push` -`push` is available in version [2.20.0](https://github.com/prisma/prisma/releases/2.20.0) and later. Use `push` to add _one_ value or _multiple_ values to a scalar list field. +Use `push` to add _one_ value or _multiple_ values to a scalar list field. #### Remarks @@ -4431,8 +4346,7 @@ const addTag = await prisma.post.update({ -This method is available on MongoDB only in versions -[3.11.1](https://github.com/prisma/prisma/releases/tag/3.11.1) and later. +This method is only available on MongoDB. @@ -4461,11 +4375,7 @@ Scalar list filters allow you to filter by the contents of a list / array field. -Available for: - -- PostgreSQL in versions [2.15.0](https://github.com/prisma/prisma/releases/tag/2.15.0) and later -- CockroachDB in versions [3.9.0](https://github.com/prisma/prisma/releases/tag/3.9.0) and later -- MongoDB in versions [3.11.0](https://github.com/prisma/prisma/releases/tag/3.11.0) and later +Available for PostgreSQL, CockroachDB, and MongoDB. @@ -4563,8 +4473,7 @@ const posts = await prisma.post.findMany({ -This filter is available on MongoDB only in versions -[3.11.1](https://github.com/prisma/prisma/releases/tag/3.11.1) and later. +This filter is only available on MongoDB. @@ -4606,7 +4515,7 @@ const posts = await prisma.post.findMany({ -Available for MongoDB only in Prisma `3.10.0` and later. +Available for MongoDB only. @@ -4775,7 +4684,7 @@ const product = prisma.product.update({ -Available for MongoDB only in Prisma `3.11.0` and later. +Available for MongoDB only. @@ -5667,19 +5576,6 @@ const validateUserAndPostInput = (name, email, postTitle) => { You can compare columns in the same table directly, for non-unique filters. -This feature was moved to general availability in version 5.0.0 and was available via the `fieldReference` Preview feature from Prisma ORM versions 4.3.0 to 4.16.2. - - - -In the following situations, you must [use raw queries to compare columns in the same table](/orm/more/help-and-troubleshooting/comparing-columns-through-raw-queries): - -- If you use a version earlier than 4.3.0 -- If you want to use a unique filter, such as [`findUnique`](#findunique) or [`findUniqueOrThrow`](#finduniqueorthrow) -- If you want to compare a field with a [unique constraint](/orm/prisma-schema/data-model/models#defining-a-unique-field) -- If you want to use one of the following operators to compare a [JSON field](/orm/prisma-client/special-fields-and-types/working-with-json-fields) in MySQL or MariaDB with another field: [`gt`](#gt), [`gte`](#gte), [`lt`](#lt), or [`lte`](#lte). Note that you can use these operators to compare the JSON field with a scalar value. This limitation applies only if you try to compare a JSON field with another field. - - - To compare columns in the same table, use the `.fields` property. In the following example, the query returns all records where the value in the `prisma.product.quantity` field is less than or equal to the value in the `prisma.product.warnQuantity` field. ```ts @@ -5766,7 +5662,6 @@ await prisma.user.findMany({ ## Filter on non-unique fields with `UserWhereUniqueInput` From version 5.0.0, the generated type `UserWhereUniqueInput` on [`where`](#where) exposes all fields on the model, not just unique fields. -This was available under the [`extendedWhereUnique` Preview flag](/orm/reference/preview-features/client-preview-features#preview-features-promoted-to-general-availability) between versions 4.5.0 to 4.16.2 You must specify at least one unique field in your `where` statement [outside of boolean operators](#boolean-operators-with-userwhereuniqueinput), and you can specify any number of additional unique and non-unique fields. You can use this to add filters to any operation that returns a single record. For example, you can use this feature for the following: @@ -5774,13 +5669,11 @@ You must specify at least one unique field in your `where` statement [outside of - [Permission checks](#permission-checks) - [Soft deletes](#soft-deletes) -From version 4.6.0, you can use this feature to filter on optional [one-to-one nested reads](/orm/prisma-client/queries/relation-queries#nested-reads). - ### Optimistic concurrency control on updates You can filter on non-unique fields to perform [optimistic concurrency control](/orm/prisma-client/queries/transactions#optimistic-concurrency-control) on `update` operations. -To perform optimistic concurrency control, we recommend that you use a `version` field to check whether the data in a record or related record has changed while your code executes. Before version 4.5.0, you could not evaluate the `version` field in an `update` operation, because the field is non-unique. From version 4.5.0, you can evaluate the `version` field. +To perform optimistic concurrency control, we recommend that you use a `version` field to check whether the data in a record or related record has changed while your code executes. In the following example, `updateOne` and `updateTwo` first read the same record and then attempt to update it. The database only executes these updates if the value in `version` is the same as the value when it did the initial read. When the database executes the first of these updates (which might be `updateOne` or `updateTwo`, depending on timing), it increments the value in `version`. This means that the database does not execute the second update because the value in `version` has changed. @@ -5871,13 +5764,6 @@ await prisma.user.update({ #### One-to-one relations -From version 4.5.0, you can filter on non-unique fields in the following operations on [one-to-one relations](/orm/prisma-schema/data-model/relations/one-to-one-relations): - -- Nested update -- Nested upsert -- Nested disconnect -- Nested delete - Prisma Client automatically uses a unique filter to select the appropriate related record. As a result, you do not need to specify a unique filter in your `where` statement with a `WhereUniqueInput` [generated type](#generated-types-for-where). Instead, the `where` statement has a `WhereInput` generated type. You can use this to filter without the restrictions of `WhereUniqueInput`. ##### Nested update example @@ -5887,9 +5773,6 @@ await prisma.user.update({ where: { id: 1, }, data: { to_one: { - // Before Prisma version 4.5.0 - update: { field: "updated" } - // From Prisma version 4.5.0, you can also do the following: update: { where: { /*WhereInput*/ }, data: { field: "updated" } } } } } @@ -5920,9 +5803,6 @@ await prisma.user.update({ where: { id: 1, }, data: { to_one: { - // Before Prisma version 4.5.0 - disconnect: true - // From Prisma version 4.5.0, you can also do the following: disconnect: { /* WhereInput */ } } } @@ -5936,9 +5816,6 @@ await prisma.user.update({ where: { id: 1, }, data: { to_one: { - // Before Prisma version 4.5.0 - delete: true - // From Prisma version 4.5.0, you can also do the following: delete: { /* WhereInput */ } } } diff --git a/content/200-orm/500-reference/100-prisma-schema-reference.mdx b/content/200-orm/500-reference/100-prisma-schema-reference.mdx index 9c8c634416..8aa89ad23f 100644 --- a/content/200-orm/500-reference/100-prisma-schema-reference.mdx +++ b/content/200-orm/500-reference/100-prisma-schema-reference.mdx @@ -20,9 +20,9 @@ A `datasource` block accepts the following fields: | `provider` | **Yes** | String (`postgresql`, `mysql`, `sqlite`, `sqlserver`, `mongodb`, `cockroachdb`) | Describes which data source connectors to use. | | `url` | **Yes** | String (URL) | Connection URL including authentication info. Most connectors use [the syntax provided by the database](/orm/reference/connection-urls#format). | | `shadowDatabaseUrl` | No | String (URL) | Connection URL to the shadow database used by Prisma Migrate. Allows you to use a cloud-hosted database as the shadow database. | -| `directUrl` | No | String (URL) | Connection URL for direct connection to the database.

If you use a connection pooler URL in the `url` argument (for example, if you use [Prisma Accelerate](/accelerate) or pgBouncer), Prisma CLI commands that require a direct connection to the database use the URL in the `directUrl` argument.

The `directUrl` property is supported by Prisma Studio from version 5.1.0 upwards.

The `directUrl` property is not needed when using [Prisma Postgres](/postgres) database. | -| `relationMode` | No | String (`foreignKeys`, `prisma`) | Sets whether [referential integrity](/orm/prisma-schema/data-model/relations/relation-mode) is enforced by foreign keys in the database or emulated in the Prisma Client.

In preview in versions 3.1.1 and later. The field is named `relationMode` in versions 4.5.0 and later, and was previously named `referentialIntegrity`. | -| `extensions` | No | List of strings (PostgreSQL extension names) | Allows you to [represent PostgreSQL extensions in your schema](/orm/prisma-schema/postgresql-extensions#how-to-represent-postgresql-extensions-in-your-prisma-schema). Available in preview for PostgreSQL only in Prisma ORM versions 4.5.0 and later. | +| `directUrl` | No | String (URL) | Connection URL for direct connection to the database.

If you use a connection pooler URL in the `url` argument (for example, if you use [Prisma Accelerate](/accelerate) or pgBouncer), Prisma CLI commands that require a direct connection to the database use the URL in the `directUrl` argument.

The `directUrl` property is supported by Prisma Studio from Prisma ORM version 5.1.0 upwards.

The `directUrl` property is not needed when using [Prisma Postgres](/postgres) database. | +| `relationMode` | No | String (`foreignKeys`, `prisma`) | Sets whether [referential integrity](/orm/prisma-schema/data-model/relations/relation-mode) is enforced by foreign keys in the database or emulated in the Prisma Client. | +| `extensions` | No | List of strings (PostgreSQL extension names) | Allows you to [represent PostgreSQL extensions in your schema](/orm/prisma-schema/postgresql-extensions#how-to-represent-postgresql-extensions-in-your-prisma-schema). | The following providers are available: @@ -196,19 +196,15 @@ Unless specified otherwise, the default supported CPU architecture is x86_64. | Build OS | Prisma engine build name | OpenSSL | | :---------------------- | :--------------------------- | :-----: | -| Alpine (3.17 and newer) | `linux-musl-openssl-3.0.x`\* | 3.0.x | +| Alpine (3.17 and newer) | `linux-musl-openssl-3.0.x` | 3.0.x | | Alpine (3.16 and older) | `linux-musl` | 1.1.x | -\* Available in Prisma ORM versions 4.8.0 and later. - ##### Linux (Alpine on ARM64 architectures) | Build OS | Prisma engine build name | OpenSSL | | :---------------------- | :--------------------------------- | :-----: | -| Alpine (3.17 and newer) | `linux-musl-arm64-openssl-3.0.x`\* | 3.0.x | -| Alpine (3.16 and older) | `linux-musl-arm64-openssl-1.1.x`\* | 1.1.x | - -\* Available in Prisma ORM versions 4.10.0 and later. +| Alpine (3.17 and newer) | `linux-musl-arm64-openssl-3.0.x` | 3.0.x | +| Alpine (3.16 and older) | `linux-musl-arm64-openssl-1.1.x` | 1.1.x | ##### Linux (Debian), x86_64 @@ -351,7 +347,7 @@ Defines a Prisma [model](/orm/prisma-schema/data-model/models#defining-models) . #### Order of fields -- In version 2.3.0 and later, introspection lists model fields in the same order as the corresponding columns in the database. Relation fields are listed after scalar fields. +Introspection lists model fields in the same order as the corresponding columns in the database. Relation fields are listed after scalar fields. ### Examples @@ -686,8 +682,6 @@ True or false value. Floating point number. -> `Float` maps to `Double` in [2.17.0](https://github.com/prisma/prisma/releases/tag/2.17.0) and later - see [release notes](https://github.com/prisma/prisma/releases/tag/2.17.0) and [Video: Changes to the default mapping of Float in Prisma ORM 2.17.0](https://www.youtube.com/watch?v=OsuGP_xNHco&%3Bab_channel=Prisma) for more information about this change. - #### Default type mappings | Connector | Default mapping | @@ -1091,8 +1085,6 @@ model User { ##### Define a scalar list with a default value -Available in version 4.0.0 and later. - @@ -1200,10 +1192,10 @@ Defines a single-field ID on the model. | Name | Required | Type | Description | | ----------- | -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `map` | **No** | `String` | The name of the underlying primary key constraint in the database.

Not supported for MySQL or MongoDB. | -| `length` | **No** | `number` | Allows you to specify a maximum length for the subpart of the value to be indexed.

MySQL only. In preview in versions 3.5.0 and later, and in general availability in versions 4.0.0 and later. | -| `sort` | **No** | `String` | Allows you to specify in what order the entries of the ID are stored in the database. The available options are `Asc` and `Desc`.

SQL Server only. In preview in versions 3.5.0 and later, and in general availability in versions 4.0.0 and later. | -| `clustered` | **No** | `Boolean` | Defines whether the ID is clustered or non-clustered. Defaults to `true`.

SQL Server only. In preview in versions 3.13.0 and later, and in general availability in versions 4.0.0 and later. | +| `map` | **No** | `String` | The name of the underlying primary key constraint in the database. Not supported for MySQL or MongoDB. | +| `length` | **No** | `number` | Allows you to specify a maximum length for the subpart of the value to be indexed. MySQL only. | +| `sort` | **No** | `String` | Allows you to specify in what order the entries of the ID are stored in the database. The available options are `Asc` and `Desc`. SQL Server only. | +| `clustered` | **No** | `Boolean` | Defines whether the ID is clustered or non-clustered. Defaults to `true`. SQL Server only. | #### Signature @@ -1211,18 +1203,6 @@ Defines a single-field ID on the model. @id(map: String?, length: number?, sort: String?, clustered: Boolean?) ``` -> **Note**: Before version 4.0.0, or 3.5.0 with the `extendedIndexes` Preview feature enabled, the signature was: -> -> ```prisma no-lines -> @id(map: String?) -> ``` - -> **Note**: Before version 3.0.0, the signature was: -> -> ```prisma no-lines -> @id -> ``` - #### Examples In most cases, you want your database to create the ID. To do this, annotate the ID field with the `@default` attribute and initialize the field with a [function](#attribute-functions). @@ -1502,10 +1482,10 @@ Defines a multi-field ID (composite ID) on the model. | ----------- | -------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fields` | **Yes** | `FieldReference[]` | A list of field names - for example, `["firstname", "lastname"]` | | `name` | **No** | `String` | The name that Prisma Client will expose for the argument covering all fields, e.g. `fullName` in `fullName: { firstName: "First", lastName: "Last"}` | -| `map` | **No** | `String` | The name of the underlying primary key constraint in the database.

Not supported for MySQL. | -| `length` | **No** | `number` | Allows you to specify a maximum length for the subpart of the value to be indexed.

MySQL only. In preview in versions 3.5.0 and later, and in general availability in versions 4.0.0 and later. | -| `sort` | **No** | `String` | Allows you to specify in what order the entries of the ID are stored in the database. The available options are `Asc` and `Desc`.

SQL Server only. In preview in versions 3.5.0 and later, and in general availability in versions 4.0.0 and later. | -| `clustered` | **No** | `Boolean` | Defines whether the ID is clustered or non-clustered. Defaults to `true`.

SQL Server only. In preview in versions 3.13.0 and later, and in general availability in versions 4.0.0 and later. | +| `map` | **No** | `String` | The name of the underlying primary key constraint in the database. Not supported for MySQL. | +| `length` | **No** | `number` | Allows you to specify a maximum length for the subpart of the value to be indexed. MySQL only. | +| `sort` | **No** | `String` | Allows you to specify in what order the entries of the ID are stored in the database. The available options are `Asc` and `Desc`. SQL Server only. | +| `clustered` | **No** | `Boolean` | Defines whether the ID is clustered or non-clustered. Defaults to `true`. SQL Server only. | The name of the `fields` argument on the `@@id` attribute can be omitted: @@ -1520,12 +1500,6 @@ The name of the `fields` argument on the `@@id` attribute can be omitted: @@id(_ fields: FieldReference[], name: String?, map: String?) ``` -> **Note**: Until version 3.0.0, the signature was: -> -> ```prisma no-lines -> @@id(_ fields: FieldReference[]) -> ``` - #### Examples ##### Specify a multi-field ID on two `String` fields (Relational databases only) @@ -1684,12 +1658,6 @@ id Int @id @default(autoincrement()) @default(_ value: Expression, map: String?) ``` -> **Note**: Until version 3.0.0, the signature was: -> -> ```prisma no-lines -> @default(_ value: Expression) -> ``` - #### Examples ##### Default value for an `Int` @@ -2007,12 +1975,12 @@ Defines a unique constraint for this field. #### Arguments -| Name | Required | Type | Description | -| ----------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `map` | **No** | `String` | | -| `length` | **No** | `number` | Allows you to specify a maximum length for the subpart of the value to be indexed.

MySQL only. In preview in versions 3.5.0 and later, and in general availability in versions 4.0.0 and later. | -| `sort` | **No** | `String` | Allows you to specify in what order the entries of the constraint are stored in the database. The available options are `Asc` and `Desc`.

In preview in versions 3.5.0 and later, and in general availability in versions 4.0.0 and later. | -| `clustered` | **No** | `Boolean` | Defines whether the constraint is clustered or non-clustered. Defaults to `false`.

SQL Server only. In preview in versions 3.13.0 and later, and in general availability in versions 4.0.0 and later. | +| Name | Required | Type | Description | +| ----------- | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `map` | **No** | `String` | | +| `length` | **No** | `number` | Allows you to specify a maximum length for the subpart of the value to be indexed. MySQL only. | +| `sort` | **No** | `String` | Allows you to specify in what order the entries of the constraint are stored in the database. The available options are `Asc` and `Desc`. | +| `clustered` | **No** | `Boolean` | Defines whether the constraint is clustered or non-clustered. Defaults to `false`. SQL Server only. | - ¹ Can be required by some of the index and field types. @@ -2022,18 +1990,6 @@ Defines a unique constraint for this field. @unique(map: String?, length: number?, sort: String?) ``` -> **Note**: Before version 4.0.0, or 3.5.0 with the `extendedIndexes` Preview feature enabled, the signature was: -> -> ```prisma no-lines -> @unique(map: String?) -> ``` - -> **Note**: Before version 3.0.0, the signature was: -> -> ```no-lines -> @unique -> ``` - #### Examples ##### Specify a unique attribute on a required `String` field @@ -2206,9 +2162,9 @@ Defines a compound [unique constraint](/orm/prisma-schema/data-model/models#defi | `fields` | **Yes** | `FieldReference[]` | A list of field names - for example, `["firstname", "lastname"]`. Fields must be mandatory - see remarks. | | `name` | **No** | `String` | The name of the unique combination of fields - defaults to `fieldName1_fieldName2_fieldName3` | | `map` | **No** | `String` | | -| `length` | **No** | `number` | Allows you to specify a maximum length for the subpart of the value to be indexed.

MySQL only. In preview in versions 3.5.0 and later, and in general availability in versions 4.0.0 and later. | -| `sort` | **No** | `String` | Allows you to specify in what order the entries of the constraint are stored in the database. The available options are `Asc` and `Desc`.

In preview in versions 3.5.0 and later, and in general availability in versions 4.0.0 and later. | -| `clustered` | **No** | `Boolean` | Defines whether the constraint is clustered or non-clustered. Defaults to `false`.

SQL Server only. In preview in versions 3.13.0 and later, and in general availability in versions 4.0.0 and later. | +| `length` | **No** | `number` | Allows you to specify a maximum length for the subpart of the value to be indexed. MySQL only. | +| `sort` | **No** | `String` | Allows you to specify in what order the entries of the constraint are stored in the database. The available options are `Asc` and `Desc`. | +| `clustered` | **No** | `Boolean` | Defines whether the constraint is clustered or non-clustered. Defaults to `false`. SQL Server only. | The name of the `fields` argument on the `@@unique` attribute can be omitted: @@ -2227,21 +2183,9 @@ The `length` and `sort` arguments are added to the relevant field names: #### Signature -> ```prisma no-lines -> @@unique(_ fields: FieldReference[], name: String?, map: String?) -> ``` - -> **Note**: Before version 4.0.0, or before version 3.5.0 with the `extendedIndexes` Preview feature enabled, the signature was: -> -> ```prisma no-lines -> @@unique(_ fields: FieldReference[], name: String?, map: String?) -> ``` - -> **Note**: Before version 3.0.0, the signature was: -> -> ```prisma no-lines -> @@unique(_ fields: FieldReference[], name: String?) -> ``` +```prisma no-lines +@@unique(_ fields: FieldReference[], name: String?, map: String?) +``` #### Examples @@ -2448,14 +2392,14 @@ While you cannot configure these option in your Prisma schema, you can still con | Name | Required | Type | Description | | ----------- | -------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `fields` | **Yes** | `FieldReference[]` | A list of field names - for example, `["firstname", "lastname"]` | -| `name` | **No** | `String` | The name that Prisma Client will expose for the argument covering all fields, e.g. `fullName` in `fullName: { firstName: "First", lastName: "Last"}` | -| `map` | **No** | `map` | The name of the index in the underlying database (Prisma generates an index name that respects identifier length limits if you do not specify a name. Prisma uses the following naming convention: `tablename.field1_field2_field3_unique`) | -| `length` | **No** | `number` | Allows you to specify a maximum length for the subpart of the value to be indexed.

MySQL only. In preview in versions 3.5.0 and later, and in general availability in versions 4.0.0 and later. | -| `sort` | **No** | `String` | Allows you to specify in what order the entries of the index or constraint are stored in the database. The available options are `asc` and `desc`.

In preview in versions 3.5.0 and later, and in general availability in versions 4.0.0 and later. | -| `clustered` | **No** | `Boolean` | Defines whether the index is clustered or non-clustered. Defaults to `false`.

SQL Server only. In preview in versions 3.5.0 and later, and in general availability in versions 4.0.0 and later. | -| `type` | **No** | `identifier` | Allows you to specify an index access method. Defaults to `BTree`.

PostgreSQL and CockroachDB only. In preview with the `Hash` index access method in versions 3.6.0 and later, and with the `Gist`, `Gin`, `SpGist` and `Brin` methods added in 3.14.0. In general availability in versions 4.0.0 and later. | -| `ops` | **No** | `identifier` or a `function` | Allows you to define the index operators for certain index types.

PostgreSQL only. In preview in versions 3.14.0 and later, and in general availability in versions 4.0.0 and later. | +| `fields` | **Yes** | `FieldReference[]` | A list of field names - for example, `["firstname", "lastname"]` | +| `name` | **No** | `String` | The name that Prisma Client will expose for the argument covering all fields, e.g. `fullName` in `fullName: { firstName: "First", lastName: "Last"}` | +| `map` | **No** | `map` | The name of the index in the underlying database (Prisma generates an index name that respects identifier length limits if you do not specify a name. Prisma uses the following naming convention: `tablename.field1_field2_field3_unique`) | +| `length` | **No** | `number` | Allows you to specify a maximum length for the subpart of the value to be indexed. MySQL only. | +| `sort` | **No** | `String` | Allows you to specify in what order the entries of the index or constraint are stored in the database. The available options are `asc` and `desc`. | +| `clustered` | **No** | `Boolean` | Defines whether the index is clustered or non-clustered. Defaults to `false`. SQL Server only. | +| `type` | **No** | `identifier` | Allows you to specify an index access method. Defaults to `BTree`. PostgreSQL and CockroachDB only. | +| `ops` | **No** | `identifier` or a `function` | Allows you to define the index operators for certain index types. PostgreSQL only. | The _name_ of the `fields` argument on the `@@index` attribute can be omitted: @@ -2477,14 +2421,6 @@ The `length` and `sort` arguments are added to the relevant field names: @@index(_ fields: FieldReference[], map: String?) ``` -> **Note**: Until version 3.0.0, the signature was: -> -> ```prisma no-lines -> @@index(_ fields: FieldReference[], name: String?) -> ``` -> -> The old `name` argument will still be accepted to avoid a breaking change. - #### Examples Assume you want to add an index for the `title` field of the `Post` model @@ -2591,12 +2527,6 @@ With SQLite, the signature changes to: @relation(_ name: String?, fields: FieldReference[]?, references: FieldReference[]?, onDelete: ReferentialAction?, onUpdate: ReferentialAction?) ``` -> **Note**: Until version 3.0.0, the signature was: -> -> ```prisma no-lines -> @relation(_ name: String?, fields: FieldReference[]?, references: FieldReference[]?) -> ``` - #### Examples See: [The `@relation` attribute](/orm/prisma-schema/data-model/relations#the-relation-attribute). @@ -3402,7 +3332,7 @@ model User { -**Note**: [`gen_random_uuid()` is a PostgreSQL function](https://www.postgresql.org/docs/13/functions-uuid.html). To use it in PostgreSQL versions 12.13 and earlier, you must enable the `pgcrypto` extension.

In Prisma ORM versions 4.5.0 and later, you can declare the `pgcrypto` extension in your Prisma schema with the [`postgresqlExtensions` preview feature](/orm/prisma-schema/postgresql-extensions). +**Note**: [`gen_random_uuid()` is a PostgreSQL function](https://www.postgresql.org/docs/13/functions-uuid.html). To use it in PostgreSQL versions 12.13 and earlier, you must enable the `pgcrypto` extension. @@ -3516,17 +3446,11 @@ model User { ## `type` - +:::warning Composite types are available **for MongoDB only**. - - - - -Composite types are available in versions 3.12.0 and later, and in versions 3.10.0 and later if you enable the `mongodb` Preview feature flag. - - +::: Defines a [composite type](/orm/prisma-schema/data-model/models#defining-composite-types) . diff --git a/content/200-orm/500-reference/200-prisma-cli-reference.mdx b/content/200-orm/500-reference/200-prisma-cli-reference.mdx index c0a451f071..c8dcd6651e 100644 --- a/content/200-orm/500-reference/200-prisma-cli-reference.mdx +++ b/content/200-orm/500-reference/200-prisma-cli-reference.mdx @@ -642,7 +642,6 @@ For hiding messages For downloading engines - PRISMA_ENGINES_MIRROR: - - PRISMA_BINARIES_MIRROR (deprecated): - PRISMA_ENGINES_CHECKSUM_IGNORE_MISSING: - BINARY_DOWNLOAD_VERSION: @@ -905,8 +904,6 @@ prisma db push --schema=/tmp/schema.prisma ### `db seed` -`db seed` changed from Preview to Generally Available (GA) in 3.0.1. - See [Seeding your database](/orm/prisma-migrate/workflows/seeding) #### Options @@ -916,8 +913,6 @@ See [Seeding your database](/orm/prisma-migrate/workflows/seeding) | `--help` / `--h` | No | Displays the help message | | `--` | No | Allows the use of custom arguments defined in a seed file | -The `--` argument/ [delimiter](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_02)/ double-dash is available from version 4.15.0 or later. - #### Examples ```terminal @@ -926,12 +921,6 @@ prisma db seed ### `db execute` - - -The `db execute` command is Generally Available in versions 3.13.0 and later. If you're using a version between 3.9.0 and 3.13.0, it is available behind a `--preview-feature` CLI flag. - - - This command is currently not supported on [MongoDB](/orm/overview/databases/mongodb). @@ -1204,7 +1193,7 @@ The migrations from the database are not found locally in prisma/migrations: 20201208100950_new_migration ``` -In versions 4.3.0 and later, `prisma migrate status` exits with exit code 1 in the following cases: +`prisma migrate status` exits with exit code 1 in the following cases: - a database connection error occurs - there are migration files in the `migrations` directory that have not been applied to the database @@ -1452,8 +1441,6 @@ The path to the desired `schema.prisma` file can be specified with the `prisma.s } ``` -This is available from version 2.7.0 and later. - ### `seed` The command used to populate the datasource is specified in the `prisma.seed` entry in the `package.json` file. It is used when `prisma db seed` is invoked or triggered. @@ -1470,8 +1457,6 @@ See [Seeding your database](/orm/prisma-migrate/workflows/seeding) } ``` -This is available from version 3.0.1 and later. - ## Using a HTTP proxy for the CLI Prisma CLI supports [custom HTTP proxies](https://github.com/prisma/prisma/issues/506). This is particularly relevant when being behind a corporate firewall. diff --git a/content/200-orm/500-reference/250-error-reference.mdx b/content/200-orm/500-reference/250-error-reference.mdx index dcc7673a7b..f5f64f210f 100644 --- a/content/200-orm/500-reference/250-error-reference.mdx +++ b/content/200-orm/500-reference/250-error-reference.mdx @@ -120,8 +120,6 @@ Prisma Client throws a `PrismaClientValidationError` exception if validation fai #### `P1012` -**Note:** If you get error code P1012 after you upgrade Prisma ORM to version 4.0.0 or later, see the [version 4.0.0 upgrade guide](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-4#upgrade-your-prisma-schema). A schema that was valid before version 4.0.0 might be invalid in version 4.0.0 and later. The upgrade guide explains how to update your schema to make it valid. - "\{full_error}" Possible P1012 error messages: diff --git a/content/200-orm/500-reference/300-environment-variables-reference.mdx b/content/200-orm/500-reference/300-environment-variables-reference.mdx index 407c6bf4fe..a4863ee6ab 100644 --- a/content/200-orm/500-reference/300-environment-variables-reference.mdx +++ b/content/200-orm/500-reference/300-environment-variables-reference.mdx @@ -157,16 +157,8 @@ PRISMA_ENGINES_MIRROR=https://example.org/custom-engines/ See [Prisma engines](/orm/more/under-the-hood/engines#hosting-engines) for a conceptual overview of how to use this environment variable. -Note: This environment variable used to be available as `PRISMA_BINARIES_MIRROR`, which was deprecated in Prisma ORM 3.0.1. It is discouraged to use anymore and will be removed in the future. - #### `PRISMA_ENGINES_CHECKSUM_IGNORE_MISSING` - - -This environment variable is available since version `4.16.0` - - - `PRISMA_ENGINES_CHECKSUM_IGNORE_MISSING` can be can be set to a truthy value to ignore problems around downloading & verifying the integrity (via a checksum file) of the Prisma ORM engines. This is particularly useful when deploying to an offline system environment where the checksum file cannot be downloaded. @@ -230,40 +222,6 @@ PRISMA_SCHEMA_ENGINE_BINARY=custom/my-schema-engine-unix PRISMA_MIGRATION_ENGINE_BINARY=custom/my-migration-engine-unix ``` -#### `PRISMA_INTROSPECTION_ENGINE_BINARY` - -`PRISMA_INTROSPECTION_ENGINE_BINARY` is used to set a custom location for your own introspection engine binary. - -```env -PRISMA_INTROSPECTION_ENGINE_BINARY=custom/my-introspection-engine-unix -``` - - - -The Introspection Engine is served by the Migration Engine from [4.9.0](https://github.com/prisma/prisma/releases/tag/4.9.0). Therefore, the `PRISMA_INTROSPECTION_ENGINE` environment variable will not be used. - - - -#### `PRISMA_FMT_BINARY` - - - -This functionality has been removed in Prisma CLI version 4.10.0. It only works in earlier versions. - - - -`PRISMA_FMT_BINARY` is used to set a custom location for your own format engine binary. - -```env -PRISMA_FMT_BINARY=custom/my-custom-format-engine-unix -``` - - - -The `PRISMA_FMT_BINARY` variable is used in versions [4.2.0](https://github.com/prisma/prisma/releases/tag/4.2.0) or lower. - - - ### CLI Binary Targets #### `PRISMA_CLI_BINARY_TARGETS` diff --git a/content/200-orm/800-more/100-under-the-hood/100-engines.mdx b/content/200-orm/800-more/100-under-the-hood/100-engines.mdx index dcf39716e6..da6ecf76cc 100644 --- a/content/200-orm/800-more/100-under-the-hood/100-engines.mdx +++ b/content/200-orm/800-more/100-under-the-hood/100-engines.mdx @@ -42,13 +42,10 @@ Use the following environment variables to specify custom locations for your bin - [`PRISMA_QUERY_ENGINE_BINARY`](/orm/reference/environment-variables-reference#prisma_query_engine_binary) (Query engine, binary) - [`PRISMA_SCHEMA_ENGINE_BINARY`](/orm/reference/environment-variables-reference#prisma_schema_engine_binary) (Schema engine) - [`PRISMA_MIGRATION_ENGINE_BINARY`](/orm/reference/environment-variables-reference#prisma_migration_engine_binary) (Migration engine) -- [`PRISMA_INTROSPECTION_ENGINE_BINARY`](/orm/reference/environment-variables-reference#prisma_introspection_engine_binary) (Introspection engine) -- `PRISMA_MIGRATION_ENGINE_BINARY` variable is deprecated in [5.0.0](https://github.com/prisma/prisma/releases/tag/5.0.0). -- The Introspection Engine is served by the Migration Engine from [4.9.0](https://github.com/prisma/prisma/releases/tag/4.9.0). Therefore, the `PRISMA_INTROSPECTION_ENGINE` environment variable will not be used. -- The `PRISMA_FMT_BINARY` variable is used in versions [4.2.0](https://github.com/prisma/prisma/releases/tag/4.2.0) or lower. +The `PRISMA_MIGRATION_ENGINE_BINARY` variable is deprecated in [5.0.0](https://github.com/prisma/prisma/releases/tag/5.0.0). diff --git a/content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/700-upgrading-to-prisma-4.mdx b/content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/700-upgrading-to-prisma-4.mdx deleted file mode 100644 index ff95e20ff9..0000000000 --- a/content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/700-upgrading-to-prisma-4.mdx +++ /dev/null @@ -1,495 +0,0 @@ ---- -title: 'Upgrade to Prisma ORM 4' -metaTitle: 'Upgrade to Prisma ORM 4' -metaDescription: 'Guides on how to upgrade to Prisma ORM 4' -tocDepth: 3 -toc: true ---- - - - -Prisma ORM 4 introduces a number of **breaking changes** when you upgrade from an earlier Prisma ORM version. This guide explains how this upgrade might affect your application and gives instructions on how to handle any changes. - - - -## Breaking changes - -This section gives an overview of breaking changes in Prisma ORM 4, grouped under [general changes](#general-changes) that affect both the Prisma Schema and Prisma Client, [Schema changes](#schema-changes) and [Client changes](#client-changes). - -We recommend that you first address any Prisma schema validation errors, then pull your database to reflect new Prisma schema capabilities, and finally fix any type errors in Prisma Client and validate by running your test suite. - -### Upgrade your Prisma Schema - -1. Carefully skim the list of changes and check if you are impacted by a breaking change. -2. Review the Prisma schema validation errors (via `npx prisma validate`, or via the Prisma VS Code extension). - 1. If you don't have validation errors, continue with step 3. - 2. If you have validation errors: - 1. Try to map the validation error to a change from the list below to understand which change caused the invalid Prisma schema, and read the linked instructions for how to upgrade. It can only come from: - - [Explicit unique constraints for 1:1 relations](#explicit-unique-constraints-on-one-to-one-relations) - - [Removed support for usage of `references` on implicit many-to-many relations](#disallow-references-syntax-for-implicit-many-to-many-relations) - - [Enforced uniqueness of referenced fields in the `references` argument in one-to-one and one-to-many relations for MySQL and MongoDB](#enforced-use-of-unique-or-id-attribute-for-one-to-one-and-one-to-many-relations-mysql-and-mongodb) - - Removal of undocumented support for the `type` alias - - Removal of the `sqlite` protocol for SQLite URLs - - [Better grammar for string literals](#better-grammar-for-string-literals) -3. Repeat until your Prisma schema is valid. -4. Run `npx prisma db pull` to upgrade the Prisma schema to all new capabilities (e.g. `extendedIndexes`). -5. Review changes of the Prisma schema and verify validity. -6. Continue with Prisma Client steps. - -### Upgrade your use of Prisma Client - -1. Carefully skim the [list of changes](#client-changes) to understand if you are impacted by a breaking change. - 1. If yes, read the detailed upgrade instructions. - 2. If no, proceed with 2. -2. Some API changes in Prisma Client are impacting runtime behavior, so please run your test suite. - -Enjoy Prisma ORM 4! - -### General changes - -This section includes changes that affect both the Prisma Schema and Prisma Client. - -#### Node.js minimum version change - -From Prisma ORM version 4.0.0, the minimum version of Node.js that we support is 14.17.x. If you use an earlier version of Node.js, you will need to update it. - -See our [system requirements](/orm/reference/system-requirements) for all minimum version requirements. - -### Schema changes - -This section includes changes that affect the Prisma Schema. - -#### Index configuration - -In Prisma ORM 4, the `extendedIndexes` Preview feature will now become generally available. This includes the following index configuration options: - -- Length configuration of indexes, unique constraints and primary key constraints for MySQL (in Preview in versions 3.5.0 and later) -- Sort order configuration of indexes, unique constraints and primary key constraints (in Preview in versions 3.5.0 and later) -- New index types for PostgreSQL: Hash (in Preview in versions 3.6.0 and later) and GIN, GiST, SP-GiST and BRIN (in Preview in versions 3.14.0 and later) -- Index clustering for SQL Server (in Preview in versions 3.13.0 and later) - -See our documentation on [Index configuration](/orm/prisma-schema/data-model/indexes#index-configuration) for more details of these features. - -##### Upgrade path - -These can all be breaking changes if you were previously configuring these properties at the database level. In this case, you will need to: - -1. Upgrade to the new Prisma ORM 4 packages following [these instructions](#upgrade-the-prisma-and-prismaclient-packages-to-version-4) -1. Run `npx prisma db pull` afterwards to retrieve any existing configuration of indexes and constraints. This needs to be done before running any `npx prisma db push` or `npx prisma migrate dev` command, or you may lose any configuration that was defined in the database but not previously represented in the Prisma schema. - -For more details, see the [Upgrading from previous versions](/orm/prisma-schema/data-model/indexes#upgrading-from-previous-versions) section of our index configuration documentation. - -#### Scalar list defaults - -For database connectors that support scalar lists (PostgreSQL, CockroachDB and MongoDB), Prisma ORM 4 introduces the ability to set a default value in your Prisma schema with the `@default` attribute: - - - - -```prisma highlight=4;normal -model User { - id Int @id @default(autoincrement()) - posts Post[] - //highlight-next-line - favoriteColors String[] @default(["red", "yellow", "purple"]) -} -``` - - - - -```prisma highlight=4;normal -model User { - id String @id @default(auto()) @map("_id") @db.ObjectId - posts Post[] - //highlight-next-line - favoriteColors String[] @default(["red", "yellow", "purple"]) -} -``` - - - - -##### Upgrade path - -This is a breaking change if you previously had defaults defined for scalar lists at the database level. In this case, you will need to: - -1. Upgrade to the new Prisma ORM 4 packages following [these instructions](#upgrade-the-prisma-and-prismaclient-packages-to-version-4) -1. Run `npx prisma db pull` afterwards to retrieve any existing configuration of indexes and constraints. This needs to be done before running any `npx prisma db push` or `npx prisma migrate dev` command, or you will lose any defaults that are defined in the database but not previously represented in the Prisma schema. - -#### Explicit `@unique` constraints on one-to-one relations - -When using one-to-one relations in Prisma ORM 4, you will need to explicitly add the `@unique` attribute to the relation scalar field. For example, for this one-to-one relation between a `User` and a `Profile` model, you will need to add the `@unique` attribute to the `profileId` field: - - - - -```prisma -model User { - id Int @id @default(autoincrement()) - profile Profile? @relation(fields: [profileId], references: [id]) - profileId Int? @unique // <-- include this explicitly -} - -model Profile { - id Int @id @default(autoincrement()) - user User? -} -``` - - - - -```prisma -model User { - id String @id @default(auto()) @map("_id") @db.ObjectId - profile Profile? @relation(fields: [profileId], references: [id]) - profileId String? @unique @db.ObjectId // <-- include this explicitly -} - -model Profile { - id String @id @default(auto()) @map("_id") @db.ObjectId - user User? -} -``` - - - - -##### Upgrade path - -After you upgrade to Prisma ORM 4, any one-to-one relations without a `@unique` attribute on the relation scalar will trigger a validation error. To upgrade, you will need to: - -1. Upgrade to the new Prisma ORM 4 packages following [these instructions](#upgrade-the-prisma-and-prismaclient-packages-to-version-4) - -1. Manually fix the validation errors in your Prisma schema by adding the explicit `@unique` or `@id` attribute to your data model. -1. Push the changes to your database using `prisma db push` for MongoDB or `prisma migrate dev` for MySQL. - -#### Enforced use of `@unique` or `@id` attribute for one-to-one and one-to-many relations (MySQL and MongoDB) - -When you use one-to-one and one-to-many relations in Prisma ORM 4, you will need to use a `@unique` attribute on the relation field to guarantee that the singular side(s) of the relation has only one record. This is now enforced for MySQL and MongoDB, bringing them into line with other connectors. Missing `@unique` attributes will now trigger a validation error. - -In the following example of a _one-to-many relation_ between a `User` and `Post` model, the `@unique` attribute must be added to the `email` field: - - - - -```prisma -model User { - id Int @id @default(autoincrement()) - email String @unique // <-- we enforce this attribute - posts Post[] -} - -model Post { - id Int @id @default(autoincrement()) - authorEmail String - author User @relation(fields: [authorEmail], references: [email]) -} -``` - - - - -```prisma -model User { - id Int @id @default(auto()) @map("_id") @db.ObjectId - email String @unique // <-- we enforce this attribute - posts Post[] -} - -model Post { - id Int @id @default(auto()) @map("_id") @db.ObjectId - authorEmail String - author User @relation(fields: [authorEmail], references: [email]) -} -``` - - - - -In the following example of a _one-to-one relation_ between a `User` and `Profile` model, the `@unique` attribute must be added to the `email` field: - - - - -```prisma -model User { - id Int @id @default(autoincrement()) - email String @unique // <- we enforce this unique attribute - profile Profile @relation(fields: [profileId], references: [id]) - profileId Int -} - -model Profile { - id Int @id @default(autoincrement()) - userEmail String? @unique - user User? -} -``` - - - - -```prisma -model User { - id Int @id @default(auto()) @map("_id") @db.ObjectId - email String @unique // <- we enforce this unique attribute - profile Profile @relation(fields: [profileId], references: [id]) - profileId Int @db.ObjectId -} - -model Profile { - id Int @id @default(auto()) @map("_id") @db.ObjectId - userEmail String? @unique - user User? @relation(fields: [userEmail], references: [email]) -} -``` - - - - -##### Upgrade path - -After you upgrade to Prisma ORM 4, any one-to-one or one-to-many relations without a `@unique` or `@id` attribute on the relation field will trigger a validation error. To upgrade, you will need to: - -1. Upgrade to the new Prisma ORM 4 packages following [these instructions](#upgrade-the-prisma-and-prismaclient-packages-to-version-4) -1. Manually fix the validation errors in your Prisma schema. Alternatively, if you have an up-to-date live database, running `npx prisma db pull` will add the `@unique` attributes automatically. - -#### Disallow `references` syntax for implicit many-to-many relations - -When using [implicit many-to-many relations](/orm/prisma-schema/data-model/relations/many-to-many-relations#implicit-many-to-many-relations) in Prisma ORM 4, you will no longer be able to use the `references` argument, which was previously optional. For example, the following relation would now trigger a validation error: - -```prisma file=schema.prisma showLineNumbers -model Post { - id Int @id @default(autoincrement()) - categories Category[] @relation("my-relation", references: [id]) // <-- validation error -} - -model Category { - id Int @id @default(autoincrement()) - posts Post[] @relation("my-relation", references: [id]) // <-- validation error -} -``` - -Instead, you can write: - -```prisma file=schema.prisma showLineNumbers -model Post { - id Int @id @default(autoincrement()) - categories Category[] @relation("my-relation") -} - -model Category { - id Int @id @default(autoincrement()) - posts Post[] @relation("my-relation") -} -``` - -This is because the only valid value for `references` was `id`, so removing this argument makes it clearer what can and cannot be changed. - -##### Upgrade path - -After you upgrade to Prisma ORM 4, any implicit many-to-many relations with a `references` argument will trigger a validation error. To upgrade, you will need to: - -1. Upgrade to the new Prisma ORM 4 packages following [these instructions](#upgrade-the-prisma-and-prismaclient-packages-to-version-4) -1. Manually fix the validation errors in your Prisma schema. Alternatively, if you have an up-to-date live database, running `npx prisma db pull` will remove the `references` arguments automatically. - -#### Better grammar for string literals - -String literals in your Prisma Schema now need to follow the same rules as strings in JSON. This mostly changes the escaping of some special characters. More details can be found in [the JSON specification](https://www.ietf.org/rfc/rfc4627.txt) or on the [JSON website](https://www.json.org/json-en.html). - -##### Upgrade path - -This is a breaking change for some existing schemas. After you upgrade to Prisma ORM 4, incorrectly escaped characters will trigger a validation error. To upgrade, you will need to: - -1. Upgrade to the new Prisma ORM 4 packages following [these instructions](#upgrade-the-prisma-and-prismaclient-packages-to-version-4) -1. Manually fix the validation errors in your Prisma schema. - -### Client changes - -This section includes changes that affect Prisma Client. - -#### Raw query type mapping: scalar values are now deserialized as their correct JavaScript types - -In versions 3.14.x and 3.15.x, [raw query type mapping](/orm/prisma-client/using-raw-sql/raw-queries#raw-query-type-mapping) was available with the Preview feature `improvedQueryRaw`. In version 4.0.0, we have made raw query type mapping Generally Available. You do not need to use `improvedQueryRaw` to get this functionality in versions 4.0.0 and later. - -Raw queries now deserialize scalar values to their corresponding JavaScript types. Note that Prisma ORM infers types from the values themselves and not from the Prisma Schema types. - -Example query and response: - -```ts -const res = - await prisma.$queryRaw`SELECT bigint, bytes, decimal, date FROM "Table";` -console.log(res) // [{ bigint: BigInt("123"), bytes: Buffer.from([1, 2]), decimal: new Prisma.Decimal("12.34"), date: Date("") }] -``` - -##### Upgrade path - -From version 4.0.0, some data types returned by `queryRaw` or `queryRawUnsafe` are different, as follows: - -| Data type | Before version 4.0.0 | From version 4.0.0 | -| ---------- | --------------------- | --------------------- | -| `DateTime` | Returned as `String` | Returned as `Date` | -| `Numeric` | Returned as `Float` | Returned as `Decimal` | -| `Bytes` | Returned as `String` | Returned as `Buffer` | -| `Int64` | Returned as `Integer` | Returned as `BigInt` | - -If you use `queryRaw` or `queryRawUnsafe` to return any of the above data types, then you must change your code to handle the new types. - -For example, if you return `DateTime` data, then you need to take into account the following: - -- You no longer need to manually instantiate a `DateTime` object for the returned data. -- If your code currently uses the returned `String` data, then you now need to convert the `DateTime` object to a `String`. - -You must make equivalent code changes for the other data types in the table above. - -#### Raw query mapping: PostgreSQL type-casts - -In versions 3.14.x and 3.15.x, [raw query type mapping](/orm/prisma-client/using-raw-sql/raw-queries#raw-query-type-mapping) was available with the Preview feature `improvedQueryRaw`. In version 4.0.0, we have made raw query type mapping Generally Available. You do not need to use `improvedQueryRaw` to get this functionality in versions 4.0.0 and later. - -Before version 4.0.0, many PostgreSQL type-casts did not work. We have tightened the type coercion rules so that all type-casts now work. As a result, some implicit casts now fail. - -##### Upgrade path - -We recommend that you re-test your use of `$queryRaw` to ensure that the types you pass into your raw queries match the types that PostgreSQL expects. - -For example, in version 4.0.0, the following query fails: - -```js -await prisma.$queryRaw`select length(${42});` -// ERROR: function length(integer) does not exist -// HINT: No function matches the given name and argument types. You might need to add explicit type casts. -``` - -This is because PostgreSQL’s `length` function expects `text` as input. Prisma ORM used to silently coerce `42` to `text`, but does not do this in version 4.0.0. To fix this, explicitly cast `42` to `text` as follows: - -```js -await prisma.$queryRaw`select length(${42}::text);` -``` - -#### Raw query mapping: PostgreSQL and JavaScript integers - -In versions 3.14.x and 3.15.x, [raw query type mapping](/orm/prisma-client/using-raw-sql/raw-queries#raw-query-type-mapping) was available with the Preview feature `improvedQueryRaw`. In version 4.0.0, we have made raw query type mapping Generally Available. You do not need to use `improvedQueryRaw` to get this functionality in versions 4.0.0 and later. - -Prisma ORM sends JavaScript integers to PostgreSQL as `INT8`. This might conflict with your user-defined functions that accept only `INT4` as input. - -##### Upgrade path - -If you use `$queryRaw` or parametrized `$queryRawUnsafe`queries with a PostgreSQL database, do one of the following: - -- Update the input types of any integers in your user-defined functions to `INT8`, or -- Cast any integers in your query parameters to `INT4`. - -#### `DbNull`, `JsonNull` and `AnyNull` are now objects - -JavaScript `null` is ambiguous for JSON columns, so Prisma ORM uses `DbNull`, `JsonNull`, and `AnyNull` to distinguish between the database `NULL` value and the JSON `null` value. Before version 4.0.0, `DbNull`, `JsonNull`, and `AnyNull` were string constants. From version 4.0.0, they are objects. - -See [Filtering by null values](/orm/prisma-client/special-fields-and-types/working-with-json-fields#filtering-by-null-values) for more information. - -##### Upgrade path - -1. If you use literal strings to address these values, then you must replace them with the following named constants: - - - `DbNull`: replace with `Prisma.DbNull` - - `JsonNull`: replace with `Prisma.JsonNull` - - `AnyNull`: replace with `Prisma.AnyNull` - - If you already use these named constants, then you do not need to take any action. - -1. If you now get a type error when you pass `Prisma.DbNull` as the value of a JSON field, then this probably indicates a bug in your code that our types did not catch before version 4.0.0. The field where you tried to store `DbNull` is probably not nullable in your schema. As a result, a literal `DbNull` string was stored in the database instead of `NULL`. -1. You might now encounter a type error or runtime validation error when you use `Prisma.DbNull`, `Prisma.JsonNull`, or `Prisma.AnyNull` with MongoDB. This was never valid, but was silently accepted prior to Prisma ORM 4. You need to review your data and change these fields to `null`. -1. If you pass in dynamic JSON to a JSON column in Prisma Client (for example `prisma.findMany({where: { jsonColumn: someJson } })`), then you must check that `someJson`cannot be the string "DBNull", "JsonNull", or "AnyNull". If it is any of these values, then the query will return different results in version 4.0.0. - -#### Default fields on composite types in MongoDB - -From version 4.0.0, if you carry out a database read on a composite type when all of the following conditions are true, then Prisma Client inserts the default value into the result. - -Conditions: - -- A field on the composite type is required, and -- this field has a default value, and -- this field is not present in the returned document or documents. - -This behavior is now consistent with the behavior for model fields. - -To learn more, see [Default values for required fields on composite types](/orm/prisma-client/special-fields-and-types/composite-types#default-values-for-required-fields-on-composite-types). - -##### Upgrade path - -If you currently rely on a return value of `null`, then you need to refactor your code to handle the default value that is now returned in Prisma ORM 4. - -#### Rounding errors on big numbers in SQLite - -SQLite is a loosely-typed database. If your schema has a field with type `Int`, then Prisma ORM prevents you from inserting a value larger than an integer. However, nothing prevents the database from directly accepting a bigger number. These manually-inserted big numbers cause rounding errors when queried. - -To avoid this problem, Prisma ORM version 4.0.0 and later checks numbers on the way out of the database to verify that they fit within the boundaries of an integer. If a number does not fit, then Prisma ORM throws a P2023 error, such as: - -``` -Inconsistent column data: Conversion failed: -Value 9223372036854775807 does not fit in an INT column, -try migrating the 'int' column type to BIGINT -``` - -##### Upgrade path - -If you use Prisma ORM in conjunction with SQLite, then you need to find any code that queries `Int` fields and ensure that it handles any P2023 errors that might be returned. - -#### Prisma ORM no longer exports `Prisma.dmmf.schema` into the generated Prisma Client - -From version 4.0.0, Prisma ORM no longer exports `Prisma.dmmf.schema` into the generated Prisma Client. This makes the generated Prisma Client much more efficient, and also avoids some memory leaks with Jest. - -Note: - -- This change does not affect the DMMF that Prisma ORM passes to the generators. -- You can use `getDmmf()`from `@prisma/internals` to access the schema property. -- We still export `Prisma.dmmf.datamodel` into the generated Prisma Client. - -## Upgrade the `prisma` and `@prisma/client` packages to version 4 - -To upgrade to Prisma ORM 4 from an earlier version, you need to update both the `prisma` and `@prisma/client` packages. Both the `prisma` and `@prisma/client` packages install with a caret `^` in their version number. This allows upgrades to new minor versions, but not major versions, to safeguard against breaking changes. - -To ignore the caret `^` and upgrade across major versions, you can use the `@4` tag when you upgrade with `npm`, or `yarn`: - - - -Before you upgrade, check each **breaking change** to see how the upgrade might affect your application. - - - - - - - -```terminal -npm install prisma@4 @prisma/client@4 -``` - - - - - -```terminal -yarn up prisma@4 @prisma/client@4 -``` - - - - - -## Video guide - -For a video walkthrough of the upgrade process and examples of upgrade scenarios, see our recorded livestream on upgrading to Prisma ORM 4: - -
- - - -
diff --git a/content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/800-upgrading-to-prisma-3/100-named-constraints.mdx b/content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/800-upgrading-to-prisma-3/100-named-constraints.mdx deleted file mode 100644 index 04964bbc95..0000000000 --- a/content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/800-upgrading-to-prisma-3/100-named-constraints.mdx +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: 'Named constraints upgrade path' -metaTitle: 'Named constraints upgrade path' -metaDescription: 'Guides on how to handle named constraints using Prisma Introspect or Prisma Migrate when upgrading to Prisma 3' -tocDepth: 3 -toc: true ---- - - - -After upgrading to Prisma ORM 3, the default naming convention for constraint and index names will change and your primary and foreign key names will now be part of the schema for databases that support them. Therefore the meaning of your existing Prisma schema will change. - -Before you continue to evolve your schema and your database, you should decide which names for constraints and indexes you want to use on your project going forward. - -You can either keep the names as they exist in your database or you can switch to use the names generated by Prisma ORM, which follow the new naming convention. - -This page describes the manual upgrade steps that you need to perform after upgrading to Prisma ORM 3. You can pick either of the two options: - -- **Option 1**: [I want to maintain my existing constraint and index names](#option-1-i-want-to-maintain-my-existing-constraint-and-index-names) -- **Option 2**: [I want to use Prisma ORM's default constraint and index names](#option-2-i-want-to-use-prisma-orms-default-constraint-and-index-names) - - - -## Option 1: I want to maintain my existing constraint and index names - -If you want to keep your database unchanged and keep the existing names for constraints and indexes you need to pull them into your schema so Prisma ORM is aware of them. - -Reasons to keep your existing names might be: - -- Naming conventions you have to follow -- Other tooling relying on the names -- Personal preference - -To keep existing names, run `prisma db pull` against the target environment. This will result in all names that do not match Prisma ORM's naming convention for constraint and index names being pulled into your schema as `map` arguments on their respective attributes. - -1. Example schema: - - ```prisma - model User { - id Int @id @default(autoincrement()) - name String @unique - posts Post[] - } - - model Post { - id Int @id @default(autoincrement()) - title String - authorName String @default("Anonymous") - author User? @relation(fields: [authorName], references: [name]) - } - ``` - -1. Introspect your **development database** to populate the Prisma schema with constraint and index names in your underlying database _that do not match Prisma ORM's naming convention_: - - ```terminal - npx prisma db pull - ``` - - In this example, the highlighted constraints did not conform to Prisma ORM's default naming convention and now include the `map` attribute field: - - ```prisma highlight=11;normal - model User { - id Int @id(map: "Custom_Constraint_Name") @default(autoincrement()) - name String @unique - posts Post[] - } - - model Post { - id Int @id @default(autoincrement()) - title String - authorName String @default("Anonymous") - //highlight-next-line - author User? @relation(fields: [authorName], references: [name], map: "Custom_Foreign_Key_Constraint") - } - ``` - -## Option 2: I want to use Prisma ORM's default constraint and index names - -If you want to keep your Prisma Schema clean and if you have no reasons preventing you from renaming constraints and indexes in your database, then you can create a migration to update the names. - -Run `prisma migrate dev` to create a migration updating the constraint names to Prisma ORM's defaults. - -Afterwards, do not forget to `prisma migrate deploy` against your production environment if you have one to also update the names there. The schema below has no explicit constraint or index names spelled out, so Prisma ORM will infer them. - -1. Example schema: - - ```prisma - model User { - name String @id //inferred as User_pkey - posts Post[] - } - - model Post { - id Int @id @default(autoincrement()) //inferred as Post_pkey - authorName String @default("Anonymous") - author User? @relation(fields: [authorName], references: [name]) //inferred as Post_authorName_fkey - } - ``` - -1. Run the `prisma migrate dev` command to generate a new migration: - - ```terminal - npx prisma migrate dev - ``` - - This migration renames any constraints that do not currently follow Prisma ORM's naming convention. - -1. Run the [`prisma migrate deploy`](/orm/prisma-client/deployment/deploy-database-changes-with-prisma-migrate) command to apply the migration to your production environment: - - ```terminal - npx prisma migrate deploy - ``` - -## Dealing with cases where more than one database environment is used for the same application - -### Checking whether your environments use identical names - -Since Prisma ORM did not offer a way to define constraint or index names explicitly in the past, you can face situations where your different database environments have differing constraint or index names. - -In order to detect this: - -- Create a backup of your current `schema.prisma` file. -- Run `prisma db pull` against each database environment, by saving the results to their own separate files using the `--schema` option. [See reference](/orm/reference/prisma-cli-reference#arguments-1) - -Then you can either manually inspect both files or use a `diff` tool in your IDE or in the terminal. If you see differences in constraint names, your production and local environments are out of sync and should be aligned. - -In the following example, the `Post` model has a foreign key constraint with a custom name in production that does not match development. - -#### Development environment: - -```prisma highlight=5;normal -model Post { - id Int @id @default(autoincrement()) - title String - authorName String @default("Anonymous") - //highlight-next-line - author User? @relation(fields: [authorName], references: [name], map: "Custom_Foreign_Key_Constraint") -} -``` - -#### Production environment: - -```prisma highlight=5;normal -model Post { - id Int @id @default(autoincrement()) - title String - authorName String @default("Anonymous") - //highlight-next-line - author User? @relation(fields: [authorName], references: [name], map: "Custom_Production_Name") -} -``` - -### Aligning your environments if their constraint or index names differ - -If the names in your environments differ, the safest option is to align your development environment with the names in your production environment. This makes sure that no changes need to be performed on your production database. - -In order to achieve this: - -- Run `prisma db pull` against your production environment to pull in the constraint and index names -- Switch to development and run `prisma migrate dev` to create a new migration. You can call that migration `migration-to-sync-names` -- Switch to production, and run `prisma migrate resolve --applied migration-to-sync-names` to mark the migration as applied on production - -Your migration history now contains a migration to ensure that the names of any new environments you spin up contain the same names as your production database. And Prisma ORM knows not to apply this migration to production since you already marked it as applied. - -Your environments are now in sync and you can proceed to the [upgrade paths for migrate users](#option-2-i-want-to-use-prisma-orms-default-constraint-and-index-names). These let you choose your future naming scheme. diff --git a/content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/800-upgrading-to-prisma-3/150-referential-actions.mdx b/content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/800-upgrading-to-prisma-3/150-referential-actions.mdx deleted file mode 100644 index a099b97d22..0000000000 --- a/content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/800-upgrading-to-prisma-3/150-referential-actions.mdx +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: 'Referential actions upgrade path' -metaTitle: 'Referential actions upgrade path' -metaDescription: 'Guides on how to deal with referential actions using Prisma Introspect or Prisma Migrate when upgrading to Prisma 3' -tocDepth: 4 -toc_max_heading_level: 4 -toc: true ---- - - - -Prisma ORM version 2.x prevents deletion of connected records in some Prisma Client functions, and does not let you configure referential actions in your Prisma Schema to change that behavior. - -Prisma ORM version 3.x and later lets you control what should happen when deleting or updating records by explicitly setting referential actions on your models' relations. After the upgrade, Prisma Client will not enforce any referential actions anymore, and any action written to the database foreign keys will define the behavior when deleting or updating records. - -Prisma Migrate 3.x will use the actions previously done by Prisma Client as the new default when writing the foreign key constraints to the database. - - - -## Prisma ORM 2.x behavior - -When invoking the [`delete()`](/orm/prisma-client/queries/crud#delete-a-single-record) or [`deleteAll()`](/orm/prisma-client/queries/crud#delete-all-records) methods using Prisma Client on required relations, a runtime check is performed and the deletion of records prevented if they are referencing related objects. **This prevents cascade behavior, no matter how the foreign key is defined**. - -The behavior in Prisma ORM 2, without upgrading, does not allow setting referential actions at all. [See Prisma ORM 2.x default referential actions](#prisma-orm-2x-default-referential-actions) - -If you need to actually use the cascade behavior configured in the database, you _can_ use [`raw`](/orm/prisma-client/using-raw-sql/raw-queries) SQL queries to [delete multiple referenced records](/orm/prisma-client/queries/crud#deleting-all-data-with-raw-sql--truncate). This is because Prisma Client will **not** perform runtime checks on raw queries. - -### Prisma ORM 2.x default referential actions - -Below are the default referential actions written to the database foreign keys when using Prisma Migrate versions 2.x: - -| Clause | Optional relations | Mandatory relations | -| :--------- | :----------------- | :------------------ | -| `onDelete` | `SetNull` | `Cascade` | -| `onUpdate` | `Cascade` | `Cascade` | - -On top of the database referential actions, the following actions are enforced in Prisma Client versions 2.x: - -| Clause | Optional relations | Mandatory relations | -| :--------- | :----------------- | :------------------ | -| `onDelete` | `SetNull` | `Restrict` | -| `onUpdate` | `Cascade` | `Cascade` | - -## Upgrade paths - -There are a couple of paths you can take when upgrading which will give different results depending on the desired outcome. - -If you currently use the migration workflow, you can run `prisma db pull` to check how the defaults are reflected in your schema. You can then manually update your database if you need to. - -You can also decide to skip checking the defaults and run a migration to update your database with the new default values. - -### Using Introspection - -If you [Introspect](/orm/prisma-schema/introspection) your database, the referential actions configured at the database level will be reflected in your Prisma Schema. If you have been using Prisma Migrate or `prisma db push` to manage the database schema, these are likely to be the [\<=2.25.0 default values](#prisma-orm-2x-default-referential-actions). - -When you run an Introspection, Prisma ORM compares all the foreign keys in the database with the schema, if the SQL statements `ON DELETE` and `ON UPDATE` do **not** match the default values, they will be explicitly set in the schema file. - -After introspecting, you can review the non-default clauses in your schema. The most important clause to review is `onDelete`, which defaults to `Cascade` in version 2.25.0 and earlier. - - - -If you are using either the [`delete()`](/orm/prisma-client/queries/crud#delete-a-single-record) or [`deleteAll()`](/orm/prisma-client/queries/crud#delete-all-records) methods, **cascading deletes will now be performed, as the safety net in Prisma Client that previously prevented cascading deletes at runtime is removed**. Be sure to check your code and make any adjustments accordingly. - - - -Make sure you are happy with every case of `onDelete: Cascade` in your schema. If not, either: - -- Modify your Prisma schema and `db push` or `dev migrate` to change the database _or_ -- Manually update the underlying database if you only use `prisma db pull` in your workflow - -The following example would result in a cascading delete, meaning that if the `User` is deleted then all of their `Post`'s will be deleted too. - -#### A blog schema example - -```prisma highlight=4;add -model Post { - id Int @id @default(autoincrement()) - title String - //add-next-line - author User @relation(fields: [authorId], references: [id], onDelete: Cascade) - authorId Int -} - -model User { - id Int @id @default(autoincrement()) - posts Post[] -} -``` - -### Using Migration - -When running a [Migration](/orm/prisma-migrate) (or the [`prisma db push`](/orm/prisma-migrate/workflows/prototyping-your-schema) command) the [new defaults](/orm/prisma-schema/data-model/relations/referential-actions#referential-action-defaults) will be applied to your database. - - - -Unlike when you run `prisma db pull` for the first time, the new referential actions clause and property will **not** automatically be added to your Prisma schema by the Prisma VSCode extension. -You will have to manually add them if you wish to use anything other than the new defaults. - - - -Explicitly defining referential actions in your Prisma schema is optional. If you do not explicitly define a referential action for a relation, Prisma ORM uses the [new defaults](/orm/prisma-schema/data-model/relations/referential-actions#referential-action-defaults). - -Note that referential actions can be added on a case by case basis. This means that you can add them to one single relation and leave the rest set to the defaults by not manually specifying anything. - -### Checking for errors - -**Before** upgrading to version 3.0.1 (or versions 2.26.0 and above with the `referentialActions` feature flag enabled), Prisma ORM prevented the deletion of records while using `delete()` or `deleteMany()` to preserve referential integrity. A custom runtime error would be thrown by Prisma Client with the error code `P2014`. - -**After** upgrading, Prisma ORM no longer performs runtime checks. You can instead specify a custom referential action to preserve the referential integrity between relations. - -When you use [`NoAction`](/orm/prisma-schema/data-model/relations/referential-actions#noaction) or [`Restrict`](/orm/prisma-schema/data-model/relations/referential-actions#restrict) to prevent the deletion of records, the error messages will be different in versions 3.0.1 and above (or 2.26.0 with the `referentialActions` feature flag enabled) compared to versions prior to that. This is because they are now triggered by the database and **not** Prisma Client. The new error code that can be expected is `P2003`, so you should check your code to make adjustments accordingly. - -#### Example of catching errors - -The following example uses the below blog schema with a 1-m relationship between `Post` and `User` and sets a [`Restrict`](/orm/prisma-schema/data-model/relations/referential-actions#restrict) referential actions on the `author` field. - -This means that if a user has a post, that user (and their posts) **cannot** be deleted. - -```prisma file=schema.prisma showLineNumbers -model Post { - id Int @id @default(autoincrement()) - title String - author User @relation(fields: [authorId], references: [id], onDelete: Restrict) - authorId String -} - -model User { - id Int @id @default(autoincrement()) - posts Post[] -} -``` - -Prior to upgrading, the error code you would receive when trying to delete a user which has posts would be `P2014` and it's message: - -> "The change you are trying to make would violate the required relation '\{relation_name}' between the \{model_a_name} and \{model_b_name} models." - -```ts -import { PrismaClient } from '@prisma/client' - -const prisma = new PrismaClient() - -async function main() { - try { - await prisma.user.delete({ - where: { - id: 'some-long-id', - }, - }) - } catch (error) { - if (error instanceof Prisma.PrismaClientKnownRequestError) { - if (error.code === 'P2014') { - console.log(error.message) - } - } - } -} - -main() - .then(async () => { - await prisma.$disconnect() - }) - .catch(async (e) => { - console.error(e) - await prisma.$disconnect() - process.exit(1) - }) -``` - -To make sure you are checking for the correct errors in your code, modify your check to look for `P2003`, which will deliver the message: - -> "Foreign key constraint failed on the field: \{field_name}" - -```ts highlight=14;delete|15;add -import { PrismaClient } from '@prisma/client' - -const prisma = new PrismaClient() - -async function main() { - try { - await prisma.user.delete({ - where: { - id: 'some-long-id' - } - }) - } catch (error) { - if (error instanceof Prisma.PrismaClientKnownRequestError) { - //delete-next-line - if (error.code === 'P2014') { - //add-next-line - if (error.code === 'P2003') { - console.log(error.message) - } - } - } -} - -main() - .then(async () => { - await prisma.$disconnect() - }) - .catch(async (e) => { - console.error(e) - await prisma.$disconnect() - process.exit(1) - }) -``` diff --git a/content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/800-upgrading-to-prisma-3/index.mdx b/content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/800-upgrading-to-prisma-3/index.mdx deleted file mode 100644 index 2180704600..0000000000 --- a/content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/800-upgrading-to-prisma-3/index.mdx +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: 'Upgrade to Prisma ORM 3' -metaTitle: 'Upgrade to Prisma ORM 3' -metaDescription: 'Guides on how to upgrade to Prisma ORM 3' -tocDepth: 3 -toc: true ---- - - - -Prisma ORM 3 introduces a number of **breaking changes** if you are upgrading from an earlier version (any 2.x version), therefore, it is important to understand how this upgrade might affect your application and make any needed adjustments to ensure a smooth transition. - -Below you will find a list of the breaking changes and how to handle them. - - - -## Breaking changes - -### [Referential actions](/orm/prisma-schema/data-model/relations/referential-actions) - -The introduction of referential actions in version 3.x removes the safety net in Prisma Client that had previously prevented cascading deletes at runtime. - -As a result, depending on which workflow you are using to work on your application, you could be impacted. We advise you to check your schema and decide if you need to define referential actions explicitly. - -See [Referential action upgrade path](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-3/referential-actions) to understand how to proceed. - -### [Named constraints](/orm/prisma-schema/data-model/database-mapping) - -We changed the convention followed by Prisma ORM to name constraints and indexes. We also introduced a clear distinction between the `map` attribute (database-level name) and `name` attribute (Prisma Client API name) in the PSL to explicitly control how constraints are defined in the Prisma schema. - -This means that you will notice an impact when running Prisma `migrate` or `db pull` which will follow this new convention. We advise you to adjust your schema to reflect the names of your constraints and indexes appropriately. - -You can check out the [Named constraints upgrade path](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-3/named-constraints) for more information on how to proceed. - -### [$queryRaw](/orm/prisma-client/using-raw-sql/raw-queries) - -From version 3.x onwards, the `$queryRaw` method now only supports a template literal. - -This means that if your application relied on `$queryRaw` calls using _strings_, those calls will **not** work anymore. We advise you to use template literals wherever possible for security reasons or resort to `$queryRawUnsafe` otherwise, after carefully escaping queries to prevent SQL injections. - -You can learn more about the new `$queryRaw` and `$queryRawUnsafe` methods in the [Raw database access](/orm/prisma-client/using-raw-sql/raw-queries) section of the docs. - -### [Json Null Equality](/orm/prisma-client/special-fields-and-types/working-with-json-fields#filtering-by-null-values) - -You cannot filter a `Json` field by a null value. [See this GitHub issue](https://github.com/prisma/prisma/issues/8399). -This is because `{ equals: null }` checks if the column value in the database is `NULL`, not if the JSON value inside the column equals `null`. - -To fix this problem, we decided to split null on Json fields into `JsonNull`, `DbNull` and `AnyNull`. - -- **JsonNull**: Selects the null value in JSON. -- **DbNull**: Selects the NULL value in the database. -- **AnyNull:** Selects both null JSON values and NULL database values. - -Given the following model in your Prisma Schema: - -```ts -model Log { - id Int @id - meta Json -} -``` - -Starting in 3.0.1, you'll see a TypeError if you try to filter by null on a `Json` field: - -```ts -prisma.log.findMany({ - where: { - data: { - meta: { - equals: null - ^ TypeError: Type 'null' is not assignable to type - } - }, - }, -}); -``` - -To fix this, you'll import and use one of the new null types: - -```ts highlight=7;normal -import { Prisma } from '@prisma/client' - -prisma.log.findMany({ - where: { - data: { - meta: { - equals: Prisma.AnyNull, - }, - }, - }, -}) -``` - -This also applies to `create`, `update` and `upsert`. To insert a `null` value -into a `Json` field, you would write: - -```ts highlight=5;normal -import { Prisma } from '@prisma/client' - -prisma.log.create({ - data: { - meta: Prisma.JsonNull, - }, -}) -``` - -And to insert a database `NULL` into a Json field, you would write: - -```ts highlight=5;normal -import { Prisma } from '@prisma/client' - -prisma.log.create({ - data: { - meta: Prisma.DbNull, - }, -}) -``` - - - -This API change does not apply to the MongoDB connector where there is not a difference between a JSON null and a database NULL. - -They also do not apply to the `array_contains` operator because there can only be a JSON null within an JSON array. Since there cannot be a database NULL within a JSON array, `{ array_contains: null }` is not ambiguous. - - - -## Specific upgrade paths - - - -## Upgrading the `prisma` and `@prisma/client` packages to Prisma ORM 3 - -To upgrade from version 2.x to 3.x, you need to update both the `prisma` and `@prisma/client` packages. Both the `prisma` and `@prisma/client` packages install with a caret `^` in their version number to safe guard against breaking changes. - -To ignore the caret `^` and upgrade across major versions, you can use the `@3` tag when upgrading with `npm`, or `yarn` . - - - -Before upgrading, check each **breaking change** to see how the upgrade might affect your application. - - - - - - - -```terminal -npm install prisma@3 @prisma/client@3 -``` - - - - - -```terminal -yarn up prisma@3 @prisma/client@3 -``` - - - - \ No newline at end of file diff --git a/content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/index.mdx b/content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/index.mdx index a207ab3508..a56e19dae3 100644 --- a/content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/index.mdx +++ b/content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/index.mdx @@ -22,16 +22,8 @@ To upgrade to the latest version of Prisma ORM: ## Common upgrade paths -### Prisma ORM 2 and onwards - - [Upgrade to Prisma ORM 6](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-6) - [Upgrade to Prisma ORM 5](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-5) -- [Upgrade to Prisma ORM 4](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-4) -- [Upgrade to Prisma ORM 3](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-3) - -### Prisma 1 - -- [Upgrade from Prisma 1](/orm/more/upgrade-guides/upgrade-from-prisma-1) ## Testing new features, without upgrading @@ -45,8 +37,8 @@ To install the latest `dev` distribution tag: npm install @prisma/client@dev prisma@dev ``` - +:::danger Do not use the `dev` distribution tag in production - wait until the official release that contains the features and fixes you are interested in is released. For example, fixes present `@prisma/client@2.23.0-dev.25` will eventually be released as part of `@prisma/client@2.23.0`. - +::: diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/01-how-to-upgrade.mdx b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/01-how-to-upgrade.mdx deleted file mode 100644 index 463a1f141b..0000000000 --- a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/01-how-to-upgrade.mdx +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: 'How to upgrade' -metaTitle: 'How to upgrade from Prisma 1 to Prisma ORM version 2.x and later' -metaDescription: 'Learn how to upgrade your Prisma 1 project to Prisma ORM version 2.x and later' ---- - -## Overview - -This page helps you make an informed decision on when and how to upgrade from Prisma 1 to Prisma ORM version 2._x_ and later. - -## Upgrade documentation - -The upgrade documentation consists of several pages, here's an overview of how to use them: - -- **How to upgrade** (_you are here_): Starting point to learn about the upgrade process in general. -- [Schema incompatibilities](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-postgresql): A _reference_ page about the schema incompatibilities between Prisma 1 and Prisma ORM 2._x_ (and later versions). Reading this page is optional but it will give you a better understanding of certain steps in the upgrade process. - -In addition to these two pages, there are various _practical guides_ that walk you through an example scenario of the upgrade process: - -- [Upgrading the Prisma layer](/orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-the-prisma-layer-postgresql): No matter what your Prisma 1 setup looks like, you should **always start your upgrade process by following this guide**. - -Once you're done with that guide, you can choose **one of the following four guides to upgrade your application layer**: - -- [Old to new Nexus](/orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-nexus-prisma-to-nexus): Choose this guide if you're currently running Prisma 1 with GraphQL Nexus. -- [prisma-binding to Nexus](/orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-prisma-binding-to-nexus): Choose this guide if you're currently running Prisma 1 with `prisma-binding` and want to upgrade to [Nexus](https://nexusjs.org/). -- [prisma-binding to SDL-first](/orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-prisma-binding-to-sdl-first): Choose this guide if you're currently running Prisma 1 with `prisma-binding` and want to upgrade to an [SDL-first](https://www.prisma.io/blog/the-problems-of-schema-first-graphql-development-x1mn4cb0tyl3) GraphQL server. -- [REST API](/orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-a-rest-api): Choose this guide if you're currently running Prisma 1 using Prisma Client 1 and are building a REST API. - -## Main differences between Prisma 1 and Prisma ORM version 2._x_ and later - -On a high-level, the biggest differences between Prisma 1 and Prisma ORM versions 2._x_ and later are summarized below. - -Prisma ORM 2._x_ and later versions: - -- don't require hosting a database proxy server (i.e., the [Prisma server](https://v1.prisma.io/docs/1.34/prisma-server/)). -- make the features of Prisma 1 more modular and splits them into dedicated tools: - - Prisma Client: An improved version of Prisma Client 1.0 - - Prisma Migrate: Data modeling and migrations (formerly `prisma deploy`). -- use the [Prisma schema](/orm/prisma-schema), a merge of Prisma 1 datamodel and `prisma.yml`. -- use its own [modeling language](https://github.com/prisma/specs/tree/master/schema) instead of being based on GraphQL SDL. -- don't expose ["a GraphQL API for your database"](https://www.prisma.io/blog/prisma-and-graphql-mfl5y2r7t49c) anymore, but only allows for _programmatic access_ via the Prisma Client API. - - don't support Prisma ORM binding any more. -- allows connecting Prisma ORM 2._x_ and later version to any existing database, via more powerful introspection - -## Feature parity - -Prisma ORM 2._x_ and later versions do not yet have full feature parity with Prisma 1. The biggest feature that is still missing from Prisma ORM versions 2._x_ and later is real-time subscriptions. - -- **Real-time API (Subscriptions)**: Prisma ORM version 2._x_ and later currently [doesn't have a way to subscribe to events happening in the database](https://github.com/prisma/prisma/issues/298) and get notified in real time. It is currently unclear if, when, and in what form a real-time API will be added to Prisma ORM versions 2._x_ and later. For the time being, you can implement real-time functionality using native database triggers, or if you're using GraphQL subscriptions you can consider triggering subscriptions manually inside your _mutation resolvers_. - -## Schema incompatibilities - -The database schema that is created when running `prisma deploy` in Prisma 1 is only partially compatible with the one that Prisma ORM versions 2._x_ and later creates. This section gives a quick overview of the general incompatibilities and the potential workarounds. - - -> **Note**: For a detailed explanation of the problems and respective workarounds, please refer to the [Schema incompatibilities](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-postgresql) page. - -Here's an overview of the different columns: - -- **Problem**: A short description of the problem when upgrading from Prisma 1 to Prisma ORM versions 2._x_ and later -- **SQL**: Can this be solved by making a non-breaking change to the SQL schema? -- **Prisma schema**: Can this be solved by making a non-breaking change to the schema in Prisma ORM versions 2._x_ and later? -- **Breaking Prisma 1**: Do the SQL statements break the Prisma 1 setup? This is only relevant when you're choosing the gradual side-by-side [upgrade strategy](#upgrade-strategies). - -| Problem | SQL | Prisma schema | Breaking Prisma 1 | -| ------------------------------------------------------------------------ | ------- | ------------- | ---------------------------------- | -| Default values aren't represented in database | Yes | Yes | No | -| Generated CUIDs as ID values aren't represented in database | No | Yes | No | -| `@createdAt` isn't represented in database | Yes | Yes | No | -| `@updatedAt` isn't represented in database | No | Yes | No | -| Inline 1-1 relations are recognized as 1-n (missing `UNIQUE` constraint) | Yes | No | No | -| _All_ non-inline relations are recognized as m-n | Yes | No | Yes | -| Json type is represented as `TEXT` in database | Yes | No | No (MySQL)
Yes (PostgreSQL) | -| Enums are represented as `TEXT` in database | Yes | No | No (MySQL)
Yes (PostgreSQL) | -| Required 1-1 relations are not represented in database | No | Yes | No | -| `@db` attributes from Prisma 1 are not transferred to the Prisma schema | No | Yes | No | -| Mismatching CUID length | Yes | No | No | -| Scalar lists (arrays) are maintained with extra table | Depends | No | Depends | - -> **Note**: A general drawback with the workarounds in the Prisma schema is that [changes to the Prisma schema get lost after re-introspecting the database](https://github.com/prisma/prisma/issues/2425) and need to be re-added manually after each introspection run. - -## Prisma 1 Upgrade CLI - -The [Prisma 1 Upgrade CLI](https://github.com/prisma/prisma1-upgrade) helps you apply the workarounds that are explained on the [Schema incompatibilities](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-postgresql) page. It generates the SQL statements to fix the database schema and make it compatible with Prisma ORM versions 2._x_ and later. Note that you are in full control over the operations that are executed against your database, the Upgrade CLI only generates and prints the statements for you. The Upgrade CLI also takes care of the workarounds in the Prisma schema. - -On a high-level, the upgrade workflow using the Upgrade CLI looks as follows. - -For the **initial setup**: - -1. You set up Prisma ORM by installing the Prisma ORM versions 2._x_ and later CLI and running `npx prisma init`. -1. You connect to your database and introspect it with `npx prisma db pull`. - -![Prisma CLI introspection flow](./images/prisma-cli-introspection-flow.png) - -For **fixing the schema incompatibilities**: - -1. You invoke the Upgrade CLI with `npx prisma-upgrade`. -1. The Upgrade CLI generates SQL commands for you to run on your database. -1. You run the SQL commands against your database. -1. You run the `prisma db pull` command again. -1. You run the `npx prisma-upgrade` command again. -1. The Upgrade CLI adjusts the Prisma schema (version 2._x_ and later) by adding missing attributes. - -![Fixing the schema incompatibilities](./images/fix-schema-incompatibilities.png) - -Note that the Upgrade CLI is designed in a way that **you can stop and re-start the process at any time**. Once you ran a SQL command that was generated by the Upgrade CLI against your database, the SQL command will not show up the next time you invoke the Upgrade CLI. That way, you can gradually resolve all schema incompatibilities when it's convenient for you. - -## Upgrade strategies - -There are two main upgrade strategies: - -- **Upgrade all at once**: Entirely remove Prisma 1 from your project and move everything over to Prisma ORM version 2._x_ or later at once. -- **Gradual upgrade side-by-side**: Add Prisma ORM version 2._x_ and later to the existing Prisma 1 project and gradually replace existing Prisma 1 features with the newer Prisma features while running them side-by-side. - -Note that if you are planning to run Prisma 1 and Prisma ORM 2._x_ or later version side-by-side, you must not yet resolve the [schema compatibilities](#schema-incompatibilities) that are breaking the Prisma 1 setup. - -### When to choose which strategy - -If your project is not yet running in production or has little traffic and user data, the **all at once** strategy is recommended. - -In case your project already sees a lot of traffic and has a lot of user data stored in the database, you might want to consider the **gradual** upgrade strategy where you're running Prisma 1 and Prisma ORM 2 or later side-by-side for a certain amount of time until you've replace all former Prisma 1 functionality with Prisma ORM 2 or later version. - -Note that you won't be able to fix the [schema incompatibilities](#schema-incompatibilities) that require a "Breaking Prisma 1" change if you choose the gradual upgrade strategy and intend to run Prisma 1 and Prisma ORM version 2._x_ or later side-by-side. That's because these data migrations are breaking the schema that Prisma 1 expects. This means that your Prisma Client API might not feel as idiomatic as it could, but you still get the full feature set of Prisma Client. - -### Upgrade path - -No matter which of the strategies you choose, on a high-level the envisioned upgrade path looks as follows: - -1. Install the new Prisma ORM version 2._x_ or later CLI as a development dependency -1. Create your Prisma schema and configure the database connection URL -1. Use the Prisma ORM version 2._x_ or later CLI to introspect your Prisma 1 database and generate your Prisma schema -1. Run the [Prisma 1 Upgrade CLI](https://github.com/prisma/prisma1-upgrade) to "fix" the Prisma schema -1. Install and generate Prisma Client version 2._x_ or later -1. Adjust your application code, specifically replace the API calls from the Prisma Client 1.0 with those of Prisma Client version 2._x_ or later - -## Next steps - -Once you've made the decision to upgrade, continue with the [Upgrading the Prisma ORM layer](/orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-the-prisma-layer-postgresql) guide. diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/02-schema-incompatibilities-mysql.mdx b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/02-schema-incompatibilities-mysql.mdx deleted file mode 100644 index 80dab5f158..0000000000 --- a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/02-schema-incompatibilities-mysql.mdx +++ /dev/null @@ -1,776 +0,0 @@ ---- -title: 'Schema incompatibilities' -metaTitle: 'Schema Incompatibilities | MySQL' -metaDescription: 'Problems and workarounds for Prisma 1 and 2.0 schemas with MySQL' -dbSwitcher: ['postgresql', 'mysql'] -sidebar_class_name: hidden-sidebar -pagination_next: orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-the-prisma-layer-mysql -slugSwitch: /orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities- ---- - -## Overview - -Each section on this page describes a potential problem when upgrading from Prisma 1 to Prisma ORM 2._x_ and later and explains the available workarounds. - -## Default values aren't represented in database - -### Problem - -When adding the `@default` directive in a Prisma 1 datamodel, the default values for this field are generated by the Prisma 1 server at runtime. There's no `DEFAULT` constraint added to the database column. Because this constraint is not reflected in the database itself, the Prisma ORM 2._x_ and later versions of introspection can't recognize it. - -### Example - -#### Prisma 1 datamodel - -```graphql -type Post { - id: ID! @id - published: Boolean @default(value: false) -} -``` - -#### Prisma 1 generated SQL migration - -```sql -CREATE TABLE "Post" ( - id VARCHAR(25) PRIMARY KEY NOT NULL, - published BOOLEAN NOT NULL -); -``` - -#### Result of introspection in Prisma ORM versions 2._x_ and later - -```prisma file=schema.prisma showLineNumbers -model Post { - id String @id - published Boolean -} -``` - -Because the `DEFAULT` constraint has not been added to the database when mapping the Prisma 1 datamodel to the database with `prisma deploy`, Prisma ORM v2 (and later versions) doesn't recognize it during introspection. - -### Workarounds - -#### Manually add a `DEFAULT` constraint to the database column - -You can alter the column to add the `DEFAULT` constraint as follows: - -```sql -ALTER TABLE `Post` - ALTER COLUMN published SET DEFAULT false; -``` - -After this adjustment, you can re-introspect your database and the `@default` attribute will be added to the `published` field: - -```prisma line-number file=schema.prisma highlight=3;normal showLineNumbers -model Post { - id String @id - //highlight-next-line - published Boolean @default(false) -} -``` - -#### Manually add a `@default` attribute to the Prisma model - -You can add the `@default` attribute to the Prisma model: - -```prisma line-number file=schema.prisma highlight=3;add showLineNumbers -model Post { - id String - //add-next-line - published Boolean @default(false) -} -``` - -If the `@default` attribute is set in the Prisma schema and you run `prisma generate`, the resulting Prisma Client code will generate the specified default values at runtime (similar to what the Prisma 1 server did in Prisma 1). - -## Generated CUIDs as ID values aren't represented in database - -### Problem - -Prisma 1 auto-generates ID values as CUIDs for `ID` fields when they're annotated with the `@id` directive. These CUIDs are generated by the Prisma 1 server at runtime. Because this behavior is not reflected in the database itself, the introspection in Prisma ORM 2._x_ and later can't recognize it. - -### Example - -#### Prisma 1 datamodel - -```graphql -type Post { - id: ID! @id -} -``` - -#### Prisma 1 generated SQL migration - -```sql -CREATE TABLE "Post" ( - id VARCHAR(25) PRIMARY KEY NOT NULL -); -``` - -#### Result of introspection in Prisma ORM versions 2._x_ and later - -```prisma file=schema.prisma showLineNumbers -model Post { - id String @id -} -``` - -Because there's no indication of the CUID behavior in the database, Prisma ORM's introspection doesn't recognize it. - -### Workaround - -As a workaround, you can manually add the `@default(cuid())` attribute to the Prisma model: - -```prisma line-number file=schema.prisma highlight=2;add showLineNumbers -model Post { - //add-next-line - id String @id @default(cuid()) -} -``` - -If the `@default` attribute is set in the Prisma schema and you run `prisma generate`, the resulting Prisma Client code will generate the specified default values at runtime (similar to what the Prisma 1 server did in Prisma 1). - -Note that you'll have to re-add the attribute after each introspection because introspection removes it (as the previous version of the Prisma schema is overwritten)! - -## `@createdAt` isn't represented in database - -### Problem - -Prisma 1 auto-generates values for `DateTime` fields when they're annotated with the `@createdAt` directive. These values are generated by the Prisma 1 server at runtime. Because this behavior is not reflected in the database itself, the introspection in Prisma ORM 2._x_ and later can't recognize it. - -### Example - -#### Prisma 1 datamodel - -```graphql line-number highlight=3;normal -type Post { - id: ID! @id - createdAt: DateTime! @createdAt -} -``` - -#### Prisma 1 generated SQL migration - -```sql -CREATE TABLE "Post" ( - id VARCHAR(25) PRIMARY KEY NOT NULL, - "createdAt" TIMESTAMP NOT NULL -); -``` - -#### Result of introspection in Prisma ORM 2._x_ and later versions - -```prisma file=schema.prisma showLineNumbers -model Post { - id String @id - createdAt DateTime -} -``` - -### Workarounds - -#### Manually add `DEFAULT CURRENT_TIMESTAMP` to the database column - -You can alter the column to add the `DEFAULT` constraint as follows: - -```sql -ALTER TABLE "Post" - ALTER COLUMN "createdAt" SET DEFAULT CURRENT_TIMESTAMP; -``` - -After this adjustment, you can re-introspect your database and the `@default` attribute will be added to the `createdAt` field: - -```prisma file=schema.prisma showLineNumbers -model Post { - id String - createdAt DateTime @default(now()) -} -``` - -#### Manually add the `@default(now())` attribute to the Prisma model - -As a workaround, you can manually add the `@default(now())` attribute to the Prisma model: - -```prisma line-number file=schema.prisma highlight=3;normal showLineNumbers -model Post { - id String @id - //highlight-next-line - createdAt DateTime @default(now()) -} -``` - -If the `@default` attribute is set in the Prisma schema and you run `prisma generate`, the resulting Prisma Client code will generate the specified default values at runtime (similar to what the Prisma 1 server did in Prisma 1). - -Note that you'll have to re-add the attribute after each introspection because introspection removes it (as the previous version of the Prisma schema is overwritten)! - -## `@updatedAt` isn't represented in database - -### Problem - -Prisma 1 auto-generates values for `DateTime` fields when they're annotated with the `@updatedAt` directive. These values are generated by the Prisma 1 server at runtime. Because this behavior is not reflected in the database itself, the introspection in Prisma ORM 2._x_ and later can't recognize it.. - -### Example - -#### Prisma 1 datamodel - -```graphql -type Post { - id: ID! @id - updatedAt: DateTime! @updatedAt -} -``` - -#### Prisma 1 generated SQL migration - -```sql -CREATE TABLE "Post" ( - id VARCHAR(25) PRIMARY KEY NOT NULL, - updatedAt TIMESTAMP -); -``` - -#### Result of introspection in Prisma ORM 2._x_ and later versions - -```prisma file=schema.prisma showLineNumbers -model Post { - id String @id - updatedAt DateTime -} -``` - -### Workarounds - -#### Manually add the `@updatedAt` attribute to the Prisma model - -As a workaround, you can manually add the `@updatedAt` attribute to the Prisma model: - -```prisma line-number file=schema.prisma highlight=3;add showLineNumbers -model Post { - id String @id - //add-next-line - updatedAt DateTime @updatedAt -} -``` - -If the `@updatedAt` attribute is set in the Prisma schema and you run `prisma generate`, the resulting Prisma Client code will automatically generate values for this column when an existing record is updated (similar to what the Prisma 1 server did in Prisma 1). - -Note that you'll have to re-add the attribute after each introspection because introspection removes it (as the previous version of the Prisma schema is overwritten)! - -## Inline 1-1 relations are recognized as 1-n (missing `UNIQUE` constraint) - -### Problem - -In the [datamodel v1.1](https://www.prisma.io/blog/datamodel-v11-lrzqy1f56c90) that was introduced in Prisma ORM v1.31, 1-1 relations can be declared as _inline_. In that case, the relation will not be maintained via a [relation table](/orm/prisma-schema/data-model/relations/many-to-many-relations#relation-tables) but via a single foreign key on one of the two tables involved. - -When this approach is used, Prisma ORM doesn't add a `UNIQUE` constraint to the foreign key column which means that after introspection in Prisma ORM version 2._x_ and later, this former 1-1 relation will be added as a 1-n relation to the Prisma schema. - -### Example - -#### Prisma ORM datamodel v1.1 (available from Prisma ORM v1.31) - -```graphql -type User { - id: ID! @id - profile: Profile @relation(link: INLINE) -} - -type Profile { - id: ID! @id - user: User -} -``` - -Note that omitting the `@relation` directive in this case would result in the same behavior because `link: INLINE` is the _default_ for 1-1 relations. - -#### Prisma 1 generated SQL migration - -```sql -CREATE TABLE "User" ( - id VARCHAR(25) PRIMARY KEY NOT NULL -); - -CREATE TABLE "Profile" ( - id VARCHAR(25) PRIMARY KEY NOT NULL, - "user" VARCHAR(25), - FOREIGN KEY ("user") REFERENCES "User"(id) -); -``` - -#### Result of introspection in Prisma ORM 2._x_ and later versions - -```prisma file=schema.prisma showLineNumbers -model User { - id String @id - Profile Profile[] -} - -model Profile { - id String @id - user String? - User User? @relation(fields: [user], references: [id]) -} -``` - -Because there's no `UNIQUE` constraint defined on the `user` column (which represents the foreign key in this relation), Prisma ORM's introspection recognizes the relation as 1-n. - -### Workaround - -#### Manually add `UNIQUE` constraint to the foreign key column - -You can alter the foreign key column to add the `UNIQUE` constraint as follows: - -```sql -ALTER TABLE `Profile` - ADD CONSTRAINT userId_unique UNIQUE (`user`); -``` - -After this adjustment, you can re-introspect your database and the 1-1 relation will be properly recognized: - -```prisma line-number file=schema.prisma highlight=3;normal showLineNumbers -model User { - id String @id - //highlight-next-line - Profile Profile? -} - -model Profile { - id String @id - user String? @unique - User User? @relation(fields: [user], references: [id]) -} -``` - -## _All_ non-inline relations are recognized as m-n - -### Problem - -Prisma 1 represents relations as relation tables most of the time: - -- All relations in the Prisma 1 **datamodel v1.0** are represented as relation tables -- In **datamodel v1.1**, all m-n relations as well as the 1-1 and 1-n relations declared as `link: TABLE` are represented as relation tables. - -Because of this representation, introspection in Prisma ORM version 2._x_ and later will recognize all these relations as m-n relations, even though they might have been declared as 1-1 or 1-n in Prisma 1. - -### Example - -#### Prisma 1 datamodel - -```graphql -type User { - id: ID! @id - posts: [Post!]! -} - -type Post { - id: ID! @id - author: User! @relation(link: TABLE) -} -``` - -#### Prisma 1 generated SQL migration - -```sql -CREATE TABLE "User" ( - id VARCHAR(25) PRIMARY KEY NOT NULL -); - -CREATE TABLE "Post" ( - id VARCHAR(25) PRIMARY KEY NOT NULL -); - -CREATE TABLE "_PostToUser" ( - "A" VARCHAR(25) NOT NULL REFERENCES "Post"(id) ON DELETE CASCADE, - "B" VARCHAR(25) NOT NULL REFERENCES "User"(id) ON DELETE CASCADE -); -CREATE UNIQUE INDEX "_PostToUser_AB_unique" ON "_PostToUser"("A" text_ops,"B" text_ops); -CREATE INDEX "_PostToUser_B" ON "_PostToUser"("B" text_ops); -``` - -#### Result of introspection in Prisma ORM 2._x_ and later versions - -```prisma file=schema.prisma showLineNumbers -model User { - id String @id - Post Post[] @relation(references: [id]) -} - -model Post { - id String @id - User User[] @relation(references: [id]) -} -``` - -Because the relation table that was created by Prisma 1 uses the same [conventions for relation tables](/orm/prisma-schema/data-model/relations/many-to-many-relations#conventions-for-relation-tables-in-implicit-m-n-relations) as in Prisma ORM version 2._x_ and later, the relation now gets recognized as a m-n relation. - -### Workaround - -As a workaround, you can migrate the data into a structure that's compatible with Prisma ORM's 1-n relation: - -1. Create new column `authorId` on the `Post` table. This column should be a _foreign key_ that references the `id` field of the `User` table: - ```sql - ALTER TABLE `Post` ADD COLUMN `authorId` VARCHAR(25); - ALTER TABLE `Post` ADD FOREIGN KEY (`authorId`) REFERENCES `User` (`id`); - ``` -1. Write a SQL query that reads all the rows from the `_PostToUser` relation table and for each row: - 1. Finds the respective `Post` record by looking up the value from column `A` - 1. Inserts the value from column `B` as the value for `authorId` into that `Post` record - ```sql - UPDATE Post, _PostToUser - SET Post.authorId = _PostToUser.B - WHERE Post.id = _PostToUser.A - ``` -1. Delete the `_PostToUser` relation table - ```sql - DROP TABLE `_PostToUser`; - ``` - -After that you can introspect your database and the relation will now be recognized as 1-n: - -```prisma line-number file=schema.prisma highlight=3,8,9;normal showLineNumbers -model User { - id String @id - //highlight-next-line - Post Post[] -} - -model Post { - id String @id - //highlight-start - User User @relation(fields: [authorId], references: [id]) - authorId String - //highlight-end -} -``` - -## `Json` type is represented as `TEXT` in database - -### Problem - -Prisma 1 supports the `Json` data type in its datamodel. However, in the underlying database, fields of type `Json` are actually stored as plain strings using the `TEXT` data type of the underlying database. Any parsing and validation of the stored JSON data is done by the Prisma 1 server at runtime. - -### Example - -#### Prisma 1 datamodel - -```graphql -type User { - id: ID! @id - jsonData: Json -} -``` - -#### Prisma 1 generated SQL migration - -```sql -CREATE TABLE "User" ( - id VARCHAR(25) PRIMARY KEY NOT NULL, - jsonData TEXT -); -``` - -#### Result of introspection in Prisma ORM 2._x_ and later versions - -```prisma file=schema.prisma showLineNumbers -model User { - id String @id - jsonData String? -} -``` - -### Workaround - -You can manually change the type of the column to `JSON` - -```sql -ALTER TABLE User MODIFY COLUMN jsonData JSON; -``` - -After this adjustment, you can re-introspect your database and the field will now be recognized as `Json`: - -```prisma line-number file=schema.prisma highlight=3;normal showLineNumbers -model User { - id String @id - //highlight-next-line - jsonData Json? -} -``` - -## Enums are represented as `TEXT` in database - -### Problem - -Prisma 1 supports the `enum` data type in its datamodel. However, in the underlying database, types declared as `enum` are actually stored as plain strings using the `TEXT` data type of the underlying database. Any validation of the stored `enum` data is done by the Prisma 1 server at runtime. - -### Example - -#### Prisma 1 datamodel - -```graphql -type User { - id: ID! @id - role: Role -} - -enum Role { - ADMIN - CUSTOMER -} -``` - -#### Prisma 1 generated SQL migration - -```sql -CREATE TABLE "User" ( - id VARCHAR(25) PRIMARY KEY NOT NULL, - role TEXT -); -``` - -#### Result of introspection in Prisma ORM 2._x_ and later versions - -```prisma file=schema.prisma showLineNumbers -model User { - id String @id - role String? -} -``` - -### Workaround - -You can manually turn the `role` column into an enum with your desired values: - -1. Create an `enum` in your database that mirrors the `enum` you defined in the Prisma 1 datamodel: - ```sql - CREATE TYPE "Role" AS ENUM ('CUSTOMER', 'ADMIN'); - ``` -1. Change the type from `TEXT` to your new `enum`: - ```sql - ALTER TABLE "User" ALTER COLUMN "role" TYPE "Role" - USING "role"::text::"Role"; - ``` - -After introspection, the type is now properly recognized as an enum: - -```prisma line-number file=schema.prisma highlight=3,6-9;normal showLineNumbers -model User { - id String @id - //highlight-next-line - role Role? -} - -//highlight-start -enum Role { - ADMIN - CUSTOMER -} -//highlight-end -``` - -## Mismatching CUID length - -### Problem - -Prisma 1 uses CUIDs as ID values for all database records. In the underlying database, these IDs are represented as strings with a maximum size of 25 characters (as `VARCHAR(25)`). However, when configuring default CUIDs in your Prisma ORM 2._x_ (or later versions) schema with `@default(cuid())` the generated ID values might exceed the limit of 25 characters (the maximum length might be 30 characters). To make your IDs proof for Prisma ORM 2._x_ (or later versions), you therefore need to adjust the column type to `VARCHAR(30)`. - -### Example - -#### Prisma 1 datamodel - -```graphql -type User { - id: ID! @id -} -``` - -#### Prisma 1 generated SQL migration - -```sql -CREATE TABLE "User" ( - id VARCHAR(25) PRIMARY KEY NOT NULL -); -``` - -#### Result of introspection in Prisma ORM 2._x_ and later versions - -```prisma file=schema.prisma showLineNumbers -model User { - id String @id -} -``` - -### Workaround - -You can manually turn the `VARCHAR(25)` columns into `VARCHAR(30)`: - -```sql -SET FOREIGN_KEY_CHECKS=0; -ALTER TABLE `User` CHANGE `id` `id` char(30) CHARACTER SET utf8 NOT NULL; -SET FOREIGN_KEY_CHECKS=1; -``` - -> **Note**: When fixing this issue with the [Upgrade CLI](/orm/more/upgrade-guides/upgrade-from-prisma-1/how-to-upgrade#prisma-1-upgrade-cli), the generated SQL statements will keep appearing in the Upgrade CLI even after you have changed the column types in the underlying database. This is a currently a limitation in the Upgrade CLI. - -## Scalar lists (arrays) are maintained with extra table - -### Problem - -In Prisma 1, you can define lists of _scalar_ types on your models. Under the hood, this is implemented with an extra table that keeps track of the values in the list. - -To remove the approach with the extra table which incurred hidden performance costs, Prisma ORM 2._x_ and later versions only support scalar lists only when they're natively supported by the database you use. At the moment, only [PostgreSQL supports scalar lists (arrays) natively](https://www.postgresql.org/docs/9.1/arrays.html). - -With PostgreSQL, you therefore can keep using scalar lists in Prisma ORM 2._x_ and later versions, but you'll need to perform a data migration to transfer the data from the extra table from Prisma 1 into an actual PostgreSQL array. - -### Example - -#### Prisma 1 datamodel - -```graphql -type User { - id: ID! @id - coinflips: [Boolean!]! @scalarList(strategy: RELATION) -} -``` - -#### Prisma 1 generated SQL migration - -```sql -CREATE TABLE "User" ( - id VARCHAR(25) PRIMARY KEY NOT NULL -); - -CREATE TABLE "User_coinflips" ( - "nodeId" VARCHAR(25) REFERENCES "User"(id), - position INTEGER, - value BOOLEAN NOT NULL, - CONSTRAINT "User_coinflips_pkey" PRIMARY KEY ("nodeId", position) -); -CREATE UNIQUE INDEX "User_coinflips_pkey" ON "User_coinflips"("nodeId" text_ops,position int4_ops); -``` - -#### Result of Prisma ORM 2 introspection - -```prisma file=schema.prisma showLineNumbers -model User { - id String @id - User_coinflips User_coinflips[] -} - -model User_coinflips { - nodeId String - position Int - value Boolean - User User @relation(fields: [nodeId], references: [id]) - - @@id([nodeId, position]) -} -``` - -Note that you can now generate Prisma Client and you'll be able to access the data from the scalar lists through the extra table. PostgreSQL users can alternatively migrate the data into a native PostgreSQL array and continue to benefit from the slicker Prisma Client API for scalar lists (read the section below for more info). - -
- -Expand for sample Prisma Client API calls - -To access the coinflips data, you will now have to always [`include`](/orm/prisma-client/queries/select-fields#return-nested-objects-by-selecting-relation-fields) it in your queries: - -```ts -const user = await prisma.user.findUnique({ - where: { id: 1 }, - include: { - coinflips: { - orderBy: { position: 'asc' }, - }, - }, -}) -``` - -> **Note**: The `orderBy` is important to retain the order of the list. - -This is the `result of the query: - -```js -{ - id: 1, - name: 'Alice', - coinflips: [ - { id: 1, position: 1000, value: false }, - { id: 2, position: 2000, value: true }, - { id: 3, position: 3000, value: false }, - { id: 4, position: 4000, value: true }, - { id: 5, position: 5000, value: true }, - { id: 6, position: 6000, value: false } - ] -} -``` - -To access just the boolean values from the list, you can `map` over the `coinflips` on `user` as follows: - -```ts -const currentCoinflips = user!.coinflips.map((cf) => cf.value) -``` - -> **Note**: The exclamation mark above means that you're _force unwrapping_ the `user` value. This is necessary because the `user` returned from the previous query might be `null`. - -Here's the value of `currentCoinflips` after the call to `map`: - -```json -[false, true, false, true, true, false] -``` - -
- -### Workaround - -The following workaround is only available for PostgreSQL users! - -As scalar lists (i.e. [arrays](https://www.postgresql.org/docs/9.1/arrays.html)) are available as a native PostgreSQL feature, you can keep using the same notation of `coinflips: Boolean[]` in your Prisma schema. - -However, in order to do so you need to manually migrate the underlying data from the `User_coinflips` table into a PostgreSQL array. Here's how you can do that: - -1. Add the new `coinflips` column to the `User` tables: - ```sql - ALTER TABLE "User" ADD COLUMN coinflips BOOLEAN[]; - ``` -1. Migrate the data from `"User_coinflips".value` to `"User.coinflips"`: - ```sql - UPDATE "User" - SET coinflips = t.flips - FROM ( - SELECT "nodeId", array_agg(VALUE ORDER BY position) AS flips - FROM "User_coinflips" - GROUP BY "nodeId" - ) t - where t."nodeId" = "User"."id"; - ``` -1. To cleanup, you can delete the `User_coinflips` table: - ```sql - DROP TABLE "User_coinflips"; - ``` - -You can now introspect your database and the `coinflips` field will be represented as an array in your new Prisma schema: - -```prisma file=schema.prisma showLineNumbers -model User { - id String @id - coinflips Boolean[] -} -``` - -You can keep using Prisma Client as before: - -```ts -const user = await prisma.user.findUnique({ - where: { id: 1 }, -}) -``` - -This is the result from the API call: - -```js -{ - id: 1, - name: 'Alice', - coinflips: [ false, true, false, true, true, false ] -} -``` diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/02-schema-incompatibilities-postgresql.mdx b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/02-schema-incompatibilities-postgresql.mdx deleted file mode 100644 index 59ff7030bd..0000000000 --- a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/02-schema-incompatibilities-postgresql.mdx +++ /dev/null @@ -1,777 +0,0 @@ ---- -title: 'Schema incompatibilities' -metaTitle: 'Schema Incompatibilities | PostgreSQL' -metaDescription: 'Problems and workarounds for Prisma 1 and 2.0 schemas with PostgreSQL' -dbSwitcher: ['postgresql', 'mysql'] -pagination_next: orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-the-prisma-layer-postgresql -slugSwitch: /orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities- ---- - -## Overview - -Each section on this page describes a potential problem when upgrading from Prisma 1 to Prisma ORM 2._x_ and later and explains the available workarounds. - -## Default values aren't represented in database - -### Problem - -When adding the `@default` directive in a Prisma 1 datamodel, the default values for this field are generated by the Prisma 1 server at runtime. There's no `DEFAULT` constraint added to the database column. Because this constraint is not reflected in the database itself, the Prisma ORM 2._x_ and later versions of introspection can't recognize it. - -### Example - -#### Prisma 1 datamodel - -```graphql -type Post { - id: ID! @id - published: Boolean @default(value: false) -} -``` - -#### Prisma 1 generated SQL migration - -```sql -CREATE TABLE "Post" ( - id VARCHAR(25) PRIMARY KEY NOT NULL, - published BOOLEAN NOT NULL -); -``` - -#### Result of introspection in Prisma ORM versions 2._x_ and later - -```prisma file=schema.prisma showLineNumbers -model Post { - id String @id - published Boolean -} -``` - -Because the `DEFAULT` constraint has not been added to the database when mapping the Prisma 1 datamodel to the database with `prisma deploy`, Prisma ORM v2 (and later versions) doesn't recognize it during introspection. - -### Workarounds - -#### Manually add a `DEFAULT` constraint to the database column - -You can alter the column to add the `DEFAULT` constraint as follows: - -```sql -ALTER TABLE "Post" - ALTER COLUMN published SET DEFAULT false; -``` - -After this adjustment, you can re-introspect your database and the `@default` attribute will be added to the `published` field: - -```prisma line-number file=schema.prisma highlight=3;normal showLineNumbers -model Post { - id String @id - //highlight-next-line - published Boolean @default(false) -} -``` - -#### Manually add a `@default` attribute to the Prisma model - -You can add the `@default` attribute to the Prisma model: - -```prisma line-number file=schema.prisma highlight=3;add showLineNumbers -model Post { - id String - //add-next-line - published Boolean @default(false) -} -``` - -If the `@default` attribute is set in the Prisma schema and you run `prisma generate`, the resulting Prisma Client code will generate the specified default values at runtime (similar to what the Prisma 1 server did in Prisma 1). - -## Generated CUIDs as ID values aren't represented in database - -### Problem - -Prisma 1 auto-generates ID values as CUIDs for `ID` fields when they're annotated with the `@id` directive. These CUIDs are generated by the Prisma 1 server at runtime. Because this behavior is not reflected in the database itself, the introspection in Prisma ORM 2._x_ and later can't recognize it. - -### Example - -#### Prisma 1 datamodel - -```graphql -type Post { - id: ID! @id -} -``` - -#### Prisma 1 generated SQL migration - -```sql -CREATE TABLE "Post" ( - id VARCHAR(25) PRIMARY KEY NOT NULL -); -``` - -#### Result of introspection in Prisma ORM versions 2._x_ and later - -```prisma file=schema.prisma showLineNumbers -model Post { - id String @id -} -``` - -Because there's no indication of the CUID behavior in the database, Prisma ORM's introspection doesn't recognize it. - -### Workaround - -As a workaround, you can manually add the `@default(cuid())` attribute to the Prisma model: - -```prisma line-number file=schema.prisma highlight=2;add showLineNumbers -model Post { - //add-next-line - id String @id @default(cuid()) -} -``` - -If the `@default` attribute is set in the Prisma schema and you run `prisma generate`, the resulting Prisma Client code will generate the specified default values at runtime (similar to what the Prisma 1 server did in Prisma 1). - -Note that you'll have to re-add the attribute after each introspection because introspection removes it (as the previous version of the Prisma schema is overwritten)! - -## `@createdAt` isn't represented in database - -### Problem - -Prisma 1 auto-generates values for `DateTime` fields when they're annotated with the `@createdAt` directive. These values are generated by the Prisma 1 server at runtime. Because this behavior is not reflected in the database itself, the introspection in Prisma ORM 2._x_ and later can't recognize it. - -### Example - -#### Prisma 1 datamodel - -```graphql line-number highlight=3;normal -type Post { - id: ID! @id - createdAt: DateTime! @createdAt -} -``` - -#### Prisma 1 generated SQL migration - -```sql -CREATE TABLE "Post" ( - id VARCHAR(25) PRIMARY KEY NOT NULL, - "createdAt" TIMESTAMP NOT NULL -); -``` - -#### Result of introspection in Prisma ORM 2._x_ and later versions - -```prisma file=schema.prisma showLineNumbers -model Post { - id String @id - createdAt DateTime -} -``` - -### Workarounds - -#### Manually add `DEFAULT CURRENT_TIMESTAMP` to the database column - -You can alter the column to add the `DEFAULT` constraint as follows: - -```sql -ALTER TABLE "Post" - ALTER COLUMN "createdAt" SET DEFAULT CURRENT_TIMESTAMP; -``` - -After this adjustment, you can re-introspect your database and the `@default` attribute will be added to the `createdAt` field: - -```prisma file=schema.prisma showLineNumbers -model Post { - id String - createdAt DateTime @default(now()) -} -``` - -#### Manually add the `@default(now())` attribute to the Prisma model - -As a workaround, you can manually add the `@default(now())` attribute to the Prisma model: - -```prisma line-number file=schema.prisma highlight=3;normal -model Post { - id String @id - //highlight-next-line - createdAt DateTime @default(now()) -} -``` - -If the `@default` attribute is set in the Prisma schema and you run `prisma generate`, the resulting Prisma Client code will generate the specified default values at runtime (similar to what the Prisma 1 server did in Prisma 1). - -Note that you'll have to re-add the attribute after each introspection because introspection removes it (as the previous version of the Prisma schema is overwritten)! - -## `@updatedAt` isn't represented in database - -### Problem - -Prisma 1 auto-generates values for `DateTime` fields when they're annotated with the `@updatedAt` directive. These values are generated by the Prisma 1 server at runtime. Because this behavior is not reflected in the database itself, the introspection in Prisma ORM 2._x_ and later can't recognize it.. - -### Example - -#### Prisma 1 datamodel - -```graphql -type Post { - id: ID! @id - updatedAt: DateTime! @updatedAt -} -``` - -#### Prisma 1 generated SQL migration - -```sql -CREATE TABLE "Post" ( - id VARCHAR(25) PRIMARY KEY NOT NULL, - updatedAt TIMESTAMP -); -``` - -#### Result of introspection in Prisma ORM 2._x_ and later versions - -```prisma file=schema.prisma showLineNumbers -model Post { - id String @id - updatedAt DateTime -} -``` - -### Workarounds - -#### Manually add the `@updatedAt` attribute to the Prisma model - -As a workaround, you can manually add the `@updatedAt` attribute to the Prisma model: - -```prisma line-number file=schema.prisma highlight=3;add -model Post { - id String @id - //add-next-line - updatedAt DateTime @updatedAt -} -``` - -If the `@updatedAt` attribute is set in the Prisma schema and you run `prisma generate`, the resulting Prisma Client code will automatically generate values for this column when an existing record is updated (similar to what the Prisma 1 server did in Prisma 1). - -Note that you'll have to re-add the attribute after each introspection because introspection removes it (as the previous version of the Prisma schema is overwritten)! - -## Inline 1-1 relations are recognized as 1-n (missing `UNIQUE` constraint) - -### Problem - -In the [datamodel v1.1](https://www.prisma.io/blog/datamodel-v11-lrzqy1f56c90) that was introduced in Prisma ORM v1.31, 1-1 relations can be declared as _inline_. In that case, the relation will not be maintained via a [relation table](/orm/prisma-schema/data-model/relations/many-to-many-relations#relation-tables) but via a single foreign key on one of the two tables involved. - -When this approach is used, Prisma ORM doesn't add a `UNIQUE` constraint to the foreign key column which means that after introspection in Prisma ORM version 2._x_ and later, this former 1-1 relation will be added as a 1-n relation to the Prisma schema. - -### Example - -#### Prisma ORM datamodel v1.1 (available from Prisma ORM v1.31) - -```graphql -type User { - id: ID! @id - profile: Profile @relation(link: INLINE) -} - -type Profile { - id: ID! @id - user: User -} -``` - -Note that omitting the `@relation` directive in this case would result in the same behavior because `link: INLINE` is the _default_ for 1-1 relations. - -#### Prisma 1 generated SQL migration - -```sql -CREATE TABLE "User" ( - id VARCHAR(25) PRIMARY KEY NOT NULL -); - -CREATE TABLE "Profile" ( - id VARCHAR(25) PRIMARY KEY NOT NULL, - "user" VARCHAR(25), - FOREIGN KEY ("user") REFERENCES "User"(id) -); -``` - -#### Result of introspection in Prisma ORM 2._x_ and later versions - -```prisma file=schema.prisma showLineNumbers -model User { - id String @id - Profile Profile[] -} - -model Profile { - id String @id - user String? - User User? @relation(fields: [user], references: [id]) -} -``` - -Because there's no `UNIQUE` constraint defined on the `user` column (which represents the foreign key in this relation), Prisma ORM's introspection recognizes the relation as 1-n. - -### Workaround - -#### Manually add `UNIQUE` constraint to the foreign key column - -You can alter the foreign key column to add the `UNIQUE` constraint as follows: - -```sql -ALTER TABLE "Profile" - ADD CONSTRAINT userId_unique UNIQUE ("user"); -``` - -After this adjustment, you can re-introspect your database and the 1-1 relation will be properly recognized: - -```prisma line-number file=schema.prisma highlight=3;normal -model User { - id String @id - //highlight-next-line - Profile Profile? -} - -model Profile { - id String @id - user String? @unique - User User? @relation(fields: [user], references: [id]) -} -``` - -## _All_ non-inline relations are recognized as m-n - -### Problem - -Prisma 1 represents relations as relation tables most of the time: - -- All relations in the Prisma 1 **datamodel v1.0** are represented as relation tables -- In **datamodel v1.1**, all m-n relations as well as the 1-1 and 1-n relations declared as `link: TABLE` are represented as relation tables. - -Because of this representation, introspection in Prisma ORM version 2._x_ and later will recognize all these relations as m-n relations, even though they might have been declared as 1-1 or 1-n in Prisma 1. - -### Example - -#### Prisma 1 datamodel - -```graphql -type User { - id: ID! @id - posts: [Post!]! -} - -type Post { - id: ID! @id - author: User! @relation(link: TABLE) -} -``` - -#### Prisma 1 generated SQL migration - -```sql -CREATE TABLE "User" ( - id VARCHAR(25) PRIMARY KEY NOT NULL -); - -CREATE TABLE "Post" ( - id VARCHAR(25) PRIMARY KEY NOT NULL -); - -CREATE TABLE "_PostToUser" ( - "A" VARCHAR(25) NOT NULL REFERENCES "Post"(id) ON DELETE CASCADE, - "B" VARCHAR(25) NOT NULL REFERENCES "User"(id) ON DELETE CASCADE -); -CREATE UNIQUE INDEX "_PostToUser_AB_unique" ON "_PostToUser"("A" text_ops,"B" text_ops); -CREATE INDEX "_PostToUser_B" ON "_PostToUser"("B" text_ops); -``` - -#### Result of introspection in Prisma ORM 2._x_ and later versions - -```prisma file=schema.prisma showLineNumbers -model User { - id String @id - Post Post[] @relation(references: [id]) -} - -model Post { - id String @id - User User[] @relation(references: [id]) -} -``` - -Because the relation table that was created by Prisma 1 uses the same [conventions for relation tables](/orm/prisma-schema/data-model/relations/many-to-many-relations#conventions-for-relation-tables-in-implicit-m-n-relations) as in Prisma ORM version 2._x_ and later, the relation now gets recognized as a m-n relation. - -### Workaround - -As a workaround, you can migrate the data into a structure that's compatible with Prisma ORM's 1-n relation: - -1. Create new column `authorId` on the `Post` table. This column should be a _foreign key_ that references the `id` field of the `User` table: - ```sql - ALTER TABLE "Post" ADD COLUMN "authorId" VARCHAR(25); - ALTER TABLE "Post" - ADD CONSTRAINT fk_author - FOREIGN KEY ("authorId") - REFERENCES "User"("id"); - ``` -1. Write a SQL query that reads all the rows from the `_PostToUser` relation table and for each row: - 1. Finds the respective `Post` record by looking up the value from column `A` - 1. Inserts the value from column `B` as the value for `authorId` into that `Post` record - ```sql - UPDATE "Post" post - SET "authorId" = post_to_user."B" - FROM "_PostToUser" post_to_user - WHERE post_to_user."A" = post."id"; - ``` -1. Delete the `_PostToUser` relation table - ```sql - DROP TABLE "_PostToUser"; - ``` - -After that you can introspect your database and the relation will now be recognized as 1-n: - -```prisma line-number file=schema.prisma highlight=3,8,9;normal -model User { - id String @id - //highlight-next-line - Post Post[] -} - -model Post { - id String @id - //highlight-start - User User @relation(fields: [authorId], references: [id]) - authorId String - //highlight-end -} -``` - -## `Json` type is represented as `TEXT` in database - -### Problem - -Prisma 1 supports the `Json` data type in its datamodel. However, in the underlying database, fields of type `Json` are actually stored as plain strings using the `TEXT` data type of the underlying database. Any parsing and validation of the stored JSON data is done by the Prisma 1 server at runtime. - -### Example - -#### Prisma 1 datamodel - -```graphql -type User { - id: ID! @id - jsonData: Json -} -``` - -#### Prisma 1 generated SQL migration - -```sql -CREATE TABLE "User" ( - id VARCHAR(25) PRIMARY KEY NOT NULL, - jsonData TEXT -); -``` - -#### Result of introspection in Prisma ORM 2._x_ and later versions - -```prisma file=schema.prisma showLineNumbers -model User { - id String @id - jsonData String? -} -``` - -### Workaround - -You can manually change the type of the column to `JSON` - -```sql -ALTER TABLE "User" ALTER COLUMN "jsonData" TYPE JSON USING "jsonData"::json; -``` - -After this adjustment, you can re-introspect your database and the field will now be recognized as `Json`: - -```prisma line-number file=schema.prisma highlight=3;normal showLineNumbers -model User { - id String @id - //highlight-next-line - jsonData Json? -} -``` - -## Enums are represented as `TEXT` in database - -### Problem - -Prisma 1 supports the `enum` data type in its datamodel. However, in the underlying database, types declared as `enum` are actually stored as plain strings using the `TEXT` data type of the underlying database. Any validation of the stored `enum` data is done by the Prisma 1 server at runtime. - -### Example - -#### Prisma 1 datamodel - -```graphql -type User { - id: ID! @id - role: Role -} - -enum Role { - ADMIN - CUSTOMER -} -``` - -#### Prisma 1 generated SQL migration - -```sql -CREATE TABLE "User" ( - id VARCHAR(25) PRIMARY KEY NOT NULL, - role TEXT -); -``` - -#### Result of introspection in Prisma ORM 2._x_ and later versions - -```prisma file=schema.prisma showLineNumbers -model User { - id String @id - role String? -} -``` - -### Workaround - -You can manually turn the `role` column into an enum with your desired values: - -1. Create an `enum` in your database that mirrors the `enum` you defined in the Prisma 1 datamodel: - ```sql - CREATE TYPE "Role" AS ENUM ('CUSTOMER', 'ADMIN'); - ``` -1. Change the type from `TEXT` to your new `enum`: - ```sql - ALTER TABLE "User" ALTER COLUMN "role" TYPE "Role" - USING "role"::text::"Role"; - ``` - -After introspection, the type is now properly recognized as an enum: - -```prisma line-number file=schema.prisma highlight=3,6-9;normal showLineNumbers -model User { - id String @id - //highlight-next-line - role Role? -} - -//highlight-start -enum Role { - ADMIN - CUSTOMER -} -//highlight-end -``` - -## Mismatching CUID length - -### Problem - -Prisma 1 uses CUIDs as ID values for all database records. In the underlying database, these IDs are represented as strings with a maximum size of 25 characters (as `VARCHAR(25)`). However, when configuring default CUIDs in your Prisma ORM 2._x_ (or later versions) schema with `@default(cuid())` the generated ID values might exceed the limit of 25 characters (the maximum length might be 30 characters). To make your IDs proof for Prisma ORM 2._x_ (or later versions), you therefore need to adjust the column type to `VARCHAR(30)`. - -### Example - -#### Prisma 1 datamodel - -```graphql -type User { - id: ID! @id -} -``` - -#### Prisma 1 generated SQL migration - -```sql -CREATE TABLE "User" ( - id VARCHAR(25) PRIMARY KEY NOT NULL -); -``` - -#### Result of introspection in Prisma ORM 2._x_ and later versions - -```prisma file=schema.prisma showLineNumbers -model User { - id String @id -} -``` - -### Workaround - -You can manually turn the `VARCHAR(25)` columns into `VARCHAR(30)`: - -```sql -ALTER TABLE "User" ALTER COLUMN "id" SET DATA TYPE character varying(30); -``` - -> **Note**: When fixing this issue with the [Upgrade CLI](/orm/more/upgrade-guides/upgrade-from-prisma-1/how-to-upgrade#prisma-1-upgrade-cli), the generated SQL statements will keep appearing in the Upgrade CLI even after you have changed the column types in the underlying database. This is a currently a limitation in the Upgrade CLI. - -## Scalar lists (arrays) are maintained with extra table - -### Problem - -In Prisma 1, you can define lists of _scalar_ types on your models. Under the hood, this is implemented with an extra table that keeps track of the values in the list. - -To remove the approach with the extra table which incurred hidden performance costs, Prisma ORM 2._x_ and later versions only support scalar lists only when they're natively supported by the database you use. At the moment, only [PostgreSQL supports scalar lists (arrays) natively](https://www.postgresql.org/docs/9.1/arrays.html). - -With PostgreSQL, you therefore can keep using scalar lists in Prisma ORM 2._x_ and later versions, but you'll need to perform a data migration to transfer the data from the extra table from Prisma 1 into an actual PostgreSQL array. - -### Example - -#### Prisma 1 datamodel - -```graphql -type User { - id: ID! @id - coinflips: [Boolean!]! @scalarList(strategy: RELATION) -} -``` - -#### Prisma 1 generated SQL migration - -```sql -CREATE TABLE "User" ( - id VARCHAR(25) PRIMARY KEY NOT NULL -); - -CREATE TABLE "User_coinflips" ( - "nodeId" VARCHAR(25) REFERENCES "User"(id), - position INTEGER, - value BOOLEAN NOT NULL, - CONSTRAINT "User_coinflips_pkey" PRIMARY KEY ("nodeId", position) -); -CREATE UNIQUE INDEX "User_coinflips_pkey" ON "User_coinflips"("nodeId" text_ops,position int4_ops); -``` - -#### Result of Prisma ORM 2 introspection - -```prisma file=schema.prisma showLineNumbers -model User { - id String @id - User_coinflips User_coinflips[] -} - -model User_coinflips { - nodeId String - position Int - value Boolean - User User @relation(fields: [nodeId], references: [id]) - - @@id([nodeId, position]) -} -``` - -Note that you can now generate Prisma Client and you'll be able to access the data from the scalar lists through the extra table. PostgreSQL users can alternatively migrate the data into a native PostgreSQL array and continue to benefit from the slicker Prisma Client API for scalar lists (read the section below for more info). - -
- -Expand for sample Prisma Client API calls - -To access the coinflips data, you will now have to always [`include`](/orm/prisma-client/queries/select-fields#return-nested-objects-by-selecting-relation-fields) it in your queries: - -```ts -const user = await prisma.user.findUnique({ - where: { id: 1 }, - include: { - coinflips: { - orderBy: { position: 'asc' }, - }, - }, -}) -``` - -> **Note**: The `orderBy` is important to retain the order of the list. - -This is the `result of the query: - -```js -{ - id: 1, - name: 'Alice', - coinflips: [ - { id: 1, position: 1000, value: false }, - { id: 2, position: 2000, value: true }, - { id: 3, position: 3000, value: false }, - { id: 4, position: 4000, value: true }, - { id: 5, position: 5000, value: true }, - { id: 6, position: 6000, value: false } - ] -} -``` - -To access just the boolean values from the list, you can `map` over the `coinflips` on `user` as follows: - -```ts -const currentCoinflips = user!.coinflips.map((cf) => cf.value) -``` - -> **Note**: The exclamation mark above means that you're _force unwrapping_ the `user` value. This is necessary because the `user` returned from the previous query might be `null`. - -Here's the value of `currentCoinflips` after the call to `map`: - -```json -[false, true, false, true, true, false] -``` - -
- -### Workaround - -The following workaround is only available for PostgreSQL users! - -As scalar lists (i.e. [arrays](https://www.postgresql.org/docs/9.1/arrays.html)) are available as a native PostgreSQL feature, you can keep using the same notation of `coinflips: Boolean[]` in your Prisma schema. - -However, in order to do so you need to manually migrate the underlying data from the `User_coinflips` table into a PostgreSQL array. Here's how you can do that: - -1. Add the new `coinflips` column to the `User` tables: - ```sql - ALTER TABLE "User" ADD COLUMN coinflips BOOLEAN[]; - ``` -1. Migrate the data from `"User_coinflips".value` to `"User.coinflips"`: - ```sql - UPDATE "User" - SET coinflips = t.flips - FROM ( - SELECT "nodeId", array_agg(VALUE ORDER BY position) AS flips - FROM "User_coinflips" - GROUP BY "nodeId" - ) t - where t."nodeId" = "User"."id"; - ``` -1. To cleanup, you can delete the `User_coinflips` table: - ```sql - DROP TABLE "User_coinflips"; - ``` - -You can now introspect your database and the `coinflips` field will be represented as an array in your new Prisma schema: - -```prisma file=schema.prisma showLineNumbers -model User { - id String @id - coinflips Boolean[] -} -``` - -You can keep using Prisma Client as before: - -```ts -const user = await prisma.user.findUnique({ - where: { id: 1 }, -}) -``` - -This is the result from the API call: - -```js -{ - id: 1, - name: 'Alice', - coinflips: [ false, true, false, true, true, false ] -} -``` diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/03-upgrading-the-prisma-layer-mysql.mdx b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/03-upgrading-the-prisma-layer-mysql.mdx deleted file mode 100644 index 1a8607c050..0000000000 --- a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/03-upgrading-the-prisma-layer-mysql.mdx +++ /dev/null @@ -1,1311 +0,0 @@ ---- -title: 'Upgrading the Prisma ORM layer' -metaTitle: 'Upgrading the Prisma ORM layer to Prisma ORM 2 | MySQL' -metaDescription: 'Learn how to upgrade the Prisma ORM layer to Prisma ORM 2 and create your Prisma schema with MySQL' -dbSwitcher: ['postgresql', 'mysql'] -sidebar_class_name: hidden-sidebar -pagination_next: orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-nexus-prisma-to-nexus -slugSwitch: /orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-the-prisma-layer- ---- - -## Overview - -This page explains the first step of your upgrade process: Taking your Prisma 1 configuration and upgrading it to Prisma ORM 2. Concretely, you will learn how to: - -1. Add the Prisma ORM 2 CLI as a development dependency -1. Create your Prisma ORM 2 schema -1. Determine your connection URL and connect to your database -1. Introspect your database (that was so far managed with Prisma 1) -1. Use the [Prisma 1 Upgrade CLI](/orm/more/upgrade-guides/upgrade-from-prisma-1/how-to-upgrade#prisma-1-upgrade-cli) to resolve the [schema incompatibilities](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-mysql) in the new Prisma ORM 2 data model -1. Install and generate Prisma Client - -Once done with these steps, you can move on to the next guide that explains how you can upgrade the application layer to use Prisma Client for your database queries. - -> **Note**: During the upgrade process it can be helpful to get a graphical view on your database. It is therefore recommended to use a graphical database client to connect to your database, such as [TablePlus](https://tableplus.com/) or [Postico](https://eggerapps.at/postico/). - -## 1. Install Prisma ORM 2 CLI - -The Prisma ORM 2 CLI is available as the [`prisma`](https://www.npmjs.com/package/prisma) package on npm and is invoked via the `prisma` command. - -Note that the former `prisma` command for Prisma 1 has been renamed to `prisma1`. You can learn more about this [here](https://www.prisma.io/blog/prisma-2-beta-b7bcl0gd8d8e#renaming-the-prisma2-cli). - -You can install the Prisma ORM 2 CLI in your Node.js project as follows (be sure to invoke this command in the directory where your `package.json` is located): - -```terminal copy -npm install prisma --save-dev -``` - -> **Note**: With Prisma 1, it was usually recommended to install the CLI globally. We now recommend to [install the Prisma CLI locally](/orm/tools/prisma-cli#installation) to prevent version conflicts. - -You can now use the local installation of the `prisma` CLI by prefixing it with `npx`: - -```terminal -npx prisma -``` - -If you're upgrading your entire project [all at once](/orm/more/upgrade-guides/upgrade-from-prisma-1/how-to-upgrade#upgrade-strategies), you can now also uninstall the Prisma 1 CLI (otherwise expand below): - -```terminal -# remove global installation -npm uninstall -g prisma1 - -# remove local installation -npm uninstall prisma1 -``` - -
- -
- -Expand if you want to keep using your Prisma 1 CLI side-by-side - -If you want to keep using the Prisma 1 CLI, it is recommend to remove your global installation of it and add the `prisma1` CLI as a development dependency: - -```terminal -# installs v1.34 of the Prisma 1 CLI -npm uninstall -g prisma -npm install prisma1 --save-dev -``` - -You can now invoke it as follows: - -```terminal -npx prisma1 -``` - -Note that if you need a CLI version smaller than 1.34 (e.g. 1.30), you can install it as follows: - -```terminal -# installs v1.30 of the Prisma 1 CLI -npm uninstall -g prisma@1.30 -npm install prisma@1.30 --save-dev -``` - -You can now invoke it as follows: - -```terminal -npx prisma -``` - -
- -## 2. Create your Prisma ORM 2 schema - -For this guide, you'll first create a new Prisma schema using the `prisma init` command and then "fill" it with a data model using [introspection](/orm/prisma-schema/introspection). - -Run the following command to create your Prisma schema (note that this throws an error if you already have a folder called `prisma`): - -```terminal copy -npx prisma init -``` - -If you're seeing the following error, you need to rename your current `prisma` directory: - -```no-lines -ERROR A folder called prisma already exists in your project. - Please try again in a project that is not yet using Prisma. -``` - -You can rename the current `prisma` directory to `prisma1` to make it clear that this holds the former Prisma 1 configuration: - -```terminal copy -mv prisma prisma1 -``` - -Now you can run `init` and it will succeed: - -```terminal copy -npx prisma init -``` - -It should print the following output: - -```no-lines wrap -✔ Your Prisma schema was created at prisma/schema.prisma. - You can now open it in your favorite editor. - -Next steps: -1. Set the `DATABASE_URL` in the `.env` file to point to your existing database. If your database has no tables yet, read https://pris.ly/d/getting-started -2. Set the `provider` of your `datasource` block in `schema.prisma` to match your database: `postgresql`, `mysql` or `sqlite`. -3. Run `prisma db pull` to turn your database schema into a Prisma data model. -4. Run `prisma generate` to install Prisma Client. You can then start querying your database. - -More information in our documentation: -https://pris.ly/d/getting-started -``` - -The command created a new folder called `prisma`, and two files: - -- `prisma/schema.prisma`: Your Prisma schema that specifies the [data source](/orm/prisma-schema/overview/data-sources), [generator](/orm/prisma-schema/overview/generators) and [data model](/orm/prisma-schema/data-model/models) (note that the data model doesn't exist yet, it will be generated via introspection). -- `.env`: A [dotenv](https://github.com/motdotla/dotenv) file to configure your database [connection URL](/orm/reference/connection-urls). - -Your initial Prisma schema looks as follows: - -```prisma file=schema.prisma showLineNumbers -// This is your Prisma schema file, -// learn more about it in the docs: https://pris.ly/d/prisma-schema - -datasource db { - provider = "mysql" - url = env("DATABASE_URL") -} - -generator client { - provider = "prisma-client-js" -} -``` - -With Prisma 1, you specify which language variant of Prisma Client you wanted to use in your `prisma.yml`. With Prisma ORM 2, this information is now specified inside the Prisma schema via a `generator` block. - -> **Note**: Unlike Prisma 1, the TypeScript and JavaScript variants of Prisma Client 2.0 use the _same_ generator called `prisma-client-js`. The generated types in `index.d.ts` are _always_ included, even in plain JavaScript projects. This enables feature like autocompletion in VS Code even when not using TypeScript. - -## 3. Determine your connection URL and connect to your database - -With Prisma 1, the database connection is configured in the Docker Compose file that's used to launch the Prisma ORM server. The Prisma ORM server then exposes a GraphQL endpoint (via HTTP) that proxies all database requests from the Prisma Client application code. That HTTP endpoint is specified in your `prisma.yml`. - -With Prisma ORM 2, the HTTP layer isn't exposed any more and Prisma Client 2.0 is configured to run requests "directly" against the database (that is, requests are proxied by Prisma ORM's [query engine](/orm/more/under-the-hood/engines), but there isn't an extra server any more). - -So, as a next step you'll need to tell Prisma ORM 2 _what_ kind of database you use (MySQL or PostgreSQL) and _where_ it is located. - -First, you need to ensure that that `provider` field on the `datasource` block inside `schema.prisma` is configured to use the right database: - -- If you're using PostgreSQL, it needs to define the value `"postgresql"` in the `provider` field. -- If you're using MySQL, it needs to define the value `"mysql"` in the `provider` field. - -Switch around with the tabs in the code block to see examples of both: - - - - -```prisma -datasource db { - provider = "postgresql" - url = env("DATABASE_URL") -} -``` - - - - -```prisma -datasource db { - provider = "mysql" - url = env("DATABASE_URL") -} -``` - - - - -With the `provider` field set, you can go ahead and configure the connection URL inside the `.env` file. - -Assume the database configuration in your Docker Compose file that you used to deploy your Prisma ORM server looks as follows: - -```yml file=docker-compose.yml -PRISMA_CONFIG: | - port: 4466 - databases: - default: - connector: mysql - host: mysql - port: 3306 - user: root - password: randompassword -``` - -Also assume your `endpoint` in `prisma.yml` is configured as follows: - -```yml file=prisma.yml -endpoint: http://localhost:4466/myproject/dev -``` - -Based on these connection details, you need to configure the `DATABASE_URL` environment variable inside your `.env` file as follows: - -```bash file=.env -DATABASE_URL="mysql://root:randompassword@localhost:3306/myproject@dev" -``` - -Note that the _database name_ in the connection URL is typically composed of your _service name_ and _service stage_ (which are part of the `endpoint` in `prisma.yml`), separated by the `@` character. - -Sometimes no service name and stage are specified in `prisma.yml`: - -```yml file=prisma.yml -endpoint: http://localhost:4466/ -``` - -In that case, the database name must be specified as follows: - -```bash file=.env -DATABASE_URL="mysql://root:randompassword@localhost:3306/default@default" -``` - -Learn more on the [Connection URLs](/orm/reference/connection-urls) page. - -## 4. Introspect your database - -For the purpose of this guide, we'll use the following Prisma 1 data model (select the **SQL** tab below to see what the data model maps to in SQL): - - - - -```graphql -type User { - id: ID! @id - email: String @unique - name: String! - role: Role! @default(value: CUSTOMER) - jsonData: Json - profile: Profile - posts: [Post!]! -} - -type Post { - id: ID! @id - createdAt: DateTime! @createdAt - updatedAt: DateTime! @updatedAt - title: String! - content: String - published: Boolean! @default(value: false) - author: User @relation(link: TABLE) - categories: [Category!]! -} - -type Profile { - id: ID! @id - bio: String - user: User! @relation(link: INLINE) -} - -type Category { - id: ID! @id - name: String! - posts: [Post!]! -} - -enum Role { - ADMIN - CUSTOMER -} -``` - - - - -```sql -CREATE TABLE"User" ( - id character varying(25) PRIMARY KEY, - email text, - name text NOT NULL, - role text NOT NULL, - "jsonData" text -); -CREATE UNIQUE INDEX "User_pkey" ON"User"(id text_ops); -CREATE UNIQUE INDEX "default$default.User.email._UNIQUE" ON"User"(email text_ops); - -CREATE TABLE"Post" ( - id character varying(25) PRIMARY KEY, - title text NOT NULL, - published boolean NOT NULL, - "createdAt" timestamp(3) without time zone NOT NULL, - "updatedAt" timestamp(3) without time zone NOT NULL, - content text -); -CREATE UNIQUE INDEX "Post_pkey" ON"Post"(id text_ops); - -CREATE TABLE"Profile" ( - id character varying(25) PRIMARY KEY, - bio text, - user character varying(25) REFERENCES"User"(id) ON DELETE SET NULL -); -CREATE UNIQUE INDEX "Profile_pkey" ON"Profile"(id text_ops); - -CREATE TABLE"Category" ( - id character varying(25) PRIMARY KEY, - name text NOT NULL -); -CREATE UNIQUE INDEX "Category_pkey" ON"Category"(id text_ops); - -CREATE TABLE"_PostToUser" ( - "A" character varying(25) NOT NULL REFERENCES"Post"(id) ON DELETE CASCADE, - "B" character varying(25) NOT NULL REFERENCES"User"(id) ON DELETE CASCADE -); -CREATE UNIQUE INDEX "_PostToUser_AB_unique" ON"_PostToUser"("A" text_ops,"B" text_ops); -CREATE INDEX "_PostToUser_B" ON"_PostToUser"("B" text_ops); - -CREATE TABLE"_CategoryToPost" ( - "A" character varying(25) NOT NULL REFERENCES"Category"(id) ON DELETE CASCADE, - "B" character varying(25) NOT NULL REFERENCES"Post"(id) ON DELETE CASCADE -); -CREATE UNIQUE INDEX "_CategoryToPost_AB_unique" ON"_CategoryToPost"("A" text_ops,"B" text_ops); -CREATE INDEX "_CategoryToPost_B" ON"_CategoryToPost"("B" text_ops); -``` - - - - -Note that this data model has three [relations](/orm/prisma-schema/data-model/relations): - -- 1-1: `User` ↔ `Profile` -- 1-n: `User` ↔ `Post` (maintained via the `_PostToUser` relation table) -- m-n: `Post` ↔ `Category` (maintained via the `_CategoryToPost` relation table) - -Now you can run Prisma ORM's introspection against your database with the following command: - -```terminal copy -npx prisma db pull -``` - -Here's a graphical illustration for what happens when `db pull` is invoked: - -![Introspect your database](/img/orm/prisma-db-pull-generate-schema.png) - -For the above Prisma 1 datamodel, this results in the following Prisma ORM 2 schema (note that the models have been reordered to match the initial order of the Prisma 1 datamodel): - -```prisma file=schema.prisma showLineNumbers -model User { - id String @id @default(cuid()) - email String? @unique - name String - role String - jsonData String? - Profile Profile[] - Post Post[] -} - -model Post { - id String @id @default(cuid()) - createdAt DateTime - updatedAt DateTime - title String - content String? - published Boolean - Category Category[] - User User[] -} - -model Profile { - id String @id @default(cuid()) - bio String? - user String? @unique - User User? @relation(fields: [user], references: [id]) -} - -model Category { - id String @id @default(cuid()) - name String - Post Post[] -} -``` - -While this is already a valid Prisma ORM 2 schema, it lacks a number of _features_ that were part of its Prisma 1 equivalent: - -- no auto-generated date values for the `createdAt` and `updatedAt` fields on `Post` -- no default value for the `role` field on `User` -- no default value for the `published` field on `Post` - -There further are a number of inconsistencies which result in a less idiomatic/ergonomic Prisma Client API: - -- `User` ↔ `Profile` is a 1-n instead of 1-1 relation -- `User` ↔ `Post` is a m-n instead of 1-n relation -- relation fields are uppercased (e.g. `Profile` and `Post` on `User`) -- the `jsonData` field on `User` is of type `String` instead of `Json` -- the `role` field on `User` is of type `String` instead of `Role`, the `enum` definition for role is missing altogether - -While these inconsistencies don't actually impact the "feature set" you'll have available in your Prisma Client API, they make you lose certain constraints/guarantees that were present before. - -For example, Prisma ORM now won't guarantee that a `User` is connected to _at most_ one `Profile` because the relation between the tables was recognized as 1-n during introspection, so one `User` record _could_ now get connected to multiple `Profile` records. - -Another issue is that you can store whatever text for the `jsonData` and `role` fields, regardless of whether it's valid JSON or represents a value of the `Role` enum. - -To learn more about these inconsistencies check out the [Schema incompatibilities](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-mysql) page. - -In the following, we'll go through these incompatibilities and fix them one by one using the Prisma schema upgrade CLI. - -## 5. Use the Prisma schema upgrade CLI to resolve schema incompatibilities - -The [Prisma 1 Upgrade CLI](/orm/more/upgrade-guides/upgrade-from-prisma-1/how-to-upgrade#prisma-1-upgrade-cli) is an interactive tool that helps you upgrading your Prisma schema and ironing out most of the inconsistencies listed above. - -The Prisma 1 Upgrade CLI works in two major phases: - -1. Fix the database schema via plain SQL -1. Add missing attributes to the Prisma ORM 2 schema and other schema fixes - -During the first phase, it will generate and print a number of SQL statements that you should run against your database to adjust the database schema. You can either run all of the statements or a subset of them before continuing to the second phase. - -During the second phase, you don't need to do anything manually. The Upgrade CLI will make changes to your Prisma schema by adding certain Prisma ORM-level attributes (like `@default(cuid))` or `@updatedAt`), adjusting the names of relation fields to match the ones from your Prisma 1 datamodel and ensure 1-1-relations that were required on both sides in your Prisma 1 datamodel are also required in the Prisma ORM 2 schema. - -Note that **you can start over at any time during the process** and go back from the second to the first phase. - -In this illustration, the green area shows the first phase, the blue area shows the second phase. Note that you can optionally run `prisma db pull` in between the phases to update your Prisma ORM data model: - -![Fixing the schema incompatibilities](./images/fix-schema-incompatibilities.png) - -To use the Upgrade CLI, you can either install it locally in your project, or invoke it once without installation using `npx` as done here: - -```terminal copy -npx prisma-upgrade prisma1/prisma.yml prisma/schema.prisma -``` - -The CLI will greet you with the following message: - -```no-lines wrap -◮ Welcome to the interactive Prisma Upgrade CLI that helps with the -upgrade process from Prisma 1 to Prisma ORM 2. - -Please read the docs to learn more about the upgrade process: -https://pris.ly/d/how-to-upgrade - -➤ Goal -The Upgrade CLI helps you resolve the schema incompatibilities -between Prisma 1 and Prisma ORM 2. Learn more in the docs: -https://pris.ly/d/schema-incompatibilities - -➤ How it works -Throughout the process, you'll need to adjust your database schema by sending -SQL statements to it. The SQL statements are provided by the Upgrade CLI. - -Note that the Upgrade CLI never makes changes to your database, -you are in full control over any operations that are executed against it. - -You can stop and re-run the Upgrade CLI at any time. - -These are the different steps of the upgrade process: - - 1. The Upgrade CLI generates SQL commands for you to run on your database. - 2. You run the SQL commands against your database. - 3. You run the `npx prisma db pull` command again. - 4. You run the `npx prisma-upgrade` command again. - 5. The Upgrade CLI adjusts the Prisma ORM 2 schema by adding missing attributes. - -➤ Note -It is recommended that you make a full backup of your existing data before starting -the upgrade process. If possible, the migration should be performed in a staging -environment before executed against a production environment. - -➤ Help -If you have any questions or run into any problems along the way, -please create an issue at: -https://github.com/prisma/prisma1-upgrade/issues/new - -Are you ready? [Y/n] -``` - -Press the Y button, then confirm by hitting RETURN on your keyboard to continue. - -Once you confirmed, the CLI outputs the SQL statements you should be running against your database: - -```no-lines wrap -➤ Adjust your database schema -Run the following SQL statements against your database: - - Fix columns with ENUM data types - https://pris.ly/d/schema-incompatibilities#enums-are-represented-as-text-in-database - - ALTER TABLE `User` CHANGE `role` `role` ENUM('ADMIN', 'CUSTOMER') NOT NULL; - - - Add missing `DEFAULT` constraints to the database - https://pris.ly/d/schema-incompatibilities#default-values-arent-represented-in-database - - ALTER TABLE `User` CHANGE `role` `role` ENUM('ADMIN', 'CUSTOMER') NOT NULL DEFAULT 'CUSTOMER'; - ALTER TABLE `Post` CHANGE `published` `published` TINYINT(1) NOT NULL DEFAULT 0; - - - Fix columns with JSON data types - https://pris.ly/d/schema-incompatibilities#json-type-is-represented-as-text-in-database - - ALTER TABLE `User` CHANGE `jsonData` `jsonData` JSON ; - - - Replicate `@createdAt` behavior in Prisma ORM 2.0 - https://pris.ly/d/schema-incompatibilities#createdat-isnt-represented-in-database - - ALTER TABLE `Post` CHANGE `createdAt` `createdAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP; - - - Fix 1-1 relations by adding `UNIQUE` constraints - https://pris.ly/d/schema-incompatibilities#inline-1-1-relations-are-recognized-as-1-n-missing-unique-constraint - - ALTER TABLE `Profile` ADD UNIQUE (`user`); - - - Migrate IDs from varchar(25) to varchar(30) - https://pris.ly/d/schema-incompatibilities#mismatching-cuid-length - - SET FOREIGN_KEY_CHECKS=0; - ALTER TABLE `Category` CHANGE `id` `id` char(30) CHARACTER SET utf8 NOT NULL; - ALTER TABLE `Post` CHANGE `id` `id` char(30) CHARACTER SET utf8 NOT NULL; - ALTER TABLE `Profile` CHANGE `id` `id` char(30) CHARACTER SET utf8 NOT NULL; - ALTER TABLE `Profile` CHANGE `user` `user` char(30) CHARACTER SET utf8 ; - ALTER TABLE `User` CHANGE `id` `id` char(30) CHARACTER SET utf8 NOT NULL; - SET FOREIGN_KEY_CHECKS=1; - -➤ Breaking changes detected - -In order to fully optimize your database schema, you'll need to run a few SQL -statements that can break your Prisma 1 setup. Note that these changes are optional -and if you are upgrading gradually and running Prisma 1 and Prisma ORM 2 side-by-side, -you should not perform these changes yet. Instead, you can perform them whenever -you are ready to completely remove Prisma 1 from your project. -If you are upgrading all at once, you can safely perform these changes now. - -Learn more in the docs: -https://pris.ly/d/how-to-upgrade' -``` - -> **Note**: If you're seeing the note about breaking changes, you can ignore it for now. We'll discuss it later. - -The shown SQL statements are categorized into a number of "buckets", all aiming to resolve a certain [schema incompatibility](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-mysql): - -- Fix columns with ENUM data types -- Add missing `DEFAULT` constraints to the database -- Fix columns with JSON data types -- Replicate `@createdAt` behavior in Prisma 2 -- Fix 1-1 relations by adding `UNIQUE` constraints - -As a next step, you can start sending the SQL statements to your database. Note that all of these changes are non-breaking and you'll be able to continue using Prisma 1 side-by-side with Prisma ORM 2. - -The next sections cover the different kinds of SQL statements to be sent to your database individually. - -### 5.1. Fix the database schema via plain SQL (non-breaking) - -In this section, we'll walk through the printed SQL statements and run them against the database one by one. - -### 5.1.1. Fix columns with ENUM data types - -The first thing the tool does is help you ensure that `enum` definitions in your Prisma 1 datamodel will be represented as actual `ENUM` types in the underlying database, right now they are represented as plain strings (e.g. as `MEDIUMTEXT` in MySQL). - -The CLI currently shows the following output: - -```no-lines wrap -Fix columns with ENUM data types -https://pris.ly/d/schema-incompatibilities#enums-are-represented-as-text-in-database - - ALTER TABLE `User` CHANGE `role` `role` ENUM('ADMIN', 'CUSTOMER') NOT NULL; -``` - -Go ahead and run these statements against your database now. - -![Altering columns to use ENUM with SQL](./images/altering-columns-to-use-enum.png) - -### 5.1.2. Add missing `DEFAULT` constraints to the database - -Next, the Upgrade CLI helps you resolve the issue that [default values aren't represented in the database](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-mysql#default-values-arent-represented-in-database) by generating SQL statements that add the respective `DEFAULT` constraints directly to the database. - -In this case, two `DEFAULT` constraints are missing which are suggested by the tool: - -```no-lines wrap -Add missing `DEFAULT` constraints to the database -https://pris.ly/d/schema-incompatibilities#default-values-arent-represented-in-database - - ALTER TABLE `User` CHANGE `role` `role` ENUM('ADMIN', 'CUSTOMER') NOT NULL DEFAULT 'CUSTOMER'; - ALTER TABLE `Post` CHANGE `published` `published` TINYINT(1) NOT NULL DEFAULT 0; -``` - -You can now run these SQL statements against your database either using a command line client or a GUI like TablePlus: - -![TablePlus GUI](./images/TablePlus-GUI.png) - -### 5.1.3. Fix columns with JSON data types - -Next, the tool helps you ensure that `Json` fields in your Prisma 1 datamodel will be represented as `JSON` columns in the underlying database, right now they are represented as plain strings (e.g. as `MEDIUMTEXT` in MySQL). - -Changing the column type to `JSON` will ensure that the field is properly recognized as `Json` during Prisma ORM 2 introspection. - -The CLI currently shows the following output: - -```no-lines wrap -Fix columns with JSON data types -https://pris.ly/d/schema-incompatibilities#json-type-is-represented-as-text-in-database - - ALTER TABLE `User` CHANGE `jsonData` `jsonData` JSON ; -``` - -You can now run these SQL statements against your database either using a command line client or a GUI like TablePlus: - -![TablePlus GUI](./images/fix-columns-with-json-data-types.png) - -### 5.1.4. Replicate `@createdAt` behavior in Prisma ORM 2 - -The next thing the tools does is help you resolve the issue that the behavior of [`@createdAt` isn't represented in database](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-mysql#default-values-arent-represented-in-database) - -The CLI currently shows the following output: - -```no-lines wrap -Replicate `@createdAt` behavior in Prisma ORM 2.0 -https://pris.ly/d/schema-incompatibilities#createdat-isnt-represented-in-database - - ALTER TABLE `Post` CHANGE `createdAt` `createdAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP; -``` - -You can now run these SQL statements against your database either using a command line client or a GUI like TablePlus. - -### 5.1.5. Fix 1-1 relations by adding `UNIQUE` constraints - -Now, the tool will help you [turn the current 1-n relation between `User` ↔ `Profile` back into a 1-1 relation](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-mysql#inline-1-1-relations-are-recognized-as-1-n-missing-unique-constraint) by adding a `UNIQUE` constraint to the foreign key column called `user` (named after the relation field in the Prisma 1 datamodel) in the database. - -The CLI currently shows the following output: - -```no-lines wrap -Fix 1-1 relations by adding `UNIQUE` constraints -https://pris.ly/d/schema-incompatibilities#inline-1-1-relations-are-recognized-as-1-n-missing-unique-constraint - - ALTER TABLE `Profile` ADD UNIQUE (`user`); -``` - -You can now run these SQL statements against your database either using a command line client or a GUI like TablePlus. - -### 5.1.6. Fix mismatch of CUID length - -> **Note**: These SQL statements will keep appearing in the Upgrade CLI even after you have changed the column types in the underlying database. This is a currently a limitation in the Upgrade CLI. - -Finally, the tool will help you [turn the current ID columns of type `VARCHAR(25)` into `VARCHAR(30)`](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-mysql#mismatching-cuid-length) by adding a `UNIQUE` constraint to the foreign key column called `user` (named after the relation field in the Prisma 1 datamodel) in the database. - -The CLI currently shows the following output: - -```no-lines wrap -Migrate IDs from varchar(25) to varchar(30) -https://pris.ly/d/schema-incompatibilities#mismatching-cuid-length - -SET FOREIGN_KEY_CHECKS=0; -ALTER TABLE `Category` CHANGE `id` `id` char(30) CHARACTER SET utf8 NOT NULL; -ALTER TABLE `Post` CHANGE `id` `id` char(30) CHARACTER SET utf8 NOT NULL; -ALTER TABLE `Profile` CHANGE `id` `id` char(30) CHARACTER SET utf8 NOT NULL; -ALTER TABLE `Profile` CHANGE `user` `user` char(30) CHARACTER SET utf8 ; -ALTER TABLE `User` CHANGE `id` `id` char(30) CHARACTER SET utf8 NOT NULL; -SET FOREIGN_KEY_CHECKS=1; -``` - -You can now run these SQL statements against your database either using a command line client or a GUI like TablePlus. - -### 5.1.7. Breaking changes detected - -In case the Upgrade CLI has printed a note about breaking changes, your database schema needs some adjustments that will break Prisma 1 compatibility in order to be fully optimized. - -If there are no breaking changes detected, you can [skip forward to section 5.2](#52-re-introspect-your-database-to-update-your-prisma-schema) - -Depending on your [upgrade strategy](/orm/more/upgrade-guides/upgrade-from-prisma-1/how-to-upgrade#upgrade-strategies), you can either perform these changes now or skip to the next phase of the Upgrade CLI: - -- If you are following the gradual side-by-side upgrade strategy, do not perform these changes yet since they will break your Prisma 1 setup. In that case, you can continue to the next phase of the Upgrade CLI by typing n and hitting RETURN. -- If you are following the all at once upgrade strategy, you can perform these changes now. In that case, continue by typing Y and hitting RETURN. - -### 5.2. Fix the database schema via plain SQL (breaking) - -In this section, you'll resolve the schema incompatibilities that are breaking your Prisma 1 setup. Do not perform these changes if you are still running Prisma 1 in your project! - -### 5.2.1. Fix incorrect m-n relations - -Now, the Upgrade CLI helps you fix all 1-1 and 1-n relations that Prisma 1 represents with relation tables and that [currently only exist as m-n relations](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-mysql#all-non-inline-relations-are-recognized-as-m-n) in your new Prisma ORM 2 schema. Concretely, this is the case for the `User` ↔ `Post` relation which currently is defined as m-n but _should_ really be a 1-n relation. - -To fix this, you'll need to perform the following migration: - -1. Create a new foreign key column on `Post` to link directly to the `User` table. -1. Migrate the foreign key values from the relation table into the new foreign key column on `Post`. -1. Delete the relation table. - -These instructions are now printed by the CLI: - -```no-lines wrap -➤ Adjust your database schema -Run the following SQL statements against your database: - - Fix one-to-many table relations - https://pris.ly/d/schema-incompatibilities#all-non-inline-relations-are-recognized-as-m-n - - ALTER TABLE `Post` ADD COLUMN `authorId` char(25) CHARACTER SET utf8 ; - ALTER TABLE `Post` ADD CONSTRAINT author FOREIGN KEY (`authorId`) REFERENCES `User`(`id`); - UPDATE `Post`, `_PostToUser` SET `Post`.`authorId` = `_PostToUser`.B where `_PostToUser`.A = `Post`.`id`; - DROP TABLE `_PostToUser`; - - -➤ Next Steps - -After you executed one or more of the above SQL statements against your database, -please run the following two commands to refresh your Prisma ORM 2 Schema and check -the changes. - - 1. Run `npx prisma db pull` again to refresh your Prisma ORM 2 schema. - 2. Run `npx prisma-upgrade` again. - -If you can't or don't want to execute the remaining SQL statements right now, you can -skip to the last step where the Upgrade CLI adds missing attributes to your Prisma ORM 2 -schema that are not picked up by introspection. - -Skip to the last step? [Y/n]? -``` - -For this fix, you'll need to run three SQL statements: - -1. Create new column `authorId` on the `Post` table. This column should be a _foreign key_ that references the `id` field of the `User` table: - ```sql no-lines - ALTER TABLE `Post` ADD COLUMN `authorId` char(25) CHARACTER SET utf8 ; - ALTER TABLE `Post` ADD CONSTRAINT author FOREIGN KEY (`authorId`) REFERENCES `User`(`id`); - ``` -1. Write a SQL query that reads all the rows from the `_PostToUser` relation table and for each row: - 1. Finds the respective `Post` record by looking up the value from column `A` - 1. Inserts the value from column `B` as the value for `authorId` into that `Post` record - ```sql no-lines - UPDATE `Post`, `_PostToUser` SET `Post`.`authorId` = `_PostToUser`.B where `_PostToUser`.A = `Post`.`id`; - ``` -1. Delete the `_PostToUser` relation table - ```sql no-lines - DROP TABLE `_PostToUser`; - ``` - -![Fixing incorrect m-n relations with SQL](./images/fix-incorrect-m-n-relations-sql.png) - -After these commands, the user ID values of the records from column `B` of the relation table are migrated to the new `authorId` column. - -### 5.2. Re-introspect your database to update your Prisma schema - -At this point, you've resolved the schema incompatibilities with the Upgrade CLI. You can now exit the Upgrade CLI for now by typing n and hitting RETURN. - -In this section, you'll update your Prisma schema with another introspection round. This time, the previous flaws of the Prisma schema will be resolved because the database schema has been adjusted: - -```terminal copy -npx prisma db pull -``` - -This time, the resulting Prisma schema looks as follows: - -```prisma file=schema.prisma showLineNumbers -model User { - id String @id - name String - email String? @unique - jsonData Json? - role Role @default(CUSTOMER) - Post Post[] - Profile Profile? -} - -model Post { - id String @id - createdAt DateTime @default(now()) - updatedAt DateTime - title String - content String? - published Boolean @default(false) - authorId String? - User User? @relation(fields: [authorId], references: [id]) - Category Category[] @relation(references: [id]) -} - -model Category { - id String @id - name String - Post Post[] @relation(references: [id]) -} - -model Profile { - bio String? - id String @id - user String? @unique - User User? @relation(fields: [user], references: [id]) -} - -enum Role { - ADMIN - CUSTOMER -} -``` - -This schema has most issues resolved, but it still lacks the following: - -### 5.2. Add missing attributes to the Prisma 2 schema and other schema fixes - -The CLI now prints the following: - -```no-lines wrap -➤ What happens next -As a last step, some final adjustments will be made to your Prisma ORM 2 schema -to carry over some Prisma ORM-level attributes that aren't picked up by introspection. - -As a last step, some final adjustments will be made to your Prisma ORM 2.0 -schema to carry over some Prisma ORM-level attributes that aren't picked -up by introspection. - -Warning -Your current Prisma ORM 2.0 schema will be overwritten, so please -make sure you have a backup! - -Are you ready? [Y/n] -``` - -At this point, you either ran all the SQL statement that were printed by the CLI or you skipped some of them. Either way, you can now move on the last step and let the Upgrade CLI add the missing Prisma ORM 2 attributes. Typically these are the following: - -- `@default(cuid())` for your `@id` fields -- `@updatedAt` for any fields that were using this attribute in Prisma 1 -- `@map` and `@@map` as replacements for `@db` and `@@db` from Prisma 1 - -In that step, the Upgrade CLI also fixes other issues that occurred in the transition to Prisma ORM 2: - -- it makes sure that 1-1-relations that were required on both sides in Prisma 1 are also required in your Prisma ORM 2 schema -- it renames relation fields to the same names they had in your Prisma 1 datamodel ([coming soon](https://github.com/prisma/prisma1-upgrade/issues/25)) - -To apply these changes, you can re-run the Upgrade CLI: - -```terminal copy -npx prisma-upgrade prisma1/prisma.yml prisma/schema.prisma -``` - -If you did not resolve all schema incompatibilities, the Upgrade CLI now prints the remaining SQL statements (as well as the ones for migrating IDs). You can just ignore them at this point and continue to the last step by continuously typing Y and hitting RETURN when prompted. - -If you did resolve all schema incompatibilities, no SQL statements will be printed and the Upgrade CLI only outputs the following: - -```no-lines wrap -$ npx prisma-upgrade prisma1/prisma.yml prisma/schema.prisma - -➤ Next Steps - -After you executed one or more of the previous SQL statements against your database, -please run the following two commands to refresh your Prisma ORM 2 schema and check -the changes. - - 1. Run `npx prisma db pull` again to refresh your Prisma ORM 2 schema. - 2. Run `npx prisma-upgrade` again. - -If you can't or don't want to execute the remaining SQL statements right now, you can -skip to the last step where the Upgrade CLI adds missing attributes to your Prisma ORM 2 -schema that are not picked up by introspection. - -Skip to the last step? [Y/n]? -``` - -One more time, type Y and hit RETURN to confirm. - -The final prompt of the Upgrade CLI now asks you to confirm the above mentioned changes it will make to your Prisma schema: - -```no-lines wrap -➤ What happens next -As a last step, some final adjustments will be made to your Prisma ORM 2 schema -to carry over some Prisma ORM-level attributes that aren't picked up by introspection. - -As a last step, some final adjustments will be made to your Prisma ORM 2.0 -schema to carry over some Prisma ORM-level attributes that aren't picked -up by introspection. - -Warning -Your current Prisma ORM 2.0 schema will be overwritten, so please -make sure you have a backup! - -Are you ready? [Y/n] -``` - -One last time, type Y and hit RETURN to confirm. - -This is the final output of the Upgrade CLI: - -```no-lines -Updating prisma/schema.prisma... -Done updating prisma/schema.prisma! - -✔ Congratulations, you're all set! - -➤ Note -If you didn't execute all generated SQL commands against your database, -you can re-run the Upgrade CLI at any time. - -Note that the Upgrade CLI doesn't resolve all of the schema incompatibilities -between Prisma 1 and Prisma ORM 2. If you want to resolve the remaining ones, -you can do so manually by following this guide: -https://pris.ly/d/upgrading-the-prisma-layer - -➤ Next steps -Otherwise you can continue your upgrade process by installing Prisma Client 2: -npm install @prisma/client - -You can find guides for different upgrade scenarios in the docs: -https://pris.ly/d/upgrade-from-prisma-1 -``` - -### 5.3. Final result - -The final version of the Prisma schema should look as follows: - -```prisma file=schema.prisma showLineNumbers -model User { - id String @id @default(cuid()) - name String - email String? @unique - jsonData Json? - role Role @default(CUSTOMER) - Post Post[] - Profile Profile? -} - -model Post { - id String @id @default(cuid()) - createdAt DateTime @default(now()) - updatedAt DateTime @updatedAt - title String - content String? - published Boolean @default(false) - authorId String? - User User? @relation(fields: [authorId], references: [id]) - Category Category[] @relation(references: [id]) -} - -model Profile { - id String @id @default(cuid()) - bio String? - user String? @unique - User User? @relation(fields: [user], references: [id]) -} - -model Category { - id String @id @default(cuid()) - name String - Post Post[] @relation(references: [id]) -} - -enum Role { - ADMIN - CUSTOMER -} -``` - -### 5.4. Rename relation fields - -One thing you'll notice with this version of the Prisma ORM 2 schema is that all [relation fields](/orm/prisma-schema/data-model/relations#relation-fields) are named after their respective models, e.g: - -```prisma file=schema.prisma showLineNumbers -model User { - Post Post[] - Profile Profile? -} - -model Post { - User User? @relation(fields: [authorId], references: [id]) - Category Category[] @relation(references: [id]) -} - -model Profile { - User User? @relation(fields: [user], references: [id]) -} - -model Category { - Post Post[] @relation(references: [id]) -} -``` - -This is not ideal and you can in fact manually rename all of them to their previous versions! - -Because all relation fields are _virtual_, meaning they don't _manifest_ in the database, you can name them whatever you like. In this case, all relation fields are lowercased and sometimes pluralized. - -Here's what they look like after the rename: - -```prisma file=schema.prisma showLineNumbers -model User { - posts Post[] - profile Profile? -} - -model Post { - author User? @relation(fields: [authorId], references: [id]) - categories Category[] @relation(references: [id]) -} - -model Profile { - user String? @unique - owner User? @relation(fields: [user], references: [id]) -} - -model Category { - posts Post[] @relation(references: [id]) -} -``` - -> **Note**: For the 1-1-relation between `User` and `Profile` it was not possible to set the old name `user` for the relation field. This is because there'd be a naming conflict with the already existing [relation scalar](/orm/prisma-schema/data-model/relations#annotated-relation-fields) field that holds the foreign key. In that case, you can choose a different name or alternatively rename the foreign key column directly in the database via SQL. - -### 5.5. Resolving remaining schema incompatibilities - -There are a few schema incompatibilities that were not yet resolved by the Upgrade CLI. At this point you still haven't fixed [scalar lists](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-mysql#scalar-lists-arrays-are-maintained-with-extra-table). You can find the recommended workarounds for this and others on the [Schema incompatibilities](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-mysql) page. - -## 6. Install and generate Prisma Client - -Now that you have your Prisma ORM 2 schema ready, you can install Prisma Client with the following command: - -```terminal copy -npm install @prisma/client -``` - -## 7. Next steps - -Congratulations, you have now upgraded your Prisma ORM layer to Prisma ORM 2! From here on, you can move on to update your application code using one of the following guides: - -- [Old to new Nexus](/orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-nexus-prisma-to-nexus): Choose this guide if you're currently running Prisma 1 with GraphQL Nexus. -- [prisma-binding to Nexus](/orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-prisma-binding-to-nexus): Choose this guide if you're currently running Prisma 1 with `prisma-binding` and want to upgrade to [Nexus](https://nexusjs.org/) (and TypeScript). -- [prisma-binding to SDL-first](/orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-prisma-binding-to-sdl-first): Choose this guide if you're currently running Prisma 1 with `prisma-binding` and want to upgrade to an [SDL-first](https://www.prisma.io/blog/the-problems-of-schema-first-graphql-development-x1mn4cb0tyl3) GraphQL server. -- [REST API](/orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-a-rest-api): Choose this guide if you're currently running Prisma 1 using Prisma Client 1 and are building a REST API. - -## Bonus: Prisma Client API comparison - -This section contains a high-level and side-by-side comparison of the Prisma Client APIs of Prisma 1 and Prisma ORM 2. For more details about the new Prisma Client API, you can explore the [Prisma Client](/orm/prisma-client) docs. - -### Reading single records - - - - - -```ts -const user = await prisma.user({ id: 1 }) -``` - - - - - -```ts -await prisma.user.findUnique({ - where: { id: 1 }, -}) -``` - - - - - -### Reading lists of records - - - - - -```ts -const user = await prisma.users() -``` - - - - - -```ts -await prisma.user.findMany() -``` - - - - - -### Filtering lists - - - - - -```ts -const users = await prisma.users({ - where: { - name: 'Alice', - }, -}) -``` - - - - - -```ts -await prisma.user.findMany({ - where: { - name: 'Alice', - }, -}) -``` - - - - - -### Paginating lists - - - - - -```ts -const posts = await prisma.posts({ - skip: 5, - first: 10, -}) -``` - - - - - -```ts -await prisma.user.findMany({ - skip: 5, - take: 10, -}) -``` - - - - - -> **Note**: You can learn more about the new pagination API in the respective [release notes](https://github.com/prisma/prisma/releases/tag/2.0.0-beta.7) or the [Pagination](/orm/prisma-client/queries/pagination) page in the docs. - -### Sorting lists - - - - - -```ts -await prisma.posts({ - orderBy: 'title_ASC', -}) -``` - - - - - -```ts -await prisma.posts({ - orderBy: { - title: 'asc', - }, -}) -``` - - - - - -### Creating records - - - - - -```ts -await prisma.createUser({ - name: 'Alice', -}) -``` - - - - - -```ts -await prisma.user.create({ - data: { - name: 'Alice', - }, -}) -``` - - - - - -### Updating records - - - - - -```ts -await prisma.updateUser({ - where: { id: 1 }, - data: { - name: 'James', - email: 'james@prisma.io', - }, -}) -``` - - - - - -```ts -await prisma.user.update({ - where: { id: 1 }, - data: { - name: 'James', - email: 'james@prisma.io', - }, -}) -``` - - - - - -### Deleting records - - - - - -```ts -await prisma.deleteUser({ id: 1 }) -``` - - - - - -```ts -await prisma.user.delete({ - where: { id: 1 }, -}) -``` - - - - - -### Selecting fields & loading relations - -In Prisma 1, the only ways to select specific fields and/or load relations of an object was by using the string-based `$fragment` and `$graphql` functions. With Prisma ORM 2, this is now done in a clean and type-safe manner using [`select`](/orm/prisma-client/queries/select-fields#select-specific-fields) and [`include`](/orm/prisma-client/queries/select-fields#return-nested-objects-by-selecting-relation-fields). - -Another benefit of this approach is that you can use `select` and `include` on _any_ Prisma Client query, e.g. `findUnique`, `findMany`, `create`, `update`, `delete`, ... - - - - - -```ts -await prisma.user({ id: 1 }).$fragment(` - fragment NameAndEmail on User { id email }` -`) -``` - - - - - -```ts -await prisma.user.findUnique({ - where: { id: 1 }, - select: { - id: true, - email: true, - }, -}) -``` - - - - - -As an example, creating a new record and only retrieving the `id` in the returned object was not possible in Prisma 1. With Prisma ORM 2 you can achieve this as follows: - -```ts -await prisma.user.create({ - data: { - name: 'Alice', - }, - select: { - id: true, - }, -}) -``` diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/03-upgrading-the-prisma-layer-postgresql.mdx b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/03-upgrading-the-prisma-layer-postgresql.mdx deleted file mode 100644 index 0de7156769..0000000000 --- a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/03-upgrading-the-prisma-layer-postgresql.mdx +++ /dev/null @@ -1,1321 +0,0 @@ ---- -title: 'Upgrading the Prisma ORM layer' -metaTitle: 'Upgrading the Prisma ORM layer to Prisma ORM 2 | PostgreSQL' -metaDescription: 'Learn how to upgrade the Prisma ORM layer to Prisma ORM 2 and create your Prisma schema with PostgreSQL' -dbSwitcher: ['postgresql', 'mysql'] -pagination_next: orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-nexus-prisma-to-nexus -slugSwitch: /orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-the-prisma-layer- ---- - -## Overview - -This page explains the first step of your upgrade process: Taking your Prisma 1 configuration and upgrading it to Prisma ORM 2. Concretely, you will learn how to: - -1. Add the Prisma ORM 2 CLI as a development dependency -1. Create your Prisma ORM 2 schema -1. Determine your connection URL and connect to your database -1. Introspect your database (that was so far managed with Prisma 1) -1. Use the [Prisma 1 Upgrade CLI](/orm/more/upgrade-guides/upgrade-from-prisma-1/how-to-upgrade#prisma-1-upgrade-cli) to resolve the [schema incompatibilities](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-postgresql) in the new Prisma ORM 2 data model -1. Install and generate Prisma Client - -Once done with these steps, you can move on to the next guide that explains how you can upgrade the application layer to use Prisma Client for your database queries. - -> **Note**: During the upgrade process it can be helpful to get a graphical view on your database. It is therefore recommended to use a graphical database client to connect to your database, such as [TablePlus](https://tableplus.com/) or [Postico](https://eggerapps.at/postico/). - -## 1. Install Prisma ORM 2 CLI - -The Prisma ORM 2 CLI is available as the [`prisma`](https://www.npmjs.com/package/prisma) package on npm and is invoked via the `prisma` command. - -Note that the former `prisma` command for Prisma 1 has been renamed to `prisma1`. You can learn more about this [here](https://www.prisma.io/blog/prisma-2-beta-b7bcl0gd8d8e#renaming-the-prisma2-cli). - -You can install the Prisma ORM 2 CLI in your Node.js project as follows (be sure to invoke this command in the directory where your `package.json` is located): - -```terminal copy -npm install prisma --save-dev -``` - -> **Note**: With Prisma 1, it was usually recommended to install the CLI globally. We now recommend to [install the Prisma CLI locally](/orm/tools/prisma-cli#installation) to prevent version conflicts. - -You can now use the local installation of the `prisma` CLI by prefixing it with `npx`: - -```terminal -npx prisma -``` - -If you're upgrading your entire project [all at once](/orm/more/upgrade-guides/upgrade-from-prisma-1/how-to-upgrade#upgrade-strategies), you can now also uninstall the Prisma 1 CLI (otherwise expand below): - -```terminal -# remove global installation -npm uninstall -g prisma1 - -# remove local installation -npm uninstall prisma1 -``` - -
- -
- -Expand if you want to keep using your Prisma 1 CLI side-by-side - -If you want to keep using the Prisma 1 CLI, it is recommend to remove your global installation of it and add the `prisma1` CLI as a development dependency: - -```terminal -# installs v1.34 of the Prisma 1 CLI -npm uninstall -g prisma -npm install prisma1 --save-dev -``` - -You can now invoke it as follows: - -```terminal -npx prisma1 -``` - -Note that if you need a CLI version smaller than 1.34 (e.g. 1.30), you can install it as follows: - -```terminal -# installs v1.30 of the Prisma 1 CLI -npm uninstall -g prisma@1.30 -npm install prisma@1.30 --save-dev -``` - -You can now invoke it as follows: - -```terminal -npx prisma -``` - -
- -## 2. Create your Prisma ORM 2 schema - -For this guide, you'll first create a new Prisma schema using the `prisma init` command and then "fill" it with a data model using [introspection](/orm/prisma-schema/introspection). - -Run the following command to create your Prisma schema (note that this throws an error if you already have a folder called `prisma`): - -```terminal copy -npx prisma init -``` - -If you're seeing the following error, you need to rename your current `prisma` directory: - -```no-lines -ERROR A folder called prisma already exists in your project. - Please try again in a project that is not yet using Prisma. -``` - -You can rename the current `prisma` directory to `prisma1` to make it clear that this holds the former Prisma 1 configuration: - -```terminal copy -mv prisma prisma1 -``` - -Now you can run `init` and it will succeed: - -```terminal copy -npx prisma init -``` - -It should print the following output: - -```no-lines wrap -✔ Your Prisma schema was created at prisma/schema.prisma. - You can now open it in your favorite editor. - -Next steps: -1. Set the `DATABASE_URL` in the `.env` file to point to your existing database. If your database has no tables yet, read https://pris.ly/d/getting-started -2. Set the `provider` of your `datasource` block in `schema.prisma` to match your database: `postgresql`, `mysql` or `sqlite`. -3. Run `prisma db pull` to turn your database schema into a Prisma data model. -4. Run `prisma generate` to install Prisma Client. You can then start querying your database. - -More information in our documentation: -https://pris.ly/d/getting-started -``` - -The command created a new folder called `prisma`, and two files: - -- `prisma/schema.prisma`: Your Prisma schema that specifies the [data source](/orm/prisma-schema/overview/data-sources), [generator](/orm/prisma-schema/overview/generators) and [data model](/orm/prisma-schema/data-model/models) (note that the data model doesn't exist yet, it will be generated via introspection). -- `.env`: A [dotenv](https://github.com/motdotla/dotenv) file to configure your database [connection URL](/orm/reference/connection-urls). - -Your initial Prisma schema looks as follows: - -```prisma file=schema.prisma showLineNumbers -// This is your Prisma schema file, -// learn more about it in the docs: https://pris.ly/d/prisma-schema - -datasource db { - provider = "postgresql" - url = env("DATABASE_URL") -} - -generator client { - provider = "prisma-client-js" -} -``` - -With Prisma 1, you specify which language variant of Prisma Client you wanted to use in your `prisma.yml`. With Prisma ORM 2, this information is now specified inside the Prisma schema via a `generator` block. - -> **Note**: Unlike Prisma 1, the TypeScript and JavaScript variants of Prisma Client 2.0 use the _same_ generator called `prisma-client-js`. The generated types in `index.d.ts` are _always_ included, even in plain JavaScript projects. This enables feature like autocompletion in VS Code even when not using TypeScript. - -## 3. Determine your connection URL and connect to your database - -With Prisma 1, the database connection is configured in the Docker Compose file that's used to launch the Prisma ORM server. The Prisma ORM server then exposes a GraphQL endpoint (via HTTP) that proxies all database requests from the Prisma Client application code. That HTTP endpoint is specified in your `prisma.yml`. - -With Prisma ORM 2, the HTTP layer isn't exposed any more and Prisma Client 2.0 is configured to run requests "directly" against the database (that is, requests are proxied by Prisma ORM's [query engine](/orm/more/under-the-hood/engines), but there isn't an extra server any more). - -So, as a next step you'll need to tell Prisma ORM 2 _what_ kind of database you use (MySQL or PostgreSQL) and _where_ it is located. - -First, you need to ensure that that `provider` field on the `datasource` block inside `schema.prisma` is configured to use the right database: - -- If you're using PostgreSQL, it needs to define the value `"postgresql"` in the `provider` field. -- If you're using MySQL, it needs to define the value `"mysql"` in the `provider` field. - -Switch around with the tabs in the code block to see examples of both: - - - - -```prisma -datasource db { - provider = "postgresql" - url = env("DATABASE_URL") -} -``` - - - - -```prisma -datasource db { - provider = "mysql" - url = env("DATABASE_URL") -} -``` - - - - -With the `provider` field set, you can go ahead and configure the connection URL inside the `.env` file. - -Assume the database configuration in your Docker Compose file that you used to deploy your Prisma ORM server looks as follows: - -```yml file=docker-compose.yml showLineNumbers -PRISMA_CONFIG: | - port: 4466 - databases: - default: - connector: postgres - host: postgres - port: 5432 - user: prisma - password: prisma -``` - -Also assume your `endpoint` in `prisma.yml` is configured as follows: - -```yml file=prisma.yml -endpoint: http://localhost:4466/myproject/dev -``` - -Based on these connection details, you need to configure the `DATABASE_URL` environment variable inside your `.env` file as follows: - -```bash file=.env -DATABASE_URL="postgresql://janedoe:randompassword@localhost:5432/prisma?schema=myproject$dev" -``` - -Note that the `schema` argument is typically composed of your _service name_ and _service stage_ (which are part of the `endpoint` in `prisma.yml`), separated by the `$` character. - -Sometimes no service name and stage are specified in `prisma.yml`: - -```yml file=prisma.yml -endpoint: http://localhost:4466/ -``` - -In that case, the `schema` must be specified as follows: - -```bash file=.env -DATABASE_URL="postgresql://janedoe:randompassword@localhost:5432/prisma?schema=default$default" -``` - -Learn more on the [Connection URLs](/orm/reference/connection-urls) page. - -## 4. Introspect your database - -For the purpose of this guide, we'll use the following Prisma 1 data model (select the **SQL** tab below to see what the data model maps to in SQL): - - - - -```graphql -type User { - id: ID! @id - email: String @unique - name: String! - role: Role! @default(value: CUSTOMER) - jsonData: Json - profile: Profile - posts: [Post!]! -} - -type Post { - id: ID! @id - createdAt: DateTime! @createdAt - updatedAt: DateTime! @updatedAt - title: String! - content: String - published: Boolean! @default(value: false) - author: User @relation(link: TABLE) - categories: [Category!]! -} - -type Profile { - id: ID! @id - bio: String - user: User! @relation(link: INLINE) -} - -type Category { - id: ID! @id - name: String! - posts: [Post!]! -} - -enum Role { - ADMIN - CUSTOMER -} -``` - - - - -```sql -CREATE TABLE"User" ( - id character varying(25) PRIMARY KEY, - email text, - name text NOT NULL, - role text NOT NULL, - "jsonData" text -); -CREATE UNIQUE INDEX "User_pkey" ON"User"(id text_ops); -CREATE UNIQUE INDEX "default$default.User.email._UNIQUE" ON"User"(email text_ops); - -CREATE TABLE"Post" ( - id character varying(25) PRIMARY KEY, - title text NOT NULL, - published boolean NOT NULL, - "createdAt" timestamp(3) without time zone NOT NULL, - "updatedAt" timestamp(3) without time zone NOT NULL, - content text -); -CREATE UNIQUE INDEX "Post_pkey" ON"Post"(id text_ops); - -CREATE TABLE"Profile" ( - id character varying(25) PRIMARY KEY, - bio text, - user character varying(25) REFERENCES"User"(id) ON DELETE SET NULL -); -CREATE UNIQUE INDEX "Profile_pkey" ON"Profile"(id text_ops); - -CREATE TABLE"Category" ( - id character varying(25) PRIMARY KEY, - name text NOT NULL -); -CREATE UNIQUE INDEX "Category_pkey" ON"Category"(id text_ops); - -CREATE TABLE"_PostToUser" ( - "A" character varying(25) NOT NULL REFERENCES"Post"(id) ON DELETE CASCADE, - "B" character varying(25) NOT NULL REFERENCES"User"(id) ON DELETE CASCADE -); -CREATE UNIQUE INDEX "_PostToUser_AB_unique" ON"_PostToUser"("A" text_ops,"B" text_ops); -CREATE INDEX "_PostToUser_B" ON"_PostToUser"("B" text_ops); - -CREATE TABLE"_CategoryToPost" ( - "A" character varying(25) NOT NULL REFERENCES"Category"(id) ON DELETE CASCADE, - "B" character varying(25) NOT NULL REFERENCES"Post"(id) ON DELETE CASCADE -); -CREATE UNIQUE INDEX "_CategoryToPost_AB_unique" ON"_CategoryToPost"("A" text_ops,"B" text_ops); -CREATE INDEX "_CategoryToPost_B" ON"_CategoryToPost"("B" text_ops); -``` - - - - -Note that this data model has three [relations](/orm/prisma-schema/data-model/relations): - -- 1-1: `User` ↔ `Profile` -- 1-n: `User` ↔ `Post` (maintained via the `_PostToUser` relation table) -- m-n: `Post` ↔ `Category` (maintained via the `_CategoryToPost` relation table) - -Now you can run Prisma ORM's introspection against your database with the following command: - -```terminal copy -npx prisma db pull -``` - -Here's a graphical illustration for what happens when `db pull` is invoked: - -![Introspect your database](/img/orm/prisma-db-pull-generate-schema.png) - -For the above Prisma 1 datamodel, this results in the following Prisma ORM 2 schema (note that the models have been reordered to match the initial order of the Prisma 1 datamodel): - -```prisma file=schema.prisma showLineNumbers -model User { - id String @id @default(cuid()) - email String? @unique - name String - role String - jsonData String? - Profile Profile[] - Post Post[] -} - -model Post { - id String @id @default(cuid()) - createdAt DateTime - updatedAt DateTime - title String - content String? - published Boolean - Category Category[] - User User[] -} - -model Profile { - id String @id @default(cuid()) - bio String? - user String? @unique - User User? @relation(fields: [user], references: [id]) -} - -model Category { - id String @id @default(cuid()) - name String - Post Post[] -} -``` - -While this is already a valid Prisma ORM 2 schema, it lacks a number of _features_ that were part of its Prisma 1 equivalent: - -- no auto-generated date values for the `createdAt` and `updatedAt` fields on `Post` -- no default value for the `role` field on `User` -- no default value for the `published` field on `Post` - -There further are a number of inconsistencies which result in a less idiomatic/ergonomic Prisma Client API: - -- `User` ↔ `Profile` is a 1-n instead of 1-1 relation -- `User` ↔ `Post` is a m-n instead of 1-n relation -- relation fields are uppercased (e.g. `Profile` and `Post` on `User`) -- the `jsonData` field on `User` is of type `String` instead of `Json` -- the `role` field on `User` is of type `String` instead of `Role`, the `enum` definition for role is missing altogether - -While these inconsistencies don't actually impact the "feature set" you'll have available in your Prisma Client API, they make you lose certain constraints/guarantees that were present before. - -For example, Prisma ORM now won't guarantee that a `User` is connected to _at most_ one `Profile` because the relation between the tables was recognized as 1-n during introspection, so one `User` record _could_ now get connected to multiple `Profile` records. - -Another issue is that you can store whatever text for the `jsonData` and `role` fields, regardless of whether it's valid JSON or represents a value of the `Role` enum. - -To learn more about these inconsistencies check out the [Schema incompatibilities](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-postgresql) page. - -In the following, we'll go through these incompatibilities and fix them one by one using the Prisma schema upgrade CLI. - -## 5. Use the Prisma schema upgrade CLI to resolve schema incompatibilities - -The [Prisma 1 Upgrade CLI](/orm/more/upgrade-guides/upgrade-from-prisma-1/how-to-upgrade#prisma-1-upgrade-cli) is an interactive tool that helps you upgrading your Prisma schema and ironing out most of the inconsistencies listed above. - -The Prisma 1 Upgrade CLI works in two major phases: - -1. Fix the database schema via plain SQL -1. Add missing attributes to the Prisma ORM 2 schema and other schema fixes - -During the first phase, it will generate and print a number of SQL statements that you should run against your database to adjust the database schema. You can either run all of the statements or a subset of them before continuing to the second phase. - -During the second phase, you don't need to do anything manually. The Upgrade CLI will make changes to your Prisma schema by adding certain Prisma ORM-level attributes (like `@default(cuid))` or `@updatedAt`), adjusting the names of relation fields to match the ones from your Prisma 1 datamodel and ensure 1-1-relations that were required on both sides in your Prisma 1 datamodel are also required in the Prisma ORM 2 schema. - -Note that **you can start over at any time during the process** and go back from the second to the first phase. - -In this illustration, the green area shows the first phase, the blue area shows the second phase. Note that you can optionally run `prisma db pull` in between the phases to update your Prisma ORM data model: - -![Fixing the schema incompatibilities](./images/fix-schema-incompatibilities.png) - -To use the Upgrade CLI, you can either install it locally in your project, or invoke it once without installation using `npx` as done here: - -```terminal copy -npx prisma-upgrade prisma1/prisma.yml prisma/schema.prisma -``` - -The CLI will greet you with the following message: - -```no-lines wrap -◮ Welcome to the interactive Prisma Upgrade CLI that helps with the -upgrade process from Prisma 1 to Prisma ORM 2. - -Please read the docs to learn more about the upgrade process: -https://pris.ly/d/how-to-upgrade - -➤ Goal -The Upgrade CLI helps you resolve the schema incompatibilities -between Prisma 1 and Prisma ORM 2. Learn more in the docs: -https://pris.ly/d/schema-incompatibilities - -➤ How it works -Throughout the process, you'll need to adjust your database schema by sending -SQL statements to it. The SQL statements are provided by the Upgrade CLI. - -Note that the Upgrade CLI never makes changes to your database, -you are in full control over any operations that are executed against it. - -You can stop and re-run the Upgrade CLI at any time. - -These are the different steps of the upgrade process: - - 1. The Upgrade CLI generates SQL commands for you to run on your database. - 2. You run the SQL commands against your database. - 3. You run the `npx prisma db pull` command again. - 4. You run the `npx prisma-upgrade` command again. - 5. The Upgrade CLI adjusts the Prisma ORM 2 schema by adding missing attributes. - -➤ Note -It is recommended that you make a full backup of your existing data before starting -the upgrade process. If possible, the migration should be performed in a staging -environment before executed against a production environment. - -➤ Help -If you have any questions or run into any problems along the way, -please create an issue at: -https://github.com/prisma/prisma1-upgrade/issues - -Are you ready? [Y/n] -``` - -Press the Y button, then confirm by hitting RETURN on your keyboard to continue. - -Once you confirmed, the CLI outputs the SQL statements you should be running against your database: - -```no-lines wrap -➤ Adjust your database schema -Run the following SQL statements against your database: - - Fix columns with ENUM data types - https://pris.ly/d/schema-incompatibilities#enums-are-represented-as-text-in-database - - CREATE TYPE "default$default"."Role" AS ENUM ('ADMIN', 'CUSTOMER'); - ALTER TABLE "default$default"."User" ALTER COLUMN "role" SET DATA TYPE "default$default"."Role" using "role"::"default$default"."Role"; - - - Add missing `DEFAULT` constraints to the database - https://pris.ly/d/schema-incompatibilities#default-values-arent-represented-in-database - - ALTER TABLE "default$default"."User" ALTER COLUMN "role" SET DEFAULT 'CUSTOMER'; - ALTER TABLE "default$default"."Post" ALTER COLUMN "published" SET DEFAULT false; - - - Fix columns with JSON data types - https://pris.ly/d/schema-incompatibilities#json-type-is-represented-as-text-in-database - - ALTER TABLE "default$default"."User" ALTER COLUMN "jsonData" SET DATA TYPE JSONB USING "jsonData"::TEXT::JSONB; - - - Replicate `@createdAt` behavior in Prisma ORM 2 - https://pris.ly/d/schema-incompatibilities#createdat-isnt-represented-in-database - - ALTER TABLE "default$default"."Post" ALTER COLUMN "createdAt" SET DEFAULT CURRENT_TIMESTAMP; - - - Fix 1-1 relations by adding `UNIQUE` constraints - https://pris.ly/d/schema-incompatibilities#inline-1-1-relations-are-recognized-as-1-n-missing-unique-constraint - - ALTER TABLE "default$default"."Profile" ADD UNIQUE ("user"); - - - Migrate IDs from varchar(25) to varchar(30) - https://pris.ly/d/schema-incompatibilities#mismatching-cuid-length - - ALTER TABLE "default$default"."Category" ALTER COLUMN "id" SET DATA TYPE character varying(30); - ALTER TABLE "default$default"."Post" ALTER COLUMN "id" SET DATA TYPE character varying(30); - ALTER TABLE "default$default"."Profile" ALTER COLUMN "id" SET DATA TYPE character varying(30); - ALTER TABLE "default$default"."Profile" ALTER COLUMN "user" SET DATA TYPE character varying(30); - ALTER TABLE "default$default"."User" ALTER COLUMN "id" SET DATA TYPE character varying(30); - -➤ Breaking changes detected - -In order to fully optimize your database schema, you'll need to run a few SQL -statements that can break your Prisma 1 setup. Note that these changes are optional -and if you are upgrading gradually and running Prisma 1 and Prisma ORM 2 side-by-side, -you should not perform these changes yet. Instead, you can perform them whenever -you are ready to completely remove Prisma 1 from your project. -If you are upgrading all at once, you can safely perform these changes now. - -Learn more in the docs: -https://pris.ly/d/how-to-upgrade' -``` - -> **Note**: If you're seeing the note about breaking changes, you can ignore it for now. We'll discuss it later. - -The shown SQL statements are categorized into a number of "buckets", all aiming to resolve a certain [schema incompatibility](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-postgresql): - -- Fix columns with ENUM data types -- Add missing `DEFAULT` constraints to the database -- Fix columns with JSON data types -- Replicate `@createdAt` behavior in Prisma 2 -- Fix 1-1 relations by adding `UNIQUE` constraints - -As a next step, you can start sending the SQL statements to your database. Note that all of these changes are non-breaking and you'll be able to continue using Prisma 1 side-by-side with Prisma ORM 2. - -The next sections cover the different kinds of SQL statements to be sent to your database individually. - -### 5.1. Fix the database schema via plain SQL (non-breaking) - -In this section, we'll walk through the printed SQL statements and run them against the database one by one. - -### 5.1.1. Fix columns with ENUM data types - -The first thing the tool does is help you ensure that `enum` definitions in your Prisma 1 datamodel will be represented as actual `ENUM` types in the underlying database, right now they are represented as plain strings (e.g. as `MEDIUMTEXT` in MySQL). - -The CLI currently shows the following output: - -```no-lines wrap -Fix columns with ENUM data types -https://pris.ly/d/schema-incompatibilities#enums-are-represented-as-text-in-database - - CREATE TYPE "default$default"."Role" AS ENUM ('ADMIN', 'CUSTOMER'); - ALTER TABLE "default$default"."User" ALTER COLUMN "role" SET DATA TYPE "default$default"."Role" using "role"::"default$default"."Role"; -``` - -> **⚠️ Warning**: If you are running Prisma 1 and Prisma ORM 2 [side-by-side](/orm/more/upgrade-guides/upgrade-from-prisma-1/how-to-upgrade#upgrade-strategies), these [SQL statements will break your Prisma 1 setup](https://github.com/prisma/prisma1-upgrade/issues/74). The docs will be updated to reflect this soon. - -Go ahead and run these statements against your database now. - -![Altering columns to use ENUM with SQL](./images/altering-columns-to-use-enum.png) - -### 5.1.2. Add missing `DEFAULT` constraints to the database - -Next, the Upgrade CLI helps you resolve the issue that [default values aren't represented in the database](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-postgresql#default-values-arent-represented-in-database) by generating SQL statements that add the respective `DEFAULT` constraints directly to the database. - -In this case, two `DEFAULT` constraints are missing which are suggested by the tool: - -```no-lines wrap -Add missing `DEFAULT` constraints to the database -https://pris.ly/d/schema-incompatibilities#default-values-arent-represented-in-database - - ALTER TABLE "default$default"."User" ALTER COLUMN "role" SET DEFAULT 'CUSTOMER'; - ALTER TABLE "default$default"."Post" ALTER COLUMN "published" SET DEFAULT false; -``` - -You can now run these SQL statements against your database either using a command line client or a GUI like Postico: - -![Adding missing `DEFAULT` constraints to columns](./images/add-missing-default-constraints-to-columns.png) - -### 5.1.3. Fix columns with JSON data types - -Next, the tool helps you ensure that `Json` fields in your Prisma 1 datamodel will be represented as `JSON` columns in the underlying database, right now they are represented as plain strings (e.g. as `MEDIUMTEXT` in MySQL). - -Changing the column type to `JSON` will ensure that the field is properly recognized as `Json` during Prisma ORM 2 introspection. - -The CLI currently shows the following output: - -```no-lines wrap -Fix columns with JSON data types -https://pris.ly/d/schema-incompatibilities#json-type-is-represented-as-text-in-database - - ALTER TABLE "default$default"."User" ALTER COLUMN "jsonData" TYPE JSON USING "jsonData"::json; -``` - -> **⚠️ Warning**: If you are running Prisma 1 and Prisma ORM 2 [side-by-side](/orm/more/upgrade-guides/upgrade-from-prisma-1/how-to-upgrade#upgrade-strategies), these [SQL statements will break your Prisma 1 setup](https://github.com/prisma/prisma1-upgrade/issues/73). The docs will be updated to reflect this soon. - -You can now run these SQL statements against your database either using a command line client or a GUI like Postico: - -![Adding missing `DEFAULT` constraints to columns](./images/fix-columns-with-json-data-types.png) - - -### 5.1.4. Replicate `@createdAt` behavior in Prisma ORM 2 - -The next thing the tools does is help you resolve the issue that the behavior of [`@createdAt` isn't represented in database](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-postgresql#default-values-arent-represented-in-database) - -The CLI currently shows the following output: - -```no-lines wrap -Replicate `@createdAt` behavior in Prisma ORM 2.0 -https://pris.ly/d/schema-incompatibilities#createdat-isnt-represented-in-database - - ALTER TABLE "default$default"."Post" ALTER COLUMN "createdAt" SET DEFAULT CURRENT_TIMESTAMP; -``` - -You can now run these SQL statements against your database either using a command line client or a GUI like Postico: - -![Running an SQL command to alter a column](./images/run-sql-command-to-alter-column.png) - -### 5.1.5. Fix 1-1 relations by adding `UNIQUE` constraints - -Now, the tool will help you [turn the current 1-n relation between `User` ↔ `Profile` back into a 1-1 relation](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-postgresql#inline-1-1-relations-are-recognized-as-1-n-missing-unique-constraint) by adding a `UNIQUE` constraint to the foreign key column called `user` (named after the relation field in the Prisma 1 datamodel) in the database. - -The CLI currently shows the following output: - -```no-lines wrap -Fix 1-1 relations by adding `UNIQUE` constraints -https://pris.ly/d/schema-incompatibilities#inline-1-1-relations-are-recognized-as-1-n-missing-unique-constraint - - ALTER TABLE "default$default"."Profile" ADD UNIQUE ("user"); -``` - -You can now run these SQL statements against your database either using a command line client or a GUI like Postico: - -![Running an SQL command to alter a column](./images/run-sql-command-to-alter-column.png) - -### 5.1.6. Fix mismatch of CUID length - -> **Note**: These SQL statements will keep appearing in the Upgrade CLI even after you have changed the column types in the underlying database. This is a currently a limitation in the Upgrade CLI. - -Finally, the tool will help you [turn the current ID columns of type `VARCHAR(25)` into `VARCHAR(30)`](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-postgresql#mismatching-cuid-length) by adding a `UNIQUE` constraint to the foreign key column called `user` (named after the relation field in the Prisma 1 datamodel) in the database. - -The CLI currently shows the following output: - -```no-lines wrap wrap -Migrate IDs from varchar(25) to varchar(30) -https://pris.ly/d/schema-incompatibilities#mismatching-cuid-length - - ALTER TABLE "default$default"."Category" ALTER COLUMN "id" SET DATA TYPE character varying(30); - ALTER TABLE "default$default"."Post" ALTER COLUMN "id" SET DATA TYPE character varying(30); - ALTER TABLE "default$default"."Profile" ALTER COLUMN "id" SET DATA TYPE character varying(30); - ALTER TABLE "default$default"."Profile" ALTER COLUMN "user" SET DATA TYPE character varying(30); - ALTER TABLE "default$default"."User" ALTER COLUMN "id" SET DATA TYPE character varying(30); -``` - -You can now run these SQL statements against your database either using a command line client or a GUI like Postico: - -![Running an SQL command to alter a column](./images/run-sql-command-to-alter-column.png) - -### 5.1.7. Breaking changes detected - -In case the Upgrade CLI has printed a note about breaking changes, your database schema needs some adjustments that will break Prisma 1 compatibility in order to be fully optimized. - -If there are no breaking changes detected, you can [skip forward to section 5.2](#52-re-introspect-your-database-to-update-your-prisma-schema) - -Depending on your [upgrade strategy](/orm/more/upgrade-guides/upgrade-from-prisma-1/how-to-upgrade#upgrade-strategies), you can either perform these changes now or skip to the next phase of the Upgrade CLI: - -- If you are following the gradual side-by-side upgrade strategy, do not perform these changes yet since they will break your Prisma 1 setup. In that case, you can continue to the next phase of the Upgrade CLI by typing n and hitting RETURN. -- If you are following the all at once upgrade strategy, you can perform these changes now. In that case, continue by typing Y and hitting RETURN. - -### 5.2. Fix the database schema via plain SQL (breaking) - -In this section, you'll resolve the schema incompatibilities that are breaking your Prisma 1 setup. Do not perform these changes if you are still running Prisma 1 in your project! - -### 5.2.1. Fix incorrect m-n relations - -Now, the Upgrade CLI helps you fix all 1-1 and 1-n relations that Prisma 1 represents with relation tables and that [currently only exist as m-n relations](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-postgresql#all-non-inline-relations-are-recognized-as-m-n) in your new Prisma ORM 2 schema. Concretely, this is the case for the `User` ↔ `Post` relation which currently is defined as m-n but _should_ really be a 1-n relation. - -To fix this, you'll need to perform the following migration: - -1. Create a new foreign key column on `Post` to link directly to the `User` table. -1. Migrate the foreign key values from the relation table into the new foreign key column on `Post`. -1. Delete the relation table. - -These instructions are now printed by the CLI: - -```no-lines wrap -➤ Adjust your database schema -Run the following SQL statements against your database: - - Fix one-to-many table relations - https://pris.ly/d/schema-incompatibilities#all-non-inline-relations-are-recognized-as-m-n - - ALTER TABLE "default$default"."Post" ADD COLUMN "authorId" character varying(25) ; - ALTER TABLE "default$default"."Post" ADD CONSTRAINT "author" FOREIGN KEY ("authorId") REFERENCES "default$default"."User"("id"); - UPDATE "default$default"."Post" SET "authorId" = "default$default"."_PostToUser"."B" FROM "default$default"."_PostToUser" WHERE "default$default"."_PostToUser"."A" = "default$default"."Post"."id"; - DROP TABLE "default$default"."_PostToUser"; - - -➤ Next Steps - -After you executed one or more of the previous SQL statements against your database, -please run the following two commands to refresh your Prisma ORM 2 schema and check -the changes. - - 1. Run `npx prisma db pull` again to refresh your Prisma ORM 2 schema. - 2. Run `npx prisma-upgrade` again. - -If you can't or don't want to execute the remaining SQL statements right now, you can -skip to the last step where the Upgrade CLI adds missing attributes to your Prisma ORM 2 -schema that are not picked up by introspection. - -Skip to the last step? [Y/n]? -``` - -For this fix, you'll need to run three SQL statements: - -1. Create new column `authorId` on the `Post` table. This column should be a _foreign key_ that references the `id` field of the `User` table: - ```sql no-lines - ALTER TABLE `Post` ADD COLUMN `authorId` VARCHAR(25); - ALTER TABLE `Post` ADD FOREIGN KEY (`authorId`) REFERENCES `User` (`id`); - ``` -1. Write a SQL query that reads all the rows from the `_PostToUser` relation table and for each row: - 1. Finds the respective `Post` record by looking up the value from column `A` - 1. Inserts the value from column `B` as the value for `authorId` into that `Post` record - ```sql no-lines - UPDATE Post, _PostToUser - SET Post.authorId = _PostToUser.B - WHERE Post.id = _PostToUser.A - ``` -1. Delete the `_PostToUser` relation table - ```sql no-lines - DROP TABLE `_PostToUser`; - ``` - -![Fixing incorrect m-n relations with SQL](./images/fix-incorrect-m-n-relations-sql.png) - -After these commands, the user ID values of the records from column `B` of the relation table are migrated to the new `authorId` column. - -### 5.2. Re-introspect your database to update your Prisma schema - -At this point, you've resolved the schema incompatibilities with the Upgrade CLI. You can now exit the Upgrade CLI for now by typing n and hitting RETURN. - -In this section, you'll update your Prisma schema with another introspection round. This time, the previous flaws of the Prisma schema will be resolved because the database schema has been adjusted: - -```terminal copy -npx prisma db pull -``` - -This time, the resulting Prisma schema looks as follows: - -```prisma file=schema.prisma showLineNumbers -model User { - id String @id - name String - email String? @unique - jsonData Json? - role Role @default(CUSTOMER) - Post Post[] - Profile Profile? -} - -model Post { - id String @id - createdAt DateTime @default(now()) - updatedAt DateTime - title String - content String? - published Boolean @default(false) - authorId String? - User User? @relation(fields: [authorId], references: [id]) - Category Category[] @relation(references: [id]) -} - -model Category { - id String @id - name String - Post Post[] @relation(references: [id]) -} - -model Profile { - bio String? - id String @id - user String? @unique - User User? @relation(fields: [user], references: [id]) -} - -enum Role { - ADMIN - CUSTOMER -} -``` - -This schema has most issues resolved, but it still lacks the following: - -### 5.2. Add missing attributes to the Prisma 2 schema and other schema fixes - -The CLI now prints the following: - -``` wrap -➤ What happens next -As a last step, some final adjustments will be made to your Prisma ORM 2 schema -to carry over some Prisma ORM-level attributes that aren't picked up by introspection. - -As a last step, some final adjustments will be made to your Prisma ORM 2.0 -schema to carry over some Prisma ORM-level attributes that aren't picked -up by introspection. - -Warning -Your current Prisma ORM 2.0 schema will be overwritten, so please -make sure you have a backup! - -Are you ready? [Y/n] -``` - -At this point, you either ran all the SQL statement that were printed by the CLI or you skipped some of them. Either way, you can now move on the last step and let the Upgrade CLI add the missing Prisma ORM 2 attributes. Typically these are the following: - -- `@default(cuid())` for your `@id` fields -- `@updatedAt` for any fields that were using this attribute in Prisma 1 -- `@map` and `@@map` as replacements for `@db` and `@@db` from Prisma 1 - -In that step, the Upgrade CLI also fixes other issues that occurred in the transition to Prisma ORM 2: - -- it makes sure that 1-1-relations that were required on both sides in Prisma 1 are also required in your Prisma ORM 2 schema -- it renames relation fields to the same names they had in your Prisma 1 datamodel ([coming soon](https://github.com/prisma/prisma1-upgrade/issues/25)) - -To apply these changes, you can re-run the Upgrade CLI: - -```terminal copy -npx prisma-upgrade prisma1/prisma.yml prisma/schema.prisma -``` - -If you did not resolve all schema incompatibilities, the Upgrade CLI now prints the remaining SQL statements (as well as the ones for migrating IDs). You can just ignore them at this point and continue to the last step by continuously typing Y and hitting RETURN when prompted. - -If you did resolve all schema incompatibilities, no SQL statements will be printed and the Upgrade CLI only outputs the following: - -```no-lines wrap -$ npx prisma-upgrade prisma1/prisma.yml prisma/schema.prisma - -➤ Next Steps - -After you executed one or more of the previous SQL statements against your database, -please run the following two commands to refresh your Prisma ORM 2 schema and check -the changes. - - 1. Run `npx prisma db pull` again to refresh your Prisma ORM 2 schema. - 2. Run `npx prisma-upgrade` again. - -If you can't or don't want to execute the remaining SQL statements right now, you can -skip to the last step where the Upgrade CLI adds missing attributes to your Prisma ORM 2 -schema that are not picked up by introspection. - -Skip to the last step? [Y/n]? -``` - -One more time, type Y and hit RETURN to confirm. - -The final prompt of the Upgrade CLI now asks you to confirm the above mentioned changes it will make to your Prisma schema: - -```no-lines wrap -➤ What happens next -As a last step, some final adjustments will be made to your Prisma ORM 2 schema -to carry over some Prisma ORM-level attributes that aren't picked up by introspection. - -As a last step, some final adjustments will be made to your Prisma ORM 2.0 -schema to carry over some Prisma ORM-level attributes that aren't picked -up by introspection. - -Warning -Your current Prisma ORM 2.0 schema will be overwritten, so please -make sure you have a backup! - -Are you ready? [Y/n] -``` - -One last time, type Y and hit RETURN to confirm. - -This is the final output of the Upgrade CLI: - -```no-lines -Updating prisma/schema.prisma... -Done updating prisma/schema.prisma! - -✔ Congratulations, you're all set! - -➤ Note -If you didn't execute all generated SQL commands against your database, -you can re-run the Upgrade CLI at any time. - -Note that the Upgrade CLI doesn't resolve all of the schema incompatibilities -between Prisma 1 and Prisma ORM 2. If you want to resolve the remaining ones, -you can do so manually by following this guide: -https://pris.ly/d/upgrading-the-prisma-layer - -➤ Next steps -Otherwise you can continue your upgrade process by installing Prisma Client 2: -npm install @prisma/client - -You can find guides for different upgrade scenarios in the docs: -https://pris.ly/d/upgrade-from-prisma-1 -``` - -### 5.3. Final result - -The final version of the Prisma schema should look as follows: - -```prisma file=schema.prisma showLineNumbers -model User { - id String @id @default(cuid()) - name String - email String? @unique - jsonData Json? - role Role @default(CUSTOMER) - Post Post[] - Profile Profile? -} - -model Post { - id String @id @default(cuid()) - createdAt DateTime @default(now()) - updatedAt DateTime @updatedAt - title String - content String? - published Boolean @default(false) - authorId String? - User User? @relation(fields: [authorId], references: [id]) - Category Category[] @relation(references: [id]) -} - -model Profile { - id String @id @default(cuid()) - bio String? - user String? @unique - User User? @relation(fields: [user], references: [id]) -} - -model Category { - id String @id @default(cuid()) - name String - Post Post[] @relation(references: [id]) -} - -enum Role { - ADMIN - CUSTOMER -} -``` - -### 5.4. Rename relation fields - -One thing you'll notice with this version of the Prisma ORM 2 schema is that all [relation fields](/orm/prisma-schema/data-model/relations#relation-fields) are named after their respective models, e.g: - -```prisma file=schema.prisma showLineNumbers -model User { - Post Post[] - Profile Profile? -} - -model Post { - User User? @relation(fields: [authorId], references: [id]) - Category Category[] @relation(references: [id]) -} - -model Profile { - User User? @relation(fields: [user], references: [id]) -} - -model Category { - Post Post[] @relation(references: [id]) -} -``` - -This is not ideal and you can in fact manually rename all of them to their previous versions! - -Because all relation fields are _virtual_, meaning they don't _manifest_ in the database, you can name them whatever you like. In this case, all relation fields are lowercased and sometimes pluralized. - -Here's what they look like after the rename: - -```prisma file=schema.prisma showLineNumbers -model User { - posts Post[] - profile Profile? -} - -model Post { - author User? @relation(fields: [authorId], references: [id]) - categories Category[] @relation(references: [id]) -} - -model Profile { - user String? @unique - owner User? @relation(fields: [user], references: [id]) -} - -model Category { - posts Post[] @relation(references: [id]) -} -``` - -> **Note**: For the 1-1-relation between `User` and `Profile` it was not possible to set the old name `user` for the relation field. This is because there'd be a naming conflict with the already existing [relation scalar](/orm/prisma-schema/data-model/relations#annotated-relation-fields) field that holds the foreign key. In that case, you can choose a different name or alternatively rename the foreign key column directly in the database via SQL. - -### 5.5. Resolving remaining schema incompatibilities - -There are a few schema incompatibilities that were not yet resolved by the Upgrade CLI. At this point you still haven't fixed [scalar lists](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-postgresql#scalar-lists-arrays-are-maintained-with-extra-table). You can find the recommended workarounds for this and others on the [Schema incompatibilities](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-postgresql) page. - -## 6. Install and generate Prisma Client - -Now that you have your Prisma ORM 2 schema ready, you can install Prisma Client with the following command: - -```terminal copy -npm install @prisma/client -``` - -## 7. Next steps - -Congratulations, you have now upgraded your Prisma ORM layer to Prisma ORM 2! From here on, you can move on to update your application code using one of the following guides: - -- [Old to new Nexus](/orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-nexus-prisma-to-nexus): Choose this guide if you're currently running Prisma 1 with GraphQL Nexus. -- [prisma-binding to Nexus](/orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-prisma-binding-to-nexus): Choose this guide if you're currently running Prisma 1 with `prisma-binding` and want to upgrade to [Nexus](https://nexusjs.org/) (and TypeScript). -- [prisma-binding to SDL-first](/orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-prisma-binding-to-sdl-first): Choose this guide if you're currently running Prisma 1 with `prisma-binding` and want to upgrade to an [SDL-first](https://www.prisma.io/blog/the-problems-of-schema-first-graphql-development-x1mn4cb0tyl3) GraphQL server. -- [REST API](/orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-a-rest-api): Choose this guide if you're currently running Prisma 1 using Prisma Client 1 and are building a REST API. - -## Bonus: Prisma Client API comparison - -This section contains a high-level and side-by-side comparison of the Prisma Client APIs of Prisma 1 and Prisma ORM 2. For more details about the new Prisma Client API, you can explore the [Prisma Client](/orm/prisma-client) docs. - -### Reading single records - - - - - -```ts -const user = await prisma.user({ id: 1 }) -``` - - - - - -```ts -await prisma.user.findUnique({ - where: { id: 1 }, -}) -``` - - - - - -### Reading lists of records - - - - - -```ts -const user = await prisma.users() -``` - - - - - -```ts -await prisma.user.findMany() -``` - - - - - -### Filtering lists - - - - - -```ts -const users = await prisma.users({ - where: { - name: 'Alice', - }, -}) -``` - - - - - -```ts -await prisma.user.findMany({ - where: { - name: 'Alice', - }, -}) -``` - - - - - -### Paginating lists - - - - - -```ts -const posts = await prisma.posts({ - skip: 5, - first: 10, -}) -``` - - - - - -```ts -await prisma.user.findMany({ - skip: 5, - take: 10, -}) -``` - - - - - -> **Note**: You can learn more about the new pagination API in the respective [release notes](https://github.com/prisma/prisma/releases/tag/2.0.0-beta.7) or the [Pagination](/orm/prisma-client/queries/pagination) page in the docs. - -### Sorting lists - - - - - -```ts -await prisma.posts({ - orderBy: 'title_ASC', -}) -``` - - - - - -```ts -await prisma.posts({ - orderBy: { - title: 'asc', - }, -}) -``` - - - - - -### Creating records - - - - - -```ts -await prisma.createUser({ - name: 'Alice', -}) -``` - - - - - -```ts -await prisma.user.create({ - data: { - name: 'Alice', - }, -}) -``` - - - - - -### Updating records - - - - - -```ts -await prisma.updateUser({ - where: { id: 1 }, - data: { - name: 'James', - email: 'james@prisma.io', - }, -}) -``` - - - - - -```ts -await prisma.user.update({ - where: { id: 1 }, - data: { - name: 'James', - email: 'james@prisma.io', - }, -}) -``` - - - - - -### Deleting records - - - - - -```ts -await prisma.deleteUser({ id: 1 }) -``` - - - - - -```ts -await prisma.user.delete({ - where: { id: 1 }, -}) -``` - - - - - -### Selecting fields & loading relations - -In Prisma 1, the only ways to select specific fields and/or load relations of an object was by using the string-based `$fragment` and `$graphql` functions. With Prisma ORM 2, this is now done in a clean and type-safe manner using [`select`](/orm/prisma-client/queries/select-fields#select-specific-fields) and [`include`](/orm/prisma-client/queries/select-fields#return-nested-objects-by-selecting-relation-fields). - -Another benefit of this approach is that you can use `select` and `include` on _any_ Prisma Client query, e.g. `findUnique()`, `findMany`, `create`, `update`, `delete`, ... - - - - - -```ts -await prisma.user({ id: 1 }).$fragment(` - fragment NameAndEmail on User { id email }` -`) -``` - - - - - -```ts -await prisma.user.findUnique({ - where: { id: 1 }, - select: { - id: true, - email: true, - }, -}) -``` - - - - - -As an example, creating a new record and only retrieving the `id` in the returned object was not possible in Prisma 1. With Prisma ORM 2 you can achieve this as follows: - -```ts -await prisma.user.create({ - data: { - name: 'Alice', - }, - select: { - id: true, - }, -}) -``` diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/04-upgrading-nexus-prisma-to-nexus.mdx b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/04-upgrading-nexus-prisma-to-nexus.mdx deleted file mode 100644 index 0fbcc232cb..0000000000 --- a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/04-upgrading-nexus-prisma-to-nexus.mdx +++ /dev/null @@ -1,778 +0,0 @@ ---- -title: 'Old to new Nexus' -metaTitle: 'Upgrade Prisma 1 with nexus-prisma to @nexus/schema' -metaDescription: 'Learn how to upgrade existing Prisma 1 projects with nexus-prisma to Prisma ORM 2 and Nexus.' ---- - -## Overview - -:::info - -This guide is not fully up-to-date as it currently uses the [deprecated](https://github.com/graphql-nexus/nexus-plugin-prisma/issues/1039) version of the [`nexus-plugin-prisma`](https://github.com/graphql-nexus/nexus-plugin-prisma). While this is still functional, it is recommended to use the new [`nexus-prisma`](https://github.com/graphql-nexus/nexus-prisma/) library or an alternative code-first GraphQL library like [Pothos](https://pothos-graphql.dev/) going forward. If you have any questions, feel free to share them on our [Discord](https://pris.ly/discord?utm_source=docs&utm_medium=intro_text). - -::: - -This upgrade guide describes how to upgrade a project that's based on [Prisma 1](https://github.com/prisma/prisma1) and uses [`nexus`](https://www.npmjs.com/package/nexus) (< v0.12.0) or [`@nexus/schema`](https://github.com/graphql-nexus/nexus) together with [`nexus-prisma`](https://www.npmjs.com/package/nexus-prisma) (< v4.0.0) to implement a GraphQL server. - -The code will be upgraded to the latest version of `@nexus/schema`. Further, the `nexus-prisma` package will be replaced with the new [`nexus-plugin-prisma`](https://github.com/graphql-nexus/nexus-plugin-prisma). - -The guide assumes that you already went through the [guide for upgrading the Prisma ORM layer](/orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-the-prisma-layer-postgresql). This means you already: - -- installed the Prisma ORM 2 CLI -- created your Prisma ORM 2 schema -- introspected your database and resolved potential [schema incompatibilities](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-postgresql) -- installed and generated Prisma Client - -The guide further assumes that you have a file setup that looks similar to this: - -``` -. -├── README.md -├── package.json -├── prisma -│ └── schema.prisma -├── prisma1 -│ ├── datamodel.prisma -│ └── prisma.yml -└── src - ├── generated - │ ├── nexus-prisma - │ ├── nexus.ts - │ ├── prisma-client - │ └── schema.graphql - ├── types.ts - └── index.ts -``` - -The important parts are: - -- A folder called with `prisma` with your Prisma ORM 2 schema -- A folder called `src` with your application code - -If this is not what your project structure looks like, you'll need to adjust the instructions in the guide to match your own setup. - -## 1. Upgrade Nexus dependencies - -To get started, you can remove the old Nexus and Prisma 1 dependencies: - -```copy -npm uninstall nexus nexus-prisma prisma-client-lib prisma1 -``` - -Then, you can install the latest `@nexus/schema` dependency in your project: - -```copy -npm install @nexus/schema -``` - -Next, install the Prisma ORM plugin for Nexus which will allow you to expose Prisma ORM models in your GraphQL API (this is the new equivalent of the former `nexus-prisma` package): - -```copy -npm install nexus-plugin-prisma -``` - -The `nexus-plugin-prisma` dependency bundles all required Prisma ORM dependencies. You should therefore remove the dependencies that you added installed when you upgraded the Prisma ORM layer of your app: - -```copy -npm uninstall @prisma/cli @prisma/client -``` - -Note however that you can still invoke the Prisma ORM 2 CLI with the familiar command: - -```copy -npx prisma -v -``` - -> **Note**: If you see the output of the Prisma 1 CLI when running `npx prisma -v`, be sure to delete your `node_modules` folder and re-run `npm install`. - -## 2. Update the configuration of Nexus and Prisma ORM - -To get started, you can remove the old imports that are not needed any more with your new setup: - -```ts line-number highlight=1-3;delete -//delete-start -import { makePrismaSchema, prismaObjectType } from 'nexus-prisma' -import datamodelInfo from './generated/nexus-prisma' -import { prisma } from './generated/prisma-client' -//delete-end -``` - -Instead, you now import the following into your application: - -```ts line-number highlight=1-3;add -//add-start -import { nexusSchemaPrisma } from 'nexus-plugin-prisma/schema' -import { objectType, makeSchema, queryType, mutationType } from '@nexus/schema' -import { PrismaClient } from '@prisma/client' -//add-end -``` - -Next you need to adjust the code where you currently create your `GraphQLSchema`, most likely this is currently happening via the `makePrismaSchema` function in your code. Since this function was imported from the removed `nexus-prisma` package, you'll need to replace it with the `makeSchema` function from the `@nexus/schema` package. The way how the Prisma ORM plugin for Nexus is used also changes in the latest version. - -Here's an example for such a configuration: - -```ts file=./src/index.ts line-number highlight=2,12-14;add|1,8-11;delete showLineNumbers -//delete-next-line - const schema = makePrismaSchema({ -//add-next-line - const schema = makeSchema({ - - // Provide all the GraphQL types we've implemented - types: [Query, Mutation, UserUniqueInput, User, Post, Category, Profile], - - // Configure the interface to Prisma - //delete-start - prisma: { - datamodelInfo, - client: prisma, - }, - //delete-end - //add-start - plugins: [nexusSchemaPrisma({ - experimentalCRUD: true, - })], - //add-end - - // Specify where Nexus should put the generated files - outputs: { - schema: path.join(__dirname, './generated/schema.graphql'), - typegen: path.join(__dirname, './generated/nexus.ts'), - }, - - // Configure nullability of input arguments: All arguments are non-nullable by default - nonNullDefaults: { - input: false, - output: false, - }, - - // Configure automatic type resolution for the TS representations of the associated types - typegenAutoConfig: { - sources: [ - { - source: path.join(__dirname, './types.ts'), - alias: 'types', - }, - ], - contextType: 'types.Context', - }, -}) -``` - -If you previously typed the GraphQL `context` object that's passed through your resolver chain, you need to adjust the type like so: - -```ts file=./src/types.ts highlight=2,6;add|1,5;delete showLineNumbers -//delete-next-line -import { Prisma } from './generated/prisma-client' -//add-next-line -import { PrismaClient } from '@prisma/client' - -export interface Context { - //delete-next-line - prisma: Prisma - //add-next-line - prisma: PrismaClient -} -``` - -## 3. Migrate your GraphQL types - -Here's a quick overview of the main differences between the two approaches of creating GraphQL types with the latest versions of `@nexus/schema` and `nexus-plugin-prisma`. - -- The `prismaObjectType` function is not available any more, all types are created with Nexus' `objectType` function. -- To expose Prisma models via Nexus, you can use the `t.model` property which is added to the `t` argument that's passed into Nexus' `definition` functions. `t.model` gives you access to the properties of a Prisma model and lets you expose them. -- Exposing CRUD operations for Prisma models via Nexus follows a similar approach. These are exposed via `t.crud` in the `definition` functions of your `queryType` and `mutationType` types. - -### 3.1. Migrating the `Post` type - -#### Type definition with the previous `nexus-prisma` package - -In the sample app, the `User` type is defined as follows: - -```ts -const User = prismaObjectType({ - name: 'User', - definition(t) { - t.prismaFields([ - 'id', - 'name', - 'email', - 'jsonData', - 'role' - { - name: 'posts', - args: [], // remove the arguments from the `posts` field of the `User` type in the Prisma schema - }, - ]) - }, -}) -``` - -#### Type definition with the latest version of `@nexus/schema` and the `nexus-plugin-prisma` - -With the latest version of `@nexus/schema`, you can now access the `objectType` function on your main `schema` instance and expose all fields from the Prisma model like so: - -```ts -const User = objectType({ - name: 'User', - definition(t) { - t.model.id() - t.model.name() - t.model.email() - t.model.jsonData() - t.model.role() - t.model.posts({ - pagination: false, - ordering: false, - filtering: false, - }) - t.model.profile() - }, -}) -``` - -Note that `t.model` looks at the `name` attribute in the object that's passed as an argument to the `objectType` function and matches it against the models in your Prisma schema. In this case, it's matched against the `User` model. Therefore, `t.model` exposes functions that are named after the fields of the `User` model. - -At this point, you might see errors on the relation fields `posts` and `profile`, e.g.: - -```bash highlight=1;delete -//delete-next-line -Missing type Post, did you forget to import a type to the root query? -``` - -This is because you didn't add the `Post` and `Profile` types to the GraphQL schema yet, the errors will go away once these types are part of the GraphQL schema as well! - -### 3.2. Migrating the `Post` type - -#### Type definition with the previous `nexus-prisma` package - -In the sample app, the `Post` type is defined as follows: - -```ts -const Post = prismaObjectType({ - name: 'Post', - definition(t) { - t.prismaFields(['*']) - }, -}) -``` - -The asterisk in `prismaFields` means that _all_ Prisma fields are exposed. - -#### Type definition with the latest version of `@nexus/schema` and the `nexus-plugin-prisma` - -With the latest version of `@nexus/schema`, you need to expose all fields explicitly, there's no option to just expose everything from a Prisma model. - -Therefore, the new definition of `Post` must explicitly list all its fields: - -```ts -const Post = objectType({ - name: 'Post', - definition(t) { - t.model.id() - t.model.title() - t.model.content() - t.model.published() - t.model.author() - t.model.categories() - }, -}) -``` - -Note that `t.model` looks at the `name` attribute and matches it against the models in your Prisma schema. In this case, it's matched against the `Post` model. Therefore, `t.model` exposes functions that are named after the fields of the `Post` model. - -### 3.3. Migrating the `Profile` type - -#### Type definition with the previous `nexus-prisma` package - -In the sample app, the `Profile` type is defined as follows: - -```ts -const Profile = prismaObjectType({ - name: 'Profile', - definition(t) { - t.prismaFields(['*']) - }, -}) -``` - -The asterisk in `prismaFields` means that _all_ Prisma fields are exposed. - -#### Type definition with the latest version of `@nexus/schema` and the `nexus-plugin-prisma` - -With the latest version of `@nexus/schema`, you need to expose all fields explicitly, there's no option to just expose everything from a Prisma model. - -Therefore, the new definition of `Profile` must explicitly list all its fields: - -```ts -const Profile = objectType({ - name: 'Profile', - definition(t) { - t.model.id() - t.model.bio() - t.model.user() - t.model.userId() - }, -}) -``` - -Note that `t.model` looks at the `name` attribute and matches it against the models in your Prisma schema. In this case, it's matched against the `Profile` model. Therefore, `t.model` exposes functions that are named after the fields of the `Profile` model. - -### 3.4. Migrating the `Category` type - -#### Type definition with the previous `nexus-prisma` package - -In the sample app, the `Category` type is defined as follows: - -```ts -const Category = prismaObjectType({ - name: 'Category', - definition(t) { - t.prismaFields(['*']) - }, -}) -``` - -The asterisk in `prismaFields` means that _all_ Prisma ORM fields are exposed. - -#### Type definition with the latest version of `@nexus/schema` and the `nexus-plugin-prisma` - -With the latest version of `@nexus/schema`, you need to expose all fields explicitly, there's no option to just expose everything from a Prisma model. - -Therefore, the new definition of `Category` must explicitly list all its fields: - -```ts -const Category = objectType({ - name: 'Category', - definition(t) { - t.model.id() - t.model.name() - t.model.posts({ - pagination: true, - ordering: true, - filtering: true, - }) - }, -}) -``` - -Note that `t.model` looks at the `name` attribute and matches it against the models in your Prisma schema. In this case, it's matched against the `Category` model. Therefore, `t.model` exposes functions that are named after the fields of the `Category` model. - -## 4. Migrate GraphQL operations - -As a next step, you can start migrating all the GraphQL _queries_ and _mutations_ from the "previous" GraphQL API to the new one. - -For this guide, the following sample GraphQL operations will be used: - -```graphql -input UserUniqueInput { - id: String - email: String -} - -type Query { - posts(searchString: String): [Post!]! - user(userUniqueInput: UserUniqueInput!): User - users(where: UserWhereInput, orderBy: Enumerable, skip: Int, after: String, before: String, first: Int, last: Int): [User]! -} - -type Mutation { - createUser(data: UserCreateInput!): User! - createDraft(title: String!, content: String, authorId: ID!): Post - updateBio(userUniqueInput: UserUniqueInput!, bio: String!): User - addPostToCategories(postId: String!, categoryIds: [String!]!): Post -} -``` - -### 4.1. Migrate GraphQL queries - -In this section, you'll migrate all GraphQL _queries_ from the previous version of `nexus` and `nexus-prisma` to the latest version of `@nexus/schema` and the `nexus-plugin-prisma`. - -#### 4.1.1. Migrate the `users` query - -In our sample API, the `users` query from the sample GraphQL schema is implemented as follows. - -```ts -const Query = prismaObjectType({ - name: 'Query', - definition(t) { - t.prismaFields(['users']) - }, -}) -``` - -To get the same behavior with the new Nexus, you need to call the `users` function on `t.crud`: - -```ts -schema.queryType({ - definition(t) { - t.crud.users({ - filtering: true, - ordering: true, - pagination: true, - }) - }, -}) -``` - -Recall that the `crud` property is added to `t` by the `nexus-plugin-prisma` (using the same mechanism as for `t.model`). - -#### 4.1.2. Migrate the `posts(searchString: String): [Post!]!` query - -In the sample API, the `posts` query is implemented as follows: - -```ts -queryType({ - definition(t) { - t.list.field('posts', { - type: 'Post', - args: { - searchString: stringArg({ nullable: true }), - }, - resolve: (parent, { searchString }, context) => { - return context.prisma.posts({ - where: { - OR: [ - { title_contains: searchString }, - { content_contains: searchString }, - ], - }, - }) - }, - }) - }, -}) -``` - -The only thing that needs to be updated for this query is the call to Prisma ORM since the new Prisma Client API looks a bit different from the one used in Prisma 1. - -```ts line-number highlight=6,9,12,13;normal -queryType({ - definition(t) { - t.list.field('posts', { - type: 'Post', - args: { - searchString: stringArg({ nullable: true }), - }, - resolve: (parent, { searchString }, context) => { - return context.prisma.post.findMany({ - where: { - OR: [ - { title: { contains: searchString } }, - { content: { contains: searchString } }, - ], - }, - }) - }, - }) - }, -}) -``` - -Notice that the `db` object is automatically attached to the `context` by the `nexus-plugin-prisma`. It represents an instance of your `PrismaClient` which enables you to send queries to your database inside your resolvers. - -#### 4.1.3. Migrate the `user(uniqueInput: UserUniqueInput): User` query - -In the sample API, the `user` query is implemented as follows: - -```ts -inputObjectType({ - name: 'UserUniqueInput', - definition(t) { - t.string('id') - t.string('email') - }, -}) - -queryType({ - definition(t) { - t.field('user', { - type: 'User', - args: { - userUniqueInput: schema.arg({ - type: 'UserUniqueInput', - nullable: false, - }), - }, - resolve: (_, args, context) => { - return context.prisma.user({ - id: args.userUniqueInput?.id, - email: args.userUniqueInput?.email, - }) - }, - }) - }, -}) -``` - -You now need to adjust the call to your `prisma` instance since the new Prisma Client API looks a bit different from the one used in Prisma 1. - -```ts line-number highlight=6,12-17;normal -const Query = queryType({ - definition(t) { - t.field('user', { - type: 'User', - args: { - //highlight-next-line - userUniqueInput: arg({ - type: 'UserUniqueInput', - nullable: false, - }), - }, - resolve: (_, args, context) => { - //highlight-start - return context.prisma.user.findUnique({ - where: { - id: args.userUniqueInput?.id, - email: args.userUniqueInput?.email, - }, - }) - //highlight-end - }, - }) - }, -}) -``` - -### 4.2. Migrate GraphQL mutations - -In this section, you'll migrate the GraphQL mutations from the sample schema to the latest versions of `@nexus/schema` and the `nexus-plugin-prisma`. - -#### 4.2.1. Migrate the `createUser` mutation - -In our sample API, the `createUser` mutation from the sample GraphQL schema is implemented as follows. - -```ts -const Mutation = prismaObjectType({ - name: 'Mutation', - definition(t) { - t.prismaFields(['createUser']) - }, -}) -``` - -To get the same behavior with the latest versions of `@nexus/schema` and the `nexus-plugin-prisma`, you need to call the `createOneUser` function on `t.crud` and pass an `alias` in order to rename the field in your GraphQL schema to `createUser` (otherwise it would be called `createOneUser`, after the function that's used): - -```ts -const Query = queryType({ - definition(t) { - t.crud.createOneUser({ - alias: 'createUser', - }) - }, -}) -``` - -Recall that the `crud` property is added to `t` by the `nexus-plugin-prisma` (using the same mechanism as for `t.model`). - -#### 4.2.2. Migrate the `createDraft(title: String!, content: String, authorId: String!): Post!` query - -In the sample app, the `createDraft` mutation implemented as follows. - -```ts line-number -mutationType({ - definition(t) { - t.field('createDraft', { - type: 'Post', - args: { - title: stringArg({ nullable: false }), - content: stringArg(), - authorId: stringArg({ nullable: false }), - }, - resolve: (_, args, context) => { - return context.prisma.createPost({ - title: args.title, - content: args.content, - author: { - connect: { id: args.authorId }, - }, - }) - }, - }) - }, -}) -``` - -You now need to adjust the call to your `prisma` instance since the new Prisma Client API looks a bit different from the one used in Prisma 1. - -```ts line-number highlight=11-19;normal -const Mutation = mutationType({ - definition(t) { - t.field('createDraft', { - type: 'Post', - args: { - title: stringArg({ nullable: false }), - content: stringArg(), - authorId: stringArg({ nullable: false }), - }, - resolve: (_, args, context) => { - //highlight-start - return context.prisma.post.create({ - data: { - title: args.title, - content: args.content, - author: { - connect: { id: args.authorId }, - }, - }, - }) - //highlight-end - }, - }) - }, -}) -``` - -#### 4.2.3. Migrate the `updateBio(bio: String, userUniqueInput: UserUniqueInput!): User` mutation - -In the sample API, the `updateBio` mutation is defined and implemented as follows. - -```ts -mutationType({ - definition(t) { - t.field('updateBio', { - type: 'User', - args: { - userUniqueInput: arg({ - type: 'UserUniqueInput', - nullable: false, - }), - bio: stringArg(), - }, - resolve: (_, args, context) => { - return context.prisma.updateUser({ - where: { - id: args.userUniqueInput?.id, - email: args.userUniqueInput?.email, - }, - data: { - profile: { - create: { bio: args.bio }, - }, - }, - }) - }, - }) - }, -}) -``` - -You now need to adjust the call to your `prisma` instance since the new Prisma Client API looks a bit different from the one used in Prisma 1. - -```ts highlight=13-23;normal -const Mutation = mutationType({ - definition(t) { - t.field('updateBio', { - type: 'User', - args: { - userUniqueInput: arg({ - type: 'UserUniqueInput', - nullable: false, - }), - bio: stringArg(), - }, - resolve: (_, args, context) => { - //highlight-start - return context.prisma.user.update({ - where: { - id: args.userUniqueInput?.id, - email: args.userUniqueInput?.email, - }, - data: { - profile: { - create: { bio: args.bio }, - }, - }, - }) - //highlight-end - }, - }) - }, -}) -``` - -#### 4.2.4. Migrate the `addPostToCategories(postId: String!, categoryIds: [String!]!): Post` mutation - -In the sample API, the `addPostToCategories` mutation is defined and implemented as follows. - -```ts line-number -mutationType({ - definition(t) { - t.field('addPostToCategories', { - type: 'Post', - args: { - postId: stringArg({ nullable: false }), - categoryIds: stringArg({ - list: true, - nullable: false, - }), - }, - resolve: (_, args, context) => { - const ids = args.categoryIds.map((id) => ({ id })) - return context.prisma.updatePost({ - where: { - id: args.postId, - }, - data: { - categories: { connect: ids }, - }, - }) - }, - }) - }, -}) -``` - -You now need to adjust the call to your `prisma` instance since the new Prisma Client API looks a bit different from the one used in Prisma 1. - -```ts line-number highlight=14-21;normal -const Mutation = mutationType({ - definition(t) { - t.field('addPostToCategories', { - type: 'Post', - args: { - postId: stringArg({ nullable: false }), - categoryIds: stringArg({ - list: true, - nullable: false, - }), - }, - resolve: (_, args, context) => { - const ids = args.categoryIds.map((id) => ({ id })) - //highlight-start - return context.prisma.post.update({ - where: { - id: args.postId, - }, - data: { - categories: { connect: ids }, - }, - }) - //highlight-end - }, - }) - }, -}) -``` - -## 5. Cleaning up - -### 5.1. Clean up npm dependencies - -If you haven't already, you can now uninstall dependencies that were related to the Prisma 1 setup: - -``` -npm uninstall prisma1 prisma-client-lib -``` - -### 5.2. Delete unused files - -Next, delete the files of your Prisma 1 setup: - -``` -rm -rf src/generated -rm -rf prisma1 -``` - -### 5.3. Stop the Prisma ORM server - -Finally, you can stop running your Prisma ORM server. diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/05-upgrading-prisma-binding-to-nexus.mdx b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/05-upgrading-prisma-binding-to-nexus.mdx deleted file mode 100644 index 3110ebafdc..0000000000 --- a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/05-upgrading-prisma-binding-to-nexus.mdx +++ /dev/null @@ -1,1332 +0,0 @@ ---- -title: 'prisma-binding to Nexus' -metaTitle: 'Upgrading from Prisma 1 with prisma-binding to Nexus' -metaDescription: 'Learn how to upgrade existing Prisma 1 projects with prisma-binding to Prisma ORM 2.0 and Nexus.' ---- - -## Overview - -:::info -This guide is not fully up-to-date as it currently uses the [deprecated](https://github.com/graphql-nexus/nexus-plugin-prisma/issues/1039) version of the [`nexus-plugin-prisma`](https://github.com/graphql-nexus/nexus-plugin-prisma). While this is still functional, it is recommended to use the new [`nexus-prisma`](https://github.com/graphql-nexus/nexus-prisma) library or an alternative code-first GraphQL library like [Pothos](https://pothos-graphql.dev/) going forward. If you have any questions, join us on our [Discord](https://pris.ly/discord?utm_source=docs&utm_medium=intro_text). - -::: - -This upgrade guide describes how to migrate a Node.js project that's based on [Prisma 1](https://github.com/prisma/prisma1) and uses `prisma-binding` to implement a GraphQL server. - -The code will be migrated to [`@nexus/schema`](https://github.com/graphql-nexus/nexus) and the [`nexus-plugin-prisma`](https://github.com/graphql-nexus/nexus-plugin-prisma). As opposed to the _SDL-first_ approach that's used with `prisma-binding`, Nexus follows a code-first approach to construct GraphQL schemas. You can learn about the main differences of these two approaches in this [article](https://www.prisma.io/blog/the-problems-of-schema-first-graphql-development-x1mn4cb0tyl3). If you want to continue using the SDL-first approach, you can follow the [guide](/orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-prisma-binding-to-sdl-first) to upgrade from `prisma-binding` to an SDL-first setup. - -This guide also explains how to migrate from JavaScript to TypeScript, it therefore basically assumes a **full rewrite** of your existing app. If you want to keep running your application in JavaScript, you can ignore the instructions that relate to the TypeScript setup keep using JavaScript as before. - -The guide assumes that you already went through the [guide for upgrading the Prisma ORM layer](/orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-the-prisma-layer-postgresql). This means you already: - -- installed the Prisma ORM 2.0 CLI -- created your Prisma ORM 2.0 schema -- introspected your database and resolved potential [schema incompatibilities](/orm/more/upgrade-guides/upgrade-from-prisma-1/schema-incompatibilities-postgresql) -- installed and generated Prisma Client - -The guide further assumes that you have a file setup that looks similar to this: - -``` -. -├── README.md -├── package.json -├── prisma -│ └── schema.prisma -├── prisma1 -│ ├── datamodel.prisma -│ └── prisma.yml -└── src - ├── generated - │ └── prisma.graphql - ├── index.js - └── schema.graphql -``` - -The important parts are: - -- A folder called with `prisma` with your Prisma ORM 2.0 schema -- A folder called `src` with your application code and a schema called `schema.graphql` - -If this is not what your project structure looks like, you'll need to adjust the instructions in the guide to match your own setup. - -## 1. Installing and configuring Nexus - -### 1.1. Install Nexus dependencies - -The first step is to install the Nexus dependency in your project: - -```terminal copy -npm install @nexus/schema -``` - -Next, install the the Prisma ORM plugin for Nexus which will allow you to expose Prisma models in your GraphQL API: - -```terminal copy -npm install nexus-plugin-prisma -``` - -The `nexus-plugin-prisma` dependency bundles all required Prisma ORM dependencies. You should therefore remove the dependencies that you installed when you upgraded the Prisma ORM layer of your app: - -```terminal copy -npm uninstall @prisma/cli @prisma/client -``` - -Note however that you can still invoke the Prisma ORM 2.0 CLI with the familiar command: - -```terminal -npx prisma -``` - -### 1.2. Configure TypeScript - -Since you'll be using TypeScript in this guide, you need to add the required dependencies: - -```terminal copy -npm install typescript ts-node-dev --save-dev -``` - -Create a new file named `tsconfig.json` in the root directory of your project: - -```terminal copy -touch tsconfig.json -``` - -Now add the following contents to the new file: - -```json copy file=tsconfig.json showLineNumbers -{ - "compilerOptions": { - "skipLibCheck": true, - "strict": true, - "rootDir": "src", - "noEmit": true - }, - "include": ["src/**/*"] -} -``` - -### 1.3. Create your basic Nexus setup - -Create the root source file of your API called `index.ts` inside the `src` directory: - -```terminal copy -touch src/index.ts -``` - -Note that for this guide, you'll write the entire application inside of `index.ts`. In practice, you probably want to split your GraphQL types across different files as shown in this [example](https://pris.ly/e/ts/graphql-auth). - -For some basic setup, add this code to `index.ts`: - -```ts file=index.ts showLineNumbers -import { queryType, makeSchema } from '@nexus/schema' -import { nexusSchemaPrisma } from 'nexus-plugin-prisma/schema' -import { GraphQLServer } from 'graphql-yoga' -import { createContext } from './context' - -const Query = queryType({ - definition(t) { - t.string('hello', () => { - return 'Hello Nexus!' - }) - }, -}) - -export const schema = makeSchema({ - types: [Query], - plugins: [nexusSchemaPrisma({ experimentalCRUD: true })], - outputs: { - schema: __dirname + '/../schema.graphql', - typegen: __dirname + '/generated/nexus.ts', - }, - typegenAutoConfig: { - contextType: 'Context.Context', - sources: [ - { - source: '@prisma/client', - alias: 'prisma', - }, - { - source: require.resolve('./context'), - alias: 'Context', - }, - ], - }, -}) - -new GraphQLServer({ schema, context: createContext() }).start(() => - console.log(`Server ready at: http://localhost:4000`) -) -``` - -Note that this setup already contains the configuration of the Prisma ORM plugin for Nexus. This will enable the `t.model` and `t.crud` functionality that you'll get to know later in this guide. - -In the `typegenAutoConfig` setting, you're providing additional types that help your editor to provide your autocompletion as you develop your app. Right now it references a file named `context.ts` that you don't have in your project yet. This file will contain the type of your `context` object that's passed through your GraphQL resolver chain. - -Create the new `context.ts` file inside the `src` directory: - -```terminal copy -touch src/context.ts -``` - -Now add the following code to it: - -```ts -import { PrismaClient } from '@prisma/client' - -const prisma = new PrismaClient() - -export interface Context { - prisma: PrismaClient -} - -export function createContext(): Context { - return { prisma } -} -``` - -Next, adjust the `scripts` section inside your `package.json` to include the following commands: - -```json -{ - "scripts": { - "start": "node dist/server", - "clean": "rm -rf dist", - "build": "npm -s run clean && npm -s run generate && tsc", - "generate": "npm -s run generate:prisma && npm -s run generate:nexus", - "generate:prisma": "prisma generate", - "generate:nexus": "ts-node --transpile-only src/schema", - "dev": "ts-node-dev --no-notify --respawn --transpile-only src" - } -} -``` - -The `dev` script starts a development server that you **always** should have running in the background when developing your app. This is important because of the code generation Nexus performs in the background. - -You can start the development server using the following command: - -```copy -npm run dev -``` - -You should see the following CLI output: - -```terminal -Server ready at: http://localhost:4000 -``` - -Your GraphQL server is now running at [http://localhost:4000](http://localhost:4000). So far it implements a single GraphQL query that you can send as follows: - -```graphql -{ - hello -} -``` - -In the following steps, we'll explain how you can migrate your existing SDL-first GraphQL schema that's implemented with `prisma-binding` to an equivalent setup using Nexus. - -## 2. Create your GraphQL types - -The next step of the upgrade process is to create your _GraphQL types_. In this case, your GraphQL types will mirror the Prisma models (as it likely was the case in your `prisma-binding` setup as well). If a GraphQL type deviates from a Prisma model, you'll be able to easily adjust the exposed GraphQL type accordingly using the Nexus API. - -For the purpose of this guide, you'll keep all the code in a single file. However, you can structure the files to your personal preference and `import` accordingly. - -In Nexus, GraphQL types are defined via the `objectType` function. Import `objectType` and then start with the skeleton for your first GraphQL type. In this case, we're starting by mapping Prisma schema's `User` model to GraphQL: - -```ts copy -import { objectType } from 'nexus' - -const User = objectType({ - name: 'User', - definition(t) { - // the fields of the type will be defined here - }, -}) -``` - -With this code in place, you can start exposing the _fields_ of the `User` model one by one. You can use your editor's autocompletion to save some typing. Inside the body of the `definition` function, type `t.model.` and then hit CTRL+SPACE. This will bring up the autocompletion and suggest all fields that are defined on the `User` model: - -![Exposing Prisma model fields with t.model](./images/expose-prisma-model-fields-with-t-model.png) - -Note that the `model` property on `t` is provided by the `nexus-plugin-prisma`. It leverages the type information from your Prisma schema and lets you expose your Prisma models via GraphQL. - -In that manner, you can start completing your object type definition until you exposed all the fields of the model: - -```ts -const User = objectType({ - name: 'User', - definition(t) { - t.model.id() - t.model.email() - t.model.name() - t.model.jsonData() - t.model.role() - t.model.profile() - t.model.posts() - }, -}) -``` - -At this point, any _relation fields_ might give you TypeScript errors (in this case, that would be `profile` and `posts` which both point to other object types). That's expected, these errors will resolve automatically after you've added the remaining types. - -> **Note**: Be sure to have your Nexus development server that you started with `npm run dev` running all the time. It constantly updates the generated Nexus types that enable the autocompletion in the background as you save a file. - -Note that the `t.model.posts` relation exposes a _list_ of `Post` objects. By default, Nexus exposes only _pagination_ properties for that list – if you want to add _ordering_ and _filtering_ for that relation as well, you'll need to explicitly enable those: - -```ts line-number highlight=10-13;add -const User = objectType({ - name: 'User', - definition(t) { - t.model.id() - t.model.email() - t.model.name() - t.model.jsonData() - t.model.role() - t.model.profile() - //add-start - t.model.posts({ - filtering: true, - ordering: true, - }) - //add-end - }, -}) -``` - -After defining a type using the `objectType` function, you also need to manually add it to your GraphQL schema that you're building with Nexus. You can do it by adding it to the `types` which are provided as an option to the `makeSchema` function: - -```ts line-number -export const schema = makeSchema({ - types: [Query, User], - plugins: [nexusSchemaPrisma()], - outputs: { - schema: __dirname + '/../schema.graphql', - typegen: __dirname + '/generated/nexus.ts', - }, - typegenAutoConfig: { - sources: [ - { - source: '@prisma/client', - alias: 'prisma', - }, - ], - }, -}) -``` - -Once you're done with the first type, you can start defining the remaining ones. - -
- -Expand to view the full version of the sample data model - -To expose all sample Prisma models with Nexus, the following code is needed: - -```ts -const User = objectType({ - name: 'User', - definition(t) { - t.model.id() - t.model.email() - t.model.name() - t.model.jsonData() - t.model.role() - t.model.profile() - t.model.posts({ - filtering: true, - ordering: true, - }) - }, -}) - -const Post = objectType({ - name: 'Post', - definition(t) { - t.model.id() - t.model.createdAt() - t.model.updatedAt() - t.model.title() - t.model.content() - t.model.published() - t.model.author() - t.model.authorId() - t.model.categories({ - filtering: true, - ordering: true, - }) - }, -}) - -const Profile = objectType({ - name: 'Profile', - definition(t) { - t.model.id() - t.model.bio() - t.model.userId() - t.model.user() - }, -}) - -const Category = objectType({ - name: 'Category', - definition(t) { - t.model.id() - t.model.name() - t.model.posts({ - filtering: true, - ordering: true, - }) - }, -}) -``` - -
- -Be sure to include all newly defined types in the `types` option that's provided to `makeSchema`: - -```ts line-number highlight=2;normal -export const schema = makeSchema({ - //highlight-next-line - types: [Query, User, Post, Profile, Category], - plugins: [nexusSchemaPrisma()], - outputs: { - schema: __dirname + '/../schema.graphql', - typegen: __dirname + '/generated/nexus.ts', - }, - typegenAutoConfig: { - sources: [ - { - source: '@prisma/client', - alias: 'prisma', - }, - ], - }, -}) -``` - -You can view the current version of your GraphQL schema in SDL in the generated GraphQL schema file in `./schema.graphql`. - -## 3. Migrate GraphQL operations - -As a next step, you can start migrating all the GraphQL _queries_ and _mutations_ from the "previous" GraphQL API to the new one that's built with Nexus. - -For this guide, the following sample GraphQL schema will be used: - -```graphql -# import Post from './generated/prisma.graphql' -# import User from './generated/prisma.graphql' -# import Category from './generated/prisma.graphql' - -input UserUniqueInput { - id: String - email: String -} - -type Query { - posts(searchString: String): [Post!]! - user(userUniqueInput: UserUniqueInput!): User - users(where: UserWhereInput, orderBy: Enumerable, skip: Int, after: String, before: String, first: Int, last: Int): [User]! -} - -type Mutation { - createUser(data: UserCreateInput!): User! - createDraft(title: String!, content: String, authorId: ID!): Post - updateBio(userUniqueInput: UserUniqueInput!, bio: String!): User - addPostToCategories(postId: String!, categoryIds: [String!]!): Post -} -``` - -### 3.1. Migrate GraphQL queries - -In this section, you'll migrate all GraphQL _queries_ from `prisma-binding` to Nexus. - -#### 3.1.1. Migrate the `users` query (which uses `forwardTo`) - -In our sample API, the `users` query from the sample GraphQL schema is defined and implemented as follows. - -##### SDL schema definition with `prisma-binding` - -```graphql -type Query { - users(where: UserWhereInput, orderBy: Enumerable, skip: Int, after: String, before: String, first: Int, last: Int): [User]! - # ... other queries -} -``` - -##### Resolver implementation with `prisma-binding` - -```js -const resolvers = { - Query: { - users: forwardTo('prisma'), - // ... other resolvers - }, -} -``` - -To mirror the same behaviour with Nexus, you can use the `crud` property on the `t` variable inside the `definition` function. - -Similar to `model`, this property is available because you're using the `nexus-prisma-plugin` which leverages type information from your Prisma models and auto-generates resolvers under the hood. The `crud` property also supports autocompletion, so you can explore all available queries in your editor again: - -![Using t.crud to generate resolvers](./images/use-t-crud-to-generate-resolvers.png) - -##### Forwarding the query with the `nexus-prisma-plugin` - -To add the `users` query to your GraphQL API, add the following lines to the query type definition: - -```ts line-number highlight=3-6;add -const Query = queryType({ - definition(t) { - //add-start - t.crud.users({ - filtering: true, - ordering: true, - }) - //add-end - }, -}) -``` - -If you have the Nexus development server running, you can save the file and your GraphQL API will be updated to expose the new `users` query. You can also observe this by looking at the `Query` type inside the generated `schema.graphql` file: - -```graphql -type Query { - users(after: UserWhereUniqueInput, before: UserWhereUniqueInput, first: Int, last: Int, orderBy: Enumerable, skip: Int, where: UserWhereInput): [User!]! -} -``` - -You can now write your first query against the new API, e.g.: - -```graphql -{ - users { - id - name - profile { - id - bio - } - posts { - id - title - categories { - id - name - } - } - } -} -``` - -If your application exposes all CRUD operations from Prisma ORM using `forwardTo`, you can now continue adding all remaining ones using the same approach via `t.crud`. To learn how "custom" queries can be defined and resolved using Nexus, move on to the next sections. - -#### 3.1.2. Migrate the `posts(searchString: String): [Post!]!` query - -The `posts` query is defined and implemented as follows. - -##### SDL schema definition with `prisma-binding` - -```graphql -type Query { - posts(searchString: String): [Post!]! - # ... other queries -} -``` - -##### Resolver implementation with `prisma-binding` - -```js -const resolvers = { - Query: { - posts: (_, args, context, info) => { - return context.prisma.query.posts( - { - where: { - OR: [ - { title_contains: args.searchString }, - { content_contains: args.searchString }, - ], - }, - }, - info - ) - }, - // ... other resolvers - }, -} -``` - -##### Code-first schema definition with `nexus` - -To get the same behavior with Nexus, you'll need to add a `t.field` definition to the `queryType`: - -```ts line-number highlight=5-9;add -const Query = queryType({ - definition(t) { - // ... previous queries - - //add-start - t.list.field('posts', { - type: 'Post', - nullable: false, - args: { searchString: stringArg() }, - }) - //add-end - }, -}) -``` - -Although this code gives probably gives you a type error in your editor, you can already look at the generated SDL version of your GraphQL schema inside `schema.graphql`. You'll notice that this has added the correct _definition_ to your GraphQL schema already: - -```graphql line-number -type Query { - //highlight-next-line - posts(searchString: String): [Post!]! - users(after: UserWhereUniqueInput, before: UserWhereUniqueInput, first: Int, last: Int, orderBy: Enumerable, skip: Int, where: UserWhereInput): [User!]! -} -``` - -However, the code is missing the actual resolver logic. This is what you're going to add next. - -##### Resolver implementation with `nexus` - -You can add the resolver with Nexus as follows: - -```ts line-number highlight=9-21;add -const Query = queryType({ - definition(t) { - // ... previous queries - - t.list.field('posts', { - type: 'Post', - nullable: false, - args: { searchString: stringArg() }, - //add-start - resolve: (_, args, context) => { - return context.prisma.post.findMany({ - where: { - OR: [ - { - title: { contains: args.searchString }, - }, - { - content: { contains: args.searchString }, - }, - ], - }, - }) - //add-end - }, - }) - }, -}) -``` - -To validate the implementation, you can now e.g. send the following example query to your GraphQL server: - -```graphql -{ - posts { - id - title - author { - id - name - } - } -} -``` - -#### 3.1.2. Migrate the `user(uniqueInput: UserUniqueInput): User` query - -In our sample app, the `user` query is defined and implemented as follows. - -##### SDL schema definition with `prisma-binding` - -```graphql -type Query { - user(userUniqueInput: UserUniqueInput): User - # ... other queries -} - -input UserUniqueInput { - id: String - email: String -} -``` - -Note that this is a bit of a contrived example to demonstrate the usage of `input` types with Nexus. - -##### Resolver implementation with `prisma-binding` - -```js -const resolvers = { - Query: { - user: (_, args, context, info) => { - return context.prisma.query.user( - { - where: args.userUniqueInput, - }, - info - ) - }, - // ... other resolvers - }, -} -``` - -##### Code-first schema definition with `nexus` - -To get the same behavior with Nexus, you'll need to add a `t.field` definition to the `queryType` and define an `inputObjectType` that includes the two `@unique` fields of your `User` model: - -```ts line-number highlight=1,3-9,15-23;add -//add-next-line -import { inputObjectType, arg } from '@nexus/schema' - -//add-start -const UserUniqueInput = inputObjectType({ - name: 'UserUniqueInput', - definition(t) { - t.string('id') - t.string('email') - }, -}) -//add-end - -const Query = queryType({ - definition(t) { - // ... previous queries - - //add-start - t.field('user', { - type: 'User', - args: { - userUniqueInput: arg({ - type: 'UserUniqueInput', - nullable: false, - }), - }, - }) - //add-end - }, -}) -``` - -Since `UserUniqueInput` is a new type in your GraphQL schema, you again need to add it to the `types` option that's passed to `makeSchema`: - -```ts line-number highlight=2;normal -export const schema = makeSchema({ - //highlight-next-line - types: [Query, User, Post, Profile, Category, UserUniqueInput], - plugins: [nexusSchemaPrisma()], - outputs: { - schema: __dirname + '/../schema.graphql', - typegen: __dirname + '/generated/nexus.ts', - }, - typegenAutoConfig: { - sources: [ - { - source: '@prisma/client', - alias: 'prisma', - }, - ], - }, -}) -``` - -If you look at the generated SDL version of your GraphQL schema inside `schema.graphql`, you'll notice that this change already added the correct _definition_ to your GraphQL schema: - -```graphql line-number highlight=3,7-10;normal -type Query { - posts(searchString: String): [Post!] - //highlight-next-line - user(userUniqueInput: UserUniqueInput!): User - users(after: UserWhereUniqueInput, before: UserWhereUniqueInput, first: Int, last: Int, orderBy: Enumerable, skip: Int, where: UserWhereInput): [User!]! -} - -//highlight-start -input UserUniqueInput { - email: String - id: String -} -//highlight-end -``` - -You can even send the respective query via the GraphQL Playground already: - -```graphql -{ - user(userUniqueInput: { email: "alice@prisma.io" }) { - id - name - } -} -``` - -However, because the resolver is not yet implemented you will not get any data back yet. - -##### Code-first resolver implementation with `nexus` - -That's because you're still missing the _resolver_ implementation for that query. You can add the resolver with Nexus as follows: - -```ts line-number highlight=22-29;add -const UserUniqueInput = inputObjectType({ - name: 'UserUniqueInput', - definition(t) { - t.string('id') - t.string('email') - }, -}) - -const Query = queryType({ - definition(t) { - // ... previous queries - - t.field('user', { - type: 'User', - nullable: true, - args: { - userUniqueInput: arg({ - type: 'UserUniqueInput', - nullable: false, - }), - }, - //add-start - resolve: (_, args, context) => { - return context.prisma.user.findUnique({ - where: { - id: args.userUniqueInput?.id, - email: args.userUniqueInput?.email, - }, - }) - }, - //add-end - }) - }, -}) -``` - -If you're re-sending the same query from before, you'll find that it now returns actual data. - -### 3.2. Migrate GraphQL mutations - -In this section, you'll migrate the GraphQL mutations from the sample schema to the Nexus. - -#### 3.2.1. Define the `Mutation` type - -The first step to migrate any mutations is to define the `Mutation` type of your GraphQL API. Once that's done, you can gradually add operations to it. Add the following definition to `index.ts`: - -```ts -import { mutationType } from '@nexus/schema' - -const Mutation = mutationType({ - definition(t) { - // your GraphQL mutations + resolvers will be defined here - }, -}) -``` - -In order to make sure that the new `Mutation` type is picked by up Nexus, you need to add it to the `types` that are provided to `makeSchema`: - -```ts line-number highlight=2;normal -export const schema = makeSchema({ - //highlight-next-line - types: [Query, User, Post, Profile, Category, UserUniqueInput, Mutation], - plugins: [nexusSchemaPrisma()], - outputs: { - schema: __dirname + '/../schema.graphql', - typegen: __dirname + '/generated/nexus.ts', - }, - typegenAutoConfig: { - sources: [ - { - source: '@prisma/client', - alias: 'prisma', - }, - ], - }, -}) -``` - -#### 3.2.2. Migrate the `createUser` mutation (which uses `forwardTo`) - -In the sample app, the `createUser` mutation from the sample GraphQL schema is defined and implemented as follows. - -##### SDL schema definition with `prisma-binding` - -```graphql -type Mutation { - createUser(data: UserCreateInput!): User! - # ... other mutations -} -``` - -##### Resolver implementation with `prisma-binding` - -```js -const resolvers = { - Mutation: { - createUser: forwardTo('prisma'), - // ... other resolvers - }, -} -``` - -Similar to forwarding GraphQL queries, you can use the `crud` property on the `t` variable inside the `definition` function in order to expose full CRUD capabilities for Prisma models. - -Similar to `model`, this property is available because you're using the `nexus-prisma-plugin` which leverages type information from your Prisma models and auto-generates resolvers under the hood. The `crud` property supports autocompletion when defining mutations as well, so you can explore all available operations in your editor again: - -![Generating resolvers with t.crud](./images/regenerate-resolvers-with-t-crud.png) - -##### Forwarding the mutation with the `nexus-prisma-plugin` - -To add the `createUser` mutation to your GraphQL API, add the following lines to the query type definition: - -```ts line-number highlight=3-5;add -const Mutation = mutationType({ - definition(t) { - //add-start - t.crud.createOneUser({ - alias: 'createUser', - }) - //add-end - }, -}) -``` - -Note that the default name for the mutation in your GraphQL schema is `createOneUser` (named after the function which is exposed by `t.crud`). In order to rename it to `createUser`, you need to provide the `alias` property. - -If you have the Nexus development server running, you can save the file and your GraphQL API will be updated to expose the new `createUser` mutation. You can also observe this by looking at the `Mutation` type inside the generated `schema.graphql` file: - -```graphql -type Mutation { - createUser(data: UserCreateInput!): User! -} -``` - -You can now write your first mutation against the new API, e.g.: - -```graphql -mutation { - createUser(data: { name: "Alice", email: "alice@prisma.io" }) { - id - } -} -``` - -If your application exposes all CRUD operations from Prisma Client using `forwardTo`, you can now continue adding all remaining ones using the same approach via `t.crud`. To learn how "custom" mutations can be defined and resolved using Nexus, move on to the next sections. - -#### 3.2.3. Migrate the `createDraft(title: String!, content: String, authorId: String!): Post!` query - -In the sample app, the `createDraft` mutation is defined and implemented as follows. - -##### SDL schema definition with `prisma-binding` - -```graphql -type Mutation { - createDraft(title: String!, content: String, authorId: String!): Post! - # ... other mutations -} -``` - -##### Resolver implementation with `prisma-binding` - -```js -const resolvers = { - Mutation: { - createDraft: (_, args, context, info) => { - return context.prisma.mutation.createPost( - { - data: { - title: args.title, - content: args.content, - author: { - connect: { - id: args.authorId, - }, - }, - }, - }, - info - ) - }, - // ... other resolvers - }, -} -``` - -##### Code-first schema definition with `nexus` - -To get the same behavior with Nexus, you'll need to add a `t.field` definition to the `mutationType`: - -```ts line-number highlight=5-12;add -const Mutation = mutationType({ - definition(t) { - // ... previous mutations - - //add-start - t.field('createDraft', { - type: 'Post', - args: { - title: stringArg({ nullable: false }), - content: stringArg(), - authorId: stringArg({ nullable: false }), - }, - }) - //add-end - }, -}) -``` - -If you look at the generated SDL version of your GraphQL schema inside `schema.graphql`, you'll notice that this has added the correct _definition_ to your GraphQL schema already: - -```graphql line-number highlight=3;normal -type Mutation { - createUser(data: UserCreateInput!): User! - //highlight-next-line - createDraft(title: String!, content: String, authorId: String!): Post! -} -``` - -You can even send the respective mutation via the GraphQL Playground already: - -```graphql -mutation { - createDraft(title: "Hello World", authorId: "__AUTHOR_ID__") { - id - published - author { - id - name - } - } -} -``` - -However, because the resolver is not yet implemented, no new `Post` record will be created and you will not get any data back in the response. - -##### Resolver implementation with `nexus` - -That's because you're still missing the _resolver_ implementation for that mutation. You can add the resolver with Nexus as follows: - -```ts line-number highlight=12-22;add -const Mutation = mutationType({ - definition(t) { - // ... previous mutations - - t.field('createDraft', { - type: 'Post', - args: { - title: stringArg({ nullable: false }), - content: stringArg(), - authorId: stringArg({ nullable: false }), - }, - //add-start - resolve: (_, args, context) => { - return context.prisma.post.create({ - data: { - title: args.title, - content: args.content, - author: { - connect: { id: args.authorId }, - }, - }, - }) - }, - //add-end - }) - }, -}) -``` - -If you're re-sending the same query from before, you'll find that it now create a new `Post` record and return valid data. - -#### 3.2.4. Migrate the `updateBio(bio: String, userUniqueInput: UserUniqueInput!): User` mutation - -In the sample app, the `updateBio` mutation is defined and implemented as follows. - -##### SDL schema definition with `prisma-binding` - -```graphql -type Mutation { - updateBio(bio: String!, userUniqueInput: UserUniqueInput!): User - # ... other mutations -} -``` - -##### Resolver implementation with `prisma-binding` - -```js -const resolvers = { - Mutation: { - updateBio: (_, args, context, info) => { - return context.prisma.mutation.updateUser( - { - data: { - profile: { - update: { bio: args.bio }, - }, - }, - where: { id: args.userId }, - }, - info - ) - }, - // ... other resolvers - }, -} -``` - -##### Code-first schema definition with `nexus` - -To get the same behavior with Nexus, you'll need to add a `t.field` definition to the `mutationType`: - -```ts line-number highlight=5-14;add -const Mutation = mutationType({ - definition(t) { - // ... previous mutations - - //add-start - t.field('updateBio', { - type: 'User', - args: { - userUniqueInput: arg({ - type: 'UserUniqueInput', - nullable: false, - }), - bio: stringArg({ nullable: false }), - }, - }) - //add-end - }, -}) -``` - -If you look at the generated SDL version of your GraphQL schema inside `schema.graphql`, you'll notice that this has added the correct _definition_ to your GraphQL schema already: - -```graphql line-number highlight=4;normal -type Mutation { - createUser(data: UserCreateInput!): User! - createDraft(title: String!, content: String, authorId: String!): Post! - //highlight-next-line - updateBio(bio: String!, userUniqueInput: UserUniqueInput!): User -} -``` - -You can even send the respective mutation via the GraphQL Playground already: - -```graphql -mutation { - updateBio( - userUniqueInput: { email: "alice@prisma.io" } - bio: "I like turtles" - ) { - id - name - profile { - id - bio - } - } -} -``` - -However, because the resolver is not yet implemented, nothing will be updated in the database and you will not get any data back in the response. - -##### Resolver implementation with `nexus` - -That's because you're still missing the _resolver_ implementation for that query. You can add the resolver with Nexus as follows: - -```ts line-number highlight=14-26;add -const Mutation = mutationType({ - definition(t) { - // ... previous mutations - - t.field('updateBio', { - type: 'User', - args: { - userUniqueInput: arg({ - type: 'UserUniqueInput', - nullable: false - }), - bio: stringArg() - }, - //add-start - resolve: (_, args, context) => { - return context.prisma.user.update({ - where: { - id: args.userUniqueInput?.id, - email: args.userUniqueInput?.email - }, - data: { - profile: { - create: { bio: args.bio } - } - } - }) - } - //add-end - } - } -}) -``` - -If you're re-sending the same query from before, you'll find that it now returns actual data instead of `null`. - -#### 3.2.5. Migrate the `addPostToCategories(postId: String!, categoryIds: [String!]!): Post` mutation - -In our sample app, the `addPostToCategories` mutation is defined and implemented as follows. - -##### SDL schema definition with `prisma-binding` - -```graphql -type Mutation { - addPostToCategories(postId: String!, categoryIds: [String!]!): Post - # ... other mutations -} -``` - -##### Resolver implementation with `prisma-binding` - -```js -const resolvers = { - Mutation: { - addPostToCategories: (_, args, context, info) => { - const ids = args.categoryIds.map((id) => ({ id })) - return context.prisma.mutation.updatePost( - { - data: { - categories: { - connect: ids, - }, - }, - where: { - id: args.postId, - }, - }, - info - ) - }, - // ... other resolvers - }, -} -``` - -##### Code-first schema definition with `nexus` - -To get the same behavior with Nexus, you'll need to add a `t.field` definition to the `mutationType`: - -```ts line-number highlight=5-14;add -const Mutation = mutationType({ - definition(t) { - // ... mutations from before - - //add-start - t.field('addPostToCategories', { - type: 'Post', - args: { - postId: stringArg({ nullable: false }), - categoryIds: stringArg({ - list: true, - nullable: false, - }), - }, - }) - //add-end - }, -}) -``` - -If you look at the generated SDL version of your GraphQL schema inside `schema.graphql`, you'll notice that this has added the correct _definition_ to your GraphQL schema already: - -```graphql line-number highlight=5;normal -type Mutation { - createUser(data: UserCreateInput!): User! - createDraft(title: String!, content: String, authorId: String!): Post! - updateBio(bio: String, userUniqueInput: UserUniqueInput!): User - //highlight-next-line - addPostToCategories(postId: String!, categoryIds: [String!]!): Post -} -``` - -You can even send the respective query via the GraphQL Playground already: - -```graphql -mutation { - addPostToCategories( - postId: "__AUTHOR_ID__" - categoryIds: ["__CATEGORY_ID_1__", "__CATEGORY_ID_2__"] - ) { - id - title - categories { - id - name - } - } -} -``` - -However, because the resolver is not yet implemented, nothing will be updated in the database and you will not get any data back in the response. - -##### Resolver implementation with `nexus` - -That's because you're still missing the _resolver_ implementation for that query. You can add the resolver with Nexus as follows: - -```ts line-number highlight=13-23;add -const Mutation = mutationType({ - definition(t) { - // ... mutations from before - t.field('addPostToCategories', { - type: 'Post', - args: { - postId: stringArg({ nullable: false }), - categoryIds: stringArg({ - list: true, - nullable: false, - }), - }, - //add-start - resolve: (_, args, context) => { - const ids = args.categoryIds.map((id) => ({ id })) - return context.prisma.post.update({ - where: { - id: args.postId, - }, - data: { - categories: { connect: ids }, - }, - }) - }, - //add-end - }) - }, -}) -``` - -If you're re-sending the same query from before, you'll find that it now returns actual data instead of `null`. - -## 4. Cleaning up - -Since the entire app has now been upgrade to Prisma ORM 2.0 and Nexus, you can delete all unnecessary files and remove the no longer needed dependencies. - -### 4.1. Clean up npm dependencies - -You can start by removing npm dependencies that were related to the Prisma 1 setup: - -```copy -npm uninstall graphql-cli prisma-binding prisma1 -``` - -### 4.2. Delete unused files - -Next, delete the files of your Prisma 1 setup: - -```copy -rm prisma1/datamodel.prisma prisma1/prisma.yml -``` - -You can also delete any remaining `.js` files, the old `schema.graphql` and `prisma.graphql` files. - -### 4.3. Stop the Prisma ORM server - -Finally, you can stop running your Prisma ORM server. diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/06-upgrading-prisma-binding-to-sdl-first.mdx b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/06-upgrading-prisma-binding-to-sdl-first.mdx deleted file mode 100644 index fcca75b411..0000000000 --- a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/06-upgrading-prisma-binding-to-sdl-first.mdx +++ /dev/null @@ -1,1692 +0,0 @@ ---- -title: 'prisma-binding to SDL-first' -metaTitle: 'Upgrading from Prisma 1 with prisma-binding to SDL-first' -metaDescription: 'Learn how to upgrade existing Prisma 1 projects with prisma-binding to Prisma ORM 2 (SDL-first).' ---- - -## Overview - -This upgrade guide describes how to migrate a Node.js project that's based on [Prisma 1](https://github.com/prisma/prisma1) and uses `prisma-binding` to implement a GraphQL server. - -The code will keep the [SDL-first approach](https://www.prisma.io/blog/the-problems-of-schema-first-graphql-development-x1mn4cb0tyl3) for constructing the GraphQL schema. When migrating from `prisma-binding` to Prisma Client, the main difference is that the `info` object can't be used to resolve relations automatically any more, instead you'll need to implement your _type resolvers_ to ensure that relations get resolved properly. - -The guide assumes that you already went through the [guide for upgrading the Prisma ORM layer](/orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-the-prisma-layer-postgresql). This means you already: - -- installed the Prisma ORM 2 CLI -- created your Prisma ORM 2 schema -- introspected your database and resolved potential schema incompatibilities -- installed and generated Prisma Client - -The guide further assumes that you have a file setup that looks similar to this: - -``` -. -├── README.md -├── package.json -├── prisma -│ └── schema.prisma -├── prisma1 -│ ├── datamodel.prisma -│ └── prisma.yml -└── src - ├── generated - │ └── prisma.graphql - ├── index.js - └── schema.graphql -``` - -The important parts are: - -- A folder called with `prisma` with your Prisma ORM 2 schema -- A folder called `src` with your application code and a schema called `schema.graphql` - -If this is not what your project structure looks like, you'll need to adjust the instructions in the guide to match your own setup. - -## 1. Adjusting your GraphQL schema - -With `prisma-binding`, your approach for defining your GraphQL schema (sometimes called [application schema](https://v1.prisma.io/docs/1.20/data-model-and-migrations/data-model-knul/#a-note-on-the-application-schema)) is based on _importing_ GraphQL types from the generated `prisma.graphql` file (in Prisma 1, this is typically called [Prisma GraphQL schema](https://v1.prisma.io/docs/1.20/data-model-and-migrations/data-model-knul/#the-prisma-graphql-schema)). These types mirror the types from your Prisma 1 datamodel and serve as foundation for your GraphQL API. - -With Prisma ORM 2, there's no `prisma.graphql` file any more that you could import from. Therefore, you have to spell out all the types of your GraphQL schema directly inside your `schema.graphql` file. - -The easiest way to do so is by downloading the full GraphQL schema from the GraphQL Playground. To do so, open the **SCHEMA** tab and click the **DOWNLOAD** button in the top-right corner, then select **SDL**: - -![Downloading the GraphQL schema with GraphQL Playground](./images/download-graphql-schema.png) - -Alternatively, you can use the `get-schema` command of the [GraphQL CLI](https://github.com/Urigo/graphql-cli) to download your full schema: - -``` -npx graphql get-schema --endpoint __GRAPHQL_YOGA_ENDPOINT__ --output schema.graphql --no-all -``` - -> **Note**: With the above command, you need to replace the `__GRAPHQL_YOGA_ENDPOINT__` placeholder with the actual endpoint of your GraphQL Yoga server. - -Once you obtained the `schema.graphql` file, replace your current version in `src/schema.graphql` with the new contents. Note that the two schemas are 100% equivalent, except that the new one doesn't use [`graphql-import`](https://github.com/ardatan/graphql-import) for importing types from a different file. Instead, it spells out all types in a single file. - -Here's a comparison of these two versions of the sample GraphQL schema that we'll migrate in this guide (you can use the tabs to switch between the two versions): - - - - -```graphql -# import Post from './generated/prisma.graphql' -# import User from './generated/prisma.graphql' -# import Category from './generated/prisma.graphql' - -type Query { - posts(searchString: String): [Post!]! - user(userUniqueInput: UserUniqueInput!): User - users(where: UserWhereInput, orderBy: Enumerable, skip: Int, after: String, before: String, first: Int, last: Int): [User]! - allCategories: [Category!]! -} - -input UserUniqueInput { - id: String - email: String -} - -type Mutation { - createDraft(authorId: ID!, title: String!, content: String!): Post - publish(id: ID!): Post - deletePost(id: ID!): Post - signup(name: String!, email: String!): User! - updateBio(userId: String!, bio: String!): User - addPostToCategories(postId: String!, categoryIds: [String!]!): Post -} -``` - - - - -```graphql -type Query { - posts(searchString: String): [Post!]! - user(id: ID!): User - users(where: UserWhereInput, orderBy: Enumerable, skip: Int, after: String, before: String, first: Int, last: Int): [User]! - allCategories: [Category!]! -} - -type Category implements Node { - id: ID! - name: String! - posts(where: PostWhereInput, orderBy: Enumerable, skip: Int, after: String, before: String, first: Int, last: Int): [Post!] -} - -input CategoryCreateManyWithoutPostsInput { - create: [CategoryCreateWithoutPostsInput!] - connect: [CategoryWhereUniqueInput!] -} - -input CategoryCreateWithoutPostsInput { - id: ID - name: String! -} - -enum CategoryOrderByInput { - id_ASC - id_DESC - name_ASC - name_DESC -} - -input CategoryWhereInput { - """Logical AND on all given filters.""" - AND: [CategoryWhereInput!] - - """Logical OR on all given filters.""" - OR: [CategoryWhereInput!] - - """Logical NOT on all given filters combined by AND.""" - NOT: [CategoryWhereInput!] - id: ID - - """All values that are not equal to given value.""" - id_not: ID - - """All values that are contained in given list.""" - id_in: [ID!] - - """All values that are not contained in given list.""" - id_not_in: [ID!] - - """All values less than the given value.""" - id_lt: ID - - """All values less than or equal the given value.""" - id_lte: ID - - """All values greater than the given value.""" - id_gt: ID - - """All values greater than or equal the given value.""" - id_gte: ID - - """All values containing the given string.""" - id_contains: ID - - """All values not containing the given string.""" - id_not_contains: ID - - """All values starting with the given string.""" - id_starts_with: ID - - """All values not starting with the given string.""" - id_not_starts_with: ID - - """All values ending with the given string.""" - id_ends_with: ID - - """All values not ending with the given string.""" - id_not_ends_with: ID - name: String - - """All values that are not equal to given value.""" - name_not: String - - """All values that are contained in given list.""" - name_in: [String!] - - """All values that are not contained in given list.""" - name_not_in: [String!] - - """All values less than the given value.""" - name_lt: String - - """All values less than or equal the given value.""" - name_lte: String - - """All values greater than the given value.""" - name_gt: String - - """All values greater than or equal the given value.""" - name_gte: String - - """All values containing the given string.""" - name_contains: String - - """All values not containing the given string.""" - name_not_contains: String - - """All values starting with the given string.""" - name_starts_with: String - - """All values not starting with the given string.""" - name_not_starts_with: String - - """All values ending with the given string.""" - name_ends_with: String - - """All values not ending with the given string.""" - name_not_ends_with: String - posts_every: PostWhereInput - posts_some: PostWhereInput - posts_none: PostWhereInput -} - -input CategoryWhereUniqueInput { - id: ID -} - -scalar DateTime - -"""Raw JSON value""" -scalar Json - -"""An object with an ID""" -interface Node { - """The id of the object.""" - id: ID! -} - -type Post implements Node { - id: ID! - createdAt: DateTime! - updatedAt: DateTime! - title: String! - content: String - published: Boolean! - author: User - categories(where: CategoryWhereInput, orderBy: Enumerable, skip: Int, after: String, before: String, first: Int, last: Int): [Category!] -} - -input PostCreateManyWithoutAuthorInput { - create: [PostCreateWithoutAuthorInput!] - connect: [PostWhereUniqueInput!] -} - -input PostCreateWithoutAuthorInput { - id: ID - title: String! - content: String - published: Boolean - categories: CategoryCreateManyWithoutPostsInput -} - -enum PostOrderByInput { - id_ASC - id_DESC - createdAt_ASC - createdAt_DESC - updatedAt_ASC - updatedAt_DESC - title_ASC - title_DESC - content_ASC - content_DESC - published_ASC - published_DESC -} - -input PostWhereInput { - """Logical AND on all given filters.""" - AND: [PostWhereInput!] - - """Logical OR on all given filters.""" - OR: [PostWhereInput!] - - """Logical NOT on all given filters combined by AND.""" - NOT: [PostWhereInput!] - id: ID - - """All values that are not equal to given value.""" - id_not: ID - - """All values that are contained in given list.""" - id_in: [ID!] - - """All values that are not contained in given list.""" - id_not_in: [ID!] - - """All values less than the given value.""" - id_lt: ID - - """All values less than or equal the given value.""" - id_lte: ID - - """All values greater than the given value.""" - id_gt: ID - - """All values greater than or equal the given value.""" - id_gte: ID - - """All values containing the given string.""" - id_contains: ID - - """All values not containing the given string.""" - id_not_contains: ID - - """All values starting with the given string.""" - id_starts_with: ID - - """All values not starting with the given string.""" - id_not_starts_with: ID - - """All values ending with the given string.""" - id_ends_with: ID - - """All values not ending with the given string.""" - id_not_ends_with: ID - createdAt: DateTime - - """All values that are not equal to given value.""" - createdAt_not: DateTime - - """All values that are contained in given list.""" - createdAt_in: [DateTime!] - - """All values that are not contained in given list.""" - createdAt_not_in: [DateTime!] - - """All values less than the given value.""" - createdAt_lt: DateTime - - """All values less than or equal the given value.""" - createdAt_lte: DateTime - - """All values greater than the given value.""" - createdAt_gt: DateTime - - """All values greater than or equal the given value.""" - createdAt_gte: DateTime - updatedAt: DateTime - - """All values that are not equal to given value.""" - updatedAt_not: DateTime - - """All values that are contained in given list.""" - updatedAt_in: [DateTime!] - - """All values that are not contained in given list.""" - updatedAt_not_in: [DateTime!] - - """All values less than the given value.""" - updatedAt_lt: DateTime - - """All values less than or equal the given value.""" - updatedAt_lte: DateTime - - """All values greater than the given value.""" - updatedAt_gt: DateTime - - """All values greater than or equal the given value.""" - updatedAt_gte: DateTime - title: String - - """All values that are not equal to given value.""" - title_not: String - - """All values that are contained in given list.""" - title_in: [String!] - - """All values that are not contained in given list.""" - title_not_in: [String!] - - """All values less than the given value.""" - title_lt: String - - """All values less than or equal the given value.""" - title_lte: String - - """All values greater than the given value.""" - title_gt: String - - """All values greater than or equal the given value.""" - title_gte: String - - """All values containing the given string.""" - title_contains: String - - """All values not containing the given string.""" - title_not_contains: String - - """All values starting with the given string.""" - title_starts_with: String - - """All values not starting with the given string.""" - title_not_starts_with: String - - """All values ending with the given string.""" - title_ends_with: String - - """All values not ending with the given string.""" - title_not_ends_with: String - content: String - - """All values that are not equal to given value.""" - content_not: String - - """All values that are contained in given list.""" - content_in: [String!] - - """All values that are not contained in given list.""" - content_not_in: [String!] - - """All values less than the given value.""" - content_lt: String - - """All values less than or equal the given value.""" - content_lte: String - - """All values greater than the given value.""" - content_gt: String - - """All values greater than or equal the given value.""" - content_gte: String - - """All values containing the given string.""" - content_contains: String - - """All values not containing the given string.""" - content_not_contains: String - - """All values starting with the given string.""" - content_starts_with: String - - """All values not starting with the given string.""" - content_not_starts_with: String - - """All values ending with the given string.""" - content_ends_with: String - - """All values not ending with the given string.""" - content_not_ends_with: String - published: Boolean - - """All values that are not equal to given value.""" - published_not: Boolean - author: UserWhereInput - categories_every: CategoryWhereInput - categories_some: CategoryWhereInput - categories_none: CategoryWhereInput -} - -input PostWhereUniqueInput { - id: ID -} - -type Profile implements Node { - id: ID! - bio: String - user: User! -} - -input ProfileCreateOneWithoutUserInput { - create: ProfileCreateWithoutUserInput - connect: ProfileWhereUniqueInput -} - -input ProfileCreateWithoutUserInput { - id: ID - bio: String -} - -input ProfileWhereInput { - """Logical AND on all given filters.""" - AND: [ProfileWhereInput!] - - """Logical OR on all given filters.""" - OR: [ProfileWhereInput!] - - """Logical NOT on all given filters combined by AND.""" - NOT: [ProfileWhereInput!] - id: ID - - """All values that are not equal to given value.""" - id_not: ID - - """All values that are contained in given list.""" - id_in: [ID!] - - """All values that are not contained in given list.""" - id_not_in: [ID!] - - """All values less than the given value.""" - id_lt: ID - - """All values less than or equal the given value.""" - id_lte: ID - - """All values greater than the given value.""" - id_gt: ID - - """All values greater than or equal the given value.""" - id_gte: ID - - """All values containing the given string.""" - id_contains: ID - - """All values not containing the given string.""" - id_not_contains: ID - - """All values starting with the given string.""" - id_starts_with: ID - - """All values not starting with the given string.""" - id_not_starts_with: ID - - """All values ending with the given string.""" - id_ends_with: ID - - """All values not ending with the given string.""" - id_not_ends_with: ID - bio: String - - """All values that are not equal to given value.""" - bio_not: String - - """All values that are contained in given list.""" - bio_in: [String!] - - """All values that are not contained in given list.""" - bio_not_in: [String!] - - """All values less than the given value.""" - bio_lt: String - - """All values less than or equal the given value.""" - bio_lte: String - - """All values greater than the given value.""" - bio_gt: String - - """All values greater than or equal the given value.""" - bio_gte: String - - """All values containing the given string.""" - bio_contains: String - - """All values not containing the given string.""" - bio_not_contains: String - - """All values starting with the given string.""" - bio_starts_with: String - - """All values not starting with the given string.""" - bio_not_starts_with: String - - """All values ending with the given string.""" - bio_ends_with: String - - """All values not ending with the given string.""" - bio_not_ends_with: String - user: UserWhereInput -} - -input ProfileWhereUniqueInput { - id: ID -} - -enum Role { - ADMIN - CUSTOMER -} - -type User implements Node { - id: ID! - email: String - name: String! - posts(where: PostWhereInput, orderBy: Enumerable, skip: Int, after: String, before: String, first: Int, last: Int): [Post!] - role: Role! - profile: Profile - jsonData: Json -} - -input UserCreateInput { - id: ID - email: String - name: String! - role: Role - jsonData: Json - posts: PostCreateManyWithoutAuthorInput - profile: ProfileCreateOneWithoutUserInput -} - -enum UserOrderByInput { - id_ASC - id_DESC - email_ASC - email_DESC - name_ASC - name_DESC - role_ASC - role_DESC - jsonData_ASC - jsonData_DESC -} - -input UserWhereInput { - """Logical AND on all given filters.""" - AND: [UserWhereInput!] - - """Logical OR on all given filters.""" - OR: [UserWhereInput!] - - """Logical NOT on all given filters combined by AND.""" - NOT: [UserWhereInput!] - id: ID - - """All values that are not equal to given value.""" - id_not: ID - - """All values that are contained in given list.""" - id_in: [ID!] - - """All values that are not contained in given list.""" - id_not_in: [ID!] - - """All values less than the given value.""" - id_lt: ID - - """All values less than or equal the given value.""" - id_lte: ID - - """All values greater than the given value.""" - id_gt: ID - - """All values greater than or equal the given value.""" - id_gte: ID - - """All values containing the given string.""" - id_contains: ID - - """All values not containing the given string.""" - id_not_contains: ID - - """All values starting with the given string.""" - id_starts_with: ID - - """All values not starting with the given string.""" - id_not_starts_with: ID - - """All values ending with the given string.""" - id_ends_with: ID - - """All values not ending with the given string.""" - id_not_ends_with: ID - email: String - - """All values that are not equal to given value.""" - email_not: String - - """All values that are contained in given list.""" - email_in: [String!] - - """All values that are not contained in given list.""" - email_not_in: [String!] - - """All values less than the given value.""" - email_lt: String - - """All values less than or equal the given value.""" - email_lte: String - - """All values greater than the given value.""" - email_gt: String - - """All values greater than or equal the given value.""" - email_gte: String - - """All values containing the given string.""" - email_contains: String - - """All values not containing the given string.""" - email_not_contains: String - - """All values starting with the given string.""" - email_starts_with: String - - """All values not starting with the given string.""" - email_not_starts_with: String - - """All values ending with the given string.""" - email_ends_with: String - - """All values not ending with the given string.""" - email_not_ends_with: String - name: String - - """All values that are not equal to given value.""" - name_not: String - - """All values that are contained in given list.""" - name_in: [String!] - - """All values that are not contained in given list.""" - name_not_in: [String!] - - """All values less than the given value.""" - name_lt: String - - """All values less than or equal the given value.""" - name_lte: String - - """All values greater than the given value.""" - name_gt: String - - """All values greater than or equal the given value.""" - name_gte: String - - """All values containing the given string.""" - name_contains: String - - """All values not containing the given string.""" - name_not_contains: String - - """All values starting with the given string.""" - name_starts_with: String - - """All values not starting with the given string.""" - name_not_starts_with: String - - """All values ending with the given string.""" - name_ends_with: String - - """All values not ending with the given string.""" - name_not_ends_with: String - role: Role - - """All values that are not equal to given value.""" - role_not: Role - - """All values that are contained in given list.""" - role_in: [Role!] - - """All values that are not contained in given list.""" - role_not_in: [Role!] - posts_every: PostWhereInput - posts_some: PostWhereInput - posts_none: PostWhereInput - profile: ProfileWhereInput -} -``` - - - - -You'll notice that the new version of your GraphQL schema not only defines the _models_ that were imported directly, but also additional types (e.g. `input` types) that were not present in the schema before. - -## 2. Set up your `PrismaClient` instance - -`PrismaClient` is your new interface to the database in Prisma ORM 2. It lets you invoke various methods which build SQL queries and send them to the database, returning the results as plain JavaScript objects. - -The `PrismaClient` query API is inspired by the initial `prisma-binding` API, so a lot of the queries you send with Prisma Client will feel familiar. - -Similar to the `prisma-binding` instance from Prisma 1, you also want to attach your `PrismaClient` from Prisma ORM 2 to GraphQL's `context` so that in can be accessed inside your resolvers: - -```js line-number highlight=10-13;delete|14;add -const { PrismaClient } = require('@prisma/client') - -// ... - -const server = new GraphQLServer({ - typeDefs: 'src/schema.graphql', - resolvers, - context: (req) => ({ - ...req, - //delete-start - prisma: new Prisma({ - typeDefs: 'src/generated/prisma.graphql', - endpoint: 'http://localhost:4466', - }), - //delete-end - //add-next-line - prisma: new PrismaClient(), - }), -}) -``` - -In the code block above, the _red_ lines are the lines to be removed from your current setup, the _green_ lines are the ones that you should add. Of course, it's possible that your previous setup differed from this one (e.g. it's unlikely that your Prisma ORM `endpoint` was `http://localhost:4466` if you're running your API in production), this is just a sample to indicate what it _could_ look like. - -When you're now accessing `context.prisma` inside of a resolver, you now have access to Prisma Client queries. - -## 2. Write your GraphQL type resolvers - -`prisma-binding` was able to _magically_ resolve relations in your GraphQL schema. When not using `prisma-binding` though, you need to explicitly resolve your relations using so-called _type resolvers_. - -> **Note** You can learn more about the concept of type resolvers and why they're necessary in this article: [GraphQL Server Basics: GraphQL Schemas, TypeDefs & Resolvers Explained](https://www.prisma.io/blog/graphql-server-basics-the-schema-ac5e2950214e) - -### 2.1. Implementing the type resolver for the `User` type - -The `User` type in our sample GraphQL schema is defined as follows: - -```graphql -type User implements Node { - id: ID! - email: String - name: String! - posts( - where: PostWhereInput - orderBy: Enumerable - skip: Int - after: String - before: String - first: Int - last: Int - ): [Post!] - role: Role! - profile: Profile - jsonData: Json -} -``` - -This type has two relations: - -- The `posts` field denotes a 1-n relation to `Post` -- The `profile` field denotes a 1-1 relation to `Profile` - -Since you're not using `prisma-binding` any more, you now need to resolve these relations "manually" in type resolvers. - -You can do so by adding a `User` field to your _resolver map_ and implement the resolvers for the `posts` and `profile` relations as follows: - -```js line-number highlight=8-23;add -const resolvers = { - Query: { - // ... your query resolvers - }, - Mutation: { - // ... your mutation resolvers - }, - //add-start - User: { - posts: (parent, args, context) => { - return context.prisma.user - .findUnique({ - where: { id: parent.id }, - }) - .posts() - }, - profile: (parent, args, context) => { - return context.prisma.user - .findUnique({ - where: { id: parent.id }, - }) - .profile() - }, - }, - //add-end -} -``` - -Inside of these resolvers, you're using your new `PrismaClient` to perform a query against the database. Inside the `posts` resolver, the database query loads all `Post` records from the specified `author` (whose `id` is carried in the `parent` object). Inside the `profile` resolver, the database query loads the `Profile` record from the specified `user` (whose `id` is carried in the `parent` object). - -Thanks to these extra resolvers, you'll now be able to nest relations in your GraphQL queries/mutations whenever you're requesting information about the `User` type in a query, e.g.: - -```graphql -{ - users { - id - name - posts { - # fetching this relation is enabled by the new type resolver - id - title - } - profile { - # fetching this relation is enabled by the new type resolver - id - bio - } - } -} -``` - -### 2.2. Implementing the type resolver for the `Post` type - -The `Post` type in our sample GraphQL schema is defined as follows: - -```graphql -type Post implements Node { - id: ID! - createdAt: DateTime! - updatedAt: DateTime! - title: String! - content: String - published: Boolean! - author: User - categories( - where: CategoryWhereInput - orderBy: Enumerable - skip: Int - after: String - before: String - first: Int - last: Int - ): [Category!] -} -``` - -This type has two relations: - -- The `author` field denotes a 1-n relation to `User` -- The `categories` field denotes a m-n relation to `Category` - -Since you're not using `prisma-binding` any more, you now need to resolve these relations "manually" in type resolvers. - -You can do so by adding a `Post` field to your _resolver map_ and implement the resolvers for the `author` and `categories` relations as follows: - -```js line-number highlight=11-26;add -const resolvers = { - Query: { - // ... your query resolvers - }, - Mutation: { - // ... your mutation resolvers - }, - User: { - // ... your type resolvers for `User` from before - }, - //add-start - Post: { - author: (parent, args, context) => { - return context.prisma.post - .findUnique({ - where: { id: parent.id }, - }) - .author() - }, - categories: (parent, args, context) => { - return context.prisma.post - .findUnique({ - where: { id: parent.id }, - }) - .categories() - }, - }, - //add-end -} -``` - -Inside of these resolvers, you're using your new `PrismaClient` to perform a query against the database. Inside the `author` resolver, the database query loads the `User` record that represents the `author` of the `Post`. Inside the `categories` resolver, the database query loads all `Category` records from the specified `post` (whose `id` is carried in the `parent` object). - -Thanks to these extra resolvers, you'll now be able to nest relations in your GraphQL queries/mutations whenever you're requesting information about the `User` type in a query, e.g.: - -```graphql -{ - posts { - id - title - author { - # fetching this relation is enabled by the new type resolver - id - name - } - categories { - # fetching this relation is enabled by the new type resolver - id - name - } - } -} -``` - -### 2.3. Implementing the type resolver for the `Profile` type - -The `Profile` type in our sample GraphQL schema is defined as follows: - -```graphql -type Profile implements Node { - id: ID! - bio: String - user: User! -} -``` - -This type has one relation: The `user` field denotes a 1-n relation to `User`. - -Since you're not using `prisma-binding` any more, you now need to resolve this relation "manually" in type resolvers. - -You can do so by adding a `Profile` field to your _resolver map_ and implement the resolvers for the `owner` relation as follows: - -```js line-number highlight=14-22;add -const resolvers = { - Query: { - // ... your query resolvers - }, - Mutation: { - // ... your mutation resolvers - }, - User: { - // ... your type resolvers for `User` from before - }, - Post: { - // ... your type resolvers for `Post` from before - }, - //add-start - Profile: { - user: (parent, args, context) => { - return context.prisma.profile - .findUnique({ - where: { id: parent.id }, - }) - .owner() - }, - }, - //add-end -} -``` - -Inside of this resolver, you're using your new `PrismaClient` to perform a query against the database. Inside the `user` resolver, the database query loads the `User` records from the specified `profile` (whose `id` is carried in the `parent` object). - -Thanks to this extra resolver, you'll now be able to nest relations in your GraphQL queries/mutations whenever you're requesting information about the `Profile` type in a query. - -### 2.4. Implementing the type resolver for the `Category` type - -The `Category` type in our sample GraphQL schema is defined as follows: - -```graphql -type Category implements Node { - id: ID! - name: String! - posts( - where: PostWhereInput - orderBy: Enumerable - skip: Int - after: String - before: String - first: Int - last: Int - ): [Post!] -} -``` - -This type has one relation: The `posts` field denotes a m-n relation to `Post`. - -Since you're not using `prisma-binding` any more, you now need to resolve this relation "manually" in type resolvers. - -You can do so by adding a `Category` field to your _resolver map_ and implement the resolvers for the `posts` and `profile` relations as follows: - -```js line-number highlight=17-25;add -const resolvers = { - Query: { - // ... your query resolvers - }, - Mutation: { - // ... your mutation resolvers - }, - User: { - // ... your type resolvers for `User` from before - }, - Post: { - // ... your type resolvers for `Post` from before - }, - Profile: { - // ... your type resolvers for `User` from before - }, - //add-start - Category: { - posts: (parent, args, context) => { - return context.prisma - .findUnique({ - where: { id: parent.id }, - }) - .posts() - }, - }, - //add-end -} -``` - -Inside of this resolver, you're using your new `PrismaClient` to perform a query against the database. Inside the `posts` resolver, the database query loads all `Post` records from the specified `categories` (whose `id` is carried in the `parent` object). - -Thanks to this extra resolver, you'll now be able to nest relations in your GraphQL queries/mutations whenever you're requesting information about a `Category` type in a query. - -With all your type resolvers in place, you can start migrating the actual GraphQL API operations. - -## 3. Migrate GraphQL operations - -### 3.1. Migrate GraphQL queries - -In this section, you'll migrate all GraphQL _queries_ from `prisma-binding` to Prisma Client. - -#### 3.1.1. Migrate the `users` query (which uses `forwardTo`) - -In our sample API, the `users` query from the sample GraphQL schema is defined and implemented as follows. - -##### SDL schema definition with `prisma-binding` - -```graphql -type Query { - users(where: UserWhereInput, orderBy: Enumerable, skip: Int, after: String, before: String, first: Int, last: Int): [User]! - # ... other queries -} -``` - -##### Resolver implementation with `prisma-binding` - -```js -const resolvers = { - Query: { - users: forwardTo('prisma'), - // ... other resolvers - }, -} -``` - -##### Implementing the `users` resolver with Prisma Client - -To re-implement queries that were previously using `forwardTo`, the idea is to pass the incoming filtering, ordering and pagination arguments to `PrismaClient`: - -```js -const resolvers = { - Query: { - users: (_, args, context, info) => { - // this doesn't work yet - const { where, orderBy, skip, first, last, after, before } = args - return context.prisma.user.findMany({ - where, - orderBy, - skip, - first, - last, - after, - before, - }) - }, - // ... other resolvers - }, -} -``` - -Note that this approach does **not** work yet because the _structures_ of the incoming arguments is different from the ones expected by `PrismaClient`. To ensure the structures are compatible, you can use the `@prisma/binding-argument-transform` npm package which ensures compatibility: - -```copy -npm install @prisma/binding-argument-transform -``` - -You can now use this package as follows: - -```js -const { - makeOrderByPrisma2Compatible, - makeWherePrisma2Compatible, -} = require('@prisma/binding-argument-transform') - -const resolvers = { - Query: { - users: (_, args, context, info) => { - // this still doesn't entirely work - const { where, orderBy, skip, first, last, after, before } = args - const prisma2Where = makeWherePrisma2Compatible(where) - const prisma2OrderBy = makeOrderByPrisma2Compatible(orderBy) - return context.prisma.user.findMany({ - where: prisma2Where, - orderBy: prisma2OrderBy, - skip, - first, - last, - after, - before, - }) - }, - // ... other resolvers - }, -} -``` - -The last remaining issue with this are the pagination arguments. Prisma ORM 2 introduces a [new pagination API](https://github.com/prisma/prisma/releases/tag/2.0.0-beta.7): - -- The `first`, `last`, `before` and `after` arguments are removed -- The new `cursor` argument replaces `before` and `after` -- The new `take` argument replaces `first` and `last` - -Here is how you can adjust the call to make it compliant with the new Prisma Client pagination API: - -```js -const { - makeOrderByPrisma2Compatible, - makeWherePrisma2Compatible, -} = require('@prisma/binding-argument-transform') - -const resolvers = { - Query: { - users: (_, args, context) => { - const { where, orderBy, skip, first, last, after, before } = args - const prisma2Where = makeWherePrisma2Compatible(where) - const prisma2OrderBy = makeOrderByPrisma2Compatible(orderBy) - const skipValue = skip || 0 - const prisma2Skip = Boolean(before) ? skipValue + 1 : skipValue - const prisma2Take = Boolean(last) ? -last : first - const prisma2Before = { id: before } - const prisma2After = { id: after } - const prisma2Cursor = - !Boolean(before) && !Boolean(after) - ? undefined - : Boolean(before) - ? prisma2Before - : prisma2After - return context.prisma.user.findMany({ - where: prisma2Where, - orderBy: prisma2OrderBy, - skip: prisma2Skip, - cursor: prisma2Cursor, - take: prisma2Take, - }) - }, - // ... other resolvers - }, -} -``` - -The calculations are needed to ensure the incoming pagination arguments map properly to the ones from the Prisma Client API. - -#### 3.1.2. Migrate the `posts(searchString: String): [Post!]!` query - -The `posts` query is defined and implemented as follows. - -##### SDL schema definition with `prisma-binding` - -```graphql -type Query { - posts(searchString: String): [Post!]! - # ... other queries -} -``` - -##### Resolver implementation with `prisma-binding` - -```js -const resolvers = { - Query: { - posts: (_, args, context, info) => { - return context.prisma.query.posts( - { - where: { - OR: [ - { title_contains: args.searchString }, - { content_contains: args.searchString }, - ], - }, - }, - info - ) - }, - // ... other resolvers - }, -} -``` - -##### Implementing the `posts` resolver with Prisma Client - -To get the same behavior with the new Prisma Client, you'll need to adjust your resolver implementation: - -```js line-number highlight=3-11;normal -const resolvers = { - Query: { - //highlight-start - posts: (_, args, context) => { - return context.prisma.post.findMany({ - where: { - OR: [ - { title: { contains: args.searchString } }, - { content: { contains: args.searchString } }, - ], - }, - }) - //highlight-end - }, - // ... other resolvers - }, -} -``` - -You can now send the respective query in the GraphQL Playground: - -```graphql -{ - posts { - id - title - author { - id - name - } - } -} -``` - -#### 3.1.3. Migrate the `user(uniqueInput: UserUniqueInput): User` query - -In our sample app, the `user` query is defined and implemented as follows. - -##### SDL schema definition with `prisma-binding` - -```graphql -type Query { - user(userUniqueInput: UserUniqueInput): User - # ... other queries -} - -input UserUniqueInput { - id: String - email: String -} -``` - -##### Resolver implementation with `prisma-binding` - -```js -const resolvers = { - Query: { - user: (_, args, context, info) => { - return context.prisma.query.user( - { - where: args.userUniqueInput, - }, - info - ) - }, - // ... other resolvers - }, -} -``` - -##### Implementing the `user` resolver with Prisma Client - -To get the same behavior with the new Prisma Client, you'll need to adjust your resolver implementation: - -```js line-number highlight=3-7;normal -const resolvers = { - Query: { - //highlight-start - user: (_, args, context) => { - return context.prisma.user.findUnique({ - where: args.userUniqueInput, - }) - }, - //highlight-end - // ... other resolvers - }, -} -``` - -You can now send the respective query via the GraphQL Playground: - -```graphql -{ - user(userUniqueInput: { email: "alice@prisma.io" }) { - id - name - } -} -``` - -### 3.1. Migrate GraphQL mutations - -In this section, you'll migrate the GraphQL mutations from the sample schema. - -#### 3.1.2. Migrate the `createUser` mutation (which uses `forwardTo`) - -In the sample app, the `createUser` mutation from the sample GraphQL schema is defined and implemented as follows. - -##### SDL schema definition with `prisma-binding` - -```graphql -type Mutation { - createUser(data: UserCreateInput!): User! - # ... other mutations -} -``` - -##### Resolver implementation with `prisma-binding` - -```js -const resolvers = { - Mutation: { - createUser: forwardTo('prisma'), - // ... other resolvers - }, -} -``` - -##### Implementing the `createUser` resolver with Prisma Client - -To get the same behavior with the new Prisma Client, you'll need to adjust your resolver implementation: - -```js line-number highlight=3-7;normal -const resolvers = { - Mutation: { - //highlight-start - createUser: (_, args, context, info) => { - return context.prisma.user.create({ - data: args.data, - }) - }, - //highlight-end - // ... other resolvers - }, -} -``` - -You can now write your first mutation against the new API, e.g.: - -```graphql -mutation { - createUser(data: { name: "Alice", email: "alice@prisma.io" }) { - id - } -} -``` - -#### 3.1.3. Migrate the `createDraft(title: String!, content: String, authorId: String!): Post!` query - -In the sample app, the `createDraft` mutation is defined and implemented as follows. - -##### SDL schema definition with `prisma-binding` - -```graphql -type Mutation { - createDraft(title: String!, content: String, authorId: String!): Post! - # ... other mutations -} -``` - -##### Resolver implementation with `prisma-binding` - -```js -const resolvers = { - Mutation: { - createDraft: (_, args, context, info) => { - return context.prisma.mutation.createPost( - { - data: { - title: args.title, - content: args.content, - author: { - connect: { - id: args.authorId, - }, - }, - }, - }, - info - ) - }, - // ... other resolvers - }, -} -``` - -##### Implementing the `createDraft` resolver with Prisma Client - -To get the same behavior with the new Prisma Client, you'll need to adjust your resolver implementation: - -```js line-number highlight=3-15;normal -const resolvers = { - Mutation: { - //highlight-start - createDraft: (_, args, context, info) => { - return context.prisma.post.create({ - data: { - title: args.title, - content: args.content, - author: { - connect: { - id: args.authorId, - }, - }, - }, - }) - }, - //highlight-end - // ... other resolvers - }, -} -``` - -You can now send the respective mutation via the GraphQL Playground: - -```graphql -mutation { - createDraft(title: "Hello World", authorId: "__AUTHOR_ID__") { - id - published - author { - id - name - } - } -} -``` - -#### 3.1.4. Migrate the `updateBio(bio: String, userUniqueInput: UserUniqueInput!): User` mutation - -In the sample app, the `updateBio` mutation is defined and implemented as follows. - -##### SDL schema definition with `prisma-binding` - -```graphql -type Mutation { - updateBio(bio: String!, userUniqueInput: UserUniqueInput!): User - # ... other mutations -} -``` - -##### Resolver implementation with `prisma-binding` - -```js -const resolvers = { - Mutation: { - updateBio: (_, args, context, info) => { - return context.prisma.mutation.updateUser( - { - data: { - profile: { - update: { bio: args.bio }, - }, - }, - where: { id: args.userId }, - }, - info - ) - }, - // ... other resolvers - }, -} -``` - -##### Implementing the `updateBio` resolver with Prisma Client - -To get the same behavior with Prisma Client, you'll need to adjust your resolver implementation: - -```js line-number highlight=3-12;normal -const resolvers = { - Mutation: { - //highlight-start - updateBio: (_, args, context, info) => { - return context.prisma.user.update({ - data: { - profile: { - update: { bio: args.bio }, - }, - }, - where: args.userUniqueInput, - }) - }, - //highlight-end - // ... other resolvers - }, -} -``` - -You can now send the respective mutation via the GraphQL Playground : - -```graphql -mutation { - updateBio( - userUniqueInput: { email: "alice@prisma.io" } - bio: "I like turtles" - ) { - id - name - profile { - id - bio - } - } -} -``` - -#### 3.1.5. Migrate the `addPostToCategories(postId: String!, categoryIds: [String!]!): Post` mutation - -In our sample app, the `addPostToCategories` mutation is defined and implemented as follows. - -##### SDL schema definition with `prisma-binding` - -```graphql -type Mutation { - addPostToCategories(postId: String!, categoryIds: [String!]!): Post - # ... other mutations -} -``` - -##### Resolver implementation with `prisma-binding` - -```js -const resolvers = { - Mutation: { - addPostToCategories: (_, args, context, info) => { - const ids = args.categoryIds.map((id) => ({ id })) - return context.prisma.mutation.updatePost( - { - data: { - categories: { - connect: ids, - }, - }, - where: { - id: args.postId, - }, - }, - info - ) - }, - // ... other resolvers - }, -} -``` - -##### Implementing the `addPostToCategories` resolver with Prisma Client - -To get the same behavior with Prisma Client, you'll need to adjust your resolver implementation: - -```js line-number highlight=3-13;normal -const resolvers = { - Mutation: { - //highlight-start - addPostToCategories: (_, args, context, info) => { - const ids = args.categoryIds.map((id) => ({ id })) - return context.prisma.post.update({ - where: { - id: args.postId, - }, - data: { - categories: { connect: ids }, - }, - }) - }, - //highlight-end - // ... other resolvers - }, -} -``` - -You can now send the respective query via the GraphQL Playground: - -```graphql -mutation { - addPostToCategories( - postId: "__AUTHOR_ID__" - categoryIds: ["__CATEGORY_ID_1__", "__CATEGORY_ID_2__"] - ) { - id - title - categories { - id - name - } - } -} -``` - -## 4. Cleaning up - -Since the entire app has now been upgraded to Prisma ORM 2, you can delete all unnecessary files and remove the no longer needed dependencies. - -### 4.1. Clean up npm dependencies - -You can start by removing npm dependencies that were related to the Prisma 1 setup: - -```copy -npm uninstall graphql-cli prisma-binding prisma1 -``` - -### 4.2. Delete unused files - -Next, delete the files of your Prisma 1 setup: - -```copy -rm prisma1/datamodel.prisma prisma1/prisma.yml -``` - -### 4.3. Stop the Prisma ORM server - -Finally, you can stop running your Prisma ORM server. diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/07-upgrading-a-rest-api.mdx b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/07-upgrading-a-rest-api.mdx deleted file mode 100644 index 2db3af392f..0000000000 --- a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/07-upgrading-a-rest-api.mdx +++ /dev/null @@ -1,251 +0,0 @@ ---- -title: 'REST API' -metaTitle: 'Upgrading a REST API from Prisma 1 to Prisma ORM 2' -metaDescription: 'Learn how to upgrade a REST API from Prisma 1 to Prisma ORM 2.' ---- - -## Overview - -This upgrade guide describes how to migrate a Node.js project that's based on [Prisma 1](https://github.com/prisma/prisma1) and uses the [Prisma 1 client](https://v1.prisma.io/docs/1.34/prisma-client/) to implement a REST API. - -The guide assumes that you already went through the [guide for upgrading the Prisma ORM layer](/orm/more/upgrade-guides/upgrade-from-prisma-1/upgrading-the-prisma-layer-postgresql). This means you already: - -- installed the Prisma ORM 2 CLI -- created your Prisma ORM 2 schema -- introspected your database and resolved potential schema incompatibilities -- installed and generated Prisma Client - -The guide further assumes that you have a file setup that looks similar to this: - -``` -. -├── README.md -├── package-lock.json -├── package.json -├── prisma -│ ├── datamodel.prisma -│ ├── docker-compose-mysql.yml -│ ├── docker-compose.yml -│ ├── prisma.yml -│ └── seed.graphql -├── src -│ ├── generated -│ │ └── prisma-client -│ │ ├── index.ts -│ │ └── prisma-schema.ts -│ └── index.ts -└── tsconfig.json -``` - -The important parts are: - -- A folder called with `prisma` with your Prisma ORM 2 schema -- A folder called `src` with your application code - -If this is not what your project structure looks like, you'll need to adjust the instructions in the guide to match your own setup. - -## 1. Adjust the application to use Prisma Client 2 - -For the purpose of this guide, we'll use the sample API calls from the [`express`](https://github.com/prisma/prisma1-examples/tree/master/typescript/rest-express) example in the [`prisma1-examples`](https://github.com/prisma/prisma1-examples/) repository. - -The application code in our example is located in a single file and looks as follows: - -```ts -import * as express from 'express' -import * as bodyParser from 'body-parser' -import { prisma } from './generated/prisma-client' - -const app = express() - -app.$use(bodyParser.json()) - -app.post(`/user`, async (req, res) => { - const result = await prisma.createUser({ - ...req.body, - }) - res.json(result) -}) - -app.post(`/post`, async (req, res) => { - const { title, content, authorEmail } = req.body - const result = await prisma.createPost({ - title: title, - content: content, - author: { connect: { email: authorEmail } }, - }) - res.json(result) -}) - -app.put('/publish/:id', async (req, res) => { - const { id } = req.params - const post = await prisma.updatePost({ - where: { id }, - data: { published: true }, - }) - res.json(post) -}) - -app.delete(`/post/:id`, async (req, res) => { - const { id } = req.params - const post = await prisma.deletePost({ id }) - res.json(post) -}) - -app.get(`/post/:id`, async (req, res) => { - const { id } = req.params - const post = await prisma.post({ id }) - res.json(post) -}) - -app.get('/feed', async (req, res) => { - const posts = await prisma.post({ where: { published: true } }) - res.json(posts) -}) - -app.get('/filterPosts', async (req, res) => { - const { searchString } = req.query - const draftPosts = await prisma.post({ - where: { - OR: [ - { - title_contains: searchString, - }, - { - content_contains: searchString, - }, - ], - }, - }) - res.json(draftPosts) -}) - -app.listen(3000, () => - console.log('Server is running on http://localhost:3000') -) -``` - -Consider each occurrence of the Prisma Client instance `prisma` and replacing with the respective usage of Prisma Client 2. You can learn more in the [API Reference](/orm/prisma-client). - -### 1.1. Adjusting the import - -Import the generated `@prisma/client` node module as shown: - -```ts -import { PrismaClient } from '@prisma/client' -``` - -Note that this only imports the `PrismaClient` constructor, so you also need to instantiate a Prisma Client 2 instance: - -```ts -const prisma = new PrismaClient() -``` - -### 1.2. Adjusting the `/user` route (`POST`) - -With the Prisma Client 2 API, the `/user` route for `POST` requests has to be changed to: - -```ts -app.post(`/user`, async (req, res) => { - const result = await prisma.user.create({ - data: { - ...req.body, - }, - }) - res.json(result) -}) -``` - -### 1.3. Adjusting the `/post` route (`POST`) - -With the Prisma Client 2 API, the `/post` route for `POST` requests has to be changed to: - -```ts -app.post(`/post`, async (req, res) => { - const { title, content, authorEmail } = req.body - const result = await prisma.post.create({ - data: { - title: title, - content: content, - author: { connect: { email: authorEmail } }, - }, - }) - res.json(result) -}) -``` - -### 1.4. Adjusting the `/publish/:id` route (`PUT`) - -With the Prisma Client 2 API, the `/publish/:id` route for `PUT` requests has to be changed to: - -```ts -app.put('/publish/:id', async (req, res) => { - const { id } = req.params - const post = await prisma.post.update({ - where: { id }, - data: { published: true }, - }) - res.json(post) -}) -``` - -### 1.5. Adjusting the `/post/:id` route (`DELETE`) - -With the Prisma Client 2 API, the `//post/:id` route for `DELETE` requests has to be changed to: - -```ts -app.delete(`/post/:id`, async (req, res) => { - const { id } = req.params - const post = await prisma.post.delete({ - where: { id }, - }) - res.json(post) -}) -``` - -### 1.6. Adjusting the `/post/:id` route (`GET`) - -With the Prisma Client 2 API, the `/post/:id` route for `GET` requests has to be changed to: - -```ts -app.get(`/post/:id`, async (req, res) => { - const { id } = req.params - const post = await prisma.post.findUnique({ - where: { id }, - }) - res.json(post) -}) -``` - -### 1.7. Adjusting the `/feed` route (`GET`) - -With the Prisma Client 2 API, the `/feed` route for `GET` requests has to be changed to: - -```ts -app.get('/feed', async (req, res) => { - const posts = await prisma.post.findMany({ where: { published: true } }) - res.json(posts) -}) -``` - -### 1.8. Adjusting the `/filterPosts` route (`GET`) - -With the Prisma Client 2 API, the `/user` route for `POST` requests has to be changed to: - -```ts -app.get('/filterPosts', async (req, res) => { - const { searchString } = req.query - const filteredPosts = await prisma.post.findMany({ - where: { - OR: [ - { - title: { contains: searchString }, - }, - { - content: { contains: searchString }, - }, - ], - }, - }) - res.json(filteredPosts) -}) -``` diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/08-upgrade-from-mongodb-beta.mdx b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/08-upgrade-from-mongodb-beta.mdx deleted file mode 100644 index 16f595028f..0000000000 --- a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/08-upgrade-from-mongodb-beta.mdx +++ /dev/null @@ -1,232 +0,0 @@ ---- -title: 'Upgrade from MongoDB Beta' -metaTitle: 'Upgrade from the Prisma 1 MongoDB Beta to Prisma ORM 2 or later' -metaDescription: 'Learn how to upgrade your MongoDB application running Prisma 1 to Prisma ORM 2 or later.' ---- - -## Introduction - -This guide helps you migrate from the Prisma 1 MongoDB Beta to MongoDB on Prisma ORM 2 or later. To learn more about the differences between Prisma 1 and Prisma ORM 2.x and later, refer to [this document](/orm/more/upgrade-guides/upgrade-from-prisma-1/how-to-upgrade#main-differences-between-prisma-1-and-prisma-orm-version-2x-and-later). - -The scope of this guide is to give you the workflow necessary to perform the migration and highlight some of the problems you might encounter. - -We unfortunately can't cover all possible scenarios or changes required, but this guide should help you on your journey. Join [our Discord](https://pris.ly/discord?utm_source=docs&utm_medium=intro_text) or create an issue [on Github](https://github.com/prisma/prisma1/issues/new/choose) with any questions. - - - Perform this migration on your staging environment before trying this in - production! - - -## Requirements - -- Must be running MongoDB 4.2+ as a replica set (MongoDB Atlas does this for you automatically) -- Node.js: see [system requirements](/orm/reference/system-requirements) -- TypeScript: see [system requirements](/orm/reference/system-requirements) - -## Installing Prisma ORM 3.12.0 or later - -In your project directory run the following commands: - -```bash -$ npm install prisma@latest -$ npx prisma init --datasource-provider=mongodb -``` - -This should create the following files: - -- `prisma/schema.prisma`: An initial Prisma schema -- `.env`: Environment file where you'll store your connection string - - - -If you see the following error: - -``` -ERROR File schema.prisma already exists in your project. -Please try again in a project that is not yet using Prisma. -``` - -You have likely a `prisma/` directory in your project already. Rename that directory to something like `_prisma/` and try again - - - -## Find the Connection String to your MongoDB Database - -Next you'll want to find the connection string to your MongoDB database. You should be able to find it in your `docker-compose.yml` file or on MongoDB Atlas. It's what you'd pass to MongoDB Compass. The connection string should look something like this: - -```bash -mongodb://:@:27017 -``` - -The database that stores application data in Prisma 1 is called `default_default`, so we'll add that to the end of the connection string and update the `DATABASE_URL` key in the `.env` file - -```bash file=.env -DATABASE_URL="mongodb://prisma:prisma@localhost:27017/default_default" -``` - -## Introspect your MongoDB Database - -You're now ready to pull the structure of your database down into your Prisma Schema. - -```bash -$ npx prisma db pull -``` - -And you should see your Prisma schema in `prisma/schema.prisma` populated with your models. - - - -If you see the following error: `Error in connector: SCRAM failure: Authentication failed.`, try adding `?authSource=admin` to the end of your connection string and trying again. - - - -## Touching up your Prisma Schema - -The generated Prisma Client from a freshly introspected Prisma 1 based MongoDB database may not have the best API. You can adjust the model names and fields, just be sure to `@map` and `@@map` the original name to the underlying database collection and field names: - -```diff -- model posts { -+ model Post { - id String @id @default(auto()) @map("_id") @db.ObjectId - published Boolean - title String -+ @@map("posts") - } - -- model users { -+ model User { - id String @id @default(auto()) @map("_id") @db.ObjectId - email String @unique(map: "email_U") - name String -- posts String[] @db.ObjectId -+ postIds String[] @db.ObjectId @map("posts") - - @@index([posts], map: "posts_R") -+ @@map("users") - } -``` - -Take caution in doing these renames because you need to make sure the Prisma Schema still maps properly to the underlying database collections and field names. - -Unlike SQL databases, MongoDB doesn't have an explicit understanding of relationships between data. This means that Prisma ORM's introspection is unable to infer those relationships for you. - -We typically recommend adding the relationships by hand with the help of [this documentation](/orm/overview/databases/mongodb#how-to-add-in-missing-relations-after-introspection). However, Prisma 1 stores foreign keys is different than where Prisma ORM 2 and later expects foreign keys, so if you want to take advantage of relationships, you'll need to shift where the foreign keys are on your database before adding the relationships. - - - -💡 Download the Prisma VSCode Extension to provide autocomplete and helpful error messages as you transition your Prisma schema. - - - -## Generating a Prisma Client - -With the Prisma schema populated with the schema of your data, you're now ready to generate a Typescript Client to read and write to your MongoDB database. - -```bash -$ npx prisma generate -``` - -## Testing Reads - -Create a simple `test.ts` script to verify that Prisma Client can read and write to your application. Note that this guide is using the example in the [Prisma 1 examples repository](https://github.com/prisma/prisma1-examples/tree/master/typescript/docker-mongodb), but the code will change depending on your application. - -```ts -import { PrismaClient } from '@prisma/client' -const prisma = new PrismaClient() - -async function main() { - await prisma.$connect() - const posts = await prisma.post.findMany() - console.log(posts) -} - -main() - .catch(console.error) - .finally(() => prisma.$disconnect()) -``` - -Make sure `ts-node` is installed globally and run: - -```bash -ts-node test.ts -``` - -You should see a list of your data: - -```bash -[ - { - comments: [], - id: '62435a83fca136000996ba16', - content: 'https://www.prisma.io/day/', - published: true, - title: 'Join us for Prisma Day 2019 in Berlin', - wasCreated: 2022-03-29T19:14:11.172Z, - wasUpdated: 2022-03-29T19:14:11.172Z - }, - { - comments: [ [Object] ], - id: '62435a83fca136000996ba18', - content: 'https://graphqlweekly.com/', - published: true, - title: 'Subscribe to GraphQL Weekly for community news', - wasCreated: 2022-03-29T19:14:11.369Z, - wasUpdated: 2022-03-29T19:14:11.369Z - }, - { - comments: [], - id: '62435a83fca136000996ba1a', - content: 'https://twitter.com/prisma', - published: false, - title: 'Follow Prisma on Twitter', - wasCreated: 2022-03-29T19:14:11.375Z, - wasUpdated: 2022-03-29T19:14:11.375Z - } -] -``` - -## Testing Writes - -You can then alter your `test.ts` to try writes: - -```ts -import { PrismaClient } from '@prisma/client' -const prisma = new PrismaClient() - -async function main() { - await prisma.$connect() - const user = await prisma.user.create({ - data: { - email: 'alice@prisma.io', - name: 'Alice', - }, - }) - console.log(user) -} - -main() - .catch(console.error) - .finally(() => prisma.$disconnect()) -``` - -And you should see a user was created. - - - -If you see the following error: - -```no-lines wrap -Prisma needs to perform transactions, which requires your MongoDB server to be run as a replica set. https://pris.ly/d/mongodb-replica-set -``` - -This means that your MongoDB database isn't running as a replica set. Refer to [the link above](https://pris.ly/d/mongodb-replica-set) for steps to resolve this issue. - - - -## Upgrading your Application - -Now that you have a working Prisma Client, you can start replacing Prisma Client 1 queries with the latest Prisma Client queries. The [Prisma Client Reference](/orm/reference/prisma-client-reference#filter-conditions-and-operators) is a helpful resource for learning how to use the latest Prisma Client. - -## Conclusion - -I hope this brief guide was helpful in getting you started on the right path. Let us know if you have any questions or issues. We really appreciate your support over the years. diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/TablePlus-GUI.png b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/TablePlus-GUI.png deleted file mode 100644 index ce3615ae53..0000000000 Binary files a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/TablePlus-GUI.png and /dev/null differ diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/add-missing-default-constraints-to-columns.png b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/add-missing-default-constraints-to-columns.png deleted file mode 100644 index 58b8021662..0000000000 Binary files a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/add-missing-default-constraints-to-columns.png and /dev/null differ diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/altering-columns-to-use-enum.png b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/altering-columns-to-use-enum.png deleted file mode 100644 index 2f6088e382..0000000000 Binary files a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/altering-columns-to-use-enum.png and /dev/null differ diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/download-graphql-schema.png b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/download-graphql-schema.png deleted file mode 100644 index cfe963c4bf..0000000000 Binary files a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/download-graphql-schema.png and /dev/null differ diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/expose-prisma-model-fields-with-t-model.png b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/expose-prisma-model-fields-with-t-model.png deleted file mode 100644 index eff2fa57aa..0000000000 Binary files a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/expose-prisma-model-fields-with-t-model.png and /dev/null differ diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/fix-columns-with-json-data-types.png b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/fix-columns-with-json-data-types.png deleted file mode 100644 index 6818c41071..0000000000 Binary files a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/fix-columns-with-json-data-types.png and /dev/null differ diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/fix-incorrect-m-n-relations-sql.png b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/fix-incorrect-m-n-relations-sql.png deleted file mode 100644 index 1ad8079a24..0000000000 Binary files a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/fix-incorrect-m-n-relations-sql.png and /dev/null differ diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/fix-schema-incompatibilities.png b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/fix-schema-incompatibilities.png deleted file mode 100644 index ec99098339..0000000000 Binary files a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/fix-schema-incompatibilities.png and /dev/null differ diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/prisma-cli-introspection-flow.png b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/prisma-cli-introspection-flow.png deleted file mode 100644 index 7b12d1ee24..0000000000 Binary files a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/prisma-cli-introspection-flow.png and /dev/null differ diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/regenerate-resolvers-with-t-crud.png b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/regenerate-resolvers-with-t-crud.png deleted file mode 100644 index 05afbde8e1..0000000000 Binary files a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/regenerate-resolvers-with-t-crud.png and /dev/null differ diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/run-sql-command-to-alter-column.png b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/run-sql-command-to-alter-column.png deleted file mode 100644 index 456f7a91c7..0000000000 Binary files a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/run-sql-command-to-alter-column.png and /dev/null differ diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/use-t-crud-to-generate-resolvers.png b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/use-t-crud-to-generate-resolvers.png deleted file mode 100644 index 774c6235d0..0000000000 Binary files a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/images/use-t-crud-to-generate-resolvers.png and /dev/null differ diff --git a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/index.mdx b/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/index.mdx deleted file mode 100644 index 72c38f9174..0000000000 --- a/content/200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/index.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: 'Upgrade from Prisma 1' -metaTitle: 'Upgrade from Prisma 1 to Prisma ORM 2' -metaDescription: 'Upgrading your project from Prisma 1 to Prisma ORM 2' -staticLink: false -hide_table_of_contents: true ---- - -## In this section - - diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/500-comparing-columns-through-raw-queries.mdx b/content/200-orm/800-more/600-help-and-troubleshooting/500-comparing-columns-through-raw-queries.mdx deleted file mode 100644 index 146867f787..0000000000 --- a/content/200-orm/800-more/600-help-and-troubleshooting/500-comparing-columns-through-raw-queries.mdx +++ /dev/null @@ -1,211 +0,0 @@ ---- -title: 'Compare columns of the same table with raw queries' -metaTitle: 'Compare columns of the same table with raw queries' -metaDescription: 'Compare columns with inbuilt raw query methods in Prisma' ---- - -Comparing different columns from the same table is a common scenario that developers encounter. Some examples include comparing two numeric values in the same table or comparing two dates in a same table. There's an existing [GitHub Issue](https://github.com/prisma/prisma/issues/5048) regarding the same. - -:::warning - -From version 4.3.0, you do not need to use raw queries to compare columns in the same table. You can use the `.fields` property to [compare the columns](/orm/reference/prisma-client-reference#compare-columns-in-the-same-table). - -The below information is kept for backwards compatibility with Prisma ORM versions prior to 4.3.0. - -::: - -## Workaround - -Comparing values from two columns in the same table can be achieved by using [raw queries](/orm/prisma-client/using-raw-sql/raw-queries). - -### Comparing numeric values - - - -From version 4.3.0, you do not need to use raw queries to compare columns in the same table. You can use the `.fields` property to compare the columns. [Learn more](/orm/reference/prisma-client-reference#compare-columns-in-the-same-table) - - - -One use case for comparing values from different columns would be retrieving posts that have more comments than likes; in this case, you need to compare the values of `commentsCount` and `likesCount`. - -```prisma -model Post { - id Int @id @default(autoincrement()) - createdAt DateTime @default(now()) - updatedAt DateTime @updatedAt - title String - content String? - published Boolean @default(false) - author User @relation(fields: [authorId], references: [id]) - authorId Int - likesCount Int - commentsCount Int -} -``` - -Queries (depending upon which database) could look something like: - -_PostgreSQL / CockroachDB_ - -```js -import { PrismaClient } from '@prisma/client' - -const prisma = new PrismaClient() - -async function initiateNumbersComparisonRawQuery() { - const response = - await prisma.$queryRaw`SELECT * FROM "public"."Post" WHERE "likesCount" < "commentsCount";` - - console.log(response) -} - -await initiateNumbersComparisonRawQuery() -``` - -_MySQL_ - -```js -import { PrismaClient } from '@prisma/client' - -const prisma = new PrismaClient() - -async function initiateNumbersComparisonRawQuery() { - const response = - await prisma.$queryRaw`SELECT * FROM \`public\`.\`Post\` WHERE \`likesCount\` < \`commentsCount\`;` - - console.log(response) -} - -await initiateNumbersComparisonRawQuery() -``` - -_Sqlite_ - -```js -import { PrismaClient } from '@prisma/client' - -const prisma = new PrismaClient() - -async function initiateNumbersComparisonRawQuery() { - const response = - await prisma.$queryRaw`SELECT * FROM "Post" WHERE "likesCount" < "commentsCount";` - - console.log(response) -} - -await initiateNumbersComparisonRawQuery() -``` - -Running the above queries (depending upon the database) would filter posts that has fewer likes compared to comments. - -_Query Response_ - -```js -;[ - { - id: 1, - createdAt: '2022-03-03T12:08:11.421+00:00', - updatedAt: '2022-03-03T12:08:11.422+00:00', - title: 'Hello World', - content: 'This is my first post', - published: false, - authorId: 1, - likesCount: 50, - commentsCount: 100, - }, -] -``` - -### Comparing date values - - - -From version 4.3.0, you do not need to use raw queries to compare columns in the same table. You can use the `.fields` property to compare the columns. [Learn more](/orm/reference/prisma-client-reference#compare-columns-in-the-same-table) - - - -Similarly, if you need to compare dates, you could also achieve the same thing using raw queries. - -For example, a use case could be to get all projects completed after the due date. - -```prisma -model Project { - id Int @id @default(autoincrement()) - title String - author User @relation(fields: [authorId], references: [id]) - authorId Int - dueDate DateTime - completedDate DateTime - createdAt DateTime @default(now()) -} -``` - -Queries (depending upon the database) could look something like: - -_PostgreSQL / CockroachDB_ - -```js -import { PrismaClient } from '@prisma/client' - -const prisma = new PrismaClient() - -async function initiateDatesComparisonRawQuery() { - const response = - await prisma.$queryRaw`SELECT * FROM "public"."Project" WHERE "completedDate" > "dueDate";` - - console.log(response) -} - -await initiateDatesComparisonRawQuery() -``` - -_MySQL_ - -```js -import { PrismaClient } from '@prisma/client' - -const prisma = new PrismaClient() - -async function initiateDatesComparisonRawQuery() { - const response = - await prisma.$queryRaw`SELECT * FROM \`public\`.\`Project\` WHERE \`completedDate\` > \`dueDate\`;` - - console.log(response) -} - -await initiateDatesComparisonRawQuery() -``` - -_Sqlite_ - -```js -import { PrismaClient } from '@prisma/client' - -const prisma = new PrismaClient() - -async function initiateDatesComparisonRawQuery() { - const response = - await prisma.$queryRaw`SELECT * FROM "Project" WHERE "completedDate" > "dueDate";` - - console.log(response) -} - -await initiateDatesComparisonRawQuery() -``` - -Running the above query would fetch projects where `completedDate` is after the `dueDate`. - -_Query Response_ - -```js -;[ - { - id: 1, - title: 'Project 1', - authorId: 1, - dueDate: '2022-03-10T00:00:00+00:00', - completedDate: '2022-03-12T00:00:00+00:00', - createdAt: '2022-03-03T12:08:11.421+00:00', - }, -] -``` diff --git a/content/600-about/20-style-guide/02-word-choice.mdx b/content/600-about/20-style-guide/02-word-choice.mdx index 4560a7fd78..920f6d3e51 100644 --- a/content/600-about/20-style-guide/02-word-choice.mdx +++ b/content/600-about/20-style-guide/02-word-choice.mdx @@ -107,13 +107,13 @@ This feature is in Preview in versions 3.5.0 and later. This feature is in Preview in v3.5.0 and higher. ``` -When you write about a specific version, make it clear _what product_ you are referring to. For example, in the following sentence, version 3.11.1 might refer to Prisma or to MongoDB: +When you write about a specific version, make it clear _what product_ you are referring to. For example, in the following sentence, version 5.11.1 might refer to Prisma or to MongoDB: -_This filter is available for MongoDB only in versions 3.11.1 and later._ +_This filter is available for MongoDB only in versions 5.11.1 and later._ When the product is not clear from the context, explicitly mention the product name in front of the version number. -_This filter is available for MongoDB only in Prisma versions 3.11.1 and later._ +_This filter is available for MongoDB only in Prisma versions 5.11.1 and later._ ### In deprecation notices, mention the deprecation version number but not the planned removal version number @@ -122,12 +122,12 @@ When you explain that a feature is deprecated, include the version number in whi ```md -From v3.0.0, the `command name` command is deprecated. +From v5.0.0, the `command name` command is deprecated. -From v3.0.0, the `command name` command is deprecated. -We plan to remove `command name` in v.4.0.0. +From v5.0.0, the `command name` command is deprecated. +We plan to remove `command name` in v.6.0.0. ``` ## Abbreviate terms @@ -190,13 +190,13 @@ Use lower case for these. For "GA", the abbreviation of general availability, us ```md -We made composite types generally available in version 3.12.0. -They were previously available in preview from version 3.10.0. +We made composite types generally available in version 5.12.0. +They were previously available in preview from version 5.10.0. -We made composite types Generally Available in version 3.12.0. -They were previously available in Preview from version 3.10.0. +We made composite types Generally Available in version 5.12.0. +They were previously available in Preview from version 5.10.0. ``` ### SQL