chrono_model 0.3.0

data/lib/chrono_model/compatibility.rb

@@ -0,0 +1,31 @@
+require 'active_record'
+
+module ChronoModel
+
+  # Utility methods added to every ActiveRecord::Base class instance
+  # to check whether ChronoModel is supported and whether a model is
+  # backed by temporal tables or not.
+  #
+  module Compatibility
+    extend ActiveSupport::Concern
+
+    # Returns true if this model is backed by a temporal table,
+    # false otherwise.
+    #
+    def chrono?
+      supports_chrono? && connection.is_chrono?(table_name)
+    end
+
+    # Returns true whether the connection adapter supports our
+    # implementation of temporal tables. Currently, only the
+    # PostgreSQL adapter is supported.
+    #
+    def supports_chrono?
+      connection.respond_to?(:chrono_supported?) &&
+        connection.chrono_supported?
+    end
+  end
+
+end
+
+ActiveRecord::Base.extend ChronoModel::Compatibility

data/lib/chrono_model/patches.rb

@@ -0,0 +1,104 @@
+require 'active_record'
+
+module ChronoModel
+  module Patches
+
+    # Patches ActiveRecord::Associations::Association to add support for
+    # temporal associations.
+    #
+    # Each record fetched from the +as_of+ scope on the owner class will have
+    # an additional "as_of_time" field yielding the UTC time of the request,
+    # then the as_of scope is called on either this association's class or
+    # on the join model's (:through association) one.
+    #
+    class Association < ActiveRecord::Associations::Association
+
+      # Add temporal Common Table Expressions (WITH queries) to the resulting
+      # scope, checking whether either the association class or the through
+      # association one are ChronoModels.
+      def scoped
+        return super unless _chrono_record?
+
+        ctes = {}
+
+        if reflection.klass.chrono?
+          ctes.update _chrono_ctes_for(reflection.klass)
+        end
+
+        if respond_to?(:through_reflection) && through_reflection.klass.chrono?
+          ctes.update _chrono_ctes_for(through_reflection.klass)
+        end
+
+        scoped = super
+        ctes.each {|table, cte| scoped = scoped.with(table, cte) }
+        return scoped.readonly
+      end
+
+      private
+        def _chrono_ctes_for(klass)
+          klass.as_of(owner.as_of_time).with_values
+        end
+
+        def _chrono_record?
+          owner.respond_to?(:as_of_time) && owner.as_of_time.present?
+        end
+    end
+
+    # Adds the WITH queries (Common Table Expressions) support to
+    # ActiveRecord::Relation.
+    #
+    # \name  is the CTE you want
+    # \value can be a plain SQL query or another AR::Relation
+    #
+    # Example:
+    #
+    #   Post.with('posts',
+    #     Post.from('history.posts').
+    #       where('? BETWEEN valid_from AND valid_to', 1.month.ago)
+    #   ).where(:author_id => 1)
+    #
+    # yields:
+    #
+    #   WITH posts AS (
+    #     SELECT * FROM history.posts WHERE ... BETWEEN valid_from AND valid_to
+    #   ) SELECT * FROM posts
+    #
+    # PG Documentation:
+    # http://www.postgresql.org/docs/9.0/static/queries-with.html
+    #
+    module QueryMethods
+      attr_accessor :with_values
+
+      def with(name, value)
+        clone.tap do |relation|
+          relation.with_values ||= {}
+          value = value.to_sql if value.respond_to? :to_sql
+          relation.with_values[name] = value
+        end
+      end
+
+      def build_arel
+        super.tap {|arel| arel.with with_values if with_values.present? }
+      end
+    end
+
+    module Querying
+      delegate :with, :to => :scoped
+    end
+
+    # Fixes ARel's WITH visitor method with the correct SQL syntax
+    #
+    # FIXME: the .children.first is messy. This should be properly
+    # fixed in ARel.
+    #
+    class Visitor < Arel::Visitors::PostgreSQL
+      def visit_Arel_Nodes_With o
+        values = o.children.first.map do |name, value|
+          [name, ' AS (', value.is_a?(String) ? value : visit(value), ')'].join
+        end
+        "WITH #{values.join ', '}"
+      end
+    end
+
+  end
+end

data/lib/chrono_model/railtie.rb

