Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
178 lines (113 sloc) 6.36 KB
= RedHill on Rails Core
RedHill on Rails Core is a plugin that features to support other RedHill on Rails plugins. Those features include:
* Creating and dropping views;
* Creating and removing foreign-keys;
* Obtaining indexes directly from a model class; and
* Determining when <code>Schema.define()</code> is running.
=== View Support
The plugin provides a mechanism for creating and dropping views as well as
preserving views when performing a schema dump:
create_view :normal_customers, "SELECT * FROM customers WHERE status = 'normal'"
drop_view :normal_customers
=== 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
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
You also have the option of specifying what to do on delete/update using
<code>:on_delete</code>/<code>:on_update</code>, respectively to one of: <code>:cascade</code>; <code>:restrict</code>; and <code>:set_null</code>:
create_table :orders do |t|
t.foreign_key :customer_id, :customers, :id, :on_delete => :set_null, :on_update => :cascade
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 <code>:name</code> option:
add_foreign_key(:orders, :customer_id, :customers, :id, :on_delete => :set_null, :on_update => :cascade, <strong>:name => :orders_customer_id_foreign_key<strong>)
You can also query the foreign keys for a model yourself by calling <code>foreign_keys()</code>:
Or for an arbitrary table by calling <code>foreign_keys(table_name)</code> 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 <code>rake migrate</code> or
<code>rake db:schema:dump</code>. 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.
Some databases (PostgreSQL and MySQL for example) allow you to set a comment for a
table. You can do this for existing tables by using:
set_table_comment :orders, "All pending and processed orders"
or even at the time of creation:
create_table :orders, :comment => "All pending and processed orders" do |t|
You can clear table comments using:
clear_table_comment :orders
There is also a rake tasks to show all database tables and their comments:
rake db:comments
The plugin fully supports and understands the following active-record
configuration properties:
* <code>config.active_record.pluralize_table_names</code>
* <code>config.active_record.table_name_prefix</code>
* <code>config.active_record.table_name_suffix</code>
=== Model Indexes
ActiveRecord::Base already provides a method on connection for obtaining the
indexes for a given table. This plugin now makes it possible to obtain the
indexes for a given model--<code>ActiveRecord::Base</code>--class. For example:
Would return all the indexes for the +invoices+ table.
=== Schema Defining
The plugin also adds a method--<code>defining?()</code>--to
<code>ActiveRecord::Schema</code> to indicate when <code>define()</code> is running. This is necessary
as some migration plugins must change their behaviour accordingly.
=== Case-insensitive Indexes
For PostgreSQL, you can add an option <code>:case_sensitive => false</code> to <code>add_index</code>
which will generate an expression index of the form:
This means finder queries of the form:
WHERE LOWER(column_name) = LOWER(?)
are able to use the indexes rather require, in the worst case, full-table scans.
Note also that this ties in well with Rails built-in support for case-insensitive searching:
validates_uniqueness_of :name, :case_sensitive => false
=== Testing
The plugin is heavily dependent on the database and rspec testing is provided to verify if database supports plugin features.
Rspec and rspec-rails plugins are neccessary:
script/plugin install git://
script/plugin install git://
script/generate rspec
The plugin test use rails test database so it must be created before the tests are run:
rake db:create RAILS_ENV=test
And then run the plugin specs with:
rake specs:plugins
The plugin was tested on:
* mysql5 - all tests pass
* sqlite - plugin doesn't support foreign key functionality for sqlite because db doesn't implement foreign key constraints
* sqlite3 - plugin doesn't support foreign key functionality for sqlite3
* postgresql - all tests pass
Currently only foreign key functionality is tested
=== See Also
* Foreign Key Associations (foreign_key_associations)
* Foreign Key Migrations (foreign_key_migrations)
* Row Version Migrations (row_version_migrations)
* Schema Validations (schema_validations)
=== License
This plugin is copyright 2006 by RedHill Consulting, Pty. Ltd. and is released
under the MIT license.