Add with_lock_retries to DB review guidelines

doc/development/database_review.md

@@ -79,6 +79,7 @@ the following preparations into account.
   - Include either a rollback procedure or describe how to rollback changes.
 - Add the output of the migration(s) to the MR description.
 - Add tests for the migration in `spec/migrations` if necessary. See [Testing Rails migrations at GitLab](testing_guide/testing_migrations_guide.md) for more details.
+- When [high-traffic](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/migration_helpers.rb#L12) tables are involved in the migration, use the [`with_lock_retries`](migration_style_guide.md#retry-mechanism-when-acquiring-database-locks) helper method. Review the relevant [examples in our documentation](migration_style_guide.md#examples) for use cases and solutions.
 
 #### Preparation when adding or modifying queries
 

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