initial readme

README.rdoc

@@ -1,2 +1,80 @@
 = 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)