online_migrations 0.20.1 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fd0059b044a120c61044268bfc32c3622163ae1871f85655ae51fe3cfb99c60
-  data.tar.gz: 1e1842002d3d229014011ee2a6af8eb122eaa7a6822912bec2d276f67e6555b4
+  metadata.gz: 3ecf0ad3b1c2bc1992e9ec205018212b4d3c663f2a3040271a0cce45d4b9f60c
+  data.tar.gz: fcc3a3ac5b96fc3bd893f251949969794ebde738e5f663eb367fd191fa50784d
 SHA512:
-  metadata.gz: 590aa0a0d36f94316cf02c0b3c8ec2dcf7be08e17cd687eb889d6fb9d8a4cfc892424cffb49c1988691720a7cbede5d58f1a2e712a0ddd8ab8545ce6df6395ed
-  data.tar.gz: a981da87aae5a6e0a5872be04ec9839285fa6b53693c73a4f8ceac354d30f5623d7aef473a8d5c07992e14654083253d3603881f031877692c6718c8f5588407
+  metadata.gz: c5a92bde9892d9f7bf545248d359527c9fac1a41b31e6eabf34f0da0a1342fdfc9e54ccc853aba6e35414d368328979d7b445246f71e72e0ac09cce80ad8a02f
+  data.tar.gz: d244cb531e3e2f58d140e75af1f8fc571a272d9d188d87f0e52d89b7efbc7233eb4c1df7bac63fe32d1e7b79643e1202872b951f1fcfc2b8ca5fa9c3abdc7746

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## master (unreleased)
 
+## 0.21.0 (2024-12-09)
+
+- Fix `add_foreign_key` when referencing same table via different columns
+- Make `validate_not_null_constraint`, `remove_foreign_key` and `remove_check_constraint` idempotent
+
+- Add helpers for validating constraints in background
+
+    ```ruby
+    validate_foreign_key_in_background(:users, :companies)
+    validate_constraint_in_background(:users, "first_name_not_null")
+    ```
+
+## 0.20.2 (2024-11-11)
+
+- Fix running background migrations over relations with duplicate records
+
 ## 0.20.1 (2024-11-05)
 
 - Fix background data migrations to work with `includes`/`eager_load` on relation

data/README.md

@@ -67,7 +67,7 @@ An operation is classified as dangerous if it either:
 Consider the following migration:
 
 ```ruby
-class AddAdminToUsers < ActiveRecord::Migration[7.2]
+class AddAdminToUsers < ActiveRecord::Migration[8.0]
   def change
     add_column :users, :admin, :boolean, default: false, null: false
   end
@@ -79,7 +79,7 @@ If the `users` table is large, running this migration on a live PostgreSQL < 11
 A safer approach would be to run something like the following:
 
 ```ruby
-class AddAdminToUsers < ActiveRecord::Migration[7.2]
+class AddAdminToUsers < ActiveRecord::Migration[8.0]
   # Do not wrap the migration in a transaction so that locks are held for a shorter time.
   disable_ddl_transaction!
 
@@ -124,7 +124,7 @@ A safer approach is to:
 
 add_column_with_default takes care of all this steps:
 
-class AddAdminToUsers < ActiveRecord::Migration[7.2]
+class AddAdminToUsers < ActiveRecord::Migration[8.0]
   disable_ddl_transaction!
 
   def change
