Document how to handle different DB (versions)

2 files changed, 27 insertions, 0 deletions

diff --git a/doc/development/README.md b/doc/development/README.md
index 36367f0a60d..50b064ee960 100644
--- a/doc/development/README.md
+++ b/doc/development/README.md
@@ -58,6 +58,7 @@
 - [Storing SHA1 Hashes As Binary](sha1_as_binary.md)
 - [Iterating Tables In Batches](iterating_tables_in_batches.md)
 - [Ordering Table Columns](ordering_table_columns.md)
+- [Verifying Database Capabilities](verifying_database_capabilities.md)
 
 ## i18n
 
diff --git a/doc/development/verifying_database_capabilities.md b/doc/development/verifying_database_capabilities.md
new file mode 100644
index 00000000000..cc6d62957e3
--- /dev/null
+++ b/doc/development/verifying_database_capabilities.md
@@ -0,0 +1,26 @@
+# Verifying Database Capabilities
+
+Sometimes certain bits of code may only work on a certain database and/or
+version. While we try to avoid such code as much as possible sometimes it is
+necessary to add database (version) specific behaviour.
+
+To facilitate this we have the following methods that you can use:
+
+* `Gitlab::Database.postgresql?`: returns `true` if PostgreSQL is being used
+* `Gitlab::Database.mysql?`: returns `true` if MySQL is being used
+* `Gitlab::Database.version`: returns the PostgreSQL version number as a string
+  in the format `X.Y.Z`. This method does not work for MySQL
+
+This allows you to write code such as:
+
+```ruby
+if Gitlab::Database.postgresql?
+  if Gitlab::Database.version.to_f >= 9.6
+    run_really_fast_query
+  else
+    run_fast_query
+  end
+else
+  run_query
+end
+```