strong_migrations 0.7.9 → 1.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2fb3fbcc5caf98759ebe2ef05a4ef011eca91924e479647d36e2b261baf2c8e
-  data.tar.gz: '0118bd4e05814f2d531a659a724237080763843bd6cb3ff0b880447348004585'
+  metadata.gz: 7444023bd5f0829a289ebc9d222a28f041a4e3789224438f9fd6bffa01fa6668
+  data.tar.gz: feb5010616cc8ef6cf36088be7a67bb0d74272cde79d0e9a0a442272bfa92d99
 SHA512:
-  metadata.gz: 7a04ea74876b44c645c9cba04c2f7b4932fcc0637eedd78b544dadf40272c84fb0461420e66c49c991c214f5d36b53acbface0347af25cb65c1e9c1251375886
-  data.tar.gz: 8e97437c5eae3b3aa6508e08c21aa8caf648a03989e621d37c165d1a2412a3cc67784d0923d47e7f814475bb000c6e68e93bf5ce6ef5dbd83f03fc399bb85b4c
+  metadata.gz: '0599a3fef628ec724471ef53b7ad7358831e6b638bdd0ca3b7cb79c1b416da6c044793ecca5475f5e602e8a7d1235ced3ff3fda526f31b9c4a56990c8531f9b4'
+  data.tar.gz: 6aac91ecb348c6a04c25511adf7df5d3e97823f6b9acdfbfd86bac50c4f5856f15fdcc271f00d0fc6f1e5d2cfdbaf3da5e056b1476aaf9b224e7df89b9737e01

data/CHANGELOG.md

@@ -1,3 +1,83 @@
+## 1.4.4 (2023-03-08)
+
+- Fixed `add_foreign_key` with `name` and `column` options with `safe_by_default`
+
+## 1.4.3 (2023-02-19)
+
+- Fixed check for `change_column` to account for charset with MySQL and MariaDB
+
+## 1.4.2 (2023-01-29)
+
+- Added `alphabetize_schema` option
+
+## 1.4.1 (2023-01-05)
+
+- Added support for multiple databases to `target_version`
+
+## 1.4.0 (2022-10-31)
+
+- Added check for `add_exclusion_constraint`
+- Added support for `RACK_ENV`
+- Fixed error when `Rails` defined without `Rails.env`
+- Fixed error with `change_column_null` when table does not exist
+
+## 1.3.2 (2022-10-09)
+
+- Improved error message for `add_column` with `default: nil` with Postgres 10
+
+## 1.3.1 (2022-09-21)
+
+- Fixed check for `add_column` with `default: nil` with Postgres 10
+
+## 1.3.0 (2022-08-30)
+
+- Added check for `add_column` with `uuid` type and volatile default value
+
+## 1.2.0 (2022-06-10)
+
+- Added check for index corruption with Postgres 14.0 to 14.3
+
+## 1.1.0 (2022-06-08)
+
+- Added check for `force` option with `create_join_table`
+- Improved errors for extra arguments
+- Fixed ignoring extra arguments with `safe_by_default`
+- Fixed missing options with `remove_index` and `safe_by_default`
+
+## 1.0.0 (2022-03-21)
+
+New safe operations with MySQL and MariaDB
+
+- Setting `NOT NULL` on an existing column with strict mode enabled
+
+New safe operations with Postgres
+
+- Changing between `text` and `citext` when not indexed
+- Changing a `string` column to a `citext` column when not indexed
+- Changing a `citext` column to a `string` column with no `:limit` when not indexed
+- Changing a `cidr` column to an `inet` column
+- Increasing `:precision` of an `interval` or `time` column
+
+New unsafe operations with Postgres
+
+- Adding a column with a callable default value
+- Decreasing `:precision` of a `datetime` column
+- Decreasing `:limit` of a `timestamptz` column
+- Passing a default value to `change_column_null`
+
+Other
+
+- Added experimental support for lock timeout retries
+- Added `target_sql_mode` option
+- Added error for `change_column_null` with default value with `safe_by_default` option
+- Fixed instructions for `remove_columns` with options
+- Dropped support for Postgres < 10, MySQL < 5.7, and MariaDB < 10.2
+
+## 0.8.0 (2022-02-09)
+
+- Fixed error with versioned schema with Active Record 7.0.2+
+- Dropped support for Ruby < 2.6 and Active Record < 5.2
+
 ## 0.7.9 (2021-12-15)
 
 - Fixed error with multiple databases with Active Record 7

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2013 Bob Remeika and David Waller, 2015-2021 Andrew Kane
+Copyright (c) 2013 Bob Remeika and David Waller, 2015-2022 Andrew Kane
 
 MIT License
 

