mysql2 0.2.24 → 0.3.0

data/.gitignore

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

data/.rspec

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

data/.rvmrc

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

data/CHANGELOG.md

@@ -0,0 +1,148 @@
+# Changelog
+
+## 0.3.0 (April 26th, 2011)
+* switch to MySQL Connector/C for win32 builds
+* win32 bugfixes
+* BREAKING CHANGE: the ActiveRecord adapter has been pulled into Rails 3.1 and is no longer part of the gem
+* added Mysql2::Client.escape (class-level) for raw one-off non-encoding-aware escaping
+
+## 0.2.7 (March 28th, 2011)
+* various fixes for em_mysql2 and fiber usage
+* use our own Mysql2IndexDefinition class for better compatibility across ActiveRecord versions
+* ensure the query is a string earlier in the Mysql2::Client#query codepath for 1.9
+* only set binary ruby encoding on fields that have a binary flag *and* encoding set
+* a few various optimizations
+* add support for :read_timeout to be set on a connection
+* Fix to install with MariDB on Windows
+* add fibered em connection without activerecord
+* fix some 1.9.3 compilation warnings
+* add LD_RUN_PATH when using hard coded mysql paths - this should help users with MySQL installed in non-standard locations
+* for windows support, duplicate the socket from libmysql and create a temporary CRT fd
+* fix for handling years before 1970 on Windows
+* fixes to the Fiber adapter
+* set wait_timeout maximum on Windows to 2147483
+* update supported range for Time objects
+* upon being required, make sure the libmysql we're using is the one we were built against
+* add Mysql2::Client#thread_id
+* add Mysql2::Client#ping
+* switch connection check in AR adapter to use Mysql2::Client#ping for efficiency
+* prefer linking against thread-safe version of libmysqlclient
+* define RSTRING_NOT_MODIFIED for an awesome rbx speed boost
+* expose Mysql2::Client#encoding in 1.9, make sure we set the error message and sqlstate encodings accordingly
+* do not segfault when raising for invalid charset (found in 1.9.3dev)
+
+## 0.2.6 (October 19th, 2010)
+* version bump since the 0.2.5 win32 binary gems were broken
+
+## 0.2.5 (October 19th, 2010)
+* fixes for easier Win32 binary gem deployment for targeting 1.8 and 1.9 in the same gem
+* refactor of connection checks and management to avoid race conditions with the GC/threading to prevent the unexpected loss of connections
+* update the default flags during connection
+* add support for setting wait_timeout on AR adapter
+* upgrade to rspec2
+* bugfix for an edge case where the GC would clean up a Mysql2::Client object before the underlying MYSQL pointer had been initialized
+* fix to CFLAGS to allow compilation on SPARC with sunstudio compiler - Anko painting <anko.com+github@gmail.com>
+
+## 0.2.4 (September 17th, 2010)
+* a few patches for win32 support from Luis Lavena - thanks man!
+* bugfix from Eric Wong to avoid a potential stack overflow during Mysql2::Client#escape
+* added the ability to turn internal row caching on/off via the :cache_rows => true/false option
+* a couple of small patches for rbx compatibility
+* set IndexDefinition#length in AR adapter - Kouhei Yanagita <yanagi@shakenbu.org>
+* fix a long-standing data corruption bug - thank you thank you thank you to @joedamato (http://github.com/ice799)
+* bugfix from calling mysql_close on a closed/freed connection surfaced by the above fix
+
+## 0.2.3 (August 20th, 2010)
+* connection flags can now be passed to the constructor via the :flags key
+* switch AR adapter connection over to use FOUND_ROWS option
+* patch to ensure we use DateTime objects in place of Time for timestamps that are out of the supported range on 32bit platforms < 1.9.2
+
+## 0.2.2 (August 19th, 2010)
+* Change how AR adapter would send initial commands upon connecting
+** we can make multiple session variable assignments in a single query
+* fix signal handling when waiting on queries
+* retry connect if interrupted by signals
+
+## 0.2.1 (August 16th, 2010)
+* bring mysql2 ActiveRecord adapter back into gem
+
+## 0.2.0 (August 16th, 2010)
+* switch back to letting libmysql manage all allocation/thread-state/freeing for the connection
+* cache various numeric type conversions in hot-spots of the code for a little speed boost
+* ActiveRecord adapter moved into Rails 3 core
+** Don't worry 2.3.x users! We'll either release the adapter as a separate gem, or try to get it into 2.3.9
+* Fix for the "closed MySQL connection" error (GH #31)
+* Fix for the "can't modify frozen object" error in 1.9.2 (GH #37)
+* Introduce cascading query and result options (more info in README)
+* Sequel adapter pulled into core (will be in the next release - 3.15.0 at the time of writing)
+* add a safety check when attempting to send a query before a result has been fetched
+
+## 0.1.9 (July 17th, 2010)
+* Support async ActiveRecord access with fibers and EventMachine (mperham)
+* string encoding support for 1.9, respecting Encoding.default_internal
+* added support for rake-compiler (tenderlove)
+* bugfixes for ActiveRecord driver
+** one minor bugfix for TimeZone support
+** fix the select_rows method to return what it should according to the docs (r-stu31)
+* Mysql2::Client#fields method added - returns the array of field names from a resultset, as strings
+* Sequel adapter
+** bugfix regarding sybolized field names (Eric Wong)
+** fix query logging in Sequel adapter
+* Lots of nice code cleanup (tenderlove)
+** Mysql2::Error definition moved to pure-Ruby
+** Mysql2::client#initialize definition moved to pure-Ruby
+** Mysql2::Result partially moved to pure-Ruby
+
+## 0.1.8 (June 2nd, 2010)
+* fixes for AR adapter for timezone juggling
+* fixes to be able to run benchmarks and specs under 1.9.2
+
+## 0.1.7 (May 22nd, 2010)
+* fix a bug when using the disconnect! method on a closed connection in the AR driver
+
+## 0.1.6 (May 14th, 2010)
+* more fixes to the AR adapter related to casting
+* add missing index creation override method to AR adapter
+* added sql_state and error_number methods to the Mysql2::Error exception class
+
+## 0.1.5 (May 12th, 2010)
+* quite a few patches from Eric Wong related to thread-safety, non-blocking I/O and general cleanup
+** wrap mysql_real_connect with rb_thread_blocking_region
+** release GVL for possibly blocking mysql_* library calls
+** [cleanup] quiet down warnings
+** [cleanup] make all C symbols static
+** add Mysql2::Client#close method
+** correctly free the wrapped result in case of EOF
+** Fix memory leak from the result wrapper struct itself
+** make Mysql2::Client destructor safely non-blocking
+* bug fixes for ActiveRecord adapter
+** added casting for default values since they all come back from Mysql as strings (!?!)
+** missing constant was added
+** fixed a typo in the show_variable method
+* switched over sscanf for date/time parsing in C
+* made some specs a little finer-grained
+* initial Sequel adapter added
+* updated query benchmarks to reflect the difference between casting in C and in Ruby
+
+## 0.1.4 (April 23rd, 2010)
+* optimization: implemented a local cache for rows that are lazily created in ruby during iteration. The MySQL C result is freed as soon as all the results have been cached
+* optimization: implemented a local cache for field names so every row reuses the same objects as field names/keys
+* refactor the Mysql2 connection adapter for ActiveRecord to not extend the Mysql adapter - now being a free-standing connection adapter
+
+## 0.1.3 (April 15th, 2010)
+* added an EventMachine Deferrable API
+* added an ActiveRecord connection adapter
+** should be compatible with 2.3.5 and 3.0 (including Arel)
+
+## 0.1.2 (April 9th, 2010)
+* fix a bug (copy/paste fail) around checking for empty TIME values and returning nil (thanks @marius)
+
+## 0.1.1 (April 6th, 2010)
+* added affected_rows method (mysql_affected_rows)
+* added last_id method (last_insert_id)
+* enable reconnect option by default
+* added initial async query support
+* updated extconf (thanks to the mysqlplus project) for easier gem building
+
+## 0.1.0 (April 6th, 2010)
+* initial release

data/Gemfile

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

data/README.rdoc

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

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

data/benchmark/active_record.rb

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