chrono_model 0.3.0 → 0.3.1

data/.gitignore

@@ -3,7 +3,6 @@
 .bundle
 .config
 .yardoc
-Gemfile.lock
 InstalledFiles
 _yardoc
 coverage

data/Gemfile

@@ -4,7 +4,7 @@ source 'https://rubygems.org'
 gemspec
 
 group :development do
-  gem 'ruby-debug19'
+  gem 'debugger'
   gem 'pry'
   gem 'rspec'
 end

data/Gemfile.lock

@@ -0,0 +1,60 @@
+PATH
+  remote: .
+  specs:
+    chrono_model (0.3.0)
+      activerecord (~> 3.2)
+      pg
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (3.2.8)
+      activesupport (= 3.2.8)
+      builder (~> 3.0.0)
+    activerecord (3.2.8)
+      activemodel (= 3.2.8)
+      activesupport (= 3.2.8)
+      arel (~> 3.0.2)
+      tzinfo (~> 0.3.29)
+    activesupport (3.2.8)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    arel (3.0.2)
+    builder (3.0.4)
+    coderay (1.0.8)
+    columnize (0.3.6)
+    debugger (1.2.1)
+      columnize (>= 0.3.1)
+      debugger-linecache (~> 1.1.1)
+      debugger-ruby_core_source (~> 1.1.4)
+    debugger-linecache (1.1.2)
+      debugger-ruby_core_source (>= 1.1.1)
+    debugger-ruby_core_source (1.1.4)
+    diff-lcs (1.1.3)
+    i18n (0.6.1)
+    method_source (0.8.1)
+    multi_json (1.3.6)
+    pg (0.14.1)
+    pry (0.9.10)
+      coderay (~> 1.0.5)
+      method_source (~> 0.8)
+      slop (~> 3.3.1)
+    rspec (2.11.0)
+      rspec-core (~> 2.11.0)
+      rspec-expectations (~> 2.11.0)
+      rspec-mocks (~> 2.11.0)
+    rspec-core (2.11.1)
+    rspec-expectations (2.11.3)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.11.3)
+    slop (3.3.3)
+    tzinfo (0.3.33)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  chrono_model!
+  debugger
+  pry
+  rspec

data/README.md

@@ -85,6 +85,23 @@ by the other schema statements. E.g.:
  * `remove_index`  - removes the index from the history table as well
 
 
+## Adding Temporal extensions to an existing table
+
+Use `change_table`:
+
+    change_table :your_table, :temporal => true
+
+If you want to also set up the history from your current data:
+
+    change_table :your_table, :temporal => true, :copy_data => true
+
+This will create an history record for each record in your table, setting its
+validity from midnight, January 1st, 1 CE. You can set a specific validity
+with the `:validity` option:
+
+    change_table :your_table, :temporal => true, :copy_data => true, :validity => '1977-01-01'
+
+
 ## Data querying
 
 A model backed by a temporal view will behave like any other model backed by a
@@ -97,7 +114,8 @@ plain table. If you want to do as-of-date queries, you need to include the
       has_many :compositions
     end
 
-This will make an `as_of` class method available to your model. E.g.:
+This will create a `Country::History` model inherited from `Country`, and it
+will make an `as_of` class method available to your model. E.g.:
 
     Country.as_of(1.year.ago)
 

data/lib/chrono_model/adapter.rb

@@ -8,9 +8,14 @@ module ChronoModel
   # adapter for a clean override of its methods using super.
   #
   class Adapter < ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
-    TEMPORAL_SCHEMA = 'temporal' # The schema holding current data
-    HISTORY_SCHEMA  = 'history'  # The schema holding historical data
+    # The schema holding current data
+    TEMPORAL_SCHEMA = 'temporal'
 
+    # The schema holding historical data
+    HISTORY_SCHEMA  = 'history'
+
+    # Chronomodel is supported starting with PostgreSQL >= 9.0
+    #
     def chrono_supported?
       postgresql_version >= 90000
     end
@@ -87,6 +92,24 @@ module ChronoModel
             chrono_create_view_for(table_name)
 
             TableCache.add! table_name
