🌷 Nitrogen 0.0.1 Draft Spec

Warning: This library is a Draft Specification. Not for Production use.

Nitrogen provides a simple and robust system for seeding your application.

Features

Easy to Use

Comes with an installation task and hooks into your generators to start seeding out of the box.

❤️'s Ruby

Embraces a powerful configuration language you already know: Ruby. No more fiddling with XML, YAML, HAML, or ALABAML. Ok, we made up ALABAML...

Clean

Nitrogen makes your config/seed.rb clean and easy to understand. It also provides a canonical folder and file structure that is easy to digest.

Free Development Data

Fertilizers provide a structured and simple way to generate fake data for use in development. This is a much faster and better way to bootstrap an application rather than passing around production dumps.

Getting Started

Add Nitrogen to your Gemfile:

gem 'nitrogen'

Run bundle to install it.

After installing Nitrogen, run the following generator to get started.

rails generate nitrogen:install

This will set up the application's seed file along with a folder structure for your Fertilizers.

Defining Seed Order

Nitrogen provides a sprout helper to use in your config/seeds.rbfile. Use this to configure the models you would like to seed and in which order. You can seed a model with the following.

# config/seeds.rb
Nitrogen::Seeds.plant do
  sprout :users
  sprout :posts
end

You can also specify which models depend on the existance of other models when defining your seeds.

Dependency support
Factory support

# config/seeds.rb
Nitrogen::Seeds.plant do
  sprout :users do
    sprout :comments
    sprout :blog_posts do
      sprout :related_posts
    end
  end
  
  sprout :countries
end

Defining Your Seeds

Nitrogen will use the name of the sprouts defined in the seeds.rb above to find a Fertilizer with the same name.

Use a Fertilizer to define what data will be seeded and for which environments. Some data may need to be available in your application all the time, while other data might only be used in certain environments. You can configure this in your model's Fertilizer like so:

# config/seeds/fertilizers/user_fertilizer.rb
class UserFertilizer < Nitrogen::Fertilizer

  all_environments do
    create(first_name: 'Jonny', last_name: 'Smith', email: 'jsmith@gmail.com')
    create(first_name: 'Sally', last_name: 'Jones', email: 'sjones@gmail.com')
  end

  environment :development, :test do
    create(first_name: 'Admin', last_name: 'Test', admin: true)
  end

end

Set a flag to determine which fields to find records by so duplicate seeds are not created. Expire existing seeds to ensure they are no longer present. Expired seeds are found and destroyed by the attributes provided.

# config/seeds/fertilizers/user_fertilizer.rb
class UserFertilizer < Nitrogen::Fertilizer
  unique_by :email

  all_environments do
    create(first_name: 'Jonny', last_name: 'Smith', email: 'jsmith@gmail.com')
    expire(first_name: 'Sally', last_name: 'Jones', email: 'sjones@gmail.com')
    expire(first_name: 'Sammy', last_name: 'Lopez', email: 'slopez@gmail.com')
  end

end

Seeding Fake Development Data

You can use Fertilizers to generate fake data with the factory_for helper. Nitrogen uses FactoryGirl behind the scenes to generate fake data. Nitrogen also provides access to Forgery to create fake data.

Provide the factory_for helper the number of records to create with a list of environments you would like the factory to apply to.

# config/seeds/fertilizers/user_fertilizer.rb
class UserFertilizer < Nitrogen::Fertilizer

  all_environments do
    # Seed Production and Other Data
  end

  factory_for 200, :development, :test do
    first_name { Forgery(:person).first_name }
    last_name { Forgery(:person).last_name }
    email { Forgery(:person).email }
  end

end

You can customize fake data by defining your own forgeries. Custom forgeries are automatically assigned to the model's corresponding attribute based on name.

# config/seeds/fertilizers/user_fertilizer.rb
class UserFertilizer < Nitrogen::Fertilizer

  factory_for :development do
    # Declare other attributes...
    spy_alias
  end

  forgery_for :spy_alias do
    dictionaries[:spy_aliases].random
  end

end

You can randomize the number of records that are created by supplying a volume option in your seed manifest. This can be useful for randomizing the number of associated child records in a given relationship. In the following example, a given User will have up to 4 Post records associated with it. If no volume is specified, the default behavior is to create one dependent model per parent model.

# config/seeds.rb
sprout :users do
  sprout :posts, volume: 1..4
end

In addition to volume, you can also supply a frequency option to specify the chance that any records will be created for an associated model. This may be useful for realistically representing the volume of dependent models in your data. Frequency can be supplied as a decimal proportion or a static integer interval. In the following example, a given Post would have a 60% chance to have an associated Comment. Posts that have any Comments at all are usually interesting, and therefore prone to having anywhere from 10 to 50 Comments. Every 10 Posts will make it into a Publication.

# config/seeds.rb
sprout :posts do
  sprout :comments, frequency: 0.5, volume: 10..50
  sprout :publication, frequency: 10
end

You can also explicitly set the Fertilizer to be used by supplying a fertilizer option.

sprout :reviews, fertilizer: :posts

rails generate hooks are also provided for the model, and scaffold generators. A rails generate seed command is also provided to bootstrap a new seed.

Unresolved Items

Defining Nitrogen's Fertilizer API for record creation

joseph-ravenwolfe/nitrogen