rdp-mysql2 0.2.7.1
Sign up to get free protection for your applications and to get access to all the features.
- data/.gitignore +12 -0
- data/.rspec +2 -0
- data/.rvmrc +1 -0
- data/CHANGELOG.md +142 -0
- data/Gemfile +3 -0
- data/MIT-LICENSE +20 -0
- data/README.rdoc +261 -0
- data/Rakefile +5 -0
- data/benchmark/active_record.rb +51 -0
- data/benchmark/active_record_threaded.rb +42 -0
- data/benchmark/allocations.rb +33 -0
- data/benchmark/escape.rb +36 -0
- data/benchmark/query_with_mysql_casting.rb +80 -0
- data/benchmark/query_without_mysql_casting.rb +47 -0
- data/benchmark/sequel.rb +37 -0
- data/benchmark/setup_db.rb +119 -0
- data/benchmark/threaded.rb +44 -0
- data/examples/eventmachine.rb +21 -0
- data/examples/threaded.rb +20 -0
- data/ext/mysql2/client.c +839 -0
- data/ext/mysql2/client.h +41 -0
- data/ext/mysql2/extconf.rb +72 -0
- data/ext/mysql2/mysql2_ext.c +12 -0
- data/ext/mysql2/mysql2_ext.h +42 -0
- data/ext/mysql2/result.c +488 -0
- data/ext/mysql2/result.h +20 -0
- data/lib/active_record/connection_adapters/em_mysql2_adapter.rb +64 -0
- data/lib/active_record/connection_adapters/mysql2_adapter.rb +654 -0
- data/lib/active_record/fiber_patches.rb +104 -0
- data/lib/arel/engines/sql/compilers/mysql2_compiler.rb +11 -0
- data/lib/mysql2.rb +16 -0
- data/lib/mysql2/client.rb +240 -0
- data/lib/mysql2/em.rb +37 -0
- data/lib/mysql2/em_fiber.rb +31 -0
- data/lib/mysql2/error.rb +15 -0
- data/lib/mysql2/result.rb +5 -0
- data/lib/mysql2/version.rb +3 -0
- data/mysql2.gemspec +32 -0
- data/spec/em/em_fiber_spec.rb +22 -0
- data/spec/em/em_spec.rb +49 -0
- data/spec/mysql2/client_spec.rb +430 -0
- data/spec/mysql2/error_spec.rb +69 -0
- data/spec/mysql2/result_spec.rb +333 -0
- data/spec/rcov.opts +3 -0
- data/spec/spec_helper.rb +66 -0
- data/tasks/benchmarks.rake +20 -0
- data/tasks/compile.rake +71 -0
- data/tasks/rspec.rake +16 -0
- data/tasks/vendor_mysql.rake +40 -0
- metadata +236 -0
data/.gitignore
ADDED
data/.rspec
ADDED
data/.rvmrc
ADDED
@@ -0,0 +1 @@
|
|
1
|
+
rvm use 1.9.2@mysql2 --create
|
data/CHANGELOG.md
ADDED
@@ -0,0 +1,142 @@
|
|
1
|
+
# Changelog
|
2
|
+
|
3
|
+
## 0.2.7 (March 28th, 2011)
|
4
|
+
* various fixes for em_mysql2 and fiber usage
|
5
|
+
* use our own Mysql2IndexDefinition class for better compatibility across ActiveRecord versions
|
6
|
+
* ensure the query is a string earlier in the Mysql2::Client#query codepath for 1.9
|
7
|
+
* only set binary ruby encoding on fields that have a binary flag *and* encoding set
|
8
|
+
* a few various optimizations
|
9
|
+
* add support for :read_timeout to be set on a connection
|
10
|
+
* Fix to install with MariDB on Windows
|
11
|
+
* add fibered em connection without activerecord
|
12
|
+
* fix some 1.9.3 compilation warnings
|
13
|
+
* add LD_RUN_PATH when using hard coded mysql paths - this should help users with MySQL installed in non-standard locations
|
14
|
+
* for windows support, duplicate the socket from libmysql and create a temporary CRT fd
|
15
|
+
* fix for handling years before 1970 on Windows
|
16
|
+
* fixes to the Fiber adapter
|
17
|
+
* set wait_timeout maximum on Windows to 2147483
|
18
|
+
* update supported range for Time objects
|
19
|
+
* upon being required, make sure the libmysql we're using is the one we were built against
|
20
|
+
* add Mysql2::Client#thread_id
|
21
|
+
* add Mysql2::Client#ping
|
22
|
+
* switch connection check in AR adapter to use Mysql2::Client#ping for efficiency
|
23
|
+
* prefer linking against thread-safe version of libmysqlclient
|
24
|
+
* define RSTRING_NOT_MODIFIED for an awesome rbx speed boost
|
25
|
+
* expose Mysql2::Client#encoding in 1.9, make sure we set the error message and sqlstate encodings accordingly
|
26
|
+
* do not segfault when raising for invalid charset (found in 1.9.3dev)
|
27
|
+
|
28
|
+
## 0.2.6 (October 19th, 2010)
|
29
|
+
* version bump since the 0.2.5 win32 binary gems were broken
|
30
|
+
|
31
|
+
## 0.2.5 (October 19th, 2010)
|
32
|
+
* fixes for easier Win32 binary gem deployment for targeting 1.8 and 1.9 in the same gem
|
33
|
+
* refactor of connection checks and management to avoid race conditions with the GC/threading to prevent the unexpected loss of connections
|
34
|
+
* update the default flags during connection
|
35
|
+
* add support for setting wait_timeout on AR adapter
|
36
|
+
* upgrade to rspec2
|
37
|
+
* bugfix for an edge case where the GC would clean up a Mysql2::Client object before the underlying MYSQL pointer had been initialized
|
38
|
+
* fix to CFLAGS to allow compilation on SPARC with sunstudio compiler - Anko painting <anko.com+github@gmail.com>
|
39
|
+
|
40
|
+
## 0.2.4 (September 17th, 2010)
|
41
|
+
* a few patches for win32 support from Luis Lavena - thanks man!
|
42
|
+
* bugfix from Eric Wong to avoid a potential stack overflow during Mysql2::Client#escape
|
43
|
+
* added the ability to turn internal row caching on/off via the :cache_rows => true/false option
|
44
|
+
* a couple of small patches for rbx compatibility
|
45
|
+
* set IndexDefinition#length in AR adapter - Kouhei Yanagita <yanagi@shakenbu.org>
|
46
|
+
* fix a long-standing data corruption bug - thank you thank you thank you to @joedamato (http://github.com/ice799)
|
47
|
+
* bugfix from calling mysql_close on a closed/freed connection surfaced by the above fix
|
48
|
+
|
49
|
+
## 0.2.3 (August 20th, 2010)
|
50
|
+
* connection flags can now be passed to the constructor via the :flags key
|
51
|
+
* switch AR adapter connection over to use FOUND_ROWS option
|
52
|
+
* 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
|
53
|
+
|
54
|
+
## 0.2.2 (August 19th, 2010)
|
55
|
+
* Change how AR adapter would send initial commands upon connecting
|
56
|
+
** we can make multiple session variable assignments in a single query
|
57
|
+
* fix signal handling when waiting on queries
|
58
|
+
* retry connect if interrupted by signals
|
59
|
+
|
60
|
+
## 0.2.1 (August 16th, 2010)
|
61
|
+
* bring mysql2 ActiveRecord adapter back into gem
|
62
|
+
|
63
|
+
## 0.2.0 (August 16th, 2010)
|
64
|
+
* switch back to letting libmysql manage all allocation/thread-state/freeing for the connection
|
65
|
+
* cache various numeric type conversions in hot-spots of the code for a little speed boost
|
66
|
+
* ActiveRecord adapter moved into Rails 3 core
|
67
|
+
** 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
|
68
|
+
* Fix for the "closed MySQL connection" error (GH #31)
|
69
|
+
* Fix for the "can't modify frozen object" error in 1.9.2 (GH #37)
|
70
|
+
* Introduce cascading query and result options (more info in README)
|
71
|
+
* Sequel adapter pulled into core (will be in the next release - 3.15.0 at the time of writing)
|
72
|
+
* add a safety check when attempting to send a query before a result has been fetched
|
73
|
+
|
74
|
+
## 0.1.9 (July 17th, 2010)
|
75
|
+
* Support async ActiveRecord access with fibers and EventMachine (mperham)
|
76
|
+
* string encoding support for 1.9, respecting Encoding.default_internal
|
77
|
+
* added support for rake-compiler (tenderlove)
|
78
|
+
* bugfixes for ActiveRecord driver
|
79
|
+
** one minor bugfix for TimeZone support
|
80
|
+
** fix the select_rows method to return what it should according to the docs (r-stu31)
|
81
|
+
* Mysql2::Client#fields method added - returns the array of field names from a resultset, as strings
|
82
|
+
* Sequel adapter
|
83
|
+
** bugfix regarding sybolized field names (Eric Wong)
|
84
|
+
** fix query logging in Sequel adapter
|
85
|
+
* Lots of nice code cleanup (tenderlove)
|
86
|
+
** Mysql2::Error definition moved to pure-Ruby
|
87
|
+
** Mysql2::client#initialize definition moved to pure-Ruby
|
88
|
+
** Mysql2::Result partially moved to pure-Ruby
|
89
|
+
|
90
|
+
## 0.1.8 (June 2nd, 2010)
|
91
|
+
* fixes for AR adapter for timezone juggling
|
92
|
+
* fixes to be able to run benchmarks and specs under 1.9.2
|
93
|
+
|
94
|
+
## 0.1.7 (May 22nd, 2010)
|
95
|
+
* fix a bug when using the disconnect! method on a closed connection in the AR driver
|
96
|
+
|
97
|
+
## 0.1.6 (May 14th, 2010)
|
98
|
+
* more fixes to the AR adapter related to casting
|
99
|
+
* add missing index creation override method to AR adapter
|
100
|
+
* added sql_state and error_number methods to the Mysql2::Error exception class
|
101
|
+
|
102
|
+
## 0.1.5 (May 12th, 2010)
|
103
|
+
* quite a few patches from Eric Wong related to thread-safety, non-blocking I/O and general cleanup
|
104
|
+
** wrap mysql_real_connect with rb_thread_blocking_region
|
105
|
+
** release GVL for possibly blocking mysql_* library calls
|
106
|
+
** [cleanup] quiet down warnings
|
107
|
+
** [cleanup] make all C symbols static
|
108
|
+
** add Mysql2::Client#close method
|
109
|
+
** correctly free the wrapped result in case of EOF
|
110
|
+
** Fix memory leak from the result wrapper struct itself
|
111
|
+
** make Mysql2::Client destructor safely non-blocking
|
112
|
+
* bug fixes for ActiveRecord adapter
|
113
|
+
** added casting for default values since they all come back from Mysql as strings (!?!)
|
114
|
+
** missing constant was added
|
115
|
+
** fixed a typo in the show_variable method
|
116
|
+
* switched over sscanf for date/time parsing in C
|
117
|
+
* made some specs a little finer-grained
|
118
|
+
* initial Sequel adapter added
|
119
|
+
* updated query benchmarks to reflect the difference between casting in C and in Ruby
|
120
|
+
|
121
|
+
## 0.1.4 (April 23rd, 2010)
|
122
|
+
* 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
|
123
|
+
* optimization: implemented a local cache for field names so every row reuses the same objects as field names/keys
|
124
|
+
* refactor the Mysql2 connection adapter for ActiveRecord to not extend the Mysql adapter - now being a free-standing connection adapter
|
125
|
+
|
126
|
+
## 0.1.3 (April 15th, 2010)
|
127
|
+
* added an EventMachine Deferrable API
|
128
|
+
* added an ActiveRecord connection adapter
|
129
|
+
** should be compatible with 2.3.5 and 3.0 (including Arel)
|
130
|
+
|
131
|
+
## 0.1.2 (April 9th, 2010)
|
132
|
+
* fix a bug (copy/paste fail) around checking for empty TIME values and returning nil (thanks @marius)
|
133
|
+
|
134
|
+
## 0.1.1 (April 6th, 2010)
|
135
|
+
* added affected_rows method (mysql_affected_rows)
|
136
|
+
* added last_id method (last_insert_id)
|
137
|
+
* enable reconnect option by default
|
138
|
+
* added initial async query support
|
139
|
+
* updated extconf (thanks to the mysqlplus project) for easier gem building
|
140
|
+
|
141
|
+
## 0.1.0 (April 6th, 2010)
|
142
|
+
* initial release
|
data/Gemfile
ADDED
data/MIT-LICENSE
ADDED
@@ -0,0 +1,20 @@
|
|
1
|
+
Copyright (c) 2010-2011 Brian Lopez - http://github.com/brianmario
|
2
|
+
|
3
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
4
|
+
a copy of this software and associated documentation files (the
|
5
|
+
"Software"), to deal in the Software without restriction, including
|
6
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
7
|
+
distribute, sublicense, and/or sell copies of the Software, and to
|
8
|
+
permit persons to whom the Software is furnished to do so, subject to
|
9
|
+
the following conditions:
|
10
|
+
|
11
|
+
The above copyright notice and this permission notice shall be
|
12
|
+
included in all copies or substantial portions of the Software.
|
13
|
+
|
14
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
15
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
16
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
17
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
18
|
+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
19
|
+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
20
|
+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
data/README.rdoc
ADDED
@@ -0,0 +1,261 @@
|
|
1
|
+
= Mysql2 - A modern, simple and very fast Mysql library for Ruby - binding to libmysql
|
2
|
+
|
3
|
+
The Mysql2 gem is meant to serve the extremely common use-case of connecting, querying and iterating on results.
|
4
|
+
Some database libraries out there serve as direct 1:1 mappings of the already complex C API's available.
|
5
|
+
This one is not.
|
6
|
+
|
7
|
+
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.
|
8
|
+
|
9
|
+
The API consists of two clases:
|
10
|
+
|
11
|
+
Mysql2::Client - your connection to the database
|
12
|
+
|
13
|
+
Mysql2::Result - returned from issuing a #query on the connection. It includes Enumerable.
|
14
|
+
|
15
|
+
== Installing
|
16
|
+
|
17
|
+
gem install mysql2
|
18
|
+
|
19
|
+
You may have to specify --with-mysql-config=/some/random/path/bin/mysql_config
|
20
|
+
|
21
|
+
On windows it will either install a binary for you, or, barring that, install like
|
22
|
+
|
23
|
+
gem install mysql2 -- --with-mysql-dir=c:\installs\mysql-5.5-11
|
24
|
+
|
25
|
+
== Usage
|
26
|
+
|
27
|
+
Connect to a database:
|
28
|
+
|
29
|
+
# this takes a hash of options, almost all of which map directly
|
30
|
+
# to the familiar database.yml in rails
|
31
|
+
# See http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/MysqlAdapter.html
|
32
|
+
client = Mysql2::Client.new(:host => "localhost", :username => "root")
|
33
|
+
|
34
|
+
Then query it:
|
35
|
+
|
36
|
+
results = client.query("SELECT * FROM users WHERE group='githubbers'")
|
37
|
+
|
38
|
+
Need to escape something first?
|
39
|
+
|
40
|
+
escaped = client.escape("gi'thu\"bbe\0r's")
|
41
|
+
results = client.query("SELECT * FROM users WHERE group='#{escaped}'")
|
42
|
+
|
43
|
+
Finally, iterate over the results:
|
44
|
+
|
45
|
+
results.each do |row|
|
46
|
+
# conveniently, row is a hash
|
47
|
+
# the keys are the fields, as you'd expect
|
48
|
+
# the values are pre-built ruby primitives mapped from their corresponding field types in MySQL
|
49
|
+
# Here's an otter: http://farm1.static.flickr.com/130/398077070_b8795d0ef3_b.jpg
|
50
|
+
end
|
51
|
+
|
52
|
+
Or, you might just keep it simple:
|
53
|
+
|
54
|
+
client.query("SELECT * FROM users WHERE group='githubbers'").each do |row|
|
55
|
+
# do something with row, it's ready to rock
|
56
|
+
end
|
57
|
+
|
58
|
+
How about with symbolized keys?
|
59
|
+
|
60
|
+
# NOTE: the :symbolize_keys and future options will likely move to the #query method soon
|
61
|
+
client.query("SELECT * FROM users WHERE group='githubbers'").each(:symbolize_keys => true) do |row|
|
62
|
+
# do something with row, it's ready to rock
|
63
|
+
end
|
64
|
+
|
65
|
+
You can get the headers and the columns in the order that they were returned
|
66
|
+
by the query like this:
|
67
|
+
|
68
|
+
headers = results.fields # <= that's an array of field names, in order
|
69
|
+
results.each(:as => :array) do |row|
|
70
|
+
# Each row is an array, ordered the same as the query results
|
71
|
+
# An otter's den is called a "holt" or "couch"
|
72
|
+
end
|
73
|
+
|
74
|
+
== Cascading config
|
75
|
+
|
76
|
+
The default config hash is at:
|
77
|
+
|
78
|
+
Mysql2::Client.default_query_options
|
79
|
+
|
80
|
+
which defaults to:
|
81
|
+
|
82
|
+
{:async => false, :as => :hash, :symbolize_keys => false}
|
83
|
+
|
84
|
+
that can be used as so:
|
85
|
+
|
86
|
+
# these are the defaults all Mysql2::Client instances inherit
|
87
|
+
Mysql2::Client.default_query_options.merge!(:as => :array)
|
88
|
+
|
89
|
+
or
|
90
|
+
|
91
|
+
# this will change the defaults for all future results returned by the #query method _for this connection only_
|
92
|
+
c = Mysql2::Client.new
|
93
|
+
c.query_options.merge!(:symbolize_keys => true)
|
94
|
+
|
95
|
+
or
|
96
|
+
|
97
|
+
# this will set the options for the Mysql2::Result instance returned from the #query method
|
98
|
+
c = Mysql2::Client.new
|
99
|
+
c.query(sql, :symbolize_keys => true)
|
100
|
+
|
101
|
+
== Result types
|
102
|
+
|
103
|
+
=== Array of Arrays
|
104
|
+
|
105
|
+
Pass the :as => :array option to any of the above methods of configuration
|
106
|
+
|
107
|
+
=== Array of Hashes
|
108
|
+
|
109
|
+
The default result type is set to :hash, but you can override a previous setting to something else with :as => :hash
|
110
|
+
|
111
|
+
=== Others...
|
112
|
+
|
113
|
+
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.
|
114
|
+
If you'd like to see either of these (or others), open an issue and start bugging me about it ;)
|
115
|
+
|
116
|
+
=== Timezones
|
117
|
+
|
118
|
+
Mysql2 now supports two timezone options:
|
119
|
+
|
120
|
+
: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
|
121
|
+
:application_timezone - this is the timezone Mysql2 will convert to before finally handing back to the caller
|
122
|
+
|
123
|
+
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.
|
124
|
+
Then, if :application_timezone is set to say - :local - Mysql2 will then convert the just-created UTC Time object to local time.
|
125
|
+
|
126
|
+
Both options only allow two values - :local or :utc - with the exception that :application_timezone can be [and defaults to] nil
|
127
|
+
|
128
|
+
=== Casting "boolean" columns
|
129
|
+
|
130
|
+
You can now tell Mysql2 to cast tinyint(1) fields to boolean values in Ruby with the :cast_booleans option.
|
131
|
+
|
132
|
+
client = Mysql2::Client.new
|
133
|
+
result = client.query("SELECT * FROM table_with_boolean_field", :cast_booleans => true)
|
134
|
+
|
135
|
+
=== Async
|
136
|
+
|
137
|
+
Mysql2::Client takes advantage of the MySQL C API's (undocumented) non-blocking function mysql_send_query for *all* queries.
|
138
|
+
But, in order to take full advantage of it in your Ruby code, you can do:
|
139
|
+
|
140
|
+
client.query("SELECT sleep(5)", :async => true)
|
141
|
+
|
142
|
+
Which will return nil immediately. At this point you'll probably want to use some socket monitoring mechanism
|
143
|
+
like EventMachine or even IO.select. Once the socket becomes readable, you can do:
|
144
|
+
|
145
|
+
# result will be a Mysql2::Result instance
|
146
|
+
result = client.async_result
|
147
|
+
|
148
|
+
NOTE: Because of the way MySQL's query API works, this method will block until the result is ready.
|
149
|
+
So if you really need things to stay async, it's best to just monitor the socket with something like EventMachine.
|
150
|
+
If you need multiple query concurrency take a look at using a connection pool.
|
151
|
+
|
152
|
+
=== Row Caching
|
153
|
+
|
154
|
+
By default, Mysql2 will cache rows that have been created in Ruby (since this happens lazily).
|
155
|
+
This is especially helpful since it saves the cost of creating the row in Ruby if you were to iterate over the collection again.
|
156
|
+
|
157
|
+
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.
|
158
|
+
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.
|
159
|
+
|
160
|
+
== ActiveRecord
|
161
|
+
|
162
|
+
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".
|
163
|
+
That was easy right? :)
|
164
|
+
|
165
|
+
== Asynchronous ActiveRecord
|
166
|
+
|
167
|
+
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
|
168
|
+
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.
|
169
|
+
|
170
|
+
== Sequel
|
171
|
+
|
172
|
+
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.
|
173
|
+
|
174
|
+
== EventMachine
|
175
|
+
|
176
|
+
The mysql2 EventMachine deferrable api allows you to make async queries using EventMachine,
|
177
|
+
while specifying callbacks for success for failure. Here's a simple example:
|
178
|
+
|
179
|
+
require 'mysql2/em'
|
180
|
+
|
181
|
+
EM.run do
|
182
|
+
client1 = Mysql2::EM::Client.new
|
183
|
+
defer1 = client1.query "SELECT sleep(3) as first_query"
|
184
|
+
defer1.callback do |result|
|
185
|
+
puts "Result: #{result.to_a.inspect}"
|
186
|
+
end
|
187
|
+
|
188
|
+
client2 = Mysql2::EM::Client.new
|
189
|
+
defer2 = client2.query "SELECT sleep(1) second_query"
|
190
|
+
defer2.callback do |result|
|
191
|
+
puts "Result: #{result.to_a.inspect}"
|
192
|
+
end
|
193
|
+
end
|
194
|
+
|
195
|
+
== Lazy Everything
|
196
|
+
|
197
|
+
Well... almost ;)
|
198
|
+
|
199
|
+
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.
|
200
|
+
|
201
|
+
Rows themselves are lazily created in ruby-land when an attempt to yield it is made via #each.
|
202
|
+
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).
|
203
|
+
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.
|
204
|
+
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.
|
205
|
+
|
206
|
+
This caching behavior can be disabled by setting the :cache_rows option to false.
|
207
|
+
|
208
|
+
As for field values themselves, I'm workin on it - but expect that soon.
|
209
|
+
|
210
|
+
== Compatibility
|
211
|
+
|
212
|
+
The specs pass on my system (SL 10.6.3, x86_64) in these rubies:
|
213
|
+
|
214
|
+
* 1.8.7-p249
|
215
|
+
* ree-1.8.7-2010.01
|
216
|
+
* 1.9.1-p378
|
217
|
+
* ruby-trunk
|
218
|
+
* rbx-head - broken at the moment, working with the rbx team for a solution
|
219
|
+
|
220
|
+
The ActiveRecord driver should work on 2.3.5 and 3.0
|
221
|
+
|
222
|
+
== Yeah... but why?
|
223
|
+
|
224
|
+
Someone: Dude, the Mysql gem works fiiiiiine.
|
225
|
+
|
226
|
+
Me: It sure does, but it only hands you nil and strings for field values. Leaving you to convert
|
227
|
+
them into proper Ruby types in Ruby-land - which is slow as balls.
|
228
|
+
|
229
|
+
|
230
|
+
Someone: OK fine, but do_mysql can already give me back values with Ruby objects mapped to MySQL types.
|
231
|
+
|
232
|
+
Me: Yep, but it's API is considerably more complex *and* can be ~2x slower.
|
233
|
+
|
234
|
+
== Benchmarks
|
235
|
+
|
236
|
+
Performing a basic "SELECT * FROM" query on a table with 30k rows and fields of nearly every Ruby-representable data type,
|
237
|
+
then iterating over every row using an #each like method yielding a block:
|
238
|
+
|
239
|
+
# These results are from the query_with_mysql_casting.rb script in the benchmarks folder
|
240
|
+
user system total real
|
241
|
+
Mysql2
|
242
|
+
0.750000 0.180000 0.930000 ( 1.821655)
|
243
|
+
do_mysql
|
244
|
+
1.650000 0.200000 1.850000 ( 2.811357)
|
245
|
+
Mysql
|
246
|
+
7.500000 0.210000 7.710000 ( 8.065871)
|
247
|
+
|
248
|
+
== Development
|
249
|
+
|
250
|
+
To run the tests, you can use RVM and Bundler to create a pristine environment for mysql2 development/hacking.
|
251
|
+
Use 'bundle install' to install the necessary development and testing gems:
|
252
|
+
|
253
|
+
bundle install
|
254
|
+
rake
|
255
|
+
|
256
|
+
== Special Thanks
|
257
|
+
|
258
|
+
* Eric Wong - for the contribution (and the informative explanations) of some thread-safety, non-blocking I/O and cleanup patches. You rock dude
|
259
|
+
* Yury Korolev (http://github.com/yury) - for TONS of help testing the ActiveRecord adapter
|
260
|
+
* Aaron Patterson (http://github.com/tenderlove) - tons of contributions, suggestions and general badassness
|
261
|
+
* Mike Perham (http://github.com/mperham) - Async ActiveRecord adapter (uses Fibers and EventMachine)
|