initial readme

This commit is contained in:
Brian Lopez 2010-04-04 22:42:00 -07:00
parent aa574a0a92
commit 9b3f862f8b

View File

@ -1,2 +1,80 @@
= Mysql2 - A simple, fast Mysql library for Ruby, binding to libmysql = Mysql2 - A simple, 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.
That's it.
== Usage
Connect to a database:
# this takes a hash of options, almost all of which map directly
# to the familiar database.yml in rails
# NOTE: ssl option support coming really soon
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
== Cool, but why?
Someone: But 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 representable data type,
then iterating over every row using an #each like method yielding a block:
user system total real
Mysql
1.050000 0.090000 1.140000 ( 1.441405)
do_mysql
11.440000 0.260000 11.700000 ( 11.951023)
Mysql2
3.660000 0.170000 3.830000 ( 4.082238)