Rails -- understanding db:migrate

Question

I am having a little trouble understanding migrations in Ruby on Rails. I have the following two classes in my application's db\migrate\ directory (stored in separate files):

class CreateUsers < ActiveRecord::Migration
  def self.up
    create_table :users do |t|
      t.string :name
      t.string :email

      t.timestamps
    end
  end

  def self.down
    drop_table :users
  end
end

class AddEmailUniquenessIndex < ActiveRecord::Migration
  def self.up
    add_index :users, :email, :unique => true
  end

  def self.down
    remove_index :users, :email
  end
end

I am confused at how these two files seem to be run together. Upon creation of this second class, Michael Hartl's book says "we could just edit the migration file for the users table but that would require rolling back then migrating back up. The Rails Way is to use migrations every time we discover that our data model needs to change." How do these migrations actually work? Are all the files in the directory run when the database is migrated? Like what is going on behind the scenes here??

Answer 1

As convention, the file name for these migration classes will be prefixed by a timestamp representation of when these were created (ex. 20110611000000). When you run db:migrate, rails will check a special table in the database which contains the timestamp of the last migration applied to the database. It will then apply all of the migrations with timestamps after that date and update the database table with the timestamp of the last migration. As a result, each migration class is applied exactly once to the database.

Michael Hart was illustrating that if you put all of the migrations into a single file, rails would have a hard / impossible time telling which migrations had been applied and which ones hadn't. The only option at that point would be to drop all the tables in the database and run through all the migrations from the beginning. Functionally that works, but you would lost all your data. Better to move only in the 'forward' direction than back to the beginning and then forward again.