mysql2_model 0.1.1

data/.document

@@ -0,0 +1,7 @@
+lib/**/*.rb
+bin/*
+features/**/*.feature
+-
+CHANGELOG.md
+VERSION
+MIT-LICENSE

data/.gitignore

@@ -0,0 +1,28 @@
+## MAC OS
+.DS_Store
+._*
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## NETBEANS
+nbproject
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+.yardoc
+doc
+
+## PROJECT::SPECIFIC
+spec/repositories.yml

data/.yardopts

@@ -0,0 +1,2 @@
+--no-private
+-

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 0.1.0 (September 2nd, 2010)
+* First Gem Release
+* Added Documentation
+
+## 0.0.5 (September 1st, 2010)
+* Added naive Date/Time Coercion (Be vewy vewy wary)
+* Added support for a Logger provided by Logging
+* Added support for sending the same query to multiple repositories and aggregating the results.
+
+## 0.0.4 (August 30th, 2010)
+* Refactored Mysql2Model::Client to use class instance instead of class variables.
+* Refactored Mysql2Model::Config to use class instance instead of class variables.
+
+## 0.0.3 (August 28th, 2010)
+* Fixed misspelling of "repository_path" in Mysql2Model::Config
+* Added specs for all classes
+* Added value method to Mysql2Model::Container
+* Added interpolating values into the queries called "composing"
+
+## 0.0.2 (August 26th, 2010)
+* First Working Version
+
+## 0.0.1 (August 25th, 2010)
+* Project Started

data/Gemfile

