UUIDs

About

The gem allows addressing ActiveRecord objects by UUID[http://en.wikipedia.org/wiki/Universally_Unique_Identifier]s following the RFC4122 standard.

The gem requires Ruby 2.1+ and ActiveRecord 3.1+. It doesn’t depend on full stack Rails and can be used in domain apps based on ActiveRecord.

Pattern

The module allows adressing records by UUID(s) instead of ID. A record can be identified by many UUIDs.

This makes it possible to merge records without touching external to the records.

For merging records it’s sufficient to:

reassign all their uuids to the united record.
destroy old records, which no uuid refers to.

Whatever external models are referred by uuid to the deleted records, that references remains valid and will lead to the united record.

Example

Suppose you have models referred to cities. One day you discover a duplication among two 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.

Now the model of cities should **know nothing about outer models** that use it.

Installation

Add this line to your application’s Gemfile:

gem "uuids"

And then execute:

$ bundle

Or install it yourself as:

$ gem install uuids

Initialization

After installation you should copy and run uuid’s db migration into your module.

When you install the module to a final application, the migration should be installed to ‘db/migrate` path directly.

$ uuids install

When you install the module to another gem as a part of its environment, the migration isn’t a part of your project. It only needed for testing your gem in a proper environment.

In this case the migration should be installed to a dummy app in a ‘spec/dummy/db/migrate` folder. Do it with the `-d` key:

$ uuids install -d

Usage

Adding UUIDs to models

Add the assotiation to your AR model with a ‘has_uuids` helper:

class City < ActiveRecord::Base
  include Uuids::Base
  has_uuids
end

This will add methods:

#uuids: List of Uuids::Models::Uuid objects referred to the record.
#uuid=(value): assigns the UUID (an alias for #uuids.new value: value).
#uuid: main UUID for the record - a value of the first uuids (ordered by value).
.by_uuid(*values): A scope for selecting unique records by UUID.

The first uuid is added by default. It can also be set manually:

# UUID generated by default:
city = City.create!
city.uuid.nil?
# => false

# UUID(s) assigned manually:
city = City.create! uuids: "6d9456a9-8f54-4ff7-ba0d-9854f1954417"
city.uuid
# => "6d9456a9-8f54-4ff7-ba0d-9854f1954417"

Destruction of object is forbidden while it has a uuid. You should reassign all object’s UUIDs to another record in advance.

Referring model by UUID

Instead of ActiveRecord::Associations belongs_to, has_one and has_many, you should define custom methods explicitly.

# db/migrate/*_create_streets.rb
class CreateStreetsTable < ActiveRecord::Migration
  def change
    create_table :streets do |t|
      t.string :city_uuid, limit: 36
    end
    add_index :streets_table, :city_uuid
  end
end

# app/models/street.rb
class Street < ActiveRecord::Base

  scope :by_city, ->(city) { City.by_uuid(city.uuid) }

  def city
    @city ||= City.by_uuid(city_uuid)
  end

  def city=(city)
    write_attribute :city_uuid, city.uuid
  end
end

Adding uuid

The module also contains the service object Add:

service = Uuids::Services::Add.new(
  value: "43523547-8230-5723-0457-234057254725",
  record: #<ActiveRecord::Base ... >
)
service.subscribe listener
service.run

Depending on the result of creation, the listener will receive either the :created, uuid, messages or :error, messages notification.

The service doesn’t know what the record is. In the success message it will be referred as the record “with id: %id”. To provide more concise messaging, the service should be reloaded with a new name method.

module Users
  module Services
    class AddUuid < Uuids::Services::Add
      private
      def name
        # It is expected the record is a user, that responds to full_name.
        # Not the success message will be something near:
        # "The uuid ... has been added to the record Иван Иванов."
        record.full_name
      end
    end
  end
end

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

License

The plugin is distributed under MIT license