From d6b1bb3dd5f7411b9c5be915766e90bc808991c1 Mon Sep 17 00:00:00 2001 From: Nikolas Burk Date: Thu, 7 Aug 2025 15:40:16 +0200 Subject: [PATCH 1/6] update docs for sql views --- .../20-data-model/40-views.mdx | 34 ++++++++++--------- 1 file changed, 18 insertions(+), 16 deletions(-) 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 c99befd7b4..fa0d85140c 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 @@ -12,17 +12,16 @@ Database views allow you to name and store queries. In relational databases, vie The `views` preview feature allows you to represent views in your Prisma schema with the `view` keyword. To use views in Prisma ORM, follow these steps: -- [Enable the `views` preview feature](#enable-the-views-preview-feature) -- [Create a view in the underlying database](#create-a-view-in-the-underlying-database), either directly or as a [manual addition to a Prisma Migrate migration file](#use-views-with-prisma-migrate-and-db-push), or use an existing view -- [Represent the view in your Prisma schema](#add-views-to-your-prisma-schema) -- [Query the view in Prisma Client](#query-views-in-prisma-client) +1. [Enable the `views` preview feature](#enable-the-views-preview-feature) +1. [Create a view in the underlying database](#create-a-view-in-the-underlying-database), either directly or as a [manual addition to a Prisma Migrate migration file](#use-views-with-prisma-migrate-and-db-push), or use an existing view +1. [Represent the view in your Prisma schema](#add-views-to-your-prisma-schema) +1. [Query the view in Prisma Client](#query-views-in-prisma-client) :::warning Support for views is currently a [Preview](/orm/more/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). - ::: ## Enable the `views` preview feature @@ -37,11 +36,11 @@ generator client { } ``` -Please leave feedback about this preview feature in our dedicated [preview feature feedback issue for `views`](https://github.com/prisma/prisma/issues/17335). +Please leave feedback about this preview feature in our dedicated preview feature [feedback issue](https://github.com/prisma/prisma/issues/17335) for `views`. ## Create a view in the underlying database -Currently, you cannot apply views that you define in your Prisma schema to your database with Prisma Migrate and `db push`. Instead, you must first create the view in the underlying database, either manually or [as part of a migration](#use-views-with-prisma-migrate-and-db-push). +Currently, you cannot apply views that you define in your Prisma schema to your database with Prisma Migrate or `db push`. Instead, you must first create the view in the underlying database, either manually or [as part of a migration](#use-views-with-prisma-migrate-and-db-push). For example, take the following Prisma schema with a `User` model and a related `Profile` model: @@ -293,7 +292,7 @@ const userinfo = await prisma.userInfo.findMany({ :::note -`findUnique`, cursor-based pagination, and writes (create/update/delete) are not supported on `views`. +Write queries (create/update/delete) are not supported on `views`. ::: @@ -320,24 +319,27 @@ Currently, Prisma ORM does not support materialized views. However, when you [ma In the future Prisma Client might support marking individual views as materialized and add a Prisma Client method to refresh the materialized view. Please comment on our [`views` feedback issue](https://github.com/prisma/prisma/issues/17335) with your use case. -Here's a **revised `## Restrictions` section** with **clarity on *why*** these limitations exist: - ## Restrictions -Prisma ORM treats all `view` blocks as **read-only representations of database queries** rather than true tables. Because of this, several restrictions apply to ensure Prisma Client remains consistent with the behavior of the underlying database: +Prisma ORM treats all `view` blocks as _read-only_ representations of database queries rather than true tables. Because of this, several restrictions apply to ensure Prisma Client remains consistent with the behavior of the underlying database: + +### No identifiers + +Views are virtual tables and do not have inherent primary keys. Hence, you cannot define `@id`, `@@id` attributes on a `view` block. + +### No indexes -### No identifiers or constraints +Because views are virtual tables, they also can't have indexes. Therefore, , `@index` and `@@index` are disallowed to be define don `view` blocks. -Views are virtual tables and do not have inherent primary keys or unique constraints. Adding artificial constraints would create invalid assumptions for Prisma Client and break queries like `findUnique`. Hence, you cannot define `@id`, `@unique`, `@@id`, `@@unique`, or `@index` attributes on a `view` block. +### Unsafe `@unique` attributes -### No relationships +While Prisma ORM does allow you to define `@unique` and `@@unique` attributes on views, the correctness of these unique contraints actually isn't enforced. This means that if you define a `@unique` attribute on a field on a view, there may be multiple records with the same values for that field in the underlying database. -Relationships in Prisma rely on foreign keys and referential integrity, which views do not enforce. Defining relationships on a view could mislead developers into thinking data integrity is guaranteed. Hence, the `@relation` attributes are not supported for views. +Neither the database nor Prisma ORM enforces the unique constraint expressed by that attributre. The purpose of the `@unique` attribute in this case is only to enable relationships across views as well as `findUnique` queries and cursor-based pagination in Prisma Client. ### Limited Prisma Client API Views do not store data themselves, so writes and operations requiring unique identifiers cannot be supported. Also: - Only `findMany` (with filters, ordering, and skip/take pagination) is available. -- `findUnique`, cursor-based pagination, and aggregate queries that depend on unique identifiers are **not supported**. - All write operations (`create`, `update`, `delete`, `upsert`) are disabled and not generated in the Prisma Client. \ No newline at end of file From 6547b29264e5b7505e5faaa030e0ea867b760609 Mon Sep 17 00:00:00 2001 From: Nikolas Date: Thu, 7 Aug 2025 15:52:25 +0200 Subject: [PATCH 2/6] Update content/200-orm/100-prisma-schema/20-data-model/40-views.mdx Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- content/200-orm/100-prisma-schema/20-data-model/40-views.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 fa0d85140c..dc5d8c183e 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 @@ -329,7 +329,7 @@ Views are virtual tables and do not have inherent primary keys. Hence, you canno ### No indexes -Because views are virtual tables, they also can't have indexes. Therefore, , `@index` and `@@index` are disallowed to be define don `view` blocks. +Because views are virtual tables, they cannot have indexes. Therefore, `@index` and `@@index` cannot be defined on `view` blocks. ### Unsafe `@unique` attributes From 07b270a2eaaf1d8b6f681d576a029dc36a6c3695 Mon Sep 17 00:00:00 2001 From: Nikolas Burk Date: Thu, 7 Aug 2025 15:54:24 +0200 Subject: [PATCH 3/6] add improvements --- .../200-orm/100-prisma-schema/20-data-model/40-views.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) 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 fa0d85140c..5d5b45b7b5 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 @@ -333,9 +333,11 @@ Because views are virtual tables, they also can't have indexes. Therefore, , `@i ### Unsafe `@unique` attributes -While Prisma ORM does allow you to define `@unique` and `@@unique` attributes on views, the correctness of these unique contraints actually isn't enforced. This means that if you define a `@unique` attribute on a field on a view, there may be multiple records with the same values for that field in the underlying database. +While Prisma ORM lets you place `@unique` and `@@unique` attributes on views, the underlying database and Prisma do not enforce those constraints. Multiple rows can therefore share the same value for a supposedly unique field. -Neither the database nor Prisma ORM enforces the unique constraint expressed by that attributre. The purpose of the `@unique` attribute in this case is only to enable relationships across views as well as `findUnique` queries and cursor-based pagination in Prisma Client. +Neither the database nor Prisma ORM enforce the unique constraint expressed by that attribute. + +The purpose of the `@unique` attribute in this case is only to enable relationships across views as well as `findUnique` queries and cursor-based pagination in Prisma Client. ### Limited Prisma Client API From d971a7565644744ea6ca199b7330f1e1b47d3422 Mon Sep 17 00:00:00 2001 From: Nikolas Burk Date: Thu, 7 Aug 2025 15:59:03 +0200 Subject: [PATCH 4/6] minor improvements --- .../100-prisma-schema/20-data-model/40-views.mdx | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) 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 94942fd7b3..85d60c3230 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 @@ -222,9 +222,10 @@ Each _field_ of a `view` block represents a column in the query results of the v ### Use introspection - - Currently only available for PostgreSQL, MySQL, SQL Server and CockroachDB. - +:::warning +Currently views can only be introspected with PostgreSQL, MySQL, SQL Server and CockroachDB databases. If you are using another database provider, your views must be added manually. +::: + If you have an existing view or views defined in your database, [introspection](/orm/prisma-schema/introspection) will automatically generate `view` blocks in your Prisma schema that represent those views. @@ -270,14 +271,6 @@ FROM ); ``` -### Limitations - -#### Introspection - -Currently, introspection of views is only available for PostgreSQL, MySQL, SQL Server and CockroachDB. If you are using another database provider, your views must be added manually. - -This is a temporary limitation and support for introspection will be extended to the other supported datasource providers. - ## Query views in Prisma Client You can query views in Prisma Client in the same way that you query models. For example, the following query finds all users with a `name` of `'Alice'` in the `UserInfo` view defined above. From 95620a835b671aa700d04d5aee158b176830e1be Mon Sep 17 00:00:00 2001 From: Nikolas Burk Date: Thu, 7 Aug 2025 16:10:16 +0200 Subject: [PATCH 5/6] minor improvements in view docs --- .../200-orm/100-prisma-schema/20-data-model/40-views.mdx | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) 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 85d60c3230..45d502555a 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 @@ -247,9 +247,7 @@ view UserInfo { ``` :::warning - Please note for now `db pull` will only introspect views in your schema when using PostgreSQL, MySQL, SQL Server or CockroachDB. Support for this workflow will be extended to other database providers. - ::: #### The `views` directory @@ -332,9 +330,6 @@ Neither the database nor Prisma ORM enforce the unique constraint expressed by t The purpose of the `@unique` attribute in this case is only to enable relationships across views as well as `findUnique` queries and cursor-based pagination in Prisma Client. -### Limited Prisma Client API - -Views do not store data themselves, so writes and operations requiring unique identifiers cannot be supported. Also: +### Disabled write queries -- Only `findMany` (with filters, ordering, and skip/take pagination) is available. -- All write operations (`create`, `update`, `delete`, `upsert`) are disabled and not generated in the Prisma Client. \ No newline at end of file +All write operations (`create`, `update`, `delete`, `upsert`) are disabled and not generated in the Prisma Client. \ No newline at end of file From bf51ce625e52b806ba341aaef7d777d8b795f7fb Mon Sep 17 00:00:00 2001 From: Nikolas Burk Date: Tue, 12 Aug 2025 11:51:04 +0200 Subject: [PATCH 6/6] polished view docs --- .../100-prisma-schema/20-data-model/40-views.mdx | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) 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 45d502555a..ab3467c8dd 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 @@ -271,6 +271,12 @@ FROM ## Query views in Prisma Client +:::note + +Be sure to run `prisma generate` after updating your Prisma schema so that the `view` definitions become part of your Prisma Client API. + +::: + You can query views in Prisma Client in the same way that you query models. For example, the following query finds all users with a `name` of `'Alice'` in the `UserInfo` view defined above. ```ts @@ -283,7 +289,7 @@ const userinfo = await prisma.userInfo.findMany({ :::note -Write queries (create/update/delete) are not supported on `views`. +Write-queries (create/update/delete) are not supported on `views`. ::: @@ -294,7 +300,7 @@ This section describes how to use Prisma ORM with updatable and materialized vie ### Updatable views -Some databases support *updatable views* (e.g. [PostgreSQL](https://www.postgresql.org/docs/current/sql-createview.html#SQL-CREATEVIEW-UPDATABLE-VIEWS), [MySQL](https://dev.mysql.com/doc/refman/8.0/en/view-updatability.html), and [SQL Server](https://learn.microsoft.com/en-us/sql/t-sql/statements/create-view-transact-sql?view=sql-server-ver16#updatable-views)). Updatable views allow creating, updating, or deleting entries if the underlying database supports such operations. +Some databases support _updatable views_ (e.g. [PostgreSQL](https://www.postgresql.org/docs/current/sql-createview.html#SQL-CREATEVIEW-UPDATABLE-VIEWS), [MySQL](https://dev.mysql.com/doc/refman/8.0/en/view-updatability.html), and [SQL Server](https://learn.microsoft.com/en-us/sql/t-sql/statements/create-view-transact-sql?view=sql-server-ver16#updatable-views)). Updatable views allow creating, updating, or deleting entries if the underlying database supports such operations. Prisma ORM does not allow any mutations (create, update, delete) on views, regardless of the database's capabilities. This change provides guardrails to ensure that views are treated consistently as read-only entities within Prisma Client. As a result, methods to perform writes such as `create`, `update`, `delete`, or `upsert` are not generated for `view` blocks in your Prisma Client API. @@ -310,9 +316,9 @@ Currently, Prisma ORM does not support materialized views. However, when you [ma In the future Prisma Client might support marking individual views as materialized and add a Prisma Client method to refresh the materialized view. Please comment on our [`views` feedback issue](https://github.com/prisma/prisma/issues/17335) with your use case. -## Restrictions +## Limitations -Prisma ORM treats all `view` blocks as _read-only_ representations of database queries rather than true tables. Because of this, several restrictions apply to ensure Prisma Client remains consistent with the behavior of the underlying database: +Prisma ORM treats all `view` blocks as _read-only_ representations of database queries rather than true tables. Because of this, several limitations apply to ensure Prisma Client remains consistent with the behavior of the underlying database. ### No identifiers