mysql2 0.3.2 → 0.3.3

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 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
 
@@ -12,6 +19,13 @@
 * 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.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
@@ -151,4 +165,4 @@
 * updated extconf (thanks to the mysqlplus project) for easier gem building
 
 ## 0.1.0 (April 6th, 2010)
-* initial release
+* initial release

data/README.md

@@ -0,0 +1,324 @@
+# 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
+
+``` 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}'")
+```
+
+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
+```
+
+## 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 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? :)
+
+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
+
+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:
+
+``` 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
+```
+
+## 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/benchmark/query_without_mysql_casting.rb

@@ -14,9 +14,18 @@ sql = "SELECT * FROM mysql2_test LIMIT 100"
 Benchmark.bmbm do |x|
   mysql2 = Mysql2::Client.new(:host => "localhost", :username => "root")
   mysql2.query "USE #{database}"
-  x.report "Mysql2" do
+  x.report "Mysql2 (cast: true)" do
     number_of.times do
-      mysql2_result = mysql2.query sql, :symbolize_keys => true
+      mysql2_result = mysql2.query sql, :symbolize_keys => true, :cast => true
+      mysql2_result.each do |res|
+        # puts res.inspect
+      end
+    end
+  end
+
+  x.report "Mysql2 (cast: false)" do
+    number_of.times do
+      mysql2_result = mysql2.query sql, :symbolize_keys => true, :cast => false
       mysql2_result.each do |res|
         # puts res.inspect
       end

data/ext/mysql2/client.c

@@ -139,10 +139,6 @@ static VALUE nogvl_close(void *ptr) {
     flags = fcntl(wrapper->client->net.fd, F_GETFL);
     if (flags > 0 && !(flags & O_NONBLOCK))
       fcntl(wrapper->client->net.fd, F_SETFL, flags | O_NONBLOCK);
-#else
-    u_long iMode;
-    iMode = 1;
-    ioctlsocket(wrapper->client->net.fd, FIONBIO, &iMode);
 #endif
 
     mysql_close(wrapper->client);
@@ -356,6 +352,7 @@ static VALUE rb_mysql_client_query(int argc, VALUE * argv, VALUE self) {
     return rb_raise_mysql2_error(wrapper);
   }
 
+#ifndef _WIN32
   read_timeout = rb_iv_get(self, "@read_timeout");
 
   tvp = NULL;
@@ -380,27 +377,11 @@ static VALUE rb_mysql_client_query(int argc, VALUE * argv, VALUE self) {
     for(;;) {
       int fd_set_fd = fd;
 
-#ifdef _WIN32
-      WSAPROTOCOL_INFO wsa_pi;
-      // dupicate the SOCKET from libmysql
-      int r = WSADuplicateSocket(fd, GetCurrentProcessId(), &wsa_pi);
-      SOCKET s = WSASocket(wsa_pi.iAddressFamily, wsa_pi.iSocketType, wsa_pi.iProtocol, &wsa_pi, 0, 0);
-      // create the CRT fd so ruby can get back to the SOCKET
-      fd_set_fd = _open_osfhandle(s, O_RDWR|O_BINARY);
-#endif
-
       FD_ZERO(&fdset);
       FD_SET(fd_set_fd, &fdset);
 
       retval = rb_thread_select(fd_set_fd + 1, &fdset, NULL, NULL, tvp);
 
-#ifdef _WIN32
-      // cleanup the CRT fd
-      _close(fd_set_fd);
-      // cleanup the duplicated SOCKET
-      closesocket(s);
-#endif
-
       if (retval == 0) {
         rb_raise(cMysql2Error, "Timeout waiting for a response from the last query. (waited %d seconds)", FIX2INT(read_timeout));
       }
@@ -420,6 +401,10 @@ static VALUE rb_mysql_client_query(int argc, VALUE * argv, VALUE self) {
   } else {
     return Qnil;
   }
+#else
+  // this will just block until the result is ready
+  return rb_mysql_client_async_result(self);
+#endif
 }
 
 static VALUE rb_mysql_client_real_escape(VALUE self, VALUE str) {
@@ -517,18 +502,12 @@ static VALUE rb_mysql_client_server_info(VALUE self) {
 
 static VALUE rb_mysql_client_socket(VALUE self) {
   GET_CLIENT(self);
+#ifndef _WIN32
   REQUIRE_OPEN_DB(wrapper);
   int fd_set_fd = wrapper->client->net.fd;
-#ifdef _WIN32
-  WSAPROTOCOL_INFO wsa_pi;
-  // dupicate the SOCKET from libmysql
-  int r = WSADuplicateSocket(wrapper->client->net.fd, GetCurrentProcessId(), &wsa_pi);
-  SOCKET s = WSASocket(wsa_pi.iAddressFamily, wsa_pi.iSocketType, wsa_pi.iProtocol, &wsa_pi, 0, 0);
-  // create the CRT fd so ruby can get back to the SOCKET
-  fd_set_fd = _open_osfhandle(s, O_RDWR|O_BINARY);
   return INT2NUM(fd_set_fd);
 #else
-  return INT2NUM(fd_set_fd);
+  rb_raise(cMysql2Error, "Raw access to the mysql file descriptor isn't supported on Windows");
 #endif
 }
 
@@ -559,8 +538,7 @@ static VALUE rb_mysql_client_thread_id(VALUE self) {
   return ULL2NUM(retVal);
 }
 
-static VALUE nogvl_ping(void *ptr)
-{
+static VALUE nogvl_ping(void *ptr) {
   MYSQL *client = ptr;
 
   return mysql_ping(client) == 0 ? Qtrue : Qfalse;

data/ext/mysql2/result.c

@@ -4,7 +4,7 @@
 static rb_encoding *binaryEncoding;
 #endif
 
-#define MYSQL2_MAX_YEAR 2058
+#define MYSQL2_MAX_YEAR 2038
 
 #ifdef NEGATIVE_TIME_T
   /* 1901-12-13 20:45:52 UTC : The oldest time in 32-bit signed time_t. */
@@ -22,7 +22,7 @@ static VALUE intern_encoding_from_charset;
 static ID intern_new, intern_utc, intern_local, intern_encoding_from_charset_code,
           intern_localtime, intern_local_offset, intern_civil, intern_new_offset;
 static VALUE sym_symbolize_keys, sym_as, sym_array, sym_database_timezone, sym_application_timezone,
-          sym_local, sym_utc, sym_cast_booleans, sym_cache_rows;
+          sym_local, sym_utc, sym_cast_booleans, sym_cache_rows, sym_cast;
 static ID intern_merge;
 
 static void rb_mysql_result_mark(void * wrapper) {
@@ -100,7 +100,32 @@ static VALUE rb_mysql_result_fetch_field(VALUE self, unsigned int idx, short int
   return rb_field;
 }
 
-static VALUE rb_mysql_result_fetch_row(VALUE self, ID db_timezone, ID app_timezone, int symbolizeKeys, int asArray, int castBool) {
+#ifdef HAVE_RUBY_ENCODING_H
+inline VALUE mysql2_set_field_string_encoding(VALUE val, MYSQL_FIELD field, rb_encoding *default_internal_enc, rb_encoding *conn_enc) {
+  // if binary flag is set, respect it's wishes
+  if (field.flags & BINARY_FLAG && field.charsetnr == 63) {
+    rb_enc_associate(val, binaryEncoding);
+  } else {
+    // lookup the encoding configured on this field
+    VALUE new_encoding = rb_funcall(cMysql2Client, intern_encoding_from_charset_code, 1, INT2NUM(field.charsetnr));
+    if (new_encoding != Qnil) {
+      // use the field encoding we were able to match
+      rb_encoding *enc = rb_to_encoding(new_encoding);
+      rb_enc_associate(val, enc);
+    } else {
+      // otherwise fall-back to the connection's encoding
+      rb_enc_associate(val, conn_enc);
+    }
+    if (default_internal_enc) {
+      val = rb_str_export_to_enc(val, default_internal_enc);
+    }
+  }
+  return val;
+}
+#endif
+
+
+static VALUE rb_mysql_result_fetch_row(VALUE self, ID db_timezone, ID app_timezone, int symbolizeKeys, int asArray, int castBool, int cast) {
   VALUE rowVal;
   mysql2_result_wrapper * wrapper;
   MYSQL_ROW row;
@@ -141,7 +166,19 @@ static VALUE rb_mysql_result_fetch_row(VALUE self, ID db_timezone, ID app_timezo
     VALUE field = rb_mysql_result_fetch_field(self, i, symbolizeKeys);
     if (row[i]) {
       VALUE val = Qnil;
-      switch(fields[i].type) {
+      enum enum_field_types type = fields[i].type;
+
+      if(!cast) {
+        if (type == MYSQL_TYPE_NULL) {
+          val = Qnil;
+        } else {
+          val = rb_str_new(row[i], fieldLengths[i]);
+#ifdef HAVE_RUBY_ENCODING_H
+          val = mysql2_set_field_string_encoding(val, fields[i], default_internal_enc, conn_enc);
+#endif
+        }
+      } else {
+        switch(type) {
         case MYSQL_TYPE_NULL:       // NULL-type field
           val = Qnil;
           break;
@@ -260,26 +297,10 @@ static VALUE rb_mysql_result_fetch_row(VALUE self, ID db_timezone, ID app_timezo
         default:
           val = rb_str_new(row[i], fieldLengths[i]);
 #ifdef HAVE_RUBY_ENCODING_H
-          // if binary flag is set, respect it's wishes
-          if (fields[i].flags & BINARY_FLAG && fields[i].charsetnr == 63) {
-            rb_enc_associate(val, binaryEncoding);
-          } else {
-            // lookup the encoding configured on this field
-            VALUE new_encoding = rb_funcall(cMysql2Client, intern_encoding_from_charset_code, 1, INT2NUM(fields[i].charsetnr));
-            if (new_encoding != Qnil) {
-              // use the field encoding we were able to match
-              rb_encoding *enc = rb_to_encoding(new_encoding);
-              rb_enc_associate(val, enc);
-            } else {
-              // otherwise fall-back to the connection's encoding
-              rb_enc_associate(val, conn_enc);
-            }
-            if (default_internal_enc) {
-              val = rb_str_export_to_enc(val, default_internal_enc);
-            }
-          }
+          val = mysql2_set_field_string_encoding(val, fields[i], default_internal_enc, conn_enc);
 #endif
           break;
+        }
       }
       if (asArray) {
         rb_ary_push(rowVal, val);
@@ -329,7 +350,7 @@ static VALUE rb_mysql_result_each(int argc, VALUE * argv, VALUE self) {
   ID db_timezone, app_timezone, dbTz, appTz;
   mysql2_result_wrapper * wrapper;
   unsigned long i;
-  int symbolizeKeys = 0, asArray = 0, castBool = 0, cacheRows = 1;
+  int symbolizeKeys = 0, asArray = 0, castBool = 0, cacheRows = 1, cast = 1;
 
   GetMysql2Result(self, wrapper);
 
@@ -356,6 +377,10 @@ static VALUE rb_mysql_result_each(int argc, VALUE * argv, VALUE self) {
     cacheRows = 0;
   }
 
+  if (rb_hash_aref(opts, sym_cast) == Qfalse) {
+    cast = 0;
+  }
+
   dbTz = rb_hash_aref(opts, sym_database_timezone);
   if (dbTz == sym_local) {
     db_timezone = intern_local;
@@ -400,7 +425,7 @@ static VALUE rb_mysql_result_each(int argc, VALUE * argv, VALUE self) {
       if (cacheRows && i < rowsProcessed) {
         row = rb_ary_entry(wrapper->rows, i);
       } else {
-        row = rb_mysql_result_fetch_row(self, db_timezone, app_timezone, symbolizeKeys, asArray, castBool);
+        row = rb_mysql_result_fetch_row(self, db_timezone, app_timezone, symbolizeKeys, asArray, castBool, cast);
         if (cacheRows) {
           rb_ary_store(wrapper->rows, i, row);
         }
@@ -473,6 +498,7 @@ void init_mysql2_result() {
   sym_database_timezone     = ID2SYM(rb_intern("database_timezone"));
   sym_application_timezone  = ID2SYM(rb_intern("application_timezone"));
   sym_cache_rows     = ID2SYM(rb_intern("cache_rows"));
+  sym_cast           = ID2SYM(rb_intern("cast"));
 
   opt_decimal_zero = rb_str_new2("0.0");
   rb_global_variable(&opt_decimal_zero); //never GC

data/lib/active_record/fiber_patches.rb

@@ -67,6 +67,34 @@ module ActiveRecord
 
         @connections = []
         @checked_out = []
+        @automatic_reconnect = true
+        @tables = {}
+
+        @columns     = Hash.new do |h, table_name|
+          h[table_name] = with_connection do |conn|
+
+            # Fetch a list of columns
+            conn.columns(table_name, "#{table_name} Columns").tap do |columns|
+
+              # set primary key information
+              columns.each do |column|
+                column.primary = column.name == primary_keys[table_name]
+              end
+            end
+          end
+        end
+
+        @columns_hash = Hash.new do |h, table_name|
+          h[table_name] = Hash[columns[table_name].map { |col|
+            [col.name, col]
+          }]
+        end
+
+        @primary_keys = Hash.new do |h, table_name|
+          h[table_name] = with_connection do |conn|
+            table_exists?(table_name) ? conn.primary_key(table_name) : 'id'
+          end
+        end
       end
 
       def clear_stale_cached_connections!
@@ -101,4 +129,4 @@ module ActiveRecord
     end
 
   end
-end
+end

data/lib/mysql2.rb

@@ -18,4 +18,4 @@ end
 if defined?(ActiveRecord::VERSION::STRING) && ActiveRecord::VERSION::STRING < "3.1"
   puts "WARNING: This version of mysql2 (#{Mysql2::VERSION}) doesn't ship with the ActiveRecord adapter bundled anymore as it's now part of Rails 3.1"
   puts "WARNING: Please use the 0.2.x releases if you plan on using it in Rails <= 3.0.x"
-end
+end

data/lib/mysql2/client.rb

@@ -9,7 +9,8 @@ module Mysql2
       :database_timezone => :local,   # timezone Mysql2 will assume datetime objects are stored in
       :application_timezone => nil,   # timezone Mysql2 will convert to before handing the object back to the caller
       :cache_rows => true,            # tells Mysql2 to use it's internal row cache for results
-      :connect_flags => REMEMBER_OPTIONS | LONG_PASSWORD | LONG_FLAG | TRANSACTIONS | PROTOCOL_41 | SECURE_CONNECTION
+      :connect_flags => REMEMBER_OPTIONS | LONG_PASSWORD | LONG_FLAG | TRANSACTIONS | PROTOCOL_41 | SECURE_CONNECTION,
+      :cast => true
     }
 
     def initialize(opts = {})

data/lib/mysql2/version.rb

@@ -1,3 +1,3 @@
 module Mysql2
-  VERSION = "0.3.2"
+  VERSION = "0.3.3"
 end

data/mysql2.gemspec

@@ -7,9 +7,6 @@ Gem::Specification.new do |s|
   s.date = Time.now.utc.strftime("%Y-%m-%d")
   s.email = %q{seniorlopez@gmail.com}
   s.extensions = ["ext/mysql2/extconf.rb"]
-  s.extra_rdoc_files = [
-    "README.rdoc"
-  ]
   s.files = `git ls-files`.split("\n")
   s.homepage = %q{http://github.com/brianmario/mysql2}
   s.rdoc_options = ["--charset=UTF-8"]

data/spec/mysql2/result_spec.rb

@@ -79,6 +79,16 @@ describe Mysql2::Result do
       @test_result = @client.query("SELECT * FROM mysql2_test ORDER BY id DESC LIMIT 1").first
     end
 
+    it "should return nil values for NULL and strings for everything else when :cast is false" do
+      result = @client.query('SELECT null_test, tiny_int_test, bool_cast_test, int_test, date_test, enum_test FROM mysql2_test WHERE bool_cast_test = 1 LIMIT 1', :cast => false).first
+      result["null_test"].should be_nil
+      result["tiny_int_test"].should  == "1"
+      result["bool_cast_test"].should == "1"
+      result["int_test"].should       == "10"
+      result["date_test"].should      == "2010-04-04"
+      result["enum_test"].should      == "val1"
+    end
+
     it "should return nil for a NULL value" do
       @test_result['null_test'].class.should eql(NilClass)
       @test_result['null_test'].should eql(nil)
@@ -173,6 +183,11 @@ describe Mysql2::Result do
       r.first['test'].class.should eql(DateTime)
     end
 
+    it "should return DateTime when time > year 2038" do
+      r = @client.query("SELECT CAST('2039-01-01 01:01:01' AS DATETIME) as test")
+      r.first['test'].class.should eql(DateTime)
+    end
+
     it "should return Time for a TIMESTAMP value when within the supported range" do
       @test_result['timestamp_test'].class.should eql(Time)
       @test_result['timestamp_test'].strftime("%F %T").should eql('2010-04-04 11:44:00')

data/spec/spec_helper.rb

@@ -45,6 +45,7 @@ RSpec.configure do |config|
         PRIMARY KEY (id)
       )
     ]
+    client.query "DELETE FROM mysql2_test;"
     client.query %[
       INSERT INTO mysql2_test (
         null_test, bit_test, tiny_int_test, bool_cast_test, small_int_test, medium_int_test, int_test, big_int_test,

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: mysql2
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 21
   prerelease: 
   segments: 
   - 0
   - 3
-  - 2
-  version: 0.3.2
+  - 3
+  version: 0.3.3
 platform: ruby
 authors: 
 - Brian Lopez
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-27 00:00:00 -07:00
+date: 2011-06-14 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -138,8 +138,8 @@ executables: []
 
 extensions: 
 - ext/mysql2/extconf.rb
-extra_rdoc_files: 
-- README.rdoc
+extra_rdoc_files: []
+
 files: 
 - .gitignore
 - .rspec
@@ -147,7 +147,7 @@ files:
 - CHANGELOG.md
 - Gemfile
 - MIT-LICENSE
-- README.rdoc
+- README.md
 - Rakefile
 - benchmark/active_record.rb
 - benchmark/active_record_threaded.rb
@@ -219,7 +219,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.3.10
 signing_key: 
 specification_version: 3
 summary: A simple, fast Mysql library for Ruby, binding to libmysql

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)