activerecord-temporal 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 885b7f7b89f8bf5631d9ff433e3848104b2dd4adf00b5fb5ae192ca77fc2791c
+  data.tar.gz: 36d7fc15adf37f0209b564a78d601ad4b2615e16227caf2a66ae21a71e4109a4
+SHA512:
+  metadata.gz: 8ee064c4813043534429ec6601b44966db678ddc616063c504f5b0b1e468edc29cb6485cb951c838f7a4d409ac620f132ed5f660bf69d310c8fa33d4d00cad11
+  data.tar.gz: 1458150e9e6297b29c10b8881b9721fe566c3cb67ccbe2c977a0db2acbf520bbff391e463c7868af5b021c1962a0da09084318f734875095c2c7309edcca4c42

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-11-11
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Martin-Alexander
+
+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 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

@@ -0,0 +1,12 @@
+# Active Record Temporal
+
+## Features
+
+- Flashback (or as-of) queries
+- Application versioning
+- System versioning
+
+## Contributing
+
+- Run `rake db:create` to create the PostgreSQL test database
+- Run `rake` to run tests and linter

data/lib/activerecord/temporal/application_versioning.rb

@@ -0,0 +1,77 @@
+module ActiveRecord::Temporal
+  module ApplicationVersioning
+    extend ActiveSupport::Concern
+
+    included do
+      include AsOfQuery
+    end
+
+    class Revision
+      attr_reader :record, :time, :options
+
+      def initialize(record, time, **options)
+        @record = record
+        @time = time
+        @options = options
+      end
+
+      def with(attributes)
+        new_revision = record.dup
+        new_revision.assign_attributes(attributes)
+        new_revision.set_time_dimension_start(time)
+        new_revision.time_scopes = record.time_scopes
+        record.set_time_dimension_end(time)
+
+        new_revision.after_initialize_revision(record)
+
+        if options[:save]
+          record.class.transaction do
+            new_revision.save if record.save
+          end
+        end
+
+        [new_revision, record]
+      end
+    end
+
+    def after_initialize_revision(old_revision)
+      self.version = old_revision.version + 1
+      self.id_value = old_revision.id_value
+    end
+
+    def head_revision?
+      time_dimension && !time_dimension_end
+    end
+
+    def revise
+      revise_at(Time.current)
+    end
+
+    def revise_at(time)
+      raise "not head revision" unless head_revision?
+
+      Revision.new(self, time, save: true)
+    end
+
+    def revision
+      revision_at(Time.current)
+    end
+
+    def revision_at(time)
+      raise "not head revision" unless head_revision?
+
+      Revision.new(self, time, save: false)
+    end
+
+    def inactivate
+      inactivate_at(Time.current)
+    end
+
+    def inactivate_at(time)
+      raise "not head revision" unless head_revision?
+
+      set_time_dimension_end(time)
+      save
+    end
+  end
+end

data/lib/activerecord/temporal/as_of_query/association_macros.rb

@@ -0,0 +1,41 @@
+module ActiveRecord::Temporal
+  module AsOfQuery
+    module AssociationMacros
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def has_many(name, scope = nil, **options, &extension)
+          scope = handle_temporal_scope_option(scope, options)
+
+          super
+        end
+
+        def has_one(name, scope = nil, **options)
+          scope = handle_temporal_scope_option(scope, options)
+
+          super
+        end
+
+        def belongs_to(name, scope = nil, **options)
+          scope = handle_temporal_scope_option(scope, options)
+
+          super
+        end
+
+        def has_and_belongs_to_many(name, scope = nil, **options, &extension)
+          scope = handle_temporal_scope_option(scope, options)
+
+          super
+        end
+
+        private
+
+        def handle_temporal_scope_option(scope, options)
+          temporal = options.extract!(:temporal)[:temporal]
+
+          temporal ? AssociationScope.build(scope) : scope
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/as_of_query/association_scope.rb

@@ -0,0 +1,54 @@
+module ActiveRecord::Temporal
+  module AsOfQuery
+    class AssociationScope
+      class << self
+        def build(block)
+          scope = build_scope(block || default_base_scope)
+
+          def scope.as_of_scope? = true
+
+          scope
+        end
+
+        private
+
+        def build_scope(block)
+          temporal_scope = build_temporal_scope
+
+          if block.arity != 0
+            return ->(owner) do
+              base = instance_exec(owner, &block)
+              instance_exec(owner, base, &temporal_scope)
+            end
+          end
+
+          ->(owner = nil) do
+            base = instance_exec(owner, &block)
+            instance_exec(owner, base, &temporal_scope)
+          end
+        end
+
+        def build_temporal_scope
+          ->(owner, base) do
+            time_scopes = ScopeRegistry.query_scope_for(time_dimensions)
+            owner_time_scopes = owner&.time_scopes_for(time_dimensions)
+
+            time_scopes.merge!(owner_time_scopes) if owner_time_scopes
+
+            default_time_scopes = time_dimensions.map do |dimension|
+              [dimension, Time.current]
+            end.to_h
+
+            time_scope_constraints = default_time_scopes.merge(time_scopes)
+
+            base.existed_at(time_scope_constraints).time_scope(time_scopes)
+          end
+        end
+
+        def default_base_scope
+          proc { all }
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/as_of_query/association_walker.rb