@@ -0,0 +1,41 @@
+module ChronoModel
+  class Railtie < ::Rails::Railtie
+    rake_tasks do
+
+      namespace :db do
+        namespace :chrono do
+          task :create_schemas do
+            ActiveRecord::Base.connection.chrono_create_schemas!
+          end
+        end
+      end
+
+      task 'db:schema:load' => 'db:chrono:create_schemas'
+    end
+
+    class SchemaDumper < ::ActiveRecord::SchemaDumper
+      def tables(*)
+        super
+        @connection.send(:_on_temporal_schema) { super }
+      end
+
+      def indexes(table, stream)
+        super
+        if @connection.is_chrono?(table)
+          stream.rewind
+          t = stream.read.sub(':force => true', '\&, :temporal => true') # HACK
+          stream.seek(0)
+          stream.truncate(0)
+          stream.write(t)
+        end
+      end
+
+    end
+
+    # I'm getting (too) used to this (dirty) override scheme.
+    #
+    silence_warnings do
+      ::ActiveRecord::SchemaDumper = SchemaDumper
+    end
+  end
+end

data/lib/chrono_model/time_machine.rb

@@ -0,0 +1,214 @@
+require 'active_record'
+
+module ChronoModel
+
+  module TimeMachine
+    extend ActiveSupport::Concern
+
+    included do
+      unless supports_chrono?
+        raise Error, "Your database server is not supported by ChronoModel. "\
+          "Currently, only PostgreSQL >= 9.0 is supported."
+      end
+
+      unless 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
+    end
+
+    # Returns an Hash keyed by table name of models that included
+    # ChronoModel::TimeMachine
+    #
+    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
+
+    # Return the complete read-only history of this instance.
+    #
+    def history
+      self.class.history_of(self)
+    end
+
+    # Aborts the destroy if this is an historical record
+    #
+    def destroy
+      if historical?
+        raise ActiveRecord::ReadOnlyRecord, 'Cannot delete historical records'
+      else
+        super
+      end
+    end
+
+    # Returns true if this record was fetched from history
+    #
+    def historical?
+      attributes.key?('hid')
+    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]) }
+    end
+
+    # Strips the history timestamps when duplicating history records
+    #
+    def initialize_dup(other)
+      super
+
+      if historical?
+        HISTORY_ATTRIBUTES.each {|attr| @attributes.delete(attr)}
+        @attributes.delete 'hid'
+        @readonly = false
+        @new_record = true
+      end
+    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|
+        query.where(:id => self)
+      end
+    end
+
+    module ClassMethods
+      # Fetches as of +time+ records.
+      #
+      def as_of(time)
+        time = Conversions.time_to_utc_string(time.utc)
+
+        readonly.with(table_name, on_history(time)).tap do |relation|
+          relation.instance_variable_set(:@temporal, time)
+        end
+      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")
+      end
+
+      # Returns the whole history as read only.
+      #
+      def history
+        readonly.from(history_table_name).order("#{history_table_name}.recorded_at")
+      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').
+          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
+        assocs = reflect_on_all_associations.select {|a|
+          [:has_one, :has_many].include?(a.macro) && a.klass.chrono?
+        }
+
+        models = [self].concat(assocs.map(&:klass))
+        fields = models.inject([]) {|a,m| a.concat m.quoted_history_fields}
+
+        relation = self.
+          joins(*assocs.map(&:name)).
+          select("DISTINCT UNNEST(ARRAY[#{fields.join(',')}]) AS ts").
+          order('ts')
+
+        relation = yield relation if block_given?
+
+        sql = "SELECT ts FROM ( #{relation.to_sql} ) foo WHERE ts IS NOT NULL AND ts < NOW()"
+        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|
+            Conversions.string_to_utc_time ts
+          end
+        end
+      end
+
+      def quoted_history_fields
+        [:valid_from, :valid_to].map do |field|
+          [connection.quote_table_name(table_name),
+           connection.quote_column_name(field)
+          ].join('.')
+        end
+      end
+    end
+
+    module QueryMethods
+      def build_arel
+        super.tap do |arel|
+
+          # 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))
+          end if @temporal
+
+        end
+      end
+    end
+    ActiveRecord::Relation.instance_eval { include QueryMethods }
+
+    module Conversions
+      extend self
+
+      ISO_DATETIME = /\A(\d{4})-(\d\d)-(\d\d) (\d\d):(\d\d):(\d\d)(\.\d+)?\z/
+
+      def string_to_utc_time(string)
+        if string =~ ISO_DATETIME
+          microsec = ($7.to_f * 1_000_000).to_i
+          Time.utc $1.to_i, $2.to_i, $3.to_i, $4.to_i, $5.to_i, $6.to_i, microsec
+        end
+      end
+
+      def time_to_utc_string(time)
+        [time.to_s(:db), sprintf('%06d', time.usec)].join '.'
+      end
+    end
+
+    module Utilities
+      # Amends the given history item setting a different period.
+      # Useful when migrating from legacy systems, but it is here
+      # as this is not a proper API.
+      #
+      # Extend your model with the Utilities model if you want to
+      # use it.
+      #
+      def amend_history_period!(hid, from, to)
+        unless [from, to].all? {|ts| ts.respond_to?(:zone) && ts.zone == 'UTC'}
+          raise 'Can amend history only with UTC timestamps'
+        end
+
+        connection.execute %[
+          UPDATE #{history_table_name}
+             SET valid_from = #{connection.quote(from)},
+                 valid_to   = #{connection.quote(to  )}
+           WHERE hid = #{hid.to_i}
+        ]
+      end
+    end
+
+  end
+
+end

