1 files changed, 85 insertions, 3 deletions
diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md
index 46ea91fcdf3..3e993243855 100644
--- a/doc/development/migration_style_guide.md
+++ b/doc/development/migration_style_guide.md
@@ -171,7 +171,7 @@ lock allow the database to process other statements.
 
 ### Examples
 
-Removing a column:
+**Removing a column:**
 
 ```ruby
 include Gitlab::Database::MigrationHelpers
@@ -189,7 +189,7 @@ def down
 end
 ```
 
-Removing a foreign key:
+**Removing a foreign key:**
 
 ```ruby
 include Gitlab::Database::MigrationHelpers
@@ -207,7 +207,7 @@ def down
 end
 ```
 
-Changing default value for a column:
+**Changing default value for a column:**
 
 ```ruby
 include Gitlab::Database::MigrationHelpers
@@ -225,6 +225,88 @@ def down
 end
 ```
 
+**Creating a new table with a foreign key:**
+
+We can simply wrap the `create_table` method with `with_lock_retries`:
+
+```ruby
+def up
+  with_lock_retries do
+    create_table :issues do |t|
+      t.references :project, index: true, null: false, foreign_key: { on_delete: :cascade }
+      t.string :title, limit: 255
+    end
+  end
+end
+
+def down
+  drop_table :issues
+end
+```
+
+**Creating a new table when we have two foreign keys:**
+
+For this, we'll need three migrations:
+
+1. Creating the table without foreign keys (with the indices).
+1. Add foreign key to the first table.
+1. Add foreign key to the second table.
+
+Creating the table:
+
+```ruby
+def up
+  create_table :imports do |t|
+    t.bigint :project_id, null: false
+    t.bigint :user_id, null: false
+    t.string :jid, limit: 255
+  end
+
+  add_index :imports, :project_id
+  add_index :imports, :user_id
+end
+
+def down
+  drop_table :imports
+end
+```
+
+Adding foreign key to `projects`:
+
+```ruby
+include Gitlab::Database::MigrationHelpers
+
+def up
+  with_lock_retries do
+    add_foreign_key :imports, :projects, column: :project_id, on_delete: :cascade
+  end
+end
+
+def down
+  with_lock_retries do
+    remove_foreign_key :imports, column: :project_id
+  end
+end
+```
+
+Adding foreign key to `users`:
+
+```ruby
+include Gitlab::Database::MigrationHelpers
+
+def up
+  with_lock_retries do
+    add_foreign_key :imports, :users, column: :user_id, on_delete: :cascade
+  end
+end
+
+def down
+  with_lock_retries do
+    remove_foreign_key :imports, column: :user_id
+  end
+end
+```
+
 ### When to use the helper method
 
 The `with_lock_retries` helper method can be used when you normally use