HairTrigger¶ ↑

<img src=“https://secure.travis-ci.org/jenseng/hair_trigger.png?branch=master” />

HairTrigger lets you create and manage database triggers in a concise, db-agnostic, Rails-y way. You declare triggers right in your models in Ruby, and a simple rake task does all the dirty work for you.

Installation¶ ↑

Rails 3¶ ↑

If you are using Rails 3, just put hairtrigger in your Gemfile.

Rails 2¶ ↑

Step 1.¶ ↑

Put hairtrigger in your Gemfile, or if you’re not using bundler, you can “gem install hairtrigger” and then put hairtrigger in environment.rb

Step 2.¶ ↑

Create lib/tasks/hair_trigger.rake with the following:

$VERBOSE = nil
Dir["#{Gem.searcher.find('hair_trigger').full_gem_path}/lib/tasks/*.rake"].each { |ext| load ext }

This will give you the db:generate_trigger_migration task, and will ensure that hairtrigger hooks into db:schema:dump.

If you are unpacking the gem in vendor/plugins, this step is not needed (though you’ll then want to delete its Gemfile to avoid possible conflicts).

Usage¶ ↑

Models¶ ↑

Declare triggers in your models and use a rake task to auto-generate the appropriate migration. For example:

class AccountUser < ActiveRecord::Base
  trigger.after(:insert) do
    "UPDATE accounts SET user_count = user_count + 1 WHERE id = NEW.account_id;"
  end
end

and then:

rake db:generate_trigger_migration

This will create a db-agnostic migration for the trigger that mirrors the model declaration. The end result in MySQL will be something like this:

CREATE TRIGGER account_users_after_insert_row_tr AFTER INSERT ON account_users
FOR EACH ROW
BEGIN
    UPDATE accounts SET user_count = user_count + 1 WHERE id = NEW.account_id;
END

Note that these auto-generated create_trigger statements in the migration contain the “:generated => true” option, indicating that they were created from the model definition. This is important, as the rake task will also generate appropriate drop/create statements for any model triggers that get removed or updated. It does this by diffing the current model trigger declarations and any auto-generated triggers in schema.rb (and subsequent migrations).

Chainable Methods¶ ↑

Triggers are built by chaining several methods together, ending in a block that specifies the SQL to be run when the trigger fires. Supported methods include:

name(trigger_name)¶ ↑

Optional, inferred from other calls.

on(table_name)¶ ↑

Ignored in models, required in migrations.

for_each(item)¶ ↑

Defaults to :row, PostgreSQL allows :statement.

before(*events)¶ ↑

Shorthand for timing(:before).events(*events).

after(*events)¶ ↑

Shorthand for timing(:after).events(*events).

where(conditions)¶ ↑

Optional, SQL snippet limiting when the trigger will fire. Supports delayed interpolation of variables.

security(user)¶ ↑

Permissions/role to check when calling trigger. PostgreSQL supports :invoker (default) and :definer, MySQL supports :definer (default) and arbitrary users (syntax: ‘user’@‘host’).

timing(timing)¶ ↑

Required (but may be satisified by before/after). Possible values are :before/:after.

events(*events)¶ ↑

Required (but may be satisified by before/after). Possible values are :insert/:update/:delete/:truncate. MySQL/SQLite only support one action per trigger, and don’t support :truncate.

all¶ ↑

Noop, useful for trigger groups (see below).

Trigger Groups¶ ↑

Trigger groups allow you to use a slightly more concise notation if you have several triggers that fire on a given model. This is also important for MySQL, since it does not support multiple triggers on a table for the same action and timing. For example:

trigger.after(:update) do |t|
  t.all do # every row
    # some sql
  end
  t.where("OLD.foo != NEW.foo") do
    # some more sql
  end
  t.where("OLD.bar != NEW.bar") do
    # some other sql
  end
end

For MySQL, this will just create a single trigger with conditional logic (since it doesn’t support multiple triggers). PostgreSQL and SQLite will have distinct triggers. This same notation is also used within trigger migrations. MySQL does not currently support nested trigger groups.

Database-specific trigger bodies¶ ↑

Although HairTrigger aims to be totally db-agnostic, at times you do need a little more control over the body of the trigger. You can tailor it for specific databases by returning a hash rather than a string. Make sure to set a :default value if you aren’t explicitly specifying all of them.

For example, MySQL generally performs poorly with subselects in UPDATE statements, and it has its own proprietary syntax for multi-table UPDATEs. So you might do something like the following:

trigger.after(:insert) do
  {:default => <<-DEFAULT_SQL, :mysql => <<-MYSQL}

  UPDATE users SET item_count = item_count + 1
  WHERE id IN (SELECT user_id FROM buckets WHERE id = NEW.bucket_id)
  DEFAULT_SQL

  UPDATE users, buckets SET item_count = item_count + 1
  WHERE users.id = user_id AND buckets.id = NEW.bucket_id
  MYSQL
end

Manual Migrations¶ ↑

You can also manage triggers manually in your migrations via create_trigger and drop_trigger. They are a little more verbose than model triggers, and they can be more work since you need to figure out the up/down create/drop logic when you change things. A sample trigger:

