mysql2 0.2.6-x86-mingw32 → 0.2.16-x86-mingw32

Sign up to get free protection for your applications and to get access to all the features.
data/.rspec CHANGED
@@ -1,2 +1,3 @@
1
1
  --format documentation
2
2
  --colour
3
+ --fail-fast
data/.rvmrc ADDED
@@ -0,0 +1 @@
1
+ rvm use 1.9.3@mysql2 --create
@@ -1,5 +1,64 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.14 (November 9th, 2011)
4
+ * use rb_wait_for_single_fd() if available
5
+ * fixed a bug with inheriting query options
6
+ * remove ext/ from the default loadpath
7
+ * fix build issues on OSX with Xcode 4.2 (gcc-llvm compiler)
8
+
9
+ ## 0.2.13 (August 16th, 2011)
10
+ * fix stupid bug around symbol encoding support (thanks coderrr!)
11
+
12
+ ## 0.2.12 (August 16th, 2011)
13
+ * ensure symbolized column names support encodings in 1.9
14
+ * plugging sql vulnerability in mysql2 adapter
15
+
16
+ ## 0.2.11 (June 17th, 2011)
17
+ * fix bug in Time/DateTime range detection
18
+ * (win32) fix bug where the Mysql2::Client object wasn't cleaned up properly if interrupted during a query
19
+ * add Mysql2::Result#count (aliased as size) to get the row count for the dataset
20
+ this can be especially helpful if you want to get the number of rows without having to inflate
21
+ the entire dataset into ruby (since this happens lazily)
22
+
23
+ ## 0.2.10 (June 15th, 2011)
24
+ * bug fix for Time/DateTime usage depending on 32/64bit Ruby
25
+
26
+ ## 0.2.9 (June 15th, 2011)
27
+ * fix a long standing bug where a signal would interrupt rb_thread_select and put the connection in a permanently broken state
28
+ * turn on casting in the ActiveRecord again, users can disable it if they need to for performance reasons
29
+
30
+ ## 0.2.8 (June 14th, 2011)
31
+ * 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.
32
+ * added support for turning eager-casting off. This is especially useful in ORMs that will lazily cast values upon access.
33
+ * 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
34
+ * added Mysql2::Client.escape (class-level method)
35
+ * disabled eager-casting in the bundled ActiveRecord adapter (for Rails 3.0 or less)
36
+
37
+ ## 0.2.7 (March 28th, 2011)
38
+ * various fixes for em_mysql2 and fiber usage
39
+ * use our own Mysql2IndexDefinition class for better compatibility across ActiveRecord versions
40
+ * ensure the query is a string earlier in the Mysql2::Client#query codepath for 1.9
41
+ * only set binary ruby encoding on fields that have a binary flag *and* encoding set
42
+ * a few various optimizations
43
+ * add support for :read_timeout to be set on a connection
44
+ * Fix to install with MariDB on Windows
45
+ * add fibered em connection without activerecord
46
+ * fix some 1.9.3 compilation warnings
47
+ * add LD_RUN_PATH when using hard coded mysql paths - this should help users with MySQL installed in non-standard locations
48
+ * for windows support, duplicate the socket from libmysql and create a temporary CRT fd
49
+ * fix for handling years before 1970 on Windows
50
+ * fixes to the Fiber adapter
51
+ * set wait_timeout maximum on Windows to 2147483
52
+ * update supported range for Time objects
53
+ * upon being required, make sure the libmysql we're using is the one we were built against
54
+ * add Mysql2::Client#thread_id
55
+ * add Mysql2::Client#ping
56
+ * switch connection check in AR adapter to use Mysql2::Client#ping for efficiency
57
+ * prefer linking against thread-safe version of libmysqlclient
58
+ * define RSTRING_NOT_MODIFIED for an awesome rbx speed boost
59
+ * expose Mysql2::Client#encoding in 1.9, make sure we set the error message and sqlstate encodings accordingly
60
+ * do not segfault when raising for invalid charset (found in 1.9.3dev)
61
+
3
62
  ## 0.2.6 (October 19th, 2010)
4
63
  * version bump since the 0.2.5 win32 binary gems were broken
5
64
 
@@ -114,4 +173,4 @@
114
173
  * updated extconf (thanks to the mysqlplus project) for easier gem building
115
174
 
116
175
  ## 0.1.0 (April 6th, 2010)
117
- * initial release
176
+ * initial release
data/Gemfile ADDED
@@ -0,0 +1,3 @@
1
+ source :rubygems
2
+
3
+ gemspec
@@ -1,4 +1,4 @@
1
- Copyright (c) 2010 Brian Lopez - http://github.com/brianmario
1
+ Copyright (c) 2010-2011 Brian Lopez - http://github.com/brianmario
2
2
 
3
3
  Permission is hereby granted, free of charge, to any person obtaining
4
4
  a copy of this software and associated documentation files (the
@@ -0,0 +1,326 @@
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
+ ``` sh
18
+ gem install mysql2
19
+ ```
20
+
21
+ You may have to specify --with-mysql-config=/some/random/path/bin/mysql_config
22
+
23
+ ## Usage
24
+
25
+ Connect to a database:
26
+
27
+ ``` ruby
28
+ # this takes a hash of options, almost all of which map directly
29
+ # to the familiar database.yml in rails
30
+ # See http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/MysqlAdapter.html
31
+ client = Mysql2::Client.new(:host => "localhost", :username => "root")
32
+ ```
33
+
34
+ Then query it:
35
+
36
+ ``` ruby
37
+ results = client.query("SELECT * FROM users WHERE group='githubbers'")
38
+ ```
39
+
40
+ Need to escape something first?
41
+
42
+ ``` ruby
43
+ escaped = client.escape("gi'thu\"bbe\0r's")
44
+ results = client.query("SELECT * FROM users WHERE group='#{escaped}'")
45
+ ```
46
+
47
+ You can get a count of your results with `results.count`.
48
+
49
+ Finally, iterate over the results:
50
+
51
+ ``` ruby
52
+ results.each do |row|
53
+ # conveniently, row is a hash
54
+ # the keys are the fields, as you'd expect
55
+ # the values are pre-built ruby primitives mapped from their corresponding field types in MySQL
56
+ # Here's an otter: http://farm1.static.flickr.com/130/398077070_b8795d0ef3_b.jpg
57
+ end
58
+ ```
59
+
60
+ Or, you might just keep it simple:
61
+
62
+ ``` ruby
63
+ client.query("SELECT * FROM users WHERE group='githubbers'").each do |row|
64
+ # do something with row, it's ready to rock
65
+ end
66
+ ```
67
+
68
+ How about with symbolized keys?
69
+
70
+ ``` ruby
71
+ # NOTE: the :symbolize_keys and future options will likely move to the #query method soon
72
+ client.query("SELECT * FROM users WHERE group='githubbers'").each(:symbolize_keys => true) do |row|
73
+ # do something with row, it's ready to rock
74
+ end
75
+ ```
76
+
77
+ You can get the headers and the columns in the order that they were returned
78
+ by the query like this:
79
+
80
+ ``` ruby
81
+ headers = results.fields # <= that's an array of field names, in order
82
+ results.each(:as => :array) do |row|
83
+ # Each row is an array, ordered the same as the query results
84
+ # An otter's den is called a "holt" or "couch"
85
+ end
86
+ ```
87
+
88
+ ## Cascading config
89
+
90
+ The default config hash is at:
91
+
92
+ ``` ruby
93
+ Mysql2::Client.default_query_options
94
+ ```
95
+
96
+ which defaults to:
97
+
98
+ ``` ruby
99
+ {:async => false, :as => :hash, :symbolize_keys => false}
100
+ ```
101
+
102
+ that can be used as so:
103
+
104
+ ``` ruby
105
+ # these are the defaults all Mysql2::Client instances inherit
106
+ Mysql2::Client.default_query_options.merge!(:as => :array)
107
+ ```
108
+
109
+ or
110
+
111
+ ``` ruby
112
+ # this will change the defaults for all future results returned by the #query method _for this connection only_
113
+ c = Mysql2::Client.new
114
+ c.query_options.merge!(:symbolize_keys => true)
115
+ ```
116
+
117
+ or
118
+
119
+ ``` ruby
120
+ # this will set the options for the Mysql2::Result instance returned from the #query method
121
+ c = Mysql2::Client.new
122
+ c.query(sql, :symbolize_keys => true)
123
+ ```
124
+
125
+ ## Result types
126
+
127
+ ### Array of Arrays
128
+
129
+ Pass the `:as => :array` option to any of the above methods of configuration
130
+
131
+ ### Array of Hashes
132
+
133
+ The default result type is set to :hash, but you can override a previous setting to something else with :as => :hash
134
+
135
+ ### Others...
136
+
137
+ 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.
138
+ If you'd like to see either of these (or others), open an issue and start bugging me about it ;)
139
+
140
+ ### Timezones
141
+
142
+ Mysql2 now supports two timezone options:
143
+
144
+ ``` ruby
145
+ :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
146
+ :application_timezone # this is the timezone Mysql2 will convert to before finally handing back to the caller
147
+ ```
148
+
149
+ 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.
150
+ Then, if `:application_timezone` is set to say - `:local` - Mysql2 will then convert the just-created UTC Time object to local time.
151
+
152
+ Both options only allow two values - `:local` or `:utc` - with the exception that `:application_timezone` can be [and defaults to] nil
153
+
154
+ ### Casting "boolean" columns
155
+
156
+ You can now tell Mysql2 to cast `tinyint(1)` fields to boolean values in Ruby with the `:cast_booleans` option.
157
+
158
+ ``` ruby
159
+ client = Mysql2::Client.new
160
+ result = client.query("SELECT * FROM table_with_boolean_field", :cast_booleans => true)
161
+ ```
162
+
163
+ ### Skipping casting
164
+
165
+ 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.
166
+
167
+ ``` ruby
168
+ client = Mysql2::Client.new
169
+ result = client.query("SELECT * FROM table", :cast => false)
170
+ ```
171
+
172
+ Here are the results from the `query_without_mysql_casting.rb` script in the benchmarks folder:
173
+
174
+ ``` sh
175
+ user system total real
176
+ Mysql2 (cast: true) 0.340000 0.000000 0.340000 ( 0.405018)
177
+ Mysql2 (cast: false) 0.160000 0.010000 0.170000 ( 0.209937)
178
+ Mysql 0.080000 0.000000 0.080000 ( 0.129355)
179
+ do_mysql 0.520000 0.010000 0.530000 ( 0.574619)
180
+ ```
181
+
182
+ 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.
183
+
184
+ ### Async
185
+
186
+ NOTE: Not supported on Windows.
187
+
188
+ `Mysql2::Client` takes advantage of the MySQL C API's (undocumented) non-blocking function mysql_send_query for *all* queries.
189
+ But, in order to take full advantage of it in your Ruby code, you can do:
190
+
191
+ ``` ruby
192
+ client.query("SELECT sleep(5)", :async => true)
193
+ ```
194
+
195
+ Which will return nil immediately. At this point you'll probably want to use some socket monitoring mechanism
196
+ like EventMachine or even IO.select. Once the socket becomes readable, you can do:
197
+
198
+ ``` ruby
199
+ # result will be a Mysql2::Result instance
200
+ result = client.async_result
201
+ ```
202
+
203
+ NOTE: Because of the way MySQL's query API works, this method will block until the result is ready.
204
+ So if you really need things to stay async, it's best to just monitor the socket with something like EventMachine.
205
+ If you need multiple query concurrency take a look at using a connection pool.
206
+
207
+ ### Row Caching
208
+
209
+ By default, Mysql2 will cache rows that have been created in Ruby (since this happens lazily).
210
+ This is especially helpful since it saves the cost of creating the row in Ruby if you were to iterate over the collection again.
211
+
212
+ 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.
213
+ 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.
214
+
215
+ ## ActiveRecord
216
+
217
+ 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".
218
+ That was easy right? :)
219
+
220
+ 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
221
+ Rails versions < 3.1 make sure and specify `gem "mysql2", "~> 0.2.7"` in your Gemfile
222
+
223
+ ## Asynchronous ActiveRecord
224
+
225
+ 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
226
+ 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.
227
+
228
+ ## Sequel
229
+
230
+ 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.
231
+
232
+ ## EventMachine
233
+
234
+ The mysql2 EventMachine deferrable api allows you to make async queries using EventMachine,
235
+ while specifying callbacks for success for failure. Here's a simple example:
236
+
237
+ ``` ruby
238
+ require 'mysql2/em'
239
+
240
+ EM.run do
241
+ client1 = Mysql2::EM::Client.new
242
+ defer1 = client1.query "SELECT sleep(3) as first_query"
243
+ defer1.callback do |result|
244
+ puts "Result: #{result.to_a.inspect}"
245
+ end
246
+
247
+ client2 = Mysql2::EM::Client.new
248
+ defer2 = client2.query "SELECT sleep(1) second_query"
249
+ defer2.callback do |result|
250
+ puts "Result: #{result.to_a.inspect}"
251
+ end
252
+ end
253
+ ```
254
+
255
+ ## Lazy Everything
256
+
257
+ Well... almost ;)
258
+
259
+ 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.
260
+
261
+ Rows themselves are lazily created in ruby-land when an attempt to yield it is made via #each.
262
+ 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).
263
+ 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.
264
+ 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.
265
+
266
+ This caching behavior can be disabled by setting the :cache_rows option to false.
267
+
268
+ As for field values themselves, I'm workin on it - but expect that soon.
269
+
270
+ ## Compatibility
271
+
272
+ The specs pass on my system (SL 10.6.3, x86_64) in these rubies:
273
+
274
+ * 1.8.7-p249
275
+ * ree-1.8.7-2010.01
276
+ * 1.9.1-p378
277
+ * ruby-trunk
278
+ * rbx-head - broken at the moment, working with the rbx team for a solution
279
+
280
+ The ActiveRecord driver should work on 2.3.5 and 3.0
281
+
282
+ ## Yeah... but why?
283
+
284
+ Someone: Dude, the Mysql gem works fiiiiiine.
285
+
286
+ Me: It sure does, but it only hands you nil and strings for field values. Leaving you to convert
287
+ them into proper Ruby types in Ruby-land - which is slow as balls.
288
+
289
+
290
+ Someone: OK fine, but do_mysql can already give me back values with Ruby objects mapped to MySQL types.
291
+
292
+ Me: Yep, but it's API is considerably more complex *and* can be ~2x slower.
293
+
294
+ ## Benchmarks
295
+
296
+ Performing a basic "SELECT * FROM" query on a table with 30k rows and fields of nearly every Ruby-representable data type,
297
+ then iterating over every row using an #each like method yielding a block:
298
+
299
+ These results are from the `query_with_mysql_casting.rb` script in the benchmarks folder
300
+
301
+ ``` sh
302
+ user system total real
303
+ Mysql2
304
+ 0.750000 0.180000 0.930000 ( 1.821655)
305
+ do_mysql
306
+ 1.650000 0.200000 1.850000 ( 2.811357)
307
+ Mysql
308
+ 7.500000 0.210000 7.710000 ( 8.065871)
309
+ ```
310
+
311
+ ## Development
312
+
313
+ To run the tests, you can use RVM and Bundler to create a pristine environment for mysql2 development/hacking.
314
+ Use 'bundle install' to install the necessary development and testing gems:
315
+
316
+ ``` sh
317
+ bundle install
318
+ rake
319
+ ```
320
+
321
+ ## Special Thanks
322
+
323
+ * Eric Wong - for the contribution (and the informative explanations) of some thread-safety, non-blocking I/O and cleanup patches. You rock dude
324
+ * Yury Korolev (http://github.com/yury) - for TONS of help testing the ActiveRecord adapter
325
+ * Aaron Patterson (http://github.com/tenderlove) - tons of contributions, suggestions and general badassness
326
+ * Mike Perham (http://github.com/mperham) - Async ActiveRecord adapter (uses Fibers and EventMachine)
@@ -27,9 +27,8 @@ class MysqlModel < ActiveRecord::Base
27
27
  end
28
28
 
29
29
  Benchmark.bmbm do |x|
30
- x.report do
30
+ x.report "Mysql2" do
31
31
  Mysql2Model.establish_connection(mysql2_opts)
32
- puts "Mysql2"
33
32
  number_of.times do
34
33
  Mysql2Model.all(:limit => 1000).each{ |r|
35
34
  r.attributes.keys.each{ |k|
@@ -39,9 +38,8 @@ Benchmark.bmbm do |x|
39
38
  end
40
39
  end
41
40
 
42
- x.report do
41
+ x.report "Mysql" do
43
42
  MysqlModel.establish_connection(mysql_opts)
44
- puts "Mysql"
45
43
  number_of.times do
46
44
  MysqlModel.all(:limit => 1000).each{ |r|
47
45
  r.attributes.keys.each{ |k|
@@ -0,0 +1,42 @@
1
+ # encoding: UTF-8
2
+ $LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + '/../lib')
3
+
4
+ require 'rubygems'
5
+ require 'benchmark'
6
+ require 'active_record'
7
+
8
+ times = 25
9
+
10
+
11
+ # mysql2
12
+ mysql2_opts = {
13
+ :adapter => 'mysql2',
14
+ :database => 'test',
15
+ :pool => times
16
+ }
17
+ ActiveRecord::Base.establish_connection(mysql2_opts)
18
+ x = Benchmark.realtime do
19
+ threads = []
20
+ times.times do
21
+ threads << Thread.new { ActiveRecord::Base.connection.execute("select sleep(1)") }
22
+ end
23
+ threads.each {|t| t.join }
24
+ end
25
+ puts "mysql2: #{x} seconds"
26
+
27
+
28
+ # mysql
29
+ mysql2_opts = {
30
+ :adapter => 'mysql',
31
+ :database => 'test',
32
+ :pool => times
33
+ }
34
+ ActiveRecord::Base.establish_connection(mysql2_opts)
35
+ x = Benchmark.realtime do
36
+ threads = []
37
+ times.times do
38
+ threads << Thread.new { ActiveRecord::Base.connection.execute("select sleep(1)") }
39
+ end
40
+ threads.each {|t| t.join }
41
+ end
42
+ puts "mysql: #{x} seconds"