mysql2/README.rdoc

93 lines
3.1 KiB
Plaintext
Raw Normal View History

2010-04-05 05:58:47 +00:00
= Mysql2 - A modern, simple and very fast Mysql library for Ruby, binding to libmysql
2010-04-04 20:14:58 +00:00
2010-04-05 05:42:00 +00:00
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.
2010-04-05 21:15:30 +00:00
== 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.
2010-04-05 05:42:00 +00:00
== 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
2010-04-05 05:42:00 +00:00
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
2010-04-06 02:17:32 +00:00
== 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
2010-04-05 07:01:17 +00:00
== Yeah... but why?
2010-04-05 05:42:00 +00:00
2010-04-05 07:01:17 +00:00
Someone: Dude, the Mysql gem works fiiiiiine.
2010-04-05 05:42:00 +00:00
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 2-3x slower.
2010-04-05 05:42:00 +00:00
== Benchmarks
Performing a basic "SELECT * FROM" query on a table with 30k rows and fields of nearly every Ruby-representable data type,
2010-04-05 05:42:00 +00:00
then iterating over every row using an #each like method yielding a block:
# And remember, the Mysql gem only gives back nil and strings.
user system total real
2010-04-05 05:42:00 +00:00
Mysql2
2.080000 0.790000 2.870000 ( 3.418861)
Mysql
1.210000 0.790000 2.000000 ( 4.527824)
do_mysql
5.450000 0.980000 6.430000 ( 7.001563)