+
+            # Optionally copy the plain table data, setting up history
+            # retroactively.
+            #
+            if options[:copy_data]
+              seq  = _on_history_schema { serial_sequence(table_name, primary_key(table_name)) }
+              from = options[:validity] || '0001-01-01 00:00:00'
+
+              execute %[
+                INSERT INTO #{HISTORY_SCHEMA}.#{table_name}
+                SELECT *,
+                  nextval('#{seq}')               AS hid,
+                  timestamp '#{from}'             AS valid_from,
+                  timestamp '9999-12-31 00:00:00' AS valid_to,
+                  timezone('UTC', now())          AS recorded_at
+                FROM #{TEMPORAL_SCHEMA}.#{table_name}
+              ]
+            end
           end
 
           chrono_alter(table_name) { super table_name, options, &block }
@@ -353,16 +376,32 @@ module ChronoModel
 
         # INSERT - inert data both in the temporal table and in the history one.
         #
-        execute <<-SQL
-          CREATE OR REPLACE RULE #{table}_ins AS ON INSERT TO #{table} DO INSTEAD (
+        if sequence.present?
+          execute <<-SQL
+            CREATE OR REPLACE RULE #{table}_ins AS ON INSERT TO #{table} DO INSTEAD (
 
-            INSERT INTO #{current} ( #{fields} ) VALUES ( #{values} );
+              INSERT INTO #{current} ( #{fields} ) VALUES ( #{values} );
 
-            INSERT INTO #{history} ( #{pk}, #{fields}, valid_from )
-            VALUES ( currval('#{sequence}'), #{values}, timezone('UTC', now()) )
-            RETURNING #{pk}, #{fields}
-          )
-        SQL
+              INSERT INTO #{history} ( #{pk}, #{fields}, valid_from )
+              VALUES ( currval('#{sequence}'), #{values}, timezone('UTC', now()) )
+              RETURNING #{pk}, #{fields}
+            )
+          SQL
+        else
+          fields_with_pk = "#{pk}, " << fields
+          values_with_pk = "new.#{pk}, " << values
+
+          execute <<-SQL
+            CREATE OR REPLACE RULE #{table}_ins AS ON INSERT TO #{table} DO INSTEAD (
+
+              INSERT INTO #{current} ( #{fields_with_pk} ) VALUES ( #{values_with_pk} );
+
+              INSERT INTO #{history} ( #{fields_with_pk}, valid_from )
+              VALUES ( #{values_with_pk}, timezone('UTC', now()) )
+              RETURNING #{fields_with_pk}
+            )
+          SQL
+        end
 
         # UPDATE - set the last history entry validity to now, save the current data
         # in a new history entry and update the temporal table with the new data.

data/lib/chrono_model/railtie.rb

@@ -11,6 +11,7 @@ module ChronoModel
       end
 
       task 'db:schema:load' => 'db:chrono:create_schemas'
+      task 'db:migrate'     => 'db:chrono:create_schemas'
     end
 
     class SchemaDumper < ::ActiveRecord::SchemaDumper

data/lib/chrono_model/time_machine.rb

@@ -11,122 +11,205 @@ module ChronoModel
           "Currently, only PostgreSQL >= 9.0 is supported."
       end
 
-      unless chrono?
+      if table_exists? && !chrono?
         raise Error, "#{table_name} is not a temporal table. " \
           "Please use change_table :#{table_name}, :temporal => true"
       end
 
-      TimeMachine.chrono_models[table_name] = self
+      history = TimeMachine.define_history_model_for(self)
+      TimeMachine.chrono_models[table_name] = history
     end
 
-    # Returns an Hash keyed by table name of models that included
-    # ChronoModel::TimeMachine
+    # Returns an Hash keyed by table name of ChronoModels
     #
     def self.chrono_models
       (@chrono_models ||= {})
     end
 
-    # Returns a read-only representation of this record as it was +time+ ago.
-    #
-    def as_of(time)
-      self.class.as_of(time).find(self)
-    end
+    def self.define_history_model_for(model)
+      history = Class.new(model) do
+        self.table_name = [Adapter::HISTORY_SCHEMA, model.table_name].join('.')
 
-    # Return the complete read-only history of this instance.
-    #
-    def history
-      self.class.history_of(self)
-    end
+        extend TimeMachine::HistoryMethods
 