@@ -178,7 +178,7 @@ You can also add [custom checks](docs/configuring.md#custom-checks) or [disable
 Active Record caches database columns at runtime, so if you drop a column, it can cause exceptions until your app reboots.
 
 ```ruby
-class RemoveNameFromUsers < ActiveRecord::Migration[7.2]
+class RemoveNameFromUsers < ActiveRecord::Migration[8.0]
   def change
     remove_column :users, :name
   end
@@ -199,7 +199,7 @@ end
 3. Wrap column removing in a `safety_assured` block:
 
    ```ruby
-   class RemoveNameFromUsers < ActiveRecord::Migration[7.2]
+   class RemoveNameFromUsers < ActiveRecord::Migration[8.0]
      def change
        safety_assured { remove_column :users, :name }
      end
@@ -216,7 +216,7 @@ end
 In earlier versions of PostgreSQL adding a column with a non-null default value to an existing table blocks reads and writes while the entire table is rewritten.
 
 ```ruby
-class AddAdminToUsers < ActiveRecord::Migration[7.2]
+class AddAdminToUsers < ActiveRecord::Migration[8.0]
   def change
     add_column :users, :admin, :boolean, default: false
   end
@@ -236,7 +236,7 @@ A safer approach is to:
 `add_column_with_default` helper takes care of all this steps:
 
 ```ruby
-class AddAdminToUsers < ActiveRecord::Migration[7.2]
+class AddAdminToUsers < ActiveRecord::Migration[8.0]
   disable_ddl_transaction!
 
   def change
@@ -254,7 +254,7 @@ end
 Active Record wraps each migration in a transaction, 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 AddAdminToUsers < ActiveRecord::Migration[7.2]
+class AddAdminToUsers < ActiveRecord::Migration[8.0]
   def change
     add_column :users, :admin, :boolean
     User.update_all(admin: false)
@@ -269,13 +269,13 @@ 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 a `update_column_in_batches` helper in a separate migration with `disable_ddl_transaction!`.
 
 ```ruby
-class AddAdminToUsers < ActiveRecord::Migration[7.2]
+class AddAdminToUsers < ActiveRecord::Migration[8.0]
   def change
     add_column :users, :admin, :boolean
   end
 end
 
-class BackfillUsersAdminColumn < ActiveRecord::Migration[7.2]
+class BackfillUsersAdminColumn < ActiveRecord::Migration[8.0]
   disable_ddl_transaction!
 
   def up
@@ -294,7 +294,7 @@ end
 Changing the type of an existing column blocks reads and writes while the entire table is rewritten.
 
 ```ruby
-class ChangeFilesSizeType < ActiveRecord::Migration[7.2]
+class ChangeFilesSizeType < ActiveRecord::Migration[8.0]
   def change
     change_column :files, :size, :bigint
   end
@@ -338,7 +338,7 @@ A safer approach can be accomplished in several steps:
 1. Create a new column and keep column's data in sync:
 
    ```ruby
-   class InitializeChangeFilesSizeType < ActiveRecord::Migration[7.2]
+   class InitializeChangeFilesSizeType < ActiveRecord::Migration[8.0]
      def change
        initialize_column_type_change :files, :size, :bigint
      end
@@ -351,7 +351,7 @@ A safer approach can be accomplished in several steps:
 2. Backfill data from the old column to the new column:
 
    ```ruby
-   class BackfillChangeFilesSizeType < ActiveRecord::Migration[7.2]
+   class BackfillChangeFilesSizeType < ActiveRecord::Migration[8.0]
      disable_ddl_transaction!
 
      def up
@@ -372,7 +372,7 @@ during writes works automatically). For most column type changes, this does not
 5. Copy indexes, foreign keys, check constraints, NOT NULL constraint, swap new column in place:
 
    ```ruby
-   class FinalizeChangeFilesSizeType < ActiveRecord::Migration[7.2]
+   class FinalizeChangeFilesSizeType < ActiveRecord::Migration[8.0]
      disable_ddl_transaction!
 
      def change
@@ -385,7 +385,7 @@ during writes works automatically). For most column type changes, this does not
 7. Finally, if everything works as expected, remove copy trigger and old column:
 
    ```ruby
-   class CleanupChangeFilesSizeType < ActiveRecord::Migration[7.2]
+   class CleanupChangeFilesSizeType < ActiveRecord::Migration[8.0]
      def up
        cleanup_column_type_change :files, :size
      end
@@ -406,7 +406,7 @@ during writes works automatically). For most column type changes, this does not
 Renaming a column that's in use will cause errors in your application.
 
 ```ruby
-class RenameUsersNameToFirstName < ActiveRecord::Migration[7.2]
+class RenameUsersNameToFirstName < ActiveRecord::Migration[8.0]
   def change
     rename_column :users, :name, :first_name
   end
@@ -477,7 +477,7 @@ nor any data/indexes/foreign keys copying will be made, so will be instantaneous
 It will use a combination of a VIEW and column aliasing to work with both column names simultaneously
 
    ```ruby
-   class InitializeRenameUsersNameToFirstName < ActiveRecord::Migration[7.2]
+   class InitializeRenameUsersNameToFirstName < ActiveRecord::Migration[8.0]
      def change
        initialize_column_rename :users, :name, :first_name
      end
@@ -500,7 +500,7 @@ It will use a combination of a VIEW and column aliasing to work with both column
 9. Remove the VIEW created in step 3 and finally rename the column:
 
    ```ruby
-   class FinalizeRenameUsersNameToFirstName < ActiveRecord::Migration[7.2]
+   class FinalizeRenameUsersNameToFirstName < ActiveRecord::Migration[8.0]
      def change
        finalize_column_rename :users, :name, :first_name
      end
@@ -516,7 +516,7 @@ It will use a combination of a VIEW and column aliasing to work with both column
 Renaming a table that's in use will cause errors in your application.
 
 ```ruby
-class RenameClientsToUsers < ActiveRecord::Migration[7.2]
+class RenameClientsToUsers < ActiveRecord::Migration[8.0]
   def change
     rename_table :clients, :users
   end
@@ -571,7 +571,7 @@ To work around this limitation, we need to tell Active Record to acquire this in
 3. Create a VIEW:
 
    ```ruby
-   class InitializeRenameClientsToUsers < ActiveRecord::Migration[7.2]
+   class InitializeRenameClientsToUsers < ActiveRecord::Migration[8.0]
      def change
        initialize_table_rename :clients, :users
      end
@@ -584,7 +584,7 @@ To work around this limitation, we need to tell Active Record to acquire this in
 7. Remove the VIEW created in step 3:
 
    ```ruby
-   class FinalizeRenameClientsToUsers < ActiveRecord::Migration[7.2]
+   class FinalizeRenameClientsToUsers < ActiveRecord::Migration[8.0]
      def change
        finalize_table_rename :clients, :users
      end
@@ -600,7 +600,7 @@ To work around this limitation, we need to tell Active Record to acquire this in
 The `force` option can drop an existing table.
 
 ```ruby
-class CreateUsers < ActiveRecord::Migration[7.2]
+class CreateUsers < ActiveRecord::Migration[8.0]
   def change
     create_table :users, force: true do |t|
       # ...
@@ -614,7 +614,7 @@ end
 Create tables without the `force` option.
 
 ```ruby
