1 files changed, 63 insertions, 0 deletions
diff --git a/doc/development/database/single_table_inheritance.md b/doc/development/database/single_table_inheritance.md
new file mode 100644
index 00000000000..c8d082e8a67
--- /dev/null
+++ b/doc/development/database/single_table_inheritance.md
@@ -0,0 +1,63 @@
+---
+stage: Data Stores
+group: Database
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# Single Table Inheritance
+
+**Summary:** don't use Single Table Inheritance (STI), use separate tables
+instead.
+
+Rails makes it possible to have multiple models stored in the same table and map
+these rows to the correct models using a `type` column. This can be used to for
+example store two different types of SSH keys in the same table.
+
+While tempting to use one should avoid this at all costs for the same reasons as
+outlined in the document ["Polymorphic Associations"](polymorphic_associations.md).
+
+## Solution
+
+The solution is very simple: just use a separate table for every type you'd
+otherwise store in the same table. For example, instead of having a `keys` table
+with `type` set to either `Key` or `DeployKey` you'd have two separate tables:
+`keys` and `deploy_keys`.
+
+## In migrations
+
+Whenever a model is used in a migration, single table inheritance should be disabled.
+Due to the way Rails loads associations (even in migrations), failing to disable STI
+could result in loading unexpected code or associations which may cause unintended
+side effects or failures during upgrades.
+
+```ruby
+class SomeMigration < Gitlab::Database::Migration[2.0]
+  class Services < MigrationRecord
+    self.table_name = 'services'
+    self.inheritance_column = :_type_disabled
+  end
+
+  def up
+  ...
+```
+
+If nothing needs to be added to the model other than disabling STI or `EachBatch`,
+use the helper `define_batchable_model` instead of defining the class.
+This ensures that the migration loads the columns for the migration in isolation,
+and the helper disables STI by default.
+
+```ruby
+class EnqueueSomeBackgroundMigration < Gitlab::Database::Migration[1.0]
+  disable_ddl_transaction!
+
+  def up
+    define_batchable_model('services').select(:id).in_batches do |relation|
+      jobs = relation.pluck(:id).map do |id|
+        ['ExtractServicesUrl', [id]]
+      end
+
+      BackgroundMigrationWorker.bulk_perform_async(jobs)
+    end
+  end
+  ...
+```