myobie / seed-fu

Advanced seed data handling for Rails, combining the best practices of several methods together.

Seed Fu

Seed Fu is an attempt to once and for all solve the problem of inserting and maintaining seed data in a database. It uses a variety of techniques gathered from various places around the web and combines them to create what is hopefully the most robust seed data system around.

Warning: API Changes

Version 2.0.0 of Seed Fu introduces API changes. Seed::Writer has been completely overhauled and will require you to update your scripts. Some other deprecations have been introduced, but the methods will not be removed until version 2.1.0. Please see the CHANGELOG for details.

The API documentation is available in full at http://rubydoc.info/github/mbleigh/seed-fu/master/frames.

Basic Example

In db/fixtures/users.rb

User.seed do |s|
  s.id    = 1
  s.login = "jon"
  s.email = "[email protected]"
  s.name  = "Jon"
end

User.seed do |s|
  s.id    = 2
  s.login = "emily"
  s.email = "[email protected]"
  s.name  = "Emily"
end

To load the data:

$ rake db:seed_fu
== Seed from /path/to/app/db/fixtures/users.rb
 - User {:id=>1, :login=>"jon", :email=>"[email protected]", :name=>"Jon"}
 - User {:id=>2, :login=>"emily", :email=>"[email protected]", :name=>"Emily"}

Installation

Rails 3

Just add gem 'seed-fu' to your Gemfile

Active Record 3

Seed Fu depends on Active Record, but doesn't have to be used with a full Rails app. Simply load and require the seed-fu gem and you're set.

Rails 2.3

The current version is not backwards compatible with Rails 2.3. Please use Seed Fu version 1.2.3.

Rails 3.1 (beta)

As above, but install the gem which has '.rails31' prepended to its version string. For example, instead of using seed-fu version 2.0.1, use seed-fu version 2.0.1.rails31.

Constraints

Constraints are used to identify seeds, so that they can be updated if necessary. For example:

Point.seed(:x, :y) do |s|
  s.x = 4
  s.y = 7
  s.name = "Home"
end

The first time this seed is loaded, a Point record will be created. No suppose the name is changed:

Point.seed(:x, :y) do |s|
  s.x = 4
  s.y = 7
  s.name = "Work"
end

When this is run, Seed Fu will look for a Point based on the :x and :y constraints provided. It will see that a matching Point already exists and so update its attributes rather than create a new record.

If you do not want seeds to be updated after they have been created, use seed_once:

Point.seed_once(:x, :y) do |s|
  s.x = 4
  s.y = 7
  s.name = "Home"
end

The default constraint just checks the id of the record.

Where to put seed files

By default, seed files are looked for in the following locations:

• Rails.root/db/fixtures and Rails.root/db/fixtures/Rails.env in a Rails app
• db/fixtures when loaded without Rails

You can change these defaults by modifying the SeedFu.fixture_paths array.

Seed files can be named whatever you like, and are loaded in alphabetical order.

Terser syntax

When loading lots of records, the above block-based syntax can be quite verbose. You can use the following instead:

User.seed(:id,
  { :id => 1, :login => "jon",   :email => "[email protected]",   :name => "Jon"   },
  { :id => 2, :login => "emily", :email => "[email protected]", :name => "Emily" }
)

Rake task

Seed files can be run automatically using rake db:seed_fu. There are two options which you can pass:

• rake db:seed_fu FIXTURE_PATH=path/to/fixtures -- Where to find the fixtures
• rake db:seed_fu FILTER=users,articles -- Only run seed files with a filename matching the FILTER

You can also do a similar thing in your code by calling SeedFu.seed(fixture_paths, filter).

Disable output

To disable output from Seed Fu, set SeedFu.quiet = true.

Handling large seed files

Seed files can be huge. To handle large files (over a million rows), try these tricks:

• Gzip your fixtures. Seed Fu will read .rb.gz files happily. gzip -9 gives the best compression, and with Seed Fu's repetitive syntax, a 160M file can shrink to 16M.
• Add lines reading # BREAK EVAL in your big fixtures, and Seed Fu will avoid loading the whole file into memory. If you use SeedFu::Writer, these breaks are built into your generated fixtures.
• Load a single fixture at a time with the FILTER environment variable
• If you don't need Seed Fu's ability to update seed with new data, then you may find that activerecord-import is faster

Generating seed files

If you need to programmatically generate seed files, for example to convert a CSV file into a seed file, then you can use SeedFu::Writer.

Bugs / Feature requests

Please report them on Github Issues.

Contributors

• Michael Bleigh is the original author
• Jon Leighton is the current maintainer
• Thanks to Matthew Beale for his great work in adding the writer, making it faster and better.

Copyright © 2008-2010 Michael Bleigh, released under the MIT license