validates_overlap 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22d9351114cf974a1843daead1ff7fb57503951d2cfecd9bfe19c2041bd4dd01
-  data.tar.gz: 95e4e59f48f05f22ad589a06e77224fd1d065414ddb22a0d68f17e23005c0168
+  metadata.gz: e58e04fbe91942b00130f68c9e8d838838039d5ba6dc5218e563cc34d2deaf06
+  data.tar.gz: 995aafe99900907fc2c43536969a6c3984026a29da87998b2c869371012ea84e
 SHA512:
-  metadata.gz: 8483ac32c24e082f364de7e090dd01b6d14183657bbf6e002770b1d256904eed24e56fcf19707bfa586d79ca9be24b1b7e5e5f9d09de9f2f18d404cc0dec840b
-  data.tar.gz: 4b2d9a55f399584ba014ca1633bfa4e278ad42a89db9ff5db4828da9c71d1bba731ceb9394ee5cb9903f2ffa51c76f542efea40037a4e99e7ed6bcea2498f73d
+  metadata.gz: dbd9aaf4d1a31d36d27222413f83d97b5cf9658b805b5de0b4a61fae7dcbc7e57833e82419b6144a9cb0a8097160167dbbf8202bb58314ac2ac537d23455b361
+  data.tar.gz: b7da9ddfb4e78fb8821af1a5d3866cda098e5f7b14f2af3506aef1b7ea67390e16f3b59c5987d25b83513bf52902473e1b2b5b6673f1d074bfa72dc0b63640ff

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # ValidatesOverlap 1.x Change Log
 
+## 1.3.0 (2026-08-15)
+
+RSpec tests: **126 → 243** (+117 tests)
+
+### New Features
+
+  - support for native PostgreSQL range columns: declare the validation with a single range-column attribute (`validates :period, overlap: { scope: :user_id }` on a `tsrange` / `tstzrange` / `daterange` / `int4range` / `int8range` / `numrange` column) — compared with PostgreSQL's `&&` operator, whose range algebra decides every edge case, so the validation and an exclusion constraint can never disagree: bound inclusivity comes from the stored value, a `NULL` range conflicts with nothing, `'(,)'` conflicts with everything. `exclude_edges` and the shifts raise `ArgumentError` for range columns; a single-attribute validation on a non-range column raises `OverlapValidator::UnsupportedColumnType`, and so does a two-attribute validation on range columns (a range column is validated on its own). `add_overlap_constraint :meetings, :period, scope: :user_id` generates the matching one-column exclusion constraint
+  - `record.overlapping_records`, defined on every model with an overlap validation: freshly queries the conflicting records on demand and returns an `ActiveRecord::Relation` — always current, and no records are loaded until the result is used. With several overlap validations, a nil range value's empty result no longer hides the other validations' conflicts (Rails 6.1/7.0), combining validations that query different models raises a clear `ArgumentError` instead of silently merging them, and a model whose validators were removed still returns an empty relation
+  - `add_overlap_constraint` / `remove_overlap_constraint` migration helpers (PostgreSQL): generate a database-level exclusion constraint that closes the check-then-act race no validation can close — the range type is inferred from the column types, scope columns are compared with equality, and the edge semantics mirror the validator's; raises `NotImplementedError` on other adapters. Reversible in `def change` migrations on Rails 7.1+ (`db:rollback` drops the constraint); `btree_gist` is only enabled when missing; warns when a scope column allows NULL — NULL-scoped rows are not restricted by an exclusion constraint (`NULL = NULL` is not true in SQL), while the validation does match NULL scope values. On PostgreSQL 18+, `without_overlaps: true` generates the standard-SQL temporal unique constraint (`UNIQUE (scope, range WITHOUT OVERLAPS)`) for a scoped range column — PostgreSQL enforces it as an exclusion constraint, so `RescueExclusionViolation` works unchanged; note that it rejects empty range values (suggested by [Chedli Bourguiba](https://github.com/chaadow) in [PR #64](https://github.com/tilo/validates_overlap/pull/64))
+  - `ValidatesOverlap::RescueExclusionViolation` (opt-in model concern): turns the constraint violation from the race window into a normal validation failure — `save` returns false with the overlap error set, `save!` raises `ActiveRecord::RecordInvalid`. The containment savepoint is only opened when the caller already has a transaction open on PostgreSQL — a halted callback (`throw :abort`) rolls its earlier writes back again, and saves on other adapters pay no savepoint round-trips; the error lands on exactly the keys the validator would use (array `message_title`, `:base` fallback for association attributes); Rails 8.1's `ActiveRecord::ExclusionViolation` is recognized even when the error's cause chain is lost (e.g. JRuby)
+  - the test suite runs against SQLite, PostgreSQL (`DB=postgres`, including the PostgreSQL-only specs in `spec_pg/`), and MySQL (`DB=mysql`), with CI jobs for all three adapters and an allowed-failure lane against rails main; new rake tasks run them locally (`rake spec:postgres` / `spec:mysql` / `spec:all`)
+
+### Deprecations
+
+  - `load_overlapped: true` is deprecated, removal in 2.0 — it wrote `@overlapped_records` into the record from the outside, kept stale results after re-validation, and loaded the records during every validation; use `record.overlapping_records` instead
+
 ## 1.2.0 (2026-08-11)
 
 RSpec tests: **85 → 126** (+41 tests)

data/CONTRIBUTORS.md

