chrono_model 1.2.2 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa9d6f8ee80241092713836e372cf3cb568639e403511ba2c48ba33275f6c1a8
-  data.tar.gz: '055794bce8014501e3eea0a180abe04278f1aba62015d3f5b98d75499c6faba1'
+  metadata.gz: 222db0e6673e7171d44dac2163b5048ebf6b459c18fa2a2609a3051fce8c6591
+  data.tar.gz: 871fdf28717c85267e6b783f1f2d6ba3a24b1261e974e53a25de28d745bc8579
 SHA512:
-  metadata.gz: 380cbab091ab178aea031fee4e8343797a5e461e98b233a8c732b7cc0f9bd584497fa3b1bcc8703f6d8b74b972aeed2a257f6aba9ca7a2d932b4e72e7c211506
-  data.tar.gz: c601c91ce05f426aef3c75b37ba9920170666523abff9b219ab09816e6c17f42146131d5ffcc89d233d5d7ec94d6ac5592e6a8160dd8207b9a48c3ff51feb629
+  metadata.gz: 0bf942259052f134ea38de898307a65f20a6b448d8e8ff99a09ae06cd751f9834e1eb22abd4498c880005b8fc91f44ecebea4702be8c174570c50027dce13a75
+  data.tar.gz: 2b894f82a0cb9687d59dca9c3427a854cf6dc02191a08df71a215dfc577a8d1dd58632d44eb179395f097aa7d2391a7c738968d0f4c68f16cc14fffd2d18e034

data/LICENSE

@@ -1,24 +1,23 @@
-Copyright (c) 2012-2014 Marcello Barnaba <m.barnaba@ifad.org>
-Copyright (c) 2012-2014 Peter J. Brindisi <p.brindisi@ifad.org>
-Copyright (c) 2012-2014 IFAD
-
 MIT License
 
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
+Copyright (c) 2012-2024 Marcello Barnaba <m.barnaba@ifad.org>
+Copyright (c) 2012-2024 Peter J. Brindisi <p.brindisi@ifad.org>
+Copyright (c) 2012-2024 IFAD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -6,7 +6,7 @@
 [![Gem Version][gem-version-badge]][gem-version]
 [![Inlinedocs][docs-analysis-badge]][docs-analysis]
 
-![{A Delorean that we all love}][delorean-image]
+![A Delorean that we all love][delorean-image]
 
 ChronoModel implements what Oracle sells as "Flashback Queries", with standard
 SQL on free PostgreSQL. Academically speaking, ChronoModel implements a
@@ -62,9 +62,9 @@ All timestamps are _forcibly_ stored in as UTC, bypassing the
 
 ## Requirements
 
