= UUIDs
{
}[https://rubygems.org/gems/uuids]
{
}[https://travis-ci.org/nepalez/uuids]
{
}[https://codeclimate.com/github/nepalez/uuids]
{
}[https://gemnasium.com/nepalez/uuids]
{
}[https://coveralls.io/r/nepalez/uuids]
{
}[https://github.com/nepalez/uuids/blob/master/LICENSE.rdoc]
== About
The gem allows addressing ActiveRecord objects by {UUID}[http://en.wikipedia.org/wiki/Universally_Unique_Identifier]s following the {RFC4122}[http://www.ietf.org/rfc/rfc4122.txt]
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
Then run the command in the root of a end-up application:
$ uuids install -g
Use the -d key when installing the gem into a module that is not
an end-up application (Rails engine etc.):
$ uuids install -d -g
(this will copy the gem's migrations to the host's dummy folder:
+spec/dummy/db/migrate+).
The -g key allows copying gem's factory girl factories to the host application.
Review them and remove unused.
== 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
# 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
include Uuids::Base
belongs_by_uuid_to :city, class: City
end
This will add both getter and setter for the attribute:
street = Street.new name: "Damrak", city: City.new name: "Amsterdam"
street.city
# => #
street.city_uuid == street.city.uuid # => true
=== Adding uuid
The module also contains the service object +Add+:
service = Uuids::Services::Add.new(
value: "43523547-8230-5723-0457-234057254725",
record: #
)
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. 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
1. Fork it ( https://github.com/nepalez/uuids/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request
== License
The plugin is distributed under {MIT license}[https://github.com/nepalez/uuids/blob/master/LICENSE.rdoc]