seed-fu 1.2.1

data/README.rdoc

@@ -0,0 +1,149 @@
+= Seed Fu
+
+Seed Fu is an attempt to once and for all solve the problem of inserting and
+maintaining seed data in a database. It uses a variety of techniques gathered
+from various places around the web and combines them to create what is 
+hopefully the most robust seed data system around.
+
+
+== Simple Usage
+
+Seed data is taken from the <tt>db/fixtures</tt> directory. Simply make descriptive .rb
+files in that directory (they can be named anything, but users.rb for the User
+model seed data makes sense, etc.). These scripts will be run whenever the
+db:seed rake task is called, and in order (you can use <tt>00_first.rb</tt>,
+<tt>00_second.rb</tt>, etc). You can put arbitrary Ruby code in these files,
+but remember that it will be executed every time the rake task is called, so
+it needs to be runnable multiple times on the same database.
+
+You can also have environment-specific seed data placed in 
+<tt>db/fixtures/ENVIRONMENT</tt> that will only be loaded if that is the current
+environment.
+
+Let's say we want to populate a few default users. In <tt>db/fixtures/users.rb</tt> we
+write the following code:
+
+    User.seed(:login, :email) do |s|
+      s.login = "bob"
+      s.email = "bob@bobson.com"
+      s.first_name = "Bob"
+      s.last_name = "Bobson"
+    end
+    
+    User.seed(:login, :email) do |s|
+      s.login = "bob"
+      s.email = "bob@stevenson.com"
+      s.first_name = "Bob"
+      s.last_name = "Stevenson"
+    end
+
+That's all you have to do! You will now have two users created in the system
+and you can change their first and last names in the users.rb file and it will
+be updated as such.
+
+The arguments passed to the <tt><ActiveRecord>.seed</tt> method are the constraining
+attributes: these must remain unchanged between db:seed calls to avoid data
+duplication. By default, seed data will constrain to the id like so:
+
+    Category.seed do |s|
+      s.id = 1
+      s.name = "Buttons"
+    end
+    
+    Category.seed do |s|
+      s.id = 2
+      s.name = "Bobbins"
+      s.parent_id = 1
+    end
+    
+Note that any constraints that are passed in must be present in the subsequent
+seed data setting.
+
+== Seed-many Usage
+
+The default <tt>.seed` syntax is very verbose.  An alternative is the `.seed_many</tt> syntax.
+Look at this refactoring of the first seed usage example above:
+
+    User.seed_many(:login, :email, [
+      { :login => "bob", :email => "bob@bobson.com",    :first_name => "Bob", :last_name = "Bobson" },
+      { :login => "bob", :email => "bob@stevenson.com", :first_name => "Bob", :last_name = "Stevenson" }
+    ])
+
+Not as pretty, but much more concise.
+
+== Handling Large SeedFu Files
+
+Seed files can be huge.  To handle large files (over a million rows), try these tricks:
+
+* Gzip your fixtures.  Seed Fu will read .rb.gz files happily.  <tt>gzip -9</tt> gives the
+  best compression, and with Seed Fu's repetitive syntax, a 160M file can shrink to 16M.
+* Add lines reading <tt># BREAK EVAL</tt> in your big fixtures, and Seed Fu will avoid loading
+  the whole file into memory.  If you use SeedFu::Writer, these breaks are built into
+  your generated fixtures.
+* Load a single fixture with the <tt>SEED</tt> environment varialble:
+  <tt>SEED=cities,states rake db:seed > seed_log`.  Each argument to `SEED</tt> is used as a
+  regex to filter fixtures by filename.
+
+== Generating SeedFu Files
+
+Say you have a CSV you need to massage and store as seed files.  You can create
+an import script using SeedFu::Writer.
+
+    #!/usr/bin/env ruby
+    #
+    # This is: script/generate_cities_seed_from_csv
+    #
+    require 'rubygems'
+    require 'fastercsv'
+    require File.join( File.dirname(__FILE__), '..', 'vendor/plugins/seed-fu/lib/seed-fu/writer' )
+
+    # Maybe SEEF_FILE could be $stdout, hm.
+    #
+    CITY_CSV  = File.join( File.dirname(__FILE__), '..', 'city.csv' )
+    SEED_FILE = File.join( File.dirname(__FILE__), '..', 'db', 'fixtures', 'cities.rb' )
+
+    # Create a seed_writer, walk the CSV, add to the file.
+    #
+
+    seed_writer = SeedFu::Writer::SeedMany.new(
+      :seed_file  => SEED_FILE,
+      :seed_model => 'City',
+      :seed_by    => [ :city, :state ]
+    )
+
+    FasterCSV.foreach( CITY_CSV,
+      :return_headers => false,
+      :headers => :first_row
+    ) do |row|
+
+      # Skip all but the US
+      #
+      next unless row['country_code'] == 'US'
+
+      unless us_state
+        puts "No State Match for #{row['region_name']}"
+        next
+      end
+
+      # Write the seed
+      #
+      seed_writer.add_seed({
+        :zip => row['zipcode'],
+        :state => row['state'],
+        :city => row['city'],
+        :latitude => row['latitude'],
+        :longitude => row['longitude']
+      })
+
+    end
+
+    seed_writer.finish
+
+There is also a SeedFu::Writer::Seed in case you prefere the seed()
+syntax over the seen_many() syntax.  Easy-peasy.
+
+== Contributors
+
+* Thanks to Matthew Beale for his great work in adding the writer, making it faster and better.
+
+Copyright (c) 2008-2009 Michael Bleigh released under the MIT license

