chrono_model 4.0.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8e1a4cdc29f1fa0435f82c9277674a7085e6caf445ea45673995864038d8a1b
-  data.tar.gz: 60df7e87f659a392cf22e8a754b608d7d1fc030d4f63a30dde4af1644ab7917d
+  metadata.gz: 6465bfc1eca17fb499f1826a7b938969bc7306b388ac93bce746a09c75a2c1a4
+  data.tar.gz: 6958a3018c4a29dbd4b81a56c60bc02d4fc8696780b62fe1ec8778725152e12d
 SHA512:
-  metadata.gz: 22333be09e65a5347f3413976eea41581b76c7ad94dc138924cd7e5e8f6cb36cd572567f6b195c896a14262d96a3623f7b49116ed2856dcf58441ad4f43ceff2
-  data.tar.gz: 9d96851d9dc3947e485a1c09c89eb06c0e5b07a0ddf9c43e75bdd1c3bb13ca4df599e7f4e8050268ba30c00de7878d1a6c496db1f70b2e3e9c76f0bb10d3d63c
+  metadata.gz: 4f0cf88eb3e21ec2cee85ba744a426e5ab125a71c18e4c7cbe31b45cbb5198f8f8dcbd1e17b87766cf3b386ebaf789fcb9dfd5190bb7e47bf61c3d9824fda490
+  data.tar.gz: e852d433e7d5c28f69e50511d0f094ae16fcb0f28cfc825273485c607b6e5fb2adc6d9cc82f0ec78c680c6e07392f296bfa27afcfe54d05595c3ac04a1a9e2cb

data/README.md

@@ -1,8 +1,6 @@
 # Temporal database system on PostgreSQL using [updatable views][pg-updatable-views], [table inheritance][pg-table-inheritance] and [INSTEAD OF triggers][pg-instead-of-triggers].
 
 [![Build Status][build-status-badge]][build-status]
-[![Code Climate][code-analysis-badge]][code-analysis]
-[![Test Coverage][test-coverage-badge]][test-coverage]
 [![Gem Version][gem-version-badge]][gem-version]
 [![Inlinedocs][docs-analysis-badge]][docs-analysis]
 
@@ -98,6 +96,79 @@ format:
 config.active_record.schema_format = :sql
 ```
 
+## Database Permissions (PostgreSQL)
+
+ChronoModel creates and manages data in the `temporal` and `history` schemas. Your application database user needs appropriate privileges on these schemas and their objects.
+
+### Required Privileges
+
+Grant the following privileges to your application database user (replace `app_user` with your actual username):
+
+```sql
+-- Schema access
+GRANT USAGE ON SCHEMA temporal TO app_user;
+GRANT USAGE ON SCHEMA history TO app_user;
+
+-- Table privileges for existing objects
+GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA temporal TO app_user;
+GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA history TO app_user;
+
+-- Sequence privileges for existing objects
+GRANT USAGE, SELECT, UPDATE ON ALL SEQUENCES IN SCHEMA temporal TO app_user;
+GRANT USAGE, SELECT, UPDATE ON ALL SEQUENCES IN SCHEMA history TO app_user;
+
+-- Default privileges for future objects
+ALTER DEFAULT PRIVILEGES IN SCHEMA temporal GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO app_user;
+ALTER DEFAULT PRIVILEGES IN SCHEMA history GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO app_user;
+ALTER DEFAULT PRIVILEGES IN SCHEMA temporal GRANT USAGE, SELECT, UPDATE ON SEQUENCES TO app_user;
+ALTER DEFAULT PRIVILEGES IN SCHEMA history GRANT USAGE, SELECT, UPDATE ON SEQUENCES TO app_user;
+```
+
+### Quick Diagnostics
+
+You can verify your privileges are correctly set up by running these queries as your application user:
+
+```sql
+-- Check schema access
+SELECT 
+  schema_name,
+  has_schema_privilege(current_user, schema_name, 'USAGE') AS has_usage
+FROM information_schema.schemata 
+WHERE schema_name IN ('temporal', 'history');
+
+-- Check table privileges (run after creating temporal tables)
+SELECT 
+  schemaname,
+  tablename,
+  has_table_privilege(current_user, schemaname||'.'||tablename, 'SELECT') AS has_select,
+  has_table_privilege(current_user, schemaname||'.'||tablename, 'INSERT') AS has_insert,
+  has_table_privilege(current_user, schemaname||'.'||tablename, 'UPDATE') AS has_update,
+  has_table_privilege(current_user, schemaname||'.'||tablename, 'DELETE') AS has_delete
+FROM pg_tables 
+WHERE schemaname IN ('temporal', 'history');
+
+-- Check sequence privileges (run after creating temporal tables)
+SELECT 
+  schemaname,
+  sequencename,
+  has_sequence_privilege(current_user, schemaname||'.'||sequencename, 'USAGE') AS has_usage,
+  has_sequence_privilege(current_user, schemaname||'.'||sequencename, 'SELECT') AS has_select,
+  has_sequence_privilege(current_user, schemaname||'.'||sequencename, 'UPDATE') AS has_update
+FROM pg_sequences 
+WHERE schemaname IN ('temporal', 'history');
+```
+
+### Troubleshooting
+
+If you encounter these symptoms, check your database permissions:
+
+- **`ActiveRecord::UnknownPrimaryKey`** errors on temporalized models
+- **`Model.chrono?` returns `false`** for models that should be temporal
+- **Unexpected primary key or temporalization issues** during schema operations
+- **Permission denied errors** when ChronoModel tries to access temporal/history objects
+
+These issues often indicate insufficient privileges on the `temporal` and `history` schemas. Run the diagnostic queries above to identify missing privileges, then apply the appropriate `GRANT` statements.
+
 ## Schema creation
 
 ChronoModel hooks all `ActiveRecord::Migration` methods to make them temporal
@@ -146,8 +217,7 @@ the `:validity` option:
 change_table :your_table, temporal: true, copy_data: true, validity: '1977-01-01'
 ```
 
