From a17027d13a48e1e64b14a28e7d58e341812f8cb4 Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Sat, 13 Sep 2008 20:28:01 +0100 Subject: Merge docrails --- railties/doc/guides/migrations/rakeing_around.txt | 111 ++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 railties/doc/guides/migrations/rakeing_around.txt (limited to 'railties/doc/guides/migrations/rakeing_around.txt') diff --git a/railties/doc/guides/migrations/rakeing_around.txt b/railties/doc/guides/migrations/rakeing_around.txt new file mode 100644 index 0000000000..1fcca0cf24 --- /dev/null +++ b/railties/doc/guides/migrations/rakeing_around.txt @@ -0,0 +1,111 @@ +== 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 fron 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 <>. + +=== 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. + -- cgit v1.2.3