data/lib/chrono_model/version.rb

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

data/spec/adapter_spec.rb

@@ -0,0 +1,398 @@
+require 'spec_helper'
+require 'support/helpers'
+
+shared_examples_for 'temporal table' do
+  it { adapter.is_chrono?(subject).should be_true }
+
+  it { should_not have_public_backing }
+
+  it { should have_temporal_backing }
+  it { should have_history_backing }
+  it { should have_history_extra_columns }
+  it { should have_public_interface }
+
+  it { should have_columns(columns) }
+  it { should have_temporal_columns(columns) }
+  it { should have_history_columns(columns) }
+end
+
+shared_examples_for 'plain table' do
+  it { adapter.is_chrono?(subject).should be_false }
+
+  it { should have_public_backing }
+
+  it { should_not have_temporal_backing }
+  it { should_not have_history_backing }
+  it { should_not have_public_interface }
+
+  it { should have_columns(columns) }
+end
+
+describe ChronoModel::Adapter do
+  include ChronoTest::Helpers::Adapter
+
+  context do
+    subject { adapter }
+    it { should be_a_kind_of(ChronoModel::Adapter) }
+
+    context do
+      before { adapter.stub(:postgresql_version => 90000) }
+      it { should be_chrono_supported }
+    end
+
+    context do
+      before { adapter.stub(:postgresql_version => 80400) }
+      it { should_not be_chrono_supported }
+    end
+  end
+
+  let(:table) { 'test_table' }
+  subject { table }
+
+  columns do
+    native = [
+      ['test', 'character varying(255)'],
+      ['foo',  'integer'],
+      ['bar',  'double precision'],
+      ['baz',  'text']
+    ]
+
+    def native.to_proc
+      proc {|t|
+        t.string  :test
+        t.integer :foo
+        t.float   :bar
+        t.text    :baz
+      }
+    end
+
+    native
+  end
+
+  describe '.create_table' do
+    with_temporal_table do
+      it_should_behave_like 'temporal table'
+    end
+
+    with_plain_table do
+      it_should_behave_like 'plain table'
+    end
+  end
+
+  describe '.rename_table' do
+    let(:table)   { 'test_table' }
+    let(:renamed) { 'foo_table'  }
+    subject { renamed }
+
+    context ':temporal => true' do
+      before :all do
+        adapter.create_table table, :temporal => true, &columns
+
+        adapter.rename_table table, renamed
+      end
+      after(:all) { adapter.drop_table(renamed) }
+
+      it_should_behave_like 'temporal table'
+    end
+
+    context ':temporal => false' do
+      before :all do
+        adapter.create_table table, :temporal => false, &columns
+
+        adapter.rename_table table, renamed
+      end
+      after(:all) { adapter.drop_table(renamed) }
+
+      it_should_behave_like 'plain table'
+    end
+  end
+
+  describe '.change_table' do
+    with_temporal_table do
+      before :all do
+        adapter.change_table table, :temporal => false
+      end
+
+      it_should_behave_like 'plain table'
+    end
+
+    with_plain_table do
+      before :all do
+        adapter.change_table table, :temporal => true
+      end
+
+      it_should_behave_like 'temporal table'
+    end
+  end
+
+  describe '.drop_table' do
+    before :all do
+      adapter.create_table table, :temporal => true, &columns
+
+      adapter.drop_table table
+    end
+
+    it { should_not have_public_backing }
+    it { should_not have_temporal_backing }
+    it { should_not have_history_backing }
+    it { should_not have_public_interface }
+  end
+
+  describe '.add_index' do
+    with_temporal_table do
+      before :all do
+        adapter.add_index table, [:foo, :bar], :name => 'foobar_index'
+        adapter.add_index table, [:test],      :name => 'test_index'
+      end
+
+      it { should have_temporal_index 'foobar_index', %w( foo bar ) }
+      it { should have_history_index  'foobar_index', %w( foo bar ) }
+      it { should have_temporal_index 'test_index',   %w( test ) }
+      it { should have_history_index  'test_index',   %w( test ) }
+
+      it { should_not have_index 'foobar_index', %w( foo bar ) }
+      it { should_not have_index 'test_index',   %w( test ) }
+    end
+
+    with_plain_table do
+      before :all do
+        adapter.add_index table, [:foo, :bar], :name => 'foobar_index'
+        adapter.add_index table, [:test],      :name => 'test_index'
+      end
+
+      it { should_not have_temporal_index 'foobar_index', %w( foo bar ) }
+      it { should_not have_history_index  'foobar_index', %w( foo bar ) }
+      it { should_not have_temporal_index 'test_index',   %w( test ) }
+      it { should_not have_history_index  'test_index',   %w( test ) }
+
+      it { should have_index 'foobar_index', %w( foo bar ) }
+      it { should have_index 'test_index',   %w( test ) }
+    end
+  end
+
+  describe '.remove_index' do
+    with_temporal_table do
+      before :all do
+        adapter.add_index table, [:foo, :bar], :name => 'foobar_index'
+        adapter.add_index table, [:test],      :name => 'test_index'
+
+        adapter.remove_index table, :name => 'test_index'
+      end
+
+      it { should_not have_temporal_index 'test_index', %w( test ) }
+      it { should_not have_history_index  'test_index', %w( test ) }
+      it { should_not have_index          'test_index', %w( test ) }
+    end
+
+    with_plain_table do
+      before :all do
+        adapter.add_index table, [:foo, :bar], :name => 'foobar_index'
+        adapter.add_index table, [:test],      :name => 'test_index'
+
+        adapter.remove_index table, :name => 'test_index'
+      end
+
+      it { should_not have_temporal_index 'test_index', %w( test ) }
+      it { should_not have_history_index  'test_index', %w( test ) }
+      it { should_not have_index          'test_index', %w( test ) }
+    end
+  end
+
+  describe '.add_column' do
+    let(:extra_columns) { [['foobarbaz', 'integer']] }
+
+    with_temporal_table do
+      before :all do
+        adapter.add_column table, :foobarbaz, :integer
+      end
+
+      it { should have_columns(extra_columns) }
+      it { should have_temporal_columns(extra_columns) }
+      it { should have_history_columns(extra_columns) }
+    end
+
+    with_plain_table do
+      before :all do
+        adapter.add_column table, :foobarbaz, :integer
+      end
+
+      it { should have_columns(extra_columns) }
+    end
+  end
+
+  describe '.remove_column' do
+    let(:resulting_columns) { columns.reject {|c,_| c == 'foo'} }
+
+    with_temporal_table do
+      before :all do
+        adapter.remove_column table, :foo
+      end
+
+      it { should have_columns(resulting_columns) }
+      it { should have_temporal_columns(resulting_columns) }
+      it { should have_history_columns(resulting_columns) }
+
+      it { should_not have_columns([['foo', 'integer']]) }
+      it { should_not have_temporal_columns([['foo', 'integer']]) }
+      it { should_not have_history_columns([['foo', 'integer']]) }
+    end
+
+    with_plain_table do
+      before :all do
+        adapter.remove_column table, :foo
+      end
+
+      it { should have_columns(resulting_columns) }
+      it { should_not have_columns([['foo', 'integer']]) }
+    end
+  end
+
+  describe '.rename_column' do
+    with_temporal_table do
+      before :all do
+        adapter.rename_column table, :foo, :taratapiatapioca
+      end
+
+      it { should_not have_columns([['foo', 'integer']]) }
+      it { should_not have_temporal_columns([['foo', 'integer']]) }
+      it { should_not have_history_columns([['foo', 'integer']]) }
+
+      it { should have_columns([['taratapiatapioca', 'integer']]) }
+      it { should have_temporal_columns([['taratapiatapioca', 'integer']]) }
+      it { should have_history_columns([['taratapiatapioca', 'integer']]) }
+    end
+
+    with_plain_table do
+      before :all do
+        adapter.rename_column table, :foo, :taratapiatapioca
+      end
+
+      it { should_not have_columns([['foo', 'integer']]) }
+      it { should have_columns([['taratapiatapioca', 'integer']]) }
+    end
+  end
+
+  describe '.change_column' do
+    with_temporal_table do
+      before :all do
+        adapter.change_column table, :foo, :float
+      end
+
+      it { should_not have_columns([['foo', 'integer']]) }
+      it { should_not have_temporal_columns([['foo', 'integer']]) }
+      it { should_not have_history_columns([['foo', 'integer']]) }
+
+      it { should have_columns([['foo', 'double precision']]) }
+      it { should have_temporal_columns([['foo', 'double precision']]) }
+      it { should have_history_columns([['foo', 'double precision']]) }
+    end
+
+    with_plain_table do
+      before(:all) do
+        adapter.change_column table, :foo, :float
+      end
+
+      it { should_not have_columns([['foo', 'integer']]) }
+      it { should have_columns([['foo', 'double precision']]) }
+    end
+  end
+
+  describe '.remove_column' do
+    with_temporal_table do
+      before :all do
+        adapter.remove_column table, :foo
+      end
+
+      it { should_not have_columns([['foo', 'integer']]) }
+      it { should_not have_temporal_columns([['foo', 'integer']]) }
+      it { should_not have_history_columns([['foo', 'integer']]) }
+    end
+
+    with_plain_table do
+      before :all do
+        adapter.remove_column table, :foo
+      end
+
+      it { should_not have_columns([['foo', 'integer']]) }
+    end
+  end
+
+  describe '.column_definitions' do
+    subject { adapter.column_definitions(table).map {|d| d.take(2)} }
+
+    assert = proc do
+      it { (subject & columns).should == columns }
+      it { should include(['id', 'integer']) }
+    end
+
+    with_temporal_table &assert
+    with_plain_table    &assert
+  end
+
+  describe '.primary_key' do
+    subject { adapter.primary_key(table) }
+
+    assert = proc do
+      it { should == 'id' }
+    end
+
+    with_temporal_table &assert
+    with_plain_table    &assert
+  end
+
+  describe '.indexes' do
+    subject { adapter.indexes(table) }
+
+    assert = proc do
+      before(:all) do
+        adapter.add_index table, :foo,         :name => 'foo_index'
+        adapter.add_index table, [:bar, :baz], :name => 'bar_index'
+      end
+
+      it { subject.map(&:name).should =~ %w( foo_index bar_index ) }
+      it { subject.map(&:columns).should =~ [['foo'], ['bar', 'baz']] }
+    end
+
+    with_temporal_table &assert
+    with_plain_table    &assert
+  end
+
+  describe '.on_schema' do
+    before(:all) do
+      5.times {|i| adapter.execute "CREATE SCHEMA test_#{i}"}
+    end
+
+    context 'with nesting' do
+
+      it 'saves the schema at each recursion' do
+        should be_in_schema(:default)
+
+        adapter.on_schema('test_1') { should be_in_schema('test_1')
+          adapter.on_schema('test_2') { should be_in_schema('test_2')
+            adapter.on_schema('test_3') { should be_in_schema('test_3')
+            }
+            should be_in_schema('test_2')
+          }
+          should be_in_schema('test_1')
+        }
+
+        should be_in_schema(:default)
+      end
+
+    end
+
+    context 'without nesting' do
+      it 'ignores recursive calls' do
+        should be_in_schema(:default)
+
+        adapter.on_schema('test_1', false) { should be_in_schema('test_1')
+          adapter.on_schema('test_2', false) { should be_in_schema('test_1')
+            adapter.on_schema('test_3', false) { should be_in_schema('test_1')
+        } } }
+
+        should be_in_schema(:default)
+      end
+    end
+  end
+
+end