Add explanation about explicit indexes

Author: greg0ire

docs/en/explanation/implicit-indexes.rst

@@ -0,0 +1,40 @@
+Implicit indexes
+================
+
+So-called implicit indexes are named as such because they are created
+without the user asking for it. Some RDBMS will do so when you create a
+foreign key: they will create an index on the referencing table, using
+the referencing columns.
+
+Here are some RDBMS that are known to create indexes when creating a
+foreign key:
+
+- `MySQL <https://dev.mysql.com/doc/refman/8.0/en/create-table-foreign-keys.html>`_
+- `MariaDB <https://mariadb.com/kb/en/foreign-keys>`_
+
+
+Some other will not do so, on grands that such indexes are not always
+needed, and can be created in many different ways. They instead leave
+that responsability to the user:
+
+- `PostgreSQL <https://stackoverflow.com/questions/970562/postgres-and-indexes-on-foreign-keys-and-primary-keys>`_
+- `SQLite <https://sqlite.org/foreignkeys.html#fk_indexes>`_
+- `SQL Server <https://stackoverflow.com/questions/836167/does-a-foreign-key-automatically-create-an-index>`_
+
+In the case of these systems, the DBAL does the index creation for you
+and automatically picks an index name that obeys string length
+constraints of the platform you are using. That way, differences between
+platforms is reduce because you always end up with an index, be it
+created by the RDBMS or by the DBAL
+
+The rationale behind this is that these indexes improve performance, for
+instance for checking that  a delete operation can be performed on a
+referenced table without violating the constraint in the referencing
+table.
+
+You can still explicitly create such indexes yourself, and the DBAL will
+notice when your index fulfills the indexing and constraint needs of the
+implicit index it would create, and will refrain from doing so.
+
+Some RDBMS such as MySQL do something similar and can also drop implicit
+indexes that are fulfilled by user-defined indexes.

docs/en/sidebar.rst

@@ -20,3 +20,5 @@
     reference/caching
     reference/known-vendor-issues
     reference/upgrading
+
+    explanation/implicit-indexes

lib/Doctrine/DBAL/Schema/Table.php

@@ -554,8 +554,8 @@ protected function _addForeignKeyConstraint(ForeignKeyConstraint $constraint)
 
         $this->_fkConstraints[$name] = $constraint;
 
-        // Add an explicit index on the foreign key columns.
-        // If there is already an index that fulfils this requirements drop the request.
+        // Add an implicit index on the foreign key columns.
+        // If there is already an index that fulfills these requirements drop the request.
         // In the case of __construct calling this method during hydration from schema-details
         // all the explicitly added indexes lead to duplicates. This creates computation overhead in this case,
         // however no duplicate indexes are ever added (based on columns).