-    # Aborts the destroy if this is an historical record
-    #
-    def destroy
-      if historical?
-        raise ActiveRecord::ReadOnlyRecord, 'Cannot delete historical records'
-      else
-        super
+        # The history id is `hid`, but this cannot set as primary key
+        # or temporal assocations will break. Solutions are welcome.
+        def id
+          hid
+        end
+
+        # Referenced record ID
+        #
+        def rid
+          attributes[self.class.primary_key]
+        end
+
+        # HACK to make ActiveAdmin work properly. This will be surely
+        # better written in the future.
+        #
+        def self.find(*args)
+          old = self.primary_key
+          self.primary_key = :hid
+          super
+        ensure
+          self.primary_key = old
+        end
+
+        # SCD Type 2 validity from timestamp
+        #
+        def valid_from
+          utc_timestamp_from('valid_from')
+        end
+
+        # SCD Type 2 validity to timestamp
+        #
+        def valid_to
+          utc_timestamp_from('valid_to')
+        end
+
+        # History recording timestamp
+        #
+        def recorded_at
+          utc_timestamp_from('recorded_at')
+        end
+
+        # Virtual attribute used to pass around the
+        # current timestamp in association queries
+        #
+        def as_of_time
+          Conversions.string_to_utc_time attributes['as_of_time']
+        end
+
+        # Inhibit destroy of historical records
+        #
+        def destroy
+          raise ActiveRecord::ReadOnlyRecord, 'Cannot delete historical records'
+        end
+
+        private
+          # Hack around AR timezone support. These timestamps are recorded
+          # by the chrono rewrite rules in UTC, but AR reads them as they
+          # were stored in the local timezone - thus here we reset its
+          # assumption. TODO: OPTIMIZE.
+          #
+          if ActiveRecord::Base.default_timezone != :utc
+            def utc_timestamp_from(attr)
+              attributes[attr].utc + Time.now.utc_offset
+            end
+          else
+            def utc_timestamp_from(attr)
+              attributes[attr]
+            end
+          end
       end
-    end
 
-    # Returns true if this record was fetched from history
-    #
-    def historical?
-      attributes.key?('hid')
-    end
+      model.singleton_class.instance_eval do
+        define_method(:history) { history }
+      end
 
-    HISTORY_ATTRIBUTES = %w( valid_from valid_to recorded_at as_of_time ).each do |attr|
-      define_method(attr) { Conversions.string_to_utc_time(attributes[attr]) }
+      model.const_set :History, history
+
+      return history
     end
 
-    # Strips the history timestamps when duplicating history records
+    # Returns a read-only representation of this record as it was +time+ ago.
     #
-    def initialize_dup(other)
-      super
+    def as_of(time)
+      self.class.as_of(time).where(:id => self.id).first!
+    end
 
-      if historical?
-        HISTORY_ATTRIBUTES.each {|attr| @attributes.delete(attr)}
-        @attributes.delete 'hid'
-        @readonly = false
-        @new_record = true
-      end
+    # Return the complete read-only history of this instance.
+    #
+    def history
+      self.class.history.of(self)
     end
 
     # Returns an Array of timestamps for which this instance has an history
     # record. Takes temporal associations into account.
     #
     def history_timestamps
-      self.class.history_timestamps do |query|
+      self.class.history.timestamps do |query|
         query.where(:id => self)
       end
     end
 
+    def historical?
+      self.kind_of? self.class.history
+    end
+
     module ClassMethods
-      # Fetches as of +time+ records.
-      #
+      # Returns an ActiveRecord::Relation on the history of this model as
+      # it was +time+ ago.
       def as_of(time)
-        time = Conversions.time_to_utc_string(time.utc)
+        history.as_of(time, current_scope)
+      end
+    end
 
-        readonly.with(table_name, on_history(time)).tap do |relation|
-          relation.instance_variable_set(:@temporal, time)
+    # Methods that make up the history interface of the companion History
+    # model build on each Model that includes TimeMachine
+    module HistoryMethods
+      # Fetches as of +time+ records.
+      #
+      def as_of(time, scope = nil)
+        time = Conversions.time_to_utc_string(time.utc) if time.kind_of? Time
+
+        as_of = superclass.unscoped.readonly.
+          with(superclass.table_name, at(time))
+
+        # Add default scopes back if we're passed nil or a
+        # specific scope, because we're .unscopeing above.
+        #
+        scopes = scope.present? ? [scope] : (
+          superclass.default_scopes.map do |s|
+            s.respond_to?(:call) ? s.call : s
+          end)
+
+        scopes.each do |scope|
+          scope.order_values.each {|clause| as_of = as_of.order(clause.to_sql)}
+          scope.where_values.each {|clause| as_of = as_of.where(clause.to_sql)}
         end
+
+        as_of.instance_variable_set(:@temporal, time)
+
+        return as_of
       end
 
