strong_migrations 1.6.3 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd18b6da9358b37dfe07adbda611a65905173b4c4bd1aae1920588002d89afe6
-  data.tar.gz: 87f5393be68a9c685adbb38a29ac1980615f933f28b1b03634c2618af3db3963
+  metadata.gz: 0b621e800497f9e9c77e0208a899f7e8d17a944caa61dffdea80911e8ddd5ead
+  data.tar.gz: 3f7d4275c416db6b954c1c2e1109ad5118a1c0a7cc6eb25a81203f82a4e47b35
 SHA512:
-  metadata.gz: 4bde3a8af5e9bae18dcf270155afeefb82b726d93c9b49ac7eeee72706af2c85a31401b8eb415b89f2df3c3234ec74b1c5b5fd48404da0b0cdb65d1c5d205099
-  data.tar.gz: 352f30e395b489175ef038d6bb418266a2ecdb7fb3f7b0df4dd1d5290994efae1962b87b8dc0e4a5a494718a781e7552ef9f530001880f493f497ac374beb6c9
+  metadata.gz: '0243834c1f5b12bc637a00b49f8b7eb773dcdd5b8592a354b705d72b6e5b6a728babfb12fc3d058093086529ebfe7de34abd9f1c834bc95323b01f8a48417445'
+  data.tar.gz: a24deb56f0adbe0206791b9155707489d03c02f021842f9284eaadcf5a2b99c30fe6f3ae2c51fef15fc5fef9bf7066b1a72f84c446ed8c12919c43f29eee9f95

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 1.7.0 (2024-01-05)
+
+- Added check for `add_unique_constraint`
+
+## 1.6.4 (2023-10-17)
+
+- Fixed false positives with `revert`
+
 ## 1.6.3 (2023-09-20)
 
 - Added support for Trilogy
@@ -241,7 +249,7 @@ Other
 ## 0.2.2 (2018-02-14)
 
 - Friendlier output
-- Better method of hooking into ActiveRecord
+- Better method of hooking into Active Record
 
 ## 0.2.1 (2018-02-07)
 

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
 
@@ -43,7 +43,7 @@ end
 
 Deploy the code, then wrap this step in a safety_assured { ... } block.
 
-class RemoveColumn < ActiveRecord::Migration[7.0]
+class RemoveColumn < ActiveRecord::Migration[7.1]
   def change
     safety_assured { remove_column :users, :name }
   end
@@ -75,6 +75,7 @@ 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)
 - [setting NOT NULL on an existing column](#setting-not-null-on-an-existing-column)
@@ -96,7 +97,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[7.1]
   def change
     remove_column :users, :some_column
   end
@@ -117,7 +118,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[7.1]
     def change
       safety_assured { remove_column :users, :some_column }
     end
@@ -134,7 +135,7 @@ end
 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]
+class AddSomeColumnToUsers < ActiveRecord::Migration[7.1]
   def change
     add_column :users, :some_column, :text, default: "default_value"
   end
@@ -148,7 +149,7 @@ In Postgres 11+, MySQL 8.0.12+, and MariaDB 10.3.2+, this no longer requires a t
 Instead, add the column without a default value, then change the default.
 
 ```ruby
-class AddSomeColumnToUsers < ActiveRecord::Migration[7.0]
+class AddSomeColumnToUsers < ActiveRecord::Migration[7.1]
   def up
     add_column :users, :some_column, :text
     change_column_default :users, :some_column, "default_value"
@@ -169,7 +170,7 @@ See the next section for how to backfill.
 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]
+class AddSomeColumnToUsers < ActiveRecord::Migration[7.1]
   def change
     add_column :users, :some_column, :text
     User.update_all some_column: "default_value"
@@ -184,7 +185,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[7.0]
+class BackfillSomeColumn < ActiveRecord::Migration[7.1]
   disable_ddl_transaction!
 
   def up
@@ -203,7 +204,7 @@ end
 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]
+class AddSomeColumnToUsers < ActiveRecord::Migration[7.1]
   def change
     add_column :users, :some_column, :virtual, type: :string, as: "...", stored: true
   end
@@ -221,7 +222,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[7.1]
   def change
     change_column :users, :some_column, :new_type
   end
@@ -267,7 +268,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[7.1]
   def change
     rename_column :users, :some_column, :new_name
   end
@@ -292,7 +293,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[7.1]
   def change
     rename_table :users, :customers
   end
@@ -305,7 +306,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 +318,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[7.1]
   def change
     create_table :users, force: true do |t|
       # ...
@@ -331,7 +332,7 @@ end
 Create tables without the `force` option.
 
 ```ruby
-class CreateUsers < ActiveRecord::Migration[7.0]
+class CreateUsers < ActiveRecord::Migration[7.1]
   def change
     create_table :users do |t|
       # ...
@@ -351,7 +352,7 @@ If you intend to drop an existing table, run `drop_table` first.
 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[7.1]
   def change
     add_check_constraint :users, "price > 0", name: "price_check"
   end