create_trigger(:compatibility => 1).on(:users).after(:insert) do
  "UPDATE accounts SET user_count = user_count + 1 WHERE id = NEW.account_id;"
end

Manual triggers and :compatibility¶ ↑

As bugs are fixed and features are implemented in hairtrigger, it’s possible that the generated trigger SQL will change (this has only happened once so far). If you upgrade to a newer version of hairtrigger, it needs a way of knowing which previous version generated the original trigger. You only need to worry about this for manual trigger migrations, as the model ones automatically take care of this. For your manual triggers you can either:

• pass “:compatibility => x” to your create_trigger statement, where x is whatever HairTrigger::Builder.compatiblity is (1 for this version).

• set “HairTrigger::Builder.base_compatibility = x” in an initializer, where x is whatever HairTrigger::Builder.compatiblity is. This is like doing the first option on every create_trigger. Note that once the compatibility changes, you’ll need to set :compatibility on new triggers (unless you just redo all your triggers and bump the base_compatibility).

If you upgrade to a newer version of hairtrigger and see that the SQL compatibility has changed, you’ll need to set the appropriate compatibility on any new triggers that you create.

rake db:schema:dump¶ ↑

HairTrigger hooks into rake db:schema:dump (and rake tasks that call it) to make it trigger-aware. A newly generated schema.rb will contain:

• create_trigger statements for any database triggers that exactly match a create_trigger statement in an applied migration or in the previous schema.rb file. this includes both generated and manual create_trigger calls.

• adapter-specific execute(‘CREATE TRIGGER..’) statements for any unmatched database triggers.

As long as you don’t delete old migrations and schema.rb prior to running rake db:schema:dump, the result should be what you expect (and portable). If you have deleted all trigger migrations, you can regenerate a new baseline for model triggers via rake db:generate_trigger_migration.

Testing¶ ↑

To stay on top of things, it’s strongly recommended that you add a test or spec to ensure your migrations/schema.rb match your models. This is as simple as:

assert HairTrigger::migrations_current?

This way you’ll know if there are any outstanding migrations you need to create.

Warnings and Errors¶ ↑

There are a couple classes of errors: declaration errors and generation errors/warnings.

Declaration errors happen if your trigger declaration is obviously wrong, and will cause a runtime error in your model or migration class. An example would be “trigger.after(:never)”, since :never is not a valid event.

Generation errors happen if you try something that your adapter doesn’t support. An example would be something like “trigger.security(:invoker)” for MySQL. These errors only happen when the trigger is actually generated, e.g. when you attempt to run the migration.

Generation warnings are similar but they don’t stop the trigger from being generated. If you do something adapter-specific supported by your database, you will still get a warning ($stderr) that your trigger is not portable. You can silence warnings via “HairTrigger::Builder.show_warnings = false”

You can validate your triggers beforehand using the Builder#validate! method. It will throw the appropriate errors/warnings so that you know what to fix, e.g.

> User.triggers.each(&:validate!)

HairTrigger does not validate your SQL, so be sure to test it in all databases you want to support.

Gotchas¶ ↑

• As is the case with ActiveRecord::Base.update_all or any direct SQL you do, be careful to reload updated objects from the database. For example, the following code will display the wrong count since we aren’t reloading the account:

  a = Account.find(123)
  a.account_users.create(:name => 'bob')
  puts "count is now #{a.user_count}"
  

• For repeated chained calls, the last one wins, there is currently no merging.

• If you want your code to be portable, the trigger actions should be limited to INSERT/UPDATE/DELETE/SELECT, and conditional logic should be handled through the :where option/method. Otherwise you’ll likely run into trouble due to differences in syntax and supported features.

• Manual create_trigger statements have some gotchas. See the section “Manual triggers and :compatibility”

Compatibility¶ ↑

• Rails 2.3+

• Postgres 8.0+

• MySQL 5.0.10+

• SQLite 3.3.8+

Version History¶ ↑

• 0.2.3 Better 1.9 support, update parsing gems

• 0.2.2 PostGIS support

• 0.2.1 Bugfix for adapter-specific warnings, loosen parser dependencies

• 0.2.0 Rails 3.1+ support, easier installation, ruby 1.9 fix, travis-ci

• 0.1.14 sqlite + ruby1.9 bugfix

• 0.1.13 drop_trigger fix

• 0.1.12 DB-specific trigger body support, bugfixes

• 0.1.11 Safer migration loading, some speedups

• 0.1.10 Sped up migration evaluation

• 0.1.9 MySQL fixes for inferred root@localhost

• 0.1.7 Rails 3 support, fixed a couple manual create_trigger bugs

• 0.1.6 rake db:schema:dump support, respect non-timestamped migrations

• 0.1.4 Compatibility tracking, fixed Postgres return bug, ensure last action has a semicolon

• 0.1.3 Better error handling, Postgres 8.x support, updated docs

• 0.1.2 Fixed Builder#security, updated docs

• 0.1.1 Fixed bug in HairTrigger.migrations_current?, fixed up Gemfile

• 0.1.0 Initial release

Copyright¶ ↑

Copyright © 2012 Jon Jensen. See LICENSE.txt for further details.