ruby script/plugin install svn://rubyforge.org/var/svn/redhillonrails/trunk/vendor/plugins/redhillonrails_core

Foreign Key Support
====================

The plugin provides two mechanisms for adding foreign keys as well as preserving foreign keys when performing a schema dump. (Using SQL-92 syntax and as such should be compatible with most databases that support foreign-key constraints.)

The first mechanism for creating foreign-keys allows you to add a foreign key when defining a table. For example:

  create_table :orders do |t|
    ...
    t.foreign_key :customer_id, :customers, :id
  end

You also have the option of specifying what to do on delete/update using :on_delete/:on_update, respectively to one of: :cascade; :restrict; and :set_null:

  create_table :orders do |t|
    ...
    t.foreign_key :customer_id, :customers, :id, :on_delete => :set_null, :on_update => :cascade
  end

The second method allows you to create arbitrary foreign-keys at any time:

  add_foreign_key(:orders, :customer_id, :customers, :id, :on_delete => :set_null, :on_update => :cascade)

In either case, if your database supports deferred foreign keys (for example PostgreSQL) you can specify this as well:

  t.foreign_key :customer_id, :customers, :id, :deferrable => true
  add_foreign_key(:orders, :customer_id, :customers, :id, :deferrable => true)

By default, the foreign key will be assigned a name by the underlying database. However, if this doesn't suit your needs, you can override the default assignment using the :name option:

  add_foreign_key(:orders, :customer_id, :customers, :id, :on_delete => :set_null, :on_update => :cascade, :name => :orders_customer_id_foreign_key)

You can also query the foreign keys for a model yourself by calling foreign_keys():

  Order.foreign_keys

Or for an arbitrary table by calling foreign_keys(table_name) on a database adapter.

Either method returns an array of the following meta-data:

* +name+ - The name of the foreign key constraint;
* +table_name+ - The table for which the foreign-key was generated;
* +column_names+ - The column names in the table;
* +references_table_name+ - The table referenced by the foreign-key; and
* +references_column_names+ - The columns names in the referenced table.

If you need to drop a foreign-key, use:

  remove_foreign_key :orders, :orders_ordered_by_id_fkey

The plugin also ensures that all foreign keys are output when performing a schema dump. This happens automatically when running rake migrate or rake db:schema:dump. This has particular implications when running unit tests that contain fixtures. To ensure the test data is correctly reset after each test, you should list your fixtures in order of parent->child. For example:

  fixtures :customers, :products, :orders, :order_lines

Rails will then set-up and tear-down the fixtures in the correct sequence.

The plugin fully supports and understands the following active-record configuration properties:

* config.active_record.pluralize_table_names
* config.active_record.table_name_prefix
* config.active_record.table_name_suffix

There is currently no advanced documentation for this plugin.