chrono_model 1.0.1 → 1.1.0

data/lib/chrono_model/adapter/ddl.rb

@@ -0,0 +1,225 @@
+require 'multi_json'
+
+module ChronoModel
+  class Adapter < ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
+
+    module DDL
+      private
+        # Create the public view and its INSTEAD OF triggers
+        #
+        def chrono_public_view_ddl(table, options = nil)
+          pk      = primary_key(table)
+          current = [TEMPORAL_SCHEMA, table].join('.')
+          history = [HISTORY_SCHEMA,  table].join('.')
+
+          options ||= chrono_metadata_for(table)
+
+          # SELECT - return only current data
+          #
+          execute "DROP VIEW #{table}" if data_source_exists? table
+          execute "CREATE VIEW #{table} AS SELECT * FROM ONLY #{current}"
+
+          chrono_metadata_set(table, options.merge(chronomodel: VERSION))
+
+          # Set default values on the view (closes #12)
+          #
+          columns(table).each do |column|
+            default = if column.default.nil?
+              column.default_function
+            else
+              quote(column.default)
+            end
+
+            next if column.name == pk || default.nil?
+
+            execute "ALTER VIEW #{table} ALTER COLUMN #{quote_column_name(column.name)} SET DEFAULT #{default}"
+          end
+
+          columns = self.columns(table).map {|c| quote_column_name(c.name)}
+          columns.delete(quote_column_name(pk))
+
+          fields, values = columns.join(', '), columns.map {|c| "NEW.#{c}"}.join(', ')
+
+          chrono_create_INSERT_trigger(table, pk, current, history, fields, values)
+          chrono_create_UPDATE_trigger(table, pk, current, history, fields, values, options, columns)
+          chrono_create_DELETE_trigger(table, pk, current, history)
+        end
+
+        # Create the history table in the history schema
+        def chrono_history_table_ddl(table)
+          parent = "#{TEMPORAL_SCHEMA}.#{table}"
+          p_pkey = primary_key(parent)
+
+          execute <<-SQL
+            CREATE TABLE #{table} (
+              hid         SERIAL PRIMARY KEY,
+              validity    tsrange NOT NULL,
+              recorded_at timestamp NOT NULL DEFAULT timezone('UTC', now())
+            ) INHERITS ( #{parent} )
+          SQL
+
+          add_history_validity_constraint(table, p_pkey)
+
+          chrono_create_history_indexes_for(table, p_pkey)
+        end
+
+        def add_history_validity_constraint(table, pkey)
+          add_timeline_consistency_constraint(table, :validity, id: pkey, on_current_schema: true)
+        end
+
+        def remove_history_validity_constraint(table, options = {})
+          remove_timeline_consistency_constraint(table, options.merge(on_current_schema: true))
+        end
+
+        # INSERT - insert data both in the temporal table and in the history one.
+        #
+        # The serial sequence is invoked manually only if the PK is NULL, to
+        # allow setting the PK to a specific value (think migration scenario).
+        #
+        def chrono_create_INSERT_trigger(table, pk, current, history, fields, values)
+          seq = serial_sequence(current, pk)
+
+          execute <<-SQL
+            CREATE OR REPLACE FUNCTION chronomodel_#{table}_insert() RETURNS TRIGGER AS $$
+              BEGIN
+                IF NEW.#{pk} IS NULL THEN
+                  NEW.#{pk} := nextval('#{seq}');
+                END IF;
+
+                INSERT INTO #{current} ( #{pk}, #{fields} )
+                VALUES ( NEW.#{pk}, #{values} );
+
+                INSERT INTO #{history} ( #{pk}, #{fields}, validity )
+                VALUES ( NEW.#{pk}, #{values}, tsrange(timezone('UTC', now()), NULL) );
+
+                RETURN NEW;
+              END;
+            $$ LANGUAGE plpgsql;
+
+            DROP TRIGGER IF EXISTS chronomodel_insert ON #{table};
+
+            CREATE TRIGGER chronomodel_insert INSTEAD OF INSERT ON #{table}
+              FOR EACH ROW EXECUTE PROCEDURE chronomodel_#{table}_insert();
+          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.
+        #
+        # If there are no changes, this trigger suppresses redundant updates.
+        #
+        # If a row in the history with the current ID and current timestamp already
+        # exists, update it with new data. This logic makes possible to "squash"
+        # together changes made in a transaction in a single history row.
+        #
+        # If you want to disable this behaviour, set the CHRONOMODEL_NO_SQUASH
+        # environment variable. This is useful when running scenarios inside
+        # cucumber, in which everything runs in the same transaction.
+        #
+        def chrono_create_UPDATE_trigger(table, pk, current, history, fields, values, options, columns)
+          # Columns to be journaled. By default everything except updated_at (GH #7)
+          #
+          journal = if options[:journal]
+            options[:journal].map {|col| quote_column_name(col)}
+
+          elsif options[:no_journal]
+            columns - options[:no_journal].map {|col| quote_column_name(col)}
+
+          elsif options[:full_journal]
+            columns
+
+          else
+            columns - [ quote_column_name('updated_at') ]
+          end
+
+          journal &= columns
+
+          execute <<-SQL
+            CREATE OR REPLACE FUNCTION chronomodel_#{table}_update() RETURNS TRIGGER AS $$
+              DECLARE _now timestamp;
+              DECLARE _hid integer;
+              DECLARE _old record;
+              DECLARE _new record;
+              BEGIN
+                IF OLD IS NOT DISTINCT FROM NEW THEN
+                  RETURN NULL;
+                END IF;
+
+                _old := row(#{journal.map {|c| "OLD.#{c}" }.join(', ')});
+                _new := row(#{journal.map {|c| "NEW.#{c}" }.join(', ')});
+
+                IF _old IS NOT DISTINCT FROM _new THEN
+                  UPDATE ONLY #{current} SET ( #{fields} ) = ( #{values} ) WHERE #{pk} = OLD.#{pk};
+                  RETURN NEW;
+                END IF;
+
+                _now := timezone('UTC', now());
+                _hid := NULL;
+
+                #{"SELECT hid INTO _hid FROM #{history} WHERE #{pk} = OLD.#{pk} AND lower(validity) = _now;" unless ENV['CHRONOMODEL_NO_SQUASH']}
+
+                IF _hid IS NOT NULL THEN
+                  UPDATE #{history} SET ( #{fields} ) = ( #{values} ) WHERE hid = _hid;
+                ELSE
+                  UPDATE #{history} SET validity = tsrange(lower(validity), _now)
+                  WHERE #{pk} = OLD.#{pk} AND upper_inf(validity);
+
+                  INSERT INTO #{history} ( #{pk}, #{fields}, validity )
+                       VALUES ( OLD.#{pk}, #{values}, tsrange(_now, NULL) );
+                END IF;
+
+                UPDATE ONLY #{current} SET ( #{fields} ) = ( #{values} ) WHERE #{pk} = OLD.#{pk};
+
+                RETURN NEW;
+              END;
+            $$ LANGUAGE plpgsql;
+
+            DROP TRIGGER IF EXISTS chronomodel_update ON #{table};
+
+            CREATE TRIGGER chronomodel_update INSTEAD OF UPDATE ON #{table}
+              FOR EACH ROW EXECUTE PROCEDURE chronomodel_#{table}_update();
+          SQL
+        end
+
+        # DELETE - save the current data in the history and eventually delete the
+        # data from the temporal table.
+        # The first DELETE is required to remove history for records INSERTed and
+        # DELETEd in the same transaction.
+        #
+        def chrono_create_DELETE_trigger(table, pk, current, history)
+          execute <<-SQL
+            CREATE OR REPLACE FUNCTION chronomodel_#{table}_delete() RETURNS TRIGGER AS $$
+              DECLARE _now timestamp;
+              BEGIN
+                _now := timezone('UTC', now());
+
+                DELETE FROM #{history}
+                WHERE #{pk} = old.#{pk} AND validity = tsrange(_now, NULL);
+
+                UPDATE #{history} SET validity = tsrange(lower(validity), _now)
+                WHERE #{pk} = old.#{pk} AND upper_inf(validity);
+
+                DELETE FROM ONLY #{current}
+                WHERE #{pk} = old.#{pk};
+
+                RETURN OLD;
+              END;
+            $$ LANGUAGE plpgsql;
+
+            DROP TRIGGER IF EXISTS chronomodel_delete ON #{table};
+
+            CREATE TRIGGER chronomodel_delete INSTEAD OF DELETE ON #{table}
+              FOR EACH ROW EXECUTE PROCEDURE chronomodel_#{table}_delete();
+          SQL
+        end
+
+        def chrono_drop_trigger_functions_for(table_name)
+          %w( insert update delete ).each do |func|
+            execute "DROP FUNCTION IF EXISTS chronomodel_#{table_name}_#{func}()"
+          end
+        end
+      # private
+    end
+
+  end
+end

data/lib/chrono_model/adapter/indexes.rb

@@ -0,0 +1,194 @@
+module ChronoModel
+  class Adapter < ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
+
+    module Indexes
+      # Create temporal indexes for timestamp search.
+      #
+      # This index is used by +TimeMachine.at+, `.current` and `.past` to
+      # build the temporal WHERE clauses that fetch the state of records at
+      # a single point in time.
+      #
+      # Parameters:
+      #
+      #   `table`: the table where to create indexes on
+      #   `range`: the tsrange field
+      #
+      # Options:
+      #
+      #   `:name`: the index name prefix, defaults to
+      #            index_{table}_temporal_on_{range / lower_range / upper_range}
+      #
+      def add_temporal_indexes(table, range, options = {})
+        range_idx, lower_idx, upper_idx =
+          temporal_index_names(table, range, options)
+
+        chrono_alter_index(table, options) do
+          execute <<-SQL
+            CREATE INDEX #{range_idx} ON #{table} USING gist ( #{range} )
+          SQL
+
+          # Indexes used for precise history filtering, sorting and, in history
+          # tables, by UPDATE / DELETE triggers.
+          #
+          execute "CREATE INDEX #{lower_idx} ON #{table} ( lower(#{range}) )"
+          execute "CREATE INDEX #{upper_idx} ON #{table} ( upper(#{range}) )"
+        end
+      end
+
+      def remove_temporal_indexes(table, range, options = {})
+        indexes = temporal_index_names(table, range, options)
+
+        chrono_alter_index(table, options) do
+          indexes.each {|idx| execute "DROP INDEX #{idx}" }
+        end
+      end
+
+      # Adds an EXCLUDE constraint to the given table, to assure that
+      # no more than one record can occupy a definite segment on a
+      # timeline.
+      #
+      def add_timeline_consistency_constraint(table, range, options = {})
+        name = timeline_consistency_constraint_name(table)
+        id   = options[:id] || primary_key(table)
+
+        chrono_alter_constraint(table, options) do
+          execute <<-SQL
+            ALTER TABLE #{table} ADD CONSTRAINT #{name}
+              EXCLUDE USING gist ( #{id} WITH =, #{range} WITH && )
+          SQL
+        end
+      end
+
+      def remove_timeline_consistency_constraint(table, options = {})
+        name = timeline_consistency_constraint_name(table)
+
+        chrono_alter_constraint(table, options) do
+          execute <<-SQL
+            ALTER TABLE #{table} DROP CONSTRAINT #{name}
+          SQL
+        end
+      end
+
+      def timeline_consistency_constraint_name(table)
+        "#{table}_timeline_consistency"
+      end
+
+      private
+        # Creates indexes for a newly made history table
+        #
+        def chrono_create_history_indexes_for(table, p_pkey)
+          add_temporal_indexes table, :validity, on_current_schema: true
+
+          execute "CREATE INDEX #{table}_inherit_pkey     ON #{table} ( #{p_pkey} )"
+          execute "CREATE INDEX #{table}_recorded_at      ON #{table} ( recorded_at )"
+          execute "CREATE INDEX #{table}_instance_history ON #{table} ( #{p_pkey}, recorded_at )"
+        end
+
+        # Rename indexes on history schema
+        #
+        def chrono_rename_history_indexes(name, new_name)
+          on_history_schema do
+            standard_index_names = %w(
+              inherit_pkey instance_history pkey
+              recorded_at timeline_consistency )
+
+            old_names = temporal_index_names(name, :validity) +
+              standard_index_names.map {|i| [name, i].join('_') }
+
+            new_names = temporal_index_names(new_name, :validity) +
+              standard_index_names.map {|i| [new_name, i].join('_') }
+
+            old_names.zip(new_names).each do |old, new|
+              execute "ALTER INDEX #{old} RENAME TO #{new}"
+            end
+          end
+        end
+
+        # Rename indexes on temporal schema
+        #
+        def chrono_rename_temporal_indexes(name, new_name)
+          on_temporal_schema do
+            temporal_indexes =  indexes(new_name)
+            temporal_indexes.map(&:name).each do |old_idx_name|
+              if old_idx_name =~ /^index_#{name}_on_(?<columns>.+)/
+                new_idx_name = "index_#{new_name}_on_#{$~['columns']}"
+                execute "ALTER INDEX #{old_idx_name} RENAME TO #{new_idx_name}"
+              end
+            end
+          end
+        end
+
+        # Copy the indexes from the temporal table to the history table
+        # if the indexes are not already created with the same name.
+        #
+        # Uniqueness is voluntarily ignored, as it doesn't make sense on
+        # history tables.
+        #
+        # Used in migrations.
+        #
+        # Ref: GitHub pull #21.
+        #
+        def chrono_copy_indexes_to_history(table_name)
+          history_indexes  = on_history_schema  { indexes(table_name) }.map(&:name)
+          temporal_indexes = on_temporal_schema { indexes(table_name) }
+
+          temporal_indexes.each do |index|
+            next if history_indexes.include?(index.name)
+
+            on_history_schema do
+              execute %[
+                CREATE INDEX #{index.name} ON #{table_name}
+                USING #{index.using} ( #{index.columns.join(', ')} )
+              ], 'Copy index from temporal to history'
+            end
+          end
+        end
+
+        # Returns a suitable index name on the given table and for the
+        # given range definition.
+        #
+        def temporal_index_names(table, range, options = {})
+          prefix = options[:name].presence || "index_#{table}_temporal"
+
+          # When creating computed indexes
+          #
+          # e.g. ends_on::timestamp + time '23:59:59'
+          #
+          # remove everything following the field name.
+          range = range.to_s.sub(/\W.*/, '')
+
+          [range, "lower_#{range}", "upper_#{range}"].map do |suffix|
+            [prefix, 'on', suffix].join('_')
+          end
+        end
+
+        # Generic alteration of history tables, where changes have to be
+        # propagated both on the temporal table and the history one.
+        #
+        # Internally, the :on_current_schema bypasses the +is_chrono?+
+        # check, as some temporal indexes and constraints are created
+        # only on the history table, and the creation methods already
+        # run scoped into the correct schema.
+        #
+        def chrono_alter_index(table_name, options)
+          if is_chrono?(table_name) && !options[:on_current_schema]
+            on_temporal_schema { yield }
+            on_history_schema { yield }
+          else
+            yield
+          end
+        end
+
+        def chrono_alter_constraint(table_name, options)
+          if is_chrono?(table_name) && !options[:on_current_schema]
+            on_temporal_schema { yield }
+          else
+            yield
+          end
+        end
+
+
+    end
+
+  end
+end

data/lib/chrono_model/adapter/migrations.rb

@@ -0,0 +1,282 @@
+module ChronoModel
+  class Adapter < ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
+
+    module Migrations
+      # Creates the given table, possibly creating the temporal schema
+      # objects if the `:temporal` option is given and set to true.
+      #
+      def create_table(table_name, options = {})
+        # No temporal features requested, skip
+        return super unless options[:temporal]
+
+        if options[:id] == false
+          logger.warn "ChronoModel: Temporal Temporal tables require a primary key."
+          logger.warn "ChronoModel: Adding a `__chrono_id' primary key to #{table_name} definition."
+
+          options[:id] = '__chrono_id'
+        end
+
+        transaction do
+          on_temporal_schema { super }
+          on_history_schema { chrono_history_table_ddl(table_name) }
+
+          chrono_public_view_ddl(table_name, options)
+        end
+      end
+
+      # If renaming a temporal table, rename the history and view as well.
+      #
+      def rename_table(name, new_name)
+        return super unless is_chrono?(name)
+
+        clear_cache!
+
+        transaction do
+          # Rename tables
+          #
+          on_temporal_schema { rename_table_and_pk(name, new_name) }
+          on_history_schema  { rename_table_and_pk(name, new_name) }
+
+          # Rename indexes
+          #
+          chrono_rename_history_indexes(name, new_name)
+          chrono_rename_temporal_indexes(name, new_name)
+
+          # Drop view
+          #
+          execute "DROP VIEW #{name}"
+
+          # Drop functions
+          #
+          chrono_drop_trigger_functions_for(name)
+
+          # Create view and functions
+          #
+          chrono_public_view_ddl(new_name)
+        end
+      end
+
+      # If changing a temporal table, redirect the change to the table in the
+      # temporal schema and recreate views.
+      #
+      # If the `:temporal` option is specified, enables or disables temporal
+      # features on the given table. Please note that you'll lose your history
+      # when demoting a temporal table to a plain one.
+      #
+      def change_table(table_name, options = {}, &block)
+        transaction do
+
+          # Add an empty proc to support calling change_table without a block.
+          #
+          block ||= proc { }
+
+          case options[:temporal]
+          when true
+            if !is_chrono?(table_name)
+              chrono_make_temporal_table(table_name, options)
+            end
+
+            drop_and_recreate_public_view(table_name, options) do
+              super table_name, options, &block
+            end
+
+          when false
+            if is_chrono?(table_name)
+              chrono_undo_temporal_table(table_name)
+            end
+
+            super table_name, options, &block
+          end
+
+        end
+      end
+
+      # If dropping a temporal table, drops it from the temporal schema
+      # adding the CASCADE option so to delete the history, view and triggers.
+      #
+      def drop_table(table_name, *)
+        return super unless is_chrono?(table_name)
+
+        on_temporal_schema { execute "DROP TABLE #{table_name} CASCADE" }
+
+        chrono_drop_trigger_functions_for(table_name)
+      end
+
+      # If adding an index to a temporal table, add it to the one in the
+      # temporal schema and to the history one. If the `:unique` option is
+      # present, it is removed from the index created in the history table.
+      #
+      def add_index(table_name, column_name, options = {})
+        return super unless is_chrono?(table_name)
+
+        transaction do
+          on_temporal_schema { super }
+
+          # Uniqueness constraints do not make sense in the history table
+          options = options.dup.tap {|o| o.delete(:unique)} if options[:unique].present?
+
+          on_history_schema { super table_name, column_name, options }
+        end
+      end
+
+      # If removing an index from a temporal table, remove it both from the
+      # temporal and the history schemas.
+      #
+      def remove_index(table_name, *)
+        return super unless is_chrono?(table_name)
+
+        transaction do
+          on_temporal_schema { super }
+          on_history_schema { super }
+        end
+      end
+
+      # If adding a column to a temporal table, creates it in the table in
+      # the temporal schema and updates the triggers.
+      #
+      def add_column(table_name, *)
+        return super unless is_chrono?(table_name)
+
+        transaction do
+          # Add the column to the temporal table
+          on_temporal_schema { super }
+
+          # Update the triggers
+          chrono_public_view_ddl(table_name)
+        end
+      end
+
+      # If renaming a column of a temporal table, rename it in the table in
+      # the temporal schema and update the triggers.
+      #
+      def rename_column(table_name, *)
+        return super unless is_chrono?(table_name)
+
+        # Rename the column in the temporal table and in the view
+        transaction do
+          on_temporal_schema { super }
+          super
+
+          # Update the triggers
+          chrono_public_view_ddl(table_name)
+        end
+      end
+
+      # If removing a column from a temporal table, we are forced to drop the
+      # view, then change the column from the table in the temporal schema and
+      # eventually recreate the triggers.
+      #
+      def change_column(table_name, *)
+        return super unless is_chrono?(table_name)
+        drop_and_recreate_public_view(table_name) { super }
+      end
+
+      # Change the default on the temporal schema table.
+      #
+      def change_column_default(table_name, *)
+        return super unless is_chrono?(table_name)
+        on_temporal_schema { super }
+      end
+
+      # Change the null constraint on the temporal schema table.
+      #
+      def change_column_null(table_name, *)
+        return super unless is_chrono?(table_name)
+        on_temporal_schema { super }
+      end
+
+      # If removing a column from a temporal table, we are forced to drop the
+      # view, then drop the column from the table in the temporal schema and
+      # eventually recreate the triggers.
+      #
+      def remove_column(table_name, *)
+        return super unless is_chrono?(table_name)
+        drop_and_recreate_public_view(table_name) { super }
+      end
+
+      private
+        # In destructive changes, such as removing columns or changing column
+        # types, the view must be dropped and recreated, while the change has
+        # to be applied to the table in the temporal schema.
+        #
+        def drop_and_recreate_public_view(table_name, opts = {})
+          transaction do
+            options = chrono_metadata_for(table_name).merge(opts)
+
+            execute "DROP VIEW #{table_name}"
+
+            on_temporal_schema { yield }
+
+            # Recreate the triggers
+            chrono_public_view_ddl(table_name, options)
+          end
+        end
+
+        def chrono_make_temporal_table(table_name, options)
+          # Add temporal features to this table
+          #
+          if !primary_key(table_name)
+            execute "ALTER TABLE #{table_name} ADD __chrono_id SERIAL PRIMARY KEY"
+          end
+
+          execute "ALTER TABLE #{table_name} SET SCHEMA #{TEMPORAL_SCHEMA}"
+          on_history_schema { chrono_history_table_ddl(table_name) }
+          chrono_public_view_ddl(table_name, options)
+          chrono_copy_indexes_to_history(table_name)
+
+          # Optionally copy the plain table data, setting up history
+          # retroactively.
+          #
+          if options[:copy_data]
+            chrono_copy_temporal_to_history(table_name, options)
+          end
+        end
+
+        def chrono_copy_temporal_to_history(table_name, options)
+          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,
+                tsrange('#{from}', NULL) AS validity,
+                timezone('UTC', now())   AS recorded_at
+              FROM #{TEMPORAL_SCHEMA}.#{table_name}
+          ]
+        end
+
+        # Removes temporal features from this table
+        #
+        def chrono_undo_temporal_table(table_name)
+          execute "DROP VIEW #{table_name}"
+
+          chrono_drop_trigger_functions_for(table_name)
+
+          on_history_schema { execute "DROP TABLE #{table_name}" }
+
+          default_schema = select_value 'SELECT current_schema()'
+          on_temporal_schema do
+            if primary_key(table_name) == '__chrono_id'
+              execute "ALTER TABLE #{table_name} DROP __chrono_id"
+            end
+
+            execute "ALTER TABLE #{table_name} SET SCHEMA #{default_schema}"
+          end
+        end
+
+        # Renames a table and its primary key sequence name
+        #
+        def rename_table_and_pk(name, new_name)
+          seq     = serial_sequence(name, primary_key(name))
+          new_seq = seq.sub(name.to_s, new_name.to_s).split('.').last
+
+          execute "ALTER SEQUENCE #{seq}  RENAME TO #{new_seq}"
+          execute "ALTER TABLE    #{name} RENAME TO #{new_name}"
+        end
+
+      # private
+    end
+
+  end
+end