PlanetScale foreign key constraint errors (no FK support) in CI

By Daniel Zoghalchali·Latchkey

PlanetScale runs on Vitess, which historically did not support foreign key constraints. A migration generated for plain MySQL that adds FK constraints fails in CI unless the database has FK support enabled or the constraints are omitted.

What this error means

A migration against a PlanetScale branch fails with "foreign key constraints are not supported" or a create-table error naming a REFERENCES clause, while the same migration passes on local MySQL.

Error 1235 (42000): VT12020: unsupported: foreign keys are not supported
when applying: ALTER TABLE orders ADD CONSTRAINT fk_user FOREIGN KEY ...

Common causes

FK constraints emitted for a Vitess database

The ORM or migration tool generated REFERENCES clauses that Vitess rejects unless foreign key support is turned on for the database.

A migration copied from a plain MySQL project

Schema authored for standard MySQL carries FK constraints that do not translate to the default PlanetScale configuration.

How to fix it

Enable foreign key support or drop the constraints

1. If your PlanetScale database supports it, enable foreign key constraints for the database.
2. Otherwise configure the ORM to not emit database-level FK constraints.
3. Enforce referential integrity in application code where FKs are unavailable.

// Prisma: relationMode moves FK enforcement to the app
datasource db {
  provider     = "mysql"
  relationMode = "prisma"
}

Generate MySQL DDL without FK constraints

Configure your migration tool to skip emitting REFERENCES so the branch schema applies cleanly.

How to prevent it

• Set the ORM to enforce relations in the app when FKs are unavailable.
• Keep PlanetScale-targeted migrations free of unsupported FK DDL.
• Run migrations against a PlanetScale branch in CI to catch FK issues early.

Frequently asked questions

Related guides

References

• GitHub Actions documentation