Strong Migrations

In Postgres, adding an index non-concurrently blocks writes. To avoid this, use algorithm: :concurrently and you must call disable_ddl_transaction! in your migration. Note that indexes on new tables created within the same migration do not require this.

class AddSomeIndexToUsers < ActiveRecord::Migration[8.1]
  disable_ddl_transaction!

  def change
    add_index :users, :some_column, algorithm: :concurrently
  end
end

Renaming columns or tables in use causes application errors. Use the following deployment pattern:

For Columns:

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.

For Tables:

1. Create a new table.
2. Write to both tables.
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.

Adding a check constraint blocks reads and writes while rows are checked.

Postgres Strategy:

1. Add the constraint without validating existing rows using validate: false.
2. Validate the constraint in a separate migration using validate_check_constraint.

MySQL/MariaDB: Currently, enforcing check constraints blocks writes. There is no recommended safe way provided in the documentation for this database engine.

# Postgres: Step 1
class AddCheckConstraint < ActiveRecord::Migration[8.1]
  def change
    add_check_constraint :users, "price > 0", name: "price_check", validate: false
  end
end

# Postgres: Step 2
class ValidateCheckConstraint < ActiveRecord::Migration[8.1]
  def change
    validate_check_constraint :users, name: "price_check"
  end
end

In Postgres, the json column type lacks an equality operator, which can cause errors for existing SELECT DISTINCT queries. Use jsonb instead for better performance and compatibility.

class AddPropertiesToUsers < ActiveRecord::Migration[8.1]
  def change
    add_column :users, :properties, :jsonb
  end
end

Adding a column with a volatile default (e.g., gen_random_uuid()) to an existing table causes a full table rewrite, blocking reads and writes. Instead, add the column without a default, change the default in a separate step, and then backfill the data.

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

Renaming an enum value in use causes application errors. Instead: 1. Add the new enum 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.

class AddCompletedToStatus < ActiveRecord::Migration[8.1]
  def up
    add_enum_value :status, "completed", after: "done"
  end
end

Rails adds indexes non-concurrently to references by default, which blocks writes in Postgres. To prevent this, pass the concurrent algorithm in the index options.

class AddReferenceToUsers < ActiveRecord::Migration[8.1]
  disable_ddl_transaction!

  def change
    add_reference :users, :city, index: {algorithm: :concurrently}
  end
end

Dropping a column directly can cause application errors because Active Record caches column information. To remove a column safely, follow these steps:

1. Ignore the column in your model: Add the column to the ignored_columns list to prevent Active Record from using it.
2. Deploy the code change.
3. Run the migration: Use a safety_assured block in your migration to bypass the check.
4. Deploy and run the migration.
5. Remove the ignored column line from your model code.

# 1. In your model
class User < ApplicationRecord
  self.ignored_columns += ["some_column"]
end

# 3. In your migration
class RemoveSomeColumnFromUsers < ActiveRecord::Migration[8.1]
  def change
    safety_assured { remove_column :users, :some_column }
  end
end

Adding a unique constraint directly creates a unique index that blocks reads and writes. The safe pattern is to create a unique index concurrently first, then apply the constraint using that index.

class AddUniqueConstraint < ActiveRecord::Migration[8.1]
  def up
    add_index :users, :some_column, unique: true, algorithm: :concurrently
    add_unique_constraint :users, using_index: "index_users_on_some_column"
  end

  def down
    remove_unique_constraint :users, :some_column
  end
end