@@ -363,7 +364,7 @@ end
 Add the check constraint without validating existing rows:
 
 ```ruby
-class AddCheckConstraint < ActiveRecord::Migration[7.0]
+class AddCheckConstraint < ActiveRecord::Migration[7.1]
   def change
     add_check_constraint :users, "price > 0", name: "price_check", validate: false
   end
@@ -373,7 +374,7 @@ end
 Then validate them in a separate migration.
 
 ```ruby
-class ValidateCheckConstraint < ActiveRecord::Migration[7.0]
+class ValidateCheckConstraint < ActiveRecord::Migration[7.1]
   def change
     validate_check_constraint :users, name: "price_check"
   end
@@ -389,7 +390,7 @@ 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[7.1]
   def change
     safety_assured { execute "..." }
   end
@@ -405,7 +406,7 @@ end
 In Postgres, adding an index non-concurrently blocks writes.
 
 ```ruby
-class AddSomeIndexToUsers < ActiveRecord::Migration[7.0]
+class AddSomeIndexToUsers < ActiveRecord::Migration[7.1]
   def change
     add_index :users, :some_column
   end
@@ -417,7 +418,7 @@ end
 Add indexes concurrently.
 
 ```ruby
-class AddSomeIndexToUsers < ActiveRecord::Migration[7.0]
+class AddSomeIndexToUsers < ActiveRecord::Migration[7.1]
   disable_ddl_transaction!
 
   def change
@@ -443,7 +444,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[7.1]
   def change
     add_reference :users, :city
   end
@@ -455,7 +456,7 @@ end
 Make sure the index is added concurrently.
 
 ```ruby
-class AddReferenceToUsers < ActiveRecord::Migration[7.0]
+class AddReferenceToUsers < ActiveRecord::Migration[7.1]
   disable_ddl_transaction!
 
   def change
@@ -473,7 +474,7 @@ end
 In Postgres, adding a foreign key blocks writes on both tables.
 
 ```ruby
-class AddForeignKeyOnUsers < ActiveRecord::Migration[7.0]
+class AddForeignKeyOnUsers < ActiveRecord::Migration[7.1]
   def change
     add_foreign_key :users, :orders
   end
@@ -483,7 +484,7 @@ end
 or
 
 ```ruby
-class AddReferenceToUsers < ActiveRecord::Migration[7.0]
+class AddReferenceToUsers < ActiveRecord::Migration[7.1]
   def change
     add_reference :users, :order, foreign_key: true
   end
@@ -495,7 +496,7 @@ end
 Add the foreign key without validating existing rows:
 
 ```ruby
-class AddForeignKeyOnUsers < ActiveRecord::Migration[7.0]
+class AddForeignKeyOnUsers < ActiveRecord::Migration[7.1]
   def change
     add_foreign_key :users, :orders, validate: false
   end
@@ -505,13 +506,46 @@ end
 Then validate them in a separate migration.
 
 ```ruby
-class ValidateForeignKeyOnUsers < ActiveRecord::Migration[7.0]
+class ValidateForeignKeyOnUsers < ActiveRecord::Migration[7.1]
   def change
     validate_foreign_key :users, :orders
   end
 end
 ```
 
+### Adding a unique constraint
+
+#### Bad
+
+In Postgres, adding a unique constraint creates a unique index, which blocks reads and writes.
+
+```ruby
+class AddUniqueContraint < ActiveRecord::Migration[7.1]
+  def change
+    add_unique_constraint :users, :some_column
+  end
+end
+```
+
+#### Good
+
+Create a unique index concurrently, then use it for the constraint.
+
+```ruby
+class AddUniqueContraint < ActiveRecord::Migration[7.1]
+  disable_ddl_transaction!
+
+  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
+```
+
 ### Adding an exclusion constraint
 
 #### Bad
@@ -537,7 +571,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[7.1]
   def change
     add_column :users, :properties, :json
   end
@@ -549,7 +583,7 @@ end
 Use `jsonb` instead.
 
 ```ruby
-class AddPropertiesToUsers < ActiveRecord::Migration[7.0]
+class AddPropertiesToUsers < ActiveRecord::Migration[7.1]
   def change
     add_column :users, :properties, :jsonb
   end
@@ -565,7 +599,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[7.1]
   def change
     change_column_null :users, :some_column, false
   end
@@ -576,10 +610,10 @@ end
 
 Instead, add a check constraint.
 
-For Rails 6.1, use:
+For Rails 6.1+, use:
 
 ```ruby
-class SetSomeColumnNotNull < ActiveRecord::Migration[7.0]
+class SetSomeColumnNotNull < ActiveRecord::Migration[7.1]
   def change
     add_check_constraint :users, "some_column IS NOT NULL", name: "users_some_column_null", validate: false
   end
@@ -600,10 +634,10 @@ 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.
 
-For Rails 6.1, use:
+For Rails 6.1+, use:
 
 ```ruby
-class ValidateSomeColumnNotNull < ActiveRecord::Migration[7.0]
+class ValidateSomeColumnNotNull < ActiveRecord::Migration[7.1]
   def change
     validate_check_constraint :users, name: "users_some_column_null"
 
@@ -656,7 +690,7 @@ Disable partial writes in `config/application.rb`. For Rails < 7, use:
 config.active_record.partial_writes = false
 ```
 
