isabella232 / sprig

Relational seeding for Rails apps

Seed Rails application by convention, not configuration.

Provides support for common files types: csv, yaml, and json. Extensible for the rest!

Learn more about Sprig and view documentation at http://vigetlabs.github.io/sprig/.

Installation

Add into your Gemfile

gem "sprig"

Use rails generate sprig:install to create environment-specific and shared seed directories.

The Sprig Directive

Within your seed file, you can use the sprig directive to initiate Sprig's dark magicks. A simple directive might look like this.

# seeds.rb

include Sprig::Helpers

sprig [User, Post, Comment]

For shared seeds:
sprig_shared [User, Post, Comment]

This directive tells Sprig to go find your datafiles for the User, Post, and Comment seed resources, build records from the data entries, and insert them into the database. Sprig will automatically detect known datafile types like .yml, .json, or .csv within your environment-specific seed directory.

Environment

Seed files are unique to the environment in which your Rails application is running. Within db/seeds create an environment-specific directory (i.e. /development for your 'development' environment).

Shared

Shared seed files default directory is shared (eg db/seeds/shared) You can change it by settings`

To insert env specific together with shared seeds use:

sprig [User]
sprig_shared [User]

This will insert :env/users and shared/users seeds

Seed files

Hang your seed definitions on a records key for yaml and json files.

Examples:

# users.yml

records:
  - sprig_id: 1
    first_name: 'Lawson'
    last_name: 'Kurtz'
    username: 'lawdawg'
  - sprig_id: 'ryan' # Note: Sprig IDs can be integers or strings
    first_name: 'Ryan'
    last_name: 'Foster'
    username: 'mc_rubs'

// posts.json

{
  "records":[
    {
      "sprig_id":1,
      "title":"Json title",
      "content":"Json content"
    },
    {
      "sprig_id":2,
      "title":"Headline",
      "content":"Words about things"
    }
  ]
}

Each seed record needs a sprig_id defined that must be unique across all seed files per class. It can be an integer, string, whatever you prefer; as long as it is unique, Sprig can sort your seeds for insertion and detect any cyclic relationships.

Relationships

Create relationships between seed records with the sprig_record helper:

# comments.yml

records:
  - sprig_id: 1
    post_id: "<%= sprig_record(Post, 1).id %>"
    body: "Yaml Comment body"

Has and Belongs to Many

For has_and_belongs_to_many (HABTM) relationships, you may define relation ids in array format. So if Post has_and_belongs_to_many :tags, you could write:

#posts.yml

records:
  - sprig_id: 42
    title: 'All About Brains'
    content: 'Lorem ipsum...'
    tag_ids:
      - '<%= sprig_record(Tag, 1).id %>'
      - '<%= sprig_record(Tag, 2).id %>'

#tags.yml

records:
  - sprig_id: 'bio'
    name: 'Biology'
  - sprig_id: 'neuro'
    name: 'Neuroscience'

Note: For namespaced or STI classes, you'll need to include the namespace with the class name in the seed file name. For example Users::HeadManager would need to be users_head_managers.yml

Special Options

These are provided in a options: key for yaml and json files.

find_existing_by:

Rather than starting from a blank database, you can optionally choose to find existing records and update them with seed data.

The passed in attribute or array of attributes will be used for finding existing records during the sprigging process.

Example:

# posts.yml

options:
  find_existing_by: ['title', 'user_id']

Computed Values

It's common to want seed values that are dynamic. Sprig supports an ERB style syntax for computing seed attributes.

# posts.yml

records:
  - sprig_id: 1
    body: "Yaml Post body"
    published_at: "<%= 1.week.ago %>"

Custom Sources and Parsers

If all your data is in .wat files, fear not. You can tell Sprig where to look for your data, and point it toward a custom parser class for turning your data into records. The example below tells Sprig to read User seed data from a Google Spreadsheet, and parse it accordingly.

require 'open-uri'

fanciness = {
  :class  => User,
  :source => open('https://spreadsheets.google.com/feeds/list/somerandomtoken/1/public/values?alt=json'),
  :parser => Sprig::Parser::GoogleSpreadsheetJson
}

sprig [
  fanciness,
  Post,
  Comment
]

Configuration

When Sprig conventions don't suit, just add a configuration block to your seed file.

Sprig.configure do |c|
  c.directory = 'seed_files'
  c.shared_directory = 'shared'
end

Populate Seed Files from Database

Want to create Sprig seed files from the records in your database? Well, Sprig::Reap can create them for you! Check out the gem's README for installation instructions and details on usage.

License

This project rocks and uses MIT-LICENSE.

---

Visit code.viget.com to see more projects from Viget.