active_record_uuid 0.0.1 → 0.1.0

data/.rvmrc

@@ -6,7 +6,7 @@
 # First we specify our desired <ruby>[@<gemset>], the @gemset name is optional,
 # Only full ruby name is supported here, for short names use:
 #     echo "rvm use 1.9.3" > .rvmrc
-environment_id="ruby-1.9.3-p125@active_record_uuid"
+environment_id="ruby-1.9.3-p194@active_record_uuid"
 
 # Uncomment the following lines if you want to verify rvm version per project
 # rvmrc_rvm_version="1.12.1 (stable)" # 1.10.1 seams as a safe start

data/README.md

@@ -1,6 +1,6 @@
 # ActiveRecordUuid
 
-`active_record_uuid` is a nice and simple gem that add uuid support to your `activerecord` models, `associations`, `schema.rb`, and `rake script`.
+`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.
 
 ## Installation
 
@@ -15,36 +15,66 @@ And then execute:
 Or install it yourself as:
 
     $ gem install active_record_uuid
+    
+## Upgrade from version 0.0.1
 
-## Usage
+`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.
 
-This gem doesn't try to overwrite anything, it just makes use of existing activerecord apis in order to work with `uuid`.
+## Usage
 
-In your migration files, you don't add any `:primary`, because it will make that column as auto-increment integer primary key. Do something like this:
+If you need to use `uuid` column as primary key, don't add any `:primary_key` in migration file, because it will make that column as auto-increment integer primary key. Instead, do something like this:
 
     create_table :posts, :force => true, :id => false do |t|
       t.string :uuid, :limit => 36
       t.string :text
       t.timestamps
     end
-    
-Add primary keys to all tables
 
-    $ rake db:add_primary_keys
+    $ rake db:add_primary_keys            # Add primary keys to all models
+    $ rake db:add_primary_key[model_name] # Add primary key to a model
 
-There are two ways you can use this gem: by `inherit` and `include`.
+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
 
-    class Post < ActiveRecord::UuidBase
-    end
+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)
 
-Or
+### 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`).
+
+    create_table :posts, :force => true, :id => false do |t|
+      t.binary :uuid, :limit => 16 # must set to the correct value
+      t.string :text
+      t.timestamps
+    end
+    
     class Post < ActiveRecord::Base
-      include UuidBaseHelper
+      uuid_config do
+        primary_key true
+        store_as    :binary
+      end
     end
 
-You include `UuidBaseHelper` to your model when your model is already inherited from other classes (STI, ...).
+### Configuring your model
+
+To use uuid in your model, call `uuid_config` 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
+    end
+    
     # create a post with auto-generated uuid
     post = Post.new(:text => "Manual uuid")
     post.save
@@ -56,31 +86,105 @@ You include `UuidBaseHelper` to your model when your model is already inherited
     post.save
     
     # assign a uuid
-    @post.assign_uuid
+    post.assign_uuid
 
     # assign a uuid and save immediately
-    @post.assign_uuid!
+    post.assign_uuid!
+    
+    # check the uuid value is valid or not
+    post.uuid_valid?
 
-    # generate to a uuid
+    # generate a new uuid
     Post.generate_uuid
 
-    # It expects you have foreign_keys with `_uuid`
-    # you don't have to pass `:foreign_key` option inside association methods
-    class Author < ActiveRecord::UuidBase
+### Binary uuid model (example)
+
+    class PostBinary < ActiveRecord::Base
+      uuid_config do
+        primary_key true
+        store_as    :binary
+      end
+    end
+    
+    post = PostBinary.create(:text => "Binary uuid1")
+    # INSERT INTO `post_binaries` (`created_at`, `text`, `updated_at`, `uuid`) VALUES ('2012-06-20 17:32:47', 'Binary uuid1', '2012-06-20 17:32:47', x'4748f690bac311e18e440026b90faf3c')
+    
+    post.uuid # "4748f690-bac3-11e1-8e44-0026b90faf3c"
+    
+    # it works as usual for finding records
+    PostBinary.find_by_uuid(post.uuid)
+    PostBinary.where(:uuid => post.uuid)
+    PostBinary.find(post)
+    PostBinary.find(post.uuid)
+    PostBinary.find([post.uuid])
+    post.comments.create(:text => "Comment 1")
+    
+    # access the value that stored in db
+    post.reload
+    post.attributes_before_type_cast["uuid"]["value"]
+
+### Avaliable options inside `uuid_config`
+#### `column` option
+
+Set the column name to store uuid value.
+
+#### `primary_key` option
+
+Specify whether the value of `column` is primary key or not.
+
+#### `generator` option
+
+Specify which generator amongs `[:random, :timestamp]` used to generate `uuid` value.
+
+#### `store_as` option
+
+Specify which format to store. Possible values are `[:binary, :base64, :hexdigest, :string]`.
+
+#### `hook` option
+
+Specify the activerecord hook `[:after_initialize, :before_validation, :before_create]` to generate uuid value. Assign it to `:after_intialize` when you want to associate this record to its children.
+
+#### `assoication` option
+
+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_and_belongs_to_many :posts
     end
 
