UUIDs

About

Defines a model Uuid to store UUIDs assigned to various AR records.

It is expected any uuid is assigned to one record, but a record can be identified by many uuids.

The gem is a mountable Rails engine.

The gem provides:

Uuids::Uuid: A model of UUIDs associated with various records.
Uuids::Base: A module to be included to AR model to provide required #uuids attribute.

Pattern

This model allows refering records by some uuid (not the id).

If necessary any referred record can be merged with another one. If you reassign all their uuids to merged record then any references remains valid without tracking and changing them before merge.

A uuid should be neither deleted, no changed. It can only be reassigned to another resource. The records can be deleted

by merging to another ones;
by explicitly marking as deleted without physical removal.

Example

Suppose you have models referred to cities. One day you discover a duplication among cities: the “New York” and the “NEW YORK”.

You should:

reassign both uuids to “New York”;
safely remove the “NEW YORK” record.

You needn’t track all records that refer to “NEW YORK”. All those references will authomatically lead to merged record via old uuid.

Standards

The Uuid is generated authomatically following the RFC4122 standard. The generation uses the sequrerandom Ruby library.

This allows keeping all uuids in one model and referring to any record whatever type it has.

Translations

Error messages are translated to English and Russian (see config/locales). Translations to other languages are welcome.

Installation

Add this line to your application’s Gemfile:

gem "uuids"

And then execute:

$ bundle

Or install it yourself as:

$ gem install uuids

Rails application

Run from a command line in application root:

$ rake uuids:install

This will copy gem migrations to a db/migrate folder and run it.

Rails mountable engine

Run from a command line in application root:

$ rake app:uuids:install

This will copy gem migrations to a spec/dummy/db/migrate folder and run it.

Usage

Add the assotiation to your AR model:

class YourModel < ActiveRecord::Base

  # declares the association
  has_many :uuids, class_name: "Uuids::Uuid", as: :record, validate: false

  # auto-generates uuid by default
  before_create  -> { uuids.present? || uuids.new }

  # prevents the record from being unreferable
  validates :uuids, presence: true, on: :update

  # prevents a record destruction before its uuids reassigned to another one
  before_destroy -> { uuids.blank? }
end

Instead of above you can simply include the Uuids::Base module:

class YourModel < ActiveRecord::Base
  include Uuids::Base
end

Now you can refer to your model via uuid:

class CreateAnotherModelTable < ActiveRecord::Migration
  def change
    create_table :another_models do |t|
      t.string :your_model_uuid, limit: 36
    end
    add_index :another_models, :your_model_uuid
  end
end

class AnotherModel < ActiveRecord::Base

  def your_model
    @your_model ||= YourModel.join(:uuids)
      .where(uuids_uuids: { value: your_model_uuid }).first
  end

  def your_model=(record)
    @your_model_uuid ||= Uuids::Uuid.find_by_record(record).try(:value)
  end
end

Uninstallation

Rails app

Run from a command line in application root:

$ rake uuids:uninstall

This will rollback and remove migration from db/migrate folder and then remove the gem dependencies from application’s Gemfile and gemspec.

Rails mountable engine

Run from a command line in engine root:

$ rake app:uuids:uninstall

This will rollback and remove migration from spec/dummy/db/migrate folder and then remove the gem dependencies from engine’s Gemfile and gemspec.

Contributing

Fork it ( github.com/nepalez/uuids/fork )
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 a new Pull Request

TODO

Redefine AR::Base class methods has_one and has_many to allow reference by uuid:

class MyModel < ActiveRecord::Base
  include Uuids::Associations

  has_one :another_model, uuid: true
end

License

The plugin is distributed under MIT license