data/Rakefile

@@ -0,0 +1,23 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "seed-fu"
+    gemspec.summary = "Allows easier database seeding of tables in Rails."
+    gemspec.email = "michael@intridea.com"
+    gemspec.homepage = "http://github.com/mblegih/seed-fu"
+    gemspec.description = "Seed Fu is an attempt to once and for all solve the problem of inserting and maintaining seed data in a database. It uses a variety of techniques gathered from various places around the web and combines them to create what is hopefully the most robust seed data system around."
+    gemspec.authors = ["Michael Bleigh"]
+    gemspec.add_dependency 'rails', '>= 2.1'
+    gemspec.files = FileList["[A-Z]*", "{lib,spec,rails}/**/*"] - FileList["**/*.log"]
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+
+desc 'Default: run specs.'
+task :default => :spec

data/VERSION

@@ -0,0 +1 @@
+1.2.1

data/lib/seed-fu.rb

@@ -0,0 +1,87 @@
+module SeedFu
+  class Seeder
+    def self.plant(model_class, *constraints, &block)
+      constraints = [:id] if constraints.empty?
+      seed = Seeder.new(model_class)
+      insert_only = constraints.last.is_a? TrueClass
+      constraints.delete_at(*constraints.length-1) if (constraints.last.is_a? TrueClass or constraints.last.is_a? FalseClass)
+      seed.set_constraints(*constraints)
+      yield seed
+      seed.plant!(insert_only)
+    end
+
+    def initialize(model_class)
+      @model_class = model_class
+      @constraints = [:id]
+      @data = {}
+    end
+
+    def set_constraints(*constraints)
+      raise "You must set at least one constraint." if constraints.empty?
+      @constraints = []
+      constraints.each do |constraint|
+        raise "Your constraint `#{constraint}` is not a column in #{@model_class}. Valid columns are `#{@model_class.column_names.join("`, `")}`." unless @model_class.column_names.include?(constraint.to_s)
+        @constraints << constraint.to_sym
+      end
+    end
+
+    def plant! insert_only=false
+      record = get
+      return if !record.new_record? and insert_only
+      @data.each do |k, v|
+        record.send("#{k}=", v)
+      end
+      raise "Error Saving: #{record.inspect}" unless record.save(false)
+      puts " - #{@model_class} #{condition_hash.inspect}"      
+      record
+    end
+
+    def method_missing(method_name, *args) #:nodoc:
+      if args.size == 1 and (match = method_name.to_s.match(/(.*)=$/))
+        self.class.class_eval "def #{method_name} arg; @data[:#{match[1]}] = arg; end"
+        send(method_name, args[0])
+      else
+        super
+      end
+    end
+
+    protected
+
+    def get
+      records = @model_class.find(:all, :conditions => condition_hash)
+      raise "Given constraints yielded multiple records." unless records.size < 2
+      if records.any?
+        return records.first
+      else
+        return @model_class.new
+      end
+    end
+
+    def condition_hash
+      @constraints.inject({}) {|a,c| a[c] = @data[c]; a }
+    end
+  end
+end
+
+
+class ActiveRecord::Base
+  # Creates a single record of seed data for use
+  # with the db:seed rake task. 
+  # 
+  # === Parameters
+  # constraints :: Immutable reference attributes. Defaults to :id
+  def self.seed(*constraints, &block)
+    SeedFu::Seeder.plant(self, *constraints, &block)
+  end
+
+  def self.seed_many(*constraints)
+    seeds = constraints.pop
+    seeds.each do |seed_data|
+      seed(*constraints) do |s|
+        seed_data.each_pair do |k,v|
+          s.send "#{k}=", v
+        end
+      end
+    end
+  end
+end