-    class Post < ActiveRecord::UuidBase
+    class Post < ActiveRecord::Base
+      uuid_config do
+        primary_key true
+        association true
+      end
       has_many :comments
       has_one  :comment
       has_and_belongs_to_many :authors
     end
 
-    class Comment < ActiveRecord::UuidBase
+    class Comment < ActiveRecord::Base
+      uuid_config do
+        primary_key true
+        association true
+      end
       belongs_to :post
     end
 
     # overwrite :foreign_key option and add additional option
-    class Post < ActiveRecord::UuidBase
+    class Post < ActiveRecord::Base
+      uuid_config do
+        primary_key true
+        association true
+      end
       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/active_record_uuid.gemspec

@@ -4,8 +4,8 @@ require File.expand_path('../lib/active_record_uuid/version', __FILE__)
 Gem::Specification.new do |gem|
   gem.authors       = ["Chamnap"]
   gem.email         = ["chamnapchhorn@gmail.com"]
-  gem.description   = %q{A nice gem to add uuids to your models, associations, and schema.rb}
-  gem.summary       = %q{A gem for adding uuids to your active record models}
+  gem.description   = %q{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.}
+  gem.summary       = %q{A full-featured gem for adding uuid support to your active record models}
   gem.homepage      = "https://github.com/chamnap/active_record_uuid"
 
   gem.files         = `git ls-files`.split($\)
@@ -17,7 +17,8 @@ Gem::Specification.new do |gem|
   
   gem.add_development_dependency "bundler", ">= 1.1.3"
   gem.add_development_dependency "rspec", "~> 2.8.0"
-  gem.add_development_dependency "sqlite3"
+  gem.add_development_dependency "mysql2"
   gem.add_dependency "activerecord", "~> 3.0"
   gem.add_dependency "uuidtools", "~> 2.1.2"
+  gem.add_dependency "mysql2"
 end

data/lib/active_record_uuid.rb

@@ -1,9 +1,15 @@
 require 'uuidtools'
+require 'base64'
 require 'active_record'
-
-require 'active_record_uuid/uuid_base'
-require 'active_record_uuid/railtie' if defined?(Rails)
+require 'active_support/concern'
 
 module ActiveRecordUuid
-  autoload :VERSION, 'active_record_uuid/version'
+  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 :Model,              'active_record_uuid/model'
 end
+
+require 'active_record_uuid/uuid_base'
+require 'active_record_uuid/rails/railtie' if defined?(Rails::Railtie)

data/lib/active_record_uuid/association_methods.rb

@@ -0,0 +1,52 @@
+module ActiveRecordUuid
+  module AssociationMethods
+    def has_many(name, options = {}, &extension)
+      options = uuid_assoc_options(:has_many, name, options)
+      super
+    end
+    
+    def has_one(name, options = {})
+      options = uuid_assoc_options(:has_one, name, options)
+      super
+    end
+    
+    def belongs_to(name, options = {})
+      options = uuid_assoc_options(:belongs_to, name, options)
+      super
+    end
+
+    def has_and_belongs_to_many(name, options = {}, &extension)
+      options = uuid_assoc_options(:has_and_belongs_to_many, name, options)
+      super
+    end
+    
+    private
+    def uuid_assoc_options(macro, association_name, options)
+      opts = {}
+      
+      # Set class_name only if not a has-through relation or poly relation
+      if options[:through].blank? and options[:as].blank? and options[:class_name].blank? and !self.name.match(/::/)
+        opts[:class_name] = "::#{association_name.to_s.singularize.camelize}"
+      end
+      
+      # Set foreign_key only if not passed
+      if options[:foreign_key].blank?
+        case macro
+        when :has_many, :has_one
+          opts[:foreign_key] = uuid_foreign_key(self.name)
+        when :belongs_to
+          opts[:foreign_key] = uuid_foreign_key(association_name)
+        when :has_and_belongs_to_many
+          opts[:foreign_key] = uuid_foreign_key(self.name)
+          opts[:association_foreign_key] = uuid_foreign_key(association_name)
+        end
+      end
+
+      options.merge(opts)
+    end
+    
+    def uuid_foreign_key(name)
+      name.to_s.singularize.underscore.downcase + "_uuid"
+    end
+  end
+end

