Data

Tools

Indexes

Applications

Experiments

Ruby

A summary of data about the Ruby ecosystem.

https://github.com/DatabaseCleaner/database_cleaner

Strategies for cleaning databases in Ruby. Can be used to ensure a clean state for testing.
https://github.com/DatabaseCleaner/database_cleaner

Keywords

database-cleaner ruby testing testing-tools

Keywords from Contributors

activerecord activejob mvc rubygems rspec rack crash-reporting cucumber sinatra devise

Last synced: about 19 hours ago
JSON representation

Repository metadata

Strategies for cleaning databases in Ruby. Can be used to ensure a clean state for testing.

README.markdown

Database Cleaner

Build Status
Code Climate
codecov
Gem Version
SemVer

Database Cleaner is a set of gems containing 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.

Gem Setup

Instead of using the database_cleaner gem directly, each ORM has its own gem. Most projects will only need the database_cleaner-active_record gem:

# Gemfile
group :test do
  gem 'database_cleaner-active_record'
end

If you are using multiple ORMs, just load multiple gems:

# Gemfile
group :test do
  gem 'database_cleaner-active_record'
  gem 'database_cleaner-redis'
end

List of adapters

Here is an overview of the databases and ORMs supported by each adapter:

MySQL, PostgreSQL, SQLite, etc

MongoDB

Redis

More details on available configuration options can be found in the README for the specific adapter gem that you're using.

For support or to discuss development please use the Google Group.

Discontinued adapters

The following adapters have been discontinued. Please let us know on the Google Group if you think one of these should be resurrected!

How to use

require 'database_cleaner/active_record'

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 need to be started before tests are run (for example the :transaction strategy needs to know to open up a transaction). This can be accomplished by calling DatabaseCleaner.start at the beginning of the run, or by running the tests inside a block to DatabaseCleaner.cleaning. So you would have:

require 'database_cleaner/active_record'

DatabaseCleaner.strategy = :transaction

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

dirty_the_db

DatabaseCleaner.clean # cleanup of the test

# OR

DatabaseCleaner.cleaning do
  dirty_the_db
end

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/active_record'

DatabaseCleaner.clean_with :truncation

DatabaseCleaner.strategy = :transaction

# then make the DatabaseCleaner.start and DatabaseCleaner.clean calls appropriately

What strategy is fastest?

For the SQL libraries the fastest option will be to use :transaction as transactions are simply rolled back. If you can use this strategy you should. However, if you wind up needing to use multiple database connections in your tests (i.e. your tests run in a different process than your application) then using this strategy becomes a bit more difficult. You can get around the problem a number of ways.

One common approach is to force all processes to use the same database connection (common ActiveRecord hack) however this approach has been reported to result in non-deterministic failures.

Another approach is to have the transactions rolled back in the application's process and relax the isolation level of the database (so the tests can read the uncommitted transactions).

An easier, but slower, solution is to use the :truncation or :deletion strategy.

So what is fastest out of :deletion and :truncation? Well, it depends on your table structure and what percentage of tables you populate in an average test. The reasoning is out of the scope of this README but here is a good SO answer on this topic for Postgres.

Some people report much faster speeds with :deletion while others say :truncation is faster for them. The best approach therefore is it try all options on your test suite and see what is faster.

If you are using ActiveRecord then take a look at the additional options available for :truncation.

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.

Test Framework Examples

RSpec Example

RSpec.configure do |config|

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

  config.around(:each) do |example|
    DatabaseCleaner.cleaning do
      example.run
    end
  end

end

RSpec with Capybara Example

You'll typically discover a feature spec is incorrectly using transaction
instead of truncation strategy when the data created in the spec is not
visible in the app-under-test.

A frequently occurring example of this is when, after creating a user in a
spec, the spec mysteriously fails to login with the user. This happens because
the user is created inside of an uncommitted transaction on one database
connection, while the login attempt is made using a separate database
connection. This separate database connection cannot access the
uncommitted user data created over the first database connection due to
transaction isolation.

For feature specs using a Capybara driver for an external
JavaScript-capable browser (in practice this is all drivers except
:rack_test), the Rack app under test and the specs do not share a
database connection.