data/lib/seed-fu/writer.rb

@@ -0,0 +1,3 @@
+require File.join( File.dirname(__FILE__), 'writer', 'abstract' )
+require File.join( File.dirname(__FILE__), 'writer', 'seed' )
+require File.join( File.dirname(__FILE__), 'writer', 'seed_many' )

data/lib/seed-fu/writer/abstract.rb

@@ -0,0 +1,58 @@
+module SeedFu
+  
+  module Writer
+
+    class Abstract
+      attr_accessor :seed_handle, :config, :number_of_seeds
+
+      def initialize(options={})
+        self.config = options
+        self.number_of_seeds = 0
+
+        self.seed_handle = File.new(self.config[:seed_file], 'w')
+
+        write_header
+      end
+      
+      def header
+        <<-END
+# DO NOT MODIFY THIS FILE, it was auto-generated.
+# 
+# Date: #{DateTime.now}
+# Using #{self.class} to seed #{config[:seed_model]}
+# Written with the command:
+#
+#   #{$0} #{$*.join}
+#
+        END
+      end
+
+      def footer
+        <<-END
+# End auto-generated file.
+        END
+      end
+
+      def add_seed(hash)
+        $stdout.puts "Added #{hash.inspect}" unless config[:quiet]
+        self.number_of_seeds += 1
+      end
+
+      def write_header
+        seed_handle.syswrite header
+      end
+
+      def write_footer
+        seed_handle.syswrite footer
+      end
+
+      def finish
+        write_footer
+        seed_handle.close
+      end
+
+    end
+  
+  end
+
+end

data/lib/seed-fu/writer/seed.rb

@@ -0,0 +1,26 @@
+module SeedFu
+  
+  module Writer
+
+    class Seed < Abstract
+
+      # This method uses the :seed_by set earlier.
+      #
+      def add_seed(hash, seed_by=nil)
+        seed_by ||= config[:seed_by]
+        seed_handle.syswrite( <<-END
+#{config[:seed_model]}.seed(#{seed_by.collect{|s| ":#{s}"}.join(',')}) { |s|
+#{hash.collect{|k,v| "  s.#{k} = '#{v.to_s.gsub("'", "\'")}'\n"}.join}}
+        END
+        )
+        super(hash)
+        if chunk_this_seed?
+          seed_handle.syswrite "# BREAK EVAL\n"
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/seed-fu/writer/seed_many.rb

