Footprint

Footprint is a MongoDB-backed versioning system for those Big Applications which have a need for storing

Huge amounts of Version data for auditing purposes
All states of a record for analysis by BI tools

But struggle because they cannot

Use a simple database system due to performance constraints
Shift to a NoSQL DB completely because of transaction requirements

Footprint integrates seamlessly into your ActiveRecord-driven Rails Application, effectively converting it into a Hybrid application, storing only version data (or Impressions, as they are called) in a MongoDB database.

Installation

Add Footprint to your Gemfile:

gem "footprint", "1.0.0.rc2"

Generate mongoid.yml if you don't have one in your project already

$ rails g mongoid:config

Modify your config/application.rb to still use ActiveRecord generators by default and to enforce

config.generators do |g| 
  g.orm :active_record 
end

Add a special lookup for Mongoid gem: (will be removed when Mongoid 3.1.0 is released)

gem "mongoid", :git => 'git@github.com:mongoid/mongoid.git'

Setting Up Documents for your ActiveRecord models

Generate a document from an existing ActiveRecord Model

$ rails g footprint:document User

Add leave_a_track to your Model class

class User < ActiveRecord::Base
  leave_a_track
  attr_accessible :name, :dob
end

Handling Impressions

Querying

Impressions (a.k.a versions) of a record are accessible through impressions attribute

u = User.find(1)
u.impressions

Collecting values

Collecting specific values in Impressions too is very similar to normal AR model behavior

u = User.find(1)
u.impressons.collect { |imp| imp.name }

Reviving a copy of the parent

Converting an Impression to an ActiveRecord model, to mirror the parent can be done via as_parent method

User.create("name" => "Subhash", "join_date" => 2.days.ago) # User:1
u = User.find(1)
u.impressions.count # 1
u.name = "Subhash Bhushan"
u.save
u.impressions.count # 2
User copy_of_user_1 = u.impressions.last.as_parent

Sorting

p.impressions.asc(:updated_at)
p.impressions.order_by(:updated_at.asc)
p.impressions.desc(:updated_at)

For a complete list of sorting options: Mongoid Sorting

Pagination

Kaminari is the preferred way to paginate mongoid documents. will_paginate_mongoid gem is an option for those who already use will_paginate.

Enabling/Disabling Footprint globally

Footprint is enabled by default. If you want to disable it globally, just include the following snippet in an environment file (like config/environments/development.rb or config/environments/test.rb)

config.after_initialize do
  Footprint.enabled = false
end

Loading Existing Data

You can create impressions for existing data of a model, by running rake task load on it:

rake footprint:load[User]

If you are using zsh, you will have to escape braces:

rake footprint:load\[User\]

rake "footprint:load[User]"

Extract Impressions

You can extract all impressions of a model in a csv, by running rake task extract on it:

rake footprint:extract[User]

If you are using zsh, you will have to escape braces:

rake footprint:extract\[User\]

rake "footprint:extract[User]"

The extracted file is placed in tmp subfolder of your rails application.

Setting up MongoDB

Getting a MongoDB instance up and running is pretty simple. Visit Installation Guides to set up one for your OS.

The tutorial Getting Started with MongoDB Development explains basics of connecting to a MongoDB instance and querying on collections

Known Issues

If you get a message that "ActiveRecord model '<model_name>' was not found" while generating a document, do rake db:migrate and then try generating the document again.

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

Inspirations

Resources

MongoDB
Versioning Strategies

alexrothenberg / footprint