From 539fc80611c0beb1ecb94a1404780be724375c42 Mon Sep 17 00:00:00 2001 From: Jan Piotrowski Date: Wed, 1 Feb 2023 02:11:35 +0100 Subject: [PATCH 01/13] feat(views): PostgreSQL Introspection --- .../100-components/01-prisma-schema/08-views.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx index 0f4a9ea13e..8886fb007c 100644 --- a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx +++ b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx @@ -162,12 +162,24 @@ view UserInfo { +### Write by Hand + +### Use Introspection + ### Limitations +#### Unique Identifier + +TODO De-emphasize `@(@)id` and focus on `@(@)unique` instead + Currently, Prisma treats views in the same way as models. This means that a view needs to have a [unique identifier](/concepts/components/prisma-schema/data-model#defining-an-id-field). In relational databases, this can be an `@id` or `@unique` attribute on one field, or an `@@id` or `@@unique` attribute on multiple fields. In MongoDB, this must be an `@id` attribute that maps to the `_id` field in the underlying database with `@map("_id")`. In the example above, the `id` field has an `@id` attribute. +#### Introspection + +TODO Change to highlight that Introspection is only available for PostgreSQL. (Re-Introspection limitation can be removed) + Prisma does not currently support introspection of views with `db pull`. Instead, you must manually add views to your Prisma schema. From 5068578db425d858da4f80bae79f6a146be369a5 Mon Sep 17 00:00:00 2001 From: Jan Piotrowski Date: Wed, 1 Feb 2023 02:18:05 +0100 Subject: [PATCH 02/13] Update 08-views.mdx --- .../100-components/01-prisma-schema/08-views.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx index 8886fb007c..c9e1b7ab8a 100644 --- a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx +++ b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx @@ -164,13 +164,17 @@ view UserInfo { ### Write by Hand +TODO Describe how to write such a `view` block by hand that represents the columns of the view query result + ### Use Introspection +TODO `db pull` + ### Limitations #### Unique Identifier -TODO De-emphasize `@(@)id` and focus on `@(@)unique` instead +TODO De-emphasize `@(@)id` and focus on `@(@)unique` instead, also update examples above Currently, Prisma treats views in the same way as models. This means that a view needs to have a [unique identifier](/concepts/components/prisma-schema/data-model#defining-an-id-field). In relational databases, this can be an `@id` or `@unique` attribute on one field, or an `@@id` or `@@unique` attribute on multiple fields. In MongoDB, this must be an `@id` attribute that maps to the `_id` field in the underlying database with `@map("_id")`. From 922e1f39f1119cf1b6d8a900b249efb0be710797 Mon Sep 17 00:00:00 2001 From: Sabin Adams Date: Thu, 2 Feb 2023 09:31:15 -0800 Subject: [PATCH 03/13] Updates introspection section --- .../100-components/01-prisma-schema/08-views.mdx | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx index eadf9ad05f..7f3d916c81 100644 --- a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx +++ b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx @@ -174,7 +174,7 @@ TODO `db pull` ### Limitations -#### Unique Identifier +#### Unique Identifier TODO De-emphasize `@(@)id` and focus on `@(@)unique` instead, also update examples above @@ -184,15 +184,7 @@ In the example above, the `id` field has an `@id` attribute. #### Introspection -TODO Change to highlight that Introspection is only available for PostgreSQL. (Re-Introspection limitation can be removed) - -Prisma does not currently support introspection of views with `db pull`. Instead, you must manually add views to your Prisma schema. - - - -Currently, if you introspect your database, Prisma removes any existing `view` blocks in your schema file. To reinstate the views, you must revert this change. - - +Currently, introspection of views is only available for PostgreSQL. If you are using another database provider, your views must be added manually. ## Query views in Prisma Client From 91298c3e927a6cda0b154d5c31891b7bd54c1b95 Mon Sep 17 00:00:00 2001 From: Sabin Adams Date: Thu, 2 Feb 2023 10:24:36 -0800 Subject: [PATCH 04/13] Adds sections for manually writing a view --- .../01-prisma-schema/08-views.mdx | 59 ++++++++++++++++++- 1 file changed, 58 insertions(+), 1 deletion(-) diff --git a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx index 7f3d916c81..526362ada0 100644 --- a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx +++ b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx @@ -166,7 +166,64 @@ view UserInfo { ### Write by Hand -TODO Describe how to write such a `view` block by hand that represents the columns of the view query result +A `view` block is comprised of two main pieces: + +- The `view` block definition +- The view's field definitions + +These two pieces allow you to define the name of your view in the generated Prisma Client and the columns present in a view's query results. + +#### Define a `view` block + +To define the `UserInfo` view from the example above, begin by using the `view` keyword to define a `view` block in your schema named `UserInfo`: + +```prisma copy +view UserInfo { +// Fields +} +``` + + + +#### Define fields + +The properties of a view are called _fields_, which consist of: + +- A field name +- A field type + + + +The fields of the `UserInfo` example view can be defined as follows: + +, ]}> + + +```prisma +view UserInfo { ++ id Int @id ++ email String ++ name String ++ bio String +} +``` + + + + +```prisma +view UserInfo { ++ id String @id @default(auto()) @map("_id") @db.ObjectId ++ email String ++ name String ++ bio String +} +``` + + + + +Each _field_ of a `view` block represents a column in the query results of the view in the underlying database. ### Use Introspection From 6efe7f784f879e4cf037564c9a362e1b88adc424 Mon Sep 17 00:00:00 2001 From: Sabin Adams Date: Thu, 2 Feb 2023 11:09:04 -0800 Subject: [PATCH 05/13] Adds introspection instructions --- .../01-prisma-schema/08-views.mdx | 56 ++++++++++++++++--- 1 file changed, 49 insertions(+), 7 deletions(-) diff --git a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx index 526362ada0..323b9e0521 100644 --- a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx +++ b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx @@ -140,7 +140,7 @@ You can represent the `UserInfo` view from the example above in your Prisma sche ```prisma view UserInfo { - id Int @id + id Int @unique email String name String bio String @@ -152,7 +152,7 @@ view UserInfo { ```prisma view UserInfo { - id String @id @default(auto()) @map("_id") @db.ObjectId + id String @unique email String name String bio String @@ -199,9 +199,9 @@ The fields of the `UserInfo` example view can be defined as follows: , ]}> -```prisma +```prisma copy view UserInfo { -+ id Int @id ++ id Int @unique + email String + name String + bio String @@ -211,9 +211,9 @@ view UserInfo { -```prisma +```prisma copy view UserInfo { -+ id String @id @default(auto()) @map("_id") @db.ObjectId ++ id String @unique + email String + name String + bio String @@ -227,7 +227,49 @@ Each _field_ of a `view` block represents a column in the query results of the v ### Use Introspection -TODO `db pull` +If you have an existing view or views defined in your database, [introspection](/concepts/components/introspection) will automatically generate `view` blocks in your Prisma schema that represents those views. + +Assuming the example `UserInfo` view exists in your underlying database, running the following command will generate a `view` block in your Prisma schema representing that view: + +```sh copy +npx prisma db pull +``` + +The resulting `view` block will be defined as follows: + +```prisma +/// The underlying view does not contain a valid unique identifier and can therefore currently not be handled by the Prisma Client. +view UserInfo { +id Int? +email String? +name String? +bio String? +@@ignore +} +``` + +The `view` block is generated initially with a `@@ignore` attribute because there is no [unique identifier](/concepts/components/prisma-schema/data-model#defining-an-id-field) defined. + +In order to make this `view` block valid, add the [`@unique`]() attribute to the `id` field and remove the `@@ignore` attribute: + +```prisma copy highlight=3;edit|1,8;delete +/// The underlying view does not contain a valid unique identifier and can therefore currently not be handled by the Prisma Client. +view UserInfo { +id Int @unique +email String? +name String? +bio String? +@@ignore +} +``` + +When re-introspecting your database, any custom changes to your view definitions will be preserved. + + + +Please note the [limitations](/concepts/components/prisma-schema/views#introspection) of this feature described below. + + ### Limitations From 445dfbe0d1c21276891c424843cff4074ac8bf78 Mon Sep 17 00:00:00 2001 From: Sabin Adams Date: Thu, 2 Feb 2023 11:19:23 -0800 Subject: [PATCH 06/13] de-emphasizes @id @@id --- .../100-components/01-prisma-schema/08-views.mdx | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx index 323b9e0521..c9dd69ee47 100644 --- a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx +++ b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx @@ -152,7 +152,7 @@ view UserInfo { ```prisma view UserInfo { - id String @unique + id String @id @default(auto()) @map("_id") @db.ObjectId email String name String bio String @@ -199,7 +199,7 @@ The fields of the `UserInfo` example view can be defined as follows: , ]}> -```prisma copy +```prisma highlight=2-5;normal view UserInfo { + id Int @unique + email String @@ -211,7 +211,7 @@ view UserInfo { -```prisma copy +```prisma highlight=2-5;normal view UserInfo { + id String @unique + email String @@ -238,7 +238,6 @@ npx prisma db pull The resulting `view` block will be defined as follows: ```prisma -/// The underlying view does not contain a valid unique identifier and can therefore currently not be handled by the Prisma Client. view UserInfo { id Int? email String? @@ -252,8 +251,7 @@ The `view` block is generated initially with a `@@ignore` attribute because ther In order to make this `view` block valid, add the [`@unique`]() attribute to the `id` field and remove the `@@ignore` attribute: -```prisma copy highlight=3;edit|1,8;delete -/// The underlying view does not contain a valid unique identifier and can therefore currently not be handled by the Prisma Client. +```prisma highlight=2;edit|7;delete view UserInfo { id Int @unique email String? @@ -275,11 +273,11 @@ Please note the [limitations](/concepts/components/prisma-schema/views#introspec #### Unique Identifier -TODO De-emphasize `@(@)id` and focus on `@(@)unique` instead, also update examples above +Currently, Prisma treats views in the same way as models. This means that a view needs to have a [unique identifier](/concepts/components/prisma-schema/data-model#defining-an-id-field). -Currently, Prisma treats views in the same way as models. This means that a view needs to have a [unique identifier](/concepts/components/prisma-schema/data-model#defining-an-id-field). In relational databases, this can be an `@id` or `@unique` attribute on one field, or an `@@id` or `@@unique` attribute on multiple fields. In MongoDB, this must be an `@id` attribute that maps to the `_id` field in the underlying database with `@map("_id")`. +In relational databases, a view's unique identifier can be defined as a `@unique` attribute on one field, or a `@@unique` attribute on multiple fields. In MongoDB, the unique identifier must be an `@id` attribute that maps to the `_id` field in the underlying database with `@map("_id")`. -In the example above, the `id` field has an `@id` attribute. +In the example above, the `id` field has a `@unique` attribute. #### Introspection From 0ccf1930ddefffe545fd2054704612d3ef021e14 Mon Sep 17 00:00:00 2001 From: Sabin Adams Date: Thu, 2 Feb 2023 11:30:03 -0800 Subject: [PATCH 07/13] Revisions --- .../01-prisma-schema/08-views.mdx | 44 ++++++++++--------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx index c9dd69ee47..5deb1d761b 100644 --- a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx +++ b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx @@ -171,15 +171,15 @@ A `view` block is comprised of two main pieces: - The `view` block definition - The view's field definitions -These two pieces allow you to define the name of your view in the generated Prisma Client and the columns present in a view's query results. +These two pieces allow you to define the name of your view in the generated Prisma Client and the columns present in your view's query results. #### Define a `view` block To define the `UserInfo` view from the example above, begin by using the `view` keyword to define a `view` block in your schema named `UserInfo`: -```prisma copy +```prisma view UserInfo { -// Fields + // Fields } ``` @@ -201,10 +201,10 @@ The fields of the `UserInfo` example view can be defined as follows: ```prisma highlight=2-5;normal view UserInfo { -+ id Int @unique -+ email String -+ name String -+ bio String + id Int @unique + email String + name String + bio String } ``` @@ -213,10 +213,10 @@ view UserInfo { ```prisma highlight=2-5;normal view UserInfo { -+ id String @unique -+ email String -+ name String -+ bio String + id String @unique + email String + name String + bio String } ``` @@ -239,11 +239,12 @@ The resulting `view` block will be defined as follows: ```prisma view UserInfo { -id Int? -email String? -name String? -bio String? -@@ignore + id Int? + email String? + name String? + bio String? + + @@ignore } ``` @@ -253,11 +254,12 @@ In order to make this `view` block valid, add the [`@unique`]() attribute to the ```prisma highlight=2;edit|7;delete view UserInfo { -id Int @unique -email String? -name String? -bio String? -@@ignore + id Int @unique + email String? + name String? + bio String? + + @@ignore } ``` From 8cf90babec49ba23973944c00445b7e71e81cc05 Mon Sep 17 00:00:00 2001 From: Sabin Adams Date: Thu, 2 Feb 2023 17:06:23 -0800 Subject: [PATCH 08/13] Updates phrasing and clarifies db pull messaging --- .../100-components/01-prisma-schema/08-views.mdx | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx index 5deb1d761b..4bde3cd0bb 100644 --- a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx +++ b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx @@ -11,7 +11,7 @@ tocDepth: 2 -Support for views is currently a very early preview feature. You can add a view to your Prisma schema with the `view` keyword, but you cannot introspect your schema with `db pull` or apply your schema to your database with Prisma Migrate and `db push`.

For updates on progress with this feature, follow [our GitHub issue](https://github.com/prisma/prisma/issues/17335). +Support for views is currently a very early preview feature. You can add a view to your Prisma schema with the `view` keyword or introspect the views in your schema with `db pull`.

For updates on progress with this feature, follow [our GitHub issue](https://github.com/prisma/prisma/issues/17335). @@ -250,7 +250,9 @@ view UserInfo { The `view` block is generated initially with a `@@ignore` attribute because there is no [unique identifier](/concepts/components/prisma-schema/data-model#defining-an-id-field) defined. -In order to make this `view` block valid, add the [`@unique`]() attribute to the `id` field and remove the `@@ignore` attribute: +In this view's case, the `id` column refers to a uniquely identifiable field in the underlying `User` table so that field will also be used as the uniquely identifiable field in the `view` block. + +In order to make this `view` block valid, add the `@unique` attribute to the `id` field and remove the `@@ignore` attribute: ```prisma highlight=2;edit|7;delete view UserInfo { @@ -267,7 +269,7 @@ When re-introspecting your database, any custom changes to your view definitions -Please note the [limitations](/concepts/components/prisma-schema/views#introspection) of this feature described below. +Please note for now `db pull` will only introspect views in your schema when using PostgreSQL. Support for this workflow will be extended to other database providers soon. @@ -279,11 +281,13 @@ Currently, Prisma treats views in the same way as models. This means that a view In relational databases, a view's unique identifier can be defined as a `@unique` attribute on one field, or a `@@unique` attribute on multiple fields. In MongoDB, the unique identifier must be an `@id` attribute that maps to the `_id` field in the underlying database with `@map("_id")`. -In the example above, the `id` field has a `@unique` attribute. +In the example above, the `id` field has a `@unique` attribute. If another column in the underlying `User` table had been defined as uniquely identifiable and made available in the view's query results, that column could have been used as the unique identifier instead. #### Introspection -Currently, introspection of views is only available for PostgreSQL. If you are using another database provider, your views must be added manually. +Currently, introspection of views is only available for PostgreSQL. If you are using another database provider, your views must be added manually. + +This is a temporary limitation and will be extended soon to the other supported datasource providers. ## Query views in Prisma Client From 50647050e8779f1ffa5aeb6f5cac7c4895c64cde Mon Sep 17 00:00:00 2001 From: Sabin Adams Date: Thu, 2 Feb 2023 17:08:57 -0800 Subject: [PATCH 09/13] Further clarification made --- .../200-concepts/100-components/01-prisma-schema/08-views.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx index 4bde3cd0bb..f2a35e9c4c 100644 --- a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx +++ b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx @@ -287,7 +287,7 @@ In the example above, the `id` field has a `@unique` attribute. If another colum Currently, introspection of views is only available for PostgreSQL. If you are using another database provider, your views must be added manually. -This is a temporary limitation and will be extended soon to the other supported datasource providers. +This is a temporary limitation and support for introspection will be extended soon to the other supported datasource providers. ## Query views in Prisma Client From f87c447933e00dc0d8c23f3721525cc0ab07a390 Mon Sep 17 00:00:00 2001 From: Nikolas Date: Fri, 3 Feb 2023 11:02:23 +0100 Subject: [PATCH 10/13] Update content/200-concepts/100-components/01-prisma-schema/08-views.mdx --- .../200-concepts/100-components/01-prisma-schema/08-views.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx index f2a35e9c4c..d3d492ec11 100644 --- a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx +++ b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx @@ -11,7 +11,7 @@ tocDepth: 2 -Support for views is currently a very early preview feature. You can add a view to your Prisma schema with the `view` keyword or introspect the views in your schema with `db pull`.

For updates on progress with this feature, follow [our GitHub issue](https://github.com/prisma/prisma/issues/17335). +Support for views is currently a very early [Preview](/about/prisma/releases#preview) feature. You can add a view to your Prisma schema with the `view` keyword or introspect the views in your schema with `db pull`.

For updates on progress with this feature, follow [our GitHub issue](https://github.com/prisma/prisma/issues/17335). From 5ed5e1e088fc164d9c8107944ee1ff17088e88e1 Mon Sep 17 00:00:00 2001 From: Sabin Adams Date: Fri, 3 Feb 2023 08:51:59 -0800 Subject: [PATCH 11/13] Adjusts based on review feedback --- .../01-prisma-schema/08-views.mdx | 21 ++++++++++++------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx index d3d492ec11..af91483aaf 100644 --- a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx +++ b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx @@ -94,7 +94,7 @@ For a relational database, the SQL statement to create this view is: CREATE VIEW "UserInfo" AS SELECT u.id, email, name, bio FROM "User" u - LEFT JOIN "Profile" p ON u.id = p."userId" + LEFT JOIN "Profile" p ON u.id = p."userId"; ``` For MongoDB, you can [create a view](https://www.mongodb.com/docs/manual/core/views/join-collections-with-view/) with the following command: @@ -123,7 +123,7 @@ db.createView('UserInfo', 'User', [ ## Use views with Prisma Migrate and db push -If you apply changes to your schema with Prisma Migrate or `db push`, Prisma does not create or run any SQL related to views. +Prisma does not create or run any SQL related to views. To include views in a migration, run `migrate dev --create-only` and then manually add the SQL for views to your migration file. Alternatively, you can create views manually in the database. @@ -164,7 +164,7 @@ view UserInfo { -### Write by Hand +### Write by hand A `view` block is comprised of two main pieces: @@ -213,7 +213,7 @@ view UserInfo { ```prisma highlight=2-5;normal view UserInfo { - id String @unique + id String @id @default(auto()) @map("_id") @db.ObjectId email String name String bio String @@ -225,9 +225,9 @@ view UserInfo { Each _field_ of a `view` block represents a column in the query results of the view in the underlying database. -### Use Introspection +### Use introspection -If you have an existing view or views defined in your database, [introspection](/concepts/components/introspection) will automatically generate `view` blocks in your Prisma schema that represents those views. +If you have an existing view or views defined in your database, [introspection](/concepts/components/introspection) will automatically generate `view` blocks in your Prisma schema that represent those views. Assuming the example `UserInfo` view exists in your underlying database, running the following command will generate a `view` block in your Prisma schema representing that view: @@ -248,7 +248,7 @@ view UserInfo { } ``` -The `view` block is generated initially with a `@@ignore` attribute because there is no [unique identifier](/concepts/components/prisma-schema/data-model#defining-an-id-field) defined. +The `view` block is generated initially with a `@@ignore` attribute because [there is no unique identifier defined](#unique-identifier) (which is a currently a [limitation](#unique-identifier) of the views implementation in Prisma). In this view's case, the `id` column refers to a uniquely identifiable field in the underlying `User` table so that field will also be used as the uniquely identifiable field in the `view` block. @@ -277,7 +277,12 @@ Please note for now `db pull` will only introspect views in your schema when usi #### Unique Identifier -Currently, Prisma treats views in the same way as models. This means that a view needs to have a [unique identifier](/concepts/components/prisma-schema/data-model#defining-an-id-field). +Currently, Prisma treats views in the same way as models. This means that a view needs to have at least one _unique identifier_, which can be represented by any of the following: + +- An [`@id`](/concepts/components/prisma-schema/data-model#defining-an-id-field) field +- A composite identifier denoted with [`@@id`](/concepts/components/prisma-schema/data-model#composite-ids) +- A unique constraint denoted with [`@unique`](/concepts/components/prisma-schema/data-model#defining-a-unique-field) +- A composite unique constraint denoted with [`@@unique`](/concepts/components/prisma-schema/data-model#defining-a-unique-field) In relational databases, a view's unique identifier can be defined as a `@unique` attribute on one field, or a `@@unique` attribute on multiple fields. In MongoDB, the unique identifier must be an `@id` attribute that maps to the `_id` field in the underlying database with `@map("_id")`. From a80525ecd7ab4c83520df342a79583479c73adbe Mon Sep 17 00:00:00 2001 From: Sabin Adams Date: Fri, 3 Feb 2023 10:09:44 -0800 Subject: [PATCH 12/13] Adjusts messaging around what is and isn't currently possible --- .../01-prisma-schema/08-views.mdx | 22 +++++++++++-------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx index af91483aaf..0dbb397aae 100644 --- a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx +++ b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx @@ -11,7 +11,7 @@ tocDepth: 2 -Support for views is currently a very early [Preview](/about/prisma/releases#preview) feature. You can add a view to your Prisma schema with the `view` keyword or introspect the views in your schema with `db pull`.

For updates on progress with this feature, follow [our GitHub issue](https://github.com/prisma/prisma/issues/17335). +Support for views is currently a very early [Preview](/about/prisma/releases#preview) feature. You can add a view to your Prisma schema with the `view` keyword or introspect the views in your database schema with `db pull`. You cannot yet apply views in your schema to your database with Prisma Migrate and `db push` unless the changes are added manually to your migration file using the `--create-only` flag.

For updates on progress with this feature, follow [our GitHub issue](https://github.com/prisma/prisma/issues/17335). @@ -123,7 +123,7 @@ db.createView('UserInfo', 'User', [ ## Use views with Prisma Migrate and db push -Prisma does not create or run any SQL related to views. +If you apply changes to your Prisma schema with Prisma Migrate or `db push`, Prisma does not create or run any SQL related to views. To include views in a migration, run `migrate dev --create-only` and then manually add the SQL for views to your migration file. Alternatively, you can create views manually in the database. @@ -192,8 +192,6 @@ The properties of a view are called _fields_, which consist of: - A field name - A field type - - The fields of the `UserInfo` example view can be defined as follows: , ]}> @@ -227,6 +225,10 @@ Each _field_ of a `view` block represents a column in the query results of the v ### Use introspection + +Currently only available for PostgreSQL. + + If you have an existing view or views defined in your database, [introspection](/concepts/components/introspection) will automatically generate `view` blocks in your Prisma schema that represent those views. Assuming the example `UserInfo` view exists in your underlying database, running the following command will generate a `view` block in your Prisma schema representing that view: @@ -248,13 +250,13 @@ view UserInfo { } ``` -The `view` block is generated initially with a `@@ignore` attribute because [there is no unique identifier defined](#unique-identifier) (which is a currently a [limitation](#unique-identifier) of the views implementation in Prisma). +The `view` block is generated initially with a `@@ignore` attribute because [there is no unique identifier defined](#unique-identifier) (which is currently a [limitation](#unique-identifier) of the views preview feature). In this view's case, the `id` column refers to a uniquely identifiable field in the underlying `User` table so that field will also be used as the uniquely identifiable field in the `view` block. In order to make this `view` block valid, add the `@unique` attribute to the `id` field and remove the `@@ignore` attribute: -```prisma highlight=2;edit|7;delete +```prisma highlight=2;edit|6,7;delete view UserInfo { id Int @unique email String? @@ -279,12 +281,14 @@ Please note for now `db pull` will only introspect views in your schema when usi Currently, Prisma treats views in the same way as models. This means that a view needs to have at least one _unique identifier_, which can be represented by any of the following: -- An [`@id`](/concepts/components/prisma-schema/data-model#defining-an-id-field) field -- A composite identifier denoted with [`@@id`](/concepts/components/prisma-schema/data-model#composite-ids) - A unique constraint denoted with [`@unique`](/concepts/components/prisma-schema/data-model#defining-a-unique-field) - A composite unique constraint denoted with [`@@unique`](/concepts/components/prisma-schema/data-model#defining-a-unique-field) +- An [`@id`](/concepts/components/prisma-schema/data-model#defining-an-id-field) field +- A composite identifier denoted with [`@@id`](/concepts/components/prisma-schema/data-model#composite-ids) + +In relational databases, a view's unique identifier can be defined as a `@unique` attribute on one field, or a `@@unique` attribute on multiple fields. When possible, it is preferable to use a `@unique` or `@@unique` constraint over an `@id` or `@@id` field. -In relational databases, a view's unique identifier can be defined as a `@unique` attribute on one field, or a `@@unique` attribute on multiple fields. In MongoDB, the unique identifier must be an `@id` attribute that maps to the `_id` field in the underlying database with `@map("_id")`. +In MongoDB, however, the unique identifier must be an `@id` attribute that maps to the `_id` field in the underlying database with `@map("_id")`. In the example above, the `id` field has a `@unique` attribute. If another column in the underlying `User` table had been defined as uniquely identifiable and made available in the view's query results, that column could have been used as the unique identifier instead. From 2c0dd55fb73108a8d232476ed70b686112b56af4 Mon Sep 17 00:00:00 2001 From: Sabin Adams Date: Mon, 6 Feb 2023 10:41:28 -0800 Subject: [PATCH 13/13] clarifies instructions on fixing an invalid view --- .../100-components/01-prisma-schema/08-views.mdx | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx index 0dbb397aae..a202c719a6 100644 --- a/content/200-concepts/100-components/01-prisma-schema/08-views.mdx +++ b/content/200-concepts/100-components/01-prisma-schema/08-views.mdx @@ -240,6 +240,7 @@ npx prisma db pull The resulting `view` block will be defined as follows: ```prisma +/// The underlying view does not contain a valid unique identifier and can therefore currently not be handled by the Prisma Client. view UserInfo { id Int? email String? @@ -254,10 +255,17 @@ The `view` block is generated initially with a `@@ignore` attribute because [the In this view's case, the `id` column refers to a uniquely identifiable field in the underlying `User` table so that field will also be used as the uniquely identifiable field in the `view` block. -In order to make this `view` block valid, add the `@unique` attribute to the `id` field and remove the `@@ignore` attribute: +In order to make this `view` block valid you will need to: -```prisma highlight=2;edit|6,7;delete +- Remove the _optional_ flag `?` from the `id` field +- Add the `@unique` attribute to the `id` field +- Remove the `@@ignore` attribute +- Remove the comment Prisma generated warning about an invalid view + +```prisma highlight=4;add|1,3,8,9;delete +/// The underlying view does not contain a valid unique identifier and can therefore currently not be handled by the Prisma Client. view UserInfo { + id Int? id Int @unique email String? name String?