README.md
# Random Unique ID
[![Build Status](https://travis-ci.org/carouselapps/random_unique_id.svg?branch=master)](https://travis-ci.org/carouselapps/random_unique_id)
[![Coverage Status](https://coveralls.io/repos/carouselapps/random_unique_id/badge.svg?branch=master&service=github)](https://coveralls.io/github/carouselapps/random_unique_id?branch=master)
[![Code Climate](https://codeclimate.com/github/carouselapps/random_unique_id.png)](https://codeclimate.com/github/carouselapps/random_unique_id)
[![Inline docs](http://inch-ci.org/github/carouselapps/random_unique_id.svg?branch=master)](http://inch-ci.org/github/carouselapps/random_unique_id)
[![Gem Version](https://badge.fury.io/rb/random_unique_id.png)](http://badge.fury.io/rb/random_unique_id)
[![Dependency Status](https://gemnasium.com/carouselapps/random_unique_id.svg)](https://gemnasium.com/carouselapps/random_unique_id)
This gem will generate a random unique id for your active record records that you can use instead of their actual ID for
all external interactions with users. The goal is for you to be able to hide how many records you have, for business
purposes, but also to make IDs non-predictable.
This gem is built to work with Ruby 1.9, 2.0, 2.1 as well as with Rails 3.2, 4.0, 4.1 and 4.2. All of these cases are
[continuously tested for](https://travis-ci.org/carouselapps/random_unique_id).
## Installation
Add this line to your application's Gemfile:
gem "random_unique_id"
And then execute:
$ bundle
Or install it yourself as:
$ gem install random_unique_id
## Usage
The usage is very simple. For each record where you want to have a random id generated, add the following line to the
class:
has_random_unique_id
For example:
class Post < ActiveRecord::Base
has_random_unique_id
end
You need to also add a column, called `rid` of type string/varchar. It is recommended that you also add a unique index
on that column, for example:
def up
add_column :posts, :rid, :string
add_index :posts, :rid, :unique
end
The method `to_param` will be overridden to return the `rid` instead of the `id`. The method `belongs_to` gets extended
to define `_rid` methods similar to the `_id` method, like: `blog_rid` and `blog_rid=`. If you don't want to define
those pass `define_rid_method` as false, for example:
class Post
belongs_to :blog, define_rid_method: false
end
Classes that have rids also get a method called `populate_random_unique_ids` to help you populate the rid of existing
records. For example:
def up
add_column :posts, :rid, :string
add_index :posts, :rid, :unique
say_with_time "Post.populate_random_unique_ids" do
Post.reset_column_information
Post.populate_random_unique_ids { print "."}
end
end
## Configuration
There are 2 settings that are configurable for RandomUniqueId:
- `min_rid_length:` If you have a large table, the default of 5 characters for an initial length may be a problem, since it may lead to
several "bounces" until a new unique RID gets generated. The gem scales well with this problem, since it makes
each subsequent try longer than the one before, but it may still may 3 or 4 DB hits for each record creation.
In that case, you may want to set it to start with a higher number directly.
- `random_generation_method:` If you have a very large table, and having very long IDs is not a problem, you can choose to generate UUIDs instead
of short-ish Random IDs. This looks worse if you're displaying these IDs in a URL, but it allows to skip the check
for existence, which in a large table can make a large difference.
random_generation_method can be either `:short` (the default) or `:uuid`
Both of these settings can be specified on a per-model basis, when adding RandomUniqueId to the model:
has_random_unique_id(min_rid_length: 10)
has_random_unique_id(random_generation_method: :uuid)
Or globally in an initializer:
RandomUniqueId.config(min_rid_length: 10)
## Users
This gem is being used by:
- [Watu](https://watuapp.com)
- [MSTY](https://www.msty.com)
- You? please, let us know if you are using this gem.
## Changelog
### Version 1.1.0 (Jan 7, 2015)
- Added global configuration.
- Added UUID generation.
- Allow changing the name of the field used for the random id.
### Version 1.0.1 (Dec 22, 2014)
- Added support for Rails 4.2.
### Version 1.0.0 (Oct 28, 2014)
- Added RandomUniqueId::Util.set_initial_ids.
- Started testing Ruby 2.1.2 and 2.1.3.
- Started testing Rails 4.1 (fixed some deprecation warnings).
- Improved documentation.
### Version 0.2.1 (May 27, 2014)
- Internal refactorings.
### Version 0.2.0 (Apr 5, 2014)
- Added method populate_random_unique_ids.
- Improved documentation
- Started testing with Ruby 2.1.
### Version 0.1.0 (Jan 6, 2014)
- Initial release of the code extracted from [Watu](http://watuapp.com).
## Contributing
1. Fork it
1. Create your feature branch (`git checkout -b my-new-feature`)
1. Code your thing
1. Write and run tests:
bundle install
appraisal
appraisal rake test
1. Write documentation and make sure it looks good: yard server --reload
1. Add items to the changelog, both in the README and the CHANGELOG file.
1. Commit your changes (`git commit -am "Add some feature"`)
1. Push to the branch (`git push origin my-new-feature`)
1. Create new Pull Request