== Migrations ==

If your plugin requires changes to the app's database you will likely want to somehow add migrations.  Rails does not include any built-in support for calling migrations from plugins, but you can still make it easy for developers to call migrations from plugins.

If you have a very simple needs, like creating a table that will always have the same name and columns, then you can use a more simple solution, like creating a custom rake task or method.  If your migration needs user input to supply table names or other options, you probably want to opt for generating a migration.

Let's say you have the following migration in your plugin:

*vendor/plugins/yaffle/lib/db/migrate/20081116181115_create_birdhouses.rb:*

[source, ruby]
----------------------------------------------
class CreateBirdhouses < ActiveRecord::Migration
  def self.up
    create_table :birdhouses, :force => true do |t|
      t.string :name
      t.timestamps
    end
  end

  def self.down
    drop_table :birdhouses
  end
end
----------------------------------------------

Here are a few possibilities for how to allow developers to use your plugin migrations:

=== Create a custom rake task ===

*vendor/plugins/yaffle/lib/db/migrate/20081116181115_create_birdhouses.rb:*

[source, ruby]
----------------------------------------------
class CreateBirdhouses < ActiveRecord::Migration
  def self.up
    create_table :birdhouses, :force => true do |t|
      t.string :name
      t.timestamps
    end
  end

  def self.down
    drop_table :birdhouses
  end
end
----------------------------------------------


*vendor/plugins/yaffle/tasks/yaffle.rake:*

[source, ruby]
----------------------------------------------
namespace :db do
  namespace :migrate do
    desc "Migrate the database through scripts in vendor/plugins/yaffle/lib/db/migrate and update db/schema.rb by invoking db:schema:dump. Target specific version with VERSION=x. Turn off output with VERBOSE=false."
    task :yaffle => :environment do
      ActiveRecord::Migration.verbose = ENV["VERBOSE"] ? ENV["VERBOSE"] == "true" : true
      ActiveRecord::Migrator.migrate("vendor/plugins/yaffle/lib/db/migrate/", ENV["VERSION"] ? ENV["VERSION"].to_i : nil)
      Rake::Task["db:schema:dump"].invoke if ActiveRecord::Base.schema_format == :ruby
    end
  end
end
----------------------------------------------

=== Call migrations directly ===

*vendor/plugins/yaffle/lib/yaffle.rb:*

[source, ruby]
----------------------------------------------
Dir.glob(File.join(File.dirname(__FILE__), "db", "migrate", "*")).each do |file|
  require file
end
----------------------------------------------

*db/migrate/20081116181115_create_birdhouses.rb:*

[source, ruby]
----------------------------------------------
class CreateBirdhouses < ActiveRecord::Migration
  def self.up
    Yaffle::CreateBirdhouses.up
  end

  def self.down
    Yaffle::CreateBirdhouses.down
  end
end
----------------------------------------------

.Editor's note:
NOTE: several plugin frameworks such as Desert and Engines provide more advanced plugin functionality.

=== Generate migrations ===

Generating migrations has several advantages over other methods.  Namely, you can allow other developers to more easily customize the migration.  The flow looks like this:

 * call your script/generate script and pass in whatever options they need
 * examine the generated migration, adding/removing columns or other options as necessary

This example will demonstrate how to use one of the built-in generator methods named 'migration_template' to create a migration file.  Extending the rails migration generator requires a somewhat intimate knowledge of the migration generator internals, so it's best to write a test first:

*vendor/plugins/yaffle/test/yaffle_migration_generator_test.rb*

[source, ruby]
------------------------------------------------------------------
require File.dirname(__FILE__) + '/test_helper.rb'
require 'rails_generator'
require 'rails_generator/scripts/generate'

class MigrationGeneratorTest < Test::Unit::TestCase

  def setup
    FileUtils.mkdir_p(fake_rails_root)
    @original_files = file_list
  end

  def teardown
    ActiveRecord::Base.pluralize_table_names = true
    FileUtils.rm_r(fake_rails_root)
  end
  
  def test_generates_correct_file_name
    Rails::Generator::Scripts::Generate.new.run(["yaffle_migration", "some_name_nobody_is_likely_to_ever_use_in_a_real_migration"], :destination => fake_rails_root)
    new_file = (file_list - @original_files).first
    assert_match /add_yaffle_fields_to_some_name_nobody_is_likely_to_ever_use_in_a_real_migrations/, new_file
    assert_match /add_column :some_name_nobody_is_likely_to_ever_use_in_a_real_migrations do |t|/, File.read(new_file)
  end

  def test_pluralizes_properly
    ActiveRecord::Base.pluralize_table_names = false
    Rails::Generator::Scripts::Generate.new.run(["yaffle_migration", "some_name_nobody_is_likely_to_ever_use_in_a_real_migration"], :destination => fake_rails_root)
    new_file = (file_list - @original_files).first
    assert_match /add_yaffle_fields_to_some_name_nobody_is_likely_to_ever_use_in_a_real_migration/, new_file
    assert_match /add_column :some_name_nobody_is_likely_to_ever_use_in_a_real_migration do |t|/, File.read(new_file)
  end

  private
    def fake_rails_root
      File.join(File.dirname(__FILE__), 'rails_root')
    end
  
    def file_list
      Dir.glob(File.join(fake_rails_root, "db", "migrate", "*"))
    end
      
end
------------------------------------------------------------------

.Editor's note:
NOTE: the migration generator checks to see if a migation already exists, and it's hard-coded to check the 'db/migrate' directory.  As a result, if your test tries to generate a migration that already exists in the app, it will fail.  The easy workaround is to make sure that the name you generate in your test is very unlikely to actually appear in the app.

After running the test with 'rake' you can make it pass with:

*vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb*

[source, ruby]
------------------------------------------------------------------
class YaffleMigrationGenerator < Rails::Generator::NamedBase
  def manifest
    record do |m|
      m.migration_template 'migration:migration.rb', "db/migrate", {:assigns => yaffle_local_assigns,
        :migration_file_name => "add_yaffle_fields_to_#{custom_file_name}"
      }
    end
  end

  private
    def custom_file_name
      custom_name = class_name.underscore.downcase
      custom_name = custom_name.pluralize if ActiveRecord::Base.pluralize_table_names
      custom_name
    end

    def yaffle_local_assigns
      returning(assigns = {}) do
        assigns[:migration_action] = "add"
        assigns[:class_name] = "add_yaffle_fields_to_#{custom_file_name}"
        assigns[:table_name] = custom_file_name
        assigns[:attributes] = [Rails::Generator::GeneratedAttribute.new("last_squawk", "string")]
      end
    end
end
------------------------------------------------------------------

The generator creates a new file in 'db/migrate' with a timestamp and an 'add_column' statement.  It reuses the built in rails `migration_template` method, and reuses the built-in rails migration template.

It's courteous to check to see if table names are being pluralized whenever you create a generator that needs to be aware of table names.  This way people using your generator won't have to manually change the generated files if they've turned pluralization off.

To run the generator, type the following at the command line:

------------------------------------------------------------------
./script/generate yaffle_migration bird
------------------------------------------------------------------

and you will see a new file:

*db/migrate/20080529225649_add_yaffle_fields_to_birds.rb*

[source, ruby]
------------------------------------------------------------------
class AddYaffleFieldsToBirds < ActiveRecord::Migration
  def self.up
    add_column :birds, :last_squawk, :string
  end

  def self.down
    remove_column :birds, :last_squawk
  end
end
------------------------------------------------------------------