Merge branch 'master' into 0.2.x

Author: sodabrew

.travis.yml

@@ -1,20 +1,42 @@
 language: ruby
-rvm:
-  - 1.8.7
-  - 1.9.2
-  - 1.9.3
-  - 2.0.0
-  - 2.1.0
-  - ree
-  - rbx
-env: RBXOPT=-Xgc.honor_start=true
 bundler_args: --without benchmarks
 script:
   - bundle exec rake spec
 # Temporary workaround for broken Rubygems on Travis
 before_install:
   - gem update --system 2.1.11
   - gem --version
+  - |
+    bash -c " # Install MariaDB if DB=mariadb
+    if [[ x$DB =~ xmariadb ]]; then
+      sudo service mysql stop
+      sudo apt-get purge '^mysql*' 'libmysql*'
+      sudo apt-get install python-software-properties
+      sudo apt-key adv --recv-keys --keyserver hkp://keyserver.ubuntu.com:80 0xcbcb082a1bb943db
+      if [[ x$DB = xmariadb55 ]]; then
+        sudo add-apt-repository 'deb http://ftp.osuosl.org/pub/mariadb/repo/5.5/ubuntu precise main'
+      elif [[ x$DB = xmariadb10 ]]; then
+        sudo add-apt-repository 'deb http://ftp.osuosl.org/pub/mariadb/repo/10.0/ubuntu precise main'
+      fi
+      sudo apt-get update
+      sudo apt-get -o Dpkg::Options::=--force-confdef -o Dpkg::Options::=--force-confold -y install mariadb-server libmariadbd-dev
+    fi
+    "
+  - mysqld --version
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - 2.0.0
+  - 2.1.1
+  - ree
 matrix:
   allow_failures:
     - rvm: rbx
+  include:
+    - rvm: 2.0.0
+      env: DB=mariadb55
+    - rvm: 2.0.0
+      env: DB=mariadb10
+    - rvm: rbx
+      env: RBXOPT=-Xgc.honor_start=true

README.md

@@ -10,9 +10,9 @@ It also forces the use of UTF-8 [or binary] for the connection [and all strings
 
 The API consists of two classes:
 
-Mysql2::Client - your connection to the database
+`Mysql2::Client` - your connection to the database
 
-Mysql2::Result - returned from issuing a #query on the connection. It includes Enumerable.
+`Mysql2::Result` - returned from issuing a #query on the connection. It includes Enumerable.
 
 ## Installing
 ### OSX / Linux
@@ -119,8 +119,7 @@ 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|
+client.query("SELECT * FROM users WHERE group='githubbers'", :symbolize_keys => true) do |row|
   # do something with row, it's ready to rock
 end
 ```
@@ -157,10 +156,12 @@ Mysql2::Client.new(
   :local_infile = true/false,
   :secure_auth = true/false,
   :default_file = '/path/to/my.cfg',
-  :default_group = 'my.cfg section'
+  :default_group = 'my.cfg section',
+  :init_command => sql
   )
 ```
 
+
 ### SSL options
 
 Setting any of the following options will enable an SSL connection, but only if
@@ -252,6 +253,15 @@ the `:default_file` and `:default_group` paramters. For example:
 Mysql2::Client.new(:default_file => '/user/.my.cnf', :default_group => 'client')
 ```
 
+### Initial command on connect and reconnect
+
+If you specify the init_command option, the SQL string you provide will be executed after the connection is established.
+If `:reconnect` is set to `true`, init_command will also be executed after a successful reconnect.
+It is useful if you want to provide session options which survive reconnection.
+
+``` ruby
+Mysql2::Client.new(:init_command => "SET @@SESSION.sql_mode = 'STRICT_ALL_TABLES'")
+```
 
 ## Cascading config
 
@@ -390,23 +400,50 @@ There are a few things that need to be kept in mind while using streaming:
 
 Read more about the consequences of using `mysql_use_result` (what streaming is implemented with) here: http://dev.mysql.com/doc/refman/5.0/en/mysql-use-result.html.
 
-## Active Record
+### 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
+
+This gem is tested with the following Ruby versions on Linux and Mac OS X:
+
+ * Ruby MRI 1.8.7, 1.9.2, 1.9.3, 2.0.0, 2.1.x (ongoing patch releases)
+ * Ruby Enterprise Edition (based on MRI 1.8.7)
+ * Rubinius 2.x
+
+This gem is tested with the following MySQL and MariaDB versions:
+
+ * MySQL 5.0, 5.1, 5.5, 5.6
+ * MySQL Connector/C 6.0 and 6.1 (primarily on Windows)
+ * MariaDB 5.5, 10.0
 
-To use the Active Record 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? :)
+### Active Record
 
-NOTE: as of 0.3.0, and Active Record 3.1 - the Active Record adapter has been pulled out of this gem and into Active Record itself. If you need to use mysql2 with
-Rails versions < 3.1 make sure and specify `gem "mysql2", "~> 0.2.7"` in your Gemfile
+ * mysql2 0.2.x includes an Active Record driver compatible with AR 2.3 and 3.0
+ * mysql2 0.3.x does not include an AR driver because it is included in AR 3.1 and above
 
-## Asynchronous Active Record
+### Asynchronous Active Record
 
 Please see the [em-synchrony](https://github.com/igrigorik/em-synchrony) project for details about using EventMachine with mysql2 and Rails.
 
-## Sequel
+### 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.
+Sequel includes a mysql2 adapter in all releases since 3.15 (2010-09-01).
+Use the prefix "mysql2://" in your connection specification.
 
-## EventMachine
+### 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:
@@ -429,64 +466,30 @@ EM.run do
 end
 ```
 
-## Lazy Everything
+## Benchmarks and Comparison
 
-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.
+The mysql2 gem converts MySQL field types to Ruby data types in C code, providing a serious speed benefit.
 
-## Compatibility
-
-This gem is regularly tested against the following Ruby versions on Linux and Mac OS X:
-
- * Ruby MRI 1.8.7, 1.9.2, 1.9.3, 2.0.0 (ongoing patch releases).
- * Ruby Enterprise Edition (based on MRI 1.8.7).
- * Rubinius 2.0 in compatibility modes 1.8, 1.9, 2.0.
-
-The mysql2 gem 0.2.x series includes an Active Record driver that works with AR
-2.3.x and 3.0.x. Starting in Active Record 3.1, a mysql2 driver is included in
-the Active Record codebase and no longer provided in mysql2 gem 0.3 and above.
-
-## Yeah... but why?
-
-Someone: Dude, the Mysql gem works fiiiiiine.
+The do_mysql gem also converts MySQL fields types, but has a considerably more complex API and is still ~2x slower than mysql2.
 
-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.
+The mysql gem returns only nil or string data types, leaving you to convert field values to Ruby types in Ruby-land, which is much slower than mysql2's C code.
 
-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
+For a comparative benchmark, the script below performs 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:
 
 ``` 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)
+         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)
 ```
 
+These results are from the `query_with_mysql_casting.rb` script in the benchmarks folder.
+
 ## 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