== Running Migrations ==

Rails provides a set of rake tasks to work with migrations which boils down to running certain sets of migrations. The very first migration related rake task you use will probably be `db:migrate`. In its most basic form it just runs the `up` method for all the migrations that have not yet been run. If there are no such migrations it exits.

If you specify a target version, Active Record will run the required migrations (up or down) until it has reached the specified version. The
version is the numerical prefix on the migration's filename. For example to migrate to version 20080906120000 run

------------------------------------
rake db:migrate VERSION=20080906120000
------------------------------------

If this is greater than the current version (i.e. it is migrating upwards) this will run the `up` method on all migrations up to and including 20080906120000, if migrating downwards this will run the `down` method on all the migrations down to, but not including, 20080906120000.

=== Rolling back ===

A common task is to rollback the last migration, for example if you made a mistake in it and wish to correct it. Rather than tracking down the version number associated with the previous migration you can run

------------------
rake db:rollback
------------------

This will run the `down` method from the latest migration. If you need to undo several migrations you can provide a `STEP` parameter:

------------------
rake db:rollback STEP=3
------------------

will run the `down` method from the last 3 migrations.

The `db:migrate:redo` task is a shortcut for doing a rollback and then migrating back up again. As with the `db:rollback` task you can use the `STEP` parameter if you need to go more than one version back, for example

------------------
rake db:migrate:redo STEP=3
------------------

Neither of these Rake tasks do anything you could not do with `db:migrate`, they are simply more convenient since you do not need to explicitly specify the version to migrate to.

Lastly, the `db:reset` task will drop the database, recreate it and load the current schema into it.

NOTE: This is not the same as running all the migrations - see the section on <<schema,schema.rb>>.

=== Being Specific ===

If you need to run a specific migration up or down the `db:migrate:up` and `db:migrate:down` tasks will do that. Just specify the appropriate version and the corresponding migration will have its `up` or `down` method invoked, for example

------------------
rake db:migrate:up VERSION=20080906120000
------------------

will run the `up` method from the 20080906120000 migration. These tasks check whether the migration has already run, so for example `db:migrate:up VERSION=20080906120000` will do nothing if Active Record believes that 20080906120000 has already been run.


=== Being talkative ===

By default migrations tell you exactly what they're doing and how long it took.
A migration creating a table and adding an index might produce output like this
-------------------------
== 20080906170109 CreateProducts: migrating ===================================
-- create_table(:products)
   -> 0.0021s
-- add_index(:products, :name)
   -> 0.0026s
== 20080906170109 CreateProducts: migrated (0.0059s) ==========================
-------------------------
Several methods are provided that allow you to control all this:

* `suppress_messages` suppresses any output generated by its block
* `say` outputs text (the second argument controls whether it is indented or not)
* `say_with_time` outputs text along with how long it took to run its block. If the block returns an integer it assumes it is the number of rows affected.

For example, this migration

[source, ruby]
----------------------
class CreateProducts < ActiveRecord::Migration
  def self.up
    suppress_messages do
      create_table :products do |t|
        t.string :name
        t.text :description
        t.timestamps
      end
    end
    say "Created a table"
    suppress_messages {add_index :products, :name}
    say "and an index!", true
    say_with_time 'Waiting for a while' do
      sleep 10
      250
    end
  end

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

generates the following output
----------------------
== 20080906170109 CreateProducts: migrating ===================================
-- Created a table
   -> and an index!
-- Waiting for a while
   -> 10.0001s
   -> 250 rows
== 20080906170109 CreateProducts: migrated (10.0097s) =========================
----------------------

If you just want Active Record to shut up then running `rake db:migrate VERBOSE=false` will suppress any output.