0.2 release, with docs & tests

README

@@ -1 +1,57 @@
-TBD
+db_populate
+===========
+db_populate is an answer to the question "how do I get seed data into a Rails application?" 
+Seed data is normally the contents of lookup tables that are essential to the normal
+functioning of your application: lists of roles, administrative accounts, choices for
+dropdown boxes, and so on.
+
+The inspiration (and some of the code) for this plugin come from a blog entry by Luke
+Francl (http://railspikes.com/2008/2/1/loading-seed-data) that looked at some of the
+available alternatives for loading seed data. Some more of the code came from Josh
+Knowles' db_populate plugin (http://code.google.com/p/db-populate/). But I didn't like 
+having to assemble bits, and had some ideas to extend it, and...well, you know how it
+goes.
+
+Using db_populate
+=================
+The basic idea behind db_populate is simple: to put seed data in your application's
+tables, it executes ruby code. The code needs to be in a specific place, and there's a 
+helper to make it easier to create and update consistent seed data. Then there are a
+couple of rake tasks. That's it.
+
+Setting up for db_populate
+==========================
+
+To get started with db_populate, create the folder db/populate in your Rails application.
+Any code you put in this folder will be run by db_populate. Optionally, you can create
+subfolders for your Rails environments, just as you can with config files. db_populate
+executes all of the top-level populate files first, followed by any environment-specific
+populate files, sorting each list by name. So, for example, with 4 files in the production
+environment, db_populate would order this way:
+
+db/populate/01_roles.rb
+db/populate/02_services.rb
+db/populate/production/01_users.rb
+db/populate/production/02_options.rb
+
+Within each file, you can place whatever ruby code you like. To help create consistent
+records, db_populate adds create_or_populate to ActiveRecord::Base. This method looks up
+a record by ID; if the record exists, it is updated, and if it doesn't, it is created. Using
+this technique means that you can edit and re-run your db_populate tasks without damaging 
+data that have already been loaded once. For example, assuming your roles table has already
+been populated, a db_populate file to create an administrative user might look like this:
+
+user = User.create_or_update(:id => 1, :login => "admin", :email => "admin@example.com", 
+ :name => "Site Administrator", :password => "admin", :password_confirmation => "admin")
+role = Role.find_by_rolename('administrator')
+Permission.create_or_update(:id => 1, :role_id => role.id, :user_id => user.id)
+
+If you change your mind about the name for the site administrator, you can just edit the data
+and re-run the task.
+
+db_populate rake tasks
+======================
+db_populate includes two rake tasks:
+
+rake db:populate loads all of the data for the current environment
+rake db:migrate_and_populate is the same as calling rake db:migrate followed by rake db:populate

db_populate.gemspec

@@ -1,14 +1,14 @@
 Gem::Specification.new do |s|
   s.name     = "db_populate"
-  s.version  = "0.1.0"
-  s.date     = "2008-09-15"
+  s.version  = "0.2.0"
+  s.date     = "2008-10-11"
   s.summary  = "Seed data populator for Rails"
   s.email    = "MikeG1@larkfarm.com"
   s.homepage = "http://github.com/ffmike/db_populate"
   s.description = "db_populate provides rake and code support for adding seed data to Rails projects. Forked from a rake task by
-  Josh Knowles, plus code by Luke Franci."
+  Josh Knowles, plus code by Luke Francl."
   s.has_rdoc = false
-  s.authors  = ["Mike Gunderloy", "Josh Knowles", "Luke Franci"]
+  s.authors  = ["Mike Gunderloy", "Josh Knowles", "Luke Francl"]
   s.files    = [
     "MIT-LICENSE",
     "README",

tasks/populate.rake

@@ -14,6 +14,8 @@ namespace :db do
   end
   
   desc "Runs migrations and then loads seed data"
+  task :migrate_and_populate => [ 'db:migrate', 'db:populate' ]
+
   task :migrate_and_load => [ 'db:migrate', 'db:populate' ]
   
 end

test/db_populate_test.rb

@@ -3,6 +3,27 @@ require 'test/unit'
 require 'rubygems'
 require 'mocha'
 
-class UserEventLoggerTest < Test::Unit::TestCase
+class User < ActiveRecord::Base
+end
+
+class DbPopulateTest < Test::Unit::TestCase
+  
+  def test_creates_new_record
+    User.delete_all
+    User.create_or_update(:id => 1, :name => "Fred")
+    assert_equal User.count, 1
+    u = User.find(:first)
+    assert_equal u.name, "Fred"
+  end
+  
+  def test_updates_existing_record
+    User.delete_all
+    User.create_or_update(:id => 1, :name => "Fred")
+    User.create_or_update(:id => 1, :name => "George")
+    assert_equal User.count, 1
+    u = User.find(:first)
+    assert_equal u.name, "George"
+  end
+  
 end
 

test/test_helper.rb

@@ -1,11 +1,12 @@
 ENV['RAILS_ENV'] = 'test'
-ENV['RAILS_ROOT'] ||= File.dirname(__FILE__) + '/../../../..'
 
+require 'rubygems'
 require 'test/unit'
-require File.expand_path(File.join(ENV['RAILS_ROOT'], 'config/environment.rb'))
+require 'action_controller'
+require 'active_record'
+require 'action_view'
 
 config = YAML::load(IO.read(File.dirname(__FILE__) + '/database.yml'))
-ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + "/debug.log")
 
 db_adapter = ENV['DB']
 
@@ -31,4 +32,3 @@ ActiveRecord::Base.establish_connection(config[db_adapter])
 load(File.dirname(__FILE__) + "/schema.rb")
 
 require File.dirname(__FILE__) + '/../init.rb'
-