@@ -0,0 +1,40 @@
+module ActiveRecord::Temporal
+  module AsOfQuery
+    class AssociationWalker
+      class << self
+        def each_target(parent_record, associations, &block)
+          walk_nodes(associations) do |association|
+            target = parent_record.association(association).target
+
+            next unless target
+
+            if target.is_a?(Array)
+              target.each(&block)
+            else
+              block.call(target)
+            end
+          end
+        end
+
+        private
+
+        def walk_nodes(node, &block)
+          case node
+          when Symbol, String
+            block.call(node)
+          when Array
+            node.each { |child| walk_nodes(child, &block) }
+          when Hash
+            # TODO: Write tests
+
+            node.each do |parent, child|
+              block.call(parent)
+
+              walk_nodes(child, &block)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/as_of_query/query_methods.rb

@@ -0,0 +1,24 @@
+module ActiveRecord::Temporal
+  module AsOfQuery
+    module QueryMethods
+      def time_scope(scope)
+        spawn.time_scope!(scope)
+      end
+
+      def time_scope!(scope)
+        self.time_scope_values = time_scope_values.merge(scope)
+        self
+      end
+
+      def time_scope_values
+        @values.fetch(:time_scope, ActiveRecord::QueryMethods::FROZEN_EMPTY_HASH)
+      end
+
+      def time_scope_values=(scope)
+        assert_modifiable! # TODO: write test
+
+        @values[:time_scope] = scope
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/as_of_query/scope_registry.rb

@@ -0,0 +1,38 @@
+module ActiveRecord::Temporal
+  module AsOfQuery
+    class ScopeRegistry
+      class << self
+        delegate :default_scopes, :query_scopes, :set_default_scopes, :query_scope_for, :with_query_scope, to: :instance
+
+        def instance
+          ActiveSupport::IsolatedExecutionState[:temporal_as_of_query_registry] ||= new
+        end
+      end
+
+      attr_reader :default_scopes, :query_scopes
+
+      def initialize
+        @default_scopes = {}
+        @query_scopes = {}
+      end
+
+      def set_default_scopes(default_scopes)
+        @default_scopes = default_scopes
+      end
+
+      def query_scope_for(dimensions)
+        query_scopes.slice(*dimensions)
+      end
+
+      def with_query_scope(scope, &block)
+        original = @query_scopes.dup
+
+        @query_scopes = @query_scopes.merge(scope)
+
+        block.call
+      ensure
+        @query_scopes = original
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/as_of_query/time_dimensions.rb

@@ -0,0 +1,69 @@
+module ActiveRecord::Temporal
+  module AsOfQuery
+    module TimeDimensions
+      extend ActiveSupport::Concern
+
+      included do
+        delegate :time_dimensions, :default_time_dimension, :time_dimension_column?, to: :class
+      end
+
+      class_methods do
+        def set_time_dimensions(*dimensions)
+          define_singleton_method(:time_dimensions) { dimensions }
+          define_singleton_method(:default_time_dimension) { dimensions.first }
+        end
+
+        def time_dimensions = []
+        def default_time_dimension = nil
+
+        def time_dimension_column?(time_dimension)
+          connection.column_exists?(table_name, time_dimension)
+        end
+      end
+
+      def time_dimension(dimension = nil)
+        dimension ||= default_time_dimension
+
+        if !time_dimension_column?(dimension)
+          raise ArgumentError, "no time dimension column '#{dimension}'"
+        end
+
+        send(dimension)
+      end
+
+      def time_dimension_start(dimension = nil)
+        time_dimension(dimension)&.begin
+      end
+
+      def time_dimension_end(dimension = nil)
+        time_dimension(dimension)&.end
+      end
+
+      def set_time_dimension(value, dimension = nil)
+        dimension ||= default_time_dimension
+
+        if !time_dimension_column?(dimension)
+          raise ArgumentError, "no time dimension column '#{dimension}'"
+        end
+
+        send("#{dimension}=", value)
+      end
+
+      def set_time_dimension_start(value, dimension = nil)
+        existing_value = time_dimension(dimension)
+
+        new_value = existing_value ? value...existing_value.end : value...nil
+
+        set_time_dimension(new_value, dimension)
+      end
+
+      def set_time_dimension_end(value, dimension = nil)
+        existing_value = time_dimension(dimension)
+
+        new_value = existing_value ? existing_value.begin...value : nil...value
+
+        set_time_dimension(new_value, dimension)
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/as_of_query.rb

