= The NullDB Connection Adapter Plugin

== What

NullDB is a Rails database connection adapter that interprets common
database operations as no-ops.  It is the Null Object pattern as
applied to database adapters.

== How 

Once installed, NullDB can be used much like any other ActiveRecord
database adapter:

  ActiveRecord::Base.establish_connection :adapter => nulldb

NullDB needs to know where you keep your schema file in order to
reflect table metadata.  By default it looks in
RAILS_ROOT/db/schema.rb.  You can override that by setting the
+schema+ option:

  ActiveRecord::Base.establish_connection :adapter => nulldb,
                                          :schema  => foo/myschema.rb

There is a helper method included for configuring RSpec sessions to
use NullDB.  Just put the following in your spec/spec_helper.rb:

  Spec::Runner.configure do |config|
    ::NullDB.insinuate_into_spec(config)
  end

You can also experiment with putting NullDB in your database.yml:

  unit_test:
    adapter: nulldb

However, due to the way Rails hard-codes specific database adapters
into its standard Rake tasks, you may find that this generates
unexpected and difficult-to-debug behavior.  Workarounds for this are
under development.

== Why 

NullDB is intended to assist in writing fast database-independant unit
tests for ActiveRecord classes.  For why you would want to test your
models without the database, see:
http://www.dcmanges.com/blog/rails-unit-record-test-without-the-database.

NullDB was inspired by the ARBS[http://arbs.rubyforge.org/] and
UnitRecord[http://unit-test-ar.rubyforge.org/] libraries.  It differs
from them in a couple of ways:

1. It works.  At the time of writing both ARBS and UnitRecord were
   not working for me out of the box with Rails 2.0. 

2. It avoids monkey-patching as much as possible.  Rather than
   re-wiring the secret inner workings of ActiveRecord (and thus being
   tightly coupled to those inner workings), NullDB implements the
   same [semi-]well-documented public interface that the other standard
   database adapters, like MySQL and SQLServer, implement.

3. UnitRecord takes the approach of eliminating database interaction
   in tests by turning almost every database interaction into an
   exception.  NullDB recognizes that ActiveRecord objects typically
   can't take two steps without consulting the database, so instead it
   turns database interactions into no-ops.

One concrete advantage of this null-object pattern design is that it
is possible with NullDB to test +after_save+ hooks.  With NullDB, you
can call +#save+ and all of the usual callbacks will be called - but
nothing will be saved.

== Limitations

* It is *not* an in-memory database.  Finds will not work.  Neither
  will #reload, currently.
* It has only the most rudimentery schema/migration support.  Complex
  migrations will probably break it.
* Lots of other things probably don't work.  Patches welcome!

== Who 

NullDB was written by Avdi Grimm <mailto:avdi@avdi.org>

== Where

* Homepage: http://avdi.org/projects/nulldb/
* Public SVN: http://svn.avdi.org/nulldb/

== Changes

 * Version 0.0.1 (2007-02-18)
   - Initial Release

== License

See the LICENSE file for licensing information.