Binary uuid keys in Rails
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.


Build Status


Add binary(16) UUIDs to ActiveRecord.


Create a Migration

activeuuid adds the uuid type to your migrations. Example:

class CreateEmails < ActiveRecord::Migration
  def self.up
    create_table :emails, :id => false  do |t|
      t.uuid :id, :primary_key => true
      t.uuid :sender_id  # belongs_to :sender

      t.string :subject
      t.text :body

      t.timestamp :sent_at
    add_index :emails, :id

  def self.down
    drop_table :emails

include ActiveUUID::UUID in your model

class Email < ActiveRecord::Base
  include ActiveUUID::UUID
  belongs_to :sender

specify a natural key for generating the UUID based on one or more columns

class Email < ActiveRecord::Base
  include ActiveUUID::UUID
  natural_key :sender_id, :received_at
  belongs_to :sender

natural_key generates a SHA1-based UUID in the ISO OID namespace by default. [7]

specify a custom UUID namespace for the natural key

class Email < ActiveRecord::Base
  include ActiveUUID::UUID
  uuid_namespace "1dd74dd0-d116-11e0-99c7-5ac5d975667e"
  natural_key :sender_id, :received_at
  belongs_to :sender

uuid_namespace can either be a UUID in string format, or a UUIDTools::UUID object.

use it:

Here are some example specs:

require 'spec_helper'

describe Email do

  context "when using uuid's as keys" do
    let(:guid) { "1dd74dd0-d116-11e0-99c7-5ac5d975667e" }
    let(:email) { Fabricate :email }

    it "the id guid should be equal to the uuid" do eql(guid)

    it "should be able to find an email by the uuid" do
      Email.find(guid).id.to_s.should == guid



From [2]:

[Here is a] UUID: 1e8ef774-581c-102c-bcfe-f1ab81872213

A UUID like the one above is 36 characters long, including dashes. If you store this VARCHAR(36), you're going to decrease compare performance dramatically. This is your primary key, you don't want it to be slow.

At its bit level, a UUID is 128 bits, which means it will fit into 16 bytes, note this is not very human readable, but it will keep storage low, and is only 4 times larger than a 32-bit int, or 2 times larger than a 64-bit int.

Many of the existing examples of how to use UUIDs as primary keys in Rails use strings rather than bytes (e.g. [3]).

However, this plugin stores the primary keys as bytes. To the application the keys are represented by a UUIDTools::UUID object.

Benefits of UUIDs as primary key

  • no id conflict during multi-master write
  • no locking due to auto-increment
  • with time-based UUIDs you can store a timestamp within your UUID
  • you can create natural keys (based on the SHA of model attributes)

Future work

  • more transparent support for natural and composite keys
  • support for MySQLs INSERT ... ON DUPLICATE KEY UPDATE syntax
  • support a primary column name other than id
  • tests


James Golick's friendly is a great gem for NoSQL on MySQL. It's a great gateway drug to systems like Cassandra for teams that are already familiar with the ins-and-outs of MySQL.


Add this to your Gemfile

gem "activeuuid"

Or get the code here:



Rails ~> 3.1.0


  • Nate Murray
  • pyromaniac
  • Andrew Kane
  • Devin Foley
  • Arkadiy Zabazhanov
  • Jean-Denis Koeck
  • Florian Staudacher
  • Schuyler Erle
  • Florian Schwab
  • Thomas Guillory
  • Daniel Blanco Rojas
  • Olivier Amblet