-Please note that `change_table` requires you to use *old_style* `up` and
-`down` migrations. It cannot work with Rails 3-style `change` migrations.
+Please note that `change_table` requires you to use `up` and `down` migrations.
 
 
 ## Selective Journaling
@@ -347,9 +417,6 @@ Ensure to run the full test suite before pushing.
 
  * Foreign keys are not supported. [See issue #174][gh-issue-174]
 
- * There may be unexpected results when combining eager loading and joins.
-   [See issue #186][gh-issue-186]
-
  * Global ID ignores historical objects. [See issue #192][gh-issue-192]
 
  * Different historical objects are considered the identical. [See issue
@@ -359,6 +426,12 @@ Ensure to run the full test suite before pushing.
    creates a new record for each modification. This will lead to increased
    storage requirements and bloated history
 
+ * `*_by_sql` query methods are not supported. [See issue #313][gh-issue-313]
+
+ * `self.table_name` must be set before `include ChronoModel::TimeMachine`.
+   [See issue #336][gh-issue-336]
+
+
 ## Contributing
 
  1. Fork it
@@ -383,14 +456,10 @@ This software is Made in Italy :it: :smile:.
 
 [build-status]: https://github.com/ifad/chronomodel/actions
 [build-status-badge]: https://github.com/ifad/chronomodel/actions/workflows/ruby.yml/badge.svg
-[code-analysis]: https://codeclimate.com/github/ifad/chronomodel/maintainability
-[code-analysis-badge]: https://api.codeclimate.com/v1/badges/cdee7327938dc2eaff99/maintainability
 [docs-analysis]: https://inch-ci.org/github/ifad/chronomodel
 [docs-analysis-badge]: https://inch-ci.org/github/ifad/chronomodel.svg?branch=master
 [gem-version]: https://rubygems.org/gems/chrono_model
 [gem-version-badge]: https://badge.fury.io/rb/chrono_model.svg
-[test-coverage]: https://codeclimate.com/github/ifad/chronomodel
-[test-coverage-badge]: https://codeclimate.com/github/ifad/chronomodel/badges/coverage.svg
 
 [delorean-image]: https://i.imgur.com/DD77F4s.jpg
 
@@ -422,6 +491,7 @@ This software is Made in Italy :it: :smile:.
 
 [gh-pzac]: https://github.com/pzac
 [gh-issue-174]: https://github.com/ifad/chronomodel/issues/174
-[gh-issue-186]: https://github.com/ifad/chronomodel/issues/186
 [gh-issue-192]: https://github.com/ifad/chronomodel/issues/192
 [gh-issue-206]: https://github.com/ifad/chronomodel/issues/206
+[gh-issue-313]: https://github.com/ifad/chronomodel/issues/313
+[gh-issue-336]: https://github.com/ifad/chronomodel/issues/336

data/lib/active_record/connection_adapters/chronomodel_adapter.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'chrono_model'
+require_relative '../../chrono_model'
 
 module ActiveRecord
   # TODO: Remove when dropping Rails < 7.2 compatibility

data/lib/active_record/tasks/chronomodel_database_tasks.rb

@@ -32,7 +32,7 @@ module ActiveRecord
         args = ['-c', '-f', target.to_s]
         args << chronomodel_configuration[:database]
 
-        run_cmd 'pg_dump', args, 'dumping data'
+        run_cmd_with_compatibility('pg_dump', args, 'dumping data')
       end
 
       def data_load(source)
@@ -41,7 +41,7 @@ module ActiveRecord
         args = ['-f', source]
         args << chronomodel_configuration[:database]
 
-        run_cmd 'psql', args, 'loading data'
+        run_cmd_with_compatibility('psql', args, 'loading data')
       end
 
       private
@@ -50,6 +50,19 @@ module ActiveRecord
         @chronomodel_configuration ||= @configuration_hash
       end
 
+      # TODO: replace `run_cmd_with_compatibility` with `run_cmd` and remove when dropping Rails < 8.1 support
+      # Compatibility method to handle Rails version differences in run_cmd signature
+      # Rails < 8.1: run_cmd(cmd, args, action)
+      # Rails >= 8.1: run_cmd(cmd, *args, **opts)
+      def run_cmd_with_compatibility(cmd, args, action_description)
+        # Check if run_cmd method accepts keyword arguments (new signature)
+        if method(:run_cmd).parameters.any? { |type, _name| type == :rest }
+          run_cmd(cmd, *args)
+        else
+          run_cmd(cmd, args, action_description)
+        end
+      end
+
       # If a schema search path is defined in the configuration file, it will
       # be used by the database tasks class to dump only the specified search
       # path. Here we add also ChronoModel's temporal and history schemas to

data/lib/chrono_model/adapter/ddl.rb

@@ -55,12 +55,12 @@ module ChronoModel
         parent = "#{TEMPORAL_SCHEMA}.#{table}"
         p_pkey = primary_key(parent)
 
-        execute <<-SQL.squish
-            CREATE TABLE #{table} (
-              hid         BIGSERIAL PRIMARY KEY,
-              validity    tsrange NOT NULL,
-              recorded_at timestamp NOT NULL DEFAULT timezone('UTC', now())
-            ) INHERITS ( #{parent} )
+        execute <<~SQL.squish
+          CREATE TABLE #{table} (
+            hid         BIGSERIAL PRIMARY KEY,
+            validity    tsrange NOT NULL,
+            recorded_at timestamp NOT NULL DEFAULT timezone('UTC', now())
+          ) INHERITS (#{parent})
         SQL
 
         add_history_validity_constraint(table, p_pkey)
@@ -85,11 +85,11 @@ module ChronoModel
         execute <<-SQL.strip_heredoc # rubocop:disable Rails/SquishedSQLHeredocs,Rails/StripHeredoc
             CREATE OR REPLACE FUNCTION chronomodel_#{table}_insert() RETURNS TRIGGER AS $$
                 BEGIN
-                    #{insert_sequence_sql(pk, current)} INTO #{current} ( #{pk}, #{fields} )
-                    VALUES ( NEW.#{pk}, #{values} );
+                    #{insert_sequence_sql(pk, current)} INTO #{current} (#{pk}, #{fields})
+                    VALUES (NEW.#{pk}, #{values});
 
-                    INSERT INTO #{history} ( #{pk}, #{fields}, validity )
-                    VALUES ( NEW.#{pk}, #{values}, tsrange(timezone('UTC', now()), NULL) );
+                    INSERT INTO #{history} (#{pk}, #{fields}, validity)
+                    VALUES (NEW.#{pk}, #{values}, tsrange(timezone('UTC', now()), NULL));
 
                     RETURN NEW;
                 END;
@@ -150,7 +150,7 @@ module ChronoModel
                     _new := row(#{journal.map { |c| "NEW.#{c}" }.join(', ')});
 
                     IF _old IS NOT DISTINCT FROM _new THEN
-                        UPDATE ONLY #{current} SET ( #{fields} ) = ( #{values} ) WHERE #{pk} = OLD.#{pk};
+                        UPDATE ONLY #{current} SET (#{fields}) = (#{values}) WHERE #{pk} = OLD.#{pk};
                         RETURN NEW;
                     END IF;
 
@@ -160,16 +160,16 @@ module ChronoModel
                     #{"SELECT hid INTO _hid FROM #{history} WHERE #{pk} = OLD.#{pk} AND lower(validity) = _now;" unless ENV['CHRONOMODEL_NO_SQUASH']}
 
                     IF _hid IS NOT NULL THEN
-                        UPDATE #{history} SET ( #{fields} ) = ( #{values} ) WHERE hid = _hid;
+                        UPDATE #{history} SET (#{fields}) = (#{values}) WHERE hid = _hid;
                     ELSE
                         UPDATE #{history} SET validity = tsrange(lower(validity), _now)
                         WHERE #{pk} = OLD.#{pk} AND upper_inf(validity);
 
-                        INSERT INTO #{history} ( #{pk}, #{fields}, validity )
-                            VALUES ( OLD.#{pk}, #{values}, tsrange(_now, NULL) );
+                        INSERT INTO #{history} (#{pk}, #{fields}, validity)
+                            VALUES (OLD.#{pk}, #{values}, tsrange(_now, NULL));
                     END IF;
 
-                    UPDATE ONLY #{current} SET ( #{fields} ) = ( #{values} ) WHERE #{pk} = OLD.#{pk};
+                    UPDATE ONLY #{current} SET (#{fields}) = (#{values}) WHERE #{pk} = OLD.#{pk};
 
                     RETURN NEW;
                 END;
@@ -234,7 +234,6 @@ module ChronoModel
                     INSERT
         SQL
       end
-      # private
     end
   end
 end

data/lib/chrono_model/adapter/indexes.rb

@@ -24,15 +24,13 @@ module ChronoModel
           temporal_index_names(table, range, options)
 
         chrono_alter_index(table, options) do
-          execute <<-SQL.squish
-            CREATE INDEX #{range_idx} ON #{table} USING gist ( #{range} )
-          SQL
+          execute "CREATE INDEX #{range_idx} ON #{table} USING gist (#{range})"
 
           # Indexes used for precise history filtering, sorting and, in history
           # tables, by UPDATE / DELETE triggers.
           #
-          execute "CREATE INDEX #{lower_idx} ON #{table} ( lower(#{range}) )"
-          execute "CREATE INDEX #{upper_idx} ON #{table} ( upper(#{range}) )"
+          execute "CREATE INDEX #{lower_idx} ON #{table} (lower(#{range}))"
+          execute "CREATE INDEX #{upper_idx} ON #{table} (upper(#{range}))"
         end
       end
 
@@ -53,9 +51,9 @@ module ChronoModel
         id   = options[:id] || primary_key(table)
 
         chrono_alter_constraint(table, options) do
-          execute <<-SQL.squish
+          execute <<~SQL.squish
             ALTER TABLE #{table} ADD CONSTRAINT #{name}
-              EXCLUDE USING gist ( #{id} WITH =, #{range} WITH && )
+              EXCLUDE USING gist (#{id} WITH =, #{range} WITH &&)
           SQL
         end
       end
@@ -64,7 +62,7 @@ module ChronoModel
         name = timeline_consistency_constraint_name(table)
 
         chrono_alter_constraint(table, options) do
-          execute <<-SQL.squish
+          execute <<~SQL.squish
             ALTER TABLE #{table} DROP CONSTRAINT #{name}
           SQL
         end
@@ -81,9 +79,9 @@ module ChronoModel
       def chrono_create_history_indexes_for(table, p_pkey)
         add_temporal_indexes table, :validity, on_current_schema: true
 
-        execute "CREATE INDEX #{table}_inherit_pkey     ON #{table} ( #{p_pkey} )"
-        execute "CREATE INDEX #{table}_recorded_at      ON #{table} ( recorded_at )"
-        execute "CREATE INDEX #{table}_instance_history ON #{table} ( #{p_pkey}, recorded_at )"
+        execute "CREATE INDEX #{table}_inherit_pkey     ON #{table} (#{p_pkey})"
+        execute "CREATE INDEX #{table}_recorded_at      ON #{table} (recorded_at)"
+        execute "CREATE INDEX #{table}_instance_history ON #{table} (#{p_pkey}, recorded_at)"
       end
 
       # Rename indexes on history schema
@@ -144,10 +142,10 @@ module ChronoModel
             #
             columns = Array.wrap(index.columns).join(', ')
 
-            execute %[
-                CREATE INDEX #{index.name} ON #{table_name}
-                USING #{index.using} ( #{columns} )
-              ], 'Copy index from temporal to history'
+            execute <<~SQL.squish, 'Copy index from temporal to history'
+              CREATE INDEX #{index.name} ON #{table_name}
+              USING #{index.using} (#{columns})
+            SQL
           end
         end
       end

data/lib/chrono_model/adapter/migrations.rb

@@ -84,7 +84,7 @@ module ChronoModel
             end
 
           else
-            if is_chrono?(table_name)
+            if is_chrono?(table_name) && options[:temporal] == false
               chrono_undo_temporal_table(table_name)
             end
 
@@ -214,14 +214,14 @@ module ChronoModel
         seq  = on_history_schema { pk_and_sequence_for(table_name).last.to_s }
         from = options[:validity] || '0001-01-01 00:00:00'
 
-        execute %[
-              INSERT INTO #{HISTORY_SCHEMA}.#{table_name}
-              SELECT *,
-                nextval('#{seq}')        AS hid,
-                tsrange('#{from}', NULL) AS validity,
-                timezone('UTC', now())   AS recorded_at
-              FROM #{TEMPORAL_SCHEMA}.#{table_name}
-          ]
+        execute <<~SQL.squish
+          INSERT INTO #{HISTORY_SCHEMA}.#{table_name}
+          SELECT *,
+            nextval('#{seq}')        AS hid,
+            tsrange('#{from}', NULL) AS validity,
+            timezone('UTC', now())   AS recorded_at
+          FROM #{TEMPORAL_SCHEMA}.#{table_name}
+        SQL
       end
 
       # Removes temporal features from this table
@@ -252,8 +252,6 @@ module ChronoModel
         execute "ALTER SEQUENCE #{seq}  RENAME TO #{new_seq}"
         execute "ALTER TABLE    #{name} RENAME TO #{new_name}"
       end
-
-      # private
     end
   end
 end

data/lib/chrono_model/adapter/migrations_modules/stable.rb

@@ -17,7 +17,7 @@ module ChronoModel
             # Uniqueness constraints do not make sense in the history table
             options = options.dup.tap { |o| o.delete(:unique) } if options[:unique].present?
 
-            on_history_schema { super(table_name, column_name, **options) }
+            on_history_schema { super }
           end
         end
 

data/lib/chrono_model/adapter/upgrade.rb

@@ -81,12 +81,12 @@ module ChronoModel
         p_pkey = primary_key(table_name)
 
         execute "ALTER TABLE #{history_table} ADD COLUMN validity tsrange;"
-        execute <<-SQL.squish
-            UPDATE #{history_table} SET validity = tsrange(valid_from,
-                CASE WHEN extract(year from valid_to) = 9999 THEN NULL
-                     ELSE valid_to
-                END
-            );
+        execute <<~SQL.squish
+          UPDATE #{history_table} SET validity = tsrange(valid_from,
+              CASE WHEN extract(year from valid_to) = 9999 THEN NULL
+                   ELSE valid_to
+              END
+          );
         SQL
 
         execute "DROP INDEX #{history_table}_temporal_on_valid_from;"
@@ -112,7 +112,6 @@ module ChronoModel
         on_history_schema { add_history_validity_constraint(table_name, p_pkey) }
         on_history_schema { chrono_create_history_indexes_for(table_name, p_pkey) }
       end
-      # private
     end
   end
 end

data/lib/chrono_model/adapter.rb

@@ -2,12 +2,12 @@
 
 require 'active_record/connection_adapters/postgresql_adapter'
 
-require 'chrono_model/adapter/migrations'
-require 'chrono_model/adapter/migrations_modules/stable'
+require_relative 'adapter/migrations'
+require_relative 'adapter/migrations_modules/stable'
 
-require 'chrono_model/adapter/ddl'
-require 'chrono_model/adapter/indexes'
-require 'chrono_model/adapter/upgrade'
+require_relative 'adapter/ddl'
+require_relative 'adapter/indexes'
+require_relative 'adapter/upgrade'
 
 module ChronoModel
   # This class implements all ActiveRecord::ConnectionAdapters::SchemaStatements
@@ -87,15 +87,10 @@ module ChronoModel
     # The default search path is included however, since the table
     # may reference types defined in other schemas, which result in their
     # names becoming schema qualified, which will cause type resolutions to fail.
-    #
-    # NOTE: This method is dynamically defined, see the source.
-    #
-    def column_definitions; end
-
-    define_method(:column_definitions) do |table_name|
-      return super(table_name) unless is_chrono?(table_name)
+    def column_definitions(table_name)
+      return super unless is_chrono?(table_name)
 
-      on_schema("#{TEMPORAL_SCHEMA},#{schema_search_path}", recurse: :ignore) { super(table_name) }
+      on_schema("#{TEMPORAL_SCHEMA},#{schema_search_path}", recurse: :ignore) { super }
     end
 
     # Evaluates the given block in the temporal schema.
@@ -170,7 +165,7 @@ module ChronoModel
     def chrono_metadata_set(view_name, metadata)
       comment = MultiJson.dump(metadata)
 
-      execute %( COMMENT ON VIEW #{view_name} IS #{quote(comment)} )
+      execute "COMMENT ON VIEW #{view_name} IS #{quote(comment)}"
     end
 
     def valid_table_definition_options

data/lib/chrono_model/conversions.rb

@@ -4,8 +4,6 @@ module ChronoModel
   module Conversions
     module_function
 
-    ISO_DATETIME = /\A(\d{4})-(\d\d)-(\d\d) (\d\d):(\d\d):(\d\d)(?:\.(\d+))?\z/
-
     def time_to_utc_string(time)
       time.to_fs(:db) << '.' << format('%06d', time.usec)
     end

data/lib/chrono_model/db_console.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
-require 'chrono_model/patches/db_console'
+require_relative 'patches/db_console'
 
 Rails::DBConsole.prepend ChronoModel::Patches::DBConsole::DbConfig

data/lib/chrono_model/patches/association.rb

@@ -11,10 +11,6 @@ module ChronoModel
     # on the join model's (:through association) one.
     #
     module Association
-      def skip_statement_cache?(*)
-        super || _chrono_target?
-      end
-
       # If the association class or the through association are ChronoModels,
       # then fetches the records from a virtual table using a subquery scope
       # to a specific timestamp.
@@ -36,6 +32,10 @@ module ChronoModel
 
       private
 
+      def skip_statement_cache?(*)
+        super || _chrono_target?
+      end
+
       def _chrono_record?
         owner.class.include?(ChronoModel::Patches::AsOfTimeHolder) && owner.as_of_time.present?
       end

data/lib/chrono_model/patches/batches.rb

@@ -2,10 +2,44 @@
 
 module ChronoModel
   module Patches
+    # Overrides the default batch methods for historical models
+    #
+    # In the default implementation, `cursor` defaults to `primary_key`, which is 'id'.
+    # However, historical models need to use 'hid' instead of 'id'.
+    #
+    # This patch addresses an issue where `with_hid_pkey` is called after the cursor
+    # is already set, potentially leading to incorrect behavior.
+    #
+    # Notes:
+    # - `find_each` and `find_in_batches` internally utilize `in_batches`.
+    #   However, in the upcoming Rails 8.0, this implementation will be
+    #   insufficient due to a new conditional branch using `enum_for`.
+    # - This approach prevents specifying 'id' as a cursor for historical models.
+    #   If 'id' is needed, it must be handled separately.
+    #
+    # See: ifad/chronomodel#321 for more context
     module Batches
-      def in_batches(**)
+      def find_each(**options)
         return super unless try(:history?)
 
+        options[:cursor] = 'hid' if options[:cursor] == 'id'
+
+        with_hid_pkey { super }
+      end
+
+      def find_in_batches(**options)
+        return super unless try(:history?)
+
+        options[:cursor] = 'hid' if options[:cursor] == 'id'
+
+        with_hid_pkey { super }
+      end
+
+      def in_batches(**options)
+        return super unless try(:history?)
+
+        options[:cursor] = 'hid' if options[:cursor] == 'id'
+
         with_hid_pkey { super }
       end
     end

data/lib/chrono_model/patches/join_node.rb

@@ -2,28 +2,17 @@
 
 module ChronoModel
   module Patches
-    # This class supports the AR 5.0 code that expects to receive an
-    # Arel::Table as the left join node. We need to replace the node
-    # with a virtual table that fetches from the history at a given
-    # point in time, we replace the join node with a SqlLiteral node
-    # that does not respond to the methods that AR expects.
-    #
-    # This class provides AR with an object implementing the methods
-    # it expects, yet producing SQL that fetches from history tables
-    # as-of-time.
-    #
+    # Replaces the left side of an Arel join (table or table alias) with a SQL
+    # literal pointing to the history virtual table at the given as_of_time,
+    # preserving any existing table alias.
     class JoinNode < Arel::Nodes::SqlLiteral
-      attr_reader :name, :table_name, :table_alias, :as_of_time
+      attr_reader :as_of_time
 
       def initialize(join_node, history_model, as_of_time)
-        @name        = join_node.table_name
-        @table_name  = join_node.table_name
-        @table_alias = join_node.table_alias
-
         @as_of_time  = as_of_time
 
-        virtual_table = history_model
-                        .virtual_table_at(@as_of_time, table_name: @table_alias || @table_name)
+        table_name = join_node.table_alias || join_node.name
+        virtual_table = history_model.virtual_table_at(@as_of_time, table_name: table_name)
 
         super(virtual_table)
       end

data/lib/chrono_model/patches/preloader.rb

@@ -9,43 +9,14 @@ module ChronoModel
     module Preloader
       attr_reader :chronomodel_options
 
-      # We overwrite the initializer in order to pass the +as_of_time+
-      # parameter above in the build_preloader
+      # Overwrite the initializer to set Chronomodel +as_of_time+ and +model+
+      # options.
       #
       def initialize(**options)
         @chronomodel_options = options.extract!(:as_of_time, :model)
         options[:scope] = chronomodel_scope(options[:scope]) if options.key?(:scope)
 
-        if options.empty?
-          super()
-        else
-          super(**options)
-        end
-      end
-
-      # Patches the AR Preloader (lib/active_record/associations/preloader.rb)
-      # in order to carry around the +as_of_time+ of the original invocation.
-      #
-      # * The +records+ are the parent records where the association is defined
-      # * The +associations+ are the association names involved in preloading
-      # * The +given_preload_scope+ is the preloading scope, that is used only
-      #   in the :through association and it holds the intermediate records
-      #   _through_ which the final associated records are eventually fetched.
-      #
-      # As the +preload_scope+ is passed around to all the different
-      # incarnations of the preloader strategies, we are using it to pass
-      # around the +as_of_time+ of the original query invocation, so that
-      # preloaded records are preloaded honoring the +as_of_time+.
-      #
-      # The +preload_scope+ is present only in through associations, but the
-      # preloader interfaces expect it to be always defined, for consistency.
-      #
-      # For `:through` associations, the +given_preload_scope+ is already a
-      # +Relation+, that already has the +as_of_time+ getters and setters,
-      # so we use it directly.
-      #
-      def preload(records, associations, given_preload_scope = nil)
-        super(records, associations, chronomodel_scope(given_preload_scope))
+        super
       end
 
       private
@@ -62,6 +33,8 @@ module ChronoModel
       end
 
       module Association
+        private
+
         # Builds the preloader scope taking into account a potential
         # +as_of_time+ passed down the call chain starting at the
         # end user invocation.
@@ -78,13 +51,14 @@ module ChronoModel
       end
 
       module ThroughAssociation
+        private
+
         # Builds the preloader scope taking into account a potential
         # +as_of_time+ passed down the call chain starting at the
         # end user invocation.
         #
         def through_scope
           scope = super
-          return unless scope # Rails 5.2 may not return a scope
 
           if preload_scope.try(:as_of_time)
             scope = scope.as_of(preload_scope.as_of_time)

data/lib/chrono_model/patches/relation.rb

@@ -23,10 +23,17 @@ module ChronoModel
         @values == klass.unscoped.as_of(as_of_time).values
       end
 
-      def load
-        return super unless @_as_of_time && !loaded?
+      def load(&block)
+        return super unless @_as_of_time && (!loaded? || scheduled?)
 
-        super.each { |record| record.as_of_time!(@_as_of_time) }
+        records = super
+
+        records.each do |record|
+          record.as_of_time!(@_as_of_time)
+          propagate_as_of_time_to_includes(record)
+        end
+
+        self
       end
 
       def merge(*)
@@ -35,6 +42,20 @@ module ChronoModel
         super.as_of_time!(@_as_of_time)
       end
 
+      def find_nth(*)
+        return super unless try(:history?)
+
+        with_hid_pkey { super }
+      end
+
+      def last(*)
+        return super unless try(:history?)
+
+        with_hid_pkey { super }
+      end
+
+      private
+
       def build_arel(*)
         return super unless @_as_of_time
 
@@ -47,54 +68,71 @@ module ChronoModel
 
       # Replaces a join with the current data with another that
       # loads records As-Of time against the history data.
-      #
       def chrono_join_history(join)
+        join_left = join.left
+
         # This case happens with nested includes, where the below
         # code has already replaced the join.left with a JoinNode.
-        #
-        return if join.left.respond_to?(:as_of_time)
-
-        model =
-          if join.left.respond_to?(:table_name)
-            ChronoModel.history_models[join.left.table_name]
-          else
-            ChronoModel.history_models[join.left]
-          end
+        return if join_left.is_a?(ChronoModel::Patches::JoinNode)
 
+        model = ChronoModel.history_models[join_left.name] if join_left.respond_to?(:name)
         return unless model
 
         join.left = ChronoModel::Patches::JoinNode.new(
-          join.left, model.history, @_as_of_time
+          join_left, model.history, @_as_of_time
         )
       end
 
-      # Build a preloader at the +as_of_time+ of this relation.
-      # Pass the current model to define Relation
-      #
-      def build_preloader
-        ActiveRecord::Associations::Preloader.new(
-          model: model, as_of_time: as_of_time
-        )
-      end
-
-      def find_nth(*)
+      def ordered_relation
         return super unless try(:history?)
 
         with_hid_pkey { super }
       end
 
-      def last(*)
-        return super unless try(:history?)
+      # Propagate as_of_time to associations that were eager loaded via includes/eager_load
+      def propagate_as_of_time_to_includes(record)
+        return unless eager_loading?
 
-        with_hid_pkey { super }
+        assign_as_of_time_to_spec(record, includes_values)
       end
 
-      private
+      def assign_as_of_time_to_spec(record, spec)
+        case spec
+        when Symbol, String
+          assign_as_of_time_to_association(record, spec.to_sym, nil)
+        when Array
+          spec.each { |s| assign_as_of_time_to_spec(record, s) }
+        when Hash
+          # This branch is difficult to trigger in practice due to Rails query optimization.
+          # Modern Rails versions tend to optimize eager loading in ways that make this specific
+          # code path challenging to reproduce in tests without artificial scenarios.
+          spec.each do |name, nested|
+            assign_as_of_time_to_association(record, name.to_sym, nested)
+          end
+        end
+      end
 
-      def ordered_relation
-        return super unless try(:history?)
+      def assign_as_of_time_to_association(record, name, nested)
+        reflection = record.class.reflect_on_association(name)
+        return unless reflection
 
-        with_hid_pkey { super }
+        assoc = record.association(name)
+        return unless assoc.loaded?
+
+        target = assoc.target
+
+        if target.is_a?(Array)
+          target.each { |t| t.respond_to?(:as_of_time!) && t.as_of_time!(@_as_of_time) }
+          # This nested condition is difficult to trigger in practice as it requires specific
+          # association loading scenarios with Array targets and nested specs that Rails
+          # query optimization tends to handle differently in modern versions.
+          if nested.present?
+            target.each { |t| assign_as_of_time_to_spec(t, nested) }
+          end
+        else
+          target.respond_to?(:as_of_time!) && target.as_of_time!(@_as_of_time)
+          assign_as_of_time_to_spec(target, nested) if nested.present? && target
+        end
       end
     end
   end

data/lib/chrono_model/patches.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require 'chrono_model/patches/as_of_time_holder'
-require 'chrono_model/patches/as_of_time_relation'
+require_relative 'patches/as_of_time_holder'
+require_relative 'patches/as_of_time_relation'
 
-require 'chrono_model/patches/join_node'
-require 'chrono_model/patches/relation'
-require 'chrono_model/patches/preloader'
-require 'chrono_model/patches/association'
-require 'chrono_model/patches/batches'
+require_relative 'patches/join_node'
+require_relative 'patches/relation'
+require_relative 'patches/preloader'
+require_relative 'patches/association'
+require_relative 'patches/batches'

data/lib/chrono_model/railtie.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'active_record/tasks/chronomodel_database_tasks'
+require_relative '../active_record/tasks/chronomodel_database_tasks'
 
 module ChronoModel
   class Railtie < ::Rails::Railtie

data/lib/chrono_model/time_machine/history_model.rb

@@ -11,7 +11,6 @@ module ChronoModel
         scope :chronological, -> { order(Arel.sql('lower(validity) ASC')) }
       end
 
-      # ACTIVE RECORD 7 does not call `class.find` but a new internal method called `_find_record`
       def _find_record(options)
         if options && options[:lock]
           self.class.preload(strict_loaded_associations).lock(options[:lock]).find_by!(hid: hid)
@@ -33,7 +32,7 @@ module ChronoModel
         #
         def with_hid_pkey
           old = primary_key
-          self.primary_key = :hid
+          self.primary_key = 'hid'
 
           yield
         ensure
@@ -83,14 +82,18 @@ module ChronoModel
 
         # Fetches history record at the given time
         #
+        # Build on an unscoped relation to avoid leaking outer predicates
+        # (e.g., through association scopes) into the inner subquery.
+        #
+        # @see https://github.com/ifad/chronomodel/issues/295
         def at(time)
-          time_query(:at, time).from(quoted_table_name).as_of_time!(time)
+          unscoped.time_query(:at, time).from(quoted_table_name).as_of_time!(time)
         end
 
         # Returns the history sorted by recorded_at
         #
         def sorted
-          all.order(Arel.sql(%( #{quoted_table_name}."recorded_at" ASC, #{quoted_table_name}."hid" ASC )))
+          all.order(Arel.sql(%(#{quoted_table_name}."recorded_at" ASC, #{quoted_table_name}."hid" ASC)))
         end
 
         # Fetches the given +object+ history, sorted by history record time
@@ -220,10 +223,33 @@ module ChronoModel
       def valid_to
         validity.end if validity.end.is_a?(Time)
       end
-      alias as_of_time valid_to
 
-      # Starting from Rails 6.0, `.read_attribute` will use the memoized
-      # `primary_key` if it detects that the attribute name is `id`.
+      # Computes an `as_of_time` strictly inside this record's validity period
+      # for historical queries.
+      #
+      # Ensures association queries return versions that existed during this
+      # record's validity, not ones that became valid exactly at the boundary
+      # time. When objects are updated in the same transaction, they can share
+      # the same `valid_to`, which would otherwise cause boundary
+      # mis-selection.
+      #
+      # PostgreSQL ranges are half-open `[start, end)` by default.
+      #
+      # @return [Time, nil] `valid_to - ChronoModel::VALIDITY_TSRANGE_PRECISION`
+      #   when `valid_to` is a Time; otherwise returns `valid_to` unchanged
+      #   (which may be `nil` for open-ended validity).
+      #
+      # @see https://github.com/ifad/chronomodel/issues/283
+      def as_of_time
+        if valid_to.is_a?(Time)
+          valid_to - ChronoModel::VALIDITY_TSRANGE_PRECISION
+        else
+          valid_to
+        end
+      end
+
+      # `.read_attribute` uses the memoized `primary_key` if it detects
+      # that the attribute name is `id`.
       #
       # Since the `primary key` may have been changed to `hid` because of
       # `.find` overload, the new behavior may break relations where `id` is
@@ -240,7 +266,7 @@ module ChronoModel
 
       def with_hid_pkey(&block)
         old_primary_key = @primary_key
-        @primary_key = :hid
+        @primary_key = 'hid'
 
         self.class.with_hid_pkey(&block)
       ensure

data/lib/chrono_model/time_machine/time_query.rb

@@ -93,9 +93,9 @@ module ChronoModel
 
       def build_time_query(time, range, op = '&&')
         if time.is_a?(Array)
-          Arel.sql %[ #{range.type}(#{time.first}, #{time.last}) #{op} #{table_name}.#{range.name} ]
+          Arel.sql %[#{range.type}(#{time.first}, #{time.last}) #{op} #{table_name}.#{range.name} ]
         else
-          Arel.sql %( #{time} <@ #{table_name}.#{range.name} )
+          Arel.sql %(#{time} <@ #{table_name}.#{range.name})
         end
       end
     end

data/lib/chrono_model/time_machine/timeline.rb

@@ -59,7 +59,7 @@ module ChronoModel
         relation = relation.from("public.#{quoted_table_name}") unless chrono?
         relation = relation.where(id: rid) if rid
 
-        sql = +"SELECT ts FROM ( #{relation.to_sql} ) AS foo WHERE ts IS NOT NULL"
+        sql = "SELECT ts FROM (#{relation.to_sql}) AS foo WHERE ts IS NOT NULL"
 
         if options.key?(:before)
           sql << " AND ts < '#{Conversions.time_to_utc_string(options[:before])}'"
@@ -72,9 +72,9 @@ module ChronoModel
         if rid && !options[:with]
           sql <<
             if chrono?
-              %{ AND ts <@ ( SELECT tsrange(min(lower(validity)), max(upper(validity)), '[]') FROM #{quoted_table_name} WHERE id = #{rid} ) }
+              %{ AND ts <@ (SELECT tsrange(min(lower(validity)), max(upper(validity)), '[]') FROM #{quoted_table_name} WHERE id = #{rid})}
             else
-              %[ AND ts < NOW() ]
+              ' AND ts < NOW()'
             end
         end
 

data/lib/chrono_model/time_machine.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require 'chrono_model/time_machine/time_query'
-require 'chrono_model/time_machine/timeline'
-require 'chrono_model/time_machine/history_model'
+require_relative 'time_machine/time_query'
+require_relative 'time_machine/timeline'
+require_relative 'time_machine/history_model'
 
 module ChronoModel
   module TimeMachine
@@ -12,7 +12,7 @@ module ChronoModel
 
     included do
       if table_exists? && !chrono?
-        logger.warn <<-MSG.squish
+        logger.warn <<~MSG.squish
           ChronoModel: #{table_name} is not a temporal table.
           Please use `change_table :#{table_name}, temporal: true` in a migration.
         MSG
@@ -176,7 +176,7 @@ module ChronoModel
       else
         return nil unless (ts = pred_timestamp(options))
 
-        order_clause = Arel.sql %[ LOWER(#{options[:table] || self.class.quoted_table_name}."validity") DESC ]
+        order_clause = Arel.sql %[LOWER(#{options[:table] || self.class.quoted_table_name}."validity") DESC]
 
         self.class.as_of(ts).order(order_clause).find(options[:id] || id)
       end

data/lib/chrono_model/utilities.rb

@@ -16,12 +16,12 @@ module ChronoModel
         raise 'Can amend history only with UTC timestamps'
       end
 
-      connection.execute %[
+      connection.execute <<~SQL.squish
         UPDATE #{quoted_table_name}
-           SET "validity" = tsrange(#{connection.quote(from)}, #{connection.quote(to)}),
+           SET "validity"    = tsrange(#{connection.quote(from)}, #{connection.quote(to)}),
                "recorded_at" = #{connection.quote(from)}
          WHERE "hid" = #{hid.to_i}
-      ]
+      SQL
     end
   end
 end

data/lib/chrono_model/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ChronoModel
-  VERSION = '4.0.0'
+  VERSION = '5.0.0'
 end

data/lib/chrono_model.rb

@@ -2,21 +2,26 @@
 
 require 'active_record'
 
-require 'chrono_model/chrono'
-require 'chrono_model/conversions'
-require 'chrono_model/patches'
-require 'chrono_model/adapter'
-require 'chrono_model/time_machine'
-require 'chrono_model/time_gate'
-require 'chrono_model/version'
+require_relative 'chrono_model/chrono'
+require_relative 'chrono_model/conversions'
+require_relative 'chrono_model/patches'
+require_relative 'chrono_model/adapter'
+require_relative 'chrono_model/time_machine'
+require_relative 'chrono_model/time_gate'
+require_relative 'chrono_model/version'
 
-require 'chrono_model/railtie' if defined?(Rails::Railtie)
-require 'chrono_model/db_console' if defined?(Rails::DBConsole) && Rails.version < '7.1'
+require_relative 'chrono_model/railtie' if defined?(Rails::Railtie)
+require_relative 'chrono_model/db_console' if defined?(Rails::DBConsole) && Rails.version < '7.1'
 
 module ChronoModel
   class Error < ActiveRecord::ActiveRecordError # :nodoc:
   end
 
+  # ChronoModel uses default timestamp precision (p=6) for tsrange columns.
+  # PostgreSQL timestamp precision can range from 0 to 6 fractional digits,
+  # where 6 provides microsecond resolution (1 microsecond = 10^-6 seconds).
+  VALIDITY_TSRANGE_PRECISION = Rational(1, 10**6)
+
   # Performs structure upgrade.
   #
   def self.upgrade!

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chrono_model
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 5.0.0
 platform: ruby
 authors:
 - Marcello Barnaba
 - Peter Joseph Brindisi
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-12 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -101,7 +100,6 @@ metadata:
   homepage_uri: https://github.com/ifad/chronomodel
   source_code_uri: https://github.com/ifad/chronomodel
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -116,8 +114,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Temporal extensions (SCD Type II) for Active Record
 test_files: []