Relational seeding for Rails apps
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
gemfiles Move testing to RSpec3 Jun 17, 2016
lib Remove hack from Sprig configuration Mar 5, 2017
spec Prepare tests for sprig_shared functionality Oct 29, 2016
.coveralls.yml Add Simplecov and Coveralls Jun 25, 2014
.gitignore Isolate ActiveRecord dependencies and add Mongoid support. Mar 20, 2015
.travis.yml Add Ruby 2.3.1 Travis CI matrix Jun 20, 2016
Appraisals Move testing to RSpec3 Jun 17, 2016
Gemfile Remove rails engine, bootstrap specs Dec 18, 2013
Gemfile.lock Move testing to RSpec3 Jun 17, 2016
MIT-LICENSE update styling and readability of readme Jan 11, 2018
Rakefile Remove rails engine, bootstrap specs Dec 18, 2013
sprig.gemspec Move testing to RSpec3 Jun 17, 2016


Code Climate Coverage Status Build Status Gem Version

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


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.


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 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.


# users.yml

  - 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

      "title":"Json title",
      "content":"Json content"
      "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.


Create relationships between seed records with the sprig_record helper:

# comments.yml

  - 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:


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

  - 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.


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.


# posts.yml

  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

  - 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(''),
  :parser => Sprig::Parser::GoogleSpreadsheetJson

sprig [


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

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

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.


This project rocks and uses MIT-LICENSE.

Code At Viget

Visit to see more projects from Viget.