-class CreateUsers < ActiveRecord::Migration[7.2]
+class CreateUsers < ActiveRecord::Migration[8.0]
   def change
     create_table :users do |t|
       # ...
@@ -632,7 +632,7 @@ If you intend to drop an existing table, run `drop_table` first.
 Adding a check constraint blocks reads and writes while every row is checked.
 
 ```ruby
-class AddCheckConstraint < ActiveRecord::Migration[7.2]
+class AddCheckConstraint < ActiveRecord::Migration[8.0]
   def change
     add_check_constraint :users, "char_length(name) >= 1", name: "name_check"
   end
@@ -644,7 +644,7 @@ end
 Add the check constraint without validating existing rows, and then validate them in a separate transaction:
 
 ```ruby
-class AddCheckConstraint < ActiveRecord::Migration[7.2]
+class AddCheckConstraint < ActiveRecord::Migration[8.0]
   disable_ddl_transaction!
 
   def change
@@ -663,7 +663,7 @@ end
 Setting `NOT NULL` on an existing column blocks reads and writes while every row is checked.
 
 ```ruby
-class ChangeUsersNameNull < ActiveRecord::Migration[7.2]
+class ChangeUsersNameNull < ActiveRecord::Migration[8.0]
   def change
     change_column_null :users, :name, false
   end
@@ -675,7 +675,7 @@ end
 Instead, add a check constraint and validate it in a separate transaction:
 
 ```ruby
-class ChangeUsersNameNull < ActiveRecord::Migration[7.2]
+class ChangeUsersNameNull < ActiveRecord::Migration[8.0]
   disable_ddl_transaction!
 
   def change