@@ -0,0 +1,109 @@
+module ActiveRecord::Temporal
+  module AsOfQuery
+    class RangeError < StandardError; end
+
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def existed_at_constraint(arel_table, time, time_dimension)
+        time_as_tstz = Arel::Nodes::As.new(
+          Arel::Nodes::Quoted.new(time),
+          Arel::Nodes::SqlLiteral.new("timestamptz")
+        )
+
+        cast_value = Arel::Nodes::NamedFunction.new("CAST", [time_as_tstz])
+
+        arel_table[time_dimension].contains(cast_value)
+      end
+
+      def temporal_association_scope(&block)
+        AssociationScope.build(block)
+      end
+
+      def resolve_time_scopes(time_or_time_scopes)
+        return time_or_time_scopes if time_or_time_scopes.is_a?(Hash)
+
+        {default_time_dimension.to_sym => time_or_time_scopes}
+      end
+    end
+
+    included do
+      include AssociationMacros
+      include TimeDimensions
+
+      delegate :resolve_time_scopes, to: :class
+
+      scope :as_of, ->(time) do
+        time_scopes = resolve_time_scopes(time)
+
+        existed_at(time_scopes).time_scope(time_scopes)
+      end
+
+      scope :existed_at, ->(time) do
+        time_scopes = resolve_time_scopes(time)
+
+        rel = all
+
+        time_scopes.each do |time_dimension, time|
+          next unless time_dimension_column?(time_dimension)
+
+          rel = rel.where(existed_at_constraint(table, time, time_dimension))
+        end
+
+        rel
+      end
+    end
+
+    def time_scopes
+      @time_scopes || {}
+    end
+
+    def time_scopes=(value)
+      @time_scopes = value&.slice(*time_dimensions)
+    end
+
+    def time_scope
+      time_scopes[default_time_dimension]
+    end
+
+    def time_scopes_for(time_dimensions)
+      time_scopes.slice(*time_dimensions)
+    end
+
+    def as_of!(time)
+      time_scopes = resolve_time_scopes(time)
+
+      ensure_time_scopes_in_bounds!(time_scopes)
+
+      reload
+
+      self.time_scopes = time_scopes
+    end
+
+    def as_of(time)
+      time_scopes = resolve_time_scopes(time)
+
+      self.class.as_of(time_scopes).find_by(self.class.primary_key => [id])
+    end
+
+    def initialize_time_scope_from_relation(relation)
+      associations = relation.includes_values | relation.eager_load_values
+
+      self.time_scopes = relation.time_scope_values
+
+      AssociationWalker.each_target(self, associations) do |target|
+        target.time_scopes = relation.time_scope_values
+      end
+    end
+
+    private
+
+    def ensure_time_scopes_in_bounds!(time_scopes)
+      time_scopes.each do |dimension, time|
+        if time_dimension_column?(dimension) && !time_dimension(dimension).cover?(time)
+          raise RangeError, "#{time} is outside of '#{dimension}' range"
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/patches/association_reflection.rb

@@ -0,0 +1,19 @@
+module ActiveRecord::Temporal
+  module Patches
+    module AssociationReflection
+      def check_eager_loadable!
+        super unless as_of_scope? && scope_requires_no_params?
+      end
+
+      private
+
+      def as_of_scope?
+        scope.respond_to?(:as_of_scope?) && scope.as_of_scope?
+      end
+
+      def scope_requires_no_params?
+        scope.arity == 0 || scope.arity == -1
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/patches/join_dependency.rb

