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, Sequel, MongoMapper, Mongoid, and CouchPotato are supported.
Here is an overview of the strategies supported for each library:
ORM | Truncation | Transaction | Deletion | Removal |
---|---|---|---|---|
ActiveRecord | Yes | Yes | Yes | Yes |
DataMapper | Yes | Yes | No | Yes |
CouchPotato | Yes | No | No | No |
MongoMapper | Yes | No | No | No |
Sequel | Yes | Yes | No | No |
(Default strategy for each library is denoted in bold)
The ActiveRecord :deletion
strategy is useful for when the :truncation
strategy causes
locks (as reported by some Oracle DB users). The :deletion
option has been reported to
be faster than :truncation
in some cases as well. In general, the best approach is to use
:transaction
since it is the fastest.
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
.
The addition of the :removal
strategy is typically for use with external web applications
where the web app cannot run within a transaction and it is desirable to remove records from
the database after a cucumber scenario has completed and where deleting all records from tables
(as in the Deletion strategy) is not desirable (for example, if you want to start with known
data in the database.)
For support or to discuss development please use the Google Group.
require 'database_cleaner' DatabaseCleaner.strategy = :truncation # then, whenever you need to clean the DB DatabaseCleaner.clean
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 dirty_the_db 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
The :removal strategy is useful if you want to work with a database with existing data and loading the data set would be too slow to repeat at each clean. This can also be useful if you are testing a remote web application in another language that cannot share a database connection and make use of the :transaction strategy.
This strategy supports both ActiveRecord and DataMapper ORMs.
For example:
require 'database_cleaner' DatabaseCleaner.strategy = :removal DatabaseCleaner.start # removing an object at clean user = User.create user.save DatabaseCleaner.mark_for_removal user # setup removal in FactoryGirl: FactoryGirl.define do factory :user do name "Joe Bloggs" after_create { |user| DatabaseCleaner.mark_for_removal user } end end # this object will also be removed at clean user = FactoryGirl.create :user # you can also undo a record change at clean account = Account.find_the_account original_balance = account.balance DatabaseCleaner.at_removal do account.balance = original_balance account.save end perform_some_action_that_changes_the_balance_in account # destroy the 2 users created above and revert the change to the account balance: DatabaseCleaner.start
RSpec.configure do |config| config.before(:suite) do DatabaseCleaner.strategy = :transaction DatabaseCleaner.clean_with(:truncation) end config.before(:each) do DatabaseCleaner.start end config.after(:each) do DatabaseCleaner.clean end end
Add this to your features/support/env.rb file:
begin require 'database_cleaner' require 'database_cleaner/cucumber' DatabaseCleaner.strategy = :truncation rescue NameError raise "You need to add database_cleaner to your Gemfile (in the :test group) if you wish to use it." end
A good idea is to create the before and after hooks to use the DatabaseCleaner.start and DatabaseCleaner.clean methods.
Inside features/support/hooks.rb:
Before do DatabaseCleaner.start end After do |scenario| DatabaseCleaner.clean end
This should cover the basics of tear down between scenarios and keeping your database clean.
For more examples see the section “Why?”
In rare cases DatabaseCleaner will encounter errors that it will log. By default it uses STDOUT set to the ERROR level but you can configure this to use whatever Logger you desire. Here’s an example of using the Rails.logger in env.rb:
DatabaseCleaner.logger = Rails.logger
If you are using Postgres and have foreign key constraints, the truncation strategy will cause a lot of extra noise to appear on STDERR (in
the form of “NOTICE truncate cascades” messages). To silence these warnings set the following log level in your postgresql.conf file:
client_min_messages = warning
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 |
Sequel | DatabaseCleaner[:sequel] | ? |
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:
#env.rb 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:
#env.rb 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:
#env.rb
require ‘database_cleaner’
require ‘database_cleaner/cucumber’
DatabaseCleaner.strategy = (ENV[‘SELENIUM’] == ‘true’) ? :truncation : :transaction
Copyright © 2009 Ben Mabey. See LICENSE for details.
Copyright © 2012 Matt Connolly. See LICENSE for details.