Skip to content

add docs for 6.14.0 #7063

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 25 additions & 33 deletions content/200-orm/100-prisma-schema/20-data-model/40-views.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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. <br /><br />For updates on progress with this feature, follow [our GitHub issue](https://github.com/prisma/prisma/issues/17335).


:::

## Enable the `views` preview feature
Expand All @@ -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:

Expand Down Expand Up @@ -223,9 +222,10 @@ Each _field_ of a `view` block represents a column in the query results of the v

### Use introspection

<Admonition type="warning">
Currently only available for PostgreSQL, MySQL, SQL Server and CockroachDB.
</Admonition>
:::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.

Expand All @@ -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
Expand All @@ -271,14 +269,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.
Expand All @@ -293,7 +283,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`.

:::

Expand All @@ -320,24 +310,26 @@ 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 cannot have indexes. Therefore, `@index` and `@@index` cannot be defined on `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 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.

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 enforce the unique constraint expressed by that attribute.

### Limited Prisma Client API
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.

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.
- `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.
All write operations (`create`, `update`, `delete`, `upsert`) are disabled and not generated in the Prisma Client.
Loading