rdbi 0.9.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,33 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+doc
+pkg
+.yardoc
+
+## PROJECT::SPECIFIC
+*.aux
+*.cp
+*.fn
+*.fns
+*.ky
+*.log
+*.pg
+*.toc
+*.tp
+*.vr

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Erik Hollensbe
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,194 @@
+= 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.
+
+== 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 foo (bar integer, baz varchar)")
+
+  # prepare an insert statement for execution with two placeholders:
+  dbh.prepare("insert into foo (bar, baz) values (?, ?)") do |sth|
+
+    # and execute it with bound variables:
+    sth.execute(1, "foo")
+    sth.execute(2, "bar")
+    sth.execute(3, "quux")
+  end
+
+  # get a result handle from a select statement:
+  result = dbh.execute("select * from foo")
+
+  # and fetch the first row
+  result.fetch(:first) # [1, "foo"]
+
+== 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 is almost 100% thread-safe.
+* 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.

data/Rakefile

@@ -0,0 +1,109 @@
+require 'rubygems'
+require 'rake'
+
+version = (File.exist?('VERSION') ? File.read('VERSION') : "").chomp
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "rdbi"
+    gem.summary = %Q{RDBI provides sane query-level database access with low magic.}
+    gem.description = %Q{RDBI is a rearchitecture of the Ruby/DBI project by its maintainer and others. It intends to fully supplant Ruby/DBI in the future for similar database access needs.}
+    gem.email = "erik@hollensbe.org"
+    gem.homepage = "http://github.com/RDBI/rdbi"
+    gem.authors = ["Erik Hollensbe"]
+
+    gem.add_development_dependency 'rdbi-driver-mock'
+    gem.add_development_dependency 'test-unit'
+    gem.add_development_dependency 'rdoc'
+    ## for now, install hanna from here: http://github.com/erikh/hanna
+    #gem.add_development_dependency 'hanna'
+    gem.add_development_dependency 'fastercsv'
+
+    gem.add_dependency 'methlab', '>= 0.0.9'
+    gem.add_dependency 'epoxy', '>= 0.3.1'
+    gem.add_dependency 'typelib'
+
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+begin
+  gem 'test-unit'
+  require 'rake/testtask'
+  Rake::TestTask.new(:test) do |test|
+    test.libs << 'lib' << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :test do
+    abort "test-unit gem is not available. In order to run test-unit, you must: sudo gem install test-unit"
+  end
+end
+
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+begin
+  require 'roodi'
+  require 'roodi_task'
+  RoodiTask.new do |t|
+    t.verbose = false
+  end
+rescue LoadError
+  task :roodi do
+    abort "Roodi is not available. In order to run roodi, you must: sudo gem install roodi"
+  end
+end
+
+task :default => :test
+
+begin
+  require 'hanna'
+  require 'rdoc/task'
+  RDoc::Task.new do |rdoc|
+    version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+    rdoc.options.push '-f', 'hanna'
+    rdoc.main = 'README.rdoc'
+    rdoc.rdoc_dir = 'rdoc'
+    rdoc.title = "RDBI #{version} Documentation"
+    rdoc.rdoc_files.include('README*')
+    rdoc.rdoc_files.include('lib/**/*.rb')
+  end
+rescue LoadError => e
+  rdoc_missing = lambda do
+    abort "What, were you born in a barn? Install rdoc and hanna at http://github.com/raggi/hanna ."
+  end
+  task :rdoc, &rdoc_missing
+  task :clobber_rdoc, &rdoc_missing
+end
+
+task :to_blog => [:clobber_rdoc, :rdoc] do
+  sh "rm -fr $git/blog/content/docs/rdbi && mv doc $git/blog/content/docs/rdbi"
+end
+
+task :install => [:test, :build]
+
+task :docview => [:rerdoc] do
+  sh "open rdoc/index.html"
+end
+
+# vim: syntax=ruby ts=2 et sw=2 sts=2

data/VERSION

@@ -0,0 +1 @@
+0.9.0

data/docs/external-api.texi

@@ -0,0 +1,365 @@
+\input texinfo
+@setfilename external-api.texi
+@settitle RDBI External API specification 1.0 draft
+
+@copying
+Copyright @copyright{} 2010 Erik Hollensbe. My dad can distribute this work
+better than your dad.
+@end copying
+
+@titlepage
+@title RDBI External API specification 1.0 draft
+@author Erik Hollensbe <erik@@hollensbe.org>
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+
+@end titlepage
+
+@contents
+@node Top
+
+
+
+@chapter All Classes
+
+
+
+@deftypemethod {All Classes} Boolean reload
+    this method will semantically refresh items, such as Schema objects or
+    rows, depending on the context of the object in question.
+@end deftypemethod
+
+
+
+@chapter module DBI
+
+
+
+@deftypemethod DBI DBH connect (Class @var{klass}, Array @var{*args}, Proc @var{&block})
+    class is a ruby class which corresponds to the database driver. it is no longer
+    a string.
+
+    *args is a hash with parameter -> value associations, such as :host or
+    :username.
+
+    Optionally yields a block for usage, yields a freshly connected DBH.
+@end deftypemethod
+
+@deftypemethod DBI {Array of Class} drivers
+    accessor to get at known classes that can be used as drivers.
+@end deftypemethod
+
+@deftypemethod DBI DBH connect_cached (Class @var{klass}, Array @var{*args}, Proc @var{&block})
+    connect to a new resource if one is required (or desired, see below) with
+    similar parameters as connect().
+
+    additional arguments :pool_name and :pool_size can be used to define a
+    Pool (object, see below) which holds a specific subset of connected
+    database handles. Playing with the size here introduces the ability for
+    connect_cached to maintain a minimum number of connections which can be
+    re-used over the lifetime of a program.
+@end deftypemethod
+
+@deftypemethod DBI Pool pool (String @var{pool_name})
+    a pool as described above is an array of database handles. this returns
+    that data as a "Pool" object, with its own API. See later on in the
+    document.
+@end deftypemethod
+
+@deftypemethod DBI Pool all_connections
+    similar to pool(), this returns all the connections, but ignores pools.
+@end deftypemethod
+
+@deftypemethod DBI Integer ping (Class @var{klass}, Array @var{*args})
+    similar to connect(), this issues a ping to the databases. This may issue
+    a connect() before the ping() to do it properly depending on the database
+    implementation.
+@end deftypemethod
+
+@deftypemethod DBI Boolean reconnect_all
+    reconnects all the known database handles.
+@end deftypemethod
+
+@deftypemethod DBI DBH last_dbh
+    returns the last returned dbh from connect() or connect_cached()
+
+    this method, by definition, can be unpredictable in threaded environments.
+@end deftypemethod
+
+
+
+@chapter class DBH
+
+
+
+@deftypemethod DBH NilClass transaction (Proc @var{&block})
+    opens a transaction and executes the statements in the block. Yields self.
+@end deftypemethod
+
+@deftypemethod DBH Schema table_schema (Symbol @var{table_name})
+    returns information about a specific table in a Schema object
+@end deftypemethod
+
+@deftypemethod DBH {Array of Schema} schema (Symbol @var{schema_name})
+    returns information about a specific schema, the current one if none is
+    specified.
+@end deftypemethod
+
+@deftypemethod DBH Boolean reconnect
+    reconnects to the database
+@end deftypemethod
+
+@deftypemethod DBH Integer ping
+    attempts to contact the database, measuring round-trip.
+@end deftypemethod
+
+@deftypemethod DBH Object driver
+    returns the underlying driver.
+@end deftypemethod
+
+@deftypemethod DBH String last_query
+    returns the last query executed or prepared.
+@end deftypemethod
+
+@deftypemethod DBH STH last_sth
+    returns the last statement handle prepared.
+@end deftypemethod
+
+@deftypemethod DBH Mutex mutex
+    returns the mutex for this database. thread management will be per-dbh.
+@end deftypemethod
+
+@deftypemethod DBH String preprocess_query (String @var{query})
+    preprocesses the query and returns what it would look like right before
+    it gets sent to the database.
+@end deftypemethod
+
+@deftypemethod DBH Boolean disconnect
+    disconnects from the database. returns success.
+@end deftypemethod
+
+@deftypemethod DBH Symbol bind_style ({Symbol of [native, preprocessed]} @var{style})
+    Accessor. Native style delegates to the underlying database connector. preprocessed
+    means we do it.
+@end deftypemethod
+
+
+
+@section Query Methods
+    these methods all optionally use a block and yield a result or sth depending
+    on context. Additionally in async environments, they return immediately,
+    the block being transformed into a callback which will yield when the query
+    completes.
+
+
+@deftypemethod DBH STH prepare (String @var{query})
+    prepares a query for execution and returns a statement handle.
+@end deftypemethod
+
+@deftypemethod DBH Result execute (String @var{query}, Array @var{*binds})
+    executes a query and returns a result. If a block is not provided, an async
+    result will be provided which will slowly result in items being fetchable.
+@end deftypemethod
+
+
+
+@chapter class STH 
+
+
+@deftypemethod STH String query
+    accessor for the query that was used to generate this sth.
+@end deftypemethod
+
+@deftypemethod STH Result execute (Array @var{*binds})
+    executes the prepared statement. optionally yielding a result if block given.
+@end deftypemethod
+
+@deftypemethod STH Object driver
+    if any, returns the underlying statement handle from the database object.
+@end deftypemethod
+
+@deftypemethod STH Result last_result
+    Returns the last Result this prepared statement has yielded.
+@end deftypemethod
+
+@deftypemethod STH Boolean finish
+    finishes the statement
+@end deftypemethod
+
+@deftypemethod STH DBH dbh
+    returns the dbh this statement handle was created from.
+@end deftypemethod
+
+
+
+@chapter class Pool
+
+
+
+@deftypemethod Pool Boolean reconnect
+    attempts to reconnect the entire pool of database connections.
+@end deftypemethod
+
+@deftypemethod Pool Integer ping
+    attempts to ping and average the response time of all database
+    connections.
+@end deftypemethod
+
+@deftypemethod Pool Boolean disconnect
+    disconnects all the database connections in the pool.
+@end deftypemethod
+
+
+
+@chapter class Result
+
+
+
+@deftypemethod Result Boolean complete?
+    Always returns true in a sync environment. In an async environment, only
+    returns true if all result processing has been completed.
+@end deftypemethod
+
+@deftypemethod Result Boolean has_data?
+    Always returns true in a sync environment. In an async environment, only
+    returns true if there is outstanding data to fetch.
+@end deftypemethod
+
+@deftypemethod Result Boolean eof?
+    Returns true if all results have been fetched.
+@end deftypemethod
+
+@deftypemethod Result NilClass rewind
+    resets the fetch iterator to the beginning. See also: #reload.
+@end deftypemethod
+
+@deftypemethod Result Integer rows
+    If available, returns the number of rows in this result. Else, nil.
+@end deftypemethod
+
+@deftypemethod Result Array binds
+    accessor for the binds that created this method
+@end deftypemethod
+
+@deftypemethod Result NilClass as (Class @var{kind}, Array @var{*args})
+    Given a Class and arguments, uses it to interpret the array. The class is
+    constructed with the result object and the arguments provided at the end,
+    and then a method called fetch() is attempted with the row count.
+    
+    Especially for specific class designations, (XML formatting is a good
+    example) output formats may not necessarily equate to a single row, in that
+    case, one "unit" should be returned from #fetch, and this entailings of
+    this unit should be specified in the driver.
+
+    If this this method is not called, fetch yields a standard array with type
+    converted items. 
+@end deftypemethod
+
+@deftypemethod Result Object fetch (Integer @var{row_count})
+    fetches one item, or given an argument, @var{row_count} rows.  If the
+    row_count is ":all", fetches all outstanding rows. See #as for how rows may
+    be interpreted.
+@end deftypemethod
+
+@deftypemethod Result {Array of Object} raw_fetch (Integer @var{row_count})
+    Raw fetch performs no conversions -- returns an array of objects yielding
+    whatever the underlying driver gave us. 
+@end deftypemethod
+
+@deftypemethod Result Boolean finish
+	finishes the underlying statement handle and invalidates the data.
+	reloading will no longer be possible once this is called and should
+	raise (or maybe we should reprepare/execute?).
+@end deftypemethod
+
+@deftypemethod Result STH sth
+	returns the statement handle that yielded this result.	
+@end deftypemethod
+
+@deftypemethod Result Schema schema
+	returns a Schema object that corresponds to the data in this result.
+@end deftypemethod
+
+@deftypemethod Result NilClass each (@var{&block})
+    similar to calling fetch iteratively with a callback. With proper async
+    driver support, will register a callback from the block which will only
+    process when there are new rows to be had.
+@end deftypemethod
+
+
+@chapter class CursorResult < Result
+
+This class is just a cursor-oriented method of transmitting results. 
+
+
+
+@chapter class Row
+
+row is just an array, but this needs to be thought out a little more.
+
+
+
+@chapter Schema
+
+
+
+@deftypemethod Schema {Array of Column} columns
+	returns column information (see Column object below) for all elements of
+	the Schema.
+@end deftypemethod
+
+@deftypemethod Schema {Array of Symbol} table_names
+	returns table names (there may be more than one in the event of a query
+	Schema) for all the objects a part of this Schema.
+@end deftypemethod
+
+
+
+@chapter Column
+
+
+
+@deftypemethod Column String name
+@end deftypemethod
+
+@deftypemethod Column String type
+	this is the type the database yields
+@end deftypemethod
+	
+@deftypemethod Column Class ruby_type
+	Accessor. this is what ruby thinks this type should be, or you can set it directly
+	which will be used at type conversion time.
+@end deftypemethod
+
+@deftypemethod Column Integer precision 
+    (alias: length)
+	precision is the first number in a database type. it is aliased to the
+	method 'length' because sometimes that's what precision actually is
+	depending on the type.
+@end deftypemethod
+
+@deftypemethod Column Integer scale
+	scale is the second number in a database type. this is often the right
+	side of a decimal value or sometimes a factoring quotient.
+@end deftypemethod
+
+@deftypemethod Column Boolean nullable@?
+	can this column be null?
+@end deftypemethod
+	
+@deftypemethod Column String metadata
+	metadata is a bucket for things we don't understand; namely things like AUTOINCREMENT.
+@end deftypemethod
+
+@deftypemethod Column String default 
+	default is the column default -- this is provided for informational
+	aspects only and should not be used for anything sane.
+@end deftypemethod
+
+@page
+@node Method Index
+@unnumbered Method Index
+@printindex fn
+
+@bye