-For Rails 7, use:
+For Rails 7+, use:
 
 ```ruby
 config.active_record.partial_inserts = false
@@ -669,7 +703,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[7.1]
   def change
     add_index :users, [:a, :b, :c, :d]
   end
@@ -681,7 +715,7 @@ 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[7.1]
   def change
     add_index :users, [:b, :d]
   end
@@ -695,7 +729,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[7.1]
   def change
     safety_assured { remove_column :users, :some_column }
   end
@@ -793,25 +827,6 @@ 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.
@@ -855,12 +870,31 @@ production:
 
 For HTTP connections, Redis, and other services, check out [this guide](https://github.com/ankane/the-ultimate-guide-to-ruby-timeouts).
 
+## Lock Timeout Retries [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 = 20230101000000
 ```
 
 Use the version from your latest migration.

data/lib/strong_migrations/checker.rb

@@ -48,6 +48,8 @@ module StrongMigrations
           check_add_index(*args)
         when :add_reference, :add_belongs_to
           check_add_reference(method, *args)
+        when :add_unique_constraint
+          check_add_unique_constraint(*args)
         when :change_column
           check_change_column(*args)
         when :change_column_default
@@ -123,6 +125,10 @@ module StrongMigrations
       end
     end
 
+    def version_safe?
+      version && version <= StrongMigrations.start_after
+    end
+
     private
 
     def check_version_supported
@@ -163,11 +169,7 @@ module StrongMigrations
     end
 
     def safe?
-      self.class.safe || ENV["SAFETY_ASSURED"] || (direction == :down && !StrongMigrations.check_down) || version_safe?
-    end
-
-    def version_safe?
-      version && version <= StrongMigrations.start_after
+      self.class.safe || ENV["SAFETY_ASSURED"] || (direction == :down && !StrongMigrations.check_down) || version_safe? || @migration.reverting?
     end
 
     def version

data/lib/strong_migrations/checks.rb

@@ -180,6 +180,21 @@ Then add the foreign key in separate migrations."
       end
     end
 
+    def check_add_unique_constraint(*args)
+      args.extract_options!
+      table, column = args
+
+      # column and using_index cannot be used together
+      # check for column to ensure error message can be generated
+      if column && !new_table?(table)
+        index_name = connection.index_name(table, {column: column})
+        raise_error :add_unique_constraint,
+          index_command: command_str(:add_index, [table, column, {unique: true, algorithm: :concurrently}]),
+          constraint_command: command_str(:add_unique_constraint, [table, {using_index: index_name}]),
+          remove_command: command_str(:remove_unique_constraint, [table, column])
+      end
+    end
+
     def check_change_column(*args)
       options = args.extract_options!
       table, column, type = args

data/lib/strong_migrations/error_messages.rb

@@ -88,7 +88,7 @@ in your application. A safer approach is to:
 
 1. Create a new column
 2. Write to both columns
-3. Backfill data from the old column to new column
+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",
@@ -99,7 +99,7 @@ in your application. A safer approach is to:
 
 1. Create a new table. Don't forget to recreate indexes from the old 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",
@@ -244,7 +244,24 @@ end",
 Use disable_ddl_transaction! or a separate migration.",
 
     add_exclusion_constraint:
-"Adding an exclusion constraint blocks reads and writes while every row is checked."
+"Adding an exclusion constraint blocks reads and writes while every row is checked.",
+
+    add_unique_constraint:
+"Adding a unique constraint creates a unique index, which blocks reads and writes.
+Instead, create a unique index concurrently, then use it for the constraint.
+
+class %{migration_name} < ActiveRecord::Migration%{migration_suffix}
+  disable_ddl_transaction!
+
+  def up
+    %{index_command}
+    %{constraint_command}
+  end
+
+  def down
+    %{remove_command}
+  end
+end"
   }
   self.enabled_checks = (error_messages.keys - [:remove_index]).map { |k| [k, {}] }.to_h
 end

data/lib/strong_migrations/migration.rb

@@ -20,6 +20,14 @@ module StrongMigrations
     end
     ruby2_keywords(:method_missing) if respond_to?(:ruby2_keywords, true)
 
+    def revert(*)
+      if strong_migrations_checker.version_safe?
+        safety_assured { super }
+      else
+        super
+      end
+    end
+
     def safety_assured
       strong_migrations_checker.class.safety_assured do
         yield

data/lib/strong_migrations/version.rb

@@ -1,3 +1,3 @@
 module StrongMigrations
-  VERSION = "1.6.3"
+  VERSION = "1.7.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: strong_migrations
 version: !ruby/object:Gem::Version
-  version: 1.6.3
+  version: 1.7.0
 platform: ruby
 authors:
 - Andrew Kane
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-09-20 00:00:00.000000000 Z
+date: 2024-01-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -75,7 +75,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: Catch unsafe migrations in development