@@ -690,7 +690,7 @@ end
 A `NOT NULL` check constraint is functionally equivalent to setting `NOT NULL` on the column (but it won't show up in `schema.rb` in Rails < 6.1). In PostgreSQL 12+, once the check constraint is validated, you can safely set `NOT NULL` on the column and drop the check constraint.
 
 ```ruby
-class ChangeUsersNameNullDropCheck < ActiveRecord::Migration[7.2]
+class ChangeUsersNameNullDropCheck < ActiveRecord::Migration[8.0]
   def change
     # in PostgreSQL 12+, you can then safely set NOT NULL on the column
     change_column_null :users, :name, false
@@ -704,7 +704,7 @@ end
 Online Migrations does not support inspecting what happens inside an `execute` call, so cannot help you here. Make really sure that what you're doing is safe before proceeding, then wrap it in a `safety_assured { ... }` block:
 
 ```ruby
-class ExecuteSQL < ActiveRecord::Migration[7.2]
+class ExecuteSQL < ActiveRecord::Migration[8.0]
   def change
     safety_assured { execute "..." }
   end
@@ -718,7 +718,7 @@ end
 Adding an index non-concurrently blocks writes.
 
 ```ruby
-class AddIndexOnUsersEmail < ActiveRecord::Migration[7.2]
+class AddIndexOnUsersEmail < ActiveRecord::Migration[8.0]
   def change
     add_index :users, :email, unique: true
   end
@@ -730,7 +730,7 @@ end
 Add indexes concurrently.
 
 ```ruby
-class AddIndexOnUsersEmail < ActiveRecord::Migration[7.2]
+class AddIndexOnUsersEmail < ActiveRecord::Migration[8.0]
   disable_ddl_transaction!
 
   def change
@@ -748,7 +748,7 @@ end
 While actual removing of an index is usually fast, removing it non-concurrently tries to obtain an `ACCESS EXCLUSIVE` lock on the table, waiting for all existing queries to complete and blocking all the subsequent queries (even `SELECT`s) on that table until the lock is obtained and index is removed.
 
 ```ruby
-class RemoveIndexOnUsersEmail < ActiveRecord::Migration[7.2]
+class RemoveIndexOnUsersEmail < ActiveRecord::Migration[8.0]
   def change
     remove_index :users, :email
   end
@@ -760,7 +760,7 @@ end
 Remove indexes concurrently.
 
 ```ruby
-class RemoveIndexOnUsersEmail < ActiveRecord::Migration[7.2]
+class RemoveIndexOnUsersEmail < ActiveRecord::Migration[8.0]
   disable_ddl_transaction!
 
   def change
@@ -778,7 +778,7 @@ end
 Removing an old index before replacing it with the new one might result in slow queries while building the new index.
 
 ```ruby
-class AddIndexOnCreationToProjects < ActiveRecord::Migration[7.2]
+class AddIndexOnCreationToProjects < ActiveRecord::Migration[8.0]
   disable_ddl_transaction!
 
   def change
@@ -795,7 +795,7 @@ end
 A safer approach is to create the new index and then delete the old one.
 
 ```ruby
-class AddIndexOnCreationToProjects < ActiveRecord::Migration[7.2]
+class AddIndexOnCreationToProjects < ActiveRecord::Migration[8.0]
   disable_ddl_transaction!
 
   def change
@@ -812,7 +812,7 @@ end
 Rails adds an index non-concurrently to references by default, which blocks writes. Additionally, if `foreign_key` option (without `validate: false`) is provided, both tables are blocked while it is validated.
 
 ```ruby
-class AddUserToProjects < ActiveRecord::Migration[7.2]
+class AddUserToProjects < ActiveRecord::Migration[8.0]
   def change
     add_reference :projects, :user, foreign_key: true
   end
@@ -825,7 +825,7 @@ Make sure the index is added concurrently and the foreign key is added in a sepa
 Or you can use `add_reference_concurrently` helper. It will create a reference and take care of safely adding index and/or foreign key.
 
 ```ruby
-class AddUserToProjects < ActiveRecord::Migration[7.2]
+class AddUserToProjects < ActiveRecord::Migration[8.0]
   disable_ddl_transaction!
 
   def change
@@ -843,7 +843,7 @@ end
 Adding a foreign key blocks writes on both tables.
 
 ```ruby
-class AddForeignKeyToProjectsUser < ActiveRecord::Migration[7.2]
+class AddForeignKeyToProjectsUser < ActiveRecord::Migration[8.0]
   def change
     add_foreign_key :projects, :users
   end
@@ -853,7 +853,7 @@ end
 or
 
 ```ruby
-class AddReferenceToProjectsUser < ActiveRecord::Migration[7.2]
+class AddReferenceToProjectsUser < ActiveRecord::Migration[8.0]
   def change
     add_reference :projects, :user, foreign_key: true
   end
@@ -865,7 +865,7 @@ end
 Add the foreign key without validating existing rows:
 
 ```ruby
-class AddForeignKeyToProjectsUser < ActiveRecord::Migration[7.2]
+class AddForeignKeyToProjectsUser < ActiveRecord::Migration[8.0]
   def change
     add_foreign_key :projects, :users, validate: false
   end
@@ -875,7 +875,7 @@ end
 Then validate them in a separate migration:
 
 ```ruby
-class ValidateForeignKeyOnProjectsUser < ActiveRecord::Migration[7.2]
+class ValidateForeignKeyOnProjectsUser < ActiveRecord::Migration[8.0]
   def change
     validate_foreign_key :projects, :users
   end
@@ -889,7 +889,7 @@ end
 Adding an exclusion constraint blocks reads and writes while every row is checked.
 
 ```ruby
-class AddExclusionContraint < ActiveRecord::Migration[7.2]
+class AddExclusionContraint < ActiveRecord::Migration[8.0]
   def change
     add_exclusion_constraint :users, "number WITH =", using: :gist
   end
@@ -907,7 +907,7 @@ end
 Adding a unique constraint blocks reads and writes while the underlying index is being built.
 
 ```ruby
-class AddUniqueConstraint < ActiveRecord::Migration[7.2]
+class AddUniqueConstraint < ActiveRecord::Migration[8.0]
   def change
     add_unique_constraint :sections, :position, deferrable: :deferred
   end
@@ -919,7 +919,7 @@ end
 A safer approach is to create a unique index first, and then create a unique key using that index.
 
 ```ruby
-class AddUniqueConstraintAddIndex < ActiveRecord::Migration[7.2]
+class AddUniqueConstraintAddIndex < ActiveRecord::Migration[8.0]
   disable_ddl_transaction!
 
   def change
@@ -929,7 +929,7 @@ end
 ```
 
 ```ruby
-class AddUniqueConstraint < ActiveRecord::Migration[7.2]
+class AddUniqueConstraint < ActiveRecord::Migration[8.0]
   def up
     add_unique_constraint :sections, :position, deferrable: :deferred, using_index: "index_sections_on_position"
   end
@@ -947,7 +947,7 @@ end
 There's no equality operator for the `json` column type, which can cause errors for existing `SELECT DISTINCT` queries in your application.
 
 ```ruby
-class AddSettingsToProjects < ActiveRecord::Migration[7.2]
+class AddSettingsToProjects < ActiveRecord::Migration[8.0]
   def change
     add_column :projects, :settings, :json
   end
@@ -959,7 +959,7 @@ end
 Use `jsonb` instead.
 
 ```ruby
-class AddSettingsToProjects < ActiveRecord::Migration[7.2]
+class AddSettingsToProjects < ActiveRecord::Migration[8.0]
   def change
     add_column :projects, :settings, :jsonb
   end
@@ -973,7 +973,7 @@ end
 Adding a stored generated column causes the entire table to be rewritten. During this time, reads and writes are blocked.
 
 ```ruby
-class AddLowerEmailToUsers < ActiveRecord::Migration[7.2]
+class AddLowerEmailToUsers < ActiveRecord::Migration[8.0]
   def change
     add_column :users, :lower_email, :virtual, type: :string, as: "LOWER(email)", stored: true
   end
@@ -991,7 +991,7 @@ Add a non-generated column and use callbacks or triggers instead.
 When using short integer types as primary key types, [there is a risk](https://m.signalvnoise.com/update-on-basecamp-3-being-stuck-in-read-only-as-of-nov-8-922am-cst/) of running out of IDs on inserts. The default type in Active Record < 5.1 for primary and foreign keys is `INTEGER`, which allows a little over of 2 billion records. Active Record 5.1 changed the default type to `BIGINT`.
 
 ```ruby
-class CreateUsers < ActiveRecord::Migration[7.2]
+class CreateUsers < ActiveRecord::Migration[8.0]
   def change
     create_table :users, id: :integer do |t|
       # ...
@@ -1005,7 +1005,7 @@ end
 Use one of `bigint`, `bigserial`, `uuid` instead.
 
 ```ruby
-class CreateUsers < ActiveRecord::Migration[7.2]
+class CreateUsers < ActiveRecord::Migration[8.0]
   def change
     create_table :users, id: :bigint do |t| # bigint is the default for Active Record >= 5.1
       # ...
@@ -1021,7 +1021,7 @@ end
 Hash index operations are not WAL-logged, so hash indexes might need to be rebuilt with `REINDEX` after a database crash if there were unwritten changes. Also, changes to hash indexes are not replicated over streaming or file-based replication after the initial base backup, so they give wrong answers to queries that subsequently use them. For these reasons, hash index use is discouraged.
 
 ```ruby
-class AddIndexToUsersOnEmail < ActiveRecord::Migration[7.2]
+class AddIndexToUsersOnEmail < ActiveRecord::Migration[8.0]
   def change
     add_index :users, :email, unique: true, using: :hash
   end
@@ -1033,7 +1033,7 @@ end
 Use B-tree indexes instead.
 
 ```ruby
-class AddIndexToUsersOnEmail < ActiveRecord::Migration[7.2]
+class AddIndexToUsersOnEmail < ActiveRecord::Migration[8.0]
   def change
     add_index :users, :email, unique: true # B-tree by default
   end
@@ -1048,7 +1048,7 @@ Adding multiple foreign keys in a single migration blocks writes on all involved
 Avoid adding foreign key more than once per migration file, unless the source and target tables are identical.
 
 ```ruby
-class CreateUserProjects < ActiveRecord::Migration[7.2]
+class CreateUserProjects < ActiveRecord::Migration[8.0]
   def change
     create_table :user_projects do |t|
       t.belongs_to :user, foreign_key: true
@@ -1063,7 +1063,7 @@ end
 Add additional foreign keys in separate migration files. See [adding a foreign key](#adding-a-foreign-key) for how to properly add foreign keys.
 
 ```ruby
-class CreateUserProjects < ActiveRecord::Migration[7.2]
+class CreateUserProjects < ActiveRecord::Migration[8.0]
   def change
     create_table :user_projects do |t|
       t.belongs_to :user, foreign_key: true
@@ -1072,7 +1072,7 @@ class CreateUserProjects < ActiveRecord::Migration[7.2]
   end
 end
 
-class AddForeignKeyFromUserProjectsToProject < ActiveRecord::Migration[7.2]
+class AddForeignKeyFromUserProjectsToProject < ActiveRecord::Migration[8.0]
   def change
     add_foreign_key :user_projects, :projects
   end
@@ -1089,7 +1089,7 @@ Remove all the foreign keys first.
 Assuming, `projects` has foreign keys on `users.id` and `repositories.id`:
 
 ```ruby
-class DropProjects < ActiveRecord::Migration[7.2]
+class DropProjects < ActiveRecord::Migration[8.0]
   def change
     drop_table :projects
   end
@@ -1101,13 +1101,13 @@ end
 Remove all the foreign keys first:
 
 ```ruby
-class RemoveProjectsUserFk < ActiveRecord::Migration[7.2]
+class RemoveProjectsUserFk < ActiveRecord::Migration[8.0]
   def change
     remove_foreign_key :projects, :users
   end
 end
 
-class RemoveProjectsRepositoryFk < ActiveRecord::Migration[7.2]
+class RemoveProjectsRepositoryFk < ActiveRecord::Migration[8.0]
   def change
     remove_foreign_key :projects, :repositories
   end
@@ -1117,7 +1117,7 @@ end
 Then remove the table:
 
 ```ruby
-class DropProjects < ActiveRecord::Migration[7.2]
+class DropProjects < ActiveRecord::Migration[8.0]
   def change
     drop_table :projects
   end
@@ -1134,7 +1134,7 @@ Otherwise, there's a risk of bugs caused by IDs representable by one type but no
 Assuming, there is a `users` table with `bigint` primary key type:
 
 ```ruby
-class AddUserIdToProjects < ActiveRecord::Migration[7.2]
+class AddUserIdToProjects < ActiveRecord::Migration[8.0]
   def change
     add_column :projects, :user_id, :integer
   end
@@ -1148,7 +1148,7 @@ Add a reference column of the same type as a referenced primary key.
 Assuming, there is a `users` table with `bigint` primary key type:
 
 ```ruby
-class AddUserIdToProjects < ActiveRecord::Migration[7.2]
+class AddUserIdToProjects < ActiveRecord::Migration[8.0]
   def change
     add_column :projects, :user_id, :bigint
   end
@@ -1162,7 +1162,7 @@ end
 Adding a single table inheritance column might cause errors in old instances of your application.
 
 ```ruby
-class AddTypeToUsers < ActiveRecord::Migration[7.2]
+class AddTypeToUsers < ActiveRecord::Migration[8.0]
   def change
     add_column :users, :string, :type, default: "Member"
   end
@@ -1194,7 +1194,7 @@ A safer approach is to:
 Active Record < 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[7.2]
+class ChangeSomeColumnDefault < ActiveRecord::Migration[8.0]
   def change
     change_column_default :users, :some_column, from: "old", to: "new"
   end
@@ -1222,7 +1222,7 @@ config.active_record.partial_inserts = false
 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.2]
+class MySafeMigration < ActiveRecord::Migration[8.0]
   def change
     safety_assured { remove_column :users, :some_column }
   end

data/docs/background_data_migrations.md

@@ -78,7 +78,7 @@ You can enqueue your background migration to be run by the scheduler via:
 
 ```ruby
 # db/migrate/xxxxxxxxxxxxxx_enqueue_backfill_project_issues_count.rb
-class EnqueueBackfillProjectIssuesCount < ActiveRecord::Migration[7.2]
+class EnqueueBackfillProjectIssuesCount < ActiveRecord::Migration[8.0]
   def up
     enqueue_background_data_migration("BackfillProjectIssuesCount")
   end

data/docs/background_schema_migrations.md

@@ -34,33 +34,39 @@ or run it manually when the deployment is finished, from the rails console:
 
 ## Enqueueing a Background Schema Migration
 
-Currently, only helpers for adding/removing indexes are provided.
+Currently, only helpers for adding/removing indexes and validating constraints are provided.
 
-Background schema migrations should be performed in 2 steps:
+Background schema migrations should be performed in 2 steps (e.g. for index creation):
 
-1. Create a PR that schedules the index to be created/removed
-2. Verify that the PR was deployed and that the index was actually created/removed on production.
-  Create a follow-up PR with a regular migration that creates/removes an index synchronously (will be a no op when run on production) and commit the schema changes for `schema.rb`/`structure.sql`
+1. Create a PR that schedules the index to be created
+2. Verify that the PR was deployed and that the index was actually created on production.
+  Create a follow-up PR with a regular migration that creates an index synchronously (will be a no op when run on production) and commit the schema changes for `schema.rb`/`structure.sql`
 
 To schedule an index creation:
 
 ```ruby
-# db/migrate/xxxxxxxxxxxxxx_add_index_to_users_email_in_background.rb
-def up
-  add_index_in_background(:users, :email, unique: true)
-end
+add_index_in_background(:users, :email, unique: true)
 ```
 
 To schedule an index removal:
 
 ```ruby
-# db/migrate/xxxxxxxxxxxxxx_remove_index_from_users_email_in_background.rb
-def up
-  remove_index_in_background(:users, name: "index_users_on_email")
-end
+remove_index_in_background(:users, name: "index_users_on_email")
+```
+
+To schedule a foreign key validation:
+
+```ruby
+validate_foreign_key_in_background(:users, :companies)
+```
+
+To schedule a constraint (`CHECK` constraint, `FOREIGN KEY` constraint) validation:
+
+```ruby
+validate_constraint_in_background(:users, "first_name_not_null")
 ```
 
-`add_index_in_background`/`remove_index_in_background` accept additional configuration options which controls how the background schema migration is run. Check the [source code](https://github.com/fatkodima/online_migrations/blob/master/lib/online_migrations/background_schema_migrations/migration_helpers.rb) for the list of all available configuration options.
+All the helpers accept additional configuration options which controls how the background schema migration is run. Check the [source code](https://github.com/fatkodima/online_migrations/blob/master/lib/online_migrations/background_schema_migrations/migration_helpers.rb) for the list of all available configuration options.
 
 ## Depending on schema changes
 

data/docs/configuring.md

@@ -156,7 +156,7 @@ This is useful to demystify `online_migrations` inner workings, and to better in
 Consider migration, running on PostgreSQL < 11:
 
 ```ruby
-class AddAdminToUsers < ActiveRecord::Migration[7.2]
+class AddAdminToUsers < ActiveRecord::Migration[8.0]
   disable_ddl_transaction!
 
   def change

data/lib/online_migrations/background_schema_migrations/migration_helpers.rb

@@ -45,6 +45,26 @@ module OnlineMigrations
         enqueue_background_schema_migration(name, table_name, definition: definition, **migration_options)
       end
 
+      def validate_foreign_key_in_background(from_table, to_table = nil, **options)
+        migration_options = options.extract!(:max_attempts, :statement_timeout, :connection_class_name)
+
+        if !foreign_key_exists?(from_table, to_table, **options)
+          Utils.raise_or_say("Foreign key validation was not enqueued because the foreign key does not exist.")
+          return
+        end
+
+        fk_name_to_validate = foreign_key_for!(from_table, to_table: to_table, **options).name
+        validate_constraint_in_background(from_table, fk_name_to_validate, **migration_options)
+      end
+
+      def validate_constraint_in_background(table_name, constraint_name, **options)
+        definition = <<~SQL.squish
+          ALTER TABLE #{quote_table_name(table_name)}
+          VALIDATE CONSTRAINT #{quote_table_name(constraint_name)}
+        SQL
+        enqueue_background_schema_migration(constraint_name, table_name, definition: definition, **options)
+      end
+
       # Ensures that the background schema migration with the provided migration name succeeded.
       #
       # If the enqueued migration was not found in development (probably when resetting a dev environment

data/lib/online_migrations/batch_iterator.rb

@@ -75,9 +75,10 @@ module OnlineMigrations
         # Retaining the results in the query cache would undermine the point of batching.
         batch_relation.uncached { yield batch_relation, start_id, last_id }
 
-        break if stop_row.nil?
+        break if last_id == finish
 
         start_id = stop_id
+        stop_id = nil
       end
     end
 

data/lib/online_migrations/change_column_type_helpers.rb

@@ -126,15 +126,15 @@ module OnlineMigrations
               # To avoid this, we instead set it to `NOT NULL DEFAULT 0` and we'll
               # copy the correct values when backfilling.
               add_column(table_name, tmp_column_name, new_type,
-                **old_col_options.merge(column_options).merge(default: old_col.default || 0, null: false))
+                **old_col_options, **column_options, default: old_col.default || 0, null: false)
             else
               if !old_col.default.nil?
                 old_col_options = old_col_options.merge(default: old_col.default, null: old_col.null)
               end
