mysql2 0.1.9 → 0.2.0

data/.gitignore

@@ -4,5 +4,8 @@ Makefile
 *.bundle
 *.so
 *.a
+*.rbc
 mkmf.log
 pkg/
+tmp
+vendor

data/CHANGELOG.md

@@ -1,6 +1,17 @@
 # Changelog
 
-## 0.1.9 (HEAD)
+## 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 #34)
+* 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)

data/README.rdoc

@@ -58,6 +58,67 @@ How about with symbolized keys?
     # do something with row, it's ready to rock
   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.
@@ -77,14 +138,17 @@ If you need multiple query concurrency take a look at using a connection pool.
 
 == ActiveRecord
 
-To use the ActiveRecord driver, 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? :)
+The ActiveRecord adapter has been removed from the mysql2 gem and is now part of Rails 3 core. We'll be releasing a separate gem or trying to get it into 2.3.9 for 2.3.x users.
 
 == 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,
@@ -151,11 +215,11 @@ 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.890000   0.190000   1.080000 (  2.028887)
+   0.750000   0.180000   0.930000 (  1.821655)
   do_mysql
-   1.740000   0.220000   1.960000 (  2.909290)
+   1.650000   0.200000   1.850000 (  2.811357)
   Mysql
-   7.330000   0.350000   7.680000 (  8.013160)
+   7.500000   0.210000   7.710000 (  8.065871)
 
 == Special Thanks
 

data/Rakefile

@@ -20,8 +20,6 @@ end
 
 require 'rake'
 require 'spec/rake/spectask'
-gem 'rake-compiler', '>= 0.4.1'
-require "rake/extensiontask"
 
 desc "Run all examples with RCov"
 Spec::Rake::SpecTask.new('spec:rcov') do |t|
@@ -36,7 +34,7 @@ Spec::Rake::SpecTask.new('spec') do |t|
   t.spec_opts << '--options' << 'spec/spec.opts'
 end
 
-Rake::ExtensionTask.new("mysql2", JEWELER.gemspec) do |ext|
-  ext.lib_dir = File.join 'lib', 'mysql2'
-end
-Rake::Task[:spec].prerequisites << :compile
+task :default => :spec
+
+# Load custom tasks
+Dir['tasks/*.rake'].sort.each { |f| load f }

data/VERSION

@@ -1 +1 @@
-0.1.9
+0.2.0

data/benchmark/active_record.rb

@@ -5,6 +5,9 @@ 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',

data/benchmark/allocations.rb

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

@@ -7,31 +7,33 @@ require 'mysql'
 require 'mysql2'
 require 'do_mysql'
 
-number_of = 1000
-str = "abc'def\"ghi\0jkl%mno"
-
-Benchmark.bmbm do |x|
-  mysql = Mysql.new("localhost", "root")
-  x.report do
-    puts "Mysql"
-    number_of.times do
-      mysql.quote str
+def run_escape_benchmarks(str, number_of = 1000)
+  Benchmark.bmbm do |x|
+    mysql = Mysql.new("localhost", "root")
+    x.report do
+      puts "Mysql #{str.inspect}"
+      number_of.times do
+        mysql.quote str
+      end
     end
-  end
 
-  mysql2 = Mysql2::Client.new(:host => "localhost", :username => "root")
-  x.report do
-    puts "Mysql2"
-    number_of.times do
-      mysql2.escape str
+    mysql2 = Mysql2::Client.new(:host => "localhost", :username => "root")
+    x.report do
+      puts "Mysql2 #{str.inspect}"
+      number_of.times do
+        mysql2.escape str
+      end
     end
-  end
 
-  do_mysql = DataObjects::Connection.new("mysql://localhost/test")
-  x.report do
-    puts "do_mysql"
-    number_of.times do
-      do_mysql.quote_string str
+    do_mysql = DataObjects::Connection.new("mysql://localhost/test")
+    x.report do
+      puts "do_mysql #{str.inspect}"
+      number_of.times do
+        do_mysql.quote_string str
+      end
     end
   end
-end
+end
+
+run_escape_benchmarks "abc'def\"ghi\0jkl%mno"
+run_escape_benchmarks "clean string"

data/benchmark/query_with_mysql_casting.rb

@@ -45,8 +45,8 @@ Benchmark.bmbm do |x|
   x.report do
     puts "Mysql2"
     number_of.times do
