= RDBI - Low-level Database Access Re-imagined RDBI is intended primarily as an alternative to the heavier database layers in the Ruby ecosystem. It provides a consistent interface to databases for working with query languages directly, instead of providing an extremely high level interface which does this work for you. While usable, it largely targets high-level database libraries, similar to how +rack+ targets web frameworks. == I'd like to get started If you'd prefer to head straight to sinking your teeth into the API, here's a path down the rabbit hole: * RDBI is what you'll use to get your RDBI::Database handle. If you need collections of database handles, look at RDBI::Pool. * RDBI::Database contains methods for dealing with database level operations and preparing and executing RDBI::Statement objects. * RDBI::Statement works with RDBI::Cursor to yield RDBI::Result objects, which leverage RDBI::Result::Driver classes to yield data. * If you're interested in how schemas and types are dealt with, see RDBI::Schema, RDBI::Column, and RDBI::Type. == Need a Driver? === Databases: ==== Maintained by the RDBI project: * rdbi-driver-mysql: http://github.com/RDBI/rdbi-driver-mysql * rdbi-driver-postgresql: http://github.com/RDBI/rdbi-driver-postgresql * rdbi-driver-sqlite3: http://github.com/RDBI/rdbi-driver-sqlite3 ==== Maintained by third parties: * rdbi-driver-odbc: https://github.com/semmons99/rdbi-driver-odbc by Shane Emmons === Results: * rdbi-result-driver-json: http://github.com/RDBI/rdbi-result-driver-json == Give me a code sample already! # connect to an in-memory sqlite3 database: dbh = RDBI.connect(:SQLite3, :database => ":memory:") # execute this CREATE TABLE statement: dbh.execute("create table tbl (string varchar(32), number integer)") # prepare an insert statement for execution with two placeholders: dbh.prepare("insert into tbl (string, number) values (?, ?)") do |sth| # and execute it three times with bound variables: sth.execute("foo", -37) sth.execute("bar", 127) sth.execute("quux", 1024) end # get a result handle from a select statement: result = dbh.execute("select * from tbl") # and fetch the first row result.fetch(:first) # ["foo", -37] == What +is+ RDBI all about, anyway? Here are some important pieces of information about RDBI that you may find compelling (or off-putting. We're pragmatists.): * RDBI is, at the time of this writing, fewer than 1000 lines of code. * RDBI is light and fast. Eventually we will show you benchmarks. * RDBI can be tested without a database, or even a database driver. * RDBI can transform your results through a driver system. Want a CSV? Use the CSV driver, don't bother transforming it yourself. Transform to JSON or YAML with another gem. Drivers can be independently installed, used and swapped. * RDBI contains no monkeypatching, core extensions, or other hell that will conflict with your other libraries. * RDBI is designed around properties of a relational database, but there is nothing in it that demands one -- use it with Mongo or Redis if you want. * RDBI database drivers are *small* -- our sqlite driver is about 150 lines and our PostgreSQL driver is about 300. Our mock driver is about 50. * RDBI has an active community of experienced Rails and Ruby programmers. == I'd like some more, please. # result objects are very flexible and amenable to method chaining: dbh.execute("select * from foo").fetch(2) # [[1, "foo"], [2, "bar"]] result = dbh.execute("select * from foo") # select iteratively, then rewind to the first item: result.fetch(2) result.rewind # change the way the results are presented: result.as(:CSV).fetch(2) # '1,"foo"\n2,"bar"\n' # :CSV is shorthand for RDBI::Result::Driver::CSV. you can also use literal # class names: result.as(RDBI::Result::Driver::CSV) # or maybe your own: result.as(MyCoolDriver) # Here's another included driver: str = result.as(:Struct).fetch(:first) str.bar # 1 str.baz # "foo" result.rewind # select a single item in CSV format csv = result.fetch(:first, :CSV) # get the whole thing as an array of structs, keyed by column ary_of_struct = result.as(:Struct).fetch(:all) # as() automagically rewinds for you, so select twice for multi-dimension # presentations: ary = result.as(:Array).fetch(:all) # and we're done! Disconnect from the database. dbh.disconnect Here are some things that it does: * Connection pooling with aggregate transforms of your connections (that's a fancy way of saying it uses Enumerable in the Pools). It can be responsible for n segmented pools which relate to different logical databases. * Native client binding *and* interpolated binding for databases that do not support it. * Don't like our drivers? No one's requiring you to use them -- RDBI drivers aren't coupled with RDBI in any way. * Result *drivers* can be used to transform your output into whatever you need -- never write a transformation skeleton again. * Result *handles* can be used to work with results like real data structures. Rewind them, ask the database to re-query the data, select a struct then select an array (*without* requerying), select n items at a time as tuples (which may be more than one or less than all). * Cursors are used underneath the hood to ensure as performant a situation as your database (and underlying driver) can provide. * RDBI's core test suite passes in MRI 1.8, 1.9, and JRuby 1.5. Aaaaaand here are some things RDBI won't do: * RDBI won't write your queries for you. (There are libraries that use RDBI for that.) * RDBI won't dictate your schema. * RDBI won't prevent you from being stupid or clever. * It won't save you tons of time because you can't be bothered to think about how you access your data. * It won't make you (or anyone, really) a rockstar. * Do not taunt RDBI. == Show me even more awesome! # retrieve cached handles 5 times -- handles will be yielded twice if there # is a smaller Pool size: 5.times do RDBI.connect_cached(:SQLite3, :database => ":memory:") end # omg! this handle is really already connected! dbh = RDBI.connect_cached(:SQLite3, :database => ":memory:") # finer-grained control via RDBI::Pool: # 2 connections: pool = RDBI::Pool.new("my_pool_name", [:SQLite3, :database => ":memory:"], 2) # zomg! dbh = pool.get_dbh # oh lordy lord! still 2 connections 10.times { pool.get_dbh } pool.disconnect # disconnect the entire pool pool.reconnect # reconnect the entire pool pool.resize(10) # resize the pool to 10 connections. == Who is responsible for this madness? * Erik Hollensbe (erikh) * Pistos (... Pistos) * Lee Jarvis (injekt) * James Tucker (raggi) == I found a bug! We use the trackers in the github +RDBI+ project: http://github.com/RDBI for each gem. Please find the appropriate place to add your ticket. Not sure? Just add it to the +rdbi+ tracker: http://github.com/RDBI/rdbi/issues == I'd like to patch and/or help maintain RDBI. How can I? * Fork the project: http://github.com/RDBI * Make your feature addition or bug fix. * Please add tests for it, or indicate there are none. Patches without tests will get integrated slower and must be very compelling. * We use +jeweler+ for our repository management -- patches that mess with this will be rejected regardless of merit. * If you fork it permanently, be prepared to support it; we won't. == Let's chat * \#ruby-dbi on irc.freenode.net * rdbi-devel@groups.google.com - for developers == Copyright Copyright (c) 2010 Erik Hollensbe. See LICENSE for details.