Skip to content
Date-relative UUID generation: Ruby library
Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
spec
.gitignore
.travis.yml
Gemfile
Gemfile.lock
README.markdown
Rakefile
druuid.gemspec
druuid.rb Fix readability of #time method May 27, 2016

README.markdown

Druuid

Date-relative (and relatively universally unique) UUID generation. A JavaScript implementation is also available.

Overview

Druuid generates 64-bit, time-sortable IDs inspired by Snowflake and Instagram.

A druuid comprises:

  • A 41-bit timestamp (which has millisecond precision for over 69 years after a defined epoch); and

  • 23 random bits.

For example, a druuid generated at midnight on February 4, 2012, may look something like 11142943683383068069. In binary:

Timestamp Randomness
10011010101000111011000000111110000000000 01110110000010110100101

This ID can be displayed compactly in base 36: 2cnpvvfkm56ed.

Pros

  • 64-bit IDs can be stored in BIGINT database columns, which are generally more efficient to index (and index uniquely) than VARCHAR.

  • The timestamp component allows for efficient date-based queries and easy cursor-based pagination.

Cons

  • 23 bits of randomness contains much less entropy than traditional, 128-bit UUIDs, so precautions must be taken to avoid collisions between druuids generated in the same millisecond (e.g., a database constraint). The probability, within a millisecond, can be calculated with the Birthday problem (where n is the number of IDs generated per millisecond and 23 represents the number of random bits):

    p(n)≈1-e^(-(n^2)/(2*2^23))

    IDs generated in different milliseconds cannot collide, but at a rate of 10 IDs per millisecond (10,000 IDs per second), the probability a collision will occur within any given millisecond approaches 0.000596%, which is about once every few minutes if that rate is constant.

Installation

$ gem install druuid

Examples

require 'druuid'
# Druuid.epoch = Time.utc 1970 # change the default (Unix) epoch

uuid = Druuid.gen
# => 11142943683383068069
Druuid.time uuid
# => 2012-02-04 00:00:00 -0800

License

(The MIT License)

© 2013 Recurly Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Something went wrong with that request. Please try again.