trucker 0.1.0 → 0.2.0

data/README.rdoc

@@ -1,16 +1,230 @@
 = Trucker
 
-Trucker is a gem for migrating legacy data into a Rails app.
+Trucker is a gem that helps migrate legacy data into a Rails app.
 
-== Note on Patches/Pull Requests
+== Installation
+
+
+1. Install the trucker gem
+
+    sudo gem install trucker
+
+2. Add trucker to your <em>config.gem</em> block in environment.rb
+  
+    config.gem "trucker"
+
+2. Generate the basic trucker files
+
+    script/generate truck
+
+    This will do the following things:
+    * Add legacy adapter to database.yml
+    * Add legacy base class
+    * Add legacy sub classes for all existing models
+    * Add app/models/legacy to load path in Rails Initializer config block
+    * Generate sample migration task (using pluralized model names)
+  
+3. Update the legacy database adapter in <em>database.yml</em> with your legacy database info
+
+    legacy:
+      adapter: mysql
+      encoding: utf8
+      database: app_legacy
+      username: root
+      password:
+      
+    (By convention, we recommend naming your legacy database APP_NAME_legacy.)
+
+4. If the legacy database doesn't already exist, add it.
+
+    rake db:create:all
+
+5. Import your legacy data into the legacy database
+   
+    mysql -u root app_legacy < old_database.sql
+
+6. Update <em>set_table_name</em> in each of your legacy models as needed
+
+    class LegacyPost < LegacyBase
+      set_table_name "LEGACY_TABLE_NAME_GOES_HERE"
+    end
+
+7. Update legacy model field mappings as needed
+
+    class LegacyPost < LegacyBase
+      set_table_name "YOUR LEGACY TABLE NAME GOES HERE"
+  
+      def map
+        {
+          :headline => self.title.squish,
+          :body => self.long_text.squish
+        }
+      end
+    end
+
+    Non-legacy model attributes on the left side.
+    Legacy model attributes on the right side.
+    (aka :new_field => legacy_field)
+    
+8. Need to tweak some data? Just add some core ruby methods or add a helper method.
+
+    class LegacyPost < LegacyBase
+      set_table_name "YOUR LEGACY TABLE NAME GOES HERE"
+
+      def map
+        {
+          :headline => self.title.squish.capitalize,
+          :body => self.long_text.squish
+        }
+      end
+    end
+
+    class LegacyPost < LegacyBase
+      set_table_name "YOUR LEGACY TABLE NAME GOES HERE"
+
+      def map
+        {
+          :headline => tweak_title(self.title.squish),
+          :body => self.long_text.squish
+        }
+      end
+      
+      def tweak_title(title)
+        title = title.capitalize
+        title = title.gsub(/teh/, "the")
+      end
+    end
+  
+9. Start migrating!
+   
+    rake db:migrate:posts
+
+
+== Migration command line options
+
+Trucker supports a few command line options when migrating records:
+
+    rake db:migrate:posts limit=100 (migrates 100 records)
+    rake db:migrate:posts limit=100 offset=100 (migrates 100 records, but skip the first 100 records)
+
+
+== Custom migration labels
+
+You can tweak the default migration output generated by Trucker by using the :label option
+
+    rake db:migrate:posts
+    => Migrating posts
+
+    rake db:migrate:posts, :label => "blog posts"
+    => Migrating blog posts
+
+
+== Custom helpers
+
+Trucker is intended for migrating data from fairly simple web apps that started life on PHP, Perl, etc. So, if you're migrating data from an enterprise system, this may not be your best choice.
+
+That said, if you need to pull off a complex migration for a model, you can use a custom helper method to override Trucker's default migrate method in your rake task.
+
+    namespace :db do
+      namespace :migrate do
+
+        ...
+    
+        desc 'Migrate pain_in_the_ass model'
+        task :pain_in_the_ass => :environment do
+          Trucker.migrate :pain_in_the_ass, :helper => pain_in_the_ass_migration
+        end 
+
+      end
+    end
+
+    def pain_in_the_ass_migration
+      # Custom code goes here
+    end
+
+Then just copy the migrate method from lib/trucker.rb and tweak accordingly.
+
+As an example, here's a custom helper used to migrate join tables on a bunch of models.
+
+    namespace :db do
+      namespace :migrate do
+
+        desc 'Migrates join tables'
+        task :joins => :environment do
+          migrate :joins, :helper => :migrate_joins  
+        end
+
+      end
+    end
+
+    def migrate_joins
+      puts "Migrating #{number_of_records || "all"} joins #{"after #{offset_for_records}" if offset_for_records}"
+
+      ["chain", "firm", "function", "style", "website"].each do |model|
+
+        # Start migration
+        puts "Migrating theaters_#{model.pluralize}"
+
+        # Delete existing joins
+        ActiveRecord::Base.connection.execute("TRUNCATE table theaters_#{model.pluralize}")
+
+        # Tweak model ids and foreign keys to match model syntax
+        if model == 'website'
+          model_id = "url_id"
+          send_foreign_key = "url_id".to_sym
+        else
+          model_id = "#{model}_id"
+          send_foreign_key = "#{model}_id".to_sym
+        end
+    
+        # Create join object class
+        join = Object.const_set("Theaters#{model.classify}", Class.new(ActiveRecord::Base))
+    
+        # Set model foreign key
+        model_foreign_key = "#{model}_id".to_sym
+    
+        # Migrate join (unless duplicate)
+        "LegacyTheater#{model.classify}".constantize.find(:all, with(:order => model_id)).each do |record|
+      
+          unless join.find(:first, :conditions => {:theater_id => record.theater_id, model_foreign_key => record.send(send_foreign_key)})
+            attributes = {
+              model_foreign_key => record.send(send_foreign_key),
+              :theater_id => record.theater_id
+            }
+        
+            # Check if theater chain is current
+            attributes[:is_current] = {'Yes' => 1, 'No' => 0, '' => 0}[record.current] if model == 'chain'
+        
+            # Migrate join
+            join.create(attributes)
+          end
+        end
+      end
+    end
+
+
+== Background
+
+Trucker is based on a migration technique using legacy models first pioneered by Dave Thomas:
+http://pragdave.blogs.pragprog.com/pragdave/2006/01/sharing_externa.html
+
+
+== Note on patches/pull requests
  
 * Fork the project.
 * Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
