Last Update: Wed Dec 03 17:41:32 -0600 2008


This plugin extends the base Rails ActiveRecord::Migration with some commonly used functionality, aiming at keeping your migrations short, easy to understand and meaningful.

Installing the plugin

The easiest way is through Rails’ own +scripts/plugins+ utility. The first thing you should do is to tell Rails where the plugin‘s tree is located.

If you want to follow the latest changes, you will probably prefer following the project‘s trunk, however, for production, I strongly suggest you to stick to a stable release. Depending on what you prefer, from your project‘s base directory, type:

  $ ./script/plugin source

Or, to follow a given release (say, 0.1 - Of course, check on the latest stable release before doing this):

  $ ./script/plugin source

Then, ask Rails to install the plugin:

  $ ./script/plugin install real_fk

If you use Subversion for tracking your project‘s development, you will probably want to mark the plugin as an external repository. To do so, add the -x switch:

  $ ./script/plugin install -x real_fk

Using the plugin


Rails is built upon a "dumb database" concept. Rails assumes the database will not force restrictions upon the user - i.e. that the model validators are all there is. But I disagree ;-)

So, if you want to create a relation field, properly acting as a foreign key and refering to another table, instead of doing it via the ActiveRecord::ConnectionAdapters::TableDefinition#column (or even ActiveRecord::ConnectionAdapters::TableDefinition#references) methods, declare them with add_refrence:

  def self.up
    create_table :proposals do |t|
    create_table :proposal_types do |t|
    create_table :proposal_statuses do |t|
    add_reference :proposals, :proposal_types
    add_reference :proposals, :proposal_statuses, :null => false, :default => 1

The corresponding fields (proposal_type_id and proposal_status_id, respectively) will be created in proposals, and the RDBMS will impose a Foreign Key constraint.

The references can be removed via remove_reference, i.e., for inclusion in down migrations:

  def self.down
    remove_reference :proposals, :proposal_types
    remove_reference :proposals, :proposal_statuses
    drop_table :proposal_statuses
    drop_table :proposal_types
    drop_table :proposals

Of course, in this case the remove_reference call is not really needed - But if you are dropping a table that is referred to from a table that will remain existing, you will have to remove the foreign key constraints (that is, the referring columns).

Join (HABTM) tables

When you define a simple has_and_belongs_to_many (HABTM) relation in your model, you are expected to create an extra table representing this relation. This is a very simple table (i.e. it has only a row for each of the related table‘s IDs), and it carries foreign key constraints (see the References section).

Please note that join tables are not supposed to carry any extra columns - If you need to add information to join tables, think twice and better use a has_many :elements, :through => :othermodel declaration, and create the othermodel table manually.

To create a HABTM table representing that each person can attend many conferences and each conference can be attended by many people:

  def self.up
    create_table :people do |t|
    create_table :conferences do |t|
    create_habtm :people, :conferences
  def self.down
    drop_habtm :people, :conferences
    drop_table :people
    drop_table :conferences

The last call will create a conferences_people table (according to Rails’ conventions, table names are sorted alphabetically to get the join table‘s name).

Note that in the down migration, the drop_habtm call must appear before the drop_table calls, as it carries foreign key constraints.

Author, copyright and licensing.

This plugin was written by Gunnar Wolf <>, Instituto de Investigaciones Económicas, UNAM.

Licensing information

This plugin is under a MIT license. For further information, please check the LICENSE file.

Getting the code

The plugin project‘s home page can be found at

The Rubyforge project page is

The Git tree can be cloned anonymously:

    git clone git://

You can also browse the Git repository via the web interface, and even generate tarballs for specific points in time at:;a=tree