strong_migrations 1.6.0 → 2.8.0

data/README.md

@@ -8,7 +8,7 @@ Supports PostgreSQL, MySQL, and MariaDB
 
 :tangerine: Battle-tested at [Instacart](https://www.instacart.com/opensource)
 
-[![Build Status](https://github.com/ankane/strong_migrations/workflows/build/badge.svg?branch=master)](https://github.com/ankane/strong_migrations/actions)
+[![Build Status](https://github.com/ankane/strong_migrations/actions/workflows/build.yml/badge.svg)](https://github.com/ankane/strong_migrations/actions)
 
 ## Installation
 
@@ -38,12 +38,12 @@ Active Record caches attributes, which causes problems
 when removing columns. Be sure to ignore the column:
 
 class User < ApplicationRecord
-  self.ignored_columns = ["name"]
+  self.ignored_columns += ["name"]
 end
 
 Deploy the code, then wrap this step in a safety_assured { ... } block.
 
-class RemoveColumn < ActiveRecord::Migration[7.0]
+class RemoveColumn < ActiveRecord::Migration[8.1]
   def change
     safety_assured { remove_column :users, :name }
   end
@@ -60,28 +60,34 @@ An operation is classified as dangerous if it either:
 Potentially dangerous operations:
 
 - [removing a column](#removing-a-column)
-- [adding a column with a default value](#adding-a-column-with-a-default-value)
-- [backfilling data](#backfilling-data)
-- [adding a stored generated column](#adding-a-stored-generated-column)
 - [changing the type of a column](#changing-the-type-of-a-column)
 - [renaming a column](#renaming-a-column)
 - [renaming a table](#renaming-a-table)
 - [creating a table with the force option](#creating-a-table-with-the-force-option)
+- [adding an auto-incrementing column](#adding-an-auto-incrementing-column)
+- [adding a stored generated column](#adding-a-stored-generated-column)
+- [adding a foreign key](#adding-a-foreign-key)
 - [adding a check constraint](#adding-a-check-constraint)
 - [executing SQL directly](#executing-SQL-directly)
+- [backfilling data](#backfilling-data)
 
 Postgres-specific checks:
 
 - [adding an index non-concurrently](#adding-an-index-non-concurrently)
 - [adding a reference](#adding-a-reference)
-- [adding a foreign key](#adding-a-foreign-key)
+- [adding a unique constraint](#adding-a-unique-constraint)
 - [adding an exclusion constraint](#adding-an-exclusion-constraint)
 - [adding a json column](#adding-a-json-column)
+- [adding a column with a volatile default value](#adding-a-column-with-a-volatile-default-value)
 - [setting NOT NULL on an existing column](#setting-not-null-on-an-existing-column)
+- [renaming an enum value](#renaming-an-enum-value)
+- [renaming a schema](#renaming-a-schema)
 
-Config-specific checks:
+MySQL and MariaDB-specific checks:
 
-- [changing the default value of a column](#changing-the-default-value-of-a-column)
+- [using the COPY algorithm](#using-the-copy-algorithm)
+- [using shared or exclusive locking](#using-shared-or-exclusive-locking)
+- [adding a column with an expression default value](#adding-a-column-with-an-expression-default-value)
 
 Best practices:
 
@@ -96,7 +102,7 @@ You can also add [custom checks](#custom-checks) or [disable specific checks](#d
 Active Record caches database columns at runtime, so if you drop a column, it can cause exceptions until your app reboots.
 
 ```ruby
-class RemoveSomeColumnFromUsers < ActiveRecord::Migration[7.0]
+class RemoveSomeColumnFromUsers < ActiveRecord::Migration[8.1]
   def change
     remove_column :users, :some_column
   end
@@ -109,7 +115,7 @@ end
 
   ```ruby
   class User < ApplicationRecord
-    self.ignored_columns = ["some_column"]
+    self.ignored_columns += ["some_column"]
   end
   ```
 
@@ -117,7 +123,7 @@ end
 3. Write a migration to remove the column (wrap in `safety_assured` block)
 
   ```ruby
-  class RemoveSomeColumnFromUsers < ActiveRecord::Migration[7.0]
+  class RemoveSomeColumnFromUsers < ActiveRecord::Migration[8.1]
     def change
       safety_assured { remove_column :users, :some_column }
     end
@@ -127,93 +133,6 @@ end
 4. Deploy and run the migration
 5. Remove the line added in step 1
 
-### Adding a column with a default value
-
-#### Bad
-
-In earlier versions of Postgres, MySQL, and MariaDB, adding a column with a default value to an existing table causes the entire table to be rewritten. During this time, reads and writes are blocked in Postgres, and writes are blocked in MySQL and MariaDB.
-
-```ruby
-class AddSomeColumnToUsers < ActiveRecord::Migration[7.0]
-  def change
-    add_column :users, :some_column, :text, default: "default_value"
-  end
-end
-```
-
-In Postgres 11+, MySQL 8.0.12+, and MariaDB 10.3.2+, this no longer requires a table rewrite and is safe (except for volatile functions like `gen_random_uuid()`).
-
-#### Good
-
-Instead, add the column without a default value, then change the default.
-
-```ruby
-class AddSomeColumnToUsers < ActiveRecord::Migration[7.0]
-  def up
-    add_column :users, :some_column, :text
-    change_column_default :users, :some_column, "default_value"
-  end
-
-  def down
-    remove_column :users, :some_column
-  end
-end
-```
-
-See the next section for how to backfill.
-
-### Backfilling data
-
-#### Bad
-
-Active Record creates a transaction around each migration, and backfilling in the same transaction that alters a table keeps the table locked for the [duration of the backfill](https://wework.github.io/data/2015/11/05/add-columns-with-default-values-to-large-tables-in-rails-postgres/).
-
-```ruby
-class AddSomeColumnToUsers < ActiveRecord::Migration[7.0]
-  def change
-    add_column :users, :some_column, :text
-    User.update_all some_column: "default_value"
-  end
-end
-```
-
-Also, running a single query to update data can cause issues for large tables.
-
-#### Good
-
-There are three keys to backfilling safely: batching, throttling, and running it outside a transaction. Use the Rails console or a separate migration with `disable_ddl_transaction!`.
-
-```ruby
-class BackfillSomeColumn < ActiveRecord::Migration[7.0]
-  disable_ddl_transaction!
-
-  def up
-    User.unscoped.in_batches do |relation|
-      relation.update_all some_column: "default_value"
-      sleep(0.01) # throttle
-    end
-  end
-end
-```
-
-### Adding a stored generated column
-
-#### Bad
-
-Adding a stored generated column causes the entire table to be rewritten. During this time, reads and writes are blocked in Postgres, and writes are blocked in MySQL and MariaDB.
-
-```ruby
-class AddSomeColumnToUsers < ActiveRecord::Migration[7.0]
-  def change
-    add_column :users, :some_column, :virtual, type: :string, as: "...", stored: true
-  end
-end
-```
-
-#### Good
-
-Add a non-generated column and use callbacks or triggers instead (or a virtual generated column with MySQL and MariaDB).
-
 ### Changing the type of a column
 
 #### Bad
@@ -221,7 +140,7 @@ Add a non-generated column and use callbacks or triggers instead (or a virtual g
 Changing the type of a column causes the entire table to be rewritten. During this time, reads and writes are blocked in Postgres, and writes are blocked in MySQL and MariaDB.
 
 ```ruby
-class ChangeSomeColumnType < ActiveRecord::Migration[7.0]
+class ChangeSomeColumnType < ActiveRecord::Migration[8.1]
   def change
     change_column :users, :some_column, :new_type
   end
@@ -234,14 +153,14 @@ Type | Safe Changes
 --- | ---
 `cidr` | Changing to `inet`
 `citext` | Changing to `text` if not indexed, changing to `string` with no `:limit` if not indexed
-`datetime` | Increasing or removing `:precision`, changing to `timestamptz` when session time zone is UTC in Postgres 12+
+`datetime` | Increasing or removing `:precision`, changing to `timestamptz` when session time zone is UTC
 `decimal` | Increasing `:precision` at same `:scale`, removing `:precision` and `:scale`
 `interval` | Increasing or removing `:precision`
 `numeric` | Increasing `:precision` at same `:scale`, removing `:precision` and `:scale`
 `string` | Increasing or removing `:limit`, changing to `text`, changing `citext` if not indexed
 `text` | Changing to `string` with no `:limit`, changing to `citext` if not indexed
 `time` | Increasing or removing `:precision`
-`timestamptz` | Increasing or removing `:limit`, changing to `datetime` when session time zone is UTC in Postgres 12+
+`timestamptz` | Increasing or removing `:limit`, changing to `datetime` when session time zone is UTC
 
 And some in MySQL and MariaDB:
 
@@ -267,7 +186,7 @@ A safer approach is to:
 Renaming a column that’s in use will cause errors in your application.
 
 ```ruby
-class RenameSomeColumn < ActiveRecord::Migration[7.0]
+class RenameSomeColumn < ActiveRecord::Migration[8.1]
   def change
     rename_column :users, :some_column, :new_name
   end
@@ -292,7 +211,7 @@ A safer approach is to:
 Renaming a table that’s in use will cause errors in your application.
 
 ```ruby
-class RenameUsersToCustomers < ActiveRecord::Migration[7.0]
+class RenameUsersToCustomers < ActiveRecord::Migration[8.1]
   def change
     rename_table :users, :customers
   end
@@ -305,7 +224,7 @@ A safer approach is to:
 
 1. Create a new table
 2. Write to both tables
-3. Backfill data from the old table to new table
+3. Backfill data from the old table to the new table
 4. Move reads from the old table to the new table
 5. Stop writing to the old table
 6. Drop the old table
@@ -317,7 +236,7 @@ A safer approach is to:
 The `force` option can drop an existing table.
 
 ```ruby
-class CreateUsers < ActiveRecord::Migration[7.0]
+class CreateUsers < ActiveRecord::Migration[8.1]
   def change
     create_table :users, force: true do |t|
       # ...
@@ -331,7 +250,7 @@ end
 Create tables without the `force` option.
 
 ```ruby
-class CreateUsers < ActiveRecord::Migration[7.0]
+class CreateUsers < ActiveRecord::Migration[8.1]
   def change
     create_table :users do |t|
       # ...
@@ -342,16 +261,125 @@ end
 
 If you intend to drop an existing table, run `drop_table` first.
 
+### Adding an auto-incrementing column
+
+#### Bad
+
+Adding an auto-incrementing column (`serial`/`bigserial` in Postgres and `AUTO_INCREMENT` in MySQL and MariaDB) causes the entire table to be rewritten. During this time, reads and writes are blocked in Postgres, and writes are blocked in MySQL and MariaDB.
+
+```ruby
+class AddIdToCitiesUsers < ActiveRecord::Migration[8.1]
+  def change
+    add_column :cities_users, :id, :primary_key
+  end
+end
+```
+
+With MySQL and MariaDB, this can also [generate different values on replicas](https://dev.mysql.com/doc/mysql-replication-excerpt/8.0/en/replication-features-auto-increment.html) if using statement-based replication.
+
+#### Good
+
+Create a new table and migrate the data with the same steps as [renaming a table](#renaming-a-table).
+
+### Adding a stored generated column
+
+#### Bad
+
+Adding a stored generated column causes the entire table to be rewritten. During this time, reads and writes are blocked in Postgres, and writes are blocked in MySQL and MariaDB.
+
+```ruby
+class AddSomeColumnToUsers < ActiveRecord::Migration[8.1]
+  def change
+    add_column :users, :some_column, :virtual, type: :string, as: "...", stored: true
+  end
+end
+```
+
+#### Good
+
+Add a non-generated column and use callbacks or triggers instead (or a virtual generated column with MySQL and MariaDB).
+
+### Adding a foreign key
+
+:turtle: Safe by default available for Postgres
+
+#### Bad
+
+Adding a foreign key blocks writes on both tables.
+
+```ruby
+class AddForeignKeyOnUsers < ActiveRecord::Migration[8.1]
+  def change
+    add_foreign_key :users, :orders
+  end
+end
+```
+
+or
+
+```ruby
+class AddReferenceToUsers < ActiveRecord::Migration[8.1]
+  def change
+    add_reference :users, :order, foreign_key: true
+  end
+end
+```
+
+#### Good - Postgres
+
+Add the foreign key without validating existing rows:
+
+```ruby
+class AddForeignKeyOnUsers < ActiveRecord::Migration[8.1]
+  def change
+    add_foreign_key :users, :orders, validate: false
+  end
+end
+```
+
+Then validate them in a separate migration.
+
+```ruby
+class ValidateForeignKeyOnUsers < ActiveRecord::Migration[8.1]
+  def change
+    validate_foreign_key :users, :orders
+  end
+end
+```
+
+#### Good - MySQL and MariaDB
+
+If you are 100% sure all rows are valid and migrations do not use a connection pooler, you can add the foreign key without validating existing rows:
+
+```ruby
+class AddForeignKeyOnUsers < ActiveRecord::Migration[8.1]
+  def up
+    safety_assured do
+      begin
+        execute "SET SESSION foreign_key_checks = 0"
+        add_foreign_key :users, :orders
+      ensure
+        execute "SET SESSION foreign_key_checks = 1"
+      end
+    end
+  end
+
+  def down
+    remove_foreign_key :users, :orders
+  end
+end
+```
+
 ### Adding a check constraint
 
-:turtle: Safe by default available
+:turtle: Safe by default available for Postgres
 
 #### Bad
 
 Adding a check constraint blocks reads and writes in Postgres and blocks writes in MySQL and MariaDB while every row is checked.
 
 ```ruby
-class AddCheckConstraint < ActiveRecord::Migration[7.0]
+class AddCheckConstraint < ActiveRecord::Migration[8.1]
   def change
     add_check_constraint :users, "price > 0", name: "price_check"
   end
@@ -363,7 +391,7 @@ end
 Add the check constraint without validating existing rows:
 
 ```ruby
-class AddCheckConstraint < ActiveRecord::Migration[7.0]
+class AddCheckConstraint < ActiveRecord::Migration[8.1]
   def change
     add_check_constraint :users, "price > 0", name: "price_check", validate: false
   end
@@ -373,7 +401,7 @@ end
 Then validate them in a separate migration.
 
 ```ruby
-class ValidateCheckConstraint < ActiveRecord::Migration[7.0]
+class ValidateCheckConstraint < ActiveRecord::Migration[8.1]
   def change
     validate_check_constraint :users, name: "price_check"
   end
@@ -389,13 +417,53 @@ end
 Strong Migrations can’t ensure safety for raw SQL statements. Make really sure that what you’re doing is safe, then use:
 
 ```ruby
-class ExecuteSQL < ActiveRecord::Migration[7.0]
+class ExecuteSQL < ActiveRecord::Migration[8.1]
   def change
     safety_assured { execute "..." }
   end
 end
 ```
 
+### Backfilling data
+
+Note: Strong Migrations does not detect dangerous backfills.
+
+#### Bad
+
+Active Record creates a transaction around each migration, and backfilling in the same transaction that alters a table keeps the table locked for the [duration of the backfill](https://wework.github.io/data/2015/11/05/add-columns-with-default-values-to-large-tables-in-rails-postgres/).
+
+```ruby
+class AddSomeColumnToUsers < ActiveRecord::Migration[8.1]
+  def change
+    add_column :users, :some_column, :text
+    User.update_all some_column: "default_value"
+  end
+end
+```
+
+Also, running a single query to update data can cause issues for large tables.
+
+#### Good
+
+There are three keys to backfilling safely: batching, throttling, and running it outside a transaction. Use the Rails console or a separate migration with `disable_ddl_transaction!`.
+
+```ruby
+class BackfillSomeColumn < ActiveRecord::Migration[8.1]
+  disable_ddl_transaction!
+
+  def up
+    User.unscoped.in_batches(of: 10000) do |relation|
+      relation.where(some_column: nil).update_all some_column: "default_value"
+      sleep(0.01) # throttle
+    end
+  end
+end
+```
+
+Note: If backfilling with a method other than `update_all`, use `User.reset_column_information` to ensure the model has up-to-date column information.
+
+## Postgres Checks
+
 ### Adding an index non-concurrently
 
 :turtle: Safe by default available
@@ -405,7 +473,7 @@ end
 In Postgres, adding an index non-concurrently blocks writes.
 
 ```ruby
-class AddSomeIndexToUsers < ActiveRecord::Migration[7.0]
+class AddSomeIndexToUsers < ActiveRecord::Migration[8.1]
   def change
     add_index :users, :some_column
   end
@@ -417,7 +485,7 @@ end
 Add indexes concurrently.
 
 ```ruby
-class AddSomeIndexToUsers < ActiveRecord::Migration[7.0]
+class AddSomeIndexToUsers < ActiveRecord::Migration[8.1]
   disable_ddl_transaction!
 
   def change
@@ -443,7 +511,7 @@ rails g index table column
 Rails adds an index non-concurrently to references by default, which blocks writes in Postgres.
 
 ```ruby
-class AddReferenceToUsers < ActiveRecord::Migration[7.0]
+class AddReferenceToUsers < ActiveRecord::Migration[8.1]
   def change
     add_reference :users, :city
   end
@@ -455,7 +523,7 @@ end
 Make sure the index is added concurrently.
 
 ```ruby
-class AddReferenceToUsers < ActiveRecord::Migration[7.0]
+class AddReferenceToUsers < ActiveRecord::Migration[8.1]
   disable_ddl_transaction!
 
   def change
@@ -464,50 +532,35 @@ class AddReferenceToUsers < ActiveRecord::Migration[7.0]
 end
 ```
 
-### Adding a foreign key
-
-:turtle: Safe by default available
+### Adding a unique constraint
 
 #### Bad
 
-In Postgres, adding a foreign key blocks writes on both tables.
+In Postgres, adding a unique constraint creates a unique index, which blocks reads and writes.
 
 ```ruby
-class AddForeignKeyOnUsers < ActiveRecord::Migration[7.0]
+class AddUniqueConstraint < ActiveRecord::Migration[8.1]
   def change
-    add_foreign_key :users, :orders
-  end
-end
-```
-
-or
-
-```ruby
-class AddReferenceToUsers < ActiveRecord::Migration[7.0]
-  def change
-    add_reference :users, :order, foreign_key: true
+    add_unique_constraint :users, :some_column
   end
 end
 ```
 
 #### Good
 
-Add the foreign key without validating existing rows:
+Create a unique index concurrently, then use it for the constraint.
 
 ```ruby
-class AddForeignKeyOnUsers < ActiveRecord::Migration[7.0]
-  def change
-    add_foreign_key :users, :orders, validate: false
-  end
-end
-```
+class AddUniqueConstraint < ActiveRecord::Migration[8.1]
+  disable_ddl_transaction!
 
-Then validate them in a separate migration.
+  def up
+    add_index :users, :some_column, unique: true, algorithm: :concurrently
+    add_unique_constraint :users, using_index: "index_users_on_some_column"
+  end
 
-```ruby
-class ValidateForeignKeyOnUsers < ActiveRecord::Migration[7.0]
-  def change
-    validate_foreign_key :users, :orders
+  def down
+    remove_unique_constraint :users, :some_column
   end
 end
 ```
@@ -519,7 +572,7 @@ end
 In Postgres, adding an exclusion constraint blocks reads and writes while every row is checked.
 
 ```ruby
-class AddExclusionContraint < ActiveRecord::Migration[7.1]
+class AddExclusionConstraint < ActiveRecord::Migration[8.1]
   def change
     add_exclusion_constraint :users, "number WITH =", using: :gist
   end
@@ -537,7 +590,7 @@ end
 In Postgres, there’s no equality operator for the `json` column type, which can cause errors for existing `SELECT DISTINCT` queries in your application.
 
 ```ruby
-class AddPropertiesToUsers < ActiveRecord::Migration[7.0]
+class AddPropertiesToUsers < ActiveRecord::Migration[8.1]
   def change
     add_column :users, :properties, :json
   end
@@ -549,13 +602,46 @@ end
 Use `jsonb` instead.
 
 ```ruby
-class AddPropertiesToUsers < ActiveRecord::Migration[7.0]
+class AddPropertiesToUsers < ActiveRecord::Migration[8.1]
   def change
     add_column :users, :properties, :jsonb
   end
 end
 ```
 
+### Adding a column with a volatile default value
+
+#### Bad
+
+Adding a column with a volatile default value to an existing table causes the entire table to be rewritten. During this time, reads and writes are blocked.
+
+```ruby
+class AddSomeColumnToUsers < ActiveRecord::Migration[8.1]
+  def change
+    add_column :users, :some_column, :uuid, default: "gen_random_uuid()"
+  end
+end
+```
+
+#### Good
+
+Instead, add the column without a default value, then change the default.
+
+```ruby
+class AddSomeColumnToUsers < ActiveRecord::Migration[8.1]
+  def up
+    add_column :users, :some_column, :uuid
+    change_column_default :users, :some_column, "gen_random_uuid()"
+  end
+
+  def down
+    remove_column :users, :some_column
+  end
+end
+```
+
+Then [backfill the data](#backfilling-data).
+
 ### Setting NOT NULL on an existing column
 
 :turtle: Safe by default available
@@ -565,7 +651,7 @@ end
 In Postgres, setting `NOT NULL` on an existing column blocks reads and writes while every row is checked.
 
 ```ruby
-class SetSomeColumnNotNull < ActiveRecord::Migration[7.0]
+class SetSomeColumnNotNull < ActiveRecord::Migration[8.1]
   def change
     change_column_null :users, :some_column, false
   end
@@ -576,92 +662,177 @@ end
 
 Instead, add a check constraint.
 
-For Rails 6.1, use:
-
 ```ruby
-class SetSomeColumnNotNull < ActiveRecord::Migration[7.0]
+class SetSomeColumnNotNull < ActiveRecord::Migration[8.1]
   def change
     add_check_constraint :users, "some_column IS NOT NULL", name: "users_some_column_null", validate: false
   end
 end
 ```
 
-For Rails < 6.1, use:
+Then validate it in a separate migration. Once the check constraint is validated, you can safely set `NOT NULL` on the column and drop the check constraint.
 
 ```ruby
-class SetSomeColumnNotNull < ActiveRecord::Migration[6.0]
-  def change
-    safety_assured do
-      execute 'ALTER TABLE "users" ADD CONSTRAINT "users_some_column_null" CHECK ("some_column" IS NOT NULL) NOT VALID'
-    end
+class ValidateSomeColumnNotNull < ActiveRecord::Migration[8.1]
+  def up
+    validate_check_constraint :users, name: "users_some_column_null"
+    change_column_null :users, :some_column, false
+    remove_check_constraint :users, name: "users_some_column_null"
+  end
+
+  def down
+    add_check_constraint :users, "some_column IS NOT NULL", name: "users_some_column_null", validate: false
+    change_column_null :users, :some_column, true
   end
 end
 ```
 
-Then validate it in a separate migration. A `NOT NULL` check constraint is [functionally equivalent](https://medium.com/doctolib/adding-a-not-null-constraint-on-pg-faster-with-minimal-locking-38b2c00c4d1c) to setting `NOT NULL` on the column (but it won’t show up in `schema.rb` in Rails < 6.1). In Postgres 12+, once the check constraint is validated, you can safely set `NOT NULL` on the column and drop the check constraint.
+### Renaming an enum value
+
+#### Bad
 
-For Rails 6.1, use:
+Renaming an enum value that’s in use will cause errors in your application.
 
 ```ruby
-class ValidateSomeColumnNotNull < ActiveRecord::Migration[7.0]
+class RenameDoneToCompleted < ActiveRecord::Migration[8.1]
   def change
-    validate_check_constraint :users, name: "users_some_column_null"
+    rename_enum_value :status, from: "done", to: "completed"
+  end
+end
+```
 
-    # in Postgres 12+, you can then safely set NOT NULL on the column
-    change_column_null :users, :some_column, false
-    remove_check_constraint :users, name: "users_some_column_null"
+#### Good
+
+A safer approach is to:
+
+1. Add a new enum value before or after the old value
+2. Update application code to handle both values and write the new value
+3. Backfill data from the old value to the new value
+
+```ruby
+class AddCompletedToStatus < ActiveRecord::Migration[8.1]
+  def up
+    add_enum_value :status, "completed", after: "done"
   end
 end
 ```
 
-For Rails < 6.1, use:
+Removing enum values is not supported in Postgres (without creating a new enum).
+
+### Renaming a schema
+
+#### Bad
+
+Renaming a schema that’s in use will cause errors in your application.
 
 ```ruby
-class ValidateSomeColumnNotNull < ActiveRecord::Migration[6.0]
+class RenameUsersToCustomers < ActiveRecord::Migration[8.1]
   def change
-    safety_assured do
-      execute 'ALTER TABLE "users" VALIDATE CONSTRAINT "users_some_column_null"'
-    end
-
-    # in Postgres 12+, you can then safely set NOT NULL on the column
-    change_column_null :users, :some_column, false
-    safety_assured do
-      execute 'ALTER TABLE "users" DROP CONSTRAINT "users_some_column_null"'
-    end
+    rename_schema :users, :customers
   end
 end
 ```
 
-### Changing the default value of a column
+#### Good
+
+A safer approach is to:
+
+1. Create a new schema
+2. Write to both schemas
+3. Backfill data from the old schema to the new schema
+4. Move reads from the old schema to the new schema
+5. Stop writing to the old schema
+6. Drop the old schema
+
+## MySQL and MariaDB Checks
+
+### Using the COPY algorithm
 
 #### Bad
 
-Rails < 7 enables partial writes by default, which can cause incorrect values to be inserted when changing the default value of a column.
+In MySQL and MariaDB, using the `COPY` algorithm blocks writes.
 
 ```ruby
-class ChangeSomeColumnDefault < ActiveRecord::Migration[6.1]
+class AddSomeIndexToUsers < ActiveRecord::Migration[8.1]
   def change
-    change_column_default :users, :some_column, from: "old", to: "new"
+    add_index :users, :some_column, algorithm: :copy
   end
 end
+```
 
-User.create!(some_column: "old") # can insert "new"
+#### Good
+
+Use the default algorithm.
+
+```ruby
+class AddSomeIndexToUsers < ActiveRecord::Migration[8.1]
+  def change
+    add_index :users, :some_column
+  end
+end
+```
+
+### Using shared or exclusive locking
+
+#### Bad
+
+In MySQL and MariaDB, using shared locking blocks writes, and using exclusive locking blocks reads and writes.
+
+```ruby
+class AddSomeIndexToUsers < ActiveRecord::Migration[8.2]
+  def change
+    add_index :users, :some_column, lock: :shared
+  end
+end
 ```
 
 #### Good
 
-Disable partial writes in `config/application.rb`. For Rails < 7, use:
+Use the default locking or no locking.
 
 ```ruby
-config.active_record.partial_writes = false
+class AddSomeIndexToUsers < ActiveRecord::Migration[8.2]
+  def change
+    add_index :users, :some_column
+  end
+end
 ```
 
-For Rails 7, use:
+### Adding a column with an expression default value
+
+#### Bad
+
+In MySQL and MariaDB, adding a column with an expression default value to an existing table causes the entire table to be rewritten. During this time, writes are blocked.
+
+```ruby
+class AddSomeColumnToUsers < ActiveRecord::Migration[8.1]
+  def change
+    add_column :users, :some_column, :datetime, default: -> { "(now())" }
+  end
+end
+```
+
+#### Good
+
+Instead, add the column without a default value, then change the default.
 
 ```ruby
-config.active_record.partial_inserts = false
+class AddSomeColumnToUsers < ActiveRecord::Migration[8.1]
+  def up
+    add_column :users, :some_column, :datetime
+    change_column_default :users, :some_column, -> { "(now())" }
+  end
+
+  def down
+    remove_column :users, :some_column
+  end
+end
 ```
 
+Then [backfill the data](#backfilling-data).
+
+## Best Practices
+
 ### Keeping non-unique indexes to three columns or less
 
 #### Bad
@@ -669,7 +840,7 @@ config.active_record.partial_inserts = false
 Adding a non-unique index with more than three columns rarely improves performance.
 
 ```ruby
-class AddSomeIndexToUsers < ActiveRecord::Migration[7.0]
+class AddSomeIndexToUsers < ActiveRecord::Migration[8.1]
   def change
     add_index :users, [:a, :b, :c, :d]
   end
@@ -681,9 +852,9 @@ end
 Instead, start an index with columns that narrow down the results the most.
 
 ```ruby
-class AddSomeIndexToUsers < ActiveRecord::Migration[7.0]
+class AddSomeIndexToUsers < ActiveRecord::Migration[8.1]
   def change
-    add_index :users, [:b, :d]
+    add_index :users, [:d, :b]
   end
 end
 ```
@@ -695,7 +866,7 @@ For Postgres, be sure to add them concurrently.
 To mark a step in the migration as safe, despite using a method that might otherwise be dangerous, wrap it in a `safety_assured` block.
 
 ```ruby
-class MySafeMigration < ActiveRecord::Migration[7.0]
+class MySafeMigration < ActiveRecord::Migration[8.1]
   def change
     safety_assured { remove_column :users, :some_column }
   end
@@ -706,7 +877,7 @@ Certain methods like `execute` and `change_table` cannot be inspected and are pr
 
 ## Safe by Default
 
-Make operations safe by default.
+Make certain operations safe by default. This allows you to write the code under the "Bad" section, but the migration will be performed as if you had written the "Good" version.
 
 - adding and removing an index
 - adding a foreign key
@@ -755,6 +926,16 @@ StrongMigrations.disable_check(:add_index)
 
 Check the [source code](https://github.com/ankane/strong_migrations/blob/master/lib/strong_migrations/error_messages.rb) for the list of keys.
 
+## Skip Databases
+
+Skip checks and other functionality for specific databases with:
+
+```ruby
+StrongMigrations.skip_database(:catalog)
+```
+
+Note: This does not affect `alphabetize_schema`.
+
 ## Down Migrations / Rollbacks
 
 By default, checks are disabled when migrating down. Enable them with:
@@ -791,26 +972,7 @@ ALTER ROLE myuser SET lock_timeout = '10s';
 ALTER ROLE myuser SET statement_timeout = '1h';
 ```
 
-Note: If you use PgBouncer in transaction mode, you must set timeouts on the database user.
-
-## Lock Timeout Retries [experimental]
-
-There’s the option to automatically retry statements when the lock timeout is reached. Here’s how it works:
-
-- If a lock timeout happens outside a transaction, the statement is retried
-- If it happens inside the DDL transaction, the entire migration is retried (only applicable to Postgres)
-
-Add to `config/initializers/strong_migrations.rb`:
-
-```ruby
-StrongMigrations.lock_timeout_retries = 3
-```
-
-Set the delay between retries with:
-
-```ruby
-StrongMigrations.lock_timeout_retry_delay = 10.seconds
-```
+Note: If you use a connection pooler like PgBouncer in transaction mode, you must set timeouts on the database user.
 
 ## App Timeouts
 
@@ -826,7 +988,7 @@ production:
     lock_timeout: 10s
 ```
 
-Note: If you use PgBouncer in transaction mode, you must set the statement and lock timeouts on the database user as shown above.
+Note: If you use a connection pooler like PgBouncer in transaction mode, you must set the statement and lock timeouts on the database user as shown above.
 
 For MySQL:
 
@@ -855,12 +1017,43 @@ production:
 
 For HTTP connections, Redis, and other services, check out [this guide](https://github.com/ankane/the-ultimate-guide-to-ruby-timeouts).
 
+## Invalid Indexes
+
+In Postgres, adding an index non-concurrently can leave behind an invalid index if the lock timeout is reached. Running the migration again can result in an error.
+
+To automatically remove the invalid index when the migration runs again, use:
+
+```ruby
+StrongMigrations.remove_invalid_indexes = true
+```
+
+## Lock Timeout Retries
+
+Note: This feature is experimental.
+
+There’s the option to automatically retry statements for migrations when the lock timeout is reached. Here’s how it works:
+
+- If a lock timeout happens outside a transaction, the statement is retried
+- If it happens inside the DDL transaction, the entire migration is retried (only applicable to Postgres)
+
+Add to `config/initializers/strong_migrations.rb`:
+
+```ruby
+StrongMigrations.lock_timeout_retries = 3
+```
+
+Set the delay between retries with:
+
+```ruby
+StrongMigrations.lock_timeout_retry_delay = 10.seconds
+```
+
 ## Existing Migrations
 
 To mark migrations as safe that were created before installing this gem, create an initializer with:
 
 ```ruby
-StrongMigrations.start_after = 20170101000000
+StrongMigrations.start_after = 20250101000000
 ```
 
 Use the version from your latest migration.
@@ -870,17 +1063,17 @@ Use the version from your latest migration.
 If your development database version is different from production, you can specify the production version so the right checks run in development.
 
 ```ruby
-StrongMigrations.target_version = 10 # or "8.0.12", "10.3.2", etc
+StrongMigrations.target_version = 16
 ```
 
-The major version works well for Postgres, while the full version is recommended for MySQL and MariaDB.
+The major version works well for Postgres, while the major and minor version is recommended for MySQL and MariaDB.
 
 For safety, this option only affects development and test environments. In other environments, the actual server version is always used.
 
-If your app has multiple databases with different versions, with Rails 6.1+, you can use:
+If your app has multiple databases with different versions, you can use:
 
 ```ruby
-StrongMigrations.target_version = {primary: 13, catalog: 15}
+StrongMigrations.target_version = {primary: 16, catalog: 18}
 ```
 
 ## Analyze Tables
@@ -893,15 +1086,20 @@ StrongMigrations.auto_analyze = true
 
 ## Faster Migrations
 
-Only dump the schema when adding a new migration. If you use Git, add to `config/environments/development.rb`:
+Only dump the schema when adding a new migration. If you use Git, add to the end of your `Rakefile`:
 
 ```rb
-config.active_record.dump_schema_after_migration = `git status db/migrate/ --porcelain`.present?
+task :faster_migrations do
+  ActiveRecord.dump_schema_after_migration = Rails.env.development? &&
+    `git status db/migrate/ --porcelain`.present?
+end
+
+task "db:migrate" => "faster_migrations"
 ```
 
 ## Schema Sanity
 
-Columns can flip order in `db/schema.rb` when you have multiple developers. One way to prevent this is to [alphabetize them](https://www.pgrs.net/2008/03/12/alphabetize-schema-rb-columns/). Add to `config/initializers/strong_migrations.rb`:
+With Active Record < 8.1, columns can flip order in `db/schema.rb` when you have multiple developers. One way to prevent this is to [alphabetize them](https://www.pgrs.net/2008/03/12/alphabetize-schema-rb-columns/). Add to `config/initializers/strong_migrations.rb`:
 
 ```ruby
 StrongMigrations.alphabetize_schema = true
@@ -917,15 +1115,18 @@ You probably don’t need this gem for smaller projects, as operations that are
 
 ## Additional Reading
 
-- [Rails Migrations with No Downtime](https://pedro.herokuapp.com/past/2011/7/13/rails_migrations_with_no_downtime/)
 - [PostgreSQL at Scale: Database Schema Changes Without Downtime](https://medium.com/braintree-product-technology/postgresql-at-scale-database-schema-changes-without-downtime-20d3749ed680)
-- [An Overview of DDL Algorithms in MySQL](https://mydbops.wordpress.com/2020/03/04/an-overview-of-ddl-algorithms-in-mysql-covers-mysql-8/)
+- [MySQL InnoDB Online DDL Operations](https://dev.mysql.com/doc/refman/en/innodb-online-ddl-operations.html)
 - [MariaDB InnoDB Online DDL Overview](https://mariadb.com/kb/en/innodb-online-ddl-overview/)
 
 ## Credits
 
 Thanks to Bob Remeika and David Waller for the [original code](https://github.com/foobarfighter/safe-migrations) and [Sean Huber](https://github.com/LendingHome/zero_downtime_migrations) for the bad/good readme format.
 
+## History
+
+View the [changelog](https://github.com/ankane/strong_migrations/blob/master/CHANGELOG.md)
+
 ## Contributing
 
 Everyone is encouraged to help improve this project. Here are a few ways you can help: