[ci skip] Add comments for `IrreversibleMigration`

1 files changed, 70 insertions, 0 deletions

diff --git a/activerecord/lib/active_record/migration.rb b/activerecord/lib/active_record/migration.rb
index 4901f9dafd..93e7a04f55 100644
--- a/activerecord/lib/active_record/migration.rb
+++ b/activerecord/lib/active_record/migration.rb
@@ -10,6 +10,76 @@ module ActiveRecord
   end
 
   # Exception that can be raised to stop migrations from going backwards.
+  # For example <tt>IrreversibleMigrationExample</tt> is not reversible.
+  # When you rollback this migration, <tt>ActiveRecord::IrreversibleMigration</tt> is raised.
+  #
+  #   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. Use <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 <tt>reversible</tt> 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