nandi 0.9.0 → 0.11.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba61fdd052ec58212031846c92ad947cb1f7cb8c033271b101f5973a2b7074f6
-  data.tar.gz: b0c30216fb5544927d1d3b47ef0ad87d935a9ea8859c37a8779662a65f88d9f5
+  metadata.gz: 78ca004c815e5952f1fc51b44fa839afd81b1297fc3079e98202719eead8ac74
+  data.tar.gz: 3e19d0265b7e428298abb84c78f463756437c431a2757abe8d28ed232f7c6aab
 SHA512:
-  metadata.gz: f4c0ecfcb5e1a84c4a8b2e0721f4e48a8abff3f6bde78f04184544e9004987a4f155eebb3342b780fc793bc2d5104a8a98d7d25c6fcc9f8da43cdd70e0b5f9fd
-  data.tar.gz: aedffb405097c5d9e988e001eab0c929ed0fab64b1b9b04a534051fa59aa16634c3c9071bf5daf31b7c416bfa94679b020685bd8c201c78d0552ebbcf60e0a75
+  metadata.gz: fa56e2901b20d88d59bd0cf05b4b78395fc39a3c8c0e7d80484fbc99045c3d8f099861b36a2220b5a183473a4de4f583f873510abe78f469ef700e5b1c6e5035
+  data.tar.gz: 91837a550c6deb7b724d5778300821cd73519cadc2e9b5999645d5884f7a1b17ea9810c24ce5ecfc3431e9fcf0ae260b1de283c6ccd0ea6828d33b7d1ffe33e0

data/README.md

@@ -4,7 +4,7 @@ Friendly Postgres migrations for people who don't want to take down their databa
 
 ## Supported
 
-- Ruby 2.4 or above
+- Ruby 2.5 or above
 - Rails 5.2 or above
 - Postgres 11 or above
 
@@ -202,10 +202,10 @@ class AddReferenceOnFoosToBars < ActiveRecord::Migration[5.2]
   set_statement_timeout(1_500)
 
   def up
-    add_reference(:foos, :bar)
+    add_column(:foos, :bar_id, :bigint)
   end
   def down
-    remove_reference(:foos, :bar)
+    remove_column(:foos, :bar_id)
   end
 end
 
@@ -268,10 +268,9 @@ Add a foreign key constraint. The generated SQL will include the NOT VALID param
 ### `#add_index(table, fields, **kwargs)`
 Adds a new index to the database.
 
-Nandi will:
-
+Nandi will
 - add the `CONCURRENTLY` option, which means the change takes a less restrictive lock at the cost of not running in a DDL transaction
-- use the `BTREE` index type which is the safest to create.
+- default to the `BTREE` index type, as it is commonly a good fit.
 
 Because index creation is particularly failure-prone, and because we cannot run in a transaction and therefore risk partially applied migrations that (in a Rails environment) require manual intervention, Nandi Validates that, if there is a add_index statement in the migration, it must be the only statement.
 
@@ -286,6 +285,12 @@ create_table :widgets do |t|
 end
 ```
 
+### `#add_reference(table, ref_name, **extra_args)`
+Adds a new reference column. Nandi will validate that the foreign key flag is not set to true; use `add_foreign_key` and `validate_foreign_key` instead! Nandi will also set the `index: false` flag, as index creation is unsafe unless done concurrently in a separate migration.
+
+### `#remove_reference(table, ref_name, **extra_args)`
+Removes a reference column.
+
 ### `#remove_column(table, name, **extra_args)`
 Remove an existing column.
 

data/exe/nandi-enforce

@@ -31,6 +31,6 @@ OptionParser.new do |o|
   end
 end.parse!
 
-enforcer = Nandi::SafeMigrationEnforcer.new(opts)
+enforcer = Nandi::SafeMigrationEnforcer.new(**opts)
 
 enforcer.run

data/lib/nandi/formatting.rb

@@ -64,7 +64,7 @@ module Nandi
         key = if k.is_a?(Symbol)
                 symbol_key(k)
               else
-                format_value(k) + " =>"
+                "#{format_value(k)} =>"
               end
         "#{key} #{format_value(v)}"
       end

data/lib/nandi/instructions/add_index.rb

@@ -21,11 +21,10 @@ module Nandi
           name: name,
 
           # Overrides and extra options
-          **@extra_args,
+          **extra_args_with_default_index_type,
 
           # Mandatory values
           algorithm: :concurrently,
-          using: :btree,
         }
       end
 
@@ -38,13 +37,19 @@ module Nandi
       private
 
       def name
-        :"idx_#{table.to_s}_on_#{field_names}"
+        :"idx_#{table}_on_#{field_names}"
       end
 
       def field_names
         field_names = fields.respond_to?(:map) ? fields.map(&:to_s).join("_") : fields
         field_names.to_s.scan(/\w+/).join("_")
       end
