Documentation

Everything you need to know to sprig.

  1. Installation
  2. Seed Directory Setup
  3. The Sprig Directive
  4. Seed Data Files
  5. Dynamic Seed Data Values
  6. Seed Data Relationships
  7. Sprig IDs

Installation

Add sprig to your Gemfile:


gem 'sprig', '~> 0.1'

Currently sprig can only be used with Rails and ActiveRecord.

Seed Directory Setup

To maintain maximum flexibility, sprig plugs into (instead of overriding) the standard Rails seeding system. When you run rake db:seed, Rails simply executes the contents of /db/seeds.rb. Environment specificity can easily be added to this system via the following recommended configuration:

db/
  seeds.rb
  seeds/
    development.rb
    development/
      users.yml
      your_other_models.yml
    production.rb
    production/
      posts.json
      your_other_models.yml

db/seeds.rb


path = Rails.root.join('db', 'seeds', "#{Rails.env}.rb")
load path if File.exist?(path)

db/seeds/development.rb


# This will be run during `rake db:seed` in the :development environment.

include Sprig::Helpers

sprig [User]

db/seeds/production.rb


# This will be run during `rake db:seed` in the :production environment.

include Sprig::Helpers

sprig [Post]

db/seeds/development/

Put your :development environment seed data files in this directory. See the users.yml example seed data file below.

db/seeds/development/users.yml


records:
  - sprig_id:   lawdawg
    first_name: Lawson
    last_name:  Kurtz
    username:   lawdawg
  - sprig_id:   mc_rubs
    first_name: Ryan
    last_name:  Foster
    username:   mc_rubs

db/seeds/production/

Put your :production environment seed data files in this directory. See the posts.json example seed data file below.

db/seeds/production/posts.json


{
  "records": [
    {
      "sprig_id": 1,
      "title": "Intro to Sprig",
      "content": "We created sprig in response to..."
    },
    {
      "sprig_id": 2,
      "title": "Diving into Sprig",
      "content": "Getting started with sprig is easy..."
    }
  ]
}

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.

db/seeds/development.rb


include Sprig::Helpers

sprig [User, Post, Comment]

This directive tells Sprig to go find your seed data files 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 (in this case, within db/seeds/development/).

Seed Data Files

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

db/seeds/development/users.yml


records:
  - sprig_id: 1
    first_name: 'Lawson'
    last_name: 'Kurtz'
    username: 'lawdawg'
  - sprig_id: 2
    first_name: 'Ryan'
    last_name: 'Foster'
    username: 'mc_rubs'

db/seeds/development/posts.json


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

Or use a CSV with a header row defining your attribute names.

db/seeds/development/users.csv


first_name,last_name,age,favorite_color
Jane,Doe,25,blue
John,Smith,34,green

Dynamic Seed Data Values

Use ERB syntax within your seed data files to seed records with dynamic values.

db/seeds/development/timesheet_entries.yml


records:
  - sprig_id: 1
    start_time: <%= 12.hours.ago %>
    end_time: <%= 11.hours.ago %>
  - sprig_id: 2
    start_time: <%= 30.minutes.ago %>
    end_time: <%= 1.minute.ago %>

Seed Data Relationships

The sprig_record Helper Method

The sprig_record helper method gives you access to your other seed data records after they are persisted, allowing you to easily create relationships between your records. The return is the seed record's real-life ActiveRecord object with all corresponding attributes and methods.

sprig_record takes two arguments:

1) The class of the desired record.

2) The sprig ID of the desired record. Read more about sprig IDs in the following section.

db/seeds/development/comments.yml


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

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

Sprig IDs

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.