Bug #98078 Required index for foreign key is not clear in doc
Submitted: 26 Dec 2019 18:42 Modified: 9 Jan 2020 18:27
Reporter: Bill Karwin (Candidate Quality Contributor) (OCA) Email Updates:
Status: Closed Impact on me:
None 
Category:MySQL Server: Documentation Severity:S3 (Non-critical)
Version:8.0 OS:Any
Assigned to: CPU Architecture:Any

[26 Dec 2019 18:42] Bill Karwin
Description:
The manual https://dev.mysql.com/doc/refman/8.0/en/create-table-foreign-keys.html says:

"The foreign key can be self referential (referring to the same table). When you add a foreign key constraint to a table using ALTER TABLE, remember to create the required indexes first."

This statement is correct, but it is susceptible to misinterpretation. Example: in this Stack Overview question https://stackoverflow.com/q/59490809/20860 a user thought the "required indexes" referred to the index on the foreign key column, which should be created automatically. But in fact the required index is the one on the column the foreign key references.

How to repeat:
Any user who doesn't immediately know what "required indexes" means in this documentation may misunderstand it.

Suggested fix:
"The foreign key can be self referential (referring to the same table). When you add a foreign key constraint to a table using ALTER TABLE, remember to create first an index on the column(s) referenced by the foreign key."
[26 Dec 2019 23:29] MySQL Verification Team
Thank you for the bug report.
[9 Jan 2020 18:27] Daniel Price
Posted by developer:
 
The referenced content has been revised as suggested. The change should appear online soon.
Thank you for the bug report.