mysql2 0.3.1 → 0.5.2

data/.gitignore

@@ -1,12 +0,0 @@
-Makefile
-*.dSYM
-*.o
-*.bundle
-*.so
-*.a
-*.rbc
-mkmf.log
-pkg/
-tmp
-vendor
-lib/mysql2/mysql2.rb

data/.rspec

@@ -1,2 +0,0 @@
---format documentation
---colour

data/.rvmrc

@@ -1 +0,0 @@
-rvm use 1.9.2@mysql2 --create

data/Gemfile

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

data/MIT-LICENSE

@@ -1,20 +0,0 @@
-Copyright (c) 2010-2011 Brian Lopez - http://github.com/brianmario
-
-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

@@ -1,257 +0,0 @@
-= Mysql2 - A modern, simple and very fast Mysql library for Ruby - binding to libmysql
-
-The Mysql2 gem is meant to serve the extremely common use-case of connecting, querying and iterating on results.
-Some database libraries out there serve as direct 1:1 mappings of the already complex C API's available.
-This one is not.
-
-It also forces the use of UTF-8 [or binary] for the connection [and all strings in 1.9, unless Encoding.default_internal is set then it'll convert from UTF-8 to that encoding] and uses encoding-aware MySQL API calls where it can.
-
-The API consists of two clases:
-
-Mysql2::Client - your connection to the database
-
-Mysql2::Result - returned from issuing a #query on the connection. It includes Enumerable.
-
-== Installing
-
-  gem install mysql2
-
-You may have to specify --with-mysql-config=/some/random/path/bin/mysql_config
-
-== Usage
-
-Connect to a database:
-
-  # this takes a hash of options, almost all of which map directly
-  # to the familiar database.yml in rails
-  # See http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/MysqlAdapter.html
-  client = Mysql2::Client.new(:host => "localhost", :username => "root")
-
-Then query it:
-
-  results = client.query("SELECT * FROM users WHERE group='githubbers'")
-
-Need to escape something first?
-
-  escaped = client.escape("gi'thu\"bbe\0r's")
-  results = client.query("SELECT * FROM users WHERE group='#{escaped}'")
-
-Finally, iterate over the results:
-
-  results.each do |row|
-    # conveniently, row is a hash
-    # the keys are the fields, as you'd expect
-    # the values are pre-built ruby primitives mapped from their corresponding field types in MySQL
-    # Here's an otter: http://farm1.static.flickr.com/130/398077070_b8795d0ef3_b.jpg
-  end
-
-Or, you might just keep it simple:
-
-  client.query("SELECT * FROM users WHERE group='githubbers'").each do |row|
-    # do something with row, it's ready to rock
-  end
-
-How about with symbolized keys?
-
-  # NOTE: the :symbolize_keys and future options will likely move to the #query method soon
-  client.query("SELECT * FROM users WHERE group='githubbers'").each(:symbolize_keys => true) do |row|
-    # do something with row, it's ready to rock
-  end
-
-You can get the headers and the columns in the order that they were returned
-by the query like this:
-
-  headers = results.fields # <= that's an array of field names, in order
-  results.each(:as => :array) do |row|
-  # Each row is an array, ordered the same as the query results
-  # An otter's den is called a "holt" or "couch"
-  end
-
-== Cascading config
-
-The default config hash is at:
-
- Mysql2::Client.default_query_options
-
-which defaults to:
-
- {:async => false, :as => :hash, :symbolize_keys => false}
-
-that can be used as so:
-
- # these are the defaults all Mysql2::Client instances inherit
- Mysql2::Client.default_query_options.merge!(:as => :array)
-
-or
-
- # this will change the defaults for all future results returned by the #query method _for this connection only_
- c = Mysql2::Client.new
- c.query_options.merge!(:symbolize_keys => true)
-
-or
-
- # this will set the options for the Mysql2::Result instance returned from the #query method
- c = Mysql2::Client.new
- c.query(sql, :symbolize_keys => true)
-
-== Result types
-
-=== Array of Arrays
-
-Pass the :as => :array option to any of the above methods of configuration
-
-=== Array of Hashes
-
-The default result type is set to :hash, but you can override a previous setting to something else with :as => :hash
-
-=== Others...
-
-I may add support for :as => :csv or even :as => :json to allow for *much* more efficient generation of those data types from result sets.
-If you'd like to see either of these (or others), open an issue and start bugging me about it ;)
-
-=== Timezones
-
-Mysql2 now supports two timezone options:
-
-  :database_timezone - this is the timezone Mysql2 will assume fields are already stored as, and will use this when creating the initial Time objects in ruby
-  :application_timezone - this is the timezone Mysql2 will convert to before finally handing back to the caller
-
-In other words, if :database_timezone is set to :utc - Mysql2 will create the Time objects using Time.utc(...) from the raw value libmysql hands over initially.
-Then, if :application_timezone is set to say - :local - Mysql2 will then convert the just-created UTC Time object to local time.
-
-Both options only allow two values - :local or :utc - with the exception that :application_timezone can be [and defaults to] nil
-
-=== Casting "boolean" columns
-
-You can now tell Mysql2 to cast tinyint(1) fields to boolean values in Ruby with the :cast_booleans option.
-
-  client = Mysql2::Client.new
-  result = client.query("SELECT * FROM table_with_boolean_field", :cast_booleans => true)
-
-=== Async
-
-Mysql2::Client takes advantage of the MySQL C API's (undocumented) non-blocking function mysql_send_query for *all* queries.
-But, in order to take full advantage of it in your Ruby code, you can do:
-
-  client.query("SELECT sleep(5)", :async => true)
-
-Which will return nil immediately. At this point you'll probably want to use some socket monitoring mechanism
-like EventMachine or even IO.select. Once the socket becomes readable, you can do:
-
-  # result will be a Mysql2::Result instance
-  result = client.async_result
-
-NOTE: Because of the way MySQL's query API works, this method will block until the result is ready.
-So if you really need things to stay async, it's best to just monitor the socket with something like EventMachine.
-If you need multiple query concurrency take a look at using a connection pool.
-
-=== Row Caching
-
-By default, Mysql2 will cache rows that have been created in Ruby (since this happens lazily).
-This is especially helpful since it saves the cost of creating the row in Ruby if you were to iterate over the collection again.
-
-If you only plan on using each row once, then it's much more efficient to disable this behavior by setting the :cache_rows option to false.
-This would be helpful if you wanted to iterate over the results in a streaming manner. Meaning the GC would cleanup rows you don't need anymore as you're iterating over the result set.
-
-== ActiveRecord
-
-To use the ActiveRecord driver (with our without rails), all you should need to do is have this gem installed and set the adapter in your database.yml to "mysql2".
-That was easy right? :)
-
-== Asynchronous ActiveRecord
-
-You can also use Mysql2 with asynchronous Rails (first introduced at http://www.mikeperham.com/2010/04/03/introducing-phat-an-asynchronous-rails-app/) by
-setting the adapter in your database.yml to "em_mysql2".  You must be running Ruby 1.9, thin and the rack-fiber_pool middleware for it to work.
-
-== Sequel
-
-The Sequel adapter was pulled out into Sequel core (will be part of the next release) and can be used by specifying the "mysql2://" prefix to your connection specification.
-
-== EventMachine
-
-The mysql2 EventMachine deferrable api allows you to make async queries using EventMachine,
-while specifying callbacks for success for failure. Here's a simple example:
-
-  require 'mysql2/em'
-
-  EM.run do
-    client1 = Mysql2::EM::Client.new
-    defer1 = client1.query "SELECT sleep(3) as first_query"
-    defer1.callback do |result|
-      puts "Result: #{result.to_a.inspect}"
-    end
-
-    client2 = Mysql2::EM::Client.new
-    defer2 = client2.query "SELECT sleep(1) second_query"
-    defer2.callback do |result|
-      puts "Result: #{result.to_a.inspect}"
-    end
-  end
-
-== Lazy Everything
-
-Well... almost ;)
-
-Field name strings/symbols are shared across all the rows so only one object is ever created to represent the field name for an entire dataset.
-
-Rows themselves are lazily created in ruby-land when an attempt to yield it is made via #each.
-For example, if you were to yield 4 rows from a 100 row dataset, only 4 hashes will be created. The rest will sit and wait in C-land until you want them (or when the GC goes to cleanup your Mysql2::Result instance).
-Now say you were to iterate over that same collection again, this time yielding 15 rows - the 4 previous rows that had already been turned into ruby hashes would be pulled from an internal cache, then 11 more would be created and stored in that cache.
-Once the entire dataset has been converted into ruby objects, Mysql2::Result will free the Mysql C result object as it's no longer needed.
-
-This caching behavior can be disabled by setting the :cache_rows option to false.
-
-As for field values themselves, I'm workin on it - but expect that soon.
-
-== Compatibility
-
-The specs pass on my system (SL 10.6.3, x86_64) in these rubies:
-
-* 1.8.7-p249
-* ree-1.8.7-2010.01
-* 1.9.1-p378
-* ruby-trunk
-* rbx-head - broken at the moment, working with the rbx team for a solution
-
-The ActiveRecord driver should work on 2.3.5 and 3.0
-
-== Yeah... but why?
-
-Someone: Dude, the Mysql gem works fiiiiiine.
-
-Me: It sure does, but it only hands you nil and strings for field values. Leaving you to convert
-them into proper Ruby types in Ruby-land - which is slow as balls.
-
-
-Someone: OK fine, but do_mysql can already give me back values with Ruby objects mapped to MySQL types.
-
-Me: Yep, but it's API is considerably more complex *and* can be ~2x slower.
-
-== Benchmarks
-
-Performing a basic "SELECT * FROM" query on a table with 30k rows and fields of nearly every Ruby-representable data type,
-then iterating over every row using an #each like method yielding a block:
-
-# These results are from the query_with_mysql_casting.rb script in the benchmarks folder
-   user       system     total       real
-  Mysql2
-   0.750000   0.180000   0.930000 (  1.821655)
-  do_mysql
-   1.650000   0.200000   1.850000 (  2.811357)
-  Mysql
-   7.500000   0.210000   7.710000 (  8.065871)
-
-== Development
-
-To run the tests, you can use RVM and Bundler to create a pristine environment for mysql2 development/hacking.
-Use 'bundle install' to install the necessary development and testing gems:
-
-    bundle install
-    rake
-
-== Special Thanks
-
-* Eric Wong - for the contribution (and the informative explanations) of some thread-safety, non-blocking I/O and cleanup patches. You rock dude
-* Yury Korolev (http://github.com/yury) - for TONS of help testing the ActiveRecord adapter
-* Aaron Patterson (http://github.com/tenderlove) - tons of contributions, suggestions and general badassness
-* Mike Perham (http://github.com/mperham) - Async ActiveRecord adapter (uses Fibers and EventMachine)

data/Rakefile

@@ -1,5 +0,0 @@
-# encoding: UTF-8
-require 'rake'
-
-# Load custom tasks
-Dir['tasks/*.rake'].sort.each { |f| load f }

data/benchmark/active_record.rb

@@ -1,51 +0,0 @@
-# encoding: UTF-8
-$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + '/../lib')
-
-require 'rubygems'
-require 'benchmark'
-require 'active_record'
-
-ActiveRecord::Base.default_timezone = :local
-ActiveRecord::Base.time_zone_aware_attributes = true
-
-number_of = 10
-mysql2_opts = {
-  :adapter => 'mysql2',
-  :database => 'test'
-}
-mysql_opts = {
-  :adapter => 'mysql',
-  :database => 'test'
-}
-
-class Mysql2Model < ActiveRecord::Base
-  set_table_name :mysql2_test
-end
-
-class MysqlModel < ActiveRecord::Base
-  set_table_name :mysql2_test
-end
-
-Benchmark.bmbm do |x|
-  x.report "Mysql2" do
-    Mysql2Model.establish_connection(mysql2_opts)
-    number_of.times do
-      Mysql2Model.all(:limit => 1000).each{ |r|
-        r.attributes.keys.each{ |k|
-          r.send(k.to_sym)
-        }
-      }
-    end
-  end
-
-  x.report "Mysql" do
-    MysqlModel.establish_connection(mysql_opts)
-    number_of.times do
-      MysqlModel.all(:limit => 1000).each{ |r|
-        r.attributes.keys.each{ |k|
-          r.send(k.to_sym)
-        }
-      }
-    end
-  end
-end

data/benchmark/active_record_threaded.rb

@@ -1,42 +0,0 @@
-# encoding: UTF-8
-$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + '/../lib')
-
-require 'rubygems'
-require 'benchmark'
-require 'active_record'
-
-times = 25
-
-
-# mysql2
-mysql2_opts = {
-  :adapter => 'mysql2',
-  :database => 'test',
-  :pool => times
-}
-ActiveRecord::Base.establish_connection(mysql2_opts)
-x = Benchmark.realtime do
-  threads = []
-  times.times do
-    threads << Thread.new { ActiveRecord::Base.connection.execute("select sleep(1)") }
-  end
-  threads.each {|t| t.join }
-end
-puts "mysql2: #{x} seconds"
-
-
-# mysql
-mysql2_opts = {
-  :adapter => 'mysql',
-  :database => 'test',
-  :pool => times
-}
-ActiveRecord::Base.establish_connection(mysql2_opts)
-x = Benchmark.realtime do
-  threads = []
-  times.times do
-    threads << Thread.new { ActiveRecord::Base.connection.execute("select sleep(1)") }
-  end
-  threads.each {|t| t.join }
-end
-puts "mysql: #{x} seconds"

data/benchmark/allocations.rb

@@ -1,33 +0,0 @@
-# encoding: UTF-8
-$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + '/../lib')
-
-raise Mysql2::Mysql2Error.new("GC allocation benchmarks only supported on Ruby 1.9!") unless RUBY_VERSION =~ /1\.9/
-
-require 'rubygems'
-require 'benchmark'
-require 'active_record'
-
-ActiveRecord::Base.default_timezone = :local
-ActiveRecord::Base.time_zone_aware_attributes = true
-
-class Mysql2Model < ActiveRecord::Base
-  set_table_name :mysql2_test
-end
-
-def bench_allocations(feature, iterations = 10, &blk)
-  puts "GC overhead for #{feature}"
-  Mysql2Model.establish_connection(:adapter => 'mysql2', :database => 'test')
-  GC::Profiler.clear
-  GC::Profiler.enable
-  iterations.times{ blk.call }
-  GC::Profiler.report(STDOUT)
-  GC::Profiler.disable
-end
-
-bench_allocations('coercion') do
-  Mysql2Model.all(:limit => 1000).each{ |r|
-    r.attributes.keys.each{ |k|
-      r.send(k.to_sym)
-    }
-  }
-end

data/benchmark/escape.rb

@@ -1,36 +0,0 @@
-# encoding: UTF-8
-$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + '/../lib')
-
-require 'rubygems'
-require 'benchmark'
-require 'mysql'
-require 'mysql2'
-require 'do_mysql'
-
-def run_escape_benchmarks(str, number_of = 1000)
-  Benchmark.bmbm do |x|
-    mysql = Mysql.new("localhost", "root")
-    x.report "Mysql #{str.inspect}" do
-      number_of.times do
-        mysql.quote str
-      end
-    end
-
-    mysql2 = Mysql2::Client.new(:host => "localhost", :username => "root")
-    x.report "Mysql2 #{str.inspect}" do
-      number_of.times do
-        mysql2.escape str
-      end
-    end
-
-    do_mysql = DataObjects::Connection.new("mysql://localhost/test")
-    x.report "do_mysql #{str.inspect}" do
-      number_of.times do
-        do_mysql.quote_string str
-      end
-    end
-  end
-end
-
-run_escape_benchmarks "abc'def\"ghi\0jkl%mno"
-run_escape_benchmarks "clean string"