rein 5.0.0 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12dbfe85b21d4fe3a16982a86d784701a74ed611046b9eaa0dcddea86afb8bd3
-  data.tar.gz: be0b34a4ecaa0098217e6bb8327fbc1cf09adf329a3ceb30d26afb4be3fb071b
+  metadata.gz: 4688e25fef8600352e4ba1cd54a5ace2eeca7f827a7ca3ad023de66b93f46d7f
+  data.tar.gz: 918d01449019e40a5d01f858755dbc3f10d4673f936ce0c9f2578de081f1f26c
 SHA512:
-  metadata.gz: a9bce885142492aa55ef15346ef19d1d631a1f85cd9ba8bc7c60ce977bd481a3d2962c3507bccde0ed9c5306f8a8f6d76b30e8e83a721f030f04df999a03ac47
-  data.tar.gz: 9e8c8ef912098fc12d944c1198783bf2b0308fa3a241ca937ae03d4ee9532c9acd391da045bb778a002c2cf528c81112008309614254aaf01a1f1863e9385add
+  metadata.gz: 8a27510401ee3dbb708f41cda16b2c697a7e2de643923c35c4657eb3b783885ffeb09186a6fd6c0683b78f27c667d82b15893b2d1d051b9656042ab9a7f1fe85
+  data.tar.gz: e82ea6c4ed180a76471419d99316ea75b80f040c8576bacfb6ed671a6ba12bdd3adc4d5cc36a15f3632bd77a16459b93e0872e081e12f07c6ab352a8b28a8615

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## Unreleased
+
+## 5.1.0 (2020-01-08)
+
+* Add validate option to foreign key and check constraints
+
 ## 5.0.0 (2019-08-23)
 
 * Upgrade development deps

data/README.md

