Skip to content

Commit a230c94

Browse files
nikolasburkjanpio
andauthored
add docs for fk constraints in planetscale (#5675)
* add docs for fk constraints in planetscale * update docs for fk constraints in planetscale * fix broken links * Update content/200-orm/050-overview/500-databases/850-planetscale.mdx Co-authored-by: Jan Piotrowski <[email protected]> * add more context about using fk constraints in planetscale * add more context about using fk constraints in planetscale * add more context about using fk constraints in planetscale * add more context about using fk constraints in planetscale * add more context about using fk constraints in planetscale * add more context about using fk constraints in planetscale * Update content/200-orm/050-overview/500-databases/850-planetscale.mdx * revert package-lock.json * Update content/200-orm/050-overview/500-databases/850-planetscale.mdx Co-authored-by: Jan Piotrowski <[email protected]> * Update content/200-orm/050-overview/500-databases/850-planetscale.mdx Co-authored-by: Jan Piotrowski <[email protected]> * Update content/200-orm/050-overview/500-databases/850-planetscale.mdx Co-authored-by: Jan Piotrowski <[email protected]> * update docs for fk constraints in planetscale --------- Co-authored-by: Jan Piotrowski <[email protected]>
1 parent fac458f commit a230c94

File tree

6 files changed

+60
-20
lines changed

6 files changed

+60
-20
lines changed

content/100-getting-started/02-setup-prisma/100-start-from-scratch/110-relational-databases/100-connect-your-database.mdx

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@ datasource db {
142142
}
143143
```
144144

145-
You will also need to [set the relation mode type to `prisma`](/orm/prisma-schema/data-model/relations/relation-mode#emulate-relations-in-prisma-orm-with-the-prisma-relation-mode) in the `datasource` block:
145+
You will also need to set the relation mode type to `prisma` in order to [emulate foreign key constraints](/orm/overview/databases/planetscale#option-1-emulate-relations-in-prisma-client) in the `datasource` block:
146146

147147
```prisma file=schema.prisma highlight=4;add
148148
datasource db {
@@ -152,6 +152,8 @@ datasource db {
152152
}
153153
```
154154

155+
> **Note**: Since February 2024, you can alternatively [use foreign key constraints on a database-level in PlanetScale](/orm/overview/databases/planetscale#option-2-enable-foreign-key-constraints-in-the-planetscale-settings), which omits the need for setting `relationMode = "prisma"`.
156+
155157
The `url` is [set via an environment variable](/orm/prisma-schema/overview#accessing-environment-variables-from-the-schema) which is defined in `.env`:
156158

157159
```bash file=.env

content/100-getting-started/02-setup-prisma/200-add-to-existing-project/110-relational-databases/100-connect-your-database.mdx

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,7 @@ datasource db {
127127
}
128128
```
129129

130-
You will also need to [set the relation mode type to `prisma`](/orm/prisma-schema/data-model/relations/relation-mode#emulate-relations-in-prisma-orm-with-the-prisma-relation-mode) in the `datasource` block:
130+
You will also need to set the relation mode type to `prisma` in order to [emulate foreign key constraints](/orm/overview/databases/planetscale#option-1-emulate-relations-in-prisma-client) in the `datasource` block:
131131

132132
```prisma file=schema.prisma highlight=4;add
133133
datasource db {
@@ -137,6 +137,8 @@ datasource db {
137137
}
138138
```
139139

140+
> **Note**: Since February 2024, you can alternatively [use foreign key constraints on a database-level in PlanetScale](/orm/overview/databases/planetscale#option-2-enable-foreign-key-constraints-in-the-planetscale-settings), which omits the need for setting `relationMode = "prisma"`.
141+
140142
The `url` is [set via an environment variable](/orm/prisma-schema/overview#accessing-environment-variables-from-the-schema) which is defined in `.env`:
141143

142144
```bash file=.env

content/200-orm/050-overview/500-databases/850-planetscale.mdx

Lines changed: 49 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -37,12 +37,8 @@ Many aspects of using Prisma ORM with PlanetScale are just like using Prisma ORM
3737
PlanetScale's branching model and design for scalability means that there are also a number of differences to consider. You should be aware of the following points when deciding to use PlanetScale with Prisma ORM:
3838

3939
- **Branching and deploy requests.** PlanetScale provides two types of database branches: _development branches_, which allow you to test out schema changes, and _production branches_, which are protected from direct schema changes. Instead, changes must be first created on a development branch and then deployed to production using a deploy request. Production branches are highly available and include automated daily backups. To learn more, see [How to use branches and deploy requests](#how-to-use-branches-and-deploy-requests).
40-
41-
- **Referential actions and integrity.** To support scaling across multiple database servers, PlanetScale [does not allow the use of foreign key constraints](https://planetscale.com/docs/learn/operating-without-foreign-key-constraints), which are normally used in relational databases to enforce relationships between data in different tables, and asks users to handle this manually in their applications.
42-
With Prisma ORM you can maintain these relationships in your data and allow the use of [referential actions](/orm/prisma-schema/data-model/relations/referential-actions) by using Prisma ORM's ability to [emulate relations in Prisma Client](/orm/prisma-schema/data-model/relations/relation-mode#emulate-relations-in-prisma-orm-with-the-prisma-relation-mode) with the `prisma` relation mode. For more information, see [How to emulate relations in Prisma Client](#how-to-emulate-relations-in-prisma-client).
43-
44-
- **Creating indexes on foreign keys.** When emulating relations in Prisma ORM, you will need to create indexes on foreign keys. In a standard MySQL database, if a table has a column with a foreign key constraint, an index is automatically created on that column. Because PlanetScale does not support foreign keys, these indexes are [currently](https://github.com/prisma/prisma/issues/10611) not created when Prisma Client emulates relations, which can lead to issues with queries not being well optimised. To avoid this, you can create indexes in Prisma ORM. For more information, see [How to create indexes on foreign keys](#how-to-create-indexes-on-foreign-keys).
45-
40+
- **Referential actions and integrity.** To support scaling across multiple database servers, PlanetScale [by default does not use foreign key constraints](https://planetscale.com/docs/learn/operating-without-foreign-key-constraints), which are normally used in relational databases to enforce relationships between data in different tables, and asks users to handle this manually in their applications. However, you can explicitly [enable them in the PlanetScale database settings](https://planetscale.com/docs/concepts/foreign-key-constraints). If you don't enable these explicitly, you can still maintain these relationships in your data and allow the use of [referential actions](/orm/prisma-schema/data-model/relations/referential-actions) by using Prisma ORM's ability to [emulate relations in Prisma Client](/orm/prisma-schema/data-model/relations/relation-mode#emulate-relations-in-prisma-orm-with-the-prisma-relation-mode) with the `prisma` relation mode. For more information, see [How to emulate relations in Prisma Client](#option-1-emulate-relations-in-prisma-client).
41+
- **Creating indexes on foreign keys.** When [emulating relations in Prisma ORM](#option-1-emulate-relations-in-prisma-client) (i.e. when _not_ using foreign key constraints on the database-level), you will need to create dedicated indexes on foreign keys. In a standard MySQL database, if a table has a column with a foreign key constraint, an index is automatically created on that column. When PlanetScale is configured to not use foreign key constraints, these indexes are [currently](https://github.com/prisma/prisma/issues/10611) not created when Prisma Client emulates relations, which can lead to issues with queries not being well optimised. To avoid this, you can create indexes in Prisma ORM. For more information, see [How to create indexes on foreign keys](#2-create-indexes-on-foreign-keys).
4642
- **Making schema changes with `db push`.** When you merge a development branch into your production branch, PlanetScale will automatically compare the two schemas and generate its own schema diff. This means that Prisma ORM's [`prisma migrate`](/orm/prisma-migrate) workflow, which generates its own history of migration files, is not a natural fit when working with PlanetScale. These migration files may not reflect the actual schema changes run by PlanetScale when the branch is merged.
4743

4844
<Admonition type="warning">
@@ -53,7 +49,7 @@ PlanetScale's branching model and design for scalability means that there are al
5349

5450
For an example of how this works, see [How to make schema changes with `db push`](#how-to-make-schema-changes-with-db-push)
5551

56-
- **Introspection**. When you introspect on an existing database, you will get a schema with no relations, as they are usually defined based on foreign keys that connect tables. Because PlanetScale does not support foreign keys, and you use Prisma ORM to emulate relations, you will need to add the missing relations in manually. For more information, see [How to add in missing relations after Introspection](#how-to-add-in-missing-relations-after-introspection).
52+
- **Introspection**. When you introspect on an existing database and you have _not_ enabled [foreign key constraints in your PlanetScale database](#option-2-enable-foreign-key-constraints-in-the-planetscale-database-settings), you will get a schema with no relations, as they are usually defined based on foreign keys that connect tables. In that case, you will need to add the missing relations in manually. For more information, see [How to add in missing relations after Introspection](#how-to-add-in-missing-relations-after-introspection).
5753

5854
## How to use branches and deploy requests
5955

@@ -63,9 +59,15 @@ Every PlanetScale database is created with a branch called `main`, which is init
6359

6460
If you try to push to a production branch, you will get the [error message](/orm/reference/error-reference#p3022) `Direct execution of DDL (Data Definition Language) SQL statements is disabled on this database.`
6561

66-
## How to emulate relations in Prisma Client
62+
## How to use relations (and enable referential integrity) with PlanetScale
63+
64+
### Option 1: Emulate relations in Prisma Client
6765

68-
PlanetScale does not allow foreign keys in its database schema. By default, Prisma ORM uses foreign keys in the underlying database to enforce relations between fields 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 keys in the database.
66+
#### 1. Set `relationMode = "prisma"`
67+
68+
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.
69+
70+
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.
6971

7072
To enable emulation of relations in Prisma Client, set the `relationMode` field to `"prisma"` in the `datasource` block:
7173

@@ -83,11 +85,11 @@ The ability to set the relation mode was introduced as part of the `referentialI
8385

8486
</Admonition>
8587

86-
If you use relations in your Prisma schema with the default `"foreignKeys"` option for the `referentialIntegrity` field, PlanetScale will error when Prisma ORM tries to create foreign keys. In versions 2.27.0 and later, Prisma ORM will output the [P3021 error message](/orm/reference/error-reference#p3021).
88+
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.)
8789

88-
## How to create indexes on foreign keys
90+
#### 2. Create indexes on foreign keys
8991

90-
When [you emulate relations in Prisma Client](#how-to-emulate-relations-in-prisma-client), you need to create your own indexes. As an example of a situation where you would want to add an index, take this schema for a blog with posts and comments:
92+
When [you emulate relations in Prisma Client](#option-1-emulate-relations-in-prisma-client), you need to create your own indexes. As an example of a situation where you would want to add an index, take this schema for a blog with posts and comments:
9193

9294
```prisma file=schema.prisma
9395
model Post {
@@ -139,9 +141,41 @@ One issue to be aware of is that [implicit many-to-many relations](/orm/prisma-s
139141

140142
</Admonition>
141143

144+
### Option 2: Enable foreign key constraints in the PlanetScale database settings
145+
146+
Support for foreign key constraints in PlanetScale databases has been Generally Available since February 2024. Follow the instructions in the [PlanetScale documentation](https://planetscale.com/docs/concepts/foreign-key-constraints) to enable them in your database.
147+
148+
You can then use Prisma ORM and define relations in your Prisma schema without the need for extra configuration.
149+
150+
In that case, you can define a relation as with other database that supports foreign key constraints, for example:
151+
152+
```prisma file=schema.prisma
153+
model Post {
154+
id Int @id @default(autoincrement())
155+
title String
156+
content String
157+
likes Int @default(0)
158+
comments Comment[]
159+
}
160+
161+
model Comment {
162+
id Int @id @default(autoincrement())
163+
comment String
164+
postId Int
165+
post Post @relation(fields: [postId], references: [id], onDelete: Cascade)
166+
}
167+
```
168+
169+
With this approach, it is _not_ necessary to:
170+
171+
- set `relationMode = "prisma"` in your Prisma schema
172+
- define additional indexes on foreign keys
173+
174+
Also, introspection will automatically create relation fields in your Prisma schema because it can detect the foreign key constraints in the database.
175+
142176
## How to make schema changes with <inlinecode>db push</inlinecode>
143177

144-
To use `db push` with PlanetScale, you will first need to [enable emulation of relations in Prisma Client](#how-to-emulate-relations-in-prisma-client). Pushing to your branch without referential emulation enabled will give the [error message](/orm/reference/error-reference#p3021) `Foreign keys cannot be created on this database.`
178+
To use `db push` with PlanetScale, you will first need to [enable emulation of relations in Prisma Client](#option-1-emulate-relations-in-prisma-client). Pushing to your branch without referential emulation enabled will give the [error message](/orm/reference/error-reference#p3021) `Foreign keys cannot be created on this database.`
145179

146180
As an example, let's say you decide to decide to add a new `excerpt` field to the blog post schema above. You will first need to [create a new development branch and connect to it](#how-to-use-branches-and-deploy-requests).
147181

@@ -179,6 +213,8 @@ For more examples, see PlanetScale's tutorial on [automatic migrations with Pris
179213

180214
## How to add in missing relations after Introspection
181215

216+
> **Note**: This section is only relevant if you use `relationMode = "prisma"` to emulate foreign key constraints with Prisma ORM. If you enabled foreign key constraints in your PlanetScale database, you can ignore this section.
217+
182218
After introspecting with `npx prisma db pull`, the schema you get may be missing some relations. For example, the following schema is missing a relation between the `User` and `Post` models:
183219

184220
```prisma file=schema.prisma

content/200-orm/100-prisma-schema/20-data-model/20-relations/420-relation-mode.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@ The ability to set the relation mode was introduced as part of the `referentialI
9292
For relational databases, the available options are:
9393

9494
- `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.
95-
- `prisma`: this emulates relations in Prisma Client. You should also [enable this option](/orm/overview/databases/planetscale#how-to-emulate-relations-in-prisma-client) when you use the MySQL connector with a PlanetScale database.
95+
- `prisma`: this emulates relations in Prisma Client. You should also [enable this option](/orm/overview/databases/planetscale#option-1-emulate-relations-in-prisma-client) when you use the MySQL connector with a PlanetScale database and don't have native foreign key constraints enabled in your PlanetScale database settings.
9696

9797
For MongoDB, the only available option is the `prisma` relation mode. This mode is also active if no `relationMode` is explicitly set in the `datasource` block.
9898

@@ -106,7 +106,7 @@ If you switch between relation modes, Prisma ORM will add or remove foreign keys
106106

107107
The `foreignKeys` relation mode handles relations in your relational database with foreign keys. This is the default option when you use a relational database connector (PostgreSQL, MySQL, SQLite, SQL Server, CockroachDB).
108108

109-
The `foreignKeys` relation mode is not available when you use the MongoDB connector. Some relational databases, [such as PlanetScale](/orm/overview/databases/planetscale#how-to-emulate-relations-in-prisma-client), also forbid the use of foreign keys. In these cases, you should instead [emulate relations in Prisma ORM with the `prisma` relation mode](#emulate-relations-in-prisma-orm-with-the-prisma-relation-mode).
109+
The `foreignKeys` relation mode is not available when you use the MongoDB connector. Some relational databases, [such as PlanetScale](/orm/overview/databases/planetscale#option-1-emulate-relations-in-prisma-client), also forbid the use of foreign keys. In these cases, you should instead [emulate relations in Prisma ORM with the `prisma` relation mode](#emulate-relations-in-prisma-orm-with-the-prisma-relation-mode).
110110

111111
### Referential integrity
112112

@@ -134,7 +134,7 @@ When you apply changes to your Prisma schema with Prisma Migrate or `db push` wi
134134

135135
The `prisma` relation mode emulates some foreign key constraints and referential actions for each Prisma Client query to maintain referential integrity, using some additional database queries and logic.
136136

137-
The `prisma` relation mode is the default option for the MongoDB connector. It should also be set if you use a relational database that does not support foreign keys. For example, [if you use PlanetScale](/orm/overview/databases/planetscale#how-to-emulate-relations-in-prisma-client) you should use the `prisma` relation mode.
137+
The `prisma` relation mode is the default option for the MongoDB connector. It should also be set if you use a relational database that does not support foreign keys. For example, [if you use PlanetScale](/orm/overview/databases/planetscale#option-1-emulate-relations-in-prisma-client) without foreign key constraints, you should use the `prisma` relation mode.
138138

139139
<Admonition type="warning">
140140
There are performance implications to emulation of referential integrity in

content/200-orm/200-prisma-client/000-setup-and-configuration/015-instantiate-prisma-client.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ const prisma = new PrismaClient()
3535

3636
<Tip>
3737

38-
You can further customize `PrismaClient` with [constructor parameters](/orm/reference/prisma-client-reference#prismaclient) — for example, set [logging levels](/orm/prisma-client/observability-and-logging/logging), [transaction options](/orm/prisma-client/queries/transactions#transactions-options) or customize [error formatting](error-formatting).
38+
You can further customize `PrismaClient` with [constructor parameters](/orm/reference/prisma-client-reference#prismaclient) — for example, set [logging levels](/orm/prisma-client/observability-and-logging/logging), [transaction options](/orm/prisma-client/queries/transactions#transaction-options) or customize [error formatting](error-formatting).
3939

4040
</Tip>
4141

content/500-platform/60-platform-cli/20-commands.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ This document describes the Prisma Data Platform's integrated Prisma CLI command
1212

1313
## Getting started
1414

15-
To get started, ensure you have the [Prisma CLI](https://www.prisma.io/docs/orm/tools/prisma-cli#installation) updated to version `5.10.0` or later. This is necessary to access the Platform through the Prisma CLI.
15+
To get started, ensure you have the [Prisma CLI](/orm/tools/prisma-cli) updated to version `5.10.0` or later. This is necessary to access the Platform through the Prisma CLI.
1616

1717
<Admonition>
1818

0 commit comments

Comments
 (0)