README.textile in database_cleaner-0.7.0 vs README.textile in database_cleaner-0.7.1
- old
+ new
@@ -3,28 +3,29 @@
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.
+ActiveRecord, DataMapper, Sequel, 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 |
+| Sequel | **Yes** | Yes | 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.
+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
+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@.
h2. How to use
<pre>
@@ -68,11 +69,11 @@
DatabaseCleaner.clean_with :truncation
DatabaseCleaner.strategy = :transaction
# then make the DatabaseCleaner.start and DatabaseCleaner.clean calls appropriately
</pre>
-Example usage with RSpec:
+h3. RSpec Example
<pre>
RSpec.configure do |config|
config.before(:suite) do
@@ -89,12 +90,43 @@
end
end
</pre>
-For use in Cucumber please see the section below.
+h3. Cucumber Example
+Add this to your features/support/env.rb file:
+
+<pre>
+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
+</pre>
+
+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:
+
+<pre>
+Before do
+ DatabaseCleaner.start
+end
+
+After do |scenario|
+ DatabaseCleaner.clean
+end
+</pre>
+
+This should cover the basics of tear down between scenarios and keeping your database clean.
+For more examples see the section "Why?"
+
+h2. Common Errors
+
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:
<pre>
DatabaseCleaner.logger = Rails.logger
</pre>
@@ -112,11 +144,11 @@
<pre>
#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}]
</pre>
Usage beyond that remains the same with DatabaseCleaner.start calling any setup on the different configured connections, and DatabaseCleaner.clean executing afterwards.
@@ -128,9 +160,10 @@
| 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] | ? |
h2. 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