active_record_uuid 0.1.0 → 0.2.0

data/README.md

@@ -2,6 +2,18 @@
 
 `active_record_uuid` is a nice gem that add uuid supports to your `activerecord` models (MySQL). It allows you to store uuid in various formats: binary (16 bytes), base64 (24 bytes), hexdigest (32 bytes), or string (36 bytes), and query back with uuid string.
 
+The performance issues arises when you store primary key in large data size. You have two options:
+- use `auto-increment` primary key along with uuid column
+- use `uuid` primary key, but store in binary format
+
+You have various choices when storing uuid:
+- binary format, 16 bytes
+- base64 format, 24 bytes (encode uuid into base64)
+- hexdigest, 32 bytes string (compact uuid format, without dash)
+- string, 36 bytes string (full length uuid)
+
+Check this out for more detail, [http://www.mysqlperformanceblog.com/2007/03/13/to-uuid-or-not-to-uuid/](http://www.mysqlperformanceblog.com/2007/03/13/to-uuid-or-not-to-uuid/).
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -18,7 +30,11 @@ Or install it yourself as:
     
 ## Upgrade from version 0.0.1
 
-`ActiveRecordBase::UuidBase` and `UuidBaseHelper` are depreciated. Right now, you can configure your model by using `uuid_config` and inherit from `ActiveRecord::Base`. Check out the usage below.
+`ActiveRecordBase::UuidBase` and `UuidBaseHelper` are depreciated. Right now, you can configure your model by using `has_uuid` and inherit from `ActiveRecord::Base`. Check out the usage below.
+
+## Upgrade from version 0.1.0
+
+`uuid_config` is fine, but I like to use `has_uuid` and passing in options instead.
 
 ## Usage
 
@@ -33,46 +49,42 @@ If you need to use `uuid` column as primary key, don't add any `:primary_key` in
     $ rake db:add_primary_keys            # Add primary keys to all models
     $ rake db:add_primary_key[model_name] # Add primary key to a model
 
-The performance issues arises when you store primary key in large data size. You have two options:
-- use `auto-increment` primary key along with uuid column
-- use `uuid` primary key, but store in binary format
-
-You have various choices when storing uuid:
-- binary format, 16 bytes
-- base64 format, 24 bytes (encode uuid into base64)
-- hexdigest, 32 bytes string (compact uuid format, without dash)
-- string, 36 bytes string (full length uuid)
-
 ### Migration
 
-In order for the gem to work well, you need to specify the column `type` and `limit` correctly according to your `uuid_config` (`store_as`).
+In order for the gem to work well, you need to specify the column `type` and `limit` correctly according to your `has_uuid` (`store_as` option).
 
     create_table :posts, :force => true, :id => false do |t|
-      t.binary :uuid, :limit => 16 # must set to the correct value
+      t.binary :uuid, :limit => 16 # `must set to the correct value`
       t.string :text
       t.timestamps
     end
     
     class Post < ActiveRecord::Base
-      uuid_config do
-        primary_key true
-        store_as    :binary
-      end
+      has_uuid :primary_key => true, :store_as => :binary
     end
+    
+### General configuration options
 
-### Configuring your model
+You can configure using `ActiveRecordUuid.configure`, and it will apply to any models which use `has_uuid`. Each model can overwrite the general options by passing options into `has_uuid`. The following are default values:
+
+    column      :uuid           # :uuid is default
+    primary_key true            # false is default
+    association false           # false is default
+    generator   :timestamp      # :timestamp is default
+    store_as    :string         # :string is default
+    hook        :before_create  # :before_validation is default
+    
+There's a config generator that generates the default configuration file into config/initializers directory.
+Run the following generator command, then edit the generated file.
 
-To use uuid in your model, call `uuid_config` in your model.
+    $ rails g active_record_uuid:config
+
+### Model configuration
+
+To use uuid in your model, call `has_uuid` in your model.
 
     class Post < ActiveRecord::Base
-      uuid_config do
-        column      :uuid       # :uuid is default
-        primary_key true        # false is default
-        association false       # false is default
-        generator   :timestamp  # :timestamp is default
-        store_as    :string     # :string is default
-        hook        :before_create # :before_validation is default
-      end
+      has_uuid :primary_key => true, :hook => :before_create
     end
     
     # create a post with auto-generated uuid
@@ -100,10 +112,7 @@ To use uuid in your model, call `uuid_config` in your model.
 ### Binary uuid model (example)
 
     class PostBinary < ActiveRecord::Base
-      uuid_config do
-        primary_key true
-        store_as    :binary
-      end
+      has_uuid :primary_key => true, :store_as => :binary
     end
     
     post = PostBinary.create(:text => "Binary uuid1")
@@ -123,7 +132,7 @@ To use uuid in your model, call `uuid_config` in your model.
     post.reload
     post.attributes_before_type_cast["uuid"]["value"]
 
-### Avaliable options inside `uuid_config`
+### Avaliable options inside `has_uuid`
 #### `column` option
 
 Set the column name to store uuid value.
@@ -149,42 +158,27 @@ Specify the activerecord hook `[:after_initialize, :before_validation, :before_c
 When you set this option to `true`, it expects you have foreign_keys with `_uuid`. Therefore, you don't have to pass `:foreign_key` option inside association methods
 
     class Author < ActiveRecord::Base
-      uuid_config do
-        primary_key true
-        association true
-      end
+      has_uuid :primary_key => true, :association => true
       has_and_belongs_to_many :posts
     end
 
     class Post < ActiveRecord::Base
-      uuid_config do
-        primary_key true
-        association true
-      end
+      has_uuid :primary_key => true, :association => true
       has_many :comments
       has_one  :comment
       has_and_belongs_to_many :authors
     end
 
     class Comment < ActiveRecord::Base
-      uuid_config do
-        primary_key true
-        association true
-      end
+      has_uuid :primary_key => true, :association => true
       belongs_to :post
     end
 
     # overwrite :foreign_key option and add additional option
     class Post < ActiveRecord::Base
-      uuid_config do
-        primary_key true
-        association true
-      end
+      has_uuid :primary_key => true, :association => true
       has_many :comments, :foreign_key => "comment_id", :inverse_of => :post
     end
     
 ## Testing
 This gem will set the format for dumping the database schema to `:sql`. This means that it is no longer dump the schema to ruby code but database-independent version, `db/structure.sql`. Therefore, you would not have any problems when running the tests.
-
-## References
-- [http://www.mysqlperformanceblog.com/2007/03/13/to-uuid-or-not-to-uuid/](http://www.mysqlperformanceblog.com/2007/03/13/to-uuid-or-not-to-uuid/)

data/lib/active_record_uuid.rb

@@ -7,8 +7,20 @@ module ActiveRecordUuid
   autoload :VERSION,            'active_record_uuid/version'
   autoload :Config,             'active_record_uuid/config'
   autoload :Serializer,         'active_record_uuid/serializer'
-  autoload :AssociationMethods, 'active_record_uuid/association_methods'
+  autoload :AssociationMethods, 'active_record_uuid/extensions/association_methods'
+  autoload :QuotingExtension,   'active_record_uuid/extensions/quoting_extension'
   autoload :Model,              'active_record_uuid/model'
+  autoload :Hooks,              'active_record_uuid/hooks'
+  
+  def self.configure(&block)
+    @config = ActiveRecordUuid::Config.new
+    @config.instance_eval(&block)
+    @config.validate_options!
+  end
+  
+  def self.config
+    @config || ActiveRecordUuid::Config.new
+  end
 end
 
 require 'active_record_uuid/uuid_base'

data/lib/active_record_uuid/config.rb

@@ -1,22 +1,37 @@
 module ActiveRecordUuid
   class Config
-    def initialize
-      @column      = :uuid
-      @primary_key = false
-      @association = false
-      @generator   = :timestamp
-      @store_as    = :string
-      @hook        = :before_validation
+    def initialize(options = {})
+      default_options = {
+        :column      => :uuid,
+        :primary_key => false,
+        :association => false,
+        :generator   => :timestamp,
+        :store_as    => :string,
+        :hook        => :before_validation
+      }
+      options = default_options.merge(options)
+      
+      options.each_pair do |key, value|
+        send(key.to_sym, value)
+      end
     end
     
     METHODS = [:column, :primary_key, :association, :generator, :store_as, :hook]
     METHODS.each do |meth|
       define_method(meth.to_sym) do |value=nil|
-        instance_variable_set("@#{meth}".to_sym, value) if value
+        instance_variable_set("@#{meth}".to_sym, value) if value.to_s.present?
         instance_variable_get("@#{meth}")
       end
     end
     
+    def to_hash
+      METHODS.inject({}) do |result, key|
+        result[key] = send(key)
+        
+        result
+      end
+    end
+    
     def validate_options!
       default_generators = [:timestamp, :random]
       raise ArgumentError,

data/lib/active_record_uuid/extensions/quoting_extension.rb

@@ -14,7 +14,7 @@ module ActiveRecordUuid
 
         case column.type
         when :binary
-          "BINARY x'#{uuid.hexdigest}'"
+          "x'#{uuid.hexdigest}'"
         when :string
           case column.limit
           when 24

data/lib/active_record_uuid/hooks.rb

@@ -0,0 +1,10 @@
+module ActiveRecordUuid
+  class Hooks
+    def self.init
+      ActiveSupport.on_load(:active_record) do |app|
+        ::ActiveRecord::Base.connection.class.send :include, ActiveRecordUuid::QuotingExtension
+        ::ActiveRecord::Base.send(:include, ActiveRecordUuid::Model)
+      end
+    end
+  end
+end

data/lib/active_record_uuid/model.rb

@@ -27,12 +27,16 @@ module ActiveRecordUuid::Model
     end
     
     private
+    def uuid_config
+      self.class.uuid_config
+    end
+    
     def assign_uuid_when_blank
       assign_uuid if uuid_value.blank?
     end
     
     def uuid_column
-      self.class.uuid_config.column
+      uuid_config.column
     end
     
     def validates_uuid
@@ -40,27 +44,37 @@ module ActiveRecordUuid::Model
     end
   end
 
-  module ClassMethods 
+  module ClassMethods
+    def generate_uuid
+      UUIDTools::UUID.send("#{uuid_config.generator}_create").to_s
+    end
+    
     def uuid_config(&block)
-      return @config if @config.present?
+      return @uuid_config if @uuid_config.present?
       
-      @config = ActiveRecordUuid::Config.new
-      @config.instance_eval(&block) if block_given?
-      @config.validate_options!
-
-      column_name = @config.column.to_sym
-      self.primary_key              = column_name if @config.primary_key
-      self.serialize                column_name, ActiveRecordUuid::Serializer.new(@config.store_as)
-      self.send(@config.hook,       :assign_uuid_when_blank)
-      self.validates_uniqueness_of  column_name, :if => Proc.new { |r| r.uuid_value.present? }
-      self.validate                 :validates_uuid , :if => Proc.new { |r| r.uuid_value.present? }
-      self.send(:extend, ActiveRecordUuid::AssociationMethods) if @config.association
+      @uuid_config = ActiveRecordUuid::Config.new
+      if block_given?
+        @uuid_config.instance_eval(&block)
+        @uuid_config.validate_options!
+      end
       
-      @config
+      # apply uuid based on config
+      has_uuid(@uuid_config.to_hash)
+      
+      @uuid_config
     end
     
-    def generate_uuid
-      UUIDTools::UUID.send("#{uuid_config.generator}_create").to_s
+    def has_uuid(options = {})
+      options = ActiveRecordUuid.config.to_hash.merge(options)
+      @uuid_config = ActiveRecordUuid::Config.new(options)
+      
+      column_name = uuid_config.column.to_sym
+      self.primary_key              = column_name if uuid_config.primary_key
+      self.serialize                column_name, ActiveRecordUuid::Serializer.new(uuid_config.store_as)
+      self.send(uuid_config.hook,   :assign_uuid_when_blank)
+      self.validates_uniqueness_of  column_name, :if => Proc.new { |r| r.uuid_value.present? }
+      self.validate                 :validates_uuid, :if => Proc.new { |r| r.uuid_value.present? }
+      self.send(:extend, ActiveRecordUuid::AssociationMethods) if uuid_config.association
     end
   end
 end

data/lib/active_record_uuid/rails/generators/config_generator.rb

@@ -0,0 +1,16 @@
+module ActiveRecordUuid
+  module Generators
+    class ConfigGenerator < Rails::Generators::Base
+      source_root File.expand_path(File.join(File.dirname(__FILE__), 'templates'))
+
+      desc <<DESC
+Description:
+  Copies ActiveRecordUuid configuration file to your application's initializer directory.
+DESC
+
+      def copy_config_file
+        template 'active_record_uuid_config.rb', 'config/initializers/active_record_uuid_config.rb'
+      end
+    end
+  end
+end

data/lib/active_record_uuid/rails/generators/templates/active_record_uuid_config.rb

@@ -0,0 +1,8 @@
+ActiveRecordUuid.configure do
+  # column      :uuid
+  # primary_key false
+  # association false
+  # generator   :timestamp
+  # store_as    :string
+  # hook        :before_validation
+end

data/lib/active_record_uuid/rails/railtie.rb

@@ -3,17 +3,15 @@ module ActiveRecordUuid
     config.active_record.schema_format = :sql
     
     initializer :after => 'active_record.initialize_database' do
-    
-      ActiveSupport.on_load(:active_record) do |app|
-        require 'active_record_uuid/extensions/quoting_extension'
-        
-        ::ActiveRecord::Base.connection.class.send :include, ActiveRecordUuid::QuotingExtension
-        ::ActiveRecord::Base.send(:include, ActiveRecordUuid::Model)
-      end
+      ActiveRecordUuid::Hooks.init
     end
     
     rake_tasks do
       load "active_record_uuid/rails/db.rake"
     end
+    
+    generators do
+      require 'active_record_uuid/rails/generators/config_generator'
+    end
   end
 end

data/lib/active_record_uuid/uuid_base.rb

@@ -4,7 +4,7 @@ class ActiveRecord::UuidBase < ::ActiveRecord::Base
   class << self
     def inherited_with_uuid(kls)
       inherited_without_uuid kls
-      warn "[DEPRECATION] `UuidBaseHelper` and `ActiveRecord::UuidBase` are deprecated.  Please inherit from `ActiveRecord::Base` and use `uuid_config` instead."
+      warn "[DEPRECATION] `UuidBaseHelper` and `ActiveRecord::UuidBase` are deprecated.  Please inherit from `ActiveRecord::Base` and use `has_uuid` instead."
       kls.uuid_config do
         primary_key true
         association true
@@ -15,7 +15,7 @@ class ActiveRecord::UuidBase < ::ActiveRecord::Base
   end
 
   self.descendants.each do |kls|
-    warn "[DEPRECATION] `UuidBaseHelper` and `ActiveRecord::UuidBase` are deprecated.  Please inherit from `ActiveRecord::Base` and use `uuid_config` instead."
+    warn "[DEPRECATION] `UuidBaseHelper` and `ActiveRecord::UuidBase` are deprecated.  Please inherit from `ActiveRecord::Base` and use `has_uuid` instead."
     kls.uuid_config do
       primary_key true
       association true

data/lib/active_record_uuid/uuid_base_helper.rb

@@ -1,6 +1,6 @@
 module UuidBaseHelper
   def self.included(base)
-    warn "[DEPRECATION] `UuidBaseHelper` and `ActiveRecord::UuidBase` are deprecated.  Please inherit from `ActiveRecord::Base` and use `uuid_config` instead."
+    warn "[DEPRECATION] `UuidBaseHelper` and `ActiveRecord::UuidBase` are deprecated.  Please inherit from `ActiveRecord::Base` and use `has_uuid` instead."
     
     base.send(:include, ActiveRecordUuid::Model)
     base.uuid_config do

data/lib/active_record_uuid/version.rb

@@ -1,3 +1,3 @@
 module ActiveRecordUuid
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/spec/lib/config_spec.rb

@@ -12,6 +12,13 @@ describe "Uuid Config" do
     @config.hook.should eq(:before_validation)
   end
   
+  it "should initialize with provided values" do
+    @config = ActiveRecordUuid::Config.new(:primary_key => true, :column => :my_uuid)
+    
+    @config.primary_key.should eq(true)
+    @config.column.should eq(:my_uuid)
+  end
+  
   it "should validate options: generator" do
     @config = ActiveRecordUuid::Config.new
     
@@ -38,4 +45,13 @@ describe "Uuid Config" do
       @config.validate_options!
     }.should raise_error ArgumentError, /^Expected :before_validation/
   end
+  
+  it "should return as a hash with appropriate value" do
+    @config = ActiveRecordUuid::Config.new(:primary_key => true, :column => :my_uuid)
+    
+    hash = @config.to_hash
+    hash.should be_instance_of(Hash)
+    hash[:primary_key].should eq(@config.primary_key)
+    hash[:column].should eq(@config.column)
+  end
 end

data/spec/lib/has_uuid_spec.rb

@@ -0,0 +1,59 @@
+require 'spec_helper'
+
+describe "has_uuid spec" do
+  context "per model" do
+    it "should have uuid as primary key based config" do
+      People.primary_key.should eq('uuid')
+    end
+    
+    it "should store uuid as binary" do
+      person = People.create(:name => "Binary name1")
+      person.reload
+      
+      person.attributes_before_type_cast["uuid"]["value"].bytesize.should eq(16)
+    end
+    
+    it "should find by uuid column" do
+      person = People.create(:name => "Binary name2")
+
+      People.find_by_uuid(person.uuid).should   eq(person)
+      People.where(:uuid => person.uuid).should eq([person])
+    end
+  end
+  
+  context "global" do
+    before(:all) do
+      ActiveRecordUuid.configure do
+        column      :uuid
+        primary_key true
+        association false
+        store_as    :binary
+      end
+      
+      class PeopleBinary < ActiveRecord::Base
+        self.table_name = "people"
+        has_uuid :association => true
+        has_many :comments
+      end
+    end
+    
+    it "should use global configuration" do
+      PeopleBinary.uuid_config.store_as.should eq(:binary)
+    end
+    
+    it "should use overwrite global configuration" do
+      PeopleBinary.uuid_config.association.should eq(true)
+    end
+    
+    it "should apply based on configuration" do
+      PeopleBinary.reflections[:comments].options[:foreign_key].should eq("people_binary_uuid")
+    end
+    
+    it "should store uuid as binary" do
+      person = PeopleBinary.create!(:name => "Binary name1")
+      person.reload
+      
+      person.attributes_before_type_cast["uuid"]["value"].bytesize.should eq(16)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -4,7 +4,7 @@ db_config = {
   :adapter => "mysql2", 
   :database => "active_record_uuid",
   :user => "root",
-  :password => "Q1p2m3g4"
+  :password => ""
 }
 
 ActiveRecord::Base.establish_connection(db_config) rescue nil
@@ -13,10 +13,8 @@ ActiveRecord::Base.establish_connection(db_config.merge(:database => nil))
 ActiveRecord::Base.connection.create_database(db_config[:database], { :charset => 'utf8', :collation => 'utf8_unicode_ci' })
 ActiveRecord::Base.establish_connection(db_config)
 
-# load extension
-require 'active_record_uuid/extensions/quoting_extension'
-::ActiveRecord::Base.connection.class.send :include, ActiveRecordUuid::QuotingExtension
-::ActiveRecord::Base.send(:include, ActiveRecordUuid::Model)
+# load hooks
+ActiveRecordUuid::Hooks.init
 
 # load support
 load File.dirname(__FILE__) + '/support/schema.rb'

data/spec/support/models.rb

@@ -30,6 +30,11 @@ class PostBinary < ActiveRecord::Base
   has_many :comments
 end
 
+class People < ActiveRecord::Base
+  self.table_name = "people"
+  has_uuid :column => :uuid, :primary_key => true, :store_as => :binary
+end
+
 class PostBase64 < ActiveRecord::Base
   uuid_config do
     primary_key true

data/spec/support/schema.rb

@@ -19,6 +19,12 @@ ActiveRecord::Schema.define do
     t.timestamps
   end
   
+  create_table :people, :force => true, :id => false do |t|
+    t.binary :uuid, :limit => 16
+    t.string :name
+    t.timestamps
+  end
+  
   create_table :post_base64s, :force => true, :id => false do |t|
     t.string :uuid, :limit => 24
     t.string :text

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_record_uuid
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-06-20 00:00:00.000000000 Z
+date: 2012-07-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -126,11 +126,14 @@ files:
 - Rakefile
 - active_record_uuid.gemspec
 - lib/active_record_uuid.rb
-- lib/active_record_uuid/association_methods.rb
 - lib/active_record_uuid/config.rb
+- lib/active_record_uuid/extensions/association_methods.rb
 - lib/active_record_uuid/extensions/quoting_extension.rb
+- lib/active_record_uuid/hooks.rb
 - lib/active_record_uuid/model.rb
 - lib/active_record_uuid/rails/db.rake
+- lib/active_record_uuid/rails/generators/config_generator.rb
+- lib/active_record_uuid/rails/generators/templates/active_record_uuid_config.rb
 - lib/active_record_uuid/rails/railtie.rb
 - lib/active_record_uuid/serializer.rb
 - lib/active_record_uuid/uuid_base.rb
@@ -141,6 +144,7 @@ files:
 - spec/lib/binary_uuid_spec.rb
 - spec/lib/config_spec.rb
 - spec/lib/deprecation_spec.rb
+- spec/lib/has_uuid_spec.rb
 - spec/lib/hexdigest_uuid_spec.rb
 - spec/lib/serializer_spec.rb
 - spec/lib/string_uuid_spec.rb
@@ -178,6 +182,7 @@ test_files:
 - spec/lib/binary_uuid_spec.rb
 - spec/lib/config_spec.rb
 - spec/lib/deprecation_spec.rb
+- spec/lib/has_uuid_spec.rb
 - spec/lib/hexdigest_uuid_spec.rb
 - spec/lib/serializer_spec.rb
 - spec/lib/string_uuid_spec.rb