mysql2-sp 0.3.10

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,3 @@
+--format documentation
+--colour
+--fail-fast

data/.rvmrc

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

data/.travis.yml

@@ -0,0 +1,7 @@
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - ree
+before_script:
+  - "mysql -e 'create database test;' >/dev/null"

data/CHANGELOG.md

@@ -0,0 +1,230 @@
+# Changelog
+
+## 0.3.10 (November 9th, 2011)
+
+## 0.3.9 (November 9th, 2011)
+
+## 0.3.8 (November 9th, 2011)
+* remove fiber support from mysql2, the code has moved to the
+  em-synchrony gem.
+* use rb_wait_for_single_fd() if available
+* fixed a bug with inheriting query options
+* remove ext/ from the default loadpath
+* fix build issues on OSX with Xcode 4.2 (gcc-llvm compiler)
+
+## 0.3.7 (August 16th, 2011)
+* ensure symbolized column names support encodings in 1.9
+
+## 0.3.6 (June 17th, 2011)
+* fix bug in Time/DateTime range detection
+* (win32) fix bug where the Mysql2::Client object wasn't cleaned up properly if interrupted during a query
+* add Mysql2::Result#count (aliased as size) to get the row count for the dataset
+  this can be especially helpful if you want to get the number of rows without having to inflate
+  the entire dataset into ruby (since this happens lazily)
+
+## 0.3.5 (June 15th, 2011)
+* bug fix for Time/DateTime usage depending on 32/64bit Ruby
+
+## 0.3.4 (June 15th, 2011)
+* fix a long standing bug where a signal would interrupt rb_thread_select and put the connection in a permanently broken state
+* turn on casting in the ActiveRecord again, users can disable it if they need to for performance reasons
+
+## 0.3.3 (June 14th, 2011)
+* disable async support, and access to the underlying file descriptor under Windows. It's never worked reliably and ruby-core has a lot of work to do in order to make it possible.
+* added support for turning eager-casting off. This is especially useful in ORMs that will lazily cast values upon access.
+* added a warning if a 0.2.x release is being used with ActiveRecord 3.1 since both the 0.2.x releases and AR 3.1 have mysql2 adapters, we want you to use the one in AR 3.1
+* added Mysql2::Client.escape (class-level method)
+* disabled eager-casting in the bundled ActiveRecord adapter (for Rails 3.0 or less)
+
+## 0.3.2 (April 26th, 2011)
+* Fix typo in initialization for older ActiveRecord versions
+
+## 0.3.1 (April 26th, 2011)
+* Fix typo in initialization for older ActiveRecord versions
+
+## 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.17 (November 9th, 2011)
+
+## 0.2.16 (November 9th, 2011)
+
+## 0.2.15 (November 9th, 2011)
+
+## 0.2.14 (November 9th, 2011)
+* use rb_wait_for_single_fd() if available
+* fixed a bug with inheriting query options
+* remove ext/ from the default loadpath
+* fix build issues on OSX with Xcode 4.2 (gcc-llvm compiler)
+
+## 0.2.13 (August 16th, 2011)
+* fix stupid bug around symbol encoding support (thanks coderrr!)
+
+## 0.2.12 (August 16th, 2011)
+* ensure symbolized column names support encodings in 1.9
+* plugging sql vulnerability in mysql2 adapter
+
+## 0.2.11 (June 17th, 2011)
+* fix bug in Time/DateTime range detection
+* (win32) fix bug where the Mysql2::Client object wasn't cleaned up properly if interrupted during a query
+* add Mysql2::Result#count (aliased as size) to get the row count for the dataset
+  this can be especially helpful if you want to get the number of rows without having to inflate
+  the entire dataset into ruby (since this happens lazily)
+
+## 0.2.10 (June 15th, 2011)
+* bug fix for Time/DateTime usage depending on 32/64bit Ruby
+
+## 0.2.9 (June 15th, 2011)
+* fix a long standing bug where a signal would interrupt rb_thread_select and put the connection in a permanently broken state
+* turn on casting in the ActiveRecord again, users can disable it if they need to for performance reasons
+
+## 0.2.8 (June 14th, 2011)
+* disable async support, and access to the underlying file descriptor under Windows. It's never worked reliably and ruby-core has a lot of work to do in order to make it possible.
+* added support for turning eager-casting off. This is especially useful in ORMs that will lazily cast values upon access.
+* added a warning if a 0.2.x release is being used with ActiveRecord 3.1 since both the 0.2.x releases and AR 3.1 have mysql2 adapters, we want you to use the one in AR 3.1
+* added Mysql2::Client.escape (class-level method)
+* disabled eager-casting in the bundled ActiveRecord adapter (for Rails 3.0 or less)
+
+## 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/MIT-LICENSE