-              add_column(table_name, tmp_column_name, new_type, **old_col_options.merge(column_options))
+              add_column(table_name, tmp_column_name, new_type, **old_col_options, **column_options)
             end
           else
-            add_column(table_name, tmp_column_name, new_type, **old_col_options.merge(column_options))
+            add_column(table_name, tmp_column_name, new_type, **old_col_options, **column_options)
             change_column_default(table_name, tmp_column_name, old_col.default) if !old_col.default.nil?
           end
         end
@@ -434,7 +434,7 @@ module OnlineMigrations
             options[:opclass] = opclasses
           end
 
-          add_index(table_name, new_columns, **options.merge(algorithm: :concurrently))
+          add_index(table_name, new_columns, **options, algorithm: :concurrently)
         end
       end
 

data/lib/online_migrations/command_checker.rb

@@ -553,7 +553,7 @@ module OnlineMigrations
         if !new_or_small_table?(table_name)
           if options[:algorithm] != :concurrently
             raise_error :add_index,
-              command: command_str(:add_index, table_name, column_name, **options.merge(algorithm: :concurrently))
+              command: command_str(:add_index, table_name, column_name, **options, algorithm: :concurrently)
           end
 
           if options[:algorithm] == :concurrently && index_corruption?
@@ -585,7 +585,7 @@ module OnlineMigrations
 
         if options[:algorithm] != :concurrently && !new_or_small_table?(table_name)
           raise_error :remove_index,
