mcfly 0.0.1

data/.gitignore

@@ -0,0 +1,21 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*~
+*.komodoproject
+.rvmrc
+spec/dummy/log

data/.rspec

@@ -0,0 +1 @@
+--colour

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in delorean.gemspec
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 Arman Bostani
+
+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,113 @@
+# Mcfly
+
+Mcfly is a database table versioning system.  It's useful for tracking
+and auditing changes to database tables.  It's also very easy to
+access the current state of Mcfly tables at any point in time.
+
+![](http://i.imgur.com/IG77ww0.jpg)
+
+## Features
+
+* All row versions are stored in the same table.
+
+* Different row versions are accessed through scoping.
+
+* Applications can use Mcfly to time-warp all tables to previous
+  points in time.
+  
+* Table queries for points in time are symmetric. i.e. queries to
+  access data in the present look just like queries available in any
+  particular point in time.
+
+* Implemented as database triggers.  So, the versioning system is
+  language/platform agnostic.
+
+## Installation
+
+    $ gem install mcfly
+
+Or add it to your `Gemfile`, etc.
+
+## Usage
+
+To create Mcfly enabled tables, they need to be created using
+`McFly::McFlyMigration` or `McFly::McFlyAppendOnlyMigration` instead
+of the usual `ActiveRecord::Migration`.
+
+    class CreateSecurityInstruments < McFlyAppendOnlyMigration
+      def change
+        create_table :security_instruments do |t|
+          t.string :name, null: false
+          t.string :settlement_class, limit: 1, null: false
+        end
+      end
+    end
+
+    class CreateMarketPrices < McFlyMigration
+      def change
+        create_table :market_prices do |t|
+          t.references :security_instrument, null: false
+          t.decimal :coupon, null: false
+          t.integer :settlement_mm, null: false
+          t.integer :settlement_yy, null: false
+          # NULL indicates unknown price
+          t.decimal :price
+        end
+      end
+    end
+
+These migration add the necessary versioning triggers for INSERT,
+UPDATE and DELETE operations.  The append-only migration disallows
+updates.  As such, append-only Mcfly tables rows to be INSERTed or
+DELETEed, but not modified.
+
+When you declare `has_mcfly` in your model, Mcfly adds some basic
+functionality to the class.
+
+    class SecurityInstrument < ActiveRecord::Base
+      has_mcfly append_only: true
+
+      attr_accessible :name, :settlement_class
+      validates_presence_of :name, :settlement_class
+      mcfly_validates_uniqueness_of :name
+    
+      mcfly_lookup :lookup, sig: 2 do
+        |pt, name|
+        find_by_name(name)
+      end
+    
+      mcfly_lookup :lookup_all, sig: 1 do
+        |pt| all
+      end
+    end
+
+The `has_mcfly` declaration provides the `mcfly_lookup` generator
+which is scopes queries to the proper timeline.  Also,
+`mcfly_validates_uniqueness_of` is Mcfly's scoped version of
+ActiveRecord's `validates_uniqueness_of`.
+
+... TODO ... show examples of adding rows and accessing versions of
+data ...
+
+## Implementation
+
+TODO
+
+## Limitations
+
+Currently, Mcfly only works with PostgreSQL databases.
+
+## History
+
+The database table versioning mechanism used in Mcfly was originally
+developed at [TWINSUN][]. It has since been modified and enhanced at
+[PENNYMAC][].
+
+## License
+
+Delorean has been released under the MIT license. Please check the
+[LICENSE][] file for more details.
+
+[license]: https://github.com/rubygems/rubygems.org/blob/master/MIT-LICENSE
+[pennymac]: http://www.pennymacusa.com
+[twinsun]: http://www.twinsun.com

data/Rakefile

@@ -0,0 +1,27 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Mcfly'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+

data/lib/mcfly/controller.rb

@@ -0,0 +1,21 @@
+module Mcfly
+  module Controller
+    def self.included(base)
+      base.before_filter :set_mcfly_whodunnit
+    end
+
+    # Returns the user who is responsible for any changes that occur.
+    # By default this calls `current_user` and returns the result.
+    #
+    # Override this method in your controller to call a different
+    # method, e.g. `current_person`, or anything you like.
+    def user_for_mcfly
+      current_user rescue nil
+    end
+
+    # Tells Mcfly who is responsible for any changes that occur.
+    def set_mcfly_whodunnit
+      ::Mcfly.whodunnit = user_for_mcfly
+    end
+  end
+end

data/lib/mcfly/delete_trig.sql

@@ -0,0 +1,18 @@
+CREATE OR REPLACE FUNCTION "%{table}_delete" ()
+  RETURNS TRIGGER
+AS $$
+
+BEGIN
+  IF OLD.obsoleted_dt <> 'infinity' THEN
+     RAISE EXCEPTION 'can not delete old row version';
+  END IF;
+
+  UPDATE "%{table}" SET "obsoleted_dt" = 'now()' WHERE id = OLD.id;
+
+  RETURN NULL; -- the row is not actually deleted
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS %{table}_delete ON %{table};
+CREATE TRIGGER "%{table}_delete" BEFORE DELETE ON "%{table}" FOR EACH ROW
+EXECUTE PROCEDURE "%{table}_delete"();

data/lib/mcfly/has_mcfly.rb

@@ -0,0 +1,63 @@
+require 'delorean_lang'
+
+module McFly
+  module Model
+    
+    def self.included(base)
+      base.send :extend, ClassMethods
+    end
+
+    module ClassMethods
+      def has_mcfly(options = {})
+        # FIXME: this methods gets a append_only option sometimes.  It
+        # needs to add model level validations which prevent update
+        # when this option is present. Note that we need to allow
+        # delete.  Deletion of McFly objects obsoletes them by setting
+        # obsoleted_dt.
+
+        send :include, InstanceMethods
+        after_initialize :record_init
+        # FIXME: :created_dt should also be readonly.  However, we set
+        # it for debugging purposes.  Should consider making this
+        # readonly once we're in production.
+        attr_readonly :group_id, :obsoleted_dt, :user_id
+      end
+
+      def mcfly_lookup(name, options = {}, &block)
+        delorean_fn(name, options) do |t, *args|
+          raise "time cannot be nil" if t.nil?
+          ts = (t == Float::INFINITY) ? 'infinity' : t
+          self.where("obsoleted_dt >= ? AND created_dt < ?", ts, ts).scoping do
+            block.call(t, *args)
+          end
+        end
+      end
+
+      def mcfly_validates_uniqueness_of(*attr_names)
+        # add :obsoleted_dt to the uniqueness scope
+
+        attr_names << {} unless attr_names.last.is_a?(Hash)
+
+        attr_names.last[:scope] ||= []
+        attr_names.last[:scope] << :obsoleted_dt
+        
+        # Set uniqueness error message if not set.  FIXME: need to
+        # figure out how to change the base message.  It still
+        # prepends the pluralized main attr.
+        attr_names.last[:message] ||= "- record must be unique"
+
+        validates_uniqueness_of(*attr_names)
+      end
+    end
+
+    module InstanceMethods
+      def record_init
+        # Set obsoleted_dt to non NIL to ensure constraints are properly
+        # constructed
+        self.obsoleted_dt = 'infinity' unless self.obsoleted_dt
+        self.user_id ||= Mcfly.whodunnit.try(:id)
+      end
+    end
+    
+  end
+end

data/lib/mcfly/insert_trig.sql

@@ -0,0 +1,27 @@
+CREATE OR REPLACE FUNCTION "%{table}_insert" ()
+  RETURNS TRIGGER
+AS $$
+BEGIN
+  -- "obsoleted_dt" is set when a history row is created by
+  -- UPDATE. Leave it alone.
+  IF NEW.obsoleted_dt <> 'infinity' THEN
+     RETURN NEW;
+  END IF;
+
+  NEW.obsoleted_dt = 'infinity';
+  NEW.group_id = NEW.id;
+
+  -- FIXME: Handle cases where created_dt is sent in on creation. This
+  -- is only useful for debugging.  Consider removing the surronding
+  -- IF for production version.
+  IF NEW.created_dt IS NULL THEN
+    NEW.created_dt = 'now()';
+  END IF;
+
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS %{table}_insert ON %{table};
+CREATE TRIGGER "%{table}_insert" BEFORE INSERT ON "%{table}" FOR EACH ROW
+EXECUTE PROCEDURE "%{table}_insert"();

data/lib/mcfly/migration.rb

@@ -0,0 +1,27 @@
+class McFlyMigration < ActiveRecord::Migration
+  INSERT_TRIG, UPDATE_TRIG, UPDATE_APPEND_ONLY_TRIG, DELETE_TRIG =
+    %w{insert_trig update_trig update_append_only_trig delete_trig}.map { |f|
+    File.read(File.dirname(__FILE__) + "/#{f}.sql")
+  }
+
+  TRIGS = [INSERT_TRIG, UPDATE_TRIG, DELETE_TRIG]
+
+  def create_table(table_name, options = {}, &block)
+    super { |t|
+      t.integer :group_id, null: false
+      # can't use created_at/updated_at as those are automatically
+      # filled by ActiveRecord.
+      t.timestamp :created_dt, null: false
+      t.timestamp :obsoleted_dt, null: false
+      t.references :user, null: false
+      block.call(t)
+    }
+
+    self.class::TRIGS.each {|sql| execute sql % {table: table_name}}
+  end
+end
+
+class McFlyAppendOnlyMigration < McFlyMigration
+  # append-only update trigger disallows updates
+  TRIGS = [INSERT_TRIG, UPDATE_APPEND_ONLY_TRIG, DELETE_TRIG]
+end

data/lib/mcfly/update_append_only_trig.sql

@@ -0,0 +1,25 @@
+CREATE OR REPLACE FUNCTION "%{table}_update" ()
+  RETURNS TRIGGER
+AS $$
+DECLARE
+
+BEGIN
+  IF OLD.obsoleted_dt <> 'infinity' THEN
+     RAISE EXCEPTION 'can not update obsoleted append-only row';
+  END IF;
+
+  -- If obsoleted_dt is being set, assume that the row is being
+  -- obsoleted.  We return the OLD row so that other field updates are
+  -- ignored.  This is used by DELETE.
+  IF NEW.obsoleted_dt <> 'infinity' THEN
+     OLD.obsoleted_dt = NEW.obsoleted_dt;
+     return OLD;
+  END IF;
+
+  RAISE EXCEPTION 'can not update append-only row';
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS %{table}_update ON %{table};
+CREATE TRIGGER "%{table}_update" BEFORE UPDATE ON "%{table}" FOR EACH ROW
+EXECUTE PROCEDURE "%{table}_update"();

data/lib/mcfly/update_trig.sql

@@ -0,0 +1,62 @@
+CREATE OR REPLACE FUNCTION "%{table}_update" ()
+  RETURNS TRIGGER
+AS $$
+DECLARE
+  rec "%{table}";
+  new_id INT4;
+  now timestamp;
+
+BEGIN
+  IF OLD.obsoleted_dt <> 'infinity' THEN
+     RAISE EXCEPTION 'can not modify old row version';
+  END IF;
+
+  -- If obsoleted_dt is being set, assume that the row is being
+  -- obsoleted.  We return the OLD row so that other field updates are
+  -- ignored.  This is used by DELETE.
+  IF NEW.obsoleted_dt <> 'infinity' THEN
+     OLD.obsoleted_dt = NEW.obsoleted_dt;
+     return OLD;
+  END IF;
+
+  -- copy old version of the row into rec
+  SELECT INTO rec * FROM "%{table}" WHERE "id" = NEW.id;
+
+  -- new_id is a new primary key that we'll use for the obsoleted row.
+  SELECT nextval('"%{table}_id_seq"') INTO new_id;
+
+  -- not sure if PGSQL will return the same value for now() in the
+  -- same transaction.  So, use the same variable to be sure.
+  now = 'now()';
+
+  rec.id = new_id;
+  rec.group_id = NEW.id;
+  
+  -- FIXME: The following IF/ELSE handles cases where created_dt is
+  -- sent in on update. This is only useful for debugging.  Consider
+  -- removing the surronding IF (and ELSE part) for production
+  -- version.
+  IF NEW.created_dt = OLD.created_dt THEN
+    -- Set the modified row's created_dt.  The obsoleted_dt field was
+    -- already infinity, so we don't need to set it.
+    NEW.created_dt = now;
+    rec.obsoleted_dt = now;
+  ELSE
+    IF NEW.created_dt <= OLD.created_dt THEN
+      RAISE EXCEPTION 'new created_dt must be greater than old';
+    END IF;
+
+    rec.obsoleted_dt = NEW.created_dt;
+  END IF;
+
+  -- insert rec, note that the insert trigger will get called.  The
+  -- obsoleted_dt is set so INSERT should not do anything with this row.
+  INSERT INTO "%{table}" VALUES (rec.*);
+
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS %{table}_update ON %{table};
+CREATE TRIGGER "%{table}_update" BEFORE UPDATE ON "%{table}" FOR EACH ROW
+EXECUTE PROCEDURE "%{table}_update"();

data/lib/mcfly/version.rb

@@ -0,0 +1,3 @@
+module Mcfly
+  VERSION = "0.0.1"
+end

data/lib/mcfly.rb

@@ -0,0 +1,36 @@
+require 'mcfly/migration'
+require 'mcfly/has_mcfly'
+require 'mcfly/controller'
+require 'active_support'
+
+module Mcfly
+  # ATTRIBUTION: some of the code in this project has been shamelessly
+  # lifted form paper_trail.
+
+  # Sets who is responsible for any changes that occur.  You would
+  # normally use this in a migration or on the console, when working
+  # with models directly.
+  def self.whodunnit=(value)
+    mcfly_store[:whodunnit] = value
+  end
+
+  def self.whodunnit
+    mcfly_store[:whodunnit]
+  end
+
+  private
+
+  # Thread-safe hash to hold Mcfly's data.
+  def self.mcfly_store
+    Thread.current[:mcfly] ||= {}
+  end
+end
+
+ActiveSupport.on_load(:active_record) do
+  include Delorean::Model
+  include McFly::Model
+end
+
+ActiveSupport.on_load(:action_controller) do
+  include Mcfly::Controller
+end

data/lib/tasks/mcfly_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :mcfly do
+#   # Task goes here
+# end

data/mcfly.gemspec

@@ -0,0 +1,27 @@
+$:.push File.expand_path("../lib", __FILE__)
+
+require "mcfly/version"
+
+# Describe your gem and declare its dependencies:
+Gem::Specification.new do |s|
+  s.name        = "mcfly"
+  s.version     = Mcfly::VERSION
+  s.authors     = ["Arman Bostani"]
+  s.email       = ["arman.bostani@pnmac.com"]
+  s.homepage    = "https://github.com/arman000/mcfly"
+  s.summary     = %q{A database table versioning system.}
+  s.description = s.summary
+  s.files 	= `git ls-files`.split($\)
+
+  s.require_paths = ["lib"]
+
+  s.add_dependency "rails", "~> 3.2.11"
+  s.add_dependency "pg"
+
+  # FIXME: Delorean is added here for historical reasons.  It should
+  # be removed as a dependency.
+  s.add_dependency "delorean_lang"
+
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "rspec-rails"
+end

data/spec/dummy/.rspec

@@ -0,0 +1 @@
+--color