+
+      def extra_args_with_default_index_type
+        {
+          using: :btree,
+        }.merge(@extra_args)
+      end
     end
   end
 end

data/lib/nandi/instructions/add_reference.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Nandi
+  module Instructions
+    class AddReference
+      DEFAULT_EXTRA_ARGS = { index: false }.freeze
+      attr_reader :table, :ref_name, :extra_args
+
+      def initialize(table:, ref_name:, **kwargs)
+        @table = table
+        @ref_name = ref_name
+        @extra_args = DEFAULT_EXTRA_ARGS.merge(kwargs)
+      end
+
+      def procedure
+        :add_reference
+      end
+
+      def lock
+        Nandi::Migration::LockWeights::ACCESS_EXCLUSIVE
+      end
+    end
+  end
+end

data/lib/nandi/instructions/remove_column.rb

@@ -8,7 +8,12 @@ module Nandi
       def initialize(table:, name:, **extra_args)
         @table = table
         @name = name
-        @extra_args = extra_args if extra_args.any?
+        @extra_args =
+          if extra_args.any?
+            extra_args
+          else
+            {}
+          end
       end
 
       def procedure

data/lib/nandi/instructions/remove_reference.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Nandi
+  module Instructions
+    class RemoveReference
+      attr_reader :table, :ref_name, :extra_args
+
+      def initialize(table:, ref_name:, **kwargs)
+        @table = table
+        @ref_name = ref_name
+        @extra_args = kwargs
+      end
+
+      def procedure
+        :remove_reference
+      end
+
+      def lock
+        Nandi::Migration::LockWeights::ACCESS_EXCLUSIVE
+      end
+    end
+  end
+end

data/lib/nandi/instructions.rb

@@ -5,6 +5,8 @@ require "nandi/instructions/remove_index"
 require "nandi/instructions/create_table"
 require "nandi/instructions/drop_table"
 require "nandi/instructions/add_column"
+require "nandi/instructions/add_reference"
+require "nandi/instructions/remove_reference"
 require "nandi/instructions/remove_column"
 require "nandi/instructions/add_foreign_key"
 require "nandi/instructions/drop_constraint"

data/lib/nandi/lockfile.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "active_support/core_ext/hash/indifferent_access"
+require "digest"
 
 module Nandi
   class Lockfile
@@ -42,7 +43,26 @@ module Nandi
       end
 
       def persist!
-        File.write(path, lockfile.to_h.deep_stringify_keys.to_yaml)
+        # This is a somewhat ridiculous trick to avoid merge conflicts in git.
+        #
+        # Normally, new migrations are added to the bottom of the Nandi lockfile.
+        # This is relatively unfriendly to git's merge algorithm, and means that
+        # if someone merges a pull request with a completely unrelated migration,
+        # you'll have to rebase to get yours merged as the last line of the file
+        # will be seen as a conflict (both branches added content there).
+        #
+        # This is in contrast to something like Gemfile.lock, where changes tend
+        # to be distributed throughout the file. The idea behind sorting by
+        # SHA-256 hash is to distribute new Nandi lockfile entries evenly, but
+        # also stably through the file. It needs to be stable or we'd have even
+        # worse merge conflict problems (e.g. if we randomised the order on
+        # writing the file, the whole thing would conflict pretty much every time
+        # it was regenerated).
+        content = Hash[lockfile.to_h.deep_stringify_keys.sort_by do |k, _|
+          Digest::SHA256.hexdigest(k)
+        end].to_yaml
+
+        File.write(path, content)
       end
 
       def path

data/lib/nandi/migration.rb

@@ -43,6 +43,7 @@ module Nandi
 
     class << self
       attr_reader :lock_timeout, :statement_timeout
+
       # For sake both of correspondence with Postgres syntax and familiarity
       # with activerecord-safe_migrations's identically named macros, we
       # disable this cop.
@@ -111,7 +112,7 @@ module Nandi
     # Nandi will:
     # * add the `CONCURRENTLY` option, which means the change takes a less
     #   restrictive lock at the cost of not running in a DDL transaction
-    # * use the `BTREE` index type which is the safest to create.
+    # * default to the `BTREE` index type, as it is commonly a good fit.
     #
     # Because index creation is particularly failure-prone, and because
     # we cannot run in a transaction and therefore risk partially applied
@@ -188,6 +189,31 @@ module Nandi
       )
     end
 
+    # Adds a new reference column. Nandi will validate that the foreign key flag
+    # is not set to true; use `add_foreign_key` and `validate_foreign_key` instead!
+    # @param table [Symbol, String] The name of the table to add the column to
+    # @param ref_name [Symbol, String] The referenced column name
+    # @param kwargs [Hash] Arbitrary options to be passed to the backend.
+    def add_reference(table, ref_name, **kwargs)
+      current_instructions << Instructions::AddReference.new(
+        table: table,
+        ref_name: ref_name,
+        **kwargs,
+      )
+    end
+
+    # Removes a reference column.
+    # @param table [Symbol, String] The name of the table to remove the reference from
+    # @param ref_name [Symbol, String] The referenced column name
+    # @param kwargs [Hash] Arbitrary options to be passed to the backend.
+    def remove_reference(table, ref_name, **kwargs)
+      current_instructions << Instructions::RemoveReference.new(
+        table: table,
+        ref_name: ref_name,
+        **kwargs,
+      )
+    end
+
     # Remove an existing column.
     # @param table [Symbol, String] The name of the table to remove the column
     #   from.
@@ -331,9 +357,9 @@ module Nandi
       end.uniq
     end
 
-    def method_missing(name, *args, &block)
+    def method_missing(name, *args, **kwargs, &block)
       if Nandi.config.custom_methods.key?(name)
-        invoke_custom_method(name, *args, &block)
+        invoke_custom_method(name, *args, **kwargs, &block)
       else
         super
       end
@@ -355,9 +381,9 @@ module Nandi
       Nandi.config.access_exclusive_lock_timeout
     end
 
-    def invoke_custom_method(name, *args, &block)
+    def invoke_custom_method(name, *args, **kwargs, &block)
       klass = Nandi.config.custom_methods[name]
-      current_instructions << klass.new(*args, &block)
+      current_instructions << klass.new(*args, **kwargs, &block)
     end
   end
 end

data/lib/nandi/renderers/active_record/instructions.rb

@@ -82,6 +82,18 @@ module Nandi
           formatted_property :extra_args
         end
 
+        class AddReferenceCell < Base
+          formatted_property :table
+          formatted_property :ref_name
+          formatted_property :extra_args
+        end
+
+        class RemoveReferenceCell < Base
+          formatted_property :table
+          formatted_property :ref_name
+          formatted_property :extra_args
+        end
+
         class RemoveColumnCell < Base
           formatted_property :table
           formatted_property :name

data/lib/nandi/validation/add_reference_validator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "nandi/validation/failure_helpers"
+
+module Nandi
+  module Validation
+    class AddReferenceValidator
+      include Nandi::Validation::FailureHelpers
+
+      def self.call(instruction)
+        new(instruction).call
+      end
+
+      def initialize(instruction)
+        @instruction = instruction
+      end
+
+      def call
+        foreign_key = instruction.extra_args.fetch(:foreign_key, false)
+        index = instruction.extra_args.fetch(:index, false)
+
+        collect_errors(
+          assert(
+            !foreign_key,
+            foreign_key_message,
+          ),
+          assert(
+            !index,
+            index_message,
+          ),
+        )
+      end
+
+      private
+
+      def index_message
+        "Indexing a reference column on creation can make the table unavailable." \
+          "Use the `add_index` method in a separate migration to index the column."
+      end
+
+      def foreign_key_message
+        "Adding a foreign key constraint must be done in two separate migrations. " \
+          "Use the `add_foreign_key` and `validate_foreign_key` methods, or the " \
+          "nandi:foreign_key generator, to do this."
+      end
+
+      attr_reader :instruction
+    end
+  end
+end

data/lib/nandi/validation/each_validator.rb

@@ -21,6 +21,8 @@ module Nandi
           RemoveIndexValidator.call(instruction)
         when :add_column
           AddColumnValidator.call(instruction)
+        when :add_reference
+          AddReferenceValidator.call(instruction)
         else
           success
         end

data/lib/nandi/validation.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "nandi/validation/add_column_validator"
+require "nandi/validation/add_reference_validator"
 require "nandi/validation/remove_index_validator"
 require "nandi/validation/each_validator"
 require "nandi/validation/result"

data/lib/nandi/version.rb

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

data/lib/templates/nandi/renderers/active_record/instructions/add_column/show.rb.erb

@@ -2,5 +2,5 @@ add_column(
   <%= table %>,
   <%= name %>,
   <%= type %>,
-  <%= extra_args %>
+  **<%= extra_args || {} %>
 )

data/lib/templates/nandi/renderers/active_record/instructions/add_foreign_key/show.rb.erb

@@ -1,5 +1,5 @@
 add_foreign_key(
   <%= table %>,
   <%= target %>,
-  <%= extra_args %>
+  **<%= extra_args || {} %>
 )

data/lib/templates/nandi/renderers/active_record/instructions/add_index/show.rb.erb

