Add latest changes from gitlab-org/gitlab@master

4 files changed, 89 insertions, 6 deletions

diff --git a/doc/development/README.md b/doc/development/README.md
index 2089cf794ba..e55989e312a 100644
--- a/doc/development/README.md
+++ b/doc/development/README.md
@@ -98,6 +98,8 @@ Complementary reads:
 - [Application limits](application_limits.md)
 - [Redis guidelines](redis.md)
 - [Rails initializers](rails_initializers.md)
+- [Code comments](code_comments.md)
+- [Renaming features](renaming_features.md)
 
 ## Performance guides
 
@@ -150,9 +152,7 @@ Complementary reads:
 - [Verifying database capabilities](verifying_database_capabilities.md)
 - [Database Debugging and Troubleshooting](database_debugging.md)
 - [Query Count Limits](query_count_limits.md)
-- [Code comments](code_comments.md)
 - [Creating enums](creating_enums.md)
-- [Renaming features](renaming_features.md)
 
 ### Case studies
 
diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md
index 7c0146017b1..37d8a677389 100644
--- a/doc/development/api_styleguide.md
+++ b/doc/development/api_styleguide.md
@@ -121,7 +121,7 @@ For instance:
 The [internal API](./internal_api.md) is documented for internal use. Please keep it up to date so we know what endpoints
 different components are making use of.
 
-[Entity]: https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/entities.rb
+[Entity]: https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/entities
 [validation, and coercion of the parameters]: https://github.com/ruby-grape/grape#parameter-validation-and-coercion
 [installing GitLab under a relative URL]: https://docs.gitlab.com/ee/install/relative_url.html
 
diff --git a/doc/development/database_review.md b/doc/development/database_review.md
index 0fdf255e266..650c6fc7936 100644
--- a/doc/development/database_review.md
+++ b/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
 
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