When a spec and app-under-test do not share a database connection,
you'll likely need to use the truncation strategy instead of the
transaction strategy.

See the suggested config below to temporarily enable truncation strategy
for affected feature specs only. This config continues to use transaction
strategy for all other specs.

It's also recommended to use append_after to ensure DatabaseCleaner.clean
runs after the after-test cleanup capybara/rspec installs.

require 'capybara/rspec'

#...

RSpec.configure do |config|

  config.use_transactional_fixtures = false

  config.before(:suite) do
    if config.use_transactional_fixtures?
      raise(<<-MSG)
        Delete line `config.use_transactional_fixtures = true` from rails_helper.rb
        (or set it to false) to prevent uncommitted transactions being used in
        JavaScript-dependent specs.

        During testing, the app-under-test that the browser driver connects to
        uses a different database connection to the database connection used by
        the spec. The app's database connection would not be able to access
        uncommitted transaction data setup over the spec's database connection.
      MSG
    end
    DatabaseCleaner.clean_with(:truncation)
  end

  config.before(:each) do
    DatabaseCleaner.strategy = :transaction
  end

  config.before(:each, type: :feature) do
    # :rack_test driver's Rack app under test shares database connection
    # with the specs, so continue to use transaction strategy for speed.
    driver_shares_db_connection_with_specs = Capybara.current_driver == :rack_test

    unless driver_shares_db_connection_with_specs
      # Driver is probably for an external browser with an app
      # under test that does *not* share a database connection with the
      # specs, so use truncation strategy.
      DatabaseCleaner.strategy = :truncation
    end
  end

  config.before(:each) do
    DatabaseCleaner.start
  end

  config.append_after(:each) do
    DatabaseCleaner.clean
  end

end

Minitest Example

DatabaseCleaner.strategy = :transaction

class Minitest::Spec
  before :each do
    DatabaseCleaner.start
  end

  after :each do
    DatabaseCleaner.clean
  end
end

# with the minitest-around gem, this may be used instead:
class Minitest::Spec
  around do |tests|
    DatabaseCleaner.cleaning(&tests)
  end
end

Cucumber Example

If you're using Cucumber with Rails, just use the generator that ships with cucumber-rails, and that will create all the code you need to integrate DatabaseCleaner into your Rails project.

Otherwise, to add DatabaseCleaner to your project by hand, create a file features/support/database_cleaner.rb that looks like this:

require 'database_cleaner/active_record'

DatabaseCleaner.strategy = :truncation

Around do |scenario, block|
  DatabaseCleaner.cleaning(&block)
end

This should cover the basics of tear down between scenarios and keeping your database clean.

For more examples see the section "Why?".

How to use with multiple ORMs

Sometimes you need to use multiple ORMs in your application.

You can use DatabaseCleaner to clean multiple ORMs, and multiple databases for those ORMs.

require 'database_cleaner/active_record'
require 'database_cleaner/mongo_mapper'

# How to specify particular orms
DatabaseCleaner[:active_record].strategy = :transaction
DatabaseCleaner[:mongo_mapper].strategy = :truncation

# How to specify particular databases
DatabaseCleaner[:active_record, db: :two]

# You may also pass in the model directly:
DatabaseCleaner[:active_record, db: ModelWithDifferentConnection]

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

Why?

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.

After copying and pasting code to do this several times I decided to package it up as a gem and save everyone a bit of time.

Safeguards

DatabaseCleaner comes with safeguards against:

  • Running in production (checking for ENV, APP_ENV, RACK_ENV, and RAILS_ENV)
  • Running against a remote database (checking for a DATABASE_URL that does not include localhost, .local or 127.0.0.1)

Both safeguards can be disabled separately as follows.

Using environment variables:

export DATABASE_CLEANER_ALLOW_PRODUCTION=true
export DATABASE_CLEANER_ALLOW_REMOTE_DATABASE_URL=true

In Ruby:

DatabaseCleaner.allow_production = true
DatabaseCleaner.allow_remote_database_url = true

In Ruby, a URL allowlist can be specified. When specified, DatabaseCleaner will only allow DATABASE_URL to be equal
to one of the values specified in the url allowlist like so:

