How to fix P3021: Foreign keys cannot be created on this database in Prisma

What this error means

The "P3021: Foreign keys cannot be created on this database" error appears when Prisma attempts to create foreign key constraints during migration, but your database provider doesn't support them natively. This is most common with PlanetScale, a MySQL-compatible serverless database that originally didn't allow traditional foreign key constraints at the database level. Prisma ORM offers two ways to handle relations: the default "foreignKeys" mode that uses database-level constraints, and the "prisma" mode that emulates relations at the application level. When you use a database that doesn't support foreign keys, Prisma cannot apply the default mode and throws the P3021 error during migration. Since February 2024, PlanetScale added support for foreign key constraints, so this error is now more commonly encountered with other serverless or restricted database environments.

Typical symptoms

• Migration fails immediately with P3021 error code
• Error occurs when running 'prisma db push' or 'prisma migrate deploy'
• Relation fields in your schema prevent any database changes
• Error message suggests learning more at 'https://pris.ly/d/migrate-no-foreign-keys'
• Database is PlanetScale, SQLite in certain configurations, or other restricted databases
• Works locally but fails in CI/CD or production environments

Common causes

1. Using PlanetScale without enabling foreign key support (before Feb 2024)
2. Default relationMode is 'foreignKeys' but database doesn't support it
3. Database restrictions prevent creating foreign key constraints
4. Using a serverless database provider with built-in limitations
5. Prisma Client version is outdated (before v2.27.0 shows raw error instead of P3021)
6. Schema defines relations but database configuration doesn't allow them

How to fix "P3021: Foreign keys cannot be created on this database"

# Check your DATABASE_URL in .env.local or .env
cat .env.local | grep DATABASE_URL

datasource db {
  provider     = "mysql"           // or "sqlite", "postgresql", etc.
  url          = env("DATABASE_URL")
  relationMode = "prisma"          // Add this line
}

model Post {
  id        Int     @id @default(autoincrement())
  title     String
  content   String
  blogId    Int
  blog      Blog    @relation(fields: [blogId], references: [id], onDelete: Cascade)

  comments  Comment[]

  @@index([blogId])  // Add this index!
}

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

  @@index([postId])  // Add this index!
}

model Blog {
  id    Int     @id @default(autoincrement())
  name  String
  posts Post[]
}

# Option 1: Using db push (recommended for development)
npx prisma db push

# Option 2: Create and run a migration
npx prisma migrate dev --name add_indexes

The following migration(s) have been created and applied:
  ./prisma/migrations/[timestamp]_init/migration.sql

All migrations have been successfully applied to your database.

import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

// Create a blog
const blog = await prisma.blog.create({
  data: { name: 'My Blog' }
});

// Create a post (this will enforce the relation via Prisma)
const post = await prisma.post.create({
  data: {
    title: 'First Post',
    content: 'Hello World',
    blogId: blog.id
  }
});

// Create a comment
const comment = await prisma.comment.create({
  data: {
    text: 'Nice post!',
    postId: post.id
  }
});

console.log('Relations work correctly!');

# Check Prisma version
npm list @prisma/client

# Recommended: Upgrade to latest Prisma if you're below v3.0
npm install @prisma/client@latest @prisma/cli@latest

# Regenerate Prisma Client
npx prisma generate

Advanced notes

// Safe: Prisma infers types
const post = await prisma.post.create({
  data: { title, content, blogId }
});

// Prisma will throw if blogId doesn't exist when using cascade

// Temporarily remove to test migration
// @relation(fields: [...], references: [...])

Frequently asked questions

What does "P3021: Foreign keys cannot be created on this database" mean?

The "P3021: Foreign keys cannot be created on this database" error appears when Prisma attempts to create foreign key constraints during migration, but your database provider doesn't support them natively. This is most common with PlanetScale, a MySQL-compatible serverless database that originally didn't allow traditional foreign key constraints at the database level. Prisma ORM offers two ways to handle relations: the default "foreignKeys" mode that uses database-level constraints, and the "prisma" mode that emulates relations at the application level.

How do I fix "P3021: Foreign keys cannot be created on this database"?

This error occurs when Prisma tries to create foreign key constraints in your schema but the database doesn't support them (like PlanetScale). Resolve it by switching to emulated relations mode or enabling foreign key support in your database.

What causes "P3021: Foreign keys cannot be created on this database"?

Using PlanetScale without enabling foreign key support (before Feb 2024) Default relationMode is 'foreignKeys' but database doesn't support it Database restrictions prevent creating foreign key constraints

Is the "P3021: Foreign keys cannot be created on this database" error serious?

Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Related errors

• P3022: Direct execution of DDL (Data Definition Language) SQL statements is disabled on this database.

  Direct execution of DDL statements is disabled

  MEDIUM

• P3020: The automatic creation of shadow databases is disabled on Azure SQL

  How to fix "P3020: Shadow database creation disabled" in Prisma

  HIGH

• P4000: Introspection operation failed to produce a schema file

  How to fix "P4000: Introspection operation failed to produce a schema file" in Prisma

  MEDIUM

• P3019: The datasource provider specified in your schema does not match the one specified in the migration_lock.toml

  Datasource provider in schema does not match migration_lock.toml

  HIGH

• P1002: The database server was reached but timed out

  Database server was reached but timed out

  HIGH

• P1013: The provided database string is invalid

  The provided database string is invalid

  HIGH

Official resources & further reading

• 📚Prisma Official Documentation
• 📖
  Prisma Docs: Manage relations between records with relation modes(Official Docs)
• 📖
  Prisma Docs: PlanetScale(Official Docs)
• 📖
  Prisma Docs: Error Reference(Official Docs)
• 📖
  Prisma Docs: Foreign keys(Official Docs)
• 📖
  Prisma Docs: Referential actions(Official Docs)