-      def on_history(time)
-        unscoped.from(history_table_name).
-          select("#{history_table_name}.*, '#{time}' AS as_of_time").
-          where("'#{time}' >= valid_from AND '#{time}' < valid_to")
+      # Fetches history record at the given time
+      #
+      def at(time)
+        from, to = quoted_history_fields
+        unscoped.
+          select("#{quoted_table_name}.*, '#{time}' AS as_of_time").
+          where("'#{time}' >= #{from} AND '#{time}' < #{to}")
       end
 
       # Returns the whole history as read only.
       #
-      def history
-        readonly.from(history_table_name).order("#{history_table_name}.recorded_at")
+      def all
+        readonly.
+          order("#{table_name}.recorded_at, hid").all
       end
 
       # Fetches the given +object+ history, sorted by history record time.
       #
-      def history_of(object)
-        history.
-          select("#{history_table_name}.*").
-          select('LEAST(valid_to, now()::timestamp) AS as_of_time').
+      def of(object)
+        now = 'LEAST(valid_to, now()::timestamp)'
+        readonly.
+          select("#{table_name}.*, #{now} AS as_of_time").
+          order("#{table_name}.recorded_at, hid").
           where(:id => object)
       end
 
-      # Returns this table name in the +Adapter::HISTORY_SCHEMA+
-      #
-      def history_table_name
-        [Adapter::HISTORY_SCHEMA, table_name].join('.')
-      end
 
       # Returns an Array of unique UTC timestamps for which at least an
       # history record exists. Takes temporal associations into account.
       #
-      def history_timestamps
+      def timestamps
         assocs = reflect_on_all_associations.select {|a|
-          [:has_one, :has_many].include?(a.macro) && a.klass.chrono?
+          [:belongs_to, :has_one, :has_many].include?(a.macro) && a.klass.chrono?
         }
 
-        models = [self].concat(assocs.map(&:klass))
+        models = [self].concat(assocs.map {|a| a.klass.history})
         fields = models.inject([]) {|a,m| a.concat m.quoted_history_fields}
 
         relation = self.
@@ -140,14 +223,14 @@ module ChronoModel
         sql.gsub! 'INNER JOIN', 'LEFT OUTER JOIN'
 
         connection.on_schema(Adapter::HISTORY_SCHEMA) do
-          connection.select_values(sql, "#{self.name} history periods").map! do |ts|
+          connection.select_values(sql, "#{self.name} periods").map! do |ts|
             Conversions.string_to_utc_time ts
           end
         end
       end
 
       def quoted_history_fields
-        [:valid_from, :valid_to].map do |field|
+        @quoted_history_fields ||= [:valid_from, :valid_to].map do |field|
           [connection.quote_table_name(table_name),
            connection.quote_column_name(field)
           ].join('.')
@@ -162,7 +245,7 @@ module ChronoModel
           # Extract joined tables and add temporal WITH if appropriate
           arel.join_sources.map {|j| j.to_sql =~ /JOIN "(\w+)" ON/ && $1}.compact.each do |table|
             next unless (model = TimeMachine.chrono_models[table])
-            with(table, model.on_history(@temporal))
+            with(table, model.history.at(@temporal))
           end if @temporal
 
         end

data/lib/chrono_model/version.rb

@@ -1,3 +1,3 @@
 module ChronoModel
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

data/spec/support/helpers.rb

@@ -64,6 +64,11 @@ module ChronoTest::Helpers
             t.string     :name
             t.references :bar
           end
+
+          adapter.create_table 'defoos', :temporal => true do |t|
+            t.string  :name
+            t.boolean :active
+          end
         end
 
         after(:all) do
@@ -90,6 +95,12 @@ module ChronoTest::Helpers
         class ::Baz < ActiveRecord::Base
           belongs_to :baz
         end
+
+        class ::Defoo < ActiveRecord::Base
+          include ChronoModel::TimeMachine
+
+          default_scope where(:active => true)
+        end
       }
 
       def define_models!

data/spec/time_machine_spec.rb

@@ -10,7 +10,7 @@ describe ChronoModel::TimeMachine do
   describe '.chrono_models' do
     subject { ChronoModel::TimeMachine.chrono_models }
 
-    it { should == {'foos' => Foo, 'bars' => Bar} }
+    it { should == {'foos' => Foo::History, 'defoos' => Defoo::History, 'bars' => Bar::History} }
   end
 
 
