summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorYorick Peterse <yorickpeterse@gmail.com>2017-08-11 14:16:08 +0200
committerYorick Peterse <yorickpeterse@gmail.com>2017-08-16 16:39:37 +0200
commita4a8cae7e1d4f5c72ddc0fce18d8530bf0e6c911 (patch)
tree2b0c30ed99c17577caad3b81b09c64da19ab4185
parent6735e1dc9a3ae2e55c837f4ecea4bc3c6972a671 (diff)
downloadgitlab-ce-a4a8cae7e1d4f5c72ddc0fce18d8530bf0e6c911.tar.gz
Document not using database hash indexes
-rw-r--r--doc/development/README.md1
-rw-r--r--doc/development/hash_indexes.md20
2 files changed, 21 insertions, 0 deletions
diff --git a/doc/development/README.md b/doc/development/README.md
index 50b064ee960..dd150421b65 100644
--- a/doc/development/README.md
+++ b/doc/development/README.md
@@ -59,6 +59,7 @@
- [Iterating Tables In Batches](iterating_tables_in_batches.md)
- [Ordering Table Columns](ordering_table_columns.md)
- [Verifying Database Capabilities](verifying_database_capabilities.md)
+- [Hash Indexes](hash_indexes.md)
## i18n
diff --git a/doc/development/hash_indexes.md b/doc/development/hash_indexes.md
new file mode 100644
index 00000000000..e6c1b3590b1
--- /dev/null
+++ b/doc/development/hash_indexes.md
@@ -0,0 +1,20 @@
+# Hash Indexes
+
+Both PostgreSQL and MySQL support hash indexes besides the regular btree
+indexes. Hash indexes however are to be avoided at all costs. While they may
+_sometimes_ provide better performance the cost of rehashing can be very high.
+More importantly: at least until PostgreSQL 10.0 hash indexes are not
+WAL-logged, meaning they are not replicated to any replicas. From the PostgreSQL
+documentation:
+
+> Hash index operations are not presently WAL-logged, so hash indexes might need
+> to be rebuilt with REINDEX after a database crash if there were unwritten
+> changes. Also, changes to hash indexes are not replicated over streaming or
+> file-based replication after the initial base backup, so they give wrong
+> answers to queries that subsequently use them. For these reasons, hash index
+> use is presently discouraged.
+
+RuboCop is configured to register an offence when it detects the use of a hash
+index.
+
+Instead of using hash indexes you should use regular btree indexes.