strong_migrations 2.6.0 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33d90fe56d07dcdf864739aeae07dac0c63b6504460299724bc293a43c5aeb7e
-  data.tar.gz: 9e7ea3be4a0d3b8b03bcb2e4e6b5f6b4425057388a4b8ae52a7263d5497d5de8
+  metadata.gz: 250e255ba679a0e581fb86ed13b2824cf5749b7dc3ac5bf0a26bfffebe314fb8
+  data.tar.gz: d91882cb145d2f59a688e41e0d20301c6ca41d3e5e9790be9996eb256cc26dd2
 SHA512:
-  metadata.gz: fe975030ddbdd8bce5f8bc1a18498e67e505627618a47d201e916d6c0ca21f846852ef08dc923e3a8626c2634fdcfa4d38fe9b674bc13b58d7a0c5064a012f0a
-  data.tar.gz: 4e0fe03e8ac9cb3872a7d9179f5902a8044587ffab5b22c02c7bbf63303a9bee48e195c6b77f30491f382ff7435a22cfe9e92c0a6dc53f145cf67d1f21cfb109
+  metadata.gz: b0bba6d87fd23e3bf68d8a8274cc6d22346a73f0001e8078f99f3c7a039772e39ded14138a2ad87eb7476f855a56647a1e07f84e7dadc96d5f3df53aebd27c9a
+  data.tar.gz: b985a53c42f12ec3268f6fd2570bdb2cdf777f80217b17a68872e86d4366b5939a702c0b8551b0ddab4f44ddfb9ef5da8a3f74ca97365124a086d46c2fe66f10

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2.7.0 (2026-04-25)
+
+- Added check for `add_foreign_key` with MySQL and MariaDB
+- Added check for `add_column` with callable default value with MySQL and MariaDB
+
 ## 2.6.0 (2026-04-07)
 
 - Added check for `algorithm: :copy` with MySQL and MariaDB

data/README.md