@@ -0,0 +1,52 @@
+module SeedFu
+  
+  module Writer
+
+    class SeedMany < Abstract
+
+      def seed_many_header
+        "#{config[:seed_model]}.seed_many(#{config[:seed_by].collect{|s| ":#{s}"}.join(',')},["
+      end
+      
+      def seed_many_footer
+        "\n])\n"
+      end
+
+      # Chunk in groups of 100 for performance
+      #
+      def chunk_this_seed?
+        0 == (self.number_of_seeds % (config[:chunk_size] || 100))
+      end
+
+      def add_seed(hash)
+        seed_handle.syswrite( (<<-END
+#{',' unless self.number_of_seeds == 0 or chunk_this_seed?}
+  { #{hash.collect{|k,v| ":#{k} => '#{v.to_s.gsub("'", "\'")}'"}.join(', ')} }
+        END
+        ).chomp )
+        super(hash)
+
+        if chunk_this_seed?
+          seed_handle.syswrite(
+            self.seed_many_footer +
+            "# BREAK EVAL\n" +
+            self.seed_many_header
+          )
+        end
+      end
+
+      def write_header
+        super
+        seed_handle.syswrite self.seed_many_header
+      end
+
+      def write_footer
+        seed_handle.syswrite self.seed_many_footer
+        super
+      end
+
+    end
+
+  end
+
+end

data/rails/init.rb

@@ -0,0 +1 @@
+require 'seed-fu'

data/spec/schema.rb

@@ -0,0 +1,8 @@
+ActiveRecord::Schema.define :version => 0 do
+  create_table :seeded_models, :force => true do |t|
+    t.column :login, :string
+    t.column :first_name, :string
+    t.column :last_name, :string
+    t.column :title, :string
+  end
+end

data/spec/seed_fu_spec.rb

@@ -0,0 +1,73 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+load(File.dirname(__FILE__) + '/schema.rb')
+
+describe SeedFu::Seeder do
+  it "should create a model if one doesn't exist" do
+    SeededModel.seed(:id) do |s|
+      s.id = 1
+      s.login = "bob"
+      s.first_name = "Bob"
+      s.last_name = "Bobson"
+      s.title = "Peon"
+    end
+    
+    bob = SeededModel.find_by_id(1)
+    bob.first_name.should == "Bob"
+    bob.last_name.should == "Bobson"
+  end
+  
+  it "should be able to handle multiple constraints" do
+    SeededModel.seed(:title, :login) do |s|
+      s.login = "bob"
+      s.title = "Peon"
+      s.first_name = "Bob"
+    end
+    
+    SeededModel.count.should == 1
+    
+    SeededModel.seed(:title, :login) do |s|
+      s.login = "frank"
+      s.title = "Peon"
+      s.first_name = "Frank"
+    end
+    
+    SeededModel.count.should == 2
+    
+    SeededModel.find_by_login("bob").first_name.should == "Bob"
+    SeededModel.seed(:title, :login) do |s|
+      s.login = "bob"
+      s.title = "Peon"
+      s.first_name = "Steve"
+    end
+    SeededModel.find_by_login("bob").first_name.should == "Steve"
+  end
+  
+  it "should be able to create models from an array of seed attributes" do
+    SeededModel.seed_many(:title, :login, [
+      {:login => "bob", :title => "Peon", :first_name => "Steve"},
+      {:login => "frank", :title => "Peasant", :first_name => "Francis"},
+      {:login => "harry", :title => "Noble", :first_name => "Harry"}
+    ])
+    
+    SeededModel.find_by_login("bob").first_name.should == "Steve"
+    SeededModel.find_by_login("frank").first_name.should == "Francis"
+    SeededModel.find_by_login("harry").first_name.should == "Harry"
+  end
+  
+  #it "should raise an error if constraints are not unique" do
+  #  SeededModel.create(:login => "bob", :first_name => "Bob", :title => "Peon")
+  #  SeededModel.create(:login => "bob", :first_name => "Robert", :title => "Manager")
+  #  
+  #  SeededModel.seed(:login) do |s|
+  #    s.login = "bob"
+  #    s.title = "Overlord"
+  #  end
+  #end
+  
+  it "should default to an id constraint"
+  it "should update, not create, if constraints are met"
+  it "should require that all constraints are defined"
+  it "should raise an error if validation fails"
+  it "should retain fields that aren't specifically altered in the seeding"
+end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+require File.dirname(__FILE__) + '/../../../../spec/spec_helper'
+
+plugin_spec_dir = File.dirname(__FILE__)
+ActiveRecord::Base.logger = Logger.new(plugin_spec_dir + "/debug.log")
+
+class SeededModel < ActiveRecord::Base
+  validates_presence_of :title
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification 
+name: seed-fu
+version: !ruby/object:Gem::Version 
+  version: 1.2.1
+platform: ruby
+authors: 
+- Michael Bleigh
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-09-23 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rails
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "2.1"
+    version: 
+description: Seed Fu is an attempt to once and for all solve the problem of inserting and maintaining seed data in a database. It uses a variety of techniques gathered from various places around the web and combines them to create what is hopefully the most robust seed data system around.
+email: michael@intridea.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/seed-fu.rb
+- lib/seed-fu/writer.rb
+- lib/seed-fu/writer/abstract.rb
+- lib/seed-fu/writer/seed.rb
+- lib/seed-fu/writer/seed_many.rb
+- rails/init.rb
+- spec/schema.rb
+- spec/seed_fu_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/mblegih/seed-fu
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Allows easier database seeding of tables in Rails.
+test_files: 
+- spec/schema.rb
+- spec/seed_fu_spec.rb
+- spec/spec_helper.rb