Description
Easily seed Rails models from sheet files. Currently supported formats are
- .csv
- .xls
- .xlsx
- .ods
- .tsv.
- .yml
Support for other formats can easily be added and contributed back here. :)
The gem supports both Mongoid and ActiveRecord.
Gem Dependency
You may need to add some additional gems to your gemfile dpending on the file types you want to load
Type | Additional gem |
---|---|
.csv | -none- |
.xls | roo-xls |
Example case
Let's say you want to seed the following models with their relations:
class Car < ActiveRecord::Base
belongs_to :parking
validates :name, :presence => true
end
class Parking < ActiveRecord::Base
has_many :cars
validates :name, :presence => true, :uniqueness => true
end
Create a db/seeds/data
folder. Add seed files in your favorite format. For instance:
db/seeds/data/cars.csv
db/seeds/data/parkings.csv
In db/seeds/seeds.rb
, simply include Superseeder
and call seed
for each of the models:
include Superseeder
seed :cars
seed :parkings
Use rake db:seed
as usual.
Writing seeds
Seeds are easy to write. For instance, for above models, your files are expected to look like:
db/seeds/data/cars.csv
name | parking_name |
---|---|
Mustang | south |
Corvette | north |
BMW | south |
db/seeds/parkings.csv
name| ----|- south| east| west| north|
# db/seeds/seeds.rb
include Superseeder
seed :parkings
seed :cars
Note that
- the seeds are ordered, parkings is seeded before car since cars need to find existing parkings to set up relations.
- the ca'rs parking relation is set with the parking's name. You can match any column of a model`s relation
by titling the column
relation_column
. Matching multiple columns to yield a single entry is also possible.
You can of course seed relations the other way around:
db/seeds/data/cars.csv
name| ----|- Mustang| Corvette| BMW|
db/seeds/parkings.csv
name | cars_name |
---|---|
south | Mustang,BMW |
east | |
west | |
north | Corvette |
# db/seeds/seeds.rb
include Superseeder
seed :cars
seed :parkings
Handling things yourself
If you want to apply special logic for a seed, just pass a block to seed:
seed :cars do |row|
#Do it your way
end
each row of the seed file will be passed as a hash.
Seeding from models
You can allow a model to seed itself:
model Car
extend Superseeder::Seedable
end
Car.seed
Single Table Inheritance
You can seed a model and its inherited models from a single file provided you add a '_type' column containing the subclass name.
model Car
end
model RentedCar < Car
end
name | _type |
---|---|
Mustang | |
Corvette | RentedCar |
BMW |
will seed
Car.new :name => 'Mustang'
RentedCar.new :name => 'Corvette'
Car.new :name => 'BMW'
Options
seed
takes a number of options:
-
:filename
to specify a file name not matching a model name
seed :cars, :filename => 'last_dump.csv'
-
:many_sep
to specify the separator in array relations
name | cars_name |
---|---|
south | Mustang@BMW |
east | |
west | |
north | Corvette |
seed :parkings, :many_sep => '@'
-
:update_by
to update records instead of creating them
seed :parkings, :update_by => :name
That will find each record by its name and update all its attributes if they differ from the seed file. This option allows you to modify a seed file and update your database without having to worry about your seed models changing id for instance. In order to find the single record to update, you can match several columns
seed :parkings, :update_by => [:name, :color]
or you can pass a Proc that will take as argument the class of the instance to create and the row as an array.
seed :parkings, :update_by => ->(instance_class, row){ instance_class.find_by :name => row[0] }
- Roo options.
You can pass any option supported by the Roo gem (https://github.com/roo-rb/roo) to read files, such as encoding, CSV column separator, etc.
seed :parkings, csv_options: { col_sep: ';' } # default is ','
Check their documentation for more information.
Configuration
If you're having a difficult time understanding why some of your models won't be seeded, you can turn the verbose mode on before calling seed:
# db/seeds.rb
include Superseeder
Superseeder.verbose!
seed :cars
Contributing / Seed formats
I appreciate any help to make this gem more robust and flexible.
If you want to add support for other formats, here's how to do it:
Add a module in the superseeder format namespace that look like:
# my_format.rb
module Superseeder
module Formats
module MyFormat
def self.extensions
# list of supported extensions, ex: %w(.mft .x4t)
end
def __process(path, *args)
# Add code for parsing your format.
end
end
end
end
LICENSE
(The MIT License)
Copyright © 2014 Olivier Milla
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.