pg_random_id 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in pg_random_id.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Rafał Rzepecki
+
+MIT License
+
+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.

data/README.md

@@ -0,0 +1,73 @@
+# PgRandomId
+
+Allow usage of pseudo-random IDs in Postgresql databases.
+Changes sequential surrogate ids (1, 2, 3...) into a pseudo-random
+sequence of unique 30-bits nonnegative integer values (eg. 760280231, 110168588, 1029278017...).
+
+Integrates with ActiveRecord. Sequel integration is upcoming.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'pg_random_id'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install pg_random_id
+
+## Usage
+
+The easiest way to use it is to use the supplied migration functions.
+
+First, make sure you put
+    create_random_id_functions
+in a migration (a single one will do).
+
+Then to apply random ids to a table, use random_id function:
+
+```ruby
+class RandomizeIdsOnFoo < ActiveRecord::Migration
+  def up
+    KEY = 21315
+    random_id :foo, :foo_id, KEY
+  end
+end
+```
+
+If you don't supply the key, a random one will be generated;
+similarly, the id column name defaults to :id. 
+This means that you can create a vanilla AR table with random ids
+with the following simple migration:
+
+```ruby
+class CreateProducts < ActiveRecord::Migration
+  def up
+    create_table :products do |t|
+      t.string :name
+    end
+    random_id :products
+  end
+end
+```
+
+No model modification is necessary, just use the table as usual and it will simply work.
+You can even use it without ActiveRecord.
+
+### Text ids
+
+If you use random_str_id function instead, it will additionally 
+change the column type to character(6) and store the ids as base32-encoded
+strings of handy human-friendly form (eg. kn5xx1, qy2kp8, e5f67z...).
+
+## Contributing
+
+1. Fork it
+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 new Pull Request

data/Rakefile

@@ -0,0 +1,5 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec

data/lib/pg_random_id/migrations/active_record.rb

@@ -0,0 +1,35 @@
+require 'active_record'
+require 'active_record/migration'
+require 'pg_random_id/sql'
+
+module PgRandomId
+  module Migrations
+    module ActiveRecord
+      # Create in the database the function (pri_scramble(bigint, bigint))
+      # necessary for this gem to work.
+      def create_random_id_functions
+        execute PgRandomId::Sql::install
+      end
+      
+      # Apply a random id to a table.
+      # If you don't give a key, a random one will be generated.
+      # The ids will be based on sequence "#{table}_#{column}_seq".
+      # You need to make sure the table is empty; migrating existing records is not implemented.
+      def random_id table, column = :id, key = nil
+        execute PgRandomId::Sql::apply(table, column, key)
+      end
+
+      # Apply a random string id to a table. 
+      # Also changes the type of the id column to char(6).
+      # If you don't give a key, a random one will be generated.
+      # The ids will be based on sequence "#{table}_#{column}_seq", 
+      # scrambled and base32-encoded.
+      # You need to make sure the table is empty; migrating existing records is not implemented.
+      def random_str_id table, column = :id, key = nil
+        execute PgRandomId::Sql::apply_str(table, column, key)
+      end
+    end
+  end
+end
+
+ActiveRecord::Migration.send :include, PgRandomId::Migrations::ActiveRecord

data/lib/pg_random_id/sql/crockford-pure.sql