data/README.md

@@ -4,7 +4,7 @@ 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)
 
@@ -15,7 +15,7 @@ Supports for PostgreSQL, MySQL, and MariaDB
 Add this line to your application’s Gemfile:
 
 ```ruby
-gem 'strong_migrations'
+gem "strong_migrations"
 ```
 
 And run:
@@ -67,7 +67,6 @@ Potentially dangerous operations:
 - [renaming a table](#renaming-a-table)
 - [creating a table with the force option](#creating-a-table-with-the-force-option)
 - [adding a check constraint](#adding-a-check-constraint)
-- [setting NOT NULL on an existing column](#setting-not-null-on-an-existing-column)
 - [executing SQL directly](#executing-SQL-directly)
 
 Postgres-specific checks:
@@ -75,7 +74,9 @@ 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)
 
 Best practices:
 
@@ -107,7 +108,7 @@ end
   end
   ```
 
-2. Deploy code
+2. Deploy the code
 3. Write a migration to remove the column (wrap in `safety_assured` block)
 
   ```ruby
@@ -118,7 +119,8 @@ 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
 
@@ -134,7 +136,7 @@ class AddSomeColumnToUsers < ActiveRecord::Migration[7.0]
 end
 ```
 
-In Postgres 11+, MySQL 8.0.12+, and MariaDB 10.3.2+, this no longer requires a table rewrite and is safe.
+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
 
@@ -203,19 +205,26 @@ class ChangeSomeColumnType < ActiveRecord::Migration[7.0]
 end
 ```
 
-A few changes don’t require a table rewrite (and are safe) in Postgres:
+Some changes don’t require a table rewrite and are safe in Postgres:
 
-- Increasing the length limit of a `varchar` column (or removing the limit)
-- Changing a `varchar` column to a `text` column
-- Changing a `text` column to a `varchar` column with no length limit
-- 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 limit of a `varchar` column from under 255 up to 255
-- Increasing the length limit of a `varchar` column from over 255 to the max limit
+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
 
@@ -352,86 +361,6 @@ end
 
 [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).
 
-### Setting NOT NULL on an existing column
-
-:turtle: Safe by default available
-
-#### Bad
-
-Setting `NOT NULL` on an existing column blocks reads and writes while every row is checked.
-
-```ruby
-class SetSomeColumnNotNull < ActiveRecord::Migration[7.0]
-  def change
-    change_column_null :users, :some_column, false
-  end
-end
-```
-
-#### Good - Postgres
-
-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]
-  def change
-    safety_assured do
-      execute 'ALTER TABLE "users" ADD CONSTRAINT "users_some_column_null" CHECK ("some_column" IS NOT NULL) NOT VALID'
-    end
-  end
-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:
-
-```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]
-  def change
-    safety_assured do
-      execute 'ALTER TABLE "users" VALIDATE CONSTRAINT "users_some_column_null"'
-    end
-
-    # 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"'
-    end
-  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.
-
 ### 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:
@@ -540,9 +469,7 @@ end
 
 #### Good
 
-Add the foreign key without validating existing rows, then validate them in a separate migration.
-
-For Rails 5.2+, use:
+Add the foreign key without validating existing rows:
 
 ```ruby
 class AddForeignKeyOnUsers < ActiveRecord::Migration[7.0]
@@ -552,7 +479,7 @@ class AddForeignKeyOnUsers < ActiveRecord::Migration[7.0]
 end
 ```
 
-Then:
+Then validate them in a separate migration.
 
 ```ruby
 class ValidateForeignKeyOnUsers < ActiveRecord::Migration[7.0]
@@ -562,30 +489,24 @@ class ValidateForeignKeyOnUsers < ActiveRecord::Migration[7.0]
 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:
+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
@@ -612,6 +533,82 @@ class AddPropertiesToUsers < ActiveRecord::Migration[7.0]
 end
 ```
 
+### Setting NOT NULL on an existing column
+
+:turtle: Safe by default available
+
+#### Bad
+
+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]
+  def change
+    change_column_null :users, :some_column, false
+  end
+end
+```
+
+#### Good
+
+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]
+  def change
+    safety_assured do
+      execute 'ALTER TABLE "users" ADD CONSTRAINT "users_some_column_null" CHECK ("some_column" IS NOT NULL) NOT VALID'
+    end
+  end
+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:
+
+```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]
+  def change
+    safety_assured do
+      execute 'ALTER TABLE "users" VALIDATE CONSTRAINT "users_some_column_null"'
+    end
+
+    # 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"'
+    end
+  end
+end
+```
+
 ### Keeping non-unique indexes to three columns or less
 
 #### Bad
@@ -703,7 +700,7 @@ 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
 
@@ -721,7 +718,7 @@ 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.
 
 ## Migration Timeouts
 
@@ -743,6 +740,25 @@ 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.
@@ -808,6 +824,12 @@ The major version works well for Postgres, while the full version is recommended
 
 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:
@@ -818,23 +840,18 @@ StrongMigrations.auto_analyze = true
 
 ## Faster Migrations
 
-Only dump the schema when adding a new migration. If you use Git, add to the end of your `Rakefile`:
+Only dump the schema when adding a new migration. If you use Git, add to `config/environments/development.rb`:
 
 ```rb
-task :faster_migrations do
-  ActiveRecord::Base.dump_schema_after_migration = Rails.env.development? &&
-    `git status db/migrate/ --porcelain`.present?
-end
-
-task "db:migrate": "faster_migrations"
+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"
+StrongMigrations.alphabetize_schema = true
 ```
 
 ## Permissions

data/lib/strong_migrations/adapters/abstract_adapter.rb

@@ -0,0 +1,77 @@
+module StrongMigrations
+  module Adapters
+    class AbstractAdapter
+      def initialize(checker)
+        @checker = checker
+      end
+
+      def name
+        "Unknown"
+      end
+
+      def min_version
+      end
+
+      def set_statement_timeout(timeout)
+        raise StrongMigrations::Error, "Statement timeout not supported for this database"
+      end
+
+      def set_lock_timeout(timeout)
+        raise StrongMigrations::Error, "Lock timeout not supported for this database"
+      end
+
+      def check_lock_timeout(limit)
+        # do nothing
+      end
+
+      def add_column_default_safe?
+        false
+      end
+
+      def change_type_safe?(table, column, type, options, existing_column, existing_type)
+        false
+      end
+
+      def rewrite_blocks
+        "reads and writes"
+      end
+
+      private
+
+      def connection
+        @checker.send(:connection)
+      end
+
+      def select_all(statement)
+        connection.select_all(statement)
+      end
+
+      def target_version(target_version)
+        target_version ||= StrongMigrations.target_version
+        version =
+          if target_version && StrongMigrations.developer_env?
+            if target_version.is_a?(Hash)
+              # Active Record 6.0 supports multiple databases
+              # but connection.pool.spec.name always returns "primary"
+              # in migrations with rails db:migrate
+              if ActiveRecord::VERSION::STRING.to_f < 6.1
+                # error class is not shown in db:migrate output so ensure message is descriptive
+                raise StrongMigrations::Error, "StrongMigrations.target_version does not support multiple databases for Active Record < 6.1"
+              end
+
+              db_config_name = connection.pool.db_config.name
+              target_version.stringify_keys.fetch(db_config_name) do
+                # error class is not shown in db:migrate output so ensure message is descriptive
+                raise StrongMigrations::Error, "StrongMigrations.target_version is not configured for :#{db_config_name} database"
+              end.to_s
+            else
+              target_version.to_s
+            end
+          else
+            yield
+          end
+        Gem::Version.new(version)
+      end
+    end
+  end
+end

data/lib/strong_migrations/adapters/mariadb_adapter.rb

@@ -0,0 +1,32 @@
+module StrongMigrations
+  module Adapters
+    class MariaDBAdapter < MySQLAdapter
+      def name
+        "MariaDB"
+      end
+
+      def min_version
+        "10.2"
+      end
+
+      def server_version
+        @server_version ||= begin
+          target_version(StrongMigrations.target_mariadb_version) do
+            select_all("SELECT VERSION()").first["VERSION()"].split("-").first
+          end
+        end
+      end
+
+      def set_statement_timeout(timeout)
+        # fix deprecation warning with Active Record 7.1
+        timeout = timeout.value if timeout.is_a?(ActiveSupport::Duration)
+
+        select_all("SET max_statement_time = #{connection.quote(timeout)}")
+      end
+
+      def add_column_default_safe?
+        server_version >= Gem::Version.new("10.3.2")
+      end
+    end
+  end
+end