@@ -88,6 +88,28 @@ describe ChronoModel::TimeMachine do
     it 'raises RecordNotFound when no history records are found' do
       expect { foo.as_of(1.minute.ago) }.to raise_error
     end
+
+    describe 'it honors default_scopes' do
+      let!(:active) {
+        active = ts_eval { Defoo.create! :name => 'active 1', :active => true }
+        ts_eval(active) { update_attributes! :name => 'active 2' }
+      }
+
+      let!(:hidden) {
+        hidden = ts_eval { Defoo.create! :name => 'hidden 1', :active => false }
+        ts_eval(hidden) { update_attributes! :name => 'hidden 2' }
+      }
+
+      it { Defoo.as_of(active.ts[0]).map(&:name).should == ['active 1'] }
+      it { Defoo.as_of(active.ts[1]).map(&:name).should == ['active 2'] }
+      it { Defoo.as_of(hidden.ts[0]).map(&:name).should == ['active 2'] }
+      it { Defoo.as_of(hidden.ts[1]).map(&:name).should == ['active 2'] }
+
+      it { Defoo.unscoped.as_of(active.ts[0]).map(&:name).should == ['active 1'] }
+      it { Defoo.unscoped.as_of(active.ts[1]).map(&:name).should == ['active 2'] }
+      it { Defoo.unscoped.as_of(hidden.ts[0]).map(&:name).should == ['active 2', 'hidden 1'] }
+      it { Defoo.unscoped.as_of(hidden.ts[1]).map(&:name).should == ['active 2', 'hidden 2'] }
+    end
   end
 
   describe '#history' do
@@ -194,21 +216,19 @@ describe ChronoModel::TimeMachine do
     describe 'on records having a :belongs_to relationship' do
       subject { bar.history_timestamps }
 
-      describe 'returns timestamps of the record only' do
-        its(:size) { should == bar.ts.size }
-        it { should == timestamps_from.call(bar) }
+      describe 'returns timestamps of the record and its associations' do
+        its(:size) { should == foo.ts.size + bar.ts.size }
+        it { should == timestamps_from.call(foo, bar) }
       end
     end
   end
 
   context do
-    history_attrs = ChronoModel::TimeMachine::HISTORY_ATTRIBUTES
-
     let!(:history) { foo.history.first }
     let!(:current) { foo }
 
-    history_attrs.each do |attr|
-      describe ['#', attr].join do
+    spec = lambda {|attr|
+      return lambda {|*|
         describe 'on history records' do
           subject { history.public_send(attr) }
 
@@ -219,23 +239,13 @@ describe ChronoModel::TimeMachine do
 
         describe 'on current records' do
           subject { current.public_send(attr) }
-          it { should be_nil }
-        end
-      end
-    end
-
-    describe '#initialize_dup' do
-      describe 'on history records' do
-        subject { history.dup }
-
-        history_attrs.each do |attr|
-          its(attr) { should be_nil }
+          it { expect { subject }.to raise_error(NoMethodError) }
         end
+      }
+    }
 
-        it { should_not be_readonly }
-        it { should be_new_record }
-
-      end
+    %w( valid_from valid_to recorded_at as_of_time ).each do |attr|
+      describe ['#', attr].join, &spec.call(attr)
     end
   end
 
@@ -291,8 +301,8 @@ describe ChronoModel::TimeMachine do
         ['bar', 'foo bar', 'bar bar', 'new bar', 'bar 0', 'bar 1']
       }
 
-      it { Foo.history.map(&:name).should == foo_history }
-      it { Bar.history.map(&:name).should == bar_history }
+      it { Foo.history.all.map(&:name).should == foo_history }
+      it { Bar.history.all.map(&:name).should == bar_history }
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chrono_model
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-06-22 00:00:00.000000000 Z
+date: 2012-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
-  requirement: &79509780 !ruby/object:Gem::Requirement
+  requirement: &70658630 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: '3.2'
   type: :runtime
   prerelease: false
-  version_requirements: *79509780
+  version_requirements: *70658630
 - !ruby/object:Gem::Dependency
   name: pg
-  requirement: &79509350 !ruby/object:Gem::Requirement
+  requirement: &70658260 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,7 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *79509350
+  version_requirements: *70658260
 description: Give your models as-of date temporal extensions. Built entirely for PostgreSQL
   >= 9.0
 email:
@@ -44,6 +44,7 @@ files:
 - .gitignore
 - .rspec
 - Gemfile
+- Gemfile.lock
 - LICENSE
 - README.md
 - README.sql