@@ -66,6 +66,7 @@ Potentially dangerous operations:
 - [creating a table with the force option](#creating-a-table-with-the-force-option)
 - [adding an auto-incrementing column](#adding-an-auto-incrementing-column)
 - [adding a stored generated column](#adding-a-stored-generated-column)
+- [adding a foreign key](#adding-a-foreign-key)
 - [adding a check constraint](#adding-a-check-constraint)
 - [executing SQL directly](#executing-SQL-directly)
 - [backfilling data](#backfilling-data)
@@ -74,18 +75,18 @@ 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)
 - [adding a column with a volatile default value](#adding-a-column-with-a-volatile-default-value)
+- [setting NOT NULL on an existing column](#setting-not-null-on-an-existing-column)
 - [renaming a schema](#renaming-a-schema)
 
 MySQL and MariaDB-specific checks:
 
 - [using the COPY algorithm](#using-the-copy-algorithm)
 - [using shared or exclusive locking](#using-shared-or-exclusive-locking)
+- [adding a column with an expression default value](#adding-a-column-with-an-expression-default-value)
 
 Best practices:
 
@@ -297,9 +298,80 @@ end
 
 Add a non-generated column and use callbacks or triggers instead (or a virtual generated column with MySQL and MariaDB).
 
+### Adding a foreign key
+
+:turtle: Safe by default available for Postgres
+
+#### Bad
+
+Adding a foreign key blocks writes on both tables.
+
+```ruby
+class AddForeignKeyOnUsers < ActiveRecord::Migration[8.1]
+  def change
+    add_foreign_key :users, :orders
+  end
+end
+```
+
+or
+
+```ruby
+class AddReferenceToUsers < ActiveRecord::Migration[8.1]
+  def change
+    add_reference :users, :order, foreign_key: true
+  end
+end
+```
+
+#### Good - Postgres
+
+Add the foreign key without validating existing rows:
+
+```ruby
+class AddForeignKeyOnUsers < ActiveRecord::Migration[8.1]
+  def change
+    add_foreign_key :users, :orders, validate: false
+  end
+end
+```
+
+Then validate them in a separate migration.
+
+```ruby
+class ValidateForeignKeyOnUsers < ActiveRecord::Migration[8.1]
+  def change
+    validate_foreign_key :users, :orders
+  end
+end
+```
+
+#### Good - MySQL and MariaDB
+
+If you are 100% sure all rows are valid and migrations do not use a connection pooler, you can add the foreign key without validating existing rows:
+
+```ruby
+class AddForeignKeyOnUsers < ActiveRecord::Migration[8.1]
+  def up
+    safety_assured do
+      begin
+        execute "SET SESSION foreign_key_checks = 0"
+        add_foreign_key :users, :orders
+      ensure
+        execute "SET SESSION foreign_key_checks = 1"
+      end
+    end
+  end
+
+  def down
+    remove_foreign_key :users, :orders
+  end
+end
+```
+
 ### Adding a check constraint
 
-:turtle: Safe by default available
+:turtle: Safe by default available for Postgres
 
 #### Bad
 
@@ -389,6 +461,8 @@ end
 
 Note: If backfilling with a method other than `update_all`, use `User.reset_column_information` to ensure the model has up-to-date column information.
 
+## Postgres Checks
+
 ### Adding an index non-concurrently
 
 :turtle: Safe by default available
@@ -457,54 +531,6 @@ class AddReferenceToUsers < ActiveRecord::Migration[8.1]
 end
 ```
 
-### Adding a foreign key
-
-:turtle: Safe by default available
-
-#### Bad
-
-In Postgres, adding a foreign key blocks writes on both tables.
-
-```ruby
-class AddForeignKeyOnUsers < ActiveRecord::Migration[8.1]
-  def change
-    add_foreign_key :users, :orders
-  end
-end
-```
-
-or
-
-```ruby
-class AddReferenceToUsers < ActiveRecord::Migration[8.1]
-  def change
-    add_reference :users, :order, foreign_key: true
-  end
-end
-```
-
-#### Good
-
-Add the foreign key without validating existing rows:
-
-```ruby
-class AddForeignKeyOnUsers < ActiveRecord::Migration[8.1]
-  def change
-    add_foreign_key :users, :orders, validate: false
-  end
-end
-```
-
-Then validate them in a separate migration.
-
-```ruby
-class ValidateForeignKeyOnUsers < ActiveRecord::Migration[8.1]
-  def change
-    validate_foreign_key :users, :orders
-  end
-end
-```
-
 ### Adding a unique constraint
 
 #### Bad
@@ -582,6 +608,39 @@ class AddPropertiesToUsers < ActiveRecord::Migration[8.1]
 end
 ```
 
+### Adding a column with a volatile default value
+
+#### Bad
+
+Adding a column with a volatile default value to an existing table causes the entire table to be rewritten. During this time, reads and writes are blocked.
+
+```ruby
+class AddSomeColumnToUsers < ActiveRecord::Migration[8.1]
+  def change
+    add_column :users, :some_column, :uuid, default: "gen_random_uuid()"
+  end
+end
+```
+
+#### Good
+
+Instead, add the column without a default value, then change the default.
+
+```ruby
+class AddSomeColumnToUsers < ActiveRecord::Migration[8.1]
+  def up
+    add_column :users, :some_column, :uuid
+    change_column_default :users, :some_column, "gen_random_uuid()"
+  end
+
+  def down
+    remove_column :users, :some_column
+  end
+end
+```
+
+Then [backfill the data](#backfilling-data).
+
 ### Setting NOT NULL on an existing column
 
 :turtle: Safe by default available
@@ -627,39 +686,6 @@ class ValidateSomeColumnNotNull < ActiveRecord::Migration[8.1]
 end
 ```
 
-### Adding a column with a volatile default value
-
-#### Bad
-
-Adding a column with a volatile default value to an existing table causes the entire table to be rewritten. During this time, reads and writes are blocked.
-
-```ruby
-class AddSomeColumnToUsers < ActiveRecord::Migration[8.1]
-  def change
-    add_column :users, :some_column, :uuid, default: "gen_random_uuid()"
-  end
-end
-```
-
-#### Good
-
-Instead, add the column without a default value, then change the default.
-
-```ruby
-class AddSomeColumnToUsers < ActiveRecord::Migration[8.1]
-  def up
-    add_column :users, :some_column, :uuid
-    change_column_default :users, :some_column, from: nil, to: "gen_random_uuid()"
-  end
-
-  def down
-    remove_column :users, :some_column
-  end
-end
-```
-
-Then [backfill the data](#backfilling-data).
-
 ### Renaming a schema
 
 #### Bad
@@ -685,6 +711,8 @@ A safer approach is to:
 5. Stop writing to the old schema
 6. Drop the old schema
 
+## MySQL and MariaDB Checks
+
 ### Using the COPY algorithm
 
 #### Bad
@@ -737,6 +765,41 @@ class AddSomeIndexToUsers < ActiveRecord::Migration[8.2]
 end
 ```
 
+### Adding a column with an expression default value
+
+#### Bad
+
+In MySQL and MariaDB, adding a column with an expression default value to an existing table causes the entire table to be rewritten. During this time, writes are blocked.
+
+```ruby
+class AddSomeColumnToUsers < ActiveRecord::Migration[8.1]
+  def change
+    add_column :users, :some_column, :datetime, default: -> { "(now())" }
+  end
+end
+```
+
+#### Good
+
+Instead, add the column without a default value, then change the default.
+
+```ruby
+class AddSomeColumnToUsers < ActiveRecord::Migration[8.1]
+  def up
+    add_column :users, :some_column, :datetime
+    change_column_default :users, :some_column, -> { "(now())" }
+  end
+
+  def down
+    remove_column :users, :some_column
+  end
+end
+```
+
+Then [backfill the data](#backfilling-data).
+
+## Best Practices
+
 ### Keeping non-unique indexes to three columns or less
 
 #### Bad
@@ -876,7 +939,7 @@ ALTER ROLE myuser SET lock_timeout = '10s';
 ALTER ROLE myuser SET statement_timeout = '1h';
 ```
 
-Note: If you use PgBouncer in transaction mode, you must set timeouts on the database user.
+Note: If you use a connection pooler like PgBouncer in transaction mode, you must set timeouts on the database user.
 
 ## App Timeouts
 
@@ -892,7 +955,7 @@ production:
     lock_timeout: 10s
 ```
 
-Note: If you use PgBouncer in transaction mode, you must set the statement and lock timeouts on the database user as shown above.
+Note: If you use a connection pooler like PgBouncer in transaction mode, you must set the statement and lock timeouts on the database user as shown above.
 
 For MySQL:
 

data/lib/strong_migrations/checks.rb

@@ -35,9 +35,18 @@ module StrongMigrations
       # keep track of new columns of change_column_default check
       @new_columns << [table.to_s, column.to_s]
 
-      # Check key since DEFAULT NULL behaves differently from no default
+      # adding a column with a volatile default is not safe with Postgres
+      # https://www.postgresql.org/docs/current/sql-altertable.html#SQL-ALTERTABLE-NOTES
+      # functions like random() and clock_timestamp() are volatile
+      # functions like concat('A', 'B') are safe
+      # default expressions in Postgres cannot reference other columns
       #
-      # Also, Active Record has special case for uuid columns that allows function default values
+      # adding a column with an expression default is not safe with MySQL
+      # even constant expressions like (3) are not safe
+      # literals like 3 are safe
+      #
+      # Active Record quotes default values except for procs
+      # there is also a special case for uuid columns
       # https://github.com/rails/rails/blob/v7.0.3.1/activerecord/lib/active_record/connection_adapters/postgresql/quoting.rb#L92-L93
       if !default.nil? && (!adapter.add_column_default_safe? || (volatile = (postgresql? && type.to_s == "uuid" && default.to_s.include?("()") && adapter.default_volatile?(default))))
         if options[:null] == false
@@ -52,13 +61,14 @@ module StrongMigrations
           code: backfill_code(table, column, default, volatile),
           append: append,
           rewrite_blocks: adapter.rewrite_blocks,
-          default_type: (volatile ? "volatile" : "non-null")
-      elsif default.is_a?(Proc) && postgresql?
-        # adding a column with a VOLATILE default is not safe
-        # https://www.postgresql.org/docs/current/sql-altertable.html#SQL-ALTERTABLE-NOTES
-        # functions like random() and clock_timestamp() are VOLATILE
+          default_type: volatile ? "volatile" : "non-null"
+      elsif default.is_a?(Proc)
         # check for Proc to match Active Record
-        raise_error :add_column_default_callable
+        raise_error :add_column_default_callable,
+          add_command: command_str("add_column", [table, column, type, options.except(:default)]),
+          change_command: command_str("change_column_default", [table, column]),
+          remove_command: command_str("remove_column", [table, column]),
+          default_type: postgresql? ? "volatile" : "an expression"
       end
 
       if type.to_s == "json" && postgresql?
@@ -117,6 +127,11 @@ module StrongMigrations
         raise_error :add_foreign_key,
           add_foreign_key_code: command_str("add_foreign_key", [from_table, to_table, options.merge(validate: false)]),
           validate_foreign_key_code: command_str("validate_foreign_key", [from_table, to_table])
+      elsif mysql? || mariadb?
+        raise_error :add_foreign_key_mysql,
+          add_foreign_key_code: command_str("add_foreign_key", [from_table, to_table, options]),
+          # TODO exclude some options?
+          remove_foreign_key_code: command_str("remove_foreign_key", [from_table, to_table, options])
       end
     end
 
@@ -187,6 +202,13 @@ module StrongMigrations
             command: command_str(method, [table, reference, options]),
             append: append
         end
+      elsif mysql? || mariadb?
+        if options[:foreign_key]
+          raise_error :add_reference,
+            headline: "Adding a foreign key blocks writes on both tables.",
+            command: command_str(method, [table, reference, options.except(:foreign_key)]),
+            append: "\n\nThen add the foreign key in a separate migration."
+        end
       end
 
       check_algorithm_option("add_reference", *args, **options)

data/lib/strong_migrations/error_messages.rb

@@ -27,8 +27,23 @@ end",
 
     add_column_default_callable:
 "Strong Migrations does not support inspecting callable default values.
-Please make really sure you're not calling a VOLATILE function,
-then wrap it in a safety_assured { ... } block.",
+
+If the default value is %{default_type}, add the column without a default value, then change the default.
+
+class %{migration_name} < ActiveRecord::Migration%{migration_suffix}
+  def up
+    %{add_command}
+    %{change_command}, -> { ... }
+  end
+
+  def down
+    %{remove_command}
+  end
+end
+
+Then backfill the existing rows in the Rails console or a separate migration with disable_ddl_transaction!.
+
+Otherwise, wrap this step in a safety_assured { ... } block.",
 
     add_column_json:
 "There's no equality operator for the json column type, which can cause errors for
@@ -235,6 +250,28 @@ class Validate%{migration_name} < ActiveRecord::Migration%{migration_suffix}
   end
 end",
 
+    add_foreign_key_mysql:
+"Adding a foreign key blocks writes on both tables. If you are 100% sure
+all rows are valid and migrations do not use a connection pooler,
+you can add the foreign key without validating existing rows.
+
+class %{migration_name} < ActiveRecord::Migration%{migration_suffix}
+  def up
+    safety_assured do
+      begin
+        execute \"SET SESSION foreign_key_checks = 0\"
+        %{add_foreign_key_code}
+      ensure
+        execute \"SET SESSION foreign_key_checks = 1\"
+      end
+    end
+  end
+
+  def down
+    %{remove_foreign_key_code}
+  end
+end",
+
     validate_foreign_key:
 "Validating a foreign key while writes are blocked is dangerous.
 Use disable_ddl_transaction! or a separate migration.",

data/lib/strong_migrations/version.rb

@@ -1,3 +1,3 @@
 module StrongMigrations
-  VERSION = "2.6.0"
+  VERSION = "2.7.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: strong_migrations
 version: !ruby/object:Gem::Version
-  version: 2.6.0
+  version: 2.7.0
 platform: ruby
 authors:
 - Andrew Kane