-            command: command_str(:remove_index, table_name, **options.merge(algorithm: :concurrently))
+            command: command_str(:remove_index, table_name, **options, algorithm: :concurrently)
         end
 
         index_def = connection.indexes(table_name).find do |index|
@@ -608,7 +608,7 @@ module OnlineMigrations
 
           if validate
             raise_error :add_foreign_key,
-              add_code: command_str(:add_foreign_key, from_table, to_table, **options.merge(validate: false)),
+              add_code: command_str(:add_foreign_key, from_table, to_table, **options, validate: false),
               validate_code: command_str(:validate_foreign_key, from_table, to_table)
           end
         end
@@ -633,7 +633,7 @@ module OnlineMigrations
           name = options[:name] || check_constraint_name(table_name, expression)
 
           raise_error :add_check_constraint,
-            add_code: command_str(:add_check_constraint, table_name, expression, **options.merge(validate: false)),
+            add_code: command_str(:add_check_constraint, table_name, expression, **options, validate: false),
             validate_code: command_str(:validate_check_constraint, table_name, name: name)
         end
       end
@@ -645,7 +645,7 @@ module OnlineMigrations
 
         raise_error :add_unique_constraint,
           add_index_code: command_str(:add_index, table_name, column_name, unique: true, name: index_name, algorithm: :concurrently),
