dibber

== Dibber

A set of tools to tidy up rails seeds.rb files.

Dibber has two compoments:

=== Seeder

Seeder is designed to simplify the process of pulling attributes from YAML files, and populating ActiveRecord objects with those attributes.

=== ProcessLog

ProcessLog provides Seeder with a simple before and after reporting tool.

=== Installation

Add this to your Gemfile:

gem 'dibber'

=== Rails Examples

You have a rails app with a Thing model, and you want to seed it with some things. Thing instances have the attributes name, colour, size. You have a YAML file db/seeds/things.yml that looks like this:

foo:
  colour: red
  size: large

bar:
  colour: blue
  size: small

Add this to your 'db/seeds.rb'

Seeder = Dibber::Seeder
Seeder.seed Thing
puts Seeder.report

Then run rake db:seed

Seeder will create two new things.

You'll then be able to do this:

thing = Thing.find_by(name: 'foo')
thing.colour    ---> 'red'

=== Pass the name of the class to seed

All of these are equivalent commands

Dibber::Seeder.seed Thing
Dibber::Seeder.seed :thing
Dibber::Seeder.seed 'Thing'

=== Dynamic content

Seed content can also have dynamic content added via ERB. For example, if you want the colour of the foo thing to be either 'red' or 'yellow', change db/seeds/things.yml to

foo:
  colour: <%= ['red', 'yellow'].sample %>
  size: large

Then when we run Dibber::Seeder.seed :thing a new Thing will be created with the colour set to either 'red' or 'yellow'.

=== Using blocks with Seeder

If you pass a block to .seed the block will be called on each object being built as it is created or updated.

So for example, if Thing has attributes size and big the following is possible:

Dibber::Seeder.seed(:thing) do |thing|
  thing.big = thing.attributes['size'] > 10
end

== Report

Seeder.report outputs a report detailing start and end time, and a log of how the number of things has changed

== Overwriting existing entries

Seeder#build will not overwrite existing data unless directed to do so.

thing.update_attribute(:colour, 'black') Seeder.seed :thing thing.reload.colour ----> 'black'

Seeder.seed(:thing, overwrite: true) thing.reload.colour ----> 'red'

== Using alternative class and field name mappings

Seeder.seed calls Seeder#build to build the objects defined in the seed files. You can call the build method directly if your seed file names do not match the class name:

Seeder.new(Thing, 'other_things.yml').build

== Outside Rails

Dibber can be used outside of Rails, but in this case you will need to specify the location of the seed files.

Seeder.seeds_path = "some/path/to/seeds"

You can also use this technique in Rails if you want to put your seed files in a folder other than 'db/seeds'

== More examples

Take a look at test/examples/seeds.rb for some more usage examples.

If you clone this app, you can run this example at the project root:

ruby test/examples/seeds.rb

There is also an example of process log usage:

ruby test/examples/process_logs.rb