pg_random_id 0.0.1 → 0.1.0

data/README.md

@@ -2,9 +2,19 @@
 
 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...).
+sequence of unique 30-bits nonnegative integer values (eg. 760280231, 110168588, 1029278017...)
+or 6-character human-friendly-ish strings (eg. kn5xx1, qy2kp8, e5f67z...).
 
-Integrates with ActiveRecord. Sequel integration is upcoming.
+Since surrogate IDs are often used in REST-ful URLs, this makes the addresses less revealing and harder to guess
+(while preserving the straightforward mapping from URLs to database IDs):
+- http://example.com/products/1 → http://example.com/products/134178313
+- http://example.com/products/2 → http://example.com/products/121521131
+- http://example.com/widgets/1 → http://example.com/widgets/2agc30
+- http://example.com/widgets/2 → http://example.com/widgets/4zkabg
+
+
+Although the code is 100% database-side, it has been packaged into Ruby functions plugging 
+into ActiveRecord and Sequel migrations for ease of use.
 
 ## Installation
 
@@ -20,49 +30,103 @@ Or install it yourself as:
 
     $ gem install pg_random_id
 
-## Usage
+## Synopsis
 
-The easiest way to use it is to use the supplied migration functions.
+### ActiveRecord
 
-First, make sure you put
+```ruby
+class InstallRandomId < ActiveRecord::Migration
+  def up
+    # install the necessary SQL functions in the DB
     create_random_id_functions
-in a migration (a single one will do).
+  end
+end
 
-Then to apply random ids to a table, use random_id function:
+class CreateProducts < ActiveRecord::Migration
+  def up
+    create_table :products do |t|
+      t.string :name
+    end
+    
+    # make the table use random ids
+    random_id :products
+  end
+end
 
-```ruby
-class RandomizeIdsOnFoo < ActiveRecord::Migration
+class RandomizeIdsOnWidgets < ActiveRecord::Migration
   def up
-    KEY = 21315
-    random_id :foo, :foo_id, KEY
+    # make ids on a previously created table 
+    # 'widgets' random (using string ids)
+    random_str_id :widgets, :widget_id # you can specify id column name
   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:
+### Sequel
 
 ```ruby
-class CreateProducts < ActiveRecord::Migration
-  def up
-    create_table :products do |t|
-      t.string :name
+Sequel.migration do
+  up do
+    # install the necessary SQL functions in the DB
+    create_random_id_functions
+  end
+end
+
+Sequel.migration do
+  up do
+    create_table :products do
+      primary_key :id
+      String :name
     end
+    
+    # make the table use random ids
     random_id :products
   end
 end
+
+Sequel.migration do
+  up do
+    # make ids on a previously created table 
+    # 'widgets' random (using string ids)
+    random_str_id :widgets, :widget_id # you can specify id column name
+  end
+end
 ```
 
+## Considerations
+
 No model modification is necessary, just use the table as usual and it will simply work.
-You can even use it without ActiveRecord.
+Each table will use its own unique sequence, chosen at random at migration time.
+
+If you use `random_str_id` make sure to use a string type in 
+foreign key columns:
+```ruby
+class CreateContraptions < ActiveRecord::Migration
+  def up
+    create_table :contraptions do |t|
+      t.string :widget_id, limit: 6
+    end
+  end
+end
+```
+```ruby
+Sequel.migration do
+  up do
+    create_table :contraptions do
+      String :widget_id, size: 6
+    end
+  end
+end
+```
+
+## Notes
 
-### Text ids
+The `random_id` function changes the default value of the ID column to a scrambled next sequence value.
+The scrambling function is a simple Feistel network, with a variable parameter which is used to choose the sequence.
 
