From 7e1beb8278e1f7cd27df6f836fd344e06cab7d53 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gr=C3=A9goire=20Paris?= <postmaster@greg0ire.fr>
Date: Fri, 11 Sep 2020 23:48:32 +0200
Subject: [PATCH] Add explanation about implicit indexes

---
 docs/en/explanation/implicit-indexes.rst | 41 ++++++++++++++++++++++++
 docs/en/sidebar.rst                      |  2 ++
 lib/Doctrine/DBAL/Schema/Table.php       |  4 +--
 3 files changed, 45 insertions(+), 2 deletions(-)
 create mode 100644 docs/en/explanation/implicit-indexes.rst

diff --git a/docs/en/explanation/implicit-indexes.rst b/docs/en/explanation/implicit-indexes.rst
new file mode 100644
index 00000000000..26b355a7a1e
--- /dev/null
+++ b/docs/en/explanation/implicit-indexes.rst
@@ -0,0 +1,41 @@
+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.
+
+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.
+
+
+Here are some database platforms 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 grounds that such indexes are not always
+needed, and can be created in many different ways. They instead leave
+that responsibility 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 reduced because you always end up with an index, be it
+created by the RDBMS or by the DBAL
+
+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.
diff --git a/docs/en/sidebar.rst b/docs/en/sidebar.rst
index 0935c8dc179..4ada9f1caf1 100644
--- a/docs/en/sidebar.rst
+++ b/docs/en/sidebar.rst
@@ -20,3 +20,5 @@
     reference/caching
     reference/known-vendor-issues
     reference/upgrading
+
+    explanation/implicit-indexes
diff --git a/lib/Doctrine/DBAL/Schema/Table.php b/lib/Doctrine/DBAL/Schema/Table.php
index 909b349107b..79c86554c9d 100644
--- a/lib/Doctrine/DBAL/Schema/Table.php
+++ b/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).