-* Ruby >= 2.3
-* Active Record >= 5.0. See the [detailed supported versions matrix on travis](https://travis-ci.org/ifad/chronomodel)
-* PostgreSQL >= 9.4 (legacy support for 9.3)
+* Ruby >= 3.0
+* Active Record >= 7.0. See the [detailed supported versions matrix on Ruby GitHub Actions workflows](https://github.com/ifad/chronomodel/blob/master/.github/workflows)
+* PostgreSQL >= 9.4
 * The `btree_gist` PostgreSQL extension
 
 With Homebrew:
@@ -96,6 +96,13 @@ development:
   username: ...
 ```
 
+Configure Active Record in your `config/application.rb` to use the `:sql` schema
+format:
+
+```rb
+config.active_record.schema_format = :sql
+```
+
 ## Schema creation
 
 ChronoModel hooks all `ActiveRecord::Migration` methods to make them temporal
@@ -141,7 +148,7 @@ validity from midnight, January 1st, 1 CE. You can set a specific validity with
 the `:validity` option:
 
 ```ruby
-change_table :your_table, :temporal => true, :copy_data => true, :validity => '1977-01-01'
+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
@@ -156,9 +163,9 @@ history.
 You can also choose which fields are to be journaled, passing the following
 options to `create_table`:
 
-  * `:journal => %w( fld1 fld2 .. .. )` - record changes in the history only when changing specified fields
-  * `:no_journal => %w( fld1 fld2 .. )` - do not record changes to the specified fields
-  * `:full_journal => true`             - record changes to *all* fields, including `updated_at`.
+  * `journal: %w( fld1 fld2 .. .. )` - record changes in the history only when changing specified fields
+  * `no_journal: %w( fld1 fld2 .. )` - do not record changes to the specified fields
+  * `full_journal: true`             - record changes to *all* fields, including `updated_at`.
 
 These options are stored as JSON in the [COMMENT][pg-comment] area of the
 public view, alongside with the ChronoModel version that created them.
@@ -195,7 +202,7 @@ to your `create_table`. Example:
 Include the `ChronoModel::TimeMachine` module in your model.
 
 ```ruby
-module Country < ActiveRecord::Base
+class Country < ActiveRecord::Base
   include ChronoModel::TimeMachine
 
   has_many :compositions
@@ -310,31 +317,19 @@ only against ActiveRecord by using
 
 Ensure to run the full test suite before pushing.
 
-## Usage with JSON (*not* JSONB) columns
-
-**DEPRECATED**: Please migrate to JSONB. It has an equality operator built-in,
-it's faster and stricter, and offers many more indexing abilities and better
-performance than JSON. It is going to be desupported soon because PostgreSQL 10
-does not support these anymore.
-
-The [JSON][pg-json-type] does not provide an [equality operator][pg-json-func].
-As both unnecessary update suppression and selective journaling require
-comparing the OLD and NEW rows fields, this fails by default.
-
-ChronoModel provides a naive and heavyweight JSON equality operator using
-[pl/python][pg-json-opclass] and associated Postgres objects.
-
-To set up you can use
-
-```ruby
-require 'chrono_model/json'
-ChronoModel::Json.create
-```
-
 ## Caveats
 
+ * Considering the nature of modern applications, it's crucial to understand
+   that the database time does not necessarily align with the application time
+   due to the delay introduced by communication between the application and
+   the database server. Consequently, there is no assurance that the application
+   time will always be less than the database time. Therefore, relying solely
+   on `created_at` and `updated_at` fields as timestamps to determine the state
+   of an object at a specific point in time within the application could
+   lead to inaccuracies.
+
  * Rails 4+ support requires disabling tsrange parsing support, as it
-   [is broken][r4-tsrange-broken] and  [incomplete][r4-tsrange-incomplete]
+   [is broken][r4-tsrange-broken] and [incomplete][r4-tsrange-incomplete]
    as of now, mainly due to a [design clash with ruby][pg-tsrange-and-ruby].
 
  * The triggers and temporal indexes cannot be saved in schema.rb. The AR
@@ -345,14 +340,27 @@ ChronoModel::Json.create
    `db:structure:load`.
    Two helper tasks are also added, `db:data:dump` and `db:data:load`.
 
- * The choice of using subqueries instead of [Common Table Expressions]
-   [pg-ctes] was dictated by the fact that CTEs [currently act as an
-   optimization fence][pg-cte-optimization-fence].
+ * The choice of using subqueries instead of [Common Table Expressions][pg-ctes]
+   was dictated by the fact that CTEs [currently act as an optimization
+   fence][pg-cte-optimization-fence].
    If it will be possible [to opt-out of the fence][pg-cte-opt-out-fence]
    in the future, they will be probably be used again as they were [in the
    past][cm-cte-impl], because the resulting queries were more readable,
    and do not inhibit using `.from()` on the `AR::Relation`.
 
+ * 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
+   #206][gh-issue-206]
+
+ * Use with caution when implementing inline editing features, as Chronomodel
+   creates a new record for each modification. This will lead to increased
+   storage requirements and bloated history
 
 ## Contributing
 
@@ -376,41 +384,40 @@ while using it in many important projects.
 This software is Made in Italy :it: :smile:.
 
 
-[build-status]: https://travis-ci.org/ifad/chronomodel
-[build-status-badge]: https://travis-ci.org/ifad/chronomodel.svg
-[code-analysis]: https://codeclimate.com/github/ifad/chronomodel
-[code-analysis-badge]: https://codeclimate.com/github/ifad/chronomodel.svg
-[docs-analysis]: http://inch-ci.org/github/ifad/chronomodel
-[docs-analysis-badge]: http://inch-ci.org/github/ifad/chronomodel.svg?branch=master
+[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
-[rebelle-society]: http://www.rebellesociety.com/2012/10/11/the-writers-way-week-two-facing-procrastination/chronos_oeuvre_grand1/
-
-[wp-scd-2]: http://en.wikipedia.org/wiki/Slowly_changing_dimension#Type_2
-[wp-scd-4]: http://en.wikipedia.org/wiki/Slowly_changing_dimension#Type_4
-
-[pg-updatable-views]: http://www.postgresql.org/docs/9.4/static/sql-createview.html#SQL-CREATEVIEW-UPDATABLE-VIEWS
-[pg-table-inheritance]: http://www.postgresql.org/docs/9.4/static/ddl-inherit.html
-[pg-instead-of-triggers]: http://www.postgresql.org/docs/9.4/static/sql-createtrigger.html
-[pg-triggers]: http://www.postgresql.org/docs/9.4/static/trigger-definition.html
-[pg-schema]: http://www.postgresql.org/docs/9.4/static/ddl-schemas.html
-[pg-current-timestamp]: http://www.postgresql.org/docs/9.4/interactive/functions-datetime.html#FUNCTIONS-DATETIME-TABLE
-[pg-partitioning]: http://www.postgresql.org/docs/9.4/static/ddl-partitioning.html
-[pg-partitioning-excl-constraints]: http://www.postgresql.org/docs/9.4/static/ddl-partitioning.html#DDL-PARTITIONING-CONSTRAINT-EXCLUSION
-[pg-gist-indexes]: http://www.postgresql.org/docs/9.4/static/gist.html
-[pg-exclusion-constraints]: http://www.postgresql.org/docs/9.4/static/sql-createtable.html#SQL-CREATETABLE-EXCLUDE
-[pg-btree-gist]: http://www.postgresql.org/docs/9.4/static/btree-gist.html
-[pg-comment]: http://www.postgresql.org/docs/9.4/static/sql-comment.html
+
+[wp-scd-2]: https://en.wikipedia.org/wiki/Slowly_changing_dimension#Type_2
+[wp-scd-4]: https://en.wikipedia.org/wiki/Slowly_changing_dimension#Type_4
+
+[pg-updatable-views]: https://www.postgresql.org/docs/9.4/sql-createview.html#SQL-CREATEVIEW-UPDATABLE-VIEWS
+[pg-table-inheritance]: https://www.postgresql.org/docs/9.4/ddl-inherit.html
+[pg-instead-of-triggers]: https://www.postgresql.org/docs/9.4/sql-createtrigger.html
+[pg-triggers]: https://www.postgresql.org/docs/9.4/trigger-definition.html
+[pg-schema]: https://www.postgresql.org/docs/9.4/ddl-schemas.html
+[pg-current-timestamp]: https://www.postgresql.org/docs/9.4/functions-datetime.html#FUNCTIONS-DATETIME-TABLE
+[pg-partitioning]: https://www.postgresql.org/docs/9.4/ddl-partitioning.html
+[pg-partitioning-excl-constraints]: https://www.postgresql.org/docs/9.4/ddl-partitioning.html#DDL-PARTITIONING-CONSTRAINT-EXCLUSION
+[pg-gist-indexes]: https://www.postgresql.org/docs/9.4/gist.html
+[pg-exclusion-constraints]: https://www.postgresql.org/docs/9.4/sql-createtable.html#SQL-CREATETABLE-EXCLUDE
+[pg-btree-gist]: https://www.postgresql.org/docs/9.4/btree-gist.html
+[pg-comment]: https://www.postgresql.org/docs/9.4/sql-comment.html
 [pg-tsrange-and-ruby]: https://bugs.ruby-lang.org/issues/6864
-[pg-ctes]: http://www.postgresql.org/docs/9.4/static/queries-with.html
-[pg-cte-optimization-fence]: http://archives.postgresql.org/pgsql-hackers/2012-09/msg00700.php
-[pg-cte-opt-out-fence]: http://archives.postgresql.org/pgsql-hackers/2012-10/msg00024.php
-[pg-json-type]: http://www.postgresql.org/docs/9.4/static/datatype-json.html
-[pg-json-func]: http://www.postgresql.org/docs/9.4/static/functions-json.html
+[pg-ctes]: https://www.postgresql.org/docs/9.4/queries-with.html
+[pg-cte-optimization-fence]: https://www.postgresql.org/message-id/201209191305.44674.db@kavod.com
+[pg-cte-opt-out-fence]: https://www.postgresql.org/message-id/CAHyXU0zpM5+Dsb_pKxDmm-ZoWUAt=SkHHaiK_DBqcmtxTas6Nw@mail.gmail.com
+[pg-json-type]: https://www.postgresql.org/docs/9.4/datatype-json.html
+[pg-json-func]: https://www.postgresql.org/docs/9.4/functions-json.html
 [pg-json-opclass]: https://github.com/ifad/chronomodel/blob/master/sql/json_ops.sql
 
 [r4-tsrange-broken]: https://github.com/rails/rails/pull/13793#issuecomment-34608093
@@ -421,3 +428,7 @@ This software is Made in Italy :it: :smile:.
 [cm-cte-impl]: https://github.com/ifad/chronomodel/commit/18f4c4b
 
 [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

data/lib/active_record/connection_adapters/chronomodel_adapter.rb

@@ -1,16 +1,22 @@
+# frozen_string_literal: true
+
 require 'chrono_model'
 
 module ActiveRecord
+  # TODO: Remove when dropping Rails < 7.2 compatibility
   module ConnectionHandling
+    def chronomodel_adapter_class
+      ChronoModel::Adapter
+    end
 
     # Install the new adapter in ActiveRecord. This approach is required because
     # the PG adapter defines +add_column+ itself, thus making impossible to use
     # super() in overridden Module methods.
     #
     def chronomodel_connection(config) # :nodoc:
-      conn_params = config.symbolize_keys
+      return chronomodel_adapter_class.new(config) if ActiveRecord::VERSION::STRING >= '7.1'
 
-      conn_params.delete_if { |_, v| v.nil? }
+      conn_params = config.symbolize_keys.compact
 
       # Map ActiveRecords param names to PGs.
       conn_params[:user] = conn_params.delete(:username) if conn_params[:username]
@@ -20,24 +26,18 @@ module ActiveRecord
       valid_conn_param_keys = PG::Connection.conndefaults_hash.keys + [:requiressl]
       conn_params.slice!(*valid_conn_param_keys)
 
-      # The postgres drivers don't allow the creation of an unconnected PG::Connection object,
-      # so just pass a nil connection object for the time being.
-      adapter = ChronoModel::Adapter.new(nil, logger, conn_params, config)
+      conn = PG.connect(conn_params)
+
+      adapter = ChronoModel::Adapter.new(conn, logger, conn_params, config)
 
       unless adapter.chrono_supported?
-        raise ChronoModel::Error, "Your database server is not supported by ChronoModel. "\
-          "Currently, only PostgreSQL >= 9.3 is supported."
+        raise ChronoModel::Error, 'Your database server is not supported by ChronoModel. ' \
+                                  'Currently, only PostgreSQL >= 9.3 is supported.'
       end
 
       adapter.chrono_setup!
 
-      return adapter
+      adapter
     end
-
-    module Connectionadapters
-      ChronoModelAdapter = ::ChronoModel::Adapter
-    end
-
   end
 end
-

data/lib/active_record/tasks/chronomodel_database_tasks.rb

@@ -1,11 +1,18 @@
+# frozen_string_literal: true
+
 module ActiveRecord
   module Tasks
     class ChronomodelDatabaseTasks < PostgreSQLDatabaseTasks
+      CHRONOMODEL_SCHEMAS = [
+        ChronoModel::Adapter::TEMPORAL_SCHEMA,
+        ChronoModel::Adapter::HISTORY_SCHEMA
+      ].freeze
 
       def structure_dump(*arguments)
-
-        with_chronomodel_schema_search_path do
-          super(*arguments)
+        if schema_search_path.present?
+          with_chronomodel_schema_search_path { super }
+        else
+          super
         end
 
         # The structure.sql includes CREATE SCHEMA statements, but as these are executed
@@ -17,70 +24,64 @@ module ActiveRecord
         filename = arguments.first
         sql = File.read(filename).gsub(/CREATE SCHEMA (?!IF NOT EXISTS)/, '\&IF NOT EXISTS ')
         File.open(filename, 'w') { |file| file << sql }
-
-        remove_sql_header_comments(filename)
       end
 
       def data_dump(target)
-        set_psql_env
+        psql_env
 
-        args = ['-c', '-f', target]
-        args << configuration['database']
+        args = ['-c', '-f', target.to_s]
+        args << chronomodel_configuration[:database]
 
-        run_cmd "pg_dump", args, 'dumping data'
+        run_cmd 'pg_dump', args, 'dumping data'
       end
 
       def data_load(source)
-        set_psql_env
+        psql_env
 
         args = ['-f', source]
-        args << configuration['database']
+        args << chronomodel_configuration[:database]
 
-        run_cmd "psql", args, 'loading data'
+        run_cmd 'psql', args, 'loading data'
       end
 
       private
 
+      def chronomodel_configuration
+        @chronomodel_configuration ||= @configuration_hash
+      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
       # the search path and yield.
       #
       def with_chronomodel_schema_search_path
-        original_schema_search_path = configuration['schema_search_path']
-
-        if original_schema_search_path.present?
-          configuration['schema_search_path'] = original_schema_search_path.split(',').concat([
-            ChronoModel::Adapter::TEMPORAL_SCHEMA,
-            ChronoModel::Adapter::HISTORY_SCHEMA
-          ]).join(',')
-        end
+        patch_configuration!
 
         yield
-
       ensure
-        configuration['schema_search_path'] = original_schema_search_path
+        reset_configuration!
       end
 
-      unless method_defined? :remove_sql_header_comments
-        def remove_sql_header_comments(filename)
-          sql_comment_begin = '--'
-          removing_comments = true
-          tempfile = Tempfile.open("uncommented_structure.sql")
-          begin
-            File.foreach(filename) do |line|
-              unless removing_comments && (line.start_with?(sql_comment_begin) || line.blank?)
-                tempfile << line
-                removing_comments = false
-              end
-            end
-          ensure
-            tempfile.close
-          end
-          FileUtils.mv(tempfile.path, filename)
-        end
+      def patch_configuration!
+        @original_schema_search_path = schema_search_path
+
+        chronomodel_schema_search_path = "#{schema_search_path},#{CHRONOMODEL_SCHEMAS.join(',')}"
+
+        @configuration_hash = @configuration_hash.dup
+        @configuration_hash[:schema_search_path] = chronomodel_schema_search_path
+        @configuration_hash.freeze
       end
 
+      def reset_configuration!
+        @configuration_hash = @configuration_hash.dup
+        @configuration_hash[:schema_search_path] = @original_schema_search_path
+        @configuration_hash.freeze
+      end
+
+      def schema_search_path
+        @schema_search_path ||= chronomodel_configuration[:schema_search_path]
+      end
     end
   end
 end