-          add_code: command_str(:add_unique_constraint, table_name, **options.merge(using_index: index_name)),
+          add_code: command_str(:add_unique_constraint, table_name, **options, using_index: index_name),
           remove_code: command_str(:remove_unique_constraint, table_name, column_name)
       end
 
@@ -661,7 +661,7 @@ module OnlineMigrations
       def add_not_null_constraint(table_name, column_name, **options)
         if !new_or_small_table?(table_name) && options[:validate] != false
           raise_error :add_not_null_constraint,
-            add_code: command_str(:add_not_null_constraint, table_name, column_name, **options.merge(validate: false)),
+            add_code: command_str(:add_not_null_constraint, table_name, column_name, **options, validate: false),
             validate_code: command_str(:validate_not_null_constraint, table_name, column_name, **options.except(:validate))
         end
       end
@@ -669,7 +669,7 @@ module OnlineMigrations
       def add_text_limit_constraint(table_name, column_name, limit, **options)
         if !new_or_small_table?(table_name) && options[:validate] != false
           raise_error :add_text_limit_constraint,
-            add_code: command_str(:add_text_limit_constraint, table_name, column_name, limit, **options.merge(validate: false)),
+            add_code: command_str(:add_text_limit_constraint, table_name, column_name, limit, **options, validate: false),
             validate_code: command_str(:validate_text_limit_constraint, table_name, column_name, **options.except(:validate))
         end
       end

data/lib/online_migrations/error_messages.rb

@@ -268,6 +268,8 @@ class <%= migration_name %> < <%= migration_parent %>
     end
 
 <% end %>
+    # You can use `validate_constraint_in_background` if you have a very large table
+    # and want to validate the constraint using background schema migrations.
     <%= validate_constraint_code %>
 <% if remove_constraint_code %>
 
@@ -404,6 +406,8 @@ end
 
 class Validate<%= migration_name %> < <%= migration_parent %>
   def change
+    # You can use `validate_foreign_key_in_background` if you have a very large table
+    # and want to validate the foreign key using background schema migrations.
     <%= validate_code %>
   end
 end",

data/lib/online_migrations/lock_retrier.rb

@@ -176,7 +176,7 @@ module OnlineMigrations
   #   # This will attempt 30 retries starting with delay of 10ms between each unsuccessful try, increasing exponentially
   #   # up to the maximum delay of 1 minute and 200ms set as lock timeout for each try:
   #