@@ -19,6 +19,7 @@ advantage of reversible Rails migrations.
 
 * [Getting Started](#getting-started)
 * [Constraint Types](#constraint-types)
+  * [Summary](#summary)
   * [Foreign Key Constraints](#foreign-key-constraints)
   * [Unique Constraints](#unique-constraints)
   * [Exclusion Constraints](#exclusion-constraints)
@@ -29,6 +30,7 @@ advantage of reversible Rails migrations.
   * [Presence Constraints](#presence-constraints)
   * [Null Constraints](#null-constraints)
   * [Check Constraints](#check-constraints)
+  * [Validate Constraints](#validate-constraints)
 * [Data Types](#data-types)
   * [Enumerated Types](#enumerated-types)
 * [Views](#views)
@@ -62,6 +64,23 @@ end
 
 ## Constraint Types
 
+### Summary
+
+The table below summarises the constraint operations provided by Rein and whether they support [validation](#validate-constraints).
+
+| Rein name   | Rein method | SQL | Supports `NOT VALID`? |
+| ----------- | ----------- | --- | --------------------- |
+| Foreign Key | `add_foreign_key_constraint` | `FOREIGN KEY` | yes |
+| Unique | `add_unique_constraint` | `UNIQUE` | no |
+| Exclusion | `add_exclusion_constraint` | `EXCLUDE` | no |
+| Inclusion | `add_inclusion_constraint` | `CHECK` | yes |
+| Length | `add_length_constraint` | `CHECK` | yes |
+| Match | `add_match_constraint` | `CHECK` | yes |
+| Numericality | `add_numericality_constraint` | `CHECK` | yes |
+| Presence | `add_presence_constraint` | `CHECK` | yes |
+| Null | `add_null_constraint` | `CHECK` | yes |
+| Check | `add_check_constraint` | `CHECK` | yes |
+
 ### Foreign Key Constraints
 
 A foreign key constraint specifies that the values in a column must match the
@@ -461,6 +480,32 @@ To remove a check constraint:
 remove_check_constraint :books, "substring(title FROM 1 FOR 1) IS DISTINCT FROM 'r'", name: 'no_r_titles'
 ```
 
+### Validate Constraints
+
+Adding a constraint can be a very costly operation, especially on larger tables, as the database has to scan all rows in the table to check for violations of the new constraint. During this time, concurrent writes are blocked as an [`ACCESS EXCLUSIVE`](https://www.postgresql.org/docs/current/explicit-locking.html#LOCKING-TABLES) table lock is taken. In addition, adding a foreign key constraint obtains a `SHARE ROW EXCLUSIVE` lock on the referenced table. See the [docs](https://www.postgresql.org/docs/current/sql-altertable.html#SQL-ALTERTABLE-NOTES) for more details.
+
+In order to allow constraints to be added concurrently on larger tables, and to allow the addition of constraints on tables containing rows with existing violations, Postgres supports adding constraints using the `NOT VALID` option (currently only for `CHECK` and foreign key constraints).
+
+This allows the constraint to be added immediately, without validating existing rows, but enforcing the constraint for any new rows and updates. After that, a `VALIDATE CONSTRAINT` command can be issued to verify that existing rows satisfy the constraint, which is done in a way that does not lock out concurrent updates and "with the least impact on other work".
+
+Rein supports adding `CHECK` and foreign key constraints with the `NOT VALID` option by passing `validate: false` to the options of the supported Rein DSL methods, [summarised above](#summary).
+
+```ruby
+add_null_constraint :books, :due_date, if: "state = 'on_loan'", validate: false
+```
+
+With Rails 5.2 or later, you can use [`validate_constraint`](https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/PostgreSQL/SchemaStatements.html#method-i-validate_constraint) in a subsequent migration to validate a `NOT VALID` constraint. If you are using versions of Rails below 5.2, you can use Rein's `validate_table_constraint` method:
+
+```ruby
+validate_table_constraint :books, "no_r_titles"
+```
+
+It's safe (a no-op) to validate a constraint that is already marked as valid.
+
+### Side note on `lock_timeout`
+
+It's advisable to set a [sensibly low `lock_timeout`](https://gocardless.com/blog/zero-downtime-postgres-migrations-the-hard-parts/) in your database migrations, otherwise existing long-running transactions can prevent your migration from acquiring the required locks, resulting in a lock queue that prevents even selects on the target table, potentially brining your production database grinding to a halt.
+
 ## Data Types
 
 ### Enumerated Types

data/lib/rein.rb

@@ -10,6 +10,7 @@ require 'rein/constraint/presence'
 require 'rein/constraint/primary_key'
 require 'rein/constraint/unique'
 require 'rein/constraint/exclusion'
+require 'rein/constraint/validate'
 require 'rein/schema'
 require 'rein/type/enum'
 require 'rein/view'
@@ -27,6 +28,7 @@ module ActiveRecord
     include Rein::Constraint::PrimaryKey
     include Rein::Constraint::Unique
     include Rein::Constraint::Exclusion
+    include Rein::Constraint::Validate
     include Rein::Schema
     include Rein::Type::Enum
     include Rein::View

data/lib/rein/constraint/check.rb

@@ -27,7 +27,7 @@ module Rein
         sql = "ALTER TABLE #{Util.wrap_identifier(table_name)}"
         sql << " ADD CONSTRAINT #{name}"
         sql << " CHECK (#{predicate})"
-        execute(sql)
+        execute(Util.add_not_valid_suffix_if_required(sql, options))
       end
 
       def _remove_check_constraint(table_name, _predicate, options = {})

data/lib/rein/constraint/foreign_key.rb

@@ -31,7 +31,7 @@ module Rein
         sql << " REFERENCES #{referenced_table} (#{Util.wrap_identifier(referenced_attribute)})"
         sql << " ON DELETE #{referential_action(options[:on_delete])}" if options[:on_delete].present?
         sql << " ON UPDATE #{referential_action(options[:on_update])}" if options[:on_update].present?
-        execute(sql)
+        execute(Util.add_not_valid_suffix_if_required(sql, options))
         add_index(referencing_table, referencing_attribute) if options[:index] == true
       end
 

data/lib/rein/constraint/inclusion.rb

@@ -28,7 +28,8 @@ module Rein
         values = options[:in].map { |value| quote(value) }.join(', ')
         attribute = Util.wrap_identifier(attribute)
         conditions = Util.conditions_with_if("#{attribute} IN (#{values})", options)
-        execute("ALTER TABLE #{table} ADD CONSTRAINT #{name} CHECK (#{conditions})")
+        sql = "ALTER TABLE #{table} ADD CONSTRAINT #{name} CHECK (#{conditions})"
+        execute(Util.add_not_valid_suffix_if_required(sql, options))
       end
 
       def _remove_inclusion_constraint(table, attribute, options = {})

data/lib/rein/constraint/length.rb

@@ -39,7 +39,8 @@ module Rein
           [attribute_length, operator, value].join(' ')
         end.join(' AND ')
         conditions = Util.conditions_with_if(conditions, options)
-        execute("ALTER TABLE #{table} ADD CONSTRAINT #{name} CHECK (#{conditions})")
+        sql = "ALTER TABLE #{table} ADD CONSTRAINT #{name} CHECK (#{conditions})"
+        execute(Util.add_not_valid_suffix_if_required(sql, options))
       end
 
       def _remove_length_constraint(table, attribute, options = {})

data/lib/rein/constraint/match.rb

@@ -36,7 +36,8 @@ module Rein
           [attribute, operator, "'#{value}'"].join(' ')
         end.join(' AND ')
         conditions = Util.conditions_with_if(conditions, options)
-        execute("ALTER TABLE #{table} ADD CONSTRAINT #{name} CHECK (#{conditions})")
+        sql = "ALTER TABLE #{table} ADD CONSTRAINT #{name} CHECK (#{conditions})"
+        execute(Util.add_not_valid_suffix_if_required(sql, options))
       end
 
       def _remove_match_constraint(table, attribute, options = {})

data/lib/rein/constraint/null.rb

@@ -27,7 +27,8 @@ module Rein
         table = Util.wrap_identifier(table)
         attribute = Util.wrap_identifier(attribute)
         conditions = Util.conditions_with_if("#{attribute} IS NOT NULL", options)
-        execute("ALTER TABLE #{table} ADD CONSTRAINT #{name} CHECK (#{conditions})")
+        sql = "ALTER TABLE #{table} ADD CONSTRAINT #{name} CHECK (#{conditions})"
+        execute(Util.add_not_valid_suffix_if_required(sql, options))
       end
 
       def _remove_null_constraint(table, attribute, options = {})

data/lib/rein/constraint/numericality.rb

@@ -38,7 +38,8 @@ module Rein
           [attribute, operator, value].join(' ')
         end.join(' AND ')
         conditions = Util.conditions_with_if(conditions, options)
-        execute("ALTER TABLE #{table} ADD CONSTRAINT #{name} CHECK (#{conditions})")
+        sql = "ALTER TABLE #{table} ADD CONSTRAINT #{name} CHECK (#{conditions})"
+        execute(Util.add_not_valid_suffix_if_required(sql, options))
       end
 
       def _remove_numericality_constraint(table, attribute, options = {})

data/lib/rein/constraint/presence.rb

@@ -30,7 +30,8 @@ module Rein
           "(#{attribute} IS NOT NULL) AND (#{attribute} !~ '^\\s*$')",
           options
         )
-        execute("ALTER TABLE #{table} ADD CONSTRAINT #{name} CHECK (#{conditions})")
+        sql = "ALTER TABLE #{table} ADD CONSTRAINT #{name} CHECK (#{conditions})"
+        execute(Util.add_not_valid_suffix_if_required(sql, options))
       end
 
       def _remove_presence_constraint(table, attribute, options = {})

data/lib/rein/constraint/validate.rb

@@ -0,0 +1,25 @@
+require 'rein/util'
+
+module Rein
+  module Constraint
+    # This module contains methods for validating constraints.
+    module Validate
+      def validate_table_constraint(*args)
+        reversible do |dir|
+          dir.up { _validate_table_constraint(*args) }
+          dir.down do
+            # No-op - it's safe to validate an already validated constraint
+            # https://www.postgresql.org/docs/current/sql-altertable.html#SQL-ALTERTABLE-NOTES
+            # "Nothing happens if the constraint is already marked valid."
+          end
+        end
+      end
+
+      private
+
+      def _validate_table_constraint(table, constraint_name)
+        execute("ALTER TABLE #{Util.wrap_identifier(table)} VALIDATE CONSTRAINT #{constraint_name}")
+      end
+    end
+  end
+end

data/lib/rein/util.rb

@@ -1,6 +1,12 @@
 module Rein
   # The {Util} module provides utility methods for handling options.
   module Util
+    # Returns a new string with the suffix appended if required
+    def self.add_not_valid_suffix_if_required(sql, options)
+      suffix = options[:validate] == false ? ' NOT VALID' : ''
+      "#{sql}#{suffix}"
+    end
+
     def self.conditions_with_if(conditions, options = {})
       if options[:if].present?
         "NOT (#{options[:if]}) OR (#{conditions})"

data/lib/rein/version.rb

@@ -1,3 +1,3 @@
 module Rein
-  VERSION = '5.0.0'.freeze
+  VERSION = '5.1.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rein
 version: !ruby/object:Gem::Version
-  version: 5.0.0
+  version: 5.1.0
 platform: ruby
 authors:
 - Joshua Bassett
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-08-23 00:00:00.000000000 Z
+date: 2020-01-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -144,6 +144,7 @@ files:
 - lib/rein/constraint/presence.rb
 - lib/rein/constraint/primary_key.rb
 - lib/rein/constraint/unique.rb
+- lib/rein/constraint/validate.rb
 - lib/rein/schema.rb
 - lib/rein/type/enum.rb
 - lib/rein/util.rb