1 files changed, 101 insertions, 17 deletions
diff --git a/activerecord/lib/active_record/migration.rb b/activerecord/lib/active_record/migration.rb
index b4dd8eff5a..f087a1eaa6 100644
--- a/activerecord/lib/active_record/migration.rb
+++ b/activerecord/lib/active_record/migration.rb
@@ -9,40 +9,128 @@ module ActiveRecord
     end
   end
 
-  # Exception that can be raised to stop migrations from going backwards.
+  # Exception that can be raised to stop migrations from being rolled back.
+  # For example the following migration is not reversible.
+  # Rolling back this migration will raise an ActiveRecord::IrreversibleMigration error.
+  #
+  #   class IrreversibleMigrationExample < ActiveRecord::Migration
+  #     def change
+  #       create_table :distributors do |t|
+  #         t.string :zipcode
+  #       end
+  #
+  #       execute <<-SQL
+  #         ALTER TABLE distributors
+  #           ADD CONSTRAINT zipchk
+  #             CHECK (char_length(zipcode) = 5) NO INHERIT;
+  #       SQL
+  #     end
+  #   end
+  #
+  # There are two ways to mitigate this problem.
+  #
+  # 1. Define <tt>#up</tt> and <tt>#down</tt> methods instead of <tt>#change</tt>:
+  #
+  #  class ReversibleMigrationExample < ActiveRecord::Migration
+  #    def up
+  #      create_table :distributors do |t|
+  #        t.string :zipcode
+  #      end
+  #
+  #      execute <<-SQL
+  #        ALTER TABLE distributors
+  #          ADD CONSTRAINT zipchk
+  #            CHECK (char_length(zipcode) = 5) NO INHERIT;
+  #      SQL
+  #    end
+  #
+  #    def down
+  #      execute <<-SQL
+  #        ALTER TABLE distributors
+  #          DROP CONSTRAINT zipchk
+  #      SQL
+  #
+  #      drop_table :distributors
+  #    end
+  #  end
+  #
+  # 2. Use the #reversible method in <tt>#change</tt> method:
+  #
+  #   class ReversibleMigrationExample < ActiveRecord::Migration
+  #     def change
+  #       create_table :distributors do |t|
+  #         t.string :zipcode
+  #       end
+  #
+  #       reversible do |dir|
+  #         dir.up do
+  #           execute <<-SQL
+  #             ALTER TABLE distributors
+  #               ADD CONSTRAINT zipchk
+  #                 CHECK (char_length(zipcode) = 5) NO INHERIT;
+  #           SQL
+  #         end
+  #
+  #         dir.down do
+  #           execute <<-SQL
+  #             ALTER TABLE distributors
+  #               DROP CONSTRAINT zipchk
+  #           SQL
+  #         end
+  #       end
+  #     end
+  #   end
   class IrreversibleMigration < MigrationError
   end
 
   class DuplicateMigrationVersionError < MigrationError#:nodoc:
-    def initialize(version)
-      super("Multiple migrations have the version number #{version}")
+    def initialize(version = nil)
+      if version
+        super("Multiple migrations have the version number #{version}.")
+      else
+        super("Duplicate migration version error.")
+      end
     end
   end
 
   class DuplicateMigrationNameError < MigrationError#:nodoc:
-    def initialize(name)
-      super("Multiple migrations have the name #{name}")
+    def initialize(name = nil)
+      if name
+        super("Multiple migrations have the name #{name}.")
+      else
+        super("Duplicate migration name.")
+      end
     end
   end
 
   class UnknownMigrationVersionError < MigrationError #:nodoc:
-    def initialize(version)
-      super("No migration with version number #{version}")
+    def initialize(version = nil)
+      if version
+        super("No migration with version number #{version}.")
+      else
+        super("Unknown migration version.")
+      end
     end
   end
 
   class IllegalMigrationNameError < MigrationError#:nodoc:
-    def initialize(name)
-      super("Illegal name for migration file: #{name}\n\t(only lower case letters, numbers, and '_' allowed)")
+    def initialize(name = nil)
+      if name
+        super("Illegal name for migration file: #{name}\n\t(only lower case letters, numbers, and '_' allowed).")
+      else
+        super("Illegal name for migration.")
+      end
     end
   end
 
   class PendingMigrationError < MigrationError#:nodoc:
-    def initialize
-      if defined?(Rails.env)
-        super("Migrations are pending. To resolve this issue, run:\n\n\tbin/rake db:migrate RAILS_ENV=#{::Rails.env}")
+    def initialize(message = nil)
+      if !message && defined?(Rails.env)
+        super("Migrations are pending. To resolve this issue, run:\n\n\tbin/rake db:migrate RAILS_ENV=#{::Rails.env}.")
+      elsif !message
+        super("Migrations are pending. To resolve this issue, run:\n\n\tbin/rake db:migrate.")
       else
-        super("Migrations are pending. To resolve this issue, run:\n\n\tbin/rake db:migrate")
+        super
       end
     end
   end
@@ -867,10 +955,6 @@ module ActiveRecord
         Array(@migrations_paths)
       end
 
-      def migrations_path
-        migrations_paths.first
-      end
-
       def migrations(paths)
         paths = Array(paths)