Skip to main content

Documentation Index

Fetch the complete documentation index at: https://planetscale.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
What this error means

FOREIGN_KEYS_CIRCULAR_DEPENDENCY means foreign key relationships form a cycle. This can be a self-referencing table or a group of tables that reference each other in a loop.

​
Why PlanetScale rejects it

Foreign key cycles can make schema dependency ordering ambiguous. They can also produce unsupported cascaded behavior, especially when all participating constraints use CASCADE or SET NULL actions.

​
How to fix it

Break the cycle where possible:
  • Remove one database-enforced foreign key constraint and enforce that relationship in application code.
  • Replace cascading actions with explicit application workflows.
  • Split schema changes so parent tables and child constraints are introduced in a predictable order.
  • For self-references, check whether the constraint is necessary or whether application validation is enough.
Example cycle: 
CREATE TABLE teams (
  id bigint unsigned NOT NULL,
  owner_user_id bigint unsigned NOT NULL,
  PRIMARY KEY (id),
  CONSTRAINT teams_owner_fk FOREIGN KEY (owner_user_id) REFERENCES users(id)
);

CREATE TABLE users (
  id bigint unsigned NOT NULL,
  team_id bigint unsigned NOT NULL,
  PRIMARY KEY (id),
  CONSTRAINT users_team_fk FOREIGN KEY (team_id) REFERENCES teams(id)
);
One common fix is to remove one constraint and keep an index for the relationship: 
CREATE TABLE users (
  id bigint unsigned NOT NULL,
  team_id bigint unsigned NOT NULL,
  PRIMARY KEY (id),
  KEY users_team_idx (team_id)
);

​
Need help?

Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.