Database Cleaner

DatabaseCleaner includes safeguards to prevent accidental database cleaning in production environments by checking ENV, APP_ENV, RACK_ENV, and RAILS_ENV. To bypass this check, you can use an environment variable or a Ruby configuration setting.

export DATABASE_CLEANER_ALLOW_PRODUCTION=true

DatabaseCleaner.allow_production = true

To manually integrate DatabaseCleaner with Cucumber, create a support file (e.g., features/support/database_cleaner.rb) and use an Around hook to wrap scenarios in a DatabaseCleaner.cleaning block.

require 'database_cleaner/active_record'

DatabaseCleaner.strategy = :truncation

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

DatabaseCleaner prevents running against remote databases by checking if DATABASE_URL excludes localhost, .local, or 127.0.0.1. To allow cleaning a remote database, use an environment variable or a Ruby configuration setting.

export DATABASE_CLEANER_ALLOW_REMOTE_DATABASE_URL=true

DatabaseCleaner.allow_remote_database_url = true

For Minitest, you can manually call .start and .clean in before and after hooks, or use the minitest-around gem to use the .cleaning block pattern.

# Manual approach
DatabaseCleaner.strategy = :transaction

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

  after :each do
    DatabaseCleaner.clean
  end
end

# Using minitest-around gem
class Minitest::Spec
  around do |tests|
    DatabaseCleaner.cleaning(&tests)
  end
end

Instead of using the main database_cleaner gem, install the specific adapter for your ORM. Most projects using ActiveRecord will only need database_cleaner-active_record.

To use multiple ORMs, include multiple gems in your Gemfile within the :test group.

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

# For multiple ORMs
group :test do
  gem 'database_cleaner-active_record'
  gem 'database_cleaner-redis'
end

To integrate DatabaseCleaner with RSpec, configure it in your RSpec.configure block. A common pattern is to use :truncation once at the start of the suite and :transaction for individual tests.

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

Instead of allowing all remote databases, you can specify a url_allowlist to restrict DatabaseCleaner to specific connection strings. Elements in the allowlist are matched using case equality (===), meaning you can provide strings, regular expressions, or procs.

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

# Using regular expressions
DatabaseCleaner.url_allowlist = [
  %r{^postgres://postgres@localhost}
]

# Using procs for custom logic
DatabaseCleaner.url_allowlist = [
  proc {|uri| URI.parse(uri).user == "test" }
]

Some strategies (like :transaction) require a lifecycle management approach. You must either call .start before the test and .clean after, or wrap the test execution in a .cleaning block.

• Manual approach: Call DatabaseCleaner.start in your test setup and DatabaseCleaner.clean in your teardown.
• Block approach: Use DatabaseCleaner.cleaning { ... } to automatically handle the lifecycle.

If your application uses multiple ORMs or multiple database connections, you can specify which one to configure using the DatabaseCleaner[:orm] syntax. You can also specify a specific database connection via the db: option or by passing a model directly.

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

# Specify particular ORMs
DatabaseCleaner[:active_record].strategy = :transaction
DatabaseCleaner[:mongo_mapper].strategy = :truncation

# Specify particular databases via symbol
DatabaseCleaner[:active_record, db: :two]

# Specify particular databases via a Model
DatabaseCleaner[:active_record, db: ModelWithDifferentConnection]

You can set a global strategy or perform one-off cleanings. Common strategies include :truncation, :transaction, and :deletion. A :null strategy (or setting strategy to nil) performs no cleaning.

To use a strategy with options (like only or except for specific tables), pass them as an array with the strategy name.

When using the postgresql adapter, provide a configuration block with the following keys:

• adapter: Set to postgresql.
• database: The name of the database.
• username: The database user.
• password: The database password.
• host: The database host address.
• encoding: The character encoding (e.g., unicode).
• template: The database template to use.

postgres:
  adapter: postgresql
  database: database_cleaner_test
  username: postgres
  password: 
  host: 127.0.0.1
  encoding: unicode
  template: template0