snaptime

This Gem is still in an early stage of development. Please not use this in production yet.

Snaptime lets you versionize Active Record models using single table versioning. Records are identified by a natural_id and their validity is controlled via valid_from and valid_to. Snaptime also supports associations between versioned models as well as associations to and from unversioned models.

Reasons for snaptime

  • Most of Snaptime’s operation is transparent, so you won’t even notice that a certain model is versioned if you don’t explicitely want to.

  • Associations between, to and from versioned models are automatically handeled. This lets Snaptime version entire, complex hierarchies.

  • It is very lightweight.

  • It is non-intrusive. It does not overwrite a single Rails method without you explicitly telling it to do so.

  • It can be easily extended to support other database adapters.

Basic concept

Snaptime can be enabled on a per-model basis. Using dedicated migration methods, each versioned table is complemented with the following fields:

  • natural_id

    This is the ID that does not change between versions. This is also the ID that is referenced when pointing to a versioned model.

  • valid_from, valid_to

    These are UTC timestamps in milliseconds that specify a specific version’s validity. The field valid_from always specifies the point in time at which a certain version has been created, while valid_to says when the version got outdated. This can happen by deleting the record (which does not actually delete it but just sets valid_to) or when a new version arises. There can’t be any gaps between the validity fields of a version string.

Snaptime works by hooking into your versioned models at creation, update and deletion:

  • At creation, it automatically generates a new natural_id and sets valid_from to the current time.

  • At update, valid_from is again set to the current time and the record is updated as usual. But before the record gets updated, Snaptime creates a copy of the record’s current state and sets valid_from and valid_to accordingly. The copy is created in-db (using insert ... select) and does not call any application side logic.

  • At deletion, all it does is setting valid_to of the current record to the current time again.

What this means is that the original record always stays the newest one. This has many advantages, as the record itself can be updated as usual and if another model would ever point at the id instead the natural_id, it would always point to the newest one.

Basic setup

Gemfile

Add the following to your application’s Gemfile:

ruby gem :snaptime

You can also specify a fixed version:

ruby gem :snaptime, '~> 1.0.0'

Setup task

Snaptime needs to generate a natural_id next to your id. In some adapters, this can be done using database sequences, while other databases require a custom setup (i.e. MySQL let’s you workaround this by adding a dedicated sequence table as well as a custom procedure).

Using the following rake task, Snaptime automatically generates the required migrations. Note that this migration only performs a basic setup and does not enable any of your models to be versioned. This happens using separate migrations as described in the following chapters.

bash rake snaptime:setup -- <adapter-name>

Replace <adapter-name> with the name of your database adapter. Spell it exactly as the adapter setting of your database configuration reads. If the specific adapter does not require any setup, you will get a respective message.

Versionizing a model

Performing the database migrations

TODO

Include the versionize module

ruby class YourModel < ActiveRecord::Base include Snaptime::Versioned end

Caveats

  • Do not use def self.default_scope but default_scope do in versioned models if you need to extend the default scope.
  • .unscoped also removes the default scope added by snaptime.