+* Add tests for it. This is important so we don't break a future version unintentionally.
+* Commit your changes, but do not mess with the rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself so we can ignore when we pull)
+* Send a pull request. Bonus points for topic branches.
+
+
+== Contributors
+
+* Patrick Crowley
+* Rob Kaufman
+* Jordan Fowler
+
 
 == Copyright
 

data/VERSION.yml

@@ -1,5 +1,5 @@
 --- 
-:major: 0
+:minor: 2
 :build: 
-:minor: 1
 :patch: 0
+:major: 0

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: trucker
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: false
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Patrick Crowley and Rob Kaufman
@@ -58,8 +58,6 @@ extra_rdoc_files:
 - LICENSE
 - README.rdoc
 files: 
-- BACKGROUND.markdown
-- INSTALL.markdown
 - LICENSE
 - README.rdoc
 - Rakefile

data/BACKGROUND.markdown

@@ -1,236 +0,0 @@
-Background
-==========
-
-Trucker is based on a migration technique using LegacyModels first pioneered by Dave Thomas.
-
-Sharing External ActiveRecord Connections
-http://pragdave.blogs.pragprog.com/pragdave/2006/01/sharing_externa.html
-
-Using this, I've developed a set of helpers for migrating code.
-
-- /app/models/legacy/
-- /app/models/legacy/legacy_base.rb
-- /app/models/legacy/legacy_model.rb
-- /config/database.yml
-- /config/environment.rb
-- /lib/migration_helper.rb
-- /lib/tasks/migrate.rake
-
-
-
-/app/models/legacy/
-===================
-
-This folder will contain the base Legacy model, and all subclasses.
-
-
-/app/models/legacy/legacy_base.rb
-=================================
-
-This is the base Legacy model which connects to the legacy database and handles the migration.
-
-    class LegacyBase < ActiveRecord::Base
-      self.abstract_class = true
-      establish_connection "legacy"
-  
-      def migrate
-        new_record = self.class.to_s.gsub(/Legacy/,'::').constantize.new(map)
-        new_record[:id] = self.id
-        new_record.save
-      end
-
-    end
-
-
-/app/models/legacy/legacy_model.rb
-=================================
-
-This is a sample Legacy subclass, which specifies the legacy model name and defines a map of old field names to new field names. All Legacy models are stored in /app/models/legacy to keep your main app model namespace unaffected.
-
-    class LegacyModel < LegacyBase
-      set_table_name "model"
-
-      def map
-        {
-          :make => self.car_company.squish,
-          :model => self.car_name.squish
-        }
-      end
-
-    end
-
-
-
-/config/environment.rb
-======================
-
-We need to update the app environment so we can load the legacy models correctly.
-
-    Rails::Initializer.run do |config|
-      config.load_paths += %W( #{RAILS_ROOT}/app/models/legacy )
-    end
-
-
-
-/config/database.yml
-====================
-
-We need to add a custom database adapter so that we can connect to our legacy database.
-
-By convention, I've used APPNAME_legacy for my legacy databases, but you can easily customize this.
-
-    legacy:
-      adapter: mysql
-      database: APPNAME_legacy
-      username: root
-      password:
-
-
-
-/app/models/legacy/legacy_base.rb
-=================================
-
-This model connects to our legacy database, and provides a migration method.
-
-    class LegacyBase < ActiveRecord::Base
-      self.abstract_class = true
-      establish_connection "legacy"
-  
-      def migrate
-        new_record = self.class.to_s.gsub(/Legacy/,'::').constantize.new(map)
-        new_record[:id] = self.id
-        new_record.save
-      end
-
-    end
-
-
-
-/lib/migration_helper.rb
-========================
-
-This helper is used by the rake task to manage the actual migration process.
-
-    def migrate(name, options={})
-      # Grab custom entity label if present
-      label = options.delete(:label) if options[:label]
-  
-      unless options[:helper]
-    
-        # Grab model to migrate
-        model = name.to_s.singularize.capitalize
-    
-        # Wipe out existing records
-        model.constantize.delete_all
-
-        # Status message
-        status = "Migrating "
-        status += "#{number_of_records || "all"} #{label || name}"
-        status += " after #{offset_for_records}" if offset_for_records
-    
-        # Set import counter
-        counter = 0
-        counter += offset_for_records if offset_for_records
-        total_records = "Legacy#{model}".constantize.find(:all).size
-    
-        # Start import
-        "Legacy#{model}".constantize.find(:all, with(options)).each do |record|
-          counter += 1
-          puts status + " (#{counter}/#{total_records})"
-          record.migrate
-        end
-      else
-        eval options[:helper].to_s
-      end
-    end
-
-    def with(options={})
-      {:limit => number_of_records, :offset => offset_for_records}.merge(options)
-    end
-
-    def number_of_records
-      nil || ENV['limit'].to_i if ENV['limit'].to_i > 0
-    end
-
-    def offset_for_records
-      nil || ENV['offset'].to_i if ENV['offset'].to_i > 0
-    end
-
-  Available options include offset and limit:
-
-    rake db:migrate:architects limit=1000
-    rake db:migrate:architects limit=1000 offset=2000
-    
-
-
-  /lib/tasks/migrate.rake
-  ========================
-
-  This is the basic rake task for migrating legacy data. With a sample model, just add a new migration task with the pluralized name of your existing model. For more complicated migrations, the migrate method supports a helper method which will override the default migration behavior and allow you to do a highly customized migration.
-
-    require 'migration_helper'
-
-    namespace :db do
-      namespace :migrate do
-    
-        desc 'Migrates architects'
-        task :architects => :environment do
-          migrate :architects
-        end
-    
-        desc 'Migrates theaters'
-        task :architects => :environment do
-          migrate :theaters, :helper => :migrate_theaters
-        end
-
-      end
-    end
-
-    def migrate_theaters
-
-      # Delete all theaters if delete_all=true
-      Theater.delete_all if ENV['delete_all']
-
-      # Set default conditions
-      conditions = ["status_publish = 'Yes' AND location_address1 != '' AND location_address1 IS NOT NULL"]
-
-      # Set counters to monitor migration
-      success, failure, skipped = 0, 0, 0
-
-      # Count number of theaters
-      start = Theater.count
-
-      # Migrate theaters
-      puts "\nMigrating #{number_of_records || "all"} theaters #{"after #{offset_for_records}\n\n" if offset_for_records}"
-      LegacyTheater.find(:all, with(:conditions => conditions)).each_with_index do |record, i|
-
-        # Migrate theater
-        new_record = record.migrate
-        message = "#{new_record.name} (#{record.id})"
-
-        if Theater.exists?(record.id)
-          puts "#{i+1} SKIP #{message}\n\n"
-          skipped += 1
-        elsif new_record.save
-          puts "#{i+1} PASS #{message}\n\n"
-          success += 1
-        else
-          puts "#{i+1} FAIL #{message}\n#{new_record.inspect}\n\n"
-          failure += 1
-        end
-  
-        # Archive old theater data
-        archive_old_theater_data(record)
-
-      end
-
-      # Count number of theaters
-      finish = Theater.count
-
-      # Batch stats
-      percentage = (failure.to_f / (skipped + success + failure).to_f).to_f * 100
-      puts "BATCH: #{number_of_records || "all"} theaters => #{success} passed, #{failure} failed (#{percentage.truncate}%), #{skipped} skipped (already imported)"
-
-    end
-
-

data/INSTALL.markdown

@@ -1,30 +0,0 @@
-
-Here are some imaginary install instructions.
-
-1. Install the trucker gem and add to your gem config block.
-
-2. Generate the basic trucker files
-
-    script/generate truck
-
-    - Add legacy adapter to database.yml
-    - Add legacy base class
-    - (Optionally) Add legacy sub classes for all existing models
-    - Add app/models/legacy to load path in Rails Initializer config block
-    - Generate sample migration task (using pluralized model names)
-  
-3. Update database.yml with legacy database info
-
-4. Run rake db:create:all to create the legacy database
-
-5. Import your legacy database.
-   (Make sure the legacy adapter is using the correct name.)
-
-6. Update legacy model table names as needed
-
-7. Update legacy model field mappings as needed
-
-8. Start migrating!
-   rake db:migrate:models
-
-