nandi 2.1.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70ecd10143c43ea10379b4dc7c6d1bbf4d4bc3d654cbf15dde273b49cf229a08
-  data.tar.gz: 0b64d84387f9e4be7eed24ddadc9f74d58d118cca7d91e0e526f680ee5fcfba8
+  metadata.gz: 986532981584b1518a8422a2cc212ed963782fb31554012a0e2b4da50bf8a3db
+  data.tar.gz: 282b4f7c95256f6a8af1090b82a2324d0cc12e4570bf22608c219d8486cb5334
 SHA512:
-  metadata.gz: 8f057aa2c71d7169d6482a2fbc2fe7fb4721bfeef3b650a74c09e002fe9b7eff4fa3479b5e2c0af7940d91d88ca71dcddab0fbd169077fee1ec00cb26e447f60
-  data.tar.gz: 112cc9d2d08c4802767d2c481d11f30ff87844c765a0afcb0224dcb1bbfc1c69dc4d7c6dd618a79d744bb7fdff03f2945f216f2eba90511d99b6c4ad58fcdd59
+  metadata.gz: 7788cca1a5ca77b8e8e04decc6819b41078936452f3ab2cae00a3b35ca6c338f4fb4870e2d8eb11f4f3109029c41a2ccd327fb980417e1b95c1bf48644bca23e
+  data.tar.gz: 2331b4022d381b2863ecbf2429365aa2870fb39386fde1cb0aa27ea8800fc3c7777490896a2d55af95696d8b0457c2f485890f5dcd8878019f1a50b2ea28af09

data/README.md

@@ -473,6 +473,16 @@ Register a block to be called on output, for example a code formatter. Whatever
 config.post_process { |migration| MyFormatter.format(migration) }
 ```
 
+#register_migration_modifier(klass)
+
+Register a custom migration modifier. Migration modifiers inherit from `Nandi::MigrationModifiers::Base` and implement `.up(instructions)`, `.down(instructions)`, or both. Nandi calls the appropriate method based on migration direction.
+
+Nandi ships with one built-in modifier, `Nandi::MigrationModifiers::CreateTableValidatesFks`, which is enabled by default. See the [Migration Modifiers](#migration-modifiers) section for details.
+
+```rb
+config.register_migration_modifier(MyCustomModifier)
+```
+
 #register_method(name, klass)
 
 Register a custom DDL method.
@@ -483,6 +493,56 @@ Parameters:
 
 `klass` (Class) — The class to initialise with the arguments to the method. It should define a `template` instance method which will return a subclass of Cell::ViewModel from the Cells templating library and a `procedure` method that returns the name of the method. It may optionally define a `mixins` method, which will return an array of `Module`s to be mixed into any migration that uses this method.
 
+## Migration Modifiers
+
+Migration modifiers allow instructions to change their behaviour based on other instructions in the same migration. After the direction block runs, Nandi iterates over all configured modifiers and passes the full instruction list to each one.
+
+### Built-in: `CreateTableValidatesFks`
+
+When you create a table and add a foreign key on that same table in a single migration, the FK does not need the usual `NOT VALID` deferral — the table is brand new, so there are no existing rows to validate. Nandi detects this automatically and sets `validate: true` on the relevant FK instructions:
+
+```rb
+class CreatePaymentsWithFk < Nandi::Migration
+  def up
+    create_table :payments do |t|
+      t.bigint :mandate_id, null: false
+    end
+
+    add_foreign_key :payments, :mandates
+  end
+end
+```
+
+The compiled output will include `validate: true` on the `add_foreign_key` call, skipping the separate validate step that would otherwise be required.
+
+This modifier is enabled by default. To disable it, you would need to replace `config.migration_modifiers` entirely — there is no built-in opt-out.
+
+### Writing a custom modifier
+
+Inherit from `Nandi::MigrationModifiers::Base` and override `.up`, `.down`, or both. The base class provides no-op defaults so you only implement what you need:
+
+```rb
+class MyModifier < Nandi::MigrationModifiers::Base
+  def self.up(instructions)
+    # inspect and mutate instructions for the up direction
+  end
+
+  def self.down(instructions)
+    # inspect and mutate instructions for the down direction
+  end
+end
+```
+
+Register it in your Nandi initializer:
+
+```rb
+Nandi.configure do |config|
+  config.register_migration_modifier(MyModifier)
+end
+```
+
+Modifiers are applied in registration order, after all built-in modifiers.
+
 ## Multi-Database Support
 
 Nandi 2.0+ supports managing migrations for multiple databases within a single Rails application. 

data/lib/nandi/config.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "nandi/migration_modifiers"
 require "nandi/renderers"
 require "nandi/lockfile"
 require "nandi/multi_database"
@@ -30,13 +31,18 @@ module Nandi
     attr_writer :lockfile_directory
 
     # @api private
-    attr_reader :post_processor, :custom_methods
+    attr_reader :post_processor, :custom_methods, :migration_modifiers
 
     def initialize(renderer: Renderers::ActiveRecord)
       @renderer = renderer
       @custom_methods = {}
       @compile_files = DEFAULT_COMPILE_FILES
       @lockfile_directory = DEFAULT_LOCKFILE_DIRECTORY
+      @migration_modifiers = [MigrationModifiers::CreateTableValidatesFks]
+    end
+
+    def register_migration_modifier(klass)
+      @migration_modifiers << klass
     end
 
     # Register a block to be called on output, for example a code formatter. Whatever is
@@ -73,11 +79,11 @@ module Nandi
     def migration_directory(database_name = nil) = config(database_name).migration_directory
     def output_directory(database_name = nil) = config(database_name).output_directory
     def access_exclusive_lock_timeout(database_name = nil) = config(database_name).access_exclusive_lock_timeout
-    def access_exclusive_lock_timeout_limit(database_name = nil) = config(database_name).access_exclusive_lock_timeout_limit
+    def access_exclusive_lock_timeout_max(database_name = nil) = config(database_name).access_exclusive_lock_timeout_max
     def access_exclusive_statement_timeout(database_name = nil) = config(database_name).access_exclusive_statement_timeout
-    def access_exclusive_statement_timeout_limit(database_name = nil) = config(database_name).access_exclusive_statement_timeout_limit
-    def concurrent_lock_timeout_limit(database_name = nil) = config(database_name).concurrent_lock_timeout_limit
-    def concurrent_statement_timeout_limit(database_name = nil) = config(database_name).concurrent_statement_timeout_limit
+    def access_exclusive_statement_timeout_max(database_name = nil) = config(database_name).access_exclusive_statement_timeout_max
+    def concurrent_lock_timeout_min(database_name = nil) = config(database_name).concurrent_lock_timeout_min
+    def concurrent_statement_timeout_min(database_name = nil) = config(database_name).concurrent_statement_timeout_min
     def concurrent_lock_timeout(database_name = nil) = config(database_name).concurrent_lock_timeout
     def concurrent_statement_timeout(database_name = nil) = config(database_name).concurrent_statement_timeout
     # rubocop:enable Layout/LineLength
@@ -86,11 +92,11 @@ module Nandi
     delegate :migration_directory=,
              :output_directory=,
              :access_exclusive_lock_timeout=,
-             :access_exclusive_lock_timeout_limit=,
+             :access_exclusive_lock_timeout_max=,
              :access_exclusive_statement_timeout=,
-             :access_exclusive_statement_timeout_limit=,
-             :concurrent_lock_timeout_limit=,
-             :concurrent_statement_timeout_limit=,
+             :access_exclusive_statement_timeout_max=,
+             :concurrent_lock_timeout_min=,
+             :concurrent_statement_timeout_min=,
              :concurrent_lock_timeout=,
              :concurrent_statement_timeout=,
              to: :default

data/lib/nandi/instructions/add_foreign_key.rb

@@ -5,24 +5,29 @@ require "active_support/inflector"
 module Nandi
   module Instructions
     class AddForeignKey
-      attr_reader :table, :target
+      attr_reader :table, :target, :validate
 
       def initialize(table:, target:, name: nil, **extra_args)
         @table = table
         @target = target
         @extra_args = extra_args
         @name = name
+        @validate = false
       end
 
       def procedure
         :add_foreign_key
       end
 
+      def validate!
+        @validate = true
+      end
+
       def extra_args
         {
           **@extra_args,
           name: name,
-          validate: false,
+          validate: validate,
         }.compact
       end
 

data/lib/nandi/migration.rb

@@ -317,6 +317,8 @@ module Nandi
 
       public_send(direction) unless current_instructions.any?
 
+      Nandi.config.migration_modifiers.each { |mod| mod.public_send(direction, current_instructions) }
+
       current_instructions
     end
 

data/lib/nandi/migration_modifiers/base.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Nandi
+  module MigrationModifiers
+    class Base
+      def self.up(instructions); end
+      def self.down(instructions); end
+    end
+  end
+end

data/lib/nandi/migration_modifiers/create_table_validates_fks.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Nandi
+  module MigrationModifiers
+    class CreateTableValidatesFks < Base
+      def self.up(instructions)
+        new_tables = instructions.
+          select { |i| i.procedure == :create_table }.
+          to_set { |i| i.table.to_sym }
+
+        return if new_tables.empty?
+
+        instructions.
+          grep(Instructions::AddForeignKey).
+          select { |i| new_tables.include?(i.table.to_sym) }.
+          each(&:validate!)
+      end
+    end
+  end
+end

data/lib/nandi/migration_modifiers.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "nandi/migration_modifiers/base"
+require "nandi/migration_modifiers/create_table_validates_fks"
+
+module Nandi
+  module MigrationModifiers
+  end
+end

data/lib/nandi/multi_database.rb

@@ -9,11 +9,12 @@ module Nandi
       DEFAULT_ACCESS_EXCLUSIVE_STATEMENT_TIMEOUT = 1_500
       DEFAULT_ACCESS_EXCLUSIVE_LOCK_TIMEOUT = 5_000
 
-      DEFAULT_ACCESS_EXCLUSIVE_STATEMENT_TIMEOUT_LIMIT =
+      DEFAULT_ACCESS_EXCLUSIVE_STATEMENT_TIMEOUT_MAX =
         DEFAULT_ACCESS_EXCLUSIVE_STATEMENT_TIMEOUT
-      DEFAULT_ACCESS_EXCLUSIVE_LOCK_TIMEOUT_LIMIT =
+      DEFAULT_ACCESS_EXCLUSIVE_LOCK_TIMEOUT_MAX =
         DEFAULT_ACCESS_EXCLUSIVE_LOCK_TIMEOUT
-      DEFAULT_CONCURRENT_TIMEOUT_LIMIT = 3_600_000
+      DEFAULT_CONCURRENT_LOCK_TIMEOUT_MIN = 10_000
+      DEFAULT_CONCURRENT_STATEMENT_TIMEOUT_MIN = 30_000
 
       DEFAULT_MIGRATION_DIRECTORY = "db/safe_migrations"
       DEFAULT_OUTPUT_DIRECTORY = "db/migrate"
@@ -33,22 +34,22 @@ module Nandi
       # The maximum lock timeout for migrations that take an ACCESS EXCLUSIVE
       # lock and therefore block all reads and writes. Default: 5,000ms.
       # @return [Integer]
-      attr_accessor :access_exclusive_statement_timeout_limit
+      attr_accessor :access_exclusive_statement_timeout_max
 
       # The maximum statement timeout for migrations that take an ACCESS
       # EXCLUSIVE lock and therefore block all reads and writes. Default: 1500ms.
       # @return [Integer]
-      attr_accessor :access_exclusive_lock_timeout_limit
+      attr_accessor :access_exclusive_lock_timeout_max
 
       # The minimum statement timeout for migrations that take place concurrently.
       # Default: 3,600,000ms (ie, 3 hours).
       # @return [Integer]
-      attr_accessor :concurrent_statement_timeout_limit
+      attr_accessor :concurrent_statement_timeout_min
 
       # The minimum lock timeout for migrations that take place concurrently.
       # Default: 3,600,000ms (ie, 3 hours).
       # @return [Integer]
-      attr_accessor :concurrent_lock_timeout_limit
+      attr_accessor :concurrent_lock_timeout_min
 
       # The default lock timeout for migrations that take place concurrently
       # (eg. add_index, remove_index). When set, concurrent migrations will use
@@ -71,6 +72,13 @@ module Nandi
       attr_accessor :migration_directory,
                     :lockfile_name
 
+      RENAMED_KEYS = {
+        access_exclusive_lock_timeout_limit: :access_exclusive_lock_timeout_max,
+        access_exclusive_statement_timeout_limit: :access_exclusive_statement_timeout_max,
+        concurrent_lock_timeout_limit: :concurrent_lock_timeout_min,
+        concurrent_statement_timeout_limit: :concurrent_statement_timeout_min,
+      }.freeze
+
       def initialize(name:, config:)
         @name = name
         @raw_config = config
@@ -81,24 +89,36 @@ module Nandi
         @output_directory = config[:output_directory] || "db/#{path_prefix(name, default)}migrate"
         @lockfile_name = config[:lockfile_name] || ".#{path_prefix(name, default)}nandilock.yml"
 
-        timeout_limits(config)
+        timeout_limits(normalize_config(config))
       end
 
       private
 
+      def normalize_config(config)
+        RENAMED_KEYS.each_with_object(config.dup) do |(old_key, new_key), normalized|
+          next unless normalized.key?(old_key)
+
+          Nandi::DEPRECATOR.warn(
+            "#{old_key} is deprecated and will be removed in a future version. " \
+            "Use #{new_key} instead.",
+          )
+          normalized[new_key] ||= normalized.delete(old_key)
+        end
+      end
+
       def timeout_limits(config)
         @access_exclusive_lock_timeout =
           config[:access_exclusive_lock_timeout] || DEFAULT_ACCESS_EXCLUSIVE_LOCK_TIMEOUT
         @access_exclusive_statement_timeout =
           config[:access_exclusive_statement_timeout] || DEFAULT_ACCESS_EXCLUSIVE_STATEMENT_TIMEOUT
-        @access_exclusive_lock_timeout_limit =
-          config[:access_exclusive_lock_timeout_limit] || DEFAULT_ACCESS_EXCLUSIVE_LOCK_TIMEOUT_LIMIT
-        @access_exclusive_statement_timeout_limit =
-          config[:access_exclusive_statement_timeout_limit] || DEFAULT_ACCESS_EXCLUSIVE_STATEMENT_TIMEOUT_LIMIT
-        @concurrent_lock_timeout_limit =
-          config[:concurrent_lock_timeout_limit] || DEFAULT_CONCURRENT_TIMEOUT_LIMIT
-        @concurrent_statement_timeout_limit =
-          config[:concurrent_statement_timeout_limit] || DEFAULT_CONCURRENT_TIMEOUT_LIMIT
+        @access_exclusive_lock_timeout_max =
+          config[:access_exclusive_lock_timeout_max] || DEFAULT_ACCESS_EXCLUSIVE_LOCK_TIMEOUT_MAX
+        @access_exclusive_statement_timeout_max =
+          config[:access_exclusive_statement_timeout_max] || DEFAULT_ACCESS_EXCLUSIVE_STATEMENT_TIMEOUT_MAX
+        @concurrent_lock_timeout_min =
+          config[:concurrent_lock_timeout_min] || DEFAULT_CONCURRENT_LOCK_TIMEOUT_MIN
+        @concurrent_statement_timeout_min =
+          config[:concurrent_statement_timeout_min] || DEFAULT_CONCURRENT_STATEMENT_TIMEOUT_MIN
         @concurrent_lock_timeout = config[:concurrent_lock_timeout]
         @concurrent_statement_timeout = config[:concurrent_statement_timeout]
       end

data/lib/nandi/timeout_policies/access_exclusive.rb

@@ -43,11 +43,11 @@ module Nandi
       end
 
       def statement_timeout_maximum
-        Nandi.config.access_exclusive_statement_timeout_limit
+        Nandi.config.access_exclusive_statement_timeout_max
       end
 
       def lock_timeout_maximum
-        Nandi.config.access_exclusive_lock_timeout_limit
+        Nandi.config.access_exclusive_lock_timeout_max
       end
     end
   end

data/lib/nandi/timeout_policies/concurrent.rb

@@ -53,11 +53,11 @@ module Nandi
       end
 
       def minimum_lock_timeout
-        Nandi.config.concurrent_lock_timeout_limit
+        Nandi.config.concurrent_lock_timeout_min
       end
 
       def minimum_statement_timeout
-        Nandi.config.concurrent_statement_timeout_limit
+        Nandi.config.concurrent_statement_timeout_min
       end
     end
   end

data/lib/nandi/validator.rb

@@ -74,13 +74,13 @@ module Nandi
     def statement_timeout_is_within_acceptable_bounds
       migration.strictest_lock != Nandi::Migration::LockWeights::ACCESS_EXCLUSIVE ||
         migration.statement_timeout <=
-          Nandi.config.access_exclusive_statement_timeout_limit
+          Nandi.config.access_exclusive_statement_timeout_max
     end
 
     def lock_timeout_is_within_acceptable_bounds
       migration.strictest_lock != Nandi::Migration::LockWeights::ACCESS_EXCLUSIVE ||
         migration.lock_timeout <=
-          Nandi.config.access_exclusive_lock_timeout_limit
+          Nandi.config.access_exclusive_lock_timeout_max
     end
 
     def each_instruction_validation

data/lib/nandi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Nandi
-  VERSION = "2.1.1"
+  VERSION = "3.0.0"
 end

data/lib/nandi.rb

@@ -4,8 +4,11 @@ require "nandi/config"
 require "nandi/renderers"
 require "nandi/compiled_migration"
 require "active_support/core_ext/string/inflections"
+require "active_support/deprecation"
 
 module Nandi
+  DEPRECATOR = ActiveSupport::Deprecation.new("4.0", "Nandi")
+
   class Error < StandardError; end
 
   class << self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nandi
 version: !ruby/object:Gem::Version
-  version: 2.1.1
+  version: 3.0.0
 platform: ruby
 authors:
 - GoCardless Engineering
@@ -120,6 +120,9 @@ files:
 - lib/nandi/instructions/validate_constraint.rb
 - lib/nandi/lockfile.rb
 - lib/nandi/migration.rb
+- lib/nandi/migration_modifiers.rb
+- lib/nandi/migration_modifiers/base.rb
+- lib/nandi/migration_modifiers/create_table_validates_fks.rb
 - lib/nandi/migration_violations.rb
 - lib/nandi/multi_database.rb
 - lib/nandi/multi_db_generator.rb
@@ -177,7 +180,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Fear-free migrations for PostgreSQL
 test_files: []