Skip to content

Document foreign key constraint naming changes #1049

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dereuromark merged 1 commit into from
Mar 11, 2026
+34 −0
Merged

Document foreign key constraint naming changes #1049

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions docs/en/upgrading.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,40 @@ insertOrSkip() for Seeds
New ``insertOrSkip()`` method for seeds to insert records only if they don't already exist,
making seeds more idempotent.

Foreign Key Constraint Naming
=============================

Starting in 5.x, when you use ``addForeignKey()`` without providing an explicit constraint
name, migrations will auto-generate a name using the pattern ``{table}_{columns}``.

Previously, MySQL would auto-generate constraint names (like ``articles_ibfk_1``), while
PostgreSQL and SQL Server used migrations-generated names. Now all adapters use the same
consistent naming pattern.

**Impact on existing migrations:**

If you have existing migrations that use ``addForeignKey()`` without explicit names, and
later migrations that reference those constraints by name (e.g., in ``dropForeignKey()``),
the generated names may differ between old and new migrations. This could cause
``dropForeignKey()`` to fail if it's looking for a name that doesn't exist.

**Recommendations:**

1. For new migrations, you can rely on auto-generated names or provide explicit names
2. If you have rollback issues with existing migrations, you may need to update them
to use explicit constraint names
3. The auto-generated names include conflict resolution - if ``{table}_{columns}`` already
exists, a counter suffix is added (``_2``, ``_3``, etc.)

**Name length limits:**

Auto-generated names are truncated to respect database limits:

- MySQL: 61 characters (64 - 3 for counter suffix)
- PostgreSQL: 60 characters (63 - 3)
- SQL Server: 125 characters (128 - 3)
- SQLite: No limit

Migration File Compatibility
============================

Expand Down
Loading