@@ -0,0 +1,20 @@
+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.md

@@ -0,0 +1,350 @@
+# 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 classes:
+
+Mysql2::Client - your connection to the database
+
+Mysql2::Result - returned from issuing a #query on the connection. It includes Enumerable.
+
+## Installing
+
+``` sh
+gem install mysql2
+```
+
+You may have to specify --with-mysql-config=/some/random/path/bin/mysql_config
+
+## Usage
+
+Connect to a database:
+
+``` ruby
+# 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:
+
+``` ruby
+results = client.query("SELECT * FROM users WHERE group='githubbers'")
+```
+
+Need to escape something first?
+
+``` ruby
+escaped = client.escape("gi'thu\"bbe\0r's")
+results = client.query("SELECT * FROM users WHERE group='#{escaped}'")
+```
+
+You can get a count of your results with `results.count`.
+
+Finally, iterate over the results:
+
+``` ruby
+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:
+
+``` ruby
+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?
+
+``` ruby
+# 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:
+
+``` ruby
+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
+```
+
+You can also retrieve multiple result sets. For this to work you need to connect with
+flags `Mysql2::Client::MULTI_STATEMENTS`. Using multiple result sets is normally used
+when calling stored procedures that return more than one result set
+
+``` ruby
+client = Mysql2::Client.new(:host => "localhost", :username => "root", :flags => Mysql2::Client::MULTI_STATEMENTS )
+result = client.query( 'CALL sp_customer_list( 25, 10 )')
+# result now contains the first result set
+while ( client.next_result)
+    result = client.store_result
+    # result now contains the next result set
+end
+```
+
+See https://gist.github.com/1367987 for using MULTI_STATEMENTS with ActiveRecord.
+
+## Cascading config
+
+The default config hash is at:
+
+``` ruby
+Mysql2::Client.default_query_options
+```
+
+which defaults to:
+
+``` ruby
+{:async => false, :as => :hash, :symbolize_keys => false}
+```
+
+that can be used as so:
+
+``` ruby
+# these are the defaults all Mysql2::Client instances inherit
+Mysql2::Client.default_query_options.merge!(:as => :array)
+```
+
+or
+
+``` ruby
+# 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
+
+``` ruby
+# 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:
+
+``` ruby
+: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.
+
+``` ruby
+client = Mysql2::Client.new
+result = client.query("SELECT * FROM table_with_boolean_field", :cast_booleans => true)
+```
+
+### Skipping casting
+
+Mysql2 casting is fast, but not as fast as not casting data.  In rare cases where typecasting is not needed, it will be faster to disable it by providing :cast => false.
+
+``` ruby
+client = Mysql2::Client.new
+result = client.query("SELECT * FROM table", :cast => false)
+```
+
+Here are the results from the `query_without_mysql_casting.rb` script in the benchmarks folder:
+
+``` sh
+                           user     system      total        real
+Mysql2 (cast: true)    0.340000   0.000000   0.340000 (  0.405018)
+Mysql2 (cast: false)   0.160000   0.010000   0.170000 (  0.209937)
+Mysql                  0.080000   0.000000   0.080000 (  0.129355)
+do_mysql               0.520000   0.010000   0.530000 (  0.574619)
+```
+
+Although Mysql2 performs reasonably well at retrieving uncasted data, it (currently) is not as fast as the Mysql gem.  In spite of this small disadvantage, Mysql2 still sports a friendlier interface and doesn't block the entire ruby process when querying.
+
+### Async
+
+NOTE: Not supported on Windows.
+
+`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:
+
+``` ruby
+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:
+
+``` ruby
+# 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 or 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? :)
+
+NOTE: as of 0.3.0, and ActiveRecord 3.1 - the ActiveRecord adapter has been pulled out of this gem and into ActiveRecord itself. If you need to use mysql2 with
+Rails versions < 3.1 make sure and specify `gem "mysql2", "~> 0.2.7"` in your Gemfile
+
+## Asynchronous ActiveRecord
+
+Please see the [em-synchrony](https://github.com/igrigorik/em-synchrony) project for details about using EventMachine with mysql2 and Rails.
+
+## 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:
+
+``` ruby
+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
+
+``` sh
+ 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:
+
+``` sh
+bundle install
+rake
+```
+
+The tests require the "test" database to exist, and expect to connect
+both as root and the running user, both with a blank password:
+
+``` sql
+CREATE DATABASE test;
+CREATE USER '<user>'@'localhost' IDENTIFIED BY '';
+GRANT ALL PRIVILEGES ON test.* TO '<user>'@'localhost';
+```
+
+## 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)