strong_migrations 0.6.8 → 1.6.1

data/README.md

@@ -4,18 +4,18 @@ Catch unsafe migrations in development
 
 &nbsp;&nbsp;✓&nbsp;&nbsp;Detects potentially dangerous operations<br />&nbsp;&nbsp;✓&nbsp;&nbsp;Prevents them from running by default<br />&nbsp;&nbsp;✓&nbsp;&nbsp;Provides instructions on safer ways to do what you want
 
-Supports for PostgreSQL, MySQL, and MariaDB
+Supports PostgreSQL, MySQL, and MariaDB
 
 :tangerine: Battle-tested at [Instacart](https://www.instacart.com/opensource)
 
-[![Build Status](https://travis-ci.org/ankane/strong_migrations.svg?branch=master)](https://travis-ci.org/ankane/strong_migrations)
+[![Build Status](https://github.com/ankane/strong_migrations/workflows/build/badge.svg?branch=master)](https://github.com/ankane/strong_migrations/actions)
 
 ## Installation
 
 Add this line to your application’s Gemfile:
 
 ```ruby
-gem 'strong_migrations'
+gem "strong_migrations"
 ```
 
 And run:
@@ -25,6 +25,36 @@ bundle install
 rails generate strong_migrations:install
 ```
 
+Strong Migrations sets a long statement timeout for migrations so you can set a [short statement timeout](#app-timeouts) for your application.
+
+## How It Works
+
+When you run a migration that’s potentially dangerous, you’ll see an error message like:
+
+```txt
+=== Dangerous operation detected #strong_migrations ===
+
+Active Record caches attributes, which causes problems
+when removing columns. Be sure to ignore the column:
+
+class User < ApplicationRecord
+  self.ignored_columns = ["name"]
+end
+
+Deploy the code, then wrap this step in a safety_assured { ... } block.
+
+class RemoveColumn < ActiveRecord::Migration[7.0]
+  def change
+    safety_assured { remove_column :users, :name }
+  end
+end
+```
+
+An operation is classified as dangerous if it either:
+
+- Blocks reads or writes for more than a few seconds (after a lock is acquired)
+- Has a good chance of causing application errors
+
 ## Checks
 
 Potentially dangerous operations:
@@ -32,11 +62,12 @@ 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)
-- [changing the type of a column](#renaming-or-changing-the-type-of-a-column)
-- [renaming a column](#renaming-or-changing-the-type-of-a-column)
+- [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)
-- [using change_column_null with a default value](#using-change_column_null-with-a-default-value)
+- [adding a check constraint](#adding-a-check-constraint)
 - [executing SQL directly](#executing-SQL-directly)
 
 Postgres-specific checks:
@@ -44,9 +75,14 @@ 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 an exclusion constraint](#adding-an-exclusion-constraint)
 - [adding a json column](#adding-a-json-column)
 - [setting NOT NULL on an existing column](#setting-not-null-on-an-existing-column)
 
+Config-specific checks:
+
+- [changing the default value of a column](#changing-the-default-value-of-a-column)
+
 Best practices:
 
 - [keeping non-unique indexes to three columns or less](#keeping-non-unique-indexes-to-three-columns-or-less)
@@ -57,10 +93,10 @@ You can also add [custom checks](#custom-checks) or [disable specific checks](#d
 
 #### Bad
 
-ActiveRecord caches database columns at runtime, so if you drop a column, it can cause exceptions until your app reboots.
+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[6.0]
+class RemoveSomeColumnFromUsers < ActiveRecord::Migration[7.0]
   def change
     remove_column :users, :some_column
   end
@@ -69,7 +105,7 @@ end
 
 #### Good
 
-1. Tell ActiveRecord to ignore the column from its cache
+1. Tell Active Record to ignore the column from its cache
 
   ```ruby
   class User < ApplicationRecord
@@ -77,41 +113,42 @@ end
   end
   ```
 
-2. Deploy code
+2. Deploy the code
 3. Write a migration to remove the column (wrap in `safety_assured` block)
 
   ```ruby
-  class RemoveSomeColumnFromUsers < ActiveRecord::Migration[6.0]
+  class RemoveSomeColumnFromUsers < ActiveRecord::Migration[7.0]
     def change
       safety_assured { remove_column :users, :some_column }
     end
   end
   ```
 
-4. Deploy and run migration
+4. Deploy and run the migration
+5. Remove the line added in step 1
 
 ### Adding a column with a default value
 
-Note: This operation is safe in Postgres 11+, MySQL 8.0.12+, and MariaDB 10.3.2+.
-
 #### Bad
 
-Adding a column with a default value to an existing table causes the entire table to be rewritten.
+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[6.0]
+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[6.0]
+class AddSomeColumnToUsers < ActiveRecord::Migration[7.0]
   def up
     add_column :users, :some_column, :text
     change_column_default :users, :some_column, "default_value"
@@ -129,10 +166,10 @@ See the next section for how to backfill.
 
 #### Bad
 
-Backfilling in the same transaction that alters a table locks the table 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/).
+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[6.0]
+class AddSomeColumnToUsers < ActiveRecord::Migration[7.0]
   def change
     add_column :users, :some_column, :text
     User.update_all some_column: "default_value"
@@ -147,7 +184,7 @@ Also, running a single query to update data can cause issues for large tables.
 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[6.0]
+class BackfillSomeColumn < ActiveRecord::Migration[7.0]
   disable_ddl_transaction!
 
   def up
@@ -159,39 +196,83 @@ class BackfillSomeColumn < ActiveRecord::Migration[6.0]
 end
 ```
 
-### Renaming or changing the type of a column
+### 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 RenameSomeColumn < ActiveRecord::Migration[6.0]
+class AddSomeColumnToUsers < ActiveRecord::Migration[7.0]
   def change
-    rename_column :users, :some_column, :new_name
+    add_column :users, :some_column, :virtual, type: :string, as: "...", stored: true
   end
 end
 ```
 
-or
+#### 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
+
+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[6.0]
+class ChangeSomeColumnType < ActiveRecord::Migration[7.0]
   def change
     change_column :users, :some_column, :new_type
   end
 end
 ```
 
-A few changes are safe in Postgres:
+Some changes don’t require a table rewrite and are safe in Postgres:
 
-- Changing between `varchar` and `text` columns
-- Increasing the precision of a `decimal` or `numeric` column
-- Making a `decimal` or `numeric` column unconstrained
-- Changing between `timestamp` and `timestamptz` columns when session time zone is UTC in Postgres 12+
+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+
+`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+
 
-And a few in MySQL and MariaDB:
+And some in MySQL and MariaDB:
 
-- Increasing the length of a `varchar` column from under 255 up to 255
-- Increasing the length of a `varchar` column over 255
+Type | Safe Changes
+--- | ---
+`string` | Increasing `:limit` from under 63 up to 63, increasing `:limit` from over 63 to the max (the threshold can be different if using an encoding other than `utf8mb4` - for instance, it’s 85 for `utf8mb3` and 255 for `latin1`)
+
+#### Good
+
+A safer approach is to:
+
+1. Create a new column
+2. Write to both columns
+3. Backfill data from the old column to the new column
+4. Move reads from the old column to the new column
+5. Stop writing to the old column
+6. Drop the old column
+
+### Renaming a column
+
+#### Bad
+
+Renaming a column that’s in use will cause errors in your application.
+
+```ruby
+class RenameSomeColumn < ActiveRecord::Migration[7.0]
+  def change
+    rename_column :users, :some_column, :new_name
+  end
+end
+```
 
 #### Good
 
@@ -208,8 +289,10 @@ A safer approach is to:
 
 #### Bad
 
+Renaming a table that’s in use will cause errors in your application.
+
 ```ruby
-class RenameUsersToCustomers < ActiveRecord::Migration[6.0]
+class RenameUsersToCustomers < ActiveRecord::Migration[7.0]
   def change
     rename_table :users, :customers
   end
@@ -234,7 +317,7 @@ A safer approach is to:
 The `force` option can drop an existing table.
 
 ```ruby
-class CreateUsers < ActiveRecord::Migration[6.0]
+class CreateUsers < ActiveRecord::Migration[7.0]
   def change
     create_table :users, force: true do |t|
       # ...
@@ -248,7 +331,7 @@ end
 Create tables without the `force` option.
 
 ```ruby
-class CreateUsers < ActiveRecord::Migration[6.0]
+class CreateUsers < ActiveRecord::Migration[7.0]
   def change
     create_table :users do |t|
       # ...
@@ -259,40 +342,54 @@ end
 
 If you intend to drop an existing table, run `drop_table` first.
 
-### Using change_column_null with a default value
+### Adding a check constraint
+
+:turtle: Safe by default available
 
 #### Bad
 
-This generates a single `UPDATE` statement to set the default value.
+Adding a check constraint blocks reads and writes in Postgres and blocks writes in MySQL and MariaDB while every row is checked.
 
 ```ruby
-class ChangeSomeColumnNull < ActiveRecord::Migration[6.0]
+class AddCheckConstraint < ActiveRecord::Migration[7.0]
   def change
-    change_column_null :users, :some_column, false, "default_value"
+    add_check_constraint :users, "price > 0", name: "price_check"
   end
 end
 ```
 
-#### Good
+#### Good - Postgres
 
-Backfill the column [safely](#backfilling-data). Then use:
+Add the check constraint without validating existing rows:
 
 ```ruby
-class ChangeSomeColumnNull < ActiveRecord::Migration[6.0]
+class AddCheckConstraint < ActiveRecord::Migration[7.0]
   def change
-    change_column_null :users, :some_column, false
+    add_check_constraint :users, "price > 0", name: "price_check", validate: false
   end
 end
 ```
 
-Note: In Postgres, `change_column_null` is still [not safe](#setting-not-null-on-an-existing-column) with this method.
+Then validate them in a separate migration.
+
+```ruby
+class ValidateCheckConstraint < ActiveRecord::Migration[7.0]
+  def change
+    validate_check_constraint :users, name: "price_check"
+  end
+end
+```
+
+#### Good - MySQL and MariaDB
+
+[Let us know](https://github.com/ankane/strong_migrations/issues/new) if you have a safe way to do this (check constraints can be added with `NOT ENFORCED`, but enforcing blocks writes).
 
 ### Executing SQL directly
 
 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[6.0]
+class ExecuteSQL < ActiveRecord::Migration[7.0]
   def change
     safety_assured { execute "..." }
   end
@@ -301,12 +398,14 @@ end
 
 ### Adding an index non-concurrently
 
+:turtle: Safe by default available
+
 #### Bad
 
-In Postgres, adding an index non-concurrently locks the table.
+In Postgres, adding an index non-concurrently blocks writes.
 
 ```ruby
-class AddSomeIndexToUsers < ActiveRecord::Migration[6.0]
+class AddSomeIndexToUsers < ActiveRecord::Migration[7.0]
   def change
     add_index :users, :some_column
   end
@@ -318,7 +417,7 @@ end
 Add indexes concurrently.
 
 ```ruby
-class AddSomeIndexToUsers < ActiveRecord::Migration[6.0]
+class AddSomeIndexToUsers < ActiveRecord::Migration[7.0]
   disable_ddl_transaction!
 
   def change
@@ -337,12 +436,14 @@ rails g index table column
 
 ### Adding a reference
 
+:turtle: Safe by default available
+
 #### Bad
 
-Rails adds an index non-concurrently to references by default, which is problematic for Postgres.
+Rails adds an index non-concurrently to references by default, which blocks writes in Postgres.
 
 ```ruby
-class AddReferenceToUsers < ActiveRecord::Migration[6.0]
+class AddReferenceToUsers < ActiveRecord::Migration[7.0]
   def change
     add_reference :users, :city
   end
@@ -354,7 +455,7 @@ end
 Make sure the index is added concurrently.
 
 ```ruby
-class AddReferenceToUsers < ActiveRecord::Migration[6.0]
+class AddReferenceToUsers < ActiveRecord::Migration[7.0]
   disable_ddl_transaction!
 
   def change
@@ -365,12 +466,14 @@ end
 
 ### Adding a foreign key
 
+:turtle: Safe by default available
+
 #### Bad
 
-In Postgres, new foreign keys are validated by default, which acquires a `ShareRowExclusiveLock` that can be [expensive on large tables](https://travisofthenorth.com/blog/2017/2/2/postgres-adding-foreign-keys-with-zero-downtime).
+In Postgres, adding a foreign key blocks writes on both tables.
 
 ```ruby
-class AddForeignKeyOnUsers < ActiveRecord::Migration[6.0]
+class AddForeignKeyOnUsers < ActiveRecord::Migration[7.0]
   def change
     add_foreign_key :users, :orders
   end
@@ -380,7 +483,7 @@ end
 or
 
 ```ruby
-class AddReferenceToUsers < ActiveRecord::Migration[6.0]
+class AddReferenceToUsers < ActiveRecord::Migration[7.0]
   def change
     add_reference :users, :order, foreign_key: true
   end
@@ -389,60 +492,52 @@ end
 
 #### Good
 
-Instead, validate it in a separate migration with a more agreeable `RowShareLock`. This approach is documented by Postgres to have “[the least impact on other work](https://www.postgresql.org/docs/current/sql-altertable.html).”
-
-For Rails 5.2+, use:
+Add the foreign key without validating existing rows:
 
 ```ruby
-class AddForeignKeyOnUsers < ActiveRecord::Migration[6.0]
+class AddForeignKeyOnUsers < ActiveRecord::Migration[7.0]
   def change
     add_foreign_key :users, :orders, validate: false
   end
 end
 ```
 
-Then validate it in a separate migration.
+Then validate them in a separate migration.
 
 ```ruby
-class ValidateForeignKeyOnUsers < ActiveRecord::Migration[6.0]
+class ValidateForeignKeyOnUsers < ActiveRecord::Migration[7.0]
   def change
     validate_foreign_key :users, :orders
   end
 end
 ```
 
-For Rails < 5.2, use:
+### Adding an exclusion constraint
 
-```ruby
-class AddForeignKeyOnUsers < ActiveRecord::Migration[5.1]
-  def change
-    safety_assured do
-      execute 'ALTER TABLE "users" ADD CONSTRAINT "fk_rails_c1e9b98e31" FOREIGN KEY ("order_id") REFERENCES "orders" ("id") NOT VALID'
-    end
-  end
-end
-```
+#### Bad
 
-Then validate it in a separate migration.
+In Postgres, adding an exclusion constraint blocks reads and writes while every row is checked.
 
 ```ruby
-class ValidateForeignKeyOnUsers < ActiveRecord::Migration[5.1]
+class AddExclusionContraint < ActiveRecord::Migration[7.1]
   def change
-    safety_assured do
-      execute 'ALTER TABLE "users" VALIDATE CONSTRAINT "fk_rails_c1e9b98e31"'
-    end
+    add_exclusion_constraint :users, "number WITH =", using: :gist
   end
 end
 ```
 
+#### Good
+
+[Let us know](https://github.com/ankane/strong_migrations/issues/new) if you have a safe way to do this (exclusion constraints cannot be marked `NOT VALID`).
+
 ### Adding a json column
 
 #### Bad
 
-In Postgres, there’s no equality operator for the `json` column type, which can cause errors for existing `SELECT DISTINCT` queries.
+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[6.0]
+class AddPropertiesToUsers < ActiveRecord::Migration[7.0]
   def change
     add_column :users, :properties, :json
   end
@@ -454,7 +549,7 @@ end
 Use `jsonb` instead.
 
 ```ruby
-class AddPropertiesToUsers < ActiveRecord::Migration[6.0]
+class AddPropertiesToUsers < ActiveRecord::Migration[7.0]
   def change
     add_column :users, :properties, :jsonb
   end
@@ -463,12 +558,14 @@ end
 
 ### Setting NOT NULL on an existing column
 
+:turtle: Safe by default available
+
 #### Bad
 
-In Postgres, setting `NOT NULL` on an existing column requires an `AccessExclusiveLock`, which is expensive on large tables.
+In Postgres, setting `NOT NULL` on an existing column blocks reads and writes while every row is checked.
 
 ```ruby
-class SetSomeColumnNotNull < ActiveRecord::Migration[6.0]
+class SetSomeColumnNotNull < ActiveRecord::Migration[7.0]
   def change
     change_column_null :users, :some_column, false
   end
@@ -477,7 +574,19 @@ end
 
 #### Good
 
-Instead, add a constraint:
+Instead, add a check constraint.
+
+For Rails 6.1, use:
+
+```ruby
+class SetSomeColumnNotNull < ActiveRecord::Migration[7.0]
+  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:
 
 ```ruby
 class SetSomeColumnNotNull < ActiveRecord::Migration[6.0]
@@ -489,7 +598,23 @@ class SetSomeColumnNotNull < ActiveRecord::Migration[6.0]
 end
 ```
 
-Then validate it in a separate migration.
+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.
+
+For Rails 6.1, use:
+
+```ruby
+class ValidateSomeColumnNotNull < ActiveRecord::Migration[7.0]
+  def change
+    validate_check_constraint :users, name: "users_some_column_null"
+
+    # 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"
+  end
+end
+```
+
+For Rails < 6.1, use:
 
 ```ruby
 class ValidateSomeColumnNotNull < ActiveRecord::Migration[6.0]
@@ -498,7 +623,7 @@ class ValidateSomeColumnNotNull < ActiveRecord::Migration[6.0]
       execute 'ALTER TABLE "users" VALIDATE CONSTRAINT "users_some_column_null"'
     end
 
-    # in Postgres 12+, you can safely turn this into a traditional column constraint
+    # 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"'
@@ -507,7 +632,35 @@ class ValidateSomeColumnNotNull < ActiveRecord::Migration[6.0]
 end
 ```
 
-Note: This is not 100% the same as `NOT NULL` column constraint before Postgres 12. Here’s a [good explanation](https://medium.com/doctolib/adding-a-not-null-constraint-on-pg-faster-with-minimal-locking-38b2c00c4d1c).
+### Changing the default value of a column
+
+#### Bad
+
+Rails < 7 enables partial writes by default, which can cause incorrect values to be inserted when changing the default value of a column.
+
+```ruby
+class ChangeSomeColumnDefault < ActiveRecord::Migration[6.1]
+  def change
+    change_column_default :users, :some_column, from: "old", to: "new"
+  end
+end
+
+User.create!(some_column: "old") # can insert "new"
+```
+
+#### Good
+
+Disable partial writes in `config/application.rb`. For Rails < 7, use:
+
+```ruby
+config.active_record.partial_writes = false
+```
+
+For Rails 7, use:
+
+```ruby
+config.active_record.partial_inserts = false
+```
 
 ### Keeping non-unique indexes to three columns or less
 
@@ -516,7 +669,7 @@ Note: This is not 100% the same as `NOT NULL` column constraint before Postgres
 Adding a non-unique index with more than three columns rarely improves performance.
 
 ```ruby
-class AddSomeIndexToUsers < ActiveRecord::Migration[6.0]
+class AddSomeIndexToUsers < ActiveRecord::Migration[7.0]
   def change
     add_index :users, [:a, :b, :c, :d]
   end
@@ -528,7 +681,7 @@ end
 Instead, start an index with columns that narrow down the results the most.
 
 ```ruby
-class AddSomeIndexToUsers < ActiveRecord::Migration[6.0]
+class AddSomeIndexToUsers < ActiveRecord::Migration[7.0]
   def change
     add_index :users, [:b, :d]
   end
@@ -542,7 +695,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[6.0]
+class MySafeMigration < ActiveRecord::Migration[7.0]
   def change
     safety_assured { remove_column :users, :some_column }
   end
@@ -551,6 +704,21 @@ end
 
 Certain methods like `execute` and `change_table` cannot be inspected and are prevented from running by default. Make sure what you’re doing is really safe and use this pattern.
 
+## Safe by Default
+
+Make operations safe by default.
+
+- adding and removing an index
+- adding a foreign key
+- adding a check constraint
+- setting NOT NULL on an existing column
+
+Add to `config/initializers/strong_migrations.rb`:
+
+```ruby
+StrongMigrations.safe_by_default = true
+```
+
 ## Custom Checks
 
 Add your own custom checks with:
@@ -585,7 +753,15 @@ Disable specific checks with:
 StrongMigrations.disable_check(:add_index)
 ```
 
-Check the [source code](https://github.com/ankane/strong_migrations/blob/master/lib/strong_migrations.rb) for the list of keys.
+Check the [source code](https://github.com/ankane/strong_migrations/blob/master/lib/strong_migrations/error_messages.rb) for the list of keys.
+
+## Down Migrations / Rollbacks
+
+By default, checks are disabled when migrating down. Enable them with:
+
+```ruby
+StrongMigrations.check_down = true
+```
 
 ## Custom Messages
 
@@ -595,9 +771,9 @@ To customize specific messages, create an initializer with:
 StrongMigrations.error_messages[:add_column_default] = "Your custom instructions"
 ```
 
-Check the [source code](https://github.com/ankane/strong_migrations/blob/master/lib/strong_migrations.rb) for the list of keys.
+Check the [source code](https://github.com/ankane/strong_migrations/blob/master/lib/strong_migrations/error_messages.rb) for the list of keys.
 
-## Timeouts
+## Migration Timeouts
 
 It’s extremely important to set a short lock timeout for migrations. This way, if a migration can’t acquire a lock in a timely manner, other statements won’t be stuck behind it. We also recommend setting a long statement timeout so migrations can run for a while.
 
@@ -617,6 +793,68 @@ 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
+```
+
+## App Timeouts
+
+We recommend adding timeouts to `config/database.yml` to prevent connections from hanging and individual queries from taking up too many resources in controllers, jobs, the Rails console, and other places.
+
+For Postgres:
+
+```yml
+production:
+  connect_timeout: 5
+  variables:
+    statement_timeout: 15s
+    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.
+
+For MySQL:
+
+```yml
+production:
+  connect_timeout: 5
+  read_timeout: 5
+  write_timeout: 5
+  variables:
+    max_execution_time: 15000 # ms
+    lock_wait_timeout: 10 # sec
+
+```
+
+For MariaDB:
+
+```yml
+production:
+  connect_timeout: 5
+  read_timeout: 5
+  write_timeout: 5
+  variables:
+    max_statement_time: 15 # sec
+    lock_wait_timeout: 10 # sec
+```
+
+For HTTP connections, Redis, and other services, check out [this guide](https://github.com/ankane/the-ultimate-guide-to-ruby-timeouts).
+
 ## Existing Migrations
 
 To mark migrations as safe that were created before installing this gem, create an initializer with:
@@ -632,13 +870,19 @@ 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_postgresql_version = "10"
-StrongMigrations.target_mysql_version = "8.0.12"
-StrongMigrations.target_mariadb_version = "10.3.2"
+StrongMigrations.target_version = 10 # or "8.0.12", "10.3.2", etc
 ```
 
+The major version works well for Postgres, while the full 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:
+
+```ruby
+StrongMigrations.target_version = {primary: 13, catalog: 15}
+```
+
 ## Analyze Tables
 
 Analyze tables automatically (to update planner statistics) after an index is added. Create an initializer with:
@@ -649,37 +893,34 @@ StrongMigrations.auto_analyze = true
 
 ## Faster Migrations
 
-Only dump the schema when adding a new migration. If you use Git, create an initializer with:
+Only dump the schema when adding a new migration. If you use Git, add to `config/environments/development.rb`:
 
-```ruby
-ActiveRecord::Base.dump_schema_after_migration = Rails.env.development? &&
-  `git status db/migrate/ --porcelain`.present?
+```rb
+config.active_record.dump_schema_after_migration = `git status db/migrate/ --porcelain`.present?
 ```
 
 ## 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 the end of your `Rakefile`:
+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
-task "db:schema:dump": "strong_migrations:alphabetize_columns"
-```
-
-## Dangerous Tasks
-
-For safety, dangerous database tasks are disabled in production - `db:drop`, `db:reset`, `db:schema:load`, and `db:structure:load`. To get around this, use:
-
-```sh
-SAFETY_ASSURED=1 rails db:drop
+StrongMigrations.alphabetize_schema = true
 ```
 
 ## Permissions
 
 We recommend using a [separate database user](https://ankane.org/postgres-users) for migrations when possible so you don’t need to grant your app user permission to alter tables.
 
+## Smaller Projects
+
+You probably don’t need this gem for smaller projects, as operations that are unsafe at scale can be perfectly safe on smaller, low-traffic tables.
+
 ## 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/)
+- [MariaDB InnoDB Online DDL Overview](https://mariadb.com/kb/en/innodb-online-ddl-overview/)
 
 ## Credits