-  #   config.retrier = OnlineMigrations::ConstantLockRetrier.new(attempts: 30,
+  #   config.retrier = OnlineMigrations::ExponentialLockRetrier.new(attempts: 30,
   #       base_delay: 0.01.seconds, max_delay: 1.minute, lock_timeout: 0.2.seconds)
   #
   class ExponentialLockRetrier < LockRetrier

data/lib/online_migrations/schema_statements.rb

@@ -451,7 +451,7 @@ module OnlineMigrations
                     "or similar) table_name: #{table_name}, column_name: #{column_name}")
         else
           transaction do
-            add_column(table_name, column_name, type, **options.merge(default: nil, null: true))
+            add_column(table_name, column_name, type, **options, default: nil, null: true)
             change_column_default(table_name, column_name, default)
           end
         end
@@ -520,7 +520,17 @@ module OnlineMigrations
     #
     def validate_not_null_constraint(table_name, column_name, name: nil)
       name ||= __not_null_constraint_name(table_name, column_name)
-      validate_check_constraint(table_name, name: name)
+      column = column_for(table_name, column_name)
+
+      if column.null == false &&
+         !__not_null_constraint_exists?(table_name, column_name, name: name)
+        Utils.say(<<~MSG.squish)
+          NOT NULL constraint was not validated: it does not exist and
+          column #{table_name}.#{column_name} is already defined as `NOT NULL`
+        MSG
+      else
+        validate_check_constraint(table_name, name: name)
+      end
     end
 
     # Removes a NOT NULL constraint from the column
@@ -672,7 +682,7 @@ module OnlineMigrations
           index[:name] ||= "index_#{table_name}_on_#{ref_name}"
         end
 
-        add_index(table_name, index_columns, **index.merge(algorithm: :concurrently))
+        add_index(table_name, index_columns, **index, algorithm: :concurrently)
       end
 
       foreign_key = options[:foreign_key]
@@ -681,7 +691,7 @@ module OnlineMigrations
         foreign_key = {} if foreign_key == true
 
         foreign_table_name = Utils.foreign_table_name(ref_name, foreign_key)
-        add_foreign_key(table_name, foreign_table_name, **foreign_key.merge(column: column_name, validate: false))
+        add_foreign_key(table_name, foreign_table_name, **foreign_key, column: column_name, validate: false)
 
         if foreign_key[:validate] != false
           validate_foreign_key(table_name, foreign_table_name, **foreign_key)
@@ -803,13 +813,13 @@ module OnlineMigrations
     # @see https://edgeapi.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_foreign_key
     #
     def add_foreign_key(from_table, to_table, **options)
-      # Do not consider validation for idempotency.
-      if foreign_key_exists?(from_table, to_table, **options.except(:validate))
-        message = +"Foreign key was not created because it already exists " \
-                   "(this can be due to an aborted migration or similar): from_table: #{from_table}, to_table: #{to_table}"
-        message << ", #{options.inspect}" if options.any?
+      options = foreign_key_options(from_table, to_table, options)
 
-        Utils.say(message)
+      if foreign_key_exists?(from_table, to_table, **options.slice(:column, :primary_key))
+        Utils.say(<<~MSG.squish)
+          Foreign key was not created because it already exists (this can be due to an aborted migration or similar).
+          from_table: #{from_table}, to_table: #{to_table}, options: #{options.inspect}
+        MSG
       else
         super
       end
@@ -844,6 +854,21 @@ module OnlineMigrations
       end
     end
 
+    # Extends default method to be idempotent.
+    #
+    # @see https://edgeapi.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-remove_foreign_key
+    #
+    def remove_foreign_key(from_table, to_table = nil, **options)
+      if foreign_key_exists?(from_table, to_table, **options.slice(:name, :to_table, :column))
+        super
+      else
+        Utils.say(<<~MSG.squish)
+          Foreign key was not removed because it does not exist (this may be due to an aborted migration or similar).
+          from_table: #{from_table}, to_table: #{to_table}, options: #{options.inspect}
+        MSG
+      end
+    end
+
     # Extends default method to be idempotent
     #
     # @see https://edgeapi.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_check_constraint
@@ -888,6 +913,21 @@ module OnlineMigrations
       end
     end
 
+    # Extends default method to be idempotent
+    #
+    # @see https://edgeapi.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-remove_check_constraint
+    #
+    def remove_check_constraint(table_name, expression = nil, **options)
+      if __check_constraint_exists?(table_name, expression: expression, **options)
+        super
+      else
+        Utils.say(<<~MSG.squish)
+          Check constraint was not removed because it does not exist (this may be due to an aborted migration or similar).
+          table_name: #{table_name}, expression: #{expression}, options: #{options.inspect}
+        MSG
+      end
+    end
+
     if Utils.ar_version >= 7.1
       def add_exclusion_constraint(table_name, expression, **options)
         if __exclusion_constraint_exists?(table_name, expression: expression, **options)

data/lib/online_migrations/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OnlineMigrations
-  VERSION = "0.20.1"
+  VERSION = "0.21.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: online_migrations
 version: !ruby/object:Gem::Version
-  version: 0.20.1
+  version: 0.21.0
 platform: ruby
 authors:
 - fatkodima
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-05 00:00:00.000000000 Z
+date: 2024-12-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord