Strategies for cleaning databases in Ruby. Can be used to ensure a clean state for testing.
Pull request Compare This branch is 624 commits behind DatabaseCleaner:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Database Cleaner

Database Cleaner is a set of strategies for cleaning your database in Ruby.
The original use case was to ensure a clean state during tests. Each strategy
is a small amount of code but is code that is usually needed in any ruby app
that is testing with a database.

ActiveRecord, DataMapper, MongoMapper, Mongoid, and CouchPotato are supported.

Here is an overview of the strategies supported for each library:

ORM Truncation Transaction Deletion
ActiveRecord Yes Yes Yes
DataMapper Yes Yes No
CouchPotato Yes No No
MongoMapper Yes No No
Mongoid Yes No No

(Default strategy for each library is denoted in bold)

The ActiveRecord :deletion strategy is only useful for when the :truncation strategy causes
locks (as reported by some Oracle DB users). The :truncation strategy is the preferred option
since it is much faster.

Database Cleaner also includes a null strategy (that does no cleaning at all) which can be used
with any ORM library. You can also explicitly use it by setting your strategy to nil.

How to use

  require 'database_cleaner'
  DatabaseCleaner.strategy = :truncation

  # then, whenever you need to clean the DB

With the :truncation strategy you can also pass in options, for example:

DatabaseCleaner.strategy = :truncation, {:only => %w[widgets dogs some_other_table]}

  DatabaseCleaner.strategy = :truncation, {:except => %w[widgets]}

(I should point out the truncation strategy will never truncate your schema_migrations table.)

Some strategies require that you call DatabaseCleaner.start before calling clean
(for example the :transaction one needs to know to open up a transaction). So
you would have:

  require 'database_cleaner'
  DatabaseCleaner.strategy = :transaction

  DatabaseCleaner.start # usually this is called in setup of a test
  DatabaseCleaner.clean # cleanup of the test

At times you may want to do a single clean with one strategy. For example, you may want
to start the process by truncating all the tables, but then use the faster transaction
strategy the remaining time. To accomplish this you can say:

  require 'database_cleaner'
  DatabaseCleaner.clean_with :truncation
  DatabaseCleaner.strategy = :transaction
  # then make the DatabaseCleaner.start and DatabaseCleaner.clean calls appropriately

Example usage with RSpec:

Spec::Runner.configure do |config|

  config.before(:suite) do
    DatabaseCleaner.strategy = :transaction

  config.before(:each) do

  config.after(:each) do


For use in Cucumber please see the section below.

How to use with multiple ORM’s

Sometimes you need to use multiple ORMs in your application. You can use DatabaseCleaner to clean multiple ORMs, and multiple connections for those ORMs.

  #How to specify particular orms
  DatabaseCleaner[:active_record].strategy = :transaction
  DatabaseCleaner[:mongo_mapper].strategy = :truncation
  #How to specify particular connections
  DatabaseCleaner[:active_record,{:connection => :two}]

Usage beyond that remains the same with DatabaseCleaner.start calling any setup on the different configured connections, and DatabaseCleaner.clean executing afterwards.

Configuration options

ORM How to access Notes
Active Record DatabaseCleaner[:active_record] Connection specified as :symbol keys, loaded from config/database.yml
Data Mapper DatabaseCleaner[:data_mapper] Connection specified as :symbol keys, loaded via Datamapper repositories
Mongo Mapper DatabaseCleaner[:mongo_mapper] Multiple connections not yet supported
Mongoid DatabaseCleaner[:mongoid] Multiple connections not yet supported
Couch Potato DatabaseCleaner[:couch_potato] Multiple connections not yet supported


One of my motivations for writing this library was to have an easy way to
turn on what Rails calls “transactional_fixtures” in my non-rails
ActiveRecord projects. For example, Cucumber ships with a Rails world that
will wrap each scenario in a transaction. This is great, but what if you are
using ActiveRecord in a non-rails project? You used to have to copy-and-paste
the needed code, but with DatabaseCleaner you can now say:

  require 'database_cleaner'
  require 'database_cleaner/cucumber'
  DatabaseCleaner.strategy = :transaction

Now lets say you are running your features and it requires that another process be
involved (i.e. Selenium running against your app’s server.) You can simply change
your strategy type:

  require 'database_cleaner'
  require 'database_cleaner/cucumber'
  DatabaseCleaner.strategy = :truncation

You can have the best of both worlds and use the best one for the job:

require ‘database_cleaner’
require ‘database_cleaner/cucumber’
DatabaseCleaner.strategy = (ENV[‘SELENIUM’] == ‘true’) ? :truncation : :transaction


Copyright © 2009 Ben Mabey. See LICENSE for details.