@@ -0,0 +1,3 @@
+source :gemcutter
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,30 @@
+PATH
+  remote: .
+  specs:
+    mysql2_model (0.1.0)
+      activesupport (~> 2.3)
+      builder (~> 2.1.2)
+      logging (~> 1)
+      mysql2 (~> 0.2)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (2.3.8)
+    builder (2.1.2)
+    little-plugger (1.1.2)
+    logging (1.4.3)
+      little-plugger (>= 1.1.2)
+    mysql2 (0.2.3)
+    rspec (1.3.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport (~> 2.3)
+  builder (~> 2.1.2)
+  logging (~> 1)
+  mysql2 (~> 0.2)
+  mysql2_model!
+  rspec (~> 1.3)

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Donovan Bray "donnoman@donovanbray.com" http://github.com/donnoman
+
+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.rdoc

@@ -0,0 +1,170 @@
+= mysql2_model the QRM (Query Resource Manager)
+
+Provides a class suitable to be used as a model, that includes connection management, variable interpolation, 
+object coercion and helper methods to write concise MySQL statements.
+
+This library is ideal for use when more adaptable, extensible, but perhaps less flexible ORM's present a significant
+obstacle to writing and running the specific MySQL statements you need.
+
+While the example given in this README is trivial, the most likely usage would be with 
+particularly gnarly business logic as you might need in generating analytics 
+where a typical ORM may yield numerous sub-optimal MySQL statements.
+
+== Inspiration
+
+This library was conceived when I wanted to solve a performance issue in a small Sinatra app that used a well established ORM.
+I wanted to create a simple class that could act as a stand-in for the original object and directly utilize carefully crafted 
+MySQL statements. The process generated a 21mb (and growing) XML file, at initially at cost of over 300k queries, and 27 minutes.
+The resulting Mysql2Model derived class was able to accomplish the same task in 56 seconds, with about 64 queries and dramatically 
+reduced the memory footprint.
+
+== Usage
+
+=== Install It
+
+  gem install mysql2_model
+
+=== Require it
+
+  require 'mysql2_model'
+
+=== Create a yml structure to point to the databases
+
+* See examples/repositories.yml
+
+=== Config it
+
+  Mysql2Model::Config.repository_path = 'config/repositories.yml'
+  
+=== Create your model
+
+  class Mtdb
+    include Mysql2Model::Container
+  
+    def self.all
+      query "SELECT id, database_name, db_server_host, db_server_port, db_server_user, db_server_password * FROM mtdbs"
+    end
+    
+    def self.count
+      value("SELECT COUNT(*) FROM mtdbs")
+    end
+    
+    # ? Mark substitution
+    def self.find_by_database_name_and_host(name,host)
+      query("SELECT * FROM mtdbs WHERE database_name = '?' and database_host = '?'",name,host)
+    end
+    
+    # printf style 
+    def self.find_by_host(host)
+      query("SELECT * FROM mtdbs WHERE database_host = '%s'",host)
+    end
+    
+    # Named Binds
+    def self.arrange_by_custom_order(order,user)
+      query("SELECT * FROM mtdbs WHERE db_server_user = ':user' ORDER BY database_name :order, db_server_host :order", :order => order, :user => user)
+    end
+  
+    def config_name
+      "mtdb#{id}".to_sym
+    end
+  
+    def to_config
+      {
+        config_name => {
+          :host => db_server_host,
+          :database => database_name,
+          :port => db_server_port,
+          :username => db_server_user,
+          :password => db_server_password_unencrypted
+        }
+      }
+    end
+  
+    def db_server_password_unencrypted
+      nil # You have to invent your own.
+    end
+  
+    def self.default_repository_name # You don't need this if you want to use the default repo
+      :infrastructure
+    end
+  
+  end
+
+=== Use it
+
+  Mtdb.all.each |mtdb|
+    puts "Database: #{mtdb.database_name}:" #direct method access
+    puts "Host: #{mtdb[:db_server_host]}"   #direct member access
+    puts "Config: {mtdb.to_config.inspect}" #model methods
+  end
+  
+=== Consume Multiple Repositories
+
+  # Assume :subscribers1 has 200 rows, :subscriber2 has 150, :subscriber3 has 50.
+
+  class Subscriber
+  
+    include Mysql2Model::Container
+  
+    def self.all
+      query("SELECT * FROM subscribers") # => resultset of 400 rows
+    end
+  
+    def self.count
+      value_sum("SELECT COUNT(*) FROM subscribers") # => 400
+    end
+  
+    def self.count_from_each
+      value("SELECT COUNT(*) FROM subscribers") # => [200,150,50]
+    end
+  
+    def self.default_repository_name
+      [:subscribers1,:subscribers2,:subscribers3]
+    end
+  
+  end
+  
+== Documentation 
+ 
+* http://rubydoc.info/github/donnoman/mysql2_model
+  
+== Troubleshooting
+
+* {Mysql2Model issue tracker}[http://github.com/donnoman/mysql2_model/issues/]
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version unintentionally.
+* Commit, do not mess with rakefile, version, or changelog.
+  (if you want to have your own version, that is fine but bump version in a commit by itself so that I can ignore it when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Todo
+* Improve coupling between classes
+* Time formatting when using the composing pattern to seamlessly pass time objects to mysql2
+  * Support ActiveSupport::TimeWithZone?
+  * Compliance with Mysql2 time handling
+* Incorporate Test,Production,Development environments into the repositories.yml
+* Improve instantiating the results so that we can regain mysql2's lazy loading.
+* Evented Connection Pools
+* Evented Query Patterns
+* Iterate in batches to allow more efficient garbage collection of large resultsets
+
+== Similar Projects
+* Sequel with the mysql2 adapter http://sequel.rubyforge.org
+* ActiveRecord with the mysql2 Adapter http://github.com/brianmario/mysql2/blob/master/lib/active_record/connection_adapters/mysql2_adapter.rb
+* Datamapper with mysql2 adapter http://datamapper.org
+* RBatis is the port of iBatis to Ruby and Ruby on Rails. http://ibatis.apache.org/docs/ruby (Appears to be discontinued)
+
+== Special Thanks
+
+* Brian Lopez - Mysql2 Gem (http://github.com/brianmario/mysql2)
+
+== Copyright
+
+Copyright (c) 2010 Donovan Bray "donnoman@donovanbray.com" http://github.com/donnoman 
+
+See MIT-LICENSE for details.
+

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "mysql2_model"
+    gem.summary = %Q{Mysql2Model provides a container for creating model code based on MySQL Statements utilizing the Mysql2 client}
+    gem.description = %Q{Provides a class suitable to be used as a model, that includes connection management, variable interpolation, object coercion and helper methods to support using direct MySQL statements for database interaction.}
+    gem.email = "donnoman@donovanbray.com"
+    gem.homepage = "http://github.com/donnoman/mysql2_model"
+    gem.authors = ["donnoman"]
+    gem.add_runtime_dependency "mysql2", "~> 0.2"
+    gem.add_runtime_dependency "activesupport", "~> 2.3"
+    gem.add_runtime_dependency 'builder', '~> 2.1.2' #Not needed if using entire active_support
+    gem.add_runtime_dependency 'logging', '~> 1'
+    gem.add_development_dependency "rspec", "~> 1.3"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "mysql2_model #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.1

data/examples/mtdb.rb

@@ -0,0 +1,43 @@
+require "mysql2_model"
+
+Mysql2Model::Config.repository_path = File.expand_path(File.dirname(__FILE__) + '/../examples/repositories.yml')
+
+# # Use like:
+# Mtdb.all.each |mtdb|
+#   puts "Database: #{mtdb.database_name}:" #direct method access
+#   puts "Host: #{mtdb[:db_server_host]}"   #direct member access
+#   puts "Config: {mtdb.to_config.inspect}" #model methods
+# end
+
+class Mtdb
+  include Mysql2Model::Container
+  
+  def self.all
+    query("SELECT id, database_name, db_server_host, db_server_port, db_server_user, db_server_password * FROM mtdbs")
+  end
+  
+  def config_name
+    "mtdb#{id}".to_sym
+  end
+  
+  def to_config
+    {
+      config_name => {
+        :host => db_server_host,
+        :database => database_name,
+        :port => db_server_port,
+        :username => db_server_user,
+        :password => db_server_password_unencrypted
+      }
+    }
+  end
+  
+  def db_server_password_unencrypted
+    nil # You have to invent your own.
+  end
+  
+  def self.default_repository_name # You don't need this if you want to use the default repo
+    :infrastructure
+  end
+  
+end

data/examples/repositories.yml

@@ -0,0 +1,26 @@
+:repositories:
+  :default:
+    :database: community_production
+    :username: root
+    :password: gibberish
+    :host: localhost
+  :infrastructure:
+    :database: infrastructure_production
+    :username: infra_user
+    :password: more_gibberish
+    :host: localhost
+  :subscribers1:
+    :database: subscribers1_production
+    :username: sub_user
+    :password: sub_gibberish
+    :host: localhost
+  :subscribers2:
+    :database: subscribers2_production
+    :username: sub_user
+    :password: sub_gibberish
+    :host: localhost
+  :subscribers3:
+    :database: subscribers3_production
+    :username: sub_user
+    :password: sub_gibberish
+    :host: localhost

data/examples/subscriber.rb

@@ -0,0 +1,27 @@
+require "mysql2_model"
+
+Mysql2Model::Config.repository_path = File.expand_path(File.dirname(__FILE__) + '/../examples/repositories.yml')
+
+class Subscriber
+  
+  include Mysql2Model::Container
+  
+  # Assume :subscribers1 has 200 rows, :subscriber2 has 150, :subscriber3 has 50.
+  
+  def self.all
+    query("SELECT * FROM subscribers") # => resultset of 400 rows
+  end
+  
+  def self.count
+    value_sum("SELECT COUNT(*) FROM subscribers") # => 400
+  end
+  
+  def self.count_from_each
+    value("SELECT COUNT(*) FROM subscribers") # => [200,150,50]
+  end
+  
+  def self.default_repository_name
+    [:subscribers1,:subscribers2,:subscribers3]
+  end
+  
+end

data/lib/mysql2_model/client.rb

@@ -0,0 +1,66 @@
+module Mysql2Model
+  # multi-repository aware mysql2 client proxy
+  # @todo Evented Connection Pool
+  class Client
+    # @return a multi-repository proxy
+    def initialize(repos)
+      @repos = repos
+    end
+    # Collect the results of a multi-repository query into a single resultset
+    # @param [String] statement MySQL statement
+    def query(statement)
+      collection = []
+      @repos.each do |repo|
+        self.class[repo].query(statement).each do |row| 
+          collection << row
+        end
+      end
+      collection
+    end
+    # Use the first connection to execute a single escape
+    # @param [String] statement MySQL statement
+    def escape(statement)
+      self.class[@repos.first].escape(statement)
+    end
+    
+    class << self
+      # Stores a collection of mysql2 connections 
+      def repositories
+        load_repos
+        @repositories 
+      end
+      # loads the repositories with the YAML object pointed to by {Mysql2Model::Config.repository_path},
+      # subsequent calls are ignored unless forced.
+      # @param [boolean] force Use force = true to reload the repositories and overwrite the existing Hash.
+      def load_repos(force=false)
+        unless force
+          return unless @repositories.blank?
+        end
+        repos = YAML.load(File.new(Mysql2Model::Config.repository_path, 'r'))
+        repos[:repositories].each do |repo, config|
+          self[repo] = config 
+        end
+      end
+      # Repository accessor lazily instantiates Mysql2::Clients or delegates them to an instance of the multi-repository proxy
+      def [](repository_name)
+        if repository_name.is_a?(Array)
+          self.new(repository_name)
+        else
+          load_repos
+          @repositories[repository_name][:client] ||= begin
+            c = Mysql2::Client.new(@repositories[repository_name][:config])
+            c.query_options.merge!(:symbolize_keys => true)
+            c
+          end
+        end
+      end
+      # Repository accessor stores the connection parameters for later use
+      def []=(repository_name,config)
+        @repositories ||= {}
+        @repositories[repository_name] ||= {}
+        @repositories[repository_name][:config] = config
+      end
+    end
+    
+  end
+end

data/lib/mysql2_model/composer.rb

@@ -0,0 +1,105 @@
+module Mysql2Model
+  
+  # Generic Mysql2Model exception class.
+  class Mysql2ModelError < StandardError
+  end
+  
+  # Raised when number of bind variables in statement does not match number of expected variables.
+  # @example two placeholders are given but only one variable to fill them.
+  #   query("SELECT FROM locs WHERE lat = ? AND lng = ?", 53.7362)
+  class PreparedStatementInvalid < Mysql2ModelError
+  end
+  
+  # Adapted from Rails ActiveRecord::Base
+  #
+  # Changed the language from "Sanitize", since not much sanitization is going on here.
+  # There is some escaping and coercion going on, but nothing explicity santizes the resulting statement.
+  module Composer
+    
+    # Accepts multiple arguments, an array, or string of SQL and composes them
+    # @example String
+    #   "name='foo''bar' and group_id='4'" #=>  "name='foo''bar' and group_id='4'"
+    # @example Array
+    #   ["name='%s' and group_id='%s'", "foo'bar", 4]  #=>  "name='foo''bar' and group_id='4'"
+    # @param [Array,String]
+    def compose_sql(*statement)
+      raise PreparedStatementInvalid, "Statement is blank!" if statement.blank?
+      if statement.is_a?(Array)
+        if statement.size == 1 #strip the outer array
+          compose_sql_array(statement.first)
+        else
+          compose_sql_array(statement)
+        end
+      else
+        statement
+      end
+    end
+    
+    # Accepts an array of conditions.  The array has each value
+    # sanitized and interpolated into the SQL statement.
+    # @param [Array] ary
+    # @example Array
+    #   ["name='%s' and group_id='%s'", "foo'bar", 4]  #=>  "name='foo''bar' and group_id='4'"
+    # @private
+    def compose_sql_array(ary)
+      statement, *values = ary
+      if values.first.is_a?(Hash) and statement =~ /:\w+/
+        replace_named_bind_variables(statement, values.first)
+      elsif statement.include?('?')
+        replace_bind_variables(statement, values)
+      else
+        statement % values.collect { |value| client.escape(value.to_s) }
+      end
+    end
+
+    def replace_bind_variables(statement, values) # @private
+      raise_if_bind_arity_mismatch(statement, statement.count('?'), values.size)
+      bound = values.dup
+      statement.gsub('?') { escape_bound_value(bound.shift) }
+    end
+
+    def replace_named_bind_variables(statement, bind_vars) # @private
+      statement.gsub(/(:?):([a-zA-Z]\w*)/) do
+        if $1 == ':' # skip postgresql casts
+          $& # return the whole match
+        elsif bind_vars.include?(match = $2.to_sym)
+          escape_bound_value(bind_vars[match])
+        else
+          raise PreparedStatementInvalid, "missing value for :#{match} in #{statement}"
+        end
+      end
+    end
+
+
+    def escape_bound_value(value) # @private
+      if value.respond_to?(:map) && !value.is_a?(String)
+        if value.respond_to?(:empty?) && value.empty?
+          escape(nil)
+        else
+          value.map { |v| escape(v) }.join(',')
+        end
+      else
+        escape(value)
+      end
+    end
+
+    def raise_if_bind_arity_mismatch(statement, expected, provided) # @private
+      unless expected == provided
+        raise PreparedStatementInvalid, "wrong number of bind variables (#{provided} for #{expected}) in: #{statement}"
+      end
+    end
+    
+    def escape(value) # @private
+      client.escape(convert(value))
+    end
+    
+    # Attempt to coerce the value to be a representation consistent with the database
+    # @private
+    def convert(value) 
+      return value.to_formatted_s(:db) if value.respond_to?(:to_formatted_s)
+      value.to_s
+    end
+    
+  end
+
+end

data/lib/mysql2_model/config.rb

@@ -0,0 +1,15 @@
+module Mysql2Model
+  # Configuration Attributes
+  class Config
+    private_class_method :new
+    class << self
+      attr_writer :repository_path
+      # Location of the YAML file to define the repositories
+      # @todo Identify a default repositories.yml inside the consuming projects' root.
+      #   How to identify config/repositories.yml when we don't know what framework they are using?      
+      def repository_path
+        @repository_path ||= 'repositories.yml'
+      end
+    end
+  end
+end