data/lib/active_record_uuid/config.rb

@@ -0,0 +1,37 @@
+module ActiveRecordUuid
+  class Config
+    def initialize
+      @column      = :uuid
+      @primary_key = false
+      @association = false
+      @generator   = :timestamp
+      @store_as    = :string
+      @hook        = :before_validation
+    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_get("@#{meth}")
+      end
+    end
+    
+    def validate_options!
+      default_generators = [:timestamp, :random]
+      raise ArgumentError,
+        "Expected :timestamp or :random, got #{@generator}." \
+        unless default_generators.include?(@generator)
+
+      default_stores = [:binary, :base64, :hexdigest, :string]
+      raise ArgumentError,
+        "Expected :binary, :base64, :hexdigest, or :string, got #{@store_as}." \
+        unless default_stores.include?(@store_as)
+      
+      default_hooks = [:before_validation, :after_initialize, :before_create]
+      raise ArgumentError,
+        "Expected :before_validation, :after_initialize, or :before_create, got #{hook}." \
+        unless default_hooks.include?(@hook)
+    end
+  end
+end

data/lib/active_record_uuid/extensions/quoting_extension.rb

@@ -0,0 +1,31 @@
+module ActiveRecordUuid
+  module QuotingExtension
+    extend ActiveSupport::Concern
+    
+    included do
+      def quote(value, column = nil)
+        return super if column.blank? or !value.instance_of?(String) or value.bytesize != 36
+        
+        begin
+          uuid = UUIDTools::UUID.parse(value)
+        rescue ArgumentError, TypeError
+          return super
+        end
+
+        case column.type
+        when :binary
+          "BINARY x'#{uuid.hexdigest}'"
+        when :string
+          case column.limit
+          when 24
+            "'#{Base64.encode64(uuid.raw).strip}'"
+          when 32
+            "'#{uuid.hexdigest}'"
+          else
+            "'#{uuid.to_s}'"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record_uuid/model.rb

@@ -0,0 +1,66 @@
+module ActiveRecordUuid::Model
+  def self.included(base)
+    base.send(:extend, ClassMethods)
+    base.send(:include, InstanceMethods)
+  end
+
+  module InstanceMethods
+    def assign_uuid
+      send("#{uuid_column}=", self.class.generate_uuid)
+    end
+
+    def assign_uuid!
+      assign_uuid
+      save!
+    end
+     
+    def uuid_valid?
+      begin
+        UUIDTools::UUID.parse(uuid_value).valid?
+      rescue ArgumentError, TypeError
+        false
+      end
+    end
+ 
+    def uuid_value
+      send(uuid_column)
+    end
+    
+    private
+    def assign_uuid_when_blank
+      assign_uuid if uuid_value.blank?
+    end
+    
+    def uuid_column
+      self.class.uuid_config.column
+    end
+    
+    def validates_uuid
+      errors.add(uuid_column, "is invalid format") unless uuid_valid?
+    end
+  end
+
+  module ClassMethods 
+    def uuid_config(&block)
+      return @config if @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
+      
+      @config
+    end
+    
+    def generate_uuid
+      UUIDTools::UUID.send("#{uuid_config.generator}_create").to_s
+    end
+  end
+end

data/lib/active_record_uuid/rails/db.rake

@@ -0,0 +1,25 @@
+namespace :db do
+  task :add_primary_keys => :environment do
+    Dir["#{Rails.root}/app/models/**/*.rb"].each { |path| require path }
+    ActiveRecord::Base.descendants.each do |model|
+      next if model.abstract_class
+      
+      add_primary_key(model.table_name, model.primary_key)
+    end
+  end
+  
+  task :add_primary_key, [:model_name] => :environment do |t, args|
+    model = Object.const_get(args.model_name)
+    
+    add_primary_key(model.table_name, model.primary_key)
+  end
+  
+  private
+  def add_primary_key(table_name, primary_key)
+    begin
+      ActiveRecord::Base.connection.execute "ALTER TABLE #{table_name} ADD PRIMARY KEY (#{primary_key});"
+    rescue => e
+      p e
+    end
+  end
+end