-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...).
+With `random_str_id` function, the column type is changed to character(6)
+and the sequence is additionally base32-encoded 
+with [Crockford encoding](http://www.crockford.com/wrmg/base32.html).
 
 ## Contributing
 

data/lib/pg_random_id.rb

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

data/lib/pg_random_id/migrations.rb

@@ -0,0 +1,43 @@
+require 'pg_random_id/sql'
+
+module PgRandomId
+  module Migrations
+    # Create in the database the functions
+    # 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
+    
+    # Install the migration functions for ActiveRecord
+    def self.install_active_record
+      require 'active_record/migration'
+      ActiveRecord::Migration.send :include, self
+    end
+
+    # Install the migration functions for Sequel
+    def self.install_sequel
+      Sequel::Database.send :include, self
+    end
+  end
+end
+
+PgRandomId::Migrations::install_active_record if defined? ActiveRecord
+PgRandomId::Migrations::install_sequel if defined? Sequel

data/lib/pg_random_id/version.rb

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

data/pg_random_id.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |gem|
   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.description   = %q{Easily use randomized keys 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"
 
@@ -17,7 +17,7 @@ Gem::Specification.new do |gem|
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
   
-  %w(activerecord rspec).each do |g|
+  %w(activerecord rspec sequel).each do |g|
     gem.add_development_dependency g
   end
 end

data/spec/helpers/active_record_helper.rb

@@ -1,9 +1,15 @@
 shared_context 'active_record' do
+  require 'active_record'
+  
   before do
     dburl = ENV['TEST_DATABASE_URL'] || 'postgres:///pg_random_id_test'
     ActiveRecord::Base.establish_connection dburl
     ActiveRecord::Base.connection.execute 'BEGIN;'
   end
+  
+  before do
+    ActiveRecord::Migration.verbose = false
+  end
 
   after do
     ActiveRecord::Base.connection.execute 'ROLLBACK;'
@@ -16,4 +22,8 @@ shared_context 'active_record' do
   def execute code
     ActiveRecord::Base.connection.select_one(code)
   end
+  
+  def create_table *a
+    migration.create_table *a
+  end
 end

data/spec/{migrations/active_record_spec.rb → helpers/migration_spec_helper.rb}

@@ -1,12 +1,6 @@
-require 'spec_helper'
-
-require 'active_record'
-require 'pg_random_id/migrations/active_record'
-
-describe PgRandomId::Migrations::ActiveRecord do
-  include_context 'active_record'
+shared_context 'test_migration' do
   describe '#create_random_id_functions' do
-    it "installs the pri_scramble function" do
+    it "installs the functions" do
       migration.create_random_id_functions
       
       execute("SELECT 1 FROM pg_proc WHERE proname = 'crockford'").should be
@@ -17,37 +11,37 @@ describe PgRandomId::Migrations::ActiveRecord do
   describe '#random_id' do
     it "changes the default value" do
       migration.create_random_id_functions
-      migration.create_table :foo
+      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
+      create_table :foo
       migration.random_id :foo
       10.times do
         expect {
-          ActiveRecord::Base.connection.execute('INSERT INTO foo VALUES(default)')
+          execute('INSERT INTO foo VALUES(default)')
         }.to_not raise_error
       end
-      execute("SELECT COUNT(*) FROM foo")['count'].to_i.should == 10
+      execute("SELECT COUNT(*) FROM foo").first[1].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
+      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'
+      execute("INSERT INTO foo VALUES (DEFAULT) RETURNING id;").first[1].should_not == '1'
     end
 
     it "changes the type" do
       migration.create_random_id_functions
-      migration.create_table :foo
+      create_table :foo
       migration.random_str_id :foo
       execute("""
         SELECT typname FROM pg_attribute, pg_type 
@@ -60,14 +54,14 @@ describe PgRandomId::Migrations::ActiveRecord do
 
     it "creates a few values without error" do
       migration.create_random_id_functions
-      migration.create_table :foo
+      create_table :foo
       migration.random_str_id :foo
       10.times do
         expect {
-          ActiveRecord::Base.connection.execute('INSERT INTO foo VALUES(default)')
+          execute('INSERT INTO foo VALUES(default)')
         }.to_not raise_error
       end
-      execute("SELECT COUNT(*) FROM foo")['count'].to_i.should == 10
+      execute("SELECT COUNT(*) FROM foo").first[1].to_i.should == 10
     end
   end
 end

data/spec/helpers/sequel_helper.rb

@@ -0,0 +1,24 @@
+shared_context 'sequel' do
+  require 'sequel'
+  
+  let(:dburl) { ENV['TEST_DATABASE_URL'] || 'postgres:///pg_random_id_test' }
+  let(:db) { Sequel::connect dburl }
+  
+  around do |example|
+    db.transaction rollback: :always do
+      example.run
+    end
+  end
+  
+  let(:migration) { db }
+
+  def execute code
+    db[code].first
+  end
+  
+  def create_table *a
+    db.create_table *a do
+      primary_key :id
+    end
+  end
+end

data/spec/migrations_spec.rb

@@ -0,0 +1,15 @@
+require 'spec_helper'
+
+describe PgRandomId::Migrations do
+  context "with ActiveRecord" do
+    include_context 'active_record'
+    PgRandomId::Migrations.install_active_record
+    include_context 'test_migration'
+  end
+
+  context "with Sequel" do
+    include_context 'sequel'
+    PgRandomId::Migrations.install_sequel
+    include_context 'test_migration'
+  end
+end

data/spec/spec_helper.rb

@@ -1 +1,5 @@
+require 'pg_random_id'
+
 require 'helpers/active_record_helper'
+require 'helpers/migration_spec_helper'
+require 'helpers/sequel_helper'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pg_random_id
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-05 00:00:00.000000000 Z
+date: 2013-02-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -43,8 +43,24 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: Easily use randomized integers instead of sequential values for your
-  record surrogate ids.
+- !ruby/object:Gem::Dependency
+  name: sequel
+  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 keys instead of sequential values for your record
+  surrogate ids.
 email:
 - divided.mind@gmail.com
 executables: []
@@ -57,7 +73,7 @@ files:
 - README.md
 - Rakefile
 - lib/pg_random_id.rb
-- lib/pg_random_id/migrations/active_record.rb
+- lib/pg_random_id/migrations.rb
 - lib/pg_random_id/sql.rb
 - lib/pg_random_id/sql/crockford-pure.sql
 - lib/pg_random_id/sql/crockford.sql
@@ -65,7 +81,9 @@ files:
 - lib/pg_random_id/version.rb
 - pg_random_id.gemspec
 - spec/helpers/active_record_helper.rb
-- spec/migrations/active_record_spec.rb
+- spec/helpers/migration_spec_helper.rb
+- spec/helpers/sequel_helper.rb
+- spec/migrations_spec.rb
 - spec/spec_helper.rb
 - spec/sql/crockford_spec.rb
 - spec/sql/scramble_spec.rb
@@ -95,7 +113,9 @@ 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/helpers/migration_spec_helper.rb
+- spec/helpers/sequel_helper.rb
+- spec/migrations_spec.rb
 - spec/spec_helper.rb
 - spec/sql/crockford_spec.rb
 - spec/sql/scramble_spec.rb

data/lib/pg_random_id/migrations/active_record.rb

@@ -1,35 +0,0 @@
-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