-      mysql2_result = mysql2.query sql
-      mysql2_result.each(:symbolize_keys => true) do |res|
+      mysql2_result = mysql2.query sql, :symbolize_keys => true
+      mysql2_result.each do |res|
         # puts res.inspect
       end
     end

data/benchmark/query_without_mysql_casting.rb

@@ -17,8 +17,8 @@ Benchmark.bmbm do |x|
   x.report do
     puts "Mysql2"
     number_of.times do
-      mysql2_result = mysql2.query sql
-      mysql2_result.each(:symbolize_keys => true) do |res|
+      mysql2_result = mysql2.query sql, :symbolize_keys => true
+      mysql2_result.each do |res|
         # puts res.inspect
       end
     end

data/benchmark/setup_db.rb

@@ -22,8 +22,10 @@ create_table_sql = %[
     int_test INT,
     big_int_test BIGINT,
     float_test FLOAT(10,3),
+    float_zero_test FLOAT(10,3),
     double_test DOUBLE(10,3),
     decimal_test DECIMAL(10,3),
+    decimal_zero_test DECIMAL(10,3),
     date_test DATE,
     date_time_test DATETIME,
     timestamp_test TIMESTAMP,
@@ -55,7 +57,7 @@ def insert_record(args)
   insert_sql = "
     INSERT INTO mysql2_test (
       null_test, bit_test, tiny_int_test, small_int_test, medium_int_test, int_test, big_int_test,
-      float_test, double_test, decimal_test, date_test, date_time_test, timestamp_test, time_test,
+      float_test, float_zero_test, double_test, decimal_test, decimal_zero_test, date_test, date_time_test, timestamp_test, time_test,
       year_test, char_test, varchar_test, binary_test, varbinary_test, tiny_blob_test,
       tiny_text_test, blob_test, text_test, medium_blob_test, medium_text_test,
       long_blob_test, long_text_test, enum_test, set_test
@@ -63,7 +65,7 @@ def insert_record(args)
 
     VALUES (
       NULL, #{args[:bit_test]}, #{args[:tiny_int_test]}, #{args[:small_int_test]}, #{args[:medium_int_test]}, #{args[:int_test]}, #{args[:big_int_test]},
-      #{args[:float_test]}, #{args[:double_test]}, #{args[:decimal_test]}, '#{args[:date_test]}', '#{args[:date_time_test]}', '#{args[:timestamp_test]}', '#{args[:time_test]}',
+      #{args[:float_test]}, #{args[:float_zero_test]}, #{args[:double_test]}, #{args[:decimal_test]}, #{args[:decimal_zero_test]}, '#{args[:date_test]}', '#{args[:date_time_test]}', '#{args[:timestamp_test]}', '#{args[:time_test]}',
       #{args[:year_test]}, '#{args[:char_test]}', '#{args[:varchar_test]}', '#{args[:binary_test]}', '#{args[:varbinary_test]}', '#{args[:tiny_blob_test]}',
       '#{args[:tiny_text_test]}', '#{args[:blob_test]}', '#{args[:text_test]}', '#{args[:medium_blob_test]}', '#{args[:medium_text_test]}',
       '#{args[:long_blob_test]}', '#{args[:long_text_test]}', '#{args[:enum_test]}', '#{args[:set_test]}'
@@ -82,8 +84,10 @@ num.times do |n|
     :int_test => rand(2147483647),
     :big_int_test => rand(9223372036854775807),
     :float_test => rand(32767)/1.87,
+    :float_zero_test => 0.0,
     :double_test => rand(8388607)/1.87,
     :decimal_test => rand(8388607)/1.87,
+    :decimal_zero_test => 0,
     :date_test => '2010-4-4',
     :date_time_test => '2010-4-4 11:44:00',
     :timestamp_test => '2010-4-4 11:44:00',

data/benchmark/thread_alone.rb

@@ -0,0 +1,20 @@
+# encoding: UTF-8
+$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + '/../lib')
+
+require 'rubygems'
+require 'benchmark'
+require 'mysql2'
+
+iterations = 1000
+client = Mysql2::Client.new(:host => "localhost", :username => "root", :database => "test")
+query = lambda{ iterations.times{ client.query("SELECT mysql2_test.* FROM mysql2_test") } }
+Benchmark.bmbm do |x|
+  x.report('select') do
+    query.call
+  end
+  x.report('rb_thread_select') do
+    thread = Thread.new{ sleep(10) }
+    query.call
+    thread.kill
+  end
+end

data/examples/threaded.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+
+$LOAD_PATH.unshift 'lib'
+require 'mysql2'
+require 'timeout'
+
+threads = []
+# Should never exceed worst case 3.5 secs across all 20 threads
+Timeout.timeout(3.5) do
+  20.times do
+    threads << Thread.new do
+      overhead = rand(3)
+      puts ">> thread #{Thread.current.object_id} query, #{overhead} sec overhead"
+      # 3 second overhead per query
+      Mysql2::Client.new(:host => "localhost", :username => "root").query("SELECT sleep(#{overhead}) as result")
+      puts "<< thread #{Thread.current.object_id} result, #{overhead} sec overhead"
+    end
+  end
+  threads.each{|t| t.join }
+end

data/ext/mysql2/client.c

@@ -0,0 +1,540 @@
+#include <mysql2_ext.h>
+#include <client.h>
+
+VALUE cMysql2Client;
+extern VALUE mMysql2, cMysql2Error;
+static VALUE intern_encoding_from_charset;
+static ID sym_id, sym_version, sym_async, sym_symbolize_keys, sym_as, sym_array;
+static ID intern_merge, intern_error_number_eql, intern_sql_state_eql;
+
+#define REQUIRE_OPEN_DB(_ctxt) \
+  if(!_ctxt->net.vio) { \
+    rb_raise(cMysql2Error, "closed MySQL connection"); \
+    return Qnil; \
+  }
+
+#define MARK_CONN_INACTIVE(conn) \
+  wrapper->active = 0;
+
+#define GET_CLIENT(self) \
+  mysql_client_wrapper *wrapper; \
+  MYSQL *client; \
+  Data_Get_Struct(self, mysql_client_wrapper, wrapper); \
+  client = &wrapper->client;
+
+/*
+ * used to pass all arguments to mysql_real_connect while inside
+ * rb_thread_blocking_region
+ */
+struct nogvl_connect_args {
+  MYSQL *mysql;
+  const char *host;
+  const char *user;
+  const char *passwd;
+  const char *db;
+  unsigned int port;
+  const char *unix_socket;
+  unsigned long client_flag;
+};
+
+/*
+ * used to pass all arguments to mysql_send_query while inside
+ * rb_thread_blocking_region
+ */
+struct nogvl_send_query_args {
+  MYSQL *mysql;
+  VALUE sql;
+};
+
+/*
+ * non-blocking mysql_*() functions that we won't be wrapping since
+ * they do not appear to hit the network nor issue any interruptible
+ * or blocking system calls.
+ *
+ * - mysql_affected_rows()
+ * - mysql_error()
+ * - mysql_fetch_fields()
+ * - mysql_fetch_lengths() - calls cli_fetch_lengths or emb_fetch_lengths
+ * - mysql_field_count()
+ * - mysql_get_client_info()
+ * - mysql_get_client_version()
+ * - mysql_get_server_info()
+ * - mysql_get_server_version()
+ * - mysql_insert_id()
+ * - mysql_num_fields()
+ * - mysql_num_rows()
+ * - mysql_options()
+ * - mysql_real_escape_string()
+ * - mysql_ssl_set()
+ */
+
+static void rb_mysql_client_mark(void * wrapper) {
+  mysql_client_wrapper * w = wrapper;
+  if (w) {
+    rb_gc_mark(w->encoding);
+  }
+}
+
+static VALUE rb_raise_mysql2_error(MYSQL *client) {
+  VALUE e = rb_exc_new2(cMysql2Error, mysql_error(client));
+  rb_funcall(e, intern_error_number_eql, 1, INT2NUM(mysql_errno(client)));
+  rb_funcall(e, intern_sql_state_eql, 1, rb_tainted_str_new2(mysql_sqlstate(client)));
+  rb_exc_raise(e);
+  return Qnil;
+}
+
+static VALUE nogvl_init(void *ptr) {
+  MYSQL * client = (MYSQL *)ptr;
+
+  /* may initialize embedded server and read /etc/services off disk */
+  client = mysql_init(NULL);
+
+  return client ? Qtrue : Qfalse;
+}
+
+static VALUE nogvl_connect(void *ptr) {
+  struct nogvl_connect_args *args = ptr;
+  MYSQL *client;
+
+  client = mysql_real_connect(args->mysql, args->host,
+                              args->user, args->passwd,
+                              args->db, args->port, args->unix_socket,
+                              args->client_flag);
+
+  return client ? Qtrue : Qfalse;
+}
+
+static void rb_mysql_client_free(void * ptr) {
+  mysql_client_wrapper * wrapper = (mysql_client_wrapper *)ptr;
+  MYSQL * client = &wrapper->client;
+
+  /*
+   * we'll send a QUIT message to the server, but that message is more of a
+   * formality than a hard requirement since the socket is getting shutdown
+   * anyways, so ensure the socket write does not block our interpreter
+   */
+  int fd = client->net.fd;
+  int flags;
+
+  if (fd >= 0) {
+    /*
+     * if the socket is dead we have no chance of blocking,
+     * so ignore any potential fcntl errors since they don't matter
+     */
+    flags = fcntl(fd, F_GETFL);
+    if (flags > 0 && !(flags & O_NONBLOCK))
+      fcntl(fd, F_SETFL, flags | O_NONBLOCK);
+  }
+
+  /* It's safe to call mysql_close() on an already closed connection. */
+  mysql_close(client);
+  xfree(ptr);
+}
+
+static VALUE nogvl_close(void * ptr) {
+  MYSQL *client = (MYSQL *)ptr;
+  mysql_close(client);
+  client->net.fd = -1;
+  return Qnil;
+}
+
+static VALUE allocate(VALUE klass) {
+  VALUE obj;
+  mysql_client_wrapper * wrapper;
+  obj = Data_Make_Struct(klass, mysql_client_wrapper, rb_mysql_client_mark, rb_mysql_client_free, wrapper);
+  wrapper->encoding = Qnil;
+  wrapper->active = 0;
+  return obj;
+}
+
+static VALUE rb_connect(VALUE self, VALUE user, VALUE pass, VALUE host, VALUE port, VALUE database, VALUE socket) {
+  struct nogvl_connect_args args;
+  GET_CLIENT(self)
+
+  args.host = NIL_P(host) ? "localhost" : StringValuePtr(host);
+  args.unix_socket = NIL_P(socket) ? NULL : StringValuePtr(socket);
+  args.port = NIL_P(port) ? 3306 : NUM2INT(port);
+  args.user = NIL_P(user) ? NULL : StringValuePtr(user);
+  args.passwd = NIL_P(pass) ? NULL : StringValuePtr(pass);
+  args.db = NIL_P(database) ? NULL : StringValuePtr(database);
+  args.mysql = client;
+  args.client_flag = 0;
+
+  if (rb_thread_blocking_region(nogvl_connect, &args, RUBY_UBF_IO, 0) == Qfalse) {
+    // unable to connect
+    return rb_raise_mysql2_error(client);
+  }
+
+  return self;
+}
+
+/*
+ * Immediately disconnect from the server, normally the garbage collector
+ * will disconnect automatically when a connection is no longer needed.
+ * Explicitly closing this will free up server resources sooner than waiting
+ * for the garbage collector.
+ */
+static VALUE rb_mysql_client_close(VALUE self) {
+  GET_CLIENT(self)
+
+  rb_thread_blocking_region(nogvl_close, client, RUBY_UBF_IO, 0);
+
+  return Qnil;
+}
+
+/*
+ * mysql_send_query is unlikely to block since most queries are small
+ * enough to fit in a socket buffer, but sometimes large UPDATE and
+ * INSERTs will cause the process to block
+ */
+static VALUE nogvl_send_query(void *ptr) {
+  struct nogvl_send_query_args *args = ptr;
+  int rv;
+  const char *sql = StringValuePtr(args->sql);
+  long sql_len = RSTRING_LEN(args->sql);
+
+  rv = mysql_send_query(args->mysql, sql, sql_len);
+
+  return rv == 0 ? Qtrue : Qfalse;
+}
+
+/*
+ * even though we did rb_thread_select before calling this, a large
+ * response can overflow the socket buffers and cause us to eventually
+ * block while calling mysql_read_query_result
+ */
+static VALUE nogvl_read_query_result(void *ptr) {
+  MYSQL * client = ptr;
+  my_bool res = mysql_read_query_result(client);
+
+  return res == 0 ? Qtrue : Qfalse;
+}
+
+/* mysql_store_result may (unlikely) read rows off the socket */
+static VALUE nogvl_store_result(void *ptr) {
+  MYSQL * client = ptr;
+  return (VALUE)mysql_store_result(client);
+}
+
+static VALUE rb_mysql_client_async_result(VALUE self) {
+  MYSQL_RES * result;
+  GET_CLIENT(self)
+
+  REQUIRE_OPEN_DB(client);
+  if (rb_thread_blocking_region(nogvl_read_query_result, client, RUBY_UBF_IO, 0) == Qfalse) {
+    // an error occurred, mark this connection inactive
+    MARK_CONN_INACTIVE(self);
+    return rb_raise_mysql2_error(client);
+  }
+
+  result = (MYSQL_RES *)rb_thread_blocking_region(nogvl_store_result, client, RUBY_UBF_IO, 0);
+
+  // we have our result, mark this connection inactive
+  MARK_CONN_INACTIVE(self);
+
+  if (result == NULL) {
+    if (mysql_field_count(client) != 0) {
+      rb_raise_mysql2_error(client);
+    }
+    return Qnil;
+  }
+
+  VALUE resultObj = rb_mysql_result_to_obj(result);
+  // pass-through query options for result construction later
+  rb_iv_set(resultObj, "@query_options", rb_obj_dup(rb_iv_get(self, "@query_options")));
+
+#ifdef HAVE_RUBY_ENCODING_H
+  mysql2_result_wrapper * result_wrapper;
+  GetMysql2Result(resultObj, result_wrapper);
+  result_wrapper->encoding = wrapper->encoding;
+#endif
+  return resultObj;
+}
+
+static VALUE rb_mysql_client_query(int argc, VALUE * argv, VALUE self) {
+  struct nogvl_send_query_args args;
+  fd_set fdset;
+  int fd, retval;
+  int async = 0;
+  VALUE opts, defaults;
+  int(*selector)(int, fd_set *, fd_set *, fd_set *, struct timeval *) = NULL;
+  GET_CLIENT(self)
+
+  REQUIRE_OPEN_DB(client);
+  args.mysql = client;
+
+  // see if this connection is still waiting on a result from a previous query
+  if (wrapper->active == 0) {
+    // mark this connection active
+    wrapper->active = 1;
+  } else {
+    rb_raise(cMysql2Error, "This connection is still waiting for a result, try again once you have the result");
+  }
+
+  defaults = rb_iv_get(self, "@query_options");
+  if (rb_scan_args(argc, argv, "11", &args.sql, &opts) == 2) {
+    opts = rb_funcall(defaults, intern_merge, 1, opts);
+    rb_iv_set(self, "@query_options", opts);
+
+    if (rb_hash_aref(opts, sym_async) == Qtrue) {
+      async = 1;
+    }
+  } else {
+    opts = defaults;
+  }
+
+#ifdef HAVE_RUBY_ENCODING_H
+  rb_encoding *conn_enc = rb_to_encoding(wrapper->encoding);
+  // ensure the string is in the encoding the connection is expecting
+  args.sql = rb_str_export_to_enc(args.sql, conn_enc);
+#endif
+
+  if (rb_thread_blocking_region(nogvl_send_query, &args, RUBY_UBF_IO, 0) == Qfalse) {
+    // an error occurred, we're not active anymore
+    MARK_CONN_INACTIVE(self);
+    return rb_raise_mysql2_error(client);
+  }
+
+  if (!async) {
+    // the below code is largely from do_mysql
+    // http://github.com/datamapper/do
+    fd = client->net.fd;
+    selector = rb_thread_alone() ? *select : *rb_thread_select;
+    for(;;) {
+      FD_ZERO(&fdset);
+      FD_SET(fd, &fdset);
+
+      retval = selector(fd + 1, &fdset, NULL, NULL, NULL);
+
+      if (retval < 0) {
+        rb_sys_fail(0);
+      }
+
+      if (retval > 0) {
+        break;
+      }
+    }
+
+    VALUE result = rb_mysql_client_async_result(self);
+
+    return result;
+  } else {
+    return Qnil;
+  }
+}
+
+static VALUE rb_mysql_client_escape(VALUE self, VALUE str) {
+  VALUE newStr;
+  unsigned long newLen, oldLen;
+  GET_CLIENT(self)
+
+  Check_Type(str, T_STRING);
+#ifdef HAVE_RUBY_ENCODING_H
+  rb_encoding *default_internal_enc = rb_default_internal_encoding();
+  rb_encoding *conn_enc = rb_to_encoding(wrapper->encoding);
+  // ensure the string is in the encoding the connection is expecting
+  str = rb_str_export_to_enc(str, conn_enc);
+#endif
+
+  oldLen = RSTRING_LEN(str);
+  char escaped[(oldLen*2)+1];
+
+  REQUIRE_OPEN_DB(client);
+  newLen = mysql_real_escape_string(client, escaped, StringValuePtr(str), oldLen);
+  if (newLen == oldLen) {
+    // no need to return a new ruby string if nothing changed
+    return str;
+  } else {
+    newStr = rb_str_new(escaped, newLen);
+#ifdef HAVE_RUBY_ENCODING_H
+    rb_enc_associate(newStr, conn_enc);
+    if (default_internal_enc) {
+      newStr = rb_str_export_to_enc(newStr, default_internal_enc);
+    }
+#endif
+    return newStr;
+  }
+}
+
+static VALUE rb_mysql_client_info(VALUE self) {
+  VALUE version = rb_hash_new(), client_info;
+  GET_CLIENT(self);
+#ifdef HAVE_RUBY_ENCODING_H
+  rb_encoding *default_internal_enc = rb_default_internal_encoding();
+  rb_encoding *conn_enc = rb_to_encoding(wrapper->encoding);
+#endif
+
+  rb_hash_aset(version, sym_id, LONG2NUM(mysql_get_client_version()));
+  client_info = rb_str_new2(mysql_get_client_info());
+#ifdef HAVE_RUBY_ENCODING_H
+  rb_enc_associate(client_info, conn_enc);
+  if (default_internal_enc) {
+    client_info = rb_str_export_to_enc(client_info, default_internal_enc);
+  }
+#endif
+  rb_hash_aset(version, sym_version, client_info);
+  return version;
+}
+
+static VALUE rb_mysql_client_server_info(VALUE self) {
+  VALUE version, server_info;
+  GET_CLIENT(self)
+#ifdef HAVE_RUBY_ENCODING_H
+  rb_encoding *default_internal_enc = rb_default_internal_encoding();
+  rb_encoding *conn_enc = rb_to_encoding(wrapper->encoding);
+#endif
+
+  REQUIRE_OPEN_DB(client);
+
+  version = rb_hash_new();
+  rb_hash_aset(version, sym_id, LONG2FIX(mysql_get_server_version(client)));
+  server_info = rb_str_new2(mysql_get_server_info(client));
+#ifdef HAVE_RUBY_ENCODING_H
+  rb_enc_associate(server_info, conn_enc);
+  if (default_internal_enc) {
+    server_info = rb_str_export_to_enc(server_info, default_internal_enc);
+  }
+#endif
+  rb_hash_aset(version, sym_version, server_info);
+  return version;
+}
+
+static VALUE rb_mysql_client_socket(VALUE self) {
+  GET_CLIENT(self)
+  REQUIRE_OPEN_DB(client);
+  return INT2NUM(client->net.fd);
+}
+
+static VALUE rb_mysql_client_last_id(VALUE self) {
+  GET_CLIENT(self)
+  REQUIRE_OPEN_DB(client);
+  return ULL2NUM(mysql_insert_id(client));
+}
+
+static VALUE rb_mysql_client_affected_rows(VALUE self) {
+  GET_CLIENT(self)
+  REQUIRE_OPEN_DB(client);
+  return ULL2NUM(mysql_affected_rows(client));
+}
+
+static VALUE set_reconnect(VALUE self, VALUE value) {
+  my_bool reconnect;
+  GET_CLIENT(self)
+
+  if(!NIL_P(value)) {
+    reconnect = value == Qfalse ? 0 : 1;
+
+    /* set default reconnect behavior */
+    if (mysql_options(client, MYSQL_OPT_RECONNECT, &reconnect)) {
+      /* TODO: warning - unable to set reconnect behavior */
+      rb_warn("%s\n", mysql_error(client));
+    }
+  }
+  return value;
+}
+
+static VALUE set_connect_timeout(VALUE self, VALUE value) {
+  unsigned int connect_timeout = 0;
+  GET_CLIENT(self)
+
+  if(!NIL_P(value)) {
+    connect_timeout = NUM2INT(value);
+    if(0 == connect_timeout) return value;
+
+    /* set default connection timeout behavior */
+    if (mysql_options(client, MYSQL_OPT_CONNECT_TIMEOUT, &connect_timeout)) {
+      /* TODO: warning - unable to set connection timeout */
+      rb_warn("%s\n", mysql_error(client));
+    }
+  }
+  return value;
+}
+
+static VALUE set_charset_name(VALUE self, VALUE value) {
+  char * charset_name;
+  GET_CLIENT(self)
+
+#ifdef HAVE_RUBY_ENCODING_H
+  VALUE new_encoding;
+  new_encoding = rb_funcall(cMysql2Client, intern_encoding_from_charset, 1, value);
+  if (new_encoding == Qnil) {
+    rb_raise(cMysql2Error, "Unsupported charset: '%s'", RSTRING_PTR(value));
+  } else {
+    if (wrapper->encoding == Qnil) {
+      wrapper->encoding = new_encoding;
+    }
+  }
+#endif
+
+  charset_name = StringValuePtr(value);
+
+  if (mysql_options(client, MYSQL_SET_CHARSET_NAME, charset_name)) {
+    /* TODO: warning - unable to set charset */
+    rb_warn("%s\n", mysql_error(client));
+  }
+
+  return value;
+}
+
+static VALUE set_ssl_options(VALUE self, VALUE key, VALUE cert, VALUE ca, VALUE capath, VALUE cipher) {
+  GET_CLIENT(self)
+
+  if(!NIL_P(ca) || !NIL_P(key)) {
+    mysql_ssl_set(client,
+        NIL_P(key) ? NULL : StringValuePtr(key),
+        NIL_P(cert) ? NULL : StringValuePtr(cert),
+        NIL_P(ca) ? NULL : StringValuePtr(ca),
+        NIL_P(capath) ? NULL : StringValuePtr(capath),
+        NIL_P(cipher) ? NULL : StringValuePtr(cipher));
+  }
+
+  return self;
+}
+
+static VALUE init_connection(VALUE self) {
+  GET_CLIENT(self)
+
+  if (rb_thread_blocking_region(nogvl_init, client, RUBY_UBF_IO, 0) == Qfalse) {
+    /* TODO: warning - not enough memory? */
+    return rb_raise_mysql2_error(client);
+  }
+
+  return self;
+}
+
+void init_mysql2_client() {
+  cMysql2Client = rb_define_class_under(mMysql2, "Client", rb_cObject);
+
+  rb_define_alloc_func(cMysql2Client, allocate);
+
+  rb_define_method(cMysql2Client, "close", rb_mysql_client_close, 0);
+  rb_define_method(cMysql2Client, "query", rb_mysql_client_query, -1);
+  rb_define_method(cMysql2Client, "escape", rb_mysql_client_escape, 1);
+  rb_define_method(cMysql2Client, "info", rb_mysql_client_info, 0);
+  rb_define_method(cMysql2Client, "server_info", rb_mysql_client_server_info, 0);
+  rb_define_method(cMysql2Client, "socket", rb_mysql_client_socket, 0);
+  rb_define_method(cMysql2Client, "async_result", rb_mysql_client_async_result, 0);
+  rb_define_method(cMysql2Client, "last_id", rb_mysql_client_last_id, 0);
+  rb_define_method(cMysql2Client, "affected_rows", rb_mysql_client_affected_rows, 0);
+
+  rb_define_private_method(cMysql2Client, "reconnect=", set_reconnect, 1);
+  rb_define_private_method(cMysql2Client, "connect_timeout=", set_connect_timeout, 1);
+  rb_define_private_method(cMysql2Client, "charset_name=", set_charset_name, 1);
+  rb_define_private_method(cMysql2Client, "ssl_set", set_ssl_options, 5);
+  rb_define_private_method(cMysql2Client, "init_connection", init_connection, 0);
+  rb_define_private_method(cMysql2Client, "connect", rb_connect, 6);
+
+  intern_encoding_from_charset = rb_intern("encoding_from_charset");
+
+  sym_id              = ID2SYM(rb_intern("id"));
+  sym_version         = ID2SYM(rb_intern("version"));
+  sym_async           = ID2SYM(rb_intern("async"));
+  sym_symbolize_keys  = ID2SYM(rb_intern("symbolize_keys"));
+  sym_as              = ID2SYM(rb_intern("as"));
+  sym_array           = ID2SYM(rb_intern("array"));
+
+  intern_merge = rb_intern("merge");
+  intern_error_number_eql = rb_intern("error_number=");
+  intern_sql_state_eql = rb_intern("sql_state=");
+
+}