vendor/rails/railties/doc/guides/source/migrations/rakeing_around.txt

   1 == Running Migrations ==
   2
   3 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.
   4
   5 If you specify a target version, Active Record will run the required migrations (up or down) until it has reached the specified version. The
   6 version is the numerical prefix on the migration's filename. For example to migrate to version 20080906120000 run
   7
   8 ------------------------------------
   9 rake db:migrate VERSION=20080906120000
  10 ------------------------------------
  11
  12 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.
  13
  14 === Rolling back ===
  15
  16 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
  17
  18 ------------------
  19 rake db:rollback
  20 ------------------
  21
  22 This will run the `down` method from the latest migration. If you need to undo several migrations you can provide a `STEP` parameter:
  23
  24 ------------------
  25 rake db:rollback STEP=3
  26 ------------------
  27
  28 will run the `down` method from the last 3 migrations.
  29
  30 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
  31
  32 ------------------
  33 rake db:migrate:redo STEP=3
  34 ------------------
  35
  36 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.
  37
  38 Lastly, the `db:reset` task will drop the database, recreate it and load the current schema into it.
  39
  40 NOTE: This is not the same as running all the migrations - see the section on <<schema,schema.rb>>.
  41
  42 === Being Specific ===
  43
  44 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
  45
  46 ------------------
  47 rake db:migrate:up VERSION=20080906120000
  48 ------------------
  49
  50 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.
  51
  52
  53 === Being talkative ===
  54
  55 By default migrations tell you exactly what they're doing and how long it took.
  56 A migration creating a table and adding an index might produce output like this
  57 -------------------------
  58 == 20080906170109 CreateProducts: migrating ===================================
  59 -- create_table(:products)
  60    -> 0.0021s
  61 -- add_index(:products, :name)
  62    -> 0.0026s
  63 == 20080906170109 CreateProducts: migrated (0.0059s) ==========================
  64 -------------------------
  65 Several methods are provided that allow you to control all this:
  66
  67 * `suppress_messages` suppresses any output generated by its block
  68 * `say` outputs text (the second argument controls whether it is indented or not)
  69 * `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.
  70
  71 For example, this migration
  72
  73 [source, ruby]
  74 ----------------------
  75 class CreateProducts < ActiveRecord::Migration
  76   def self.up
  77     suppress_messages do
  78       create_table :products do |t|
  79         t.string :name
  80         t.text :description
  81         t.timestamps
  82       end
  83     end
  84     say "Created a table"
  85     suppress_messages {add_index :products, :name}
  86     say "and an index!", true
  87     say_with_time 'Waiting for a while' do
  88       sleep 10
  89       250
  90     end
  91   end
  92
  93   def self.down
  94     drop_table :products
  95   end
  96 end
  97 ----------------------
  98
  99 generates the following output
 100 ----------------------
 101 == 20080906170109 CreateProducts: migrating ===================================
 102 -- Created a table
 103    -> and an index!
 104 -- Waiting for a while
 105    -> 10.0001s
 106    -> 250 rows
 107 == 20080906170109 CreateProducts: migrated (10.0097s) =========================
 108 ----------------------
 109
 110 If you just want Active Record to shut up then running `rake db:migrate VERBOSE=false` will suppress any output.
 111