@@ -0,0 +1,15 @@
+-- Pure Postgres SQL implementation of Base32 Crockford encoding
+-- using recursive common table expressions
+-- (about 10% slower than the pg/plsql variant)
+CREATE OR REPLACE FUNCTION crockford(input bigint) RETURNS varchar
+LANGUAGE sql
+IMMUTABLE STRICT AS $$
+  WITH RECURSIVE parts(part) AS (
+    (SELECT $1 AS part) 
+  UNION 
+    (SELECT part >> 5 FROM parts WHERE part > 31))
+  SELECT string_agg(
+    (ARRAY['0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'j', 'k', 'm', 'n', 'p', 'q', 'r', 's', 't', 'v', 'w', 'x', 'y', 'z'])
+    [(part & 31) + 1]
+  ,'') FROM (SELECT part FROM parts ORDER BY part ASC) AS reversed;
+$$;

data/lib/pg_random_id/sql/crockford.sql

@@ -0,0 +1,23 @@
+-- Postgres pl/pgSQL implementation of Base32 Crockford encoding
+-- (see http://www.crockford.com/wrmg/base32.html )
+
+CREATE OR REPLACE FUNCTION crockford(input bigint) RETURNS varchar
+LANGUAGE plpgsql
+IMMUTABLE STRICT AS $$
+  DECLARE
+    charmap CONSTANT char[] = ARRAY['0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'j', 'k', 'm', 'n', 'p', 'q', 'r', 's', 't', 'v', 'w', 'x', 'y', 'z'];
+    result varchar = '';
+  BEGIN
+    IF (input < 0) THEN
+      RAISE EXCEPTION numeric_value_out_of_range USING
+        MESSAGE = 'crockford(): bad input value --> ' || input,
+        HINT = 'Input needs to be nonnegative.';
+    END IF;
+    LOOP
+      result := charmap[(input & 31) + 1] || result;
+      input := input >> 5;
+      EXIT WHEN input = 0;
+    END LOOP;
+    RETURN result;
+  END;
+$$;

data/lib/pg_random_id/sql/scramble.sql

@@ -0,0 +1,38 @@
+-- A simple Feistel network to scramble a 30-bit unsigned integer.
+-- There are seven rounds with a simple round function.
+-- The output is guaranteed to be 1:1 mapping, ie. no collisions.
+-- Supply a unique key (table oid is a good choice) to create different sequences.
+-- 30-bit length makes it possible to use ints instead of bigints
+-- and convenient to base32-encode the value.
+
+-- The code is based on http://wiki.postgresql.org/wiki/Pseudo_encrypt
+CREATE OR REPLACE FUNCTION
+pri_scramble(key bigint, input bigint) RETURNS int
+LANGUAGE plpgsql
+IMMUTABLE STRICT
+AS $$
+  DECLARE
+    l1 int;
+    l2 int;
+    r1 int;
+    r2 int;
+    i int:=0;
+  BEGIN
+    IF (input < 0) OR (input > 1073741823) THEN
+      RAISE EXCEPTION numeric_value_out_of_range USING
+        MESSAGE = 'pri_scramble(): bad input value --> ' || input,
+        HINT = 'Input needs to be a 30-bit nonnegative integer.';
+    END IF;
+    l1:= (input >> 15) & 32767;
+    r1:= input & 32767;
+    key := key + 15228; -- we don't want the key to be zero
+    WHILE i < 7 LOOP
+      l2 := r1;
+      r2 := l1 # ((r1::bigint * key + 3506) & 32767);
+      l1 := l2;
+      r1 := r2;
+      i := i + 1;
+    END LOOP;
+    RETURN ((l1 << 15) + r1);
+  END;
+$$;

data/lib/pg_random_id/sql.rb

@@ -0,0 +1,37 @@
+module PgRandomId
+  module Sql
+    class << self
+      def install
+        FILES.map {|f| read_file f}.join
+      end
+      
+      def apply table, column, key = nil, base = nil
+        key ||= rand(2**15)
+        base ||= sequence_nextval "#{table}_#{column}_seq"
+        "ALTER TABLE #{table} ALTER COLUMN #{column} SET DEFAULT pri_scramble(#{key}, #{base})"
+      end
+      
+      def apply_str table, column, key = nil, base = nil
+        key ||= rand(2**15)
+        base ||= sequence_nextval "#{table}_#{column}_seq"
+        """
+          ALTER TABLE #{table} ALTER COLUMN #{column} SET DATA TYPE character(6);
+          ALTER TABLE #{table} ALTER COLUMN #{column} SET DEFAULT lpad(crockford(pri_scramble(#{key}, #{base})), 6, '0');
+        """
+      end
+      
+      private
+
+      FILES = %w(scramble.sql crockford.sql)
+      BASEDIR = File.expand_path 'sql', File.dirname(__FILE__)
+      
+      def read_file filename
+        File.read(File.expand_path(filename, BASEDIR))
+      end
+      
+      def sequence_nextval sequence_name
+        "nextval('#{sequence_name}'::regclass)"
+      end
+    end
+  end
+end

data/lib/pg_random_id/version.rb

@@ -0,0 +1,3 @@
+module PgRandomId
+  VERSION = "0.0.1"
+end

data/lib/pg_random_id.rb

@@ -0,0 +1,9 @@
+require "pg_random_id/sql"
+require "pg_random_id/version"
+
+if defined? ActiveRecord
+  require "pg_random_id/migrations/active_record"
+end
+
+module PgRandomId
+end

data/pg_random_id.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'pg_random_id/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "pg_random_id"
+  gem.version       = PgRandomId::VERSION
+  gem.authors       = ["Rafał Rzepecki"]
+  gem.email         = ["divided.mind@gmail.com"]
+  gem.description   = %q{Easily use randomized integers instead of sequential values for your record surrogate ids.}
+  gem.summary       = %q{Pseudo-random record ids in Postgres}
+  gem.homepage      = "https://github.com/dividedmind/pg_random_id"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+  
+  %w(activerecord rspec).each do |g|
+    gem.add_development_dependency g
+  end
+end

data/spec/helpers/active_record_helper.rb

@@ -0,0 +1,19 @@
+shared_context 'active_record' do
+  before do
+    dburl = ENV['TEST_DATABASE_URL'] || 'postgres:///pg_random_id_test'
+    ActiveRecord::Base.establish_connection dburl
+    ActiveRecord::Base.connection.execute 'BEGIN;'
+  end
+
+  after do
+    ActiveRecord::Base.connection.execute 'ROLLBACK;'
+  end
+  
+  let(:migration) {
+    Class.new(ActiveRecord::Migration)
+  }
+
+  def execute code
+    ActiveRecord::Base.connection.select_one(code)
+  end
+end

data/spec/migrations/active_record_spec.rb

@@ -0,0 +1,73 @@
+require 'spec_helper'
+
+require 'active_record'
+require 'pg_random_id/migrations/active_record'
+
+describe PgRandomId::Migrations::ActiveRecord do
+  include_context 'active_record'
+  describe '#create_random_id_functions' do
+    it "installs the pri_scramble function" do
+      migration.create_random_id_functions
+      
+      execute("SELECT 1 FROM pg_proc WHERE proname = 'crockford'").should be
+      execute("SELECT 1 FROM pg_proc WHERE proname = 'pri_scramble'").should be
+    end
+  end
+  
+  describe '#random_id' do
+    it "changes the default value" do
+      migration.create_random_id_functions
+      migration.create_table :foo
+      migration.random_id :foo
+      execute("SELECT 1 FROM pg_attrdef WHERE adrelid = 'foo'::regclass AND adsrc LIKE '%pri_scramble%'").should be
+    end
+
+    it "creates a few values without error" do
+      migration.create_random_id_functions
+      migration.create_table :foo
+      migration.random_id :foo
+      10.times do
+        expect {
+          ActiveRecord::Base.connection.execute('INSERT INTO foo VALUES(default)')
+        }.to_not raise_error
+      end
+      execute("SELECT COUNT(*) FROM foo")['count'].to_i.should == 10
+    end
+  end
+
+  describe '#random_str_id' do
+    it "changes the default value" do
+      migration.create_random_id_functions
+      migration.create_table :foo
+      migration.random_str_id :foo
+      execute("SELECT 1 FROM pg_attrdef WHERE adrelid = 'foo'::regclass AND adsrc LIKE '%pri_scramble%'").should be
+      execute("SELECT 1 FROM pg_attrdef WHERE adrelid = 'foo'::regclass AND adsrc LIKE '%crockford%'").should be
+      execute("INSERT INTO foo VALUES (DEFAULT) RETURNING id;")['id'].should_not == '1'
+    end
+
+    it "changes the type" do
+      migration.create_random_id_functions
+      migration.create_table :foo
+      migration.random_str_id :foo
+      execute("""
+        SELECT typname FROM pg_attribute, pg_type 
+          WHERE attrelid = 'foo'::regclass 
+            AND attname = 'id' 
+            AND atttypid = typelem 
+            AND typname LIKE '%int%'
+      """).should_not be
+    end
+
+    it "creates a few values without error" do
+      migration.create_random_id_functions
+      migration.create_table :foo
+      migration.random_str_id :foo
+      10.times do
+        expect {
+          ActiveRecord::Base.connection.execute('INSERT INTO foo VALUES(default)')
+        }.to_not raise_error
+      end
+      execute("SELECT COUNT(*) FROM foo")['count'].to_i.should == 10
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require 'helpers/active_record_helper'

data/spec/sql/crockford_spec.rb

@@ -0,0 +1,30 @@
+require 'spec_helper'
+
+require 'active_record'
+require 'pg_random_id/migrations/active_record'
+
+describe 'crockford(bigint)' do
+  include_context 'active_record'
+  before do
+    migration.create_random_id_functions
+  end
+  
+  def crockford argument
+    execute("SELECT crockford(#{argument})")['crockford']
+  end
+
+  it "returns correct encodings for a few chosen values" do
+    {
+      0 => '0',
+      1 => '1',
+      31 => 'z',
+      32 => '10',
+      1712969022158652754 => '1fhdg7zyg7haj',
+      9223372036854775807 => '7zzzzzzzzzzzz'
+    }.each {|k, v| crockford(k).should == v}
+  end
+  
+  it "errors out on negative numbers" do
+    expect{crockford(-1)}.to raise_error
+  end
+end

data/spec/sql/scramble_spec.rb

@@ -0,0 +1,18 @@
+require 'spec_helper'
+
+require 'active_record'
+require 'pg_random_id/migrations/active_record'
+
+describe "pri_scramble(bigint, bigint)" do
+  include_context 'active_record'
+  before do
+    migration.create_random_id_functions
+  end
+  
+  it "seems to have no collisions" do
+    COUNT = 10000
+    KEY = rand(2**32)
+    CODE = "SELECT COUNT(DISTINCT pri_scramble(#{KEY}, seq)) FROM generate_series(1, #{COUNT}) AS s(seq)"
+    execute(CODE)['count'].to_i.should == COUNT
+  end
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: pg_random_id
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Rafał Rzepecki
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Easily use randomized integers instead of sequential values for your
+  record surrogate ids.
+email:
+- divided.mind@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/pg_random_id.rb
+- lib/pg_random_id/migrations/active_record.rb
+- lib/pg_random_id/sql.rb
+- lib/pg_random_id/sql/crockford-pure.sql
+- lib/pg_random_id/sql/crockford.sql
+- lib/pg_random_id/sql/scramble.sql
+- lib/pg_random_id/version.rb
+- pg_random_id.gemspec
+- spec/helpers/active_record_helper.rb
+- spec/migrations/active_record_spec.rb
+- spec/spec_helper.rb
+- spec/sql/crockford_spec.rb
+- spec/sql/scramble_spec.rb
+homepage: https://github.com/dividedmind/pg_random_id
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Pseudo-random record ids in Postgres
+test_files:
+- spec/helpers/active_record_helper.rb
+- spec/migrations/active_record_spec.rb
+- spec/spec_helper.rb
+- spec/sql/crockford_spec.rb
+- spec/sql/scramble_spec.rb
+has_rdoc: