93 lines
3.2 KiB
Plaintext
93 lines
3.2 KiB
Plaintext
= 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] 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
|
|
|
|
I plan to release the initial gem version within the next day or so. Just wanted to tweak extconf to help find the libmysql binary easier, and add the ssl options.
|
|
|
|
== 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
|
|
|
|
== 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
|
|
|
|
== 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* is 3x slower.
|
|
|
|
== Benchmarks
|
|
|
|
Performing a basic "SELECT * FROM" query on a table with ~31k rows and fields of nearly every Ruby-representable data type,
|
|
then iterating over every row using an #each like method yielding a block:
|
|
|
|
# The Mysql gem appears faster because it only gives back nil and strings.
|
|
user system total real
|
|
Mysql
|
|
1.050000 0.090000 1.140000 ( 1.441405)
|
|
Mysql2
|
|
3.660000 0.170000 3.830000 ( 4.082238)
|
|
do_mysql
|
|
11.440000 0.260000 11.700000 ( 11.951023) |