@@ -1,4 +1,4 @@
-# A Big Thank You to all 21 Contributors!!
+# A Big Thank You to all 22 Contributors!!
 
 `validates_overlap` was created in 2011 by [Robin Bortlik](https://github.com/robinbortlik), who designed it and maintained it, reviewing and merging every pull request below along the way. Thank you, Robin, for this gem and all the work you put into it! ❤️
 
@@ -24,3 +24,4 @@ A Big Thank you to everyone who filed issues, sent comments, and who contributed
  * [Nujian Den Mark Meralpis](https://github.com/denmarkmeralpis)
  * [ohenrik](https://github.com/ohenrik)
  * [Jorge Santos](https://github.com/jsantos)
+ * [Chedli Bourguiba](https://github.com/chaadow)

data/README.md

@@ -4,55 +4,11 @@
 
 `validates_overlap` provides an ActiveRecord validator for resources that must not overlap, e.g. in datetime. Think rentals, meetings, bookings, work shifts, or assignments where the same resource cannot be assigned to multiple people or entities during overlapping time periods. But it also works for other domains than datetime (see below).
 
-You specify two attributes defining a datetime range, such as `starts_at` and `ends_at`, and the validator checks with a single SQL query whether another record overlaps that range — no records are loaded for the comparison. If one does, the record receives a normal validation error.
+You specify the attributes defining a datetime range — typically two, such as `starts_at` and `ends_at`, or on PostgreSQL a single native range column — and the validator checks with a single SQL query whether another record overlaps that range; no records are loaded for the comparison. If one does, the record receives a normal validation error.
 
 It also supports scoped validation (per user, room, resource, etc.), open-ended ranges (a nil start or end counts as extending forever), ranges that may touch at their boundaries (`exclude_edges`), required gaps between ranges or a tolerated amount of overlap (`start_shift` / `end_shift`), associations, and retrieving the conflicting records.
 
-The range columns don't have to be dates or times: any linearly orderable column type works, such as integer ranges (ticket number blocks), decimal ranges (price bands), or string ranges (alphabetical partitions).
-
-## Note: Other Domains
-
-Other domains / types can be checked for overlap, as long as they can be compared linearly.
-e.g. The overlap check runs on plain SQL comparisons, so any linearly orderable column type works — for example integer ranges (no two records may claim overlapping number blocks), decimal ranges (price bands), or string ranges (alphabetical partitions). A nil endpoint means the range is open-ended on that side, for these types too, and the shifts work for numeric ranges as well (e.g. an integer gap or overlap tolerance). The test suite covers `date`, `datetime`, `timestamp`, `integer`, `decimal`, and `string` range columns.
-
-## ⚠️ Note: Cyclic Domains can NOT be validated for overlap
-
-Overlap validation requires a linear domain: every range must satisfy `start <= end`. On a cyclic (wrap-around) domain, like time, every pair of values denotes *some* valid range (`11:00..10:00` is simply the 23-hour complement of `10:00..11:00`), so a wraparound range is indistinguishable from accidentally swapped fields — no validation can tell intent from typo. This is a mathematical property of circular domains, not an implementation gap.
-
-The validator therefore refuses `:time` range columns and raises `OverlapValidator::UnsupportedColumnType` — use datetime columns instead, or split windows that cross midnight into two records.
-
-But cyclicity is a property of the domain, not the column type — ⚠️ user-encoded cyclic domains hide inside perfectly linear columns, where no guard can see them:
-
-- day-of-week as integer (0..6): a Friday-to-Monday shift range `5..1` wraps — same pathology as `22:00..02:00`, stored in an innocent `:integer` column
-- month numbers (1..12): a November-to-February season range `11..2`
-- ISO week numbers: a range from week 52 to week 2 across New Year
-- angles / compass headings (0..360): a heading sector `350..10`
-- longitude (−180°..+180°)
-- hour-of-day as integer — people re-implement `:time` in an int column all the time
-- time-of-day (24-hour clock values without a date component)
-
-If your domain is cyclic, the validator will silently give wrong answers for wrapping ranges. Restructure the data instead: split wrapping ranges into two linear records, or lift the values into a linear domain (e.g. datetime instead of time-of-day).
-
-To catch inverted ranges loudly instead of silently (for any column type), pair the overlap validation with an order check on your model, e.g. `validates :ends_at, comparison: { greater_than: :starts_at }`.
-
-## Ruby / Rails Compatibility
-
-Every combination below is verified on every push by the [CI matrix](https://github.com/tilo/validates_overlap/actions):
-
-| Rails | Tested with Ruby   |
-|-------|--------------------|
-| 8.1   | 3.2, 3.3, 3.4      |
-| 8.0   | 3.2, 3.3, 3.4      |
-| 7.2   | 3.1, 3.2, 3.3, 3.4 |
-| 7.1   | 3.0, 3.1, 3.2, 3.3 |
-| 7.0   | 3.0, 3.1, 3.2      |
-| 6.1   | 3.0                |
-
-The gemspec requires `activerecord >= 6.0`. Rails 6.0 is not part of the test matrix, but no incompatibilities are known. The previous version 0.8.6 was compatible with Rails 3, 4, and 5.
-
-Note for MySQL users: use `DATETIME` (not `TIMESTAMP`) columns for your range attributes — MySQL's `TIMESTAMP` type cannot store dates after January 2038, which matters for long-running or far-future ranges. PostgreSQL and SQLite date/time types have no such limit.
-
-## Usage
+## Quick Start
 
 Add to your gemfile
 
@@ -62,98 +18,67 @@ gem 'validates_overlap'
 
 In your model
 
-#### without scope
-
 ```ruby
 validates :starts_at, :ends_at, :overlap => true
-```
-
-#### with scope
 
-```ruby
+# or scoped, e.g. per user:
 validates :starts_at, :ends_at, :overlap => {:scope => "user_id"}
 ```
 
-#### exclude edge(s)
-
-```ruby
-validates :starts_at, :ends_at, :overlap => {:exclude_edges => "starts_at"}
-validates :starts_at, :ends_at, :overlap => {:exclude_edges => ["starts_at", "ends_at"]}
-```
+All options — scopes, edge handling, gaps and tolerated overlap, custom messages, associations, retrieving the conflicting records — are described in the [Option Reference](docs/options.md).
 
-#### shift edges
+## Documentation
 
-The shifts move the record's own range edges before the overlap check, so you can require a gap between records — or tolerate a bounded overlap:
+  * [Examples and Introduction](docs/_introduction.md)
+  * [Option Reference](docs/options.md)
+  * [Range Types and Domains](docs/range_types.md)
+  * [PostgreSQL: Exclusion Constraints](docs/postgresql.md)
 
-```ruby
-# widen the range: records must be at least 1 day apart (gap enforced)
-validates :starts_at, :ends_at, :overlap => {:start_shift => -1.day, :end_shift => 1.day}
+## Range Types
 
-# shrink the range: up to 2 days of overlap are accepted
-validates :starts_at, :ends_at, :overlap => {:start_shift => 2.days, :end_shift => -2.days}
-```
+The range columns don't have to be dates or times: any linearly orderable column type works, such as integer ranges (ticket number blocks), decimal ranges (price bands), or string ranges (alphabetical partitions). ⚠️ Cyclic (wrap-around) domains — time-of-day, day-of-week, month numbers, angles — can NOT be validated for overlap; the validator refuses `:time` columns outright. [Range Types and Domains](docs/range_types.md) explains both halves.
 
-#### non-date ranges
+## ⚠️ Concurrent Writes
 
-The overlap check runs on plain SQL comparisons, so any orderable column type works — for example integer ranges (no two records may claim overlapping number blocks), decimal ranges (price bands), or string ranges (alphabetical partitions). A nil endpoint means the range is open-ended on that side, for these types too, and the shifts work for numeric ranges as well (e.g. an integer gap or overlap tolerance). The test suite covers `date`, `datetime`, `timestamp`, `integer`, `decimal`, and `string` range columns.
+Validation alone can not prevent double-booking under concurrent writes: two simultaneous requests can both pass the check and both save — the same limitation as `validates_uniqueness_of`. On PostgreSQL, the gem's migration helpers generate an exclusion constraint that closes this race at the database level:
 
 ```ruby
-class TicketBlock < ActiveRecord::Base
-  validates :number_start, :number_end, :overlap => true
-end
-
-TicketBlock.create!(number_start: 100, number_end: 199)
-TicketBlock.new(number_start: 150, number_end: 250).valid?  # => false (overlaps)
-TicketBlock.new(number_start: 150, number_end: nil).valid?  # => false (open-ended, overlaps)
-TicketBlock.new(number_start: 200, number_end: 299).valid?  # => true
+add_overlap_constraint :meetings, :starts_at, :ends_at, scope: :user_id
 ```
 
-#### define custom validation key(s) and message
+## ⭐ PostgreSQL Support
+Native PostgreSQL range columns are supported as well — declare the validation with the single range attribute (`validates :period, overlap: ...` on a `tstzrange` column). On PostgreSQL 18+, the migration helpers can also generate the standard-SQL temporal unique constraint (`without_overlaps: true`). See [PostgreSQL: Exclusion Constraints](docs/postgresql.md) for the helpers, the range-column semantics, the companion concern that turns the constraint violation into a normal validation error, and the equivalent hand-written SQL. CI runs the PostgreSQL suite against versions 16 and 18.
 
-```ruby
-validates :starts_at, :ends_at, :overlap => {:message_title => "Some validation title", :message_content => "Some validation message"}
-validates :starts_at, :ends_at, :overlap => {:message_title => [:start_at, :end_at], :message_content => "Some validation message"}
-```
+## Note: Add an index — the overlap check runs on every save
 
-#### with complicated relations
-
-Example describes validation of user, positions and time slots.
-User can't be assigned 2 times on position which is under time slot with time overlap.
+The validation runs one `EXISTS` query per save. Without a suitable index that query is a full table scan — invisible at 1,000 rows, painful at 1,000,000. Add a composite index with your scope columns first, then the range columns:
 
 ```ruby
-class Position < ActiveRecord::Base
-  belongs_to :time_slot
-  belongs_to :user
-  validates "time_slots.starts_at", "time_slots.ends_at",
-    :overlap => {
-      :query_options => {:joins => :time_slot},
-      :scope => { "positions.user_id" => proc{|position| position.user_id} }
-    }
-end
+add_index :meetings, [:user_id, :starts_at, :ends_at]
 ```
 
-#### apply named scopes
+For unscoped validation, index the range columns alone (`[:starts_at, :ends_at]`). If you added the PostgreSQL exclusion constraint, you already have a suitable index — the constraint is backed by a GiST index that serves overlap queries. On large tables, verify with `EXPLAIN` that the query actually uses your index.
 
-```ruby
-class ActiveMeeting < ActiveRecord::Base
-  validates :starts_at, :ends_at, :overlap => {:query_options => {:active => nil}}
-  scope :active, where(:is_active => true)
-end
-```
+## Ruby / Rails Compatibility
 
-#### Overlapped records
-If you need to know what records are in conflict, pass the `{load_overlapped: true }` as validator option and validator will set instance variable `@overlapped_records` to the validated object.
+Every combination below is verified on every push by the [CI matrix](https://github.com/tilo/validates_overlap/actions):
 
-```ruby
-class ActiveMeeting < ActiveRecord::Base
-  validates :starts_at, :ends_at, :overlap => {:load_overlapped => true}
+| Rails | Tested with Ruby   |
+|-------|--------------------|
+| 8.1   | 3.2, 3.3, 3.4      |
+| 8.0   | 3.2, 3.3, 3.4      |
+| 7.2   | 3.1, 3.2, 3.3, 3.4 |
+| 7.1   | 3.0, 3.1, 3.2, 3.3 |
+| 7.0   | 3.0, 3.1, 3.2      |
+| 6.1   | 3.0                |
 
-  def overlapped_records
-    @overlapped_records || []
-  end
-end
+The gemspec requires `activerecord >= 6.0`. Rails 6.0 is not part of the test matrix, but no incompatibilities are known. The previous version 0.8.6 was compatible with Rails 3, 4, and 5.
 
-```
+Note for MySQL users: use `DATETIME` (not `TIMESTAMP`) columns for your range attributes — MySQL's `TIMESTAMP` type cannot store dates after January 2038, which matters for long-running or far-future ranges. PostgreSQL and SQLite date/time types have no such limit.
+
+## Contributing
+
+Bug reports and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for how to run the test suite against all three database adapters (SQLite, PostgreSQL, MySQL).
 
 ## Maintainership
 
@@ -161,5 +86,3 @@ end
 Since August 2026 the gem is maintained by [Tilo Sloboda](https://github.com/tilo).
 
 A big thank you to Robin for creating this awesome gem and for the years of work he put into it. ❤️
-
-

data/lib/validates_overlap/migration_helpers.rb

@@ -0,0 +1,146 @@
+module ValidatesOverlap
+  # Migration helpers for a database-level overlap guarantee (PostgreSQL only).
+  # The validation is check-then-act and cannot prevent double-booking under
+  # concurrent writes; an exclusion constraint can (see the README).
+  #
+  # == Example:
+  #   def up
+  #     add_overlap_constraint :meetings, :starts_at, :ends_at, scope: :user_id
+  #   end
+  #   def down
+  #     remove_overlap_constraint :meetings
+  #   end
+  module MigrationHelpers
+    # Two scalar columns:  add_overlap_constraint :meetings, :starts_at, :ends_at, scope: :user_id
+    # One range column:    add_overlap_constraint :meetings, :period, scope: :user_id
+    #
+    # scope:            column(s) compared with equality, mirroring the validator's :scope
+    # name:             constraint name (default: <table>_no_overlap)
+    # range_type:       PostgreSQL range type; inferred from the column types when omitted
+    # exclude_edges:    false (default) matches the validator's default — touching edges
+    #                   conflict; true builds half-open ranges, matching the validator's
+    #                   exclude_edges: [start, end] where touching is allowed.
+    #                   Not applicable to a range column (bounds live in the value)
+    # without_overlaps: PostgreSQL 18+, single range column with scope only — generate
+    #                   the standard-SQL temporal unique constraint
+    #                   UNIQUE (scope, range WITHOUT OVERLAPS) instead of the EXCLUDE clause
+    def add_overlap_constraint(table, starts_at, ends_at = nil, scope: [], name: nil, range_type: nil, exclude_edges: false, without_overlaps: false)
+      assert_postgresql!('add_overlap_constraint')
+      scope_columns = Array(scope)
+      warn_nullable_scope_columns(table, scope_columns)
+      enable_extension 'btree_gist' if !scope_columns.empty? && !connection.extension_enabled?('btree_gist')
+      return add_without_overlaps_constraint(table, starts_at, ends_at, scope_columns, name, exclude_edges) if without_overlaps
+      elements = scope_columns.map { |column| "#{connection.quote_column_name(column)} WITH =" }
+      if ends_at.nil?
+        raise ArgumentError, 'validates_overlap: exclude_edges is not applicable to a range column — bound inclusivity is part of the range value itself' if exclude_edges
+        assert_range_column!(table, starts_at)
+        elements << "#{connection.quote_column_name(starts_at)} WITH &&"
+      else
+        range_type ||= overlap_range_type(table, starts_at, ends_at)
+        bounds = exclude_edges ? '[)' : '[]'
+        elements << "#{range_type}(#{connection.quote_column_name(starts_at)}, #{connection.quote_column_name(ends_at)}, '#{bounds}') WITH &&"
+      end
+      if connection.respond_to?(:add_exclusion_constraint)
+        # Rails 7.1+: the recorded command is invertible, so the helper works in def change
+        add_exclusion_constraint table, elements.join(', '), using: :gist, name: overlap_constraint_name(table, name)
+      else
+        execute <<~SQL
+          ALTER TABLE #{connection.quote_table_name(table)}
+            ADD CONSTRAINT #{connection.quote_column_name(overlap_constraint_name(table, name))}
+            EXCLUDE USING gist (#{elements.join(', ')})
+        SQL
+      end
+    end
+
+    # A plain DROP CONSTRAINT on purpose: it drops both constraint forms, while
+    # Rails' remove_exclusion_constraint refuses a temporal unique constraint
+    # (without_overlaps) — and delegating would not make removal invertible in
+    # def change anyway, since the inversion needs the original expression
+    def remove_overlap_constraint(table, name: nil)
+      assert_postgresql!('remove_overlap_constraint')
+      execute "ALTER TABLE #{connection.quote_table_name(table)} DROP CONSTRAINT #{connection.quote_column_name(overlap_constraint_name(table, name))}"
+    end
+
+    private
+
+    # PostgreSQL 18's temporal unique constraint. PostgreSQL enforces it as an
+    # exclusion constraint — UNIQUE (id, r WITHOUT OVERLAPS) behaves like
+    # EXCLUDE USING GIST (id WITH =, r WITH &&) and violations raise
+    # PG::ExclusionViolation — so RescueExclusionViolation keeps working.
+    # Differences to the EXCLUDE form: standard SQL syntax, but empty ranges are
+    # rejected by the database, and the raw SQL here cannot be inverted by
+    # Rails — use def up / def down with this option
+    def add_without_overlaps_constraint(table, range_column, ends_at, scope_columns, name, exclude_edges)
+      raise ArgumentError, 'validates_overlap: without_overlaps applies to a single range column — the two-column form builds a range expression, which PostgreSQL does not allow in a temporal constraint' unless ends_at.nil?
+      raise ArgumentError, 'validates_overlap: exclude_edges is not applicable to a range column — bound inclusivity is part of the range value itself' if exclude_edges
+      raise ArgumentError, 'validates_overlap: without_overlaps needs at least one scope column — PostgreSQL requires an ordinary column before WITHOUT OVERLAPS' if scope_columns.empty?
+      raise ArgumentError, "validates_overlap: without_overlaps requires PostgreSQL 18+ (the server reports version #{connection.database_version})" if connection.database_version < 180_000
+      assert_range_column!(table, range_column)
+      columns = scope_columns.map { |column| connection.quote_column_name(column) } + ["#{connection.quote_column_name(range_column)} WITHOUT OVERLAPS"]
+      execute <<~SQL
+        ALTER TABLE #{connection.quote_table_name(table)}
+          ADD CONSTRAINT #{connection.quote_column_name(overlap_constraint_name(table, name))}
+          UNIQUE (#{columns.join(', ')})
+      SQL
+    end
+
+    # NULL = NULL is not true in SQL, so the constraint never restricts rows whose
+    # scope value is NULL — while the validator DOES match NULL scope values against
+    # each other (see docs/postgresql.md). Warn so the gap is a choice, not a surprise.
+    def warn_nullable_scope_columns(table, scope_columns)
+      return if scope_columns.empty?
+      columns = connection.columns(table).index_by(&:name)
+      scope_columns.each do |scope_column|
+        column = columns[scope_column.to_s]
+        next unless column&.null
+        say "validates_overlap: scope column #{scope_column} on #{table} allows NULL — rows with a NULL #{scope_column} are NOT restricted by this constraint (NULL = NULL is not true in SQL), while the overlap validation does match NULL scope values against each other. Consider a NOT NULL constraint on #{scope_column}."
+      end
+    end
+
+    def assert_range_column!(table, column_name)
+      column = connection.columns(table).find { |col| col.name == column_name.to_s }
+      raise ArgumentError, "validates_overlap: no column #{column_name} on #{table}" unless column
+      return if OverlapValidator::RANGE_COLUMN_TYPES.include?(column.type)
+      raise ArgumentError, "validates_overlap: #{column_name} on #{table} is #{column.type.inspect}, not a range column — pass two columns for scalar range endpoints"
+    end
+
+    def overlap_constraint_name(table, name)
+      name || "#{table}_no_overlap"
+    end
+
+    def assert_postgresql!(method_name)
+      return if connection.adapter_name.match?(/postgresql/i)
+      raise NotImplementedError, "validates_overlap: #{method_name} requires PostgreSQL (exclusion constraints are not available on #{connection.adapter_name})"
+    end
+
+    def overlap_range_type(table, starts_at, ends_at)
+      columns = connection.columns(table).index_by(&:name)
+      range_types = [starts_at, ends_at].map do |attr|
+        column = columns[attr.to_s]
+        raise ArgumentError, "validates_overlap: no column #{attr} on #{table}" unless column
+        range_type_for(column)
+      end.uniq
+      raise ArgumentError, "validates_overlap: #{starts_at} and #{ends_at} on #{table} have different types; pass range_type: explicitly" if range_types.size > 1
+      range_types.first
+    end
+
+    def range_type_for(column)
+      case column.type
+      when :datetime, :timestamp
+        column.sql_type.match?(/with time zone/) ? 'tstzrange' : 'tsrange'
+      when :date
+        'daterange'
+      when :integer
+        column.limit == 8 ? 'int8range' : 'int4range'
+      when :decimal
+        'numrange'
+      else
+        raise ArgumentError, "validates_overlap: cannot infer a range type for #{column.name} (#{column.type}); pass range_type: explicitly"
+      end
+    end
+  end
+end
+
+ActiveSupport.on_load(:active_record) do
+  ActiveRecord::Migration.include(ValidatesOverlap::MigrationHelpers)
+end

data/lib/validates_overlap/overlap_validator.rb

@@ -7,10 +7,29 @@ class OverlapValidator < ActiveModel::EachValidator
   # operate on (e.g. :time — a cyclic domain, see README)
   class UnsupportedColumnType < ArgumentError; end
 
+  # PostgreSQL range column types usable with the single-attribute form
+  RANGE_COLUMN_TYPES = %i[tsrange tstzrange daterange int4range int8range numrange].freeze
+
   def initialize(args)
     attributes_are_range(args[:attributes])
+    reject_range_column_options(args)
+    model_class = args[:class]
 
     super
+
+    # defines record.overlapping_records on the validated model
+    model_class.include(ValidatesOverlap::OverlappingRecords) if model_class
+    if options[:load_overlapped]
+      ValidatesOverlap.deprecator.warn('load_overlapped is deprecated and will be removed in validates_overlap 2.0 — use record.overlapping_records instead')
+    end
+  end
+
+  # Build and return the overlap query for the given record — used by
+  # ValidatesOverlap::OverlappingRecords#overlapping_records
+  def overlapping_records_for(record)
+    reject_unsupported_column_types(record)
+    relation, sql_conditions, sql_values = initialize_query(record, options)
+    get_overlapped(relation, sql_conditions, sql_values)
   end
 
   # NOTE: Rails registers ONE validator instance per model class, shared by every
@@ -24,17 +43,24 @@ class OverlapValidator < ActiveModel::EachValidator
         record.instance_variable_set(:@overlapped_records, get_overlapped(relation, sql_conditions, sql_values))
       end
 
-      if record.respond_to? attributes.first
-        if options[:message_title].is_a?(Array)
-          options[:message_title].each do |key|
-            record.errors.add(key, options[:message_content] || :overlap)
-          end
-        else
-          record.errors.add(options[:message_title] || attributes.first, options[:message_content] || :overlap)
+      add_overlap_error(record)
+    end
+  end
+
+  # Add this validation's configured error to the record. Also used by
+  # ValidatesOverlap::RescueExclusionViolation so a constraint violation caught
+  # in the race window lands on exactly the same keys as a validator-caught one
+  def add_overlap_error(record)
+    if record.respond_to? attributes.first
+      if options[:message_title].is_a?(Array)
+        options[:message_title].each do |key|
+          record.errors.add(key, options[:message_content] || :overlap)
         end
       else
-        record.errors.add(options[:message_title] || :base, options[:message_content] || :overlap)
+        record.errors.add(options[:message_title] || attributes.first, options[:message_content] || :overlap)
       end
+    else
+      record.errors.add(options[:message_title] || :base, options[:message_content] || :overlap)
     end
   end
 
@@ -47,34 +73,67 @@ class OverlapValidator < ActiveModel::EachValidator
   # metadata must not be touched while migrations may still be pending.
   def reject_unsupported_column_types(record)
     return unless record.class.respond_to?(:columns_hash)
+    if range_column_mode?
+      attr = attributes.first
+      column = record.class.columns_hash[attr.to_s]
+      return if column && RANGE_COLUMN_TYPES.include?(column.type)
+      found = column ? column.type.inspect : 'no column at all'
+      raise UnsupportedColumnType, "#{record.class.name}##{attr}: a single-attribute overlap validation requires a PostgreSQL range column (#{RANGE_COLUMN_TYPES.join(', ')}), but #{attr} is #{found} — declare two attributes for scalar range endpoints"
+    end
     attributes.each do |attr|
       next if attr.to_s.include?('.')
       column = record.class.columns_hash[attr.to_s]
-      next unless column && column.type == :time
+      next unless column
+      if RANGE_COLUMN_TYPES.include?(column.type)
+        raise UnsupportedColumnType, "#{record.class.name}##{attr} is a #{column.type} range column — a range column is validated on its own (validates :#{attr}, overlap: ...); a two-attribute validation takes scalar range endpoints"
+      end
+      next unless column.type == :time
       raise UnsupportedColumnType, "#{record.class.name}##{attr} is a :time column; time-of-day is a cyclic domain and cannot be validated for overlap — use datetime columns, or split ranges that cross midnight (see README)"
     end
   end
 
-  # Build the complete overlap query for this record.
+  # One attribute = a native range column, compared with PostgreSQL's && operator
+  def range_column_mode?
+    attributes.size == 1
+  end
+
+  # Edge inclusivity and shifts live in the range value itself, so these
+  # options have nothing to act on — refuse loudly instead of ignoring
+  def reject_range_column_options(args)
+    return unless args[:attributes].size == 1
+    invalid = [:exclude_edges, :start_shift, :end_shift].select { |key| args[key] }
+    return if invalid.empty?
+    raise ArgumentError, "validates_overlap: #{invalid.join(', ')} not applicable to a range column — edge inclusivity and shifts are part of the range value itself"
+  end
+
+  # Build the complete overlap query for this record. Range-column mode builds
+  # the whole query on the relation (sql_conditions/sql_values stay nil); the
+  # two-attribute mode carries its conditions as a SQL string with bind values.
   # return array in form [relation, sql_conditions, sql_values]
   def initialize_query(record, options = {})
     scoped_model = options[:scoped_model].present? ? options[:scoped_model].constantize : record.class
     relation = scoped_model.default_scoped
-    sql_values = generate_overlap_sql_values(record)
-    sql_conditions, primary_key_values = generate_overlap_sql_conditions(record, sql_values)
-    sql_values = sql_values.merge(primary_key_values)
-    sql_conditions, sql_values = add_attributes(record, options[:scope], sql_conditions, sql_values) if options && options[:scope].present?
+    if range_column_mode?
+      relation = range_column_relation(relation, record)
+      relation = add_scope_to_relation(record, options[:scope], relation) if options && options[:scope].present?
+      sql_conditions = sql_values = nil
+    else
+      sql_values = generate_overlap_sql_values(record)
+      sql_conditions, primary_key_values = generate_overlap_sql_conditions(record, sql_values)
+      sql_values = sql_values.merge(primary_key_values)
+      sql_conditions, sql_values = add_attributes(record, options[:scope], sql_conditions, sql_values) if options && options[:scope].present?
+    end
     relation = add_query_options(relation, options[:query_options]) if options && options[:query_options].present?
     [relation, sql_conditions, sql_values]
   end
 
   # Check if exists at least one record in DB which is overlapped with current record
   def overlapped_exists?(relation, sql_conditions, sql_values)
-    relation.exists?([sql_conditions, sql_values])
+    sql_conditions ? relation.exists?([sql_conditions, sql_values]) : relation.exists?
   end
 
   def get_overlapped(relation, sql_conditions, sql_values)
-    relation.where([sql_conditions, sql_values])
+    sql_conditions ? relation.where([sql_conditions, sql_values]) : relation
   end
 
   # Resolve attributes values from record to use in sql conditions
@@ -115,9 +174,44 @@ class OverlapValidator < ActiveModel::EachValidator
     record.class.table_name
   end
 
-  # Check if the validation of time range is defined by 2 attributes
+  # A range is defined by 2 scalar attributes, or by 1 range-column attribute
   def attributes_are_range(attributes)
-    fail 'Validation of time range must be defined by 2 attributes' unless attributes.size == 2
+    fail 'Validation of time range must be defined by 1 or 2 attributes' unless [1, 2].include?(attributes.size)
+  end
+
+  # Native range column: PostgreSQL's own && operator does the comparison, and
+  # its range algebra decides every edge case — NULL overlaps nothing, 'empty'
+  # overlaps nothing, '(,)' overlaps everything, bound inclusivity comes from
+  # the stored value. The value is bound through the column's type via Arel,
+  # and a persisted record excludes itself with where.not on the primary key.
+  # return the relation with the overlap comparison applied
+  def range_column_relation(relation, record)
+    attr = attributes.first
+    value = record.send(attr)
+    return relation.none if value.nil?
+    arel_attribute = record.class.arel_table[attr]
+    relation = relation.where(Arel::Nodes::InfixOperation.new('&&', arel_attribute, Arel::Nodes.build_quoted(value, arel_attribute)))
+    return relation if record.new_record?
+    relation.where.not(record.class.primary_key => record.send(record.class.primary_key))
+  end
+
+  # Range mode adds scope conditions to the relation itself (two-attribute mode
+  # appends them to its SQL string via add_attributes): a nil value becomes
+  # IS NULL, an Array becomes IN, and procs / enum names resolve as everywhere
+  def add_scope_to_relation(record, attrs, relation)
+    pairs = attrs.is_a?(Hash) ? attrs.to_a : Array(attrs).map { |attr_name| [attr_name, nil] }
+    pairs.each do |attr_name, value|
+      relation = relation.where(attribute_to_sql(attr_name, record) => resolve_attribute_value(record, attr_name, value))
+    end
+    relation
+  end
+
+  # Exclude a persisted record from the comparison by its primary key
+  # return array in form [sql_conditions, sql_values]
+  def primary_key_exclusion(record)
+    return ['', {}] if record.new_record?
+    key = primary_key_value(primary_key(record), record)
+    ["#{record_table_name(record)}.#{primary_key(record)} != :record_primary_key_value", { record_primary_key_value: key }]
   end
 
   def primary_key(record)
@@ -134,12 +228,9 @@ class OverlapValidator < ActiveModel::EachValidator
   def generate_overlap_sql_conditions(record, sql_values)
     starts_at_attr, ends_at_attr = attributes_to_sql(record)
     main_condition = condition_string(starts_at_attr, ends_at_attr, sql_values)
-    if record.new_record?
-      [main_condition, {}]
-    else
-      key = primary_key_value(primary_key(record), record)
-      ["#{main_condition} AND #{record_table_name(record)}.#{primary_key(record)} != :record_primary_key_value", { record_primary_key_value: key }]
-    end
+    pk_conditions, pk_values = primary_key_exclusion(record)
+    return [main_condition, {}] if pk_conditions.empty?
+    ["#{main_condition} AND #{pk_conditions}", pk_values]
   end
 
   # Return hash of values for overlap sql condition; a nil endpoint means the

data/lib/validates_overlap/overlapping_records.rb

@@ -0,0 +1,26 @@
+module ValidatesOverlap
+  # Included into a model class when it declares an overlap validation
+  module OverlappingRecords
+    # The records whose ranges overlap this record's range, freshly queried on
+    # every call and respecting the validation's options (scope, scoped_model,
+    # shifts, exclude_edges, and self-exclusion for persisted records).
+    # Returns an ActiveRecord::Relation — no records are loaded until used.
+    def overlapping_records
+      relations = self.class.validators.grep(OverlapValidator).map { |validator| validator.overlapping_records_for(self) }
+      # a validation whose range value is nil conflicts with nothing — its empty
+      # relation must not join the union: Relation#or keeps a NullRelation's
+      # emptiness on Rails 6.1/7.0, which would hide the other validations' conflicts
+      # (Relation#null_relation? arrived in 7.1; before that .none is detectable
+      # by its extended NullRelation module, a constant removed in Rails 8)
+      relations = relations.reject do |relation|
+        relation.respond_to?(:null_relation?) ? relation.null_relation? : relation.extending_values.include?(ActiveRecord::NullRelation)
+      end
+      return self.class.none if relations.empty?
+      models = relations.map(&:klass).uniq
+      # Relation#or never compares the relations' classes — a union across models
+      # would silently run one validation's conditions against the other's table
+      raise ArgumentError, "overlapping_records cannot combine overlap validations that query different models (#{models.join(', ')}) — query each model separately" if models.size > 1
+      relations.reduce(:or)
+    end
+  end
+end

data/lib/validates_overlap/rescue_exclusion_violation.rb

@@ -0,0 +1,73 @@
+module ValidatesOverlap
+  # Opt-in companion to the exclusion constraint (see MigrationHelpers): in the
+  # race window the validator cannot see, the constraint raises — this concern
+  # rescues that and turns it into a normal validation failure: save returns
+  # false with errors populated, save! raises ActiveRecord::RecordInvalid.
+  #
+  # NOTE: a statement error aborts the innermost database transaction, so when
+  # the caller already has a joinable transaction open, save runs in its own
+  # savepoint (requires_new) with the rescue OUTSIDE it — otherwise the rescue
+  # would leave the caller's transaction in the aborted state. (The same
+  # pattern the Rails guides document for rescuing RecordNotUnique.)
+  # In every other situation the wrapper must NOT be added: ActiveRecord's own
+  # save transaction already contains the error there, and an extra wrapper at
+  # top level makes the save transaction JOIN it — silently swallowing the
+  # rollback a halted callback (throw :abort) relies on.
+  #
+  # == Example:
+  #   class Meeting < ActiveRecord::Base
+  #     validates :starts_at, :ends_at, overlap: { scope: :user_id }
+  #     include ValidatesOverlap::RescueExclusionViolation
+  #   end
+  module RescueExclusionViolation
+    def save(...)
+      contain_exclusion_violation { super }
+    rescue ActiveRecord::StatementInvalid => e
+      raise unless ValidatesOverlap.exclusion_violation?(e)
+      add_overlap_error
+      false
+    end
+
+    def save!(...)
+      contain_exclusion_violation { super }
+    rescue ActiveRecord::StatementInvalid => e
+      raise unless ValidatesOverlap.exclusion_violation?(e)
+      add_overlap_error
+      raise ActiveRecord::RecordInvalid, self
+    end
+
+    private
+
+    # See the NOTE above: the savepoint exists to protect a caller's open
+    # joinable transaction, and only PostgreSQL can raise the violation this
+    # concern rescues — everywhere else the wrapper would be pure overhead
+    # (a SAVEPOINT/RELEASE round-trip per save) or actively harmful (the
+    # swallowed rollback-on-abort at top level)
+    def contain_exclusion_violation(&block)
+      connection = self.class.connection
+      if connection.adapter_name.match?(/postgresql/i) && connection.transaction_open? && connection.current_transaction.joinable?
+        self.class.transaction(requires_new: true, &block)
+      else
+        yield
+      end
+    end
+
+    # mirror the validator's error placement exactly (add_overlap_error on the
+    # validator handles array titles and the :base fallback); with several
+    # overlap validations the database does not tell us which constraint
+    # fired — the first validator's message settings are used
+    def add_overlap_error
+      validator = self.class.validators.grep(OverlapValidator).first
+      if validator
+        validator.add_overlap_error(self)
+      else
+        errors.add(:base, :overlap)
+      end
+    end
+  end
+
+  def self.exclusion_violation?(error)
+    return true if defined?(ActiveRecord::ExclusionViolation) && error.is_a?(ActiveRecord::ExclusionViolation)
+    !!(defined?(PG::ExclusionViolation) && error.cause.is_a?(PG::ExclusionViolation))
+  end
+end

data/lib/validates_overlap/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ValidatesOverlap
-  VERSION = '1.2.0'
+  VERSION = '1.3.0'
 end

data/lib/validates_overlap.rb

@@ -1,2 +1,11 @@
 require_relative 'validates_overlap/version'
+require_relative 'validates_overlap/overlapping_records'
 require_relative 'validates_overlap/overlap_validator'
+require_relative 'validates_overlap/migration_helpers'
+require_relative 'validates_overlap/rescue_exclusion_violation'
+
+module ValidatesOverlap
+  def self.deprecator
+    @deprecator ||= ActiveSupport::Deprecation.new('2.0', 'validates_overlap')
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: validates_overlap
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Robin Bortlik
@@ -67,7 +67,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: pry
+  name: pg
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -81,7 +81,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: pry
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -95,7 +95,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rb-readline
+  name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -184,15 +184,19 @@ files:
 - lib/validates_overlap/locale/es.yml
 - lib/validates_overlap/locale/pt-BR.yml
 - lib/validates_overlap/locale/ru.yml
+- lib/validates_overlap/migration_helpers.rb
 - lib/validates_overlap/overlap_validator.rb
+- lib/validates_overlap/overlapping_records.rb
+- lib/validates_overlap/rescue_exclusion_violation.rb
 - lib/validates_overlap/version.rb
 homepage: https://github.com/tilo/validates_overlap
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/tilo/validates_overlap/tree/v1.2.0
+  source_code_uri: https://github.com/tilo/validates_overlap/tree/v1.3.0
   bug_tracker_uri: https://github.com/tilo/validates_overlap/issues
   changelog_uri: https://github.com/tilo/validates_overlap/blob/main/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/validates_overlap
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: