This article is part one of the series about Rails Migrations and it will explain on a basic level how to use the Ruby on Rails migrations.

1. What are Migrations ?

Migrations in Rails is a way of describing what the database should look like and synchronize it with the respective model.
Migrations are abstract to the database they are used with. This means that if you have used a MySQL database server when developing the application and the production database server is different let’s say Postgresql the database you defined within the migrations will remain intact and will run just fine on the new database server.
Migrations provide a way to make the database development SVN like… I will cover this latter on so just keep in mind this for now.

2. Creating and Running Migrations

A migration is a simple Ruby file in the db/migrate directory.
Each migration file has a name starting with three digits and an
underscore. Those digits are the representation of the migrations version (a bit like SVN),
because they define the sequence in which the migrations are applied.

To generate a migration type:

Notice: This will generate a model and a migration to it.

As user will be the name of the migration after the three digits and the underscore.
This name serves as an explanation to what the migration does.
But what actually happened?
We generate in our db/migrate directory a file named 001_create_users.rb

With the following command line you are able to execute the migration:

As the generated migration file is empty (containing only the create and drop table) we have to open it with our favorite editor and make our database table.

The file generated.

The file after we edited it.

The source shall be understandable.
It contains code which is executed as SQL queries.
It should be easily understandable for people with a bit of SQL knowledge.
So with this we created and run our migrations.
Now we might want to proceed and make another migration which will tweak our database.

3. Renaming, Adding Columns and more…

As you might notice we have an self.up and self.down def.
This serves the purpose of migration levels.
With our old command line and an additional parameter we are able to somewhat downgrade our database.
This is the part where we look at this as SVN. As in SVN we are restoring our database to a previous state.
We achieve this with the definition of the self.down.

You might wonder how to create only a Migration without a model. In case you haven’t tried it
already it is as intuitive as it should be:

We now know how to run and how to restore previous version of our database.
We know what self.up and self.down are used for.
We know that migrations are abstract to any database.
Now we are going to see how to add or edit table columns.

Renaming tables is used in the same way with rename_table.

Notice: beware that renaming tables causes model renaming and in certain situations after migrations you might get an exception.
Example: If you have a migration 1 create a table then migration 2 renames it. If you now drop the database and rerun the migration you will get an exception. It is caused by not finding the name of the class used for the migration cause we have renamed it.

As it seems pretty obvious what the lines of code do… and this is not a Ruby basic tutorial I will not go into details explaining this but here is a short overview of the code.

The first param for example rename_column show us the action we are doing. In the example it is renaming the column. Pretty straight forward isn’t it ?
The next param :users specify the table and the next one :customer_email the column.
The last param from the line :e_mail shows us the the name to which the column should be renamed. And cause this is in the def self.down it will be only executed if we downgrade to an old version of our database.

4. Reference

This is a reference with the names of the types used for describing the type of the column in a migration file.

:binary
:boolean
:date
:datetime
:decimal
:float
:integer
:string
:text
:time
:timestamp

Some of the types result in the same SQL database column types in the server used.
A useful param is the :limit . It was used in one of the very first code examples here and if you somehow managed to confuse the use of it simply say how long the field type should be. For example if using STRING :limit => 10 will result in a column of type VARCHAR in MySQL with max length of 10 Chars.

Hope it was useful!

More Migration talk will be released soon as a PART II of How to use Rails Migrations.

Cheers!