WORK IN PROGRESS - PLEASE DO NOT FOLLOW THESE INSTRUCTIONS UNTIL v2.0.0 FINAL IS RELEASED!

How to add a new adapter

Note the following tutorial is for database_cleaner version 2 and above

Every adapter is a separate gem, the first step in the creation of an adapter is to create a new gem.

Naming

Please follow the Rubygems convention for gem naming. The namespace you will be working within is DatabaseCleaner::Namespace where Namespace is the name of the ORM you are creation an adapter for. For example, database_cleaner-active_record provides DatabaseCleaner::ActiveRecord, and database_cleaner-redis provides DatabaseCleaner::Redis, etc.

Bootstrapping a gem

We will use bundle to bootstrap the new gem. This will produce all the initial files needed.

bundle gem database_cleaner-orm_name

Modifying .gemspec

You need to add a couple of dependecies to .gemspec:

database_cleaner-core
Adapter you're creating this gem for

  spec.add_dependency "database_cleaner-core"
  spec.add_dependency "orm_name", "some version if required"

File structure

Inside the lib/database_cleaner/orm_name directory, you will need to create a few files:

Separate files for each strategy you have

The file structure you end up with will look something like this

\-lib
  \-database_cleaner
    \- orm_name
      \- truncation.rb
      \- deletion.rb
      \- transaction.rb
      \- version.rb
    \- orm_name.rb

orm_name.rb

File orm_name.rb must do the following:

define module method .available_strategies on DatabaseCleaner::OrmName.
require all the gems strategies
configure DatabaseCleaner with the default strategy for the ORM.

So, in the end you will end up with a file that might look something like this:

# lib/database_cleaner/orm_name.rb

require 'database_cleaner/orm_name/version'
require 'database_cleaner/core'
require 'database_cleaner/orm_name/transaction'
require 'database_cleaner/orm_name/truncation'
require 'database_cleaner/orm_name/deletion'

module DatabaseCleaner
  module OrmName
    def self.available_strategies
      %i[transaction truncation deletion]
    end
  end
end

DatabaseCleaner[:orm_name].strategy = :transaction

Strategy classes

Each strategy class can inherit from DatabaseCleaner::Strategy to get it most of the way there. If you do, you only need to define one method!

Each strategy must have the following instance methods

#clean -- where the cleaning happens

Optionally, depending on how your strategy works you may define

#start -- if your strategy is transactional, this is where you would start the database transaction that #clean later rolls back.

Given that we're creating a strategy for truncation, you may end up with something like the following class:

# lib/database_cleaner/orm_name/truncation.rb

require 'database_cleaner/strategy'
require 'orm'

module DatabaseCleaner
  module OrmName
    class Truncation < Strategy
      def clean
        # actual database cleaning code goes here
        ORM.truncate_all_tables!
      end
    end
  end
end

That's about it for the code needed to create your own adapter!

Testing

To make sure that your new adapter adheres to the Database Cleaner API, database_cleaner-core provides an RSpec shared example. This shared example only checks to make sure all the right methods exist. You will still want to write tests to verify that the cleaning actually works as you expect!

# spec/database_cleaner/orm_name_spec.rb

require 'database_cleaner/orm_name'
require 'database_cleaner/spec'

RSpec.describe DatabaseCleaner::OrmName do
  it_should_behave_like "a database_cleaner strategy"
end

What's next

Now you should be set up to with your own database_cleaner ORM adapter. Also, don't forget to take a look at the already created adapters, if you encounter any problems.

When you are done with your adapter gem, only a few things left to do

Create a repository with your code
Push code to rubygems
Open a PR to add your adapter to the list

4.1 KiB Raw Blame History