@@ -1,5 +1,5 @@
 add_index(
   <%= table %>,
   <%= fields %>,
-  <%= extra_args %>
+  **<%= extra_args || {} %>
 )

data/lib/templates/nandi/renderers/active_record/instructions/add_reference/show.rb.erb

@@ -0,0 +1,5 @@
+add_reference(
+  <%= table %>,
+  <%= ref_name %>,
+  **<%= extra_args || {} %>
+)

data/lib/templates/nandi/renderers/active_record/instructions/remove_column/show.rb.erb

@@ -1,5 +1,5 @@
 remove_column(
   <%= table %>,
   <%= name %>,
-  <%= extra_args %>
+  **<%= extra_args || {} %>
 )

data/lib/templates/nandi/renderers/active_record/instructions/remove_index/show.rb.erb

@@ -1,4 +1,4 @@
 remove_index(
   <%= table %>,
-  <%= extra_args %>
+  **<%= extra_args || {} %>
 )

data/lib/templates/nandi/renderers/active_record/instructions/remove_reference/show.rb.erb

@@ -0,0 +1,5 @@
+remove_reference(
+  <%= table %>,
+  <%= ref_name %>,
+  **<%= extra_args || {} %>
+)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nandi
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.3
 platform: ruby
 authors:
 - GoCardless Engineering
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-03-16 00:00:00.000000000 Z
+date: 2021-09-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -100,28 +100,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.14
+        version: 2.15.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.14
+        version: 2.15.0
 - !ruby/object:Gem::Dependency
   name: pry-byebug
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.7.0
+        version: 3.9.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.7.0
+        version: 3.9.0
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -140,22 +140,22 @@ dependencies:
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '12.3'
     - - ">="
       - !ruby/object:Gem::Version
         version: 12.3.3
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '12.3'
     - - ">="
       - !ruby/object:Gem::Version
         version: 12.3.3
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -190,14 +190,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.61'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.61'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -212,7 +212,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
-description: 
+description:
 email:
 - engineering@gocardless.com
 executables:
@@ -252,6 +252,7 @@ files:
 - lib/nandi/instructions/add_column.rb
 - lib/nandi/instructions/add_foreign_key.rb
 - lib/nandi/instructions/add_index.rb
+- lib/nandi/instructions/add_reference.rb
 - lib/nandi/instructions/change_column_default.rb
 - lib/nandi/instructions/create_table.rb
 - lib/nandi/instructions/drop_constraint.rb
@@ -260,6 +261,7 @@ files:
 - lib/nandi/instructions/remove_column.rb
 - lib/nandi/instructions/remove_index.rb
 - lib/nandi/instructions/remove_not_null_constraint.rb
+- lib/nandi/instructions/remove_reference.rb
 - lib/nandi/instructions/validate_constraint.rb
 - lib/nandi/lockfile.rb
 - lib/nandi/migration.rb
@@ -273,6 +275,7 @@ files:
 - lib/nandi/timeout_policies/concurrent.rb
 - lib/nandi/validation.rb
 - lib/nandi/validation/add_column_validator.rb
+- lib/nandi/validation/add_reference_validator.rb
 - lib/nandi/validation/each_validator.rb
 - lib/nandi/validation/failure_helpers.rb
 - lib/nandi/validation/remove_index_validator.rb
@@ -285,6 +288,7 @@ files:
 - lib/templates/nandi/renderers/active_record/instructions/add_column/show.rb.erb
 - lib/templates/nandi/renderers/active_record/instructions/add_foreign_key/show.rb.erb
 - lib/templates/nandi/renderers/active_record/instructions/add_index/show.rb.erb
+- lib/templates/nandi/renderers/active_record/instructions/add_reference/show.rb.erb
 - lib/templates/nandi/renderers/active_record/instructions/change_column_default/show.rb.erb
 - lib/templates/nandi/renderers/active_record/instructions/create_table/show.rb.erb
 - lib/templates/nandi/renderers/active_record/instructions/drop_constraint/show.rb.erb
@@ -293,12 +297,13 @@ files:
 - lib/templates/nandi/renderers/active_record/instructions/remove_column/show.rb.erb
 - lib/templates/nandi/renderers/active_record/instructions/remove_index/show.rb.erb
 - lib/templates/nandi/renderers/active_record/instructions/remove_not_null_constraint/show.rb.erb
+- lib/templates/nandi/renderers/active_record/instructions/remove_reference/show.rb.erb
 - lib/templates/nandi/renderers/active_record/instructions/validate_constraint/show.rb.erb
 homepage: https://github.com/gocardless/nandi
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -306,15 +311,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.2.3
+signing_key:
 specification_version: 4
 summary: Fear-free migrations for PostgreSQL
 test_files: []