@@ -0,0 +1,53 @@
+module ActiveRecord::Temporal
+  module Patches
+    module JoinDependency
+      def instantiate(result_set, strict_loading_value, &block)
+        primary_key = Array(join_root.primary_key).map { |column| aliases.column_alias(join_root, column) }
+
+        seen = Hash.new { |i, parent|
+          i[parent] = Hash.new { |j, child_class|
+            j[child_class] = {}
+          }
+        }.compare_by_identity
+
+        model_cache = Hash.new { |h, klass| h[klass] = {} }
+        parents = model_cache[join_root]
+
+        column_aliases = aliases.column_aliases(join_root)
+        column_names = []
+
+        result_set.columns.each do |name|
+          column_names << name unless /\At\d+_r\d+\z/.match?(name)
+        end
+
+        if column_names.empty?
+          column_types = {}
+        else
+          column_types = result_set.column_types
+          unless column_types.empty?
+            attribute_types = join_root.attribute_types
+            column_types = column_types.slice(*column_names).delete_if { |k, _| attribute_types.key?(k) }
+          end
+          column_aliases += column_names.map! { |name| Aliases::Column.new(name, name) }
+        end
+
+        message_bus = ActiveSupport::Notifications.instrumenter
+
+        payload = {
+          record_count: result_set.length,
+          class_name: join_root.base_klass.name
+        }
+
+        message_bus.instrument("instantiation.active_record", payload) do
+          result_set.each { |row_hash|
+            parent_key = primary_key.empty? ? row_hash : row_hash.values_at(*primary_key)
+            parent = parents[parent_key] ||= join_root.instantiate(row_hash, column_aliases, column_types, &block)
+            construct(parent, join_root, row_hash, seen, model_cache, strict_loading_value)
+          }
+        end
+
+        parents.values
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/patches/merger.rb

@@ -0,0 +1,11 @@
+module ActiveRecord::Temporal
+  module Patches
+    module Merger
+      def merge
+        super.tap do |relation|
+          relation.time_scope!(values[:time_scope] || {})
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/patches/relation.rb

@@ -0,0 +1,29 @@
+module ActiveRecord::Temporal
+  module Patches
+    module Relation
+      private
+
+      if ActiveRecord.version > Gem::Version.new("8.0.4")
+        def build_arel(connection)
+          AsOfQuery::ScopeRegistry.with_query_scope(time_scope_values) { super }
+        end
+      else
+        def build_arel(connection, aliases = nil)
+          AsOfQuery::ScopeRegistry.with_query_scope(time_scope_values) { super }
+        end
+      end
+
+      def instantiate_records(rows, &block)
+        return super if time_scope_values.empty?
+
+        records = super
+
+        records.each do |record|
+          record.initialize_time_scope_from_relation(self) if record.is_a?(AsOfQuery)
+        end
+
+        records
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/patches/through_association.rb

@@ -0,0 +1,11 @@
+module ActiveRecord::Temporal
+  module Patches
+    module ThroughAssociation
+      def through_scope
+        super.tap do |scope|
+          scope.time_scope_values = reflection_scope.time_scope_values
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/system_versioning/command_recorder.rb

