Merge branch 'mc-specify-change-column-default-is-not-risky-docs' into 'master'

Adds a section about `change_column_default`

See merge request gitlab-org/gitlab!18090

doc/development/migration_style_guide.md

@@ -286,6 +286,48 @@ For a small table (such as an empty one or one with less than `1,000` records),
 use `add_column` and `change_column_default` in a single-transaction migration,
 combining it with other operations that don't require `disable_ddl_transaction!`.
 
+## Changing the column default
+
+One might think that changing a default column with `change_column_default` is an
+expensive and disruptive operation for larger tables, but in reality it's not.
+
+Take the following migration as an example:
+
+```ruby
+class DefaultRequestAccessGroups < ActiveRecord::Migration[5.2]
+  include Gitlab::Database::MigrationHelpers
+
+  DOWNTIME = false
+
+  def up
+    change_column_default :namespaces, :request_access_enabled, true
+  end
+
+  def down
+    change_column_default :namespaces, :request_access_enabled, false
+  end
+end
+```
+
+Migration above changes the default column value of one of our largest
+tables: `namespaces`. This can be translated to:
+
+```sql
+ALTER TABLE namespaces
+ALTER COLUMN request_access_enabled
+DEFAULT false
+```
+
+In this particular case, the default value exists and we're just changing the metadata for
+`request_access_enabled` column, which does not imply a rewrite of all the existing records
+in the `namespaces` table. Only when creating a new column with a default, all the records are going be rewritten.
+
+NOTE: **Note:**  A faster [ALTER TABLE ADD COLUMN with a non-null default](https://www.depesz.com/2018/04/04/waiting-for-postgresql-11-fast-alter-table-add-column-with-a-non-null-default/)
+was introduced on PostgresSQL 11.0, removing the need of rewritting the table when a new column with a default value is added.
+
+For the reasons mentioned above, it's safe to use `change_column_default` in a single-transaction migration
+without requiring `disable_ddl_transaction!`.
+
 ## Updating an existing column
 
 To update an existing column to a particular value, you can use