{"id":3463,"date":"2025-04-24T08:30:00","date_gmt":"2025-04-24T08:30:00","guid":{"rendered":"https:\/\/kedar.nitty-witty.com\/blog\/?p=3463"},"modified":"2025-04-24T08:21:43","modified_gmt":"2025-04-24T08:21:43","slug":"a-unique-foreign-key-issue-in-mysql-8-4","status":"publish","type":"post","link":"https:\/\/kedar.nitty-witty.com\/blog\/a-unique-foreign-key-issue-in-mysql-8-4","title":{"rendered":"A Unique Foreign Key issue in MySQL 8.4"},"content":{"rendered":"\n<p>Recently, a friend reached out to me for help after encountering an error while restoring a MySQL dump during an upgrade from MySQL 8.0 to 8.4. The error read:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>ERROR 6125 (HY000) at line 75: Failed to add the foreign key constraint. Missing unique key for constraint 'orders_ibfk_1' in the referenced table 'clients'.<\/code><\/pre>\n\n\n\n<p>At first glance, message is straightforward \u2014 the foreign key was pointing to a column without a unique constraint. <strong><em>BUT I&#8217;d not write a blog if that&#8217;s the only thing!<\/em><\/strong> In this post we analyze the working, the work around, the fixtures and meet a bug.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>&#91;root@mysql84 ~]# mysql -e \u201ccreate database production_database;\"\n&#91;root@mysql84 ~]# mysql production_database &lt; production_database.sql\nERROR 6125 (HY000) at line 75: Failed to add the foreign key constraint. Missing unique key for constraint 'orders_ibfk_1' in the referenced table 'clients'\n&#91;root@mysql84 ~]#<\/code><\/pre>\n\n\n\n<p>The error clearly states that the SQL failed to add Foreign Key as the referenced table had no unique key on the targetted column. This happened while importing a MySQL dump from version 8.0 into MySQL 8.4, the process failed with an error:<\/p>\n\n\n\n<p><br><strong>ERROR 6125 (HY000): Failed to add the foreign key constraint. Missing unique key for constraint\u2026<\/strong><\/p>\n\n\n\n<p>This happens because, starting with MySQL 8.4, the server enforces stricter foreign key rules \u2014 foreign keys must reference columns that are part of a unique or primary key constraint. This is a significant change from previous behavior, and it&#8217;s enforced by default using the new system variable restrict_fk_on_non_standard_key.<\/p>\n\n\n\n<p><strong>MySQL 8.4 Documentation<\/strong> reads this&#8230;<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Nonstandard foreign keys. The use of non-unique or partial keys as foreign keys is nonstandard, and is deprecated in MySQL. Beginning with MySQL 8.4.0, you must explicitly enable such keys by setting restrict_fk_on_non_standard_key to OFF, or by starting the server with &#8211;skip-restrict-fk-on-non-standard-key.<\/li>\n\n\n\n<li>restrict_fk_on_non_standard_key is ON by default, which means that trying to use a nonstandard key as a foreign key in a CREATE TABLE or other SQL statement is rejected with ER_WARN_DEPRECATED_NON_STANDARD_KEY. Setting it to ON allows such statements to run, but they raise the same error as a warning.<\/li>\n\n\n\n<li>Upgrades from MySQL 8.0 are supported even if there are tables containing foreign keys referring to non-unique or partial keys. In such cases, the server writes a list of warning messages containing the names of any foreign keys which refer to nonstandard keys.<\/li>\n<\/ul>\n\n\n\n<p>He wasn&#8217;t sure of if he can make the unique index on the system and he was in &#8220;hurry&#8221;. So I suggested the workaround to skip the foreign key issue temporarily:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>mysql> set global <strong>restrict_fk_on_non_standard_key<\/strong>=OFF;\nQuery OK, 0 rows affected, 1 warning (0.00 sec)\n\nmysql> show warnings;\n+\u2014\u2014\u2014+\u2014\u2014+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2013+\n| Level | Code | Message |\n+\u2014\u2014\u2014+\u2014\u2014+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2013+\n| Warning | 4166 | \u2018restrict_fk_on_non_standard_key\u2019 is deprecated and will be removed in a future release. Foreign key referring to non-unique or partial keys is unsafe and may break replication. |\n+\u2014\u2014\u2014+\u2014\u2014+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2013+\n1 row in set (0.00 sec)\n\nmysql> exit\nBye\n&#91;root@mysql84 ~]# mysql upgradetest &lt; upgradetest.sql\n&#91;root@mysql84 ~]# echo $?\n0\n&#91;root@mysql84 ~]#<\/code><\/pre>\n\n\n\n<p>Note that this variable is deprecated and it is strongly recommended to follow the standard foreign keys to refer columns which are defined as unique.<br>I suggested my friend to follow proper upgrade approach and use check-for-server-upgrade utility before doing upgrades. Anyhow, this could have ended here but then there&#8217;s something called &#8220;let me see more&#8221;!<\/p>\n\n\n\n<p><em>If you&#8217;re as curious, I&#8217;d ask you to run this along with me.<\/em><\/p>\n\n\n\n<h2 class=\"wp-block-heading\">The &#8220;Unique&#8221; Foreign Key Issue<\/h2>\n\n\n\n<p>I decided to run some test around this to understand what&#8217;s going on in MySQL 8.4.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>Following 4 tables were created in MySQL 8.0:\n\n\nDROP TABLE IF EXISTS clients;\nCREATE TABLE clients (\n    id INT AUTO_INCREMENT PRIMARY KEY,\n    client_id INT NOT NULL,\n    name VARCHAR(100),\n<strong>    UNIQUE KEY (client_id),<\/strong>\n<strong>    INDEX idx_client_id (client_id)<\/strong>\n);\n\nDROP TABLE IF EXISTS orders;\nCREATE TABLE orders (\n    id INT AUTO_INCREMENT PRIMARY KEY,\n    client_id INT,\n    order_details VARCHAR(255),\n    FOREIGN KEY (client_id) REFERENCES clients(client_id)\n);\n\nDROP TABLE IF EXISTS orders_2;\nDROP TABLE IF EXISTS clients_2;\nCREATE TABLE clients_2 (\n    id INT AUTO_INCREMENT PRIMARY KEY,\n    client_id INT NOT NULL,\n    name VARCHAR(100),\n    INDEX idx_client_id (client_id)\n);\n\nCREATE TABLE orders_2 (\n    id INT AUTO_INCREMENT PRIMARY KEY,\n    client_id INT,\n    order_details VARCHAR(255),\n    FOREIGN KEY (client_id) REFERENCES clients_2(client_id)\n);<\/code><\/pre>\n\n\n\n<p>To ensure compatibility before upgrading to MySQL 8.4, I ran the check-for-server-upgrade utility using MySQL Shell 8.4:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>&#91;root@centos_1 ~]# mysqlsh -- util check-for-server-upgrade root@localhost\n\n...\n\n4) Checks for foreign keys not referencing a full unique index\n(foreignKeyReferences)\n   Foreign keys to partial indexes may be forbidden as of 8.4.0, this check\n   identifies such cases to warn the user.\n\n<strong>   test.orders_ibfk_1 - invalid foreign key defined as 'orders(client_id)'<\/strong>\n      references a non unique key at table 'clients'.\n   test.orders_2_ibfk_1 - invalid foreign key defined as 'orders_2(client_id)'\n      references a non unique key at table 'clients_2'.\n<\/code><\/pre>\n\n\n\n<p>This tool flagged invalid foreign key definitions \u2014 specifically, those referencing non-unique keys, which are now disallowed by default in MySQL 8.4. These checks help identify upgrade-breaking schema issues such as foreign keys pointing to non-unique or partial indexes.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">How to identify Foreign Key compatibility?<\/h2>\n\n\n\n<p>The beauty of opensource allows you to explore the code under the hood and look what I found: <a href=\"https:\/\/github.com\/mysql\/mysql-shell\/blob\/8.4.4\/modules\/util\/upgrade_checker\/upgrade_check_creators.cc#L1581\">https:\/\/github.com\/mysql\/mysql-shell\/blob\/8.4.4\/modules\/util\/upgrade_checker\/upgrade_check_creators.cc#L1581<\/a><\/p>\n\n\n\n<p>This query there fetches the required information to provide us with the FK \/ UK relation. That said, I saw a problem in the query, nothing critical but surely wrong.<\/p>\n\n\n\n<p>Did you note that the query wrongly identifies error about client_id not having unique key for clients table?! The clients table&#8217;s client_id does have a UNIQUE KEY yet it is reported. Why? It is not a critical issue but it is a bug.<\/p>\n\n\n\n<p>Executing above query manually returns two records:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>select\n  fk.constraint_schema,\n  fk.constraint_name,\n  '',\n  fk.parent_fk_definition as fk_definition,\n  fk.REFERENCED_TABLE_NAME as target_table,\n  '##fkToNonUniqueKey'\nfrom (select\n      rc.constraint_schema,\n      rc.constraint_name,\n      CONCAT(rc.table_name, '(', GROUP_CONCAT(kc.column_name order by kc.ORDINAL_POSITION),')') as parent_fk_definition,\n      CONCAT(kc.REFERENCED_TABLE_SCHEMA,'.',kc.REFERENCED_TABLE_NAME, '(', GROUP_CONCAT(kc.REFERENCED_COLUMN_NAME order by kc.POSITION_IN_UNIQUE_CONSTRAINT),')') as target_fk_definition,\n      rc.REFERENCED_TABLE_NAME\n    from\n      information_schema.REFERENTIAL_CONSTRAINTS rc\n        join\n          information_schema.KEY_COLUMN_USAGE kc\n        on\n          rc.constraint_schema = kc.constraint_schema AND\n          rc.constraint_name = kc.constraint_name AND\n          rc.constraint_schema = kc.REFERENCED_TABLE_SCHEMA AND\n          rc.REFERENCED_TABLE_NAME = kc.REFERENCED_TABLE_NAME AND\n          kc.REFERENCED_TABLE_NAME is not NULL AND\n          kc.REFERENCED_COLUMN_NAME is not NULL\n    where\n      true\n    group by\n      rc.constraint_schema,\n      rc.constraint_name,\n      rc.table_name,\n      rc.REFERENCED_TABLE_NAME) fk\n  join (SELECT\n      CONCAT(table_schema,'.',table_name,'(',GROUP_CONCAT(column_name order by seq_in_index),')') as fk_definition,\n      SUM(non_unique) as non_unique_count\n    FROM\n      INFORMATION_SCHEMA.STATISTICS\n    WHERE\n      sub_part IS NULL\n    GROUP BY\n      table_schema, table_name, index_name) idx\n    on\n      fk.target_fk_definition = idx.fk_definition AND\n      idx.non_unique_count > 0\n+-------------------+-----------------+--+---------------------+--------------+--------------------+\n| constraint_schema | constraint_name |  | fk_definition       | target_table | ##fkToNonUniqueKey |\n+-------------------+-----------------+--+---------------------+--------------+--------------------+\n| test              | orders_ibfk_1   |  | orders(client_id)   | clients      | ##fkToNonUniqueKey |\n| test              | orders_2_ibfk_1 |  | orders_2(client_id) | clients_2    | ##fkToNonUniqueKey |\n+-------------------+-----------------+--+---------------------+--------------+--------------------+<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">Fixing the query<\/h2>\n\n\n\n<p>We can rewrite this query and correctly report:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>SELECT\n  fk.constraint_schema,\n  fk.constraint_name,\n  '',\n  fk.parent_fk_definition AS fk_definition,\n  fk.REFERENCED_TABLE_NAME AS target_table,\n  '##fkToNonUniqueKey'\nFROM (\n  SELECT\n    rc.constraint_schema,\n    rc.constraint_name,\n    CONCAT(rc.table_name, '(', GROUP_CONCAT(kc.column_name ORDER BY kc.ORDINAL_POSITION), ')') AS parent_fk_definition,\n    CONCAT(kc.REFERENCED_TABLE_SCHEMA, '.', kc.REFERENCED_TABLE_NAME, '(', GROUP_CONCAT(kc.REFERENCED_COLUMN_NAME ORDER BY kc.POSITION_IN_UNIQUE_CONSTRAINT), ')') AS target_fk_definition,\n    rc.REFERENCED_TABLE_NAME\n  FROM\n    information_schema.REFERENTIAL_CONSTRAINTS rc\n  JOIN\n    information_schema.KEY_COLUMN_USAGE kc\n  ON\n    rc.constraint_schema = kc.constraint_schema AND\n    rc.constraint_name = kc.constraint_name AND\n    rc.constraint_schema = kc.REFERENCED_TABLE_SCHEMA AND\n    rc.REFERENCED_TABLE_NAME = kc.REFERENCED_TABLE_NAME AND\n    kc.REFERENCED_TABLE_NAME IS NOT NULL AND\n    kc.REFERENCED_COLUMN_NAME IS NOT NULL\n  GROUP BY\n    rc.constraint_schema,\n    rc.constraint_name,\n    rc.table_name,\n    rc.REFERENCED_TABLE_NAME\n) fk\nLEFT JOIN (\n  SELECT\n    CONCAT(table_schema, '.', table_name, '(', GROUP_CONCAT(column_name ORDER BY seq_in_index), ')') AS fk_definition\n  FROM\n    INFORMATION_SCHEMA.STATISTICS\n  WHERE\n    sub_part IS NULL AND\n    non_unique = 0  -- Only consider unique indexes\n  GROUP BY\n    table_schema, table_name, index_name\n) unique_idx ON fk.target_fk_definition = unique_idx.fk_definition\nWHERE\n  unique_idx.fk_definition IS NULL;\n+-------------------+-----------------+--+---------------------+--------------+--------------------+\n| constraint_schema | constraint_name |  | fk_definition       | target_table | ##fkToNonUniqueKey |\n+-------------------+-----------------+--+---------------------+--------------+--------------------+\n| test              | orders_2_ibfk_1 |  | orders_2(client_id) | clients_2    | ##fkToNonUniqueKey |\n+-------------------+-----------------+--+---------------------+--------------+--------------------+<\/code><\/pre>\n\n\n\n<p>I have already reported this bug and it has been verified.<\/p>\n\n\n\n<p>Bug Report: <a href=\"https:\/\/bugs.mysql.com\/bug.php?id=118023\">https:\/\/bugs.mysql.com\/bug.php?id=118023<\/a><\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Conclusion<\/h2>\n\n\n\n<p>Hope this post clarified what &#8220;unique&#8221; about &#8220;foreign keys&#8221; in MySQL 8.4. What started as a simple foreign key error led to uncovering how MySQL 8.4 handles constraints more strictly than before. It&#8217;s a good reminder: every upgrade can change behavior, and knowing the details matters.<\/p>\n\n\n\n<p>Quick fixes like disabling <code>restrict_fk_on_non_standard_key<\/code> might help short-term, but the real fix is adapting to MySQL\u2019s latest standards.<\/p>\n\n\n\n<p>Let me know your learning stories until I come back with another one. Happy Upgrading.<\/p>\n","protected":false},"excerpt":{"rendered":"Recently, a friend reached out to me for help after encountering an error while restoring a MySQL dump during an upgrade from MySQL 8.0 to 8.4. The error read: At&hellip;\n","protected":false},"author":1,"featured_media":3464,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"om_disable_all_campaigns":false,"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"footnotes":""},"categories":[8,867],"tags":[1093,315,427,1094,1096,1090,1095,495,1091,1092],"class_list":{"0":"post-3463","1":"post","2":"type-post","3":"status-publish","4":"format-standard","5":"has-post-thumbnail","7":"category-mysql","8":"category-mysql-upgrade","9":"tag-er_warn_deprecated_non_standard_key","10":"tag-foreign-key","11":"tag-mysql","12":"tag-mysql-8-0-to-8-4-compatibility","13":"tag-mysql-8-0-to-8-4-upgrade","14":"tag-mysql-8-4","15":"tag-mysql-8-4-foreign-keys","16":"tag-mysql-bug","17":"tag-mysql-upgrade","18":"tag-restrict_fk_on_non_standard_key"},"aioseo_notices":[],"amp_enabled":true,"_links":{"self":[{"href":"https:\/\/kedar.nitty-witty.com\/blog\/wp-json\/wp\/v2\/posts\/3463","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/kedar.nitty-witty.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/kedar.nitty-witty.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/kedar.nitty-witty.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/kedar.nitty-witty.com\/blog\/wp-json\/wp\/v2\/comments?post=3463"}],"version-history":[{"count":1,"href":"https:\/\/kedar.nitty-witty.com\/blog\/wp-json\/wp\/v2\/posts\/3463\/revisions"}],"predecessor-version":[{"id":3465,"href":"https:\/\/kedar.nitty-witty.com\/blog\/wp-json\/wp\/v2\/posts\/3463\/revisions\/3465"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/kedar.nitty-witty.com\/blog\/wp-json\/wp\/v2\/media\/3464"}],"wp:attachment":[{"href":"https:\/\/kedar.nitty-witty.com\/blog\/wp-json\/wp\/v2\/media?parent=3463"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/kedar.nitty-witty.com\/blog\/wp-json\/wp\/v2\/categories?post=3463"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/kedar.nitty-witty.com\/blog\/wp-json\/wp\/v2\/tags?post=3463"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}