@@ -0,0 +1,47 @@
+module ActiveRecord::Temporal
+  module SystemVersioning
+    module CommandRecorder
+      [
+        :create_versioning_hook,
+        :drop_versioning_hook,
+        :change_versioning_hook
+      ].each do |method|
+        class_eval <<-EOV, __FILE__, __LINE__ + 1
+          def #{method}(*args)
+            record(:#{method}, args)
+          end
+        EOV
+
+        ruby2_keywords(method)
+      end
+
+      def invert_drop_versioning_hook(args)
+        _, _, columns = args
+
+        if columns.nil?
+          raise ActiveRecord::IrreversibleMigration, "drop_versioning_hook is only reversible if given :columns option."
+        end
+
+        [:create_versioning_hook, args]
+      end
+
+      def invert_create_versioning_hook(args)
+        [:drop_versioning_hook, args]
+      end
+
+      def invert_change_versioning_hook(args)
+        source_table, history_table, options = args
+
+        [
+          :change_versioning_hook,
+          [
+            source_table,
+            history_table,
+            add_columns: options[:remove_columns],
+            remove_columns: options[:add_columns]
+          ]
+        ]
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/system_versioning/model.rb

@@ -0,0 +1,37 @@
+module ActiveRecord::Temporal
+  module SystemVersioning
+    module Model
+      extend ActiveSupport::Concern
+
+      included do
+        include AsOfQuery
+
+        set_time_dimensions :system_period
+
+        reflect_on_all_associations.each do |reflection|
+          scope = temporal_association_scope(&reflection.scope)
+
+          send(reflection.macro, reflection.name, scope, **reflection.options)
+        end
+      end
+
+      class_methods do
+        def polymorphic_class_for(name)
+          super.version_model
+        end
+
+        def sti_name
+          superclass.sti_name
+        end
+
+        def find_sti_class(type_name)
+          superclass.send(:find_sti_class, type_name).version_model
+        end
+
+        def finder_needs_type_condition?
+          superclass.finder_needs_type_condition?
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/system_versioning/namespace.rb

@@ -0,0 +1,34 @@
+module ActiveRecord::Temporal
+  module SystemVersioning
+    module Namespace
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def const_missing(name)
+          model = name.to_s.constantize
+        rescue NameError
+          super
+        else
+          unless model.is_a?(Class) && model < ActiveRecord::Base
+            raise NameError, "#{model} is not a descendent of ActiveRecord::Base"
+          end
+
+          version_model = if (history_table = model.history_table)
+            Class.new(model) do
+              self.table_name = history_table
+              self.primary_key = model.primary_key_from_db + [:system_period]
+
+              include Model
+            end
+          else
+            Class.new(model) do
+              include Model
+            end
+          end
+
+          const_set(name, version_model)
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/system_versioning/schema_creation.rb

@@ -0,0 +1,147 @@
+require "active_support/core_ext/hash/deep_transform_values"
+
+module ActiveRecord::Temporal
+  module SystemVersioning
+    class SchemaCreation
+      def initialize(conn)
+        @conn = conn
+      end
+
+      def accept(o)
+        m = "visit_#{o.class.name.split("::").last}"
+        send m, o
+      end
+
+      delegate :quote_table_name, :quote_column_name, :quote_string, :versioning_function_name, to: :@conn, private: true
+
+      private
+
+      def visit_VersioningHookDefinition(o)
+        [o.insert_hook, o.update_hook, o.delete_hook].map { |t| accept(t) }.join(" ")
+      end
+
+      def visit_InsertHookDefinition(o)
+        column_names = o.columns.map { |c| quote_column_name(c) }
+        fields = column_names.join(", ")
+        values = column_names.map { |c| "NEW.#{c}" }.join(", ")
+        function_name = versioning_function_name(o.source_table, :insert)
+
+        metadata = {
+          verb: :insert,
+          source_table: o.source_table,
+          history_table: o.history_table,
+          columns: o.columns
+        }
+
+        <<~SQL
+          CREATE FUNCTION #{function_name}() RETURNS TRIGGER AS $$
+            BEGIN
+              INSERT INTO #{quote_table_name(o.history_table)} (#{fields}, system_period)
+              VALUES (#{values}, tstzrange(NOW(), 'infinity'));
+
+              RETURN NULL;
+            END;
+          $$ LANGUAGE plpgsql;
+
+          CREATE TRIGGER versioning_insert_trigger AFTER INSERT ON #{quote_table_name(o.source_table)}
+            FOR EACH ROW EXECUTE PROCEDURE #{function_name}();
+
+          #{create_metadata_comment(function_name, metadata)}
+        SQL
+      end
+
+      def visit_UpdateHookDefinition(o)
+        column_names = o.columns.map { |c| quote_column_name(c) }
+        primary_key_quoted = o.primary_key.map { |c| quote_column_name(c) }
+        fields = column_names.join(", ")
+        values = column_names.map { |c| "NEW.#{c}" }.join(", ")
+        update_pk_predicates = primary_key_quoted.map { |c| "#{c} = OLD.#{c}" }.join(" AND ")
+        on_conflict_constraint = (primary_key_quoted + [:system_period]).join(", ")
+        on_conflict_sets = column_names.map { |c| "#{c} = EXCLUDED.#{c}" }.join(", ")
+        function_name = versioning_function_name(o.source_table, :update)
+        metadata = {
+          verb: :update,
+          source_table: o.source_table,
+          history_table: o.history_table,
+          columns: o.columns,
+          primary_key: o.primary_key
+        }
+
+        <<~SQL
+          CREATE FUNCTION #{function_name}() RETURNS trigger AS $$
+            BEGIN
+              IF OLD IS NOT DISTINCT FROM NEW THEN
+                RETURN NULL;
+              END IF;
+
+              UPDATE #{quote_table_name(o.history_table)}
+              SET system_period = tstzrange(lower(system_period), NOW())
+              WHERE #{update_pk_predicates} AND upper(system_period) = 'infinity' AND lower(system_period) < NOW();
+
+              INSERT INTO #{quote_table_name(o.history_table)} (#{fields}, system_period)
+              VALUES (#{values}, tstzrange(NOW(), 'infinity'))
+              ON CONFLICT (#{on_conflict_constraint}) DO UPDATE SET #{on_conflict_sets};
+
+              RETURN NULL;
+            END;
+          $$ LANGUAGE plpgsql;
+
+          CREATE TRIGGER versioning_update_trigger AFTER UPDATE ON #{quote_table_name(o.source_table)}
+            FOR EACH ROW EXECUTE PROCEDURE #{function_name}();
+
+          #{create_metadata_comment(function_name, metadata)}
+        SQL
+      end
+
+      def visit_DeleteHookDefinition(o)
+        primary_key_quoted = o.primary_key.map { |c| quote_column_name(c) }
+        function_name = versioning_function_name(o.source_table, :delete)
+        pk_predicates = primary_key_quoted.map { |c| "#{c} = OLD.#{c}" }.join(" AND ")
+        metadata = {
+          verb: :delete,
+          source_table: o.source_table,
+          history_table: o.history_table,
+          primary_key: o.primary_key
+        }
+
+        <<~SQL
+          CREATE FUNCTION #{function_name}() RETURNS TRIGGER AS $$
+            BEGIN
+              DELETE FROM #{quote_table_name(o.history_table)}
+              WHERE #{pk_predicates} AND system_period = tstzrange(NOW(), 'infinity');
+
+              UPDATE #{quote_table_name(o.history_table)}
+              SET system_period = tstzrange(lower(system_period), NOW())
+              WHERE #{pk_predicates} AND upper(system_period) = 'infinity';
+
+              RETURN NULL;
+            END;
+          $$ LANGUAGE plpgsql;
+
+          CREATE TRIGGER versioning_delete_trigger AFTER DELETE ON #{quote_table_name(o.source_table)}
+            FOR EACH ROW EXECUTE PROCEDURE #{function_name}();
+
+          #{create_metadata_comment(function_name, metadata)}
+        SQL
+      end
+
+      private
+
+      def create_metadata_comment(function_name, metadata)
+        quoted_metadata = metadata.deep_transform_values do |v|
+          if v.is_a?(Array)
+            v.map { quote_string(_1.to_s) }
+          else
+            quote_string(v.to_s)
+          end
+        end
+
+        json = JSON.generate(quoted_metadata)
+
+        <<~SQL
+          COMMENT ON FUNCTION #{function_name}() IS '#{json}';
+        SQL
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/system_versioning/schema_definitions.rb

@@ -0,0 +1,37 @@
+module ActiveRecord::Temporal
+  module SystemVersioning
+    class VersioningHookDefinition
+      attr_accessor :source_table, :history_table, :columns, :primary_key
+
+      def initialize(
+        source_table,
+        history_table,
+        columns:,
+        primary_key:
+      )
+        @source_table = source_table
+        @history_table = history_table
+        @columns = columns
+        @primary_key = primary_key
+      end
+
+      def insert_hook
+        InsertHookDefinition.new(@source_table, @history_table, @columns)
+      end
+
+      def update_hook
+        UpdateHookDefinition.new(@source_table, @history_table, @columns, @primary_key)
+      end
+
+      def delete_hook
+        DeleteHookDefinition.new(@source_table, @history_table, @primary_key)
+      end
+    end
+
+    InsertHookDefinition = Struct.new(:source_table, :history_table, :columns)
+
+    UpdateHookDefinition = Struct.new(:source_table, :history_table, :columns, :primary_key)
+
+    DeleteHookDefinition = Struct.new(:source_table, :history_table, :primary_key)
+  end
+end

data/lib/activerecord/temporal/system_versioning/schema_statements.rb

@@ -0,0 +1,129 @@
+module ActiveRecord::Temporal
+  module SystemVersioning
+    module SchemaStatements
+      def create_versioning_hook(source_table, history_table, **options)
+        columns = options.fetch(:columns)&.map(&:to_s)
+        primary_key = Array(options.fetch(:primary_key, :id))
+
+        ensure_table_exists!(source_table)
+        ensure_table_exists!(history_table)
+        ensure_columns_match!(source_table, history_table, columns)
+        ensure_columns_exists!(source_table, primary_key)
+
+        schema_creation = SchemaCreation.new(self)
+
+        hook_definition = VersioningHookDefinition.new(
+          source_table,
+          history_table,
+          columns: columns,
+          primary_key: primary_key
+        )
+
+        execute schema_creation.accept(hook_definition)
+      end
+
+      def drop_versioning_hook(source_table, history_table, columns: nil)
+        %i[insert update delete].each do |verb|
+          function_name = versioning_function_name(source_table, verb)
+
+          execute "DROP FUNCTION #{function_name}() CASCADE"
+        end
+      end
+
+      def versioning_hook(source_table)
+        update_function_name = versioning_function_name(source_table, :update)
+
+        row = execute(<<~SQL.squish).first
+          SELECT
+            pg_proc.proname as function_name,
+            obj_description(pg_proc.oid, 'pg_proc') as comment
+          FROM pg_proc
+          JOIN pg_namespace ON pg_proc.pronamespace = pg_namespace.oid
+          WHERE pg_namespace.nspname NOT IN ('pg_catalog', 'information_schema')
+            AND pg_proc.proname = '#{update_function_name}'
+        SQL
+
+        return unless row
+
+        metadata = JSON.parse(row["comment"])
+
+        VersioningHookDefinition.new(
+          metadata["source_table"],
+          metadata["history_table"],
+          columns: metadata["columns"],
+          primary_key: metadata["primary_key"]
+        )
+      end
+
+      def change_versioning_hook(source_table, history_table, options)
+        add_columns = (options[:add_columns] || []).map(&:to_s)
+        remove_columns = (options[:remove_columns] || []).map(&:to_s)
+
+        ensure_table_exists!(source_table)
+        ensure_table_exists!(history_table)
+        ensure_columns_match!(source_table, history_table, add_columns)
+
+        hook_definition = versioning_hook(source_table)
+
+        ensure_hook_has_columns!(hook_definition, remove_columns)
+
+        drop_versioning_hook(source_table, history_table)
+
+        new_columns = hook_definition.columns + add_columns - remove_columns
+
+        create_versioning_hook(source_table, history_table, columns: new_columns)
+      end
+
+      def history_table(source_table)
+        hook_definition = versioning_hook(source_table)
+
+        hook_definition&.history_table
+      end
+
+      def versioning_function_name(source_table, verb)
+        identifier = "#{source_table}_#{verb}"
+        hashed_identifier = Digest::SHA256.hexdigest(identifier).first(10)
+
+        "sys_ver_func_#{hashed_identifier}"
+      end
+
+      private
+
+      def ensure_table_exists!(table_name)
+        return if table_exists?(table_name)
+
+        raise ArgumentError, "table '#{table_name}' does not exist"
+      end
+
+      def ensure_columns_match!(source_table, history_table, column_names)
+        ensure_columns_exists!(source_table, column_names)
+        ensure_columns_exists!(history_table, column_names)
+
+        column_names.each do |column|
+          source_column = columns(source_table).find { _1.name == column }
+          history_column = columns(history_table).find { _1.name == column }
+
+          if source_column.type != history_column.type
+            raise ArgumentError, "table '#{history_table}' does not have column '#{column}' of type '#{source_column.type}'"
+          end
+        end
+      end
+
+      def ensure_columns_exists!(table_name, column_names)
+        column_names.each do |column|
+          next if column_exists?(table_name, column)
+
+          raise ArgumentError, "table '#{table_name}' does not have column '#{column}'"
+        end
+      end
+
+      def ensure_hook_has_columns!(hook, column_names)
+        column_names.each do |column_name|
+          next if hook.columns.include?(column_name)
+
+          raise ArgumentError, "versioning hook between '#{hook.source_table}' and '#{hook.history_table}' does not have column '#{column_name}'"
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/system_versioning.rb

@@ -0,0 +1,27 @@
+module ActiveRecord::Temporal
+  module SystemVersioning
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def history_table
+        connection.history_table(table_name)
+      end
+
+      def primary_key_from_db
+        Array(connection.primary_key(table_name)).map(&:to_sym)
+      end
+
+      def version_model
+        "Version::#{name}".constantize
+      end
+
+      def system_versioning(namespace: "Version")
+        unless Object.const_defined?(namespace)
+          mod = Module.new
+          mod.include(Namespace)
+          Object.const_set(namespace, mod)
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/version.rb

@@ -0,0 +1,3 @@
+module ActiveRecord::Temporal
+  VERSION = "0.1.0"
+end

data/lib/activerecord/temporal.rb

@@ -0,0 +1,63 @@
+require "active_support"
+
+require_relative "temporal/application_versioning"
+require_relative "temporal/as_of_query"
+require_relative "temporal/as_of_query/association_macros"
+require_relative "temporal/as_of_query/association_scope"
+require_relative "temporal/as_of_query/association_walker"
+require_relative "temporal/as_of_query/query_methods"
+require_relative "temporal/as_of_query/scope_registry"
+require_relative "temporal/as_of_query/time_dimensions"
+require_relative "temporal/patches/association_reflection"
+require_relative "temporal/patches/join_dependency"
+require_relative "temporal/patches/merger"
+require_relative "temporal/patches/relation"
+require_relative "temporal/patches/through_association"
+require_relative "temporal/system_versioning"
+require_relative "temporal/system_versioning/command_recorder"
+require_relative "temporal/system_versioning/namespace"
+require_relative "temporal/system_versioning/model"
+require_relative "temporal/system_versioning/schema_creation"
+require_relative "temporal/system_versioning/schema_definitions"
+require_relative "temporal/system_versioning/schema_statements"
+
+ActiveSupport.on_load(:active_record) do
+  require "active_record/connection_adapters/postgresql_adapter" # TODO: add test
+
+  ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.include(ActiveRecord::Temporal::SystemVersioning::SchemaStatements)
+  ActiveRecord::Migration::CommandRecorder.include(ActiveRecord::Temporal::SystemVersioning::CommandRecorder)
+  ActiveRecord::Relation.include(ActiveRecord::Temporal::AsOfQuery::QueryMethods)
+
+  # Patches
+
+  # Patches the `build_arel` method wrap itself in the as-of query scope registry.
+  # This is what allows temporal association scopes to be aware of the time-scope
+  # value of the relation that included them.
+  #
+  # Patches the `instantiate_records` method to call `initialize_time_scope_from_relation`
+  # on each loaded record.
+  ActiveRecord::Relation.prepend(ActiveRecord::Temporal::Patches::Relation)
+
+  # Patches the `merge` method (called by `Relation#merge`) to handle the new
+  # query method `time_scope` that this gem adds.
+  ActiveRecord::Relation::Merger.prepend(ActiveRecord::Temporal::Patches::Merger)
+
+  # Patches the preloader's `through_scope` method to pass along the relation's
+  # time-scope values when it handles has-many-through associations. The handler
+  # for has-many assoication uses `Relation#merge`, but this one doesn't.
+  ActiveRecord::Associations::Preloader::ThroughAssociation.prepend(ActiveRecord::Temporal::Patches::ThroughAssociation)
+
+  # This permits association scopes generated by this gem to be eager-load if they
+  # are "optionally instance-dependent." That is to say, they accept arguments,
+  # but don't require any arguments.
+  #
+  # I think permitting eager-loading optionally instance-dependent association
+  # scopes would make sense as a general feature. See this PR for my justification:
+  # https://github.com/rails/rails/pull/56004
+  ActiveRecord::Reflection::AssociationReflection.prepend(ActiveRecord::Temporal::Patches::AssociationReflection)
+
+  # This is a copy of a fix from https://github.com/rails/rails/pull/56088 that
+  # impacts this gem. I has been backported to supported stable versions of
+  # Active Record, but until those patches are released it's included here.
+  ActiveRecord::Associations::JoinDependency.prepend(ActiveRecord::Temporal::Patches::JoinDependency)
+end

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: activerecord-temporal
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Martin-Alexander
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: An unobtrusive and modular plugin for Active Record that adds support
+  for time-travel querying and data versioning at the application level, at the system
+  level via PostgreSQL triggers, or both.
+email:
+- martingianna@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/activerecord/temporal.rb
+- lib/activerecord/temporal/application_versioning.rb
+- lib/activerecord/temporal/as_of_query.rb
+- lib/activerecord/temporal/as_of_query/association_macros.rb
+- lib/activerecord/temporal/as_of_query/association_scope.rb
+- lib/activerecord/temporal/as_of_query/association_walker.rb
+- lib/activerecord/temporal/as_of_query/query_methods.rb
+- lib/activerecord/temporal/as_of_query/scope_registry.rb
+- lib/activerecord/temporal/as_of_query/time_dimensions.rb
+- lib/activerecord/temporal/patches/association_reflection.rb
+- lib/activerecord/temporal/patches/join_dependency.rb
+- lib/activerecord/temporal/patches/merger.rb
+- lib/activerecord/temporal/patches/relation.rb
+- lib/activerecord/temporal/patches/through_association.rb
+- lib/activerecord/temporal/system_versioning.rb
+- lib/activerecord/temporal/system_versioning/command_recorder.rb
+- lib/activerecord/temporal/system_versioning/model.rb
+- lib/activerecord/temporal/system_versioning/namespace.rb
+- lib/activerecord/temporal/system_versioning/schema_creation.rb
+- lib/activerecord/temporal/system_versioning/schema_definitions.rb
+- lib/activerecord/temporal/system_versioning/schema_statements.rb
+- lib/activerecord/temporal/version.rb
+homepage: https://github.com/Martin-Alexander/activerecord-temporal
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/Martin-Alexander/activerecord-temporal/issues
+  changelog_uri: https://github.com/Martin-Alexander/activerecord-temporal/CHANGELOG.md
+  homepage_uri: https://github.com/Martin-Alexander/activerecord-temporal
+  source_code_uri: https://github.com/Martin-Alexander/activerecord-temporal
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Time-travel querying, application/system versioning, and bitemporal support
+  for Active Record
+test_files: []