README

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

real_fk

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 http://realfk.rubyforge.org/svn/trunk/

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

  $ ./script/plugin source http://realfk.rubyforge.org/svn/tags/0.1/

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

References

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|
      (...)
    end
    create_table :proposal_types do |t|
      (...)
    end
    create_table :proposal_statuses do |t|
      (...)
    end
    add_reference :proposals, :proposal_types
    add_reference :proposals, :proposal_statuses, :null => false, :default => 1
  end

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
  end

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|
      (...)
    end
    create_table :conferences do |t|
      (...)
    end
    create_habtm :people, :conferences
  end
  def self.down
    drop_habtm :people, :conferences
    drop_table :people
    drop_table :conferences
  end

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 <gwolf@gwolf.org>, 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 realfk.rubyforge.org/

The Rubyforge project page is rubyforge.org/projects/realfk/

The Git tree can be cloned anonymously:

    git clone git://rubyforge.org/actsascatalog.git

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

    http://realfk.rubyforge.org/git?p=realfk.git;a=tree

[Validate]