Prisma P3021: Foreign keys cannot be created on this database (PlanetScale)

By Ohad Krispin, founder of VibeRaven · LinkedIn

"Foreign keys cannot be created on this database" is Prisma error P3021. Prisma tried to create foreign key constraints on a PlanetScale (Vitess) database that has them turned off, which is the default, and MySQL answered with error 1317. There are two fixes. Either set relationMode = "prisma" in the datasource block so Prisma Client emulates relations, and add an @@index on every relation scalar field, or tick Allow foreign key constraints in the database settings in PlanetScale. Prisma recommends prisma db push on a development branch for schema changes, not prisma migrate, and PlanetScale's Prisma tutorial uses it.

Which relationMode do I set for PlanetScale?

The default relationMode is foreignKeys, where the database enforces relations with constraints, so Prisma sends foreign key DDL. With relationMode = "prisma" it creates no constraints, and Prisma Client does the referential checks. Prisma's PlanetScale page lists this as option 1. The field was called referentialIntegrity before Prisma 4.5.0. One Prisma relation mode page still says PlanetScale does not support foreign keys; PlanetScale's own docs and Prisma's PlanetScale page say they do, as an opt-in per database.

datasource db {
  provider     = "mysql"
  url          = env("DATABASE_URL")
  relationMode = "prisma"
}

Why does prisma validate warn about indexes?

Without foreign keys the database creates no index on the relation column, so Prisma asks you to add one. In a run of prisma 6.19.3 on 2026-10-31, a schema with relationMode = "prisma" and a Comment.postId relation printed the warning below, and adding @@index([postId]) to the model removed it. Prisma's PlanetScale page says a missing index can leave queries poorly optimized.

Prisma schema warning:
- With relationMode = "prisma", no foreign keys are used, so relation fields will not benefit from the index usually created by the relational database under the hood. This can lead to poor performance when querying these fields. We recommend adding an index manually.

model Comment {
  id     Int  @id @default(autoincrement())
  postId Int
  post   Post @relation(fields: [postId], references: [id])

  @@index([postId])
}

How do I turn foreign keys on in PlanetScale instead?

Open the database's Settings tab, check Allow foreign key constraints under General, and save. PlanetScale says support is per database, currently only for unsharded databases, and that you cannot have open deploy requests when you enable it. It also says deploy requests do not validate existing rows, so adding a foreign key to a table with orphaned rows succeeds and the orphans stay. With the setting on, Prisma's page says you can define relations as on any database that supports foreign keys.

Checklist

How to fix it, then check the fix

01
Check how the schema is set up. The old name was referentialIntegrity:
```
grep -rnE "relationMode|referentialIntegrity" prisma/
```
02Pick one path. Path A: relationMode = "prisma" in the datasource block. Path B: Allow foreign key constraints in the PlanetScale database settings, after closing open deploy requests.
03
On path A, add an @@index on each relation scalar field, then validate. The index warning should be gone:
```
npx prisma validate
```
04Run the push on a development branch, not on the production branch, with DATABASE_URL pointing at that branch: npx prisma db push. P3021 should not appear. If P3022 appears instead, see the direct DDL page.
05Open a deploy request from the development branch to production and deploy it. Do not run prisma db push in the Vercel build against the production branch.

Sources

Official docs behind this checklist

More PlanetScale errors

Browse all launch guides · Read resources · How to make and check your next change

FAQ

FAQ for builders before launch

Does PlanetScale support foreign keys now?

Yes, as an option per database. PlanetScale's docs say foreign key constraints are supported in unsharded environments, switched on under Settings with Allow foreign key constraints. Prisma's PlanetScale page says they have been generally available since February 2024.

Should I use prisma migrate with PlanetScale?

Prisma recommends prisma db push instead. PlanetScale generates its own schema diff when a branch is merged, so the migration files Prisma writes may not reflect the changes PlanetScale runs.

Does the same error appear with PlanetScale Postgres?

The P3021 check in Prisma's schema engine only runs for databases it detects as Vitess, with MySQL error 1317. PlanetScale's docs describe the foreign key setting for its Vitess databases.