DatabaseCleaner.url_allowlist = ['postgres://postgres@localhost', 'postgres://foo@bar']

Allowlist elements are matched with case equality (===), so regular expressions or procs may be used:

DatabaseCleaner.url_allowlist = [
  %r{^postgres://postgres@localhost},         # match any db with this prefix
  proc {|uri| URI.parse(uri).user == "test" } # match any db authenticating with the 'test' user
]

CHANGELOG

See HISTORY for details.

COPYRIGHT

See LICENSE for details.

Owner metadata

GitHub Events

Total
Last Year

Committers metadata

Last synced: 4 days ago

Total Commits: 960
Total Committers: 217
Avg Commits per committer: 4.424
Development Distribution Score (DDS): 0.782

Commits in past year: 2
Committers in past year: 2
Avg Commits per committer in past year: 1.0
Development Distribution Score (DDS) in past year: 0.5

Name Email Commits
Micah Geisel m****h@b****m 209
Ben Mabey b****n@b****m 202
Jon Rowe h****o@j****k 74
Ernesto Tagwerker e****b@o****m 71
Jon Rowe j****n@m****k 17
snusnu g****a@g****m 12
Kostas Karachalios v****k@m****m 11
sanemat o****n@g****m 10
Sven Fuchs me@s****m 9
Sebastian Skałacki s****e@g****m 9
stanislaw s****h@g****m 9
Petteri Räty p****u@p****u 8
Peter Goldstein p****n@g****m 7
Dieter Pisarewski d****i@g****m 6
Andreas Bühmann b****n@f****e 5
Timothée Peignier t****r@t****g 5
Judson n****y@g****m 5
Ethan e****n@d****l 5
Corin Langosch i****o@n****m 5
Brian P O'Rourke b****n@o****o 5
ezro o****r@e****z 5
Greg Barnett g****t@u****m 4
David Barri j****y@g****m 4
Hank Shiao h****o@s****m 4
Jan Vlnas g****t@j****z 4
John Ferlito j****f@i****g 4
Micah Geisel o****s@g****m 4
Rob Hunter r****r@t****m 4
Sirko Sittig s****g@g****m 4
Tom Meier t****m@v****m 4
and 187 more...

Committer domains:

Issue and Pull Request metadata

Last synced: about 2 months ago

Total issues: 62
Total pull requests: 59
Average time to close issues: 10 months
Average time to close pull requests: about 1 year
Total issue authors: 54
Total pull request authors: 40
Average comments per issue: 4.02
Average comments per pull request: 2.41
Merged pull request: 38
Bot issues: 0
Bot pull requests: 0

Past year issues: 3
Past year pull requests: 4
Past year average time to close issues: N/A
Past year average time to close pull requests: 24 days
Past year issue authors: 3
Past year pull request authors: 4
Past year average comments per issue: 2.0
Past year average comments per pull request: 0.25
Past year merged pull request: 3
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/DatabaseCleaner/database_cleaner

Top Issue Authors

  • botandrose (5)
  • etagwerker (4)
  • dmolesUC (2)
  • tmaier (1)
  • luizkowalski (1)
  • thefotios (1)
  • kp666 (1)
  • TheSmartnik (1)
  • deivid-rodriguez (1)
  • jamesw (1)
  • swiknaba (1)
  • exocode (1)
  • jttyeung (1)
  • martijnmoneybird (1)
  • wjessop (1)

Top Pull Request Authors

  • botandrose (12)
  • petergoldstein (4)
  • etagwerker (3)
  • jslucas (2)
  • timriley (2)
  • pat (2)
  • TheSmartnik (2)
  • bpo (2)
  • arielj (2)
  • mtsmfm (2)
  • cherbst-2112 (2)
  • oggy (1)
  • ablignaut (1)
  • ProGM (1)
  • zoso10 (1)

Top Issue Labels

  • enhancement (1)
  • first-timers-only (1)
  • good first issue (1)

Top Pull Request Labels

  • enhancement (3)

Package metadata

gem.coop: database_cleaner

Strategies for cleaning databases. Can be used to ensure a clean slate for testing.

  • Homepage: https://github.com/DatabaseCleaner/database_cleaner
  • Documentation: http://www.rubydoc.info/gems/database_cleaner/
  • Licenses: MIT
  • Latest release: 2.1.0 (published about 1 year ago)
  • Last Synced: 2025-12-08T21:33:34.056Z (2 days ago)
  • Versions: 58
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 200,071,393 Total
  • Docker Downloads: 528,992,856
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 0.077%
    • Downloads: 0.119%
    • Docker downloads count: 0.189%
  • Maintainers (4)
gem.coop: database_cleaner-core

Strategies for cleaning databases. Can be used to ensure a clean slate for testing.

  • Homepage: https://github.com/DatabaseCleaner/database_cleaner
  • Documentation: http://www.rubydoc.info/gems/database_cleaner-core/
  • Licenses: MIT
  • Latest release: 2.0.1 (published almost 5 years ago)
  • Last Synced: 2025-12-09T13:00:51.458Z (1 day ago)
  • Versions: 4
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 103,665,123 Total
  • Docker Downloads: 378,576,642
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 0.156%
    • Downloads: 0.242%
    • Docker downloads count: 0.384%
  • Maintainers (2)
rubygems.org: database_cleaner

Strategies for cleaning databases. Can be used to ensure a clean slate for testing.

  • Homepage: https://github.com/DatabaseCleaner/database_cleaner
  • Documentation: http://www.rubydoc.info/gems/database_cleaner/
  • Licenses: MIT
  • Latest release: 2.1.0 (published about 1 year ago)
  • Last Synced: 2025-12-07T13:31:41.624Z (3 days ago)
  • Versions: 58
  • Dependent Packages: 2,026
  • Dependent Repositories: 102,151
  • Downloads: 200,001,689 Total
  • Docker Downloads: 528,992,856
  • Rankings:
    • Dependent packages count: 0.025%
    • Downloads: 0.102%
    • Dependent repos count: 0.118%
    • Docker downloads count: 0.267%
    • Average: 0.403%
    • Stargazers count: 0.682%
    • Forks count: 1.221%
  • Maintainers (4)
rubygems.org: database_cleaner-core

Strategies for cleaning databases. Can be used to ensure a clean slate for testing.

  • Homepage: https://github.com/DatabaseCleaner/database_cleaner
  • Documentation: http://www.rubydoc.info/gems/database_cleaner-core/
  • Licenses: MIT
  • Latest release: 2.0.1 (published almost 5 years ago)
  • Last Synced: 2025-12-09T15:31:34.595Z (1 day ago)
  • Versions: 4
  • Dependent Packages: 7
  • Dependent Repositories: 6,790
  • Downloads: 103,679,699 Total
  • Docker Downloads: 378,576,642
  • Rankings:
    • Dependent repos count: 0.391%
    • Downloads: 0.427%
    • Stargazers count: 0.682%
    • Average: 1.098%
    • Forks count: 1.222%
    • Docker downloads count: 1.627%
    • Dependent packages count: 2.237%
  • Maintainers (2)
proxy.golang.org: github.com/databasecleaner/database_cleaner

proxy.golang.org: github.com/DatabaseCleaner/database_cleaner

Dependencies

Gemfile rubygems
  • codecov >= 0 development
  • simplecov >= 0 development
  • byebug >= 0
  • database_cleaner-active_record >= 0
  • database_cleaner-redis >= 0
database_cleaner-core.gemspec rubygems
  • activesupport >= 0 development
  • bundler >= 0 development
  • cucumber ~> 3.0 development
  • database_cleaner-active_record >= 0 development
  • database_cleaner-redis >= 0 development
  • guard-rspec >= 0 development
  • listen >= 0 development
  • rake >= 0 development
  • rspec >= 0 development
  • sqlite3 >= 0 development
database_cleaner.gemspec rubygems
  • database_cleaner-active_record ~> 2.0.0
.github/workflows/ci.yml actions
  • actions/checkout v2 composite
  • ruby/setup-ruby v1 composite
  • redis * docker

Score: 34.990727162902544