hairtrigger 0.2.4 → 0.2.5

data/README.md

@@ -0,0 +1,290 @@
+# HairTrigger
+[<img src="https://secure.travis-ci.org/jenseng/hair_trigger.png?branch=master" />](http://travis-ci.org/jenseng/hair_trigger)
+
+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 or 4
+
+If you are using Rails 3 or 4, just `gem 'hairtrigger'`
+
+### 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:
+
+```ruby
+$VERBOSE = nil
+Dir["#{Gem::Specification.find_by_name('hairtrigger').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:
+
+```ruby
+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:
+
+```bash
+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:
+
+```sql
+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:
+
+```ruby
+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 `UPDATE`s. So
+you might do something like the following:
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+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.
+
+```ruby
+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:
+
+  ```ruby
+  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
+
+* Ruby 1.8.7+
+* Rails 2.3+
+* Postgres 8.0+
+* MySQL 5.0.10+
+* SQLite 3.3.8+
+
+## [Changelog](blob/master/CHANGELOG.md)
+
+## Copyright
+
+Copyright (c) 2011-2014 Jon Jensen. See LICENSE.txt for further details.

data/lib/hair_trigger/version.rb

@@ -1,5 +1,5 @@
 module HairTrigger
-  VERSION = "0.2.4"
+  VERSION = "0.2.5"
 
   def VERSION.<=>(other)
     split(/\./).map(&:to_i) <=> other.split(/\./).map(&:to_i)

data/spec/builder_spec.rb

@@ -14,8 +14,8 @@ class MockAdapter
   end
 end
 
-def builder
-  HairTrigger::Builder.new(nil, :adapter => @adapter)
+def builder(name = nil)
+  HairTrigger::Builder.new(name, :adapter => @adapter)
 end
 
 describe "builder" do
@@ -48,6 +48,20 @@ describe "builder" do
     end
   end
 
+  describe "name" do
+    it "should be inferred if none is provided" do
+      builder.on(:foos).after(:update){ "foo" }.prepared_name.
+        should == "foos_after_update_row_tr"
+    end
+
+    it "should respect the last chained name" do
+      builder("lolwut").on(:foos).after(:update){ "foo" }.prepared_name.
+        should == "lolwut"
+      builder("lolwut").on(:foos).name("zomg").after(:update).name("yolo"){ "foo" }.prepared_name.
+        should == "yolo"
+    end
+  end
+
   context "adapter-specific actions" do
     before(:each) do
       @adapter = MockAdapter.new("mysql")
@@ -263,4 +277,4 @@ describe "builder" do
       }.should raise_error
     end
   end
-end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hairtrigger
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-12 00:00:00.000000000 Z
+date: 2014-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -34,7 +34,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 3.2.2
+        version: '3.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -42,7 +42,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 3.2.2
+        version: '3.4'
 - !ruby/object:Gem::Dependency
   name: ruby2ruby
   requirement: !ruby/object:Gem::Requirement
@@ -160,12 +160,11 @@ description: allows you to declare database triggers in ruby in your models, and
 email: jenseng@gmail.com
 executables: []
 extensions: []
-extra_rdoc_files:
-- README.rdoc
+extra_rdoc_files: []
 files:
 - LICENSE.txt
 - Rakefile
-- README.rdoc
+- README.md
 - lib/hair_trigger/adapter.rb
 - lib/hair_trigger/base.rb
 - lib/hair_trigger/builder.rb
@@ -208,7 +207,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.5
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.25
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: easy database triggers for active record

data/README.rdoc

@@ -1,289 +0,0 @@
-= HairTrigger
-{<img src="https://secure.travis-ci.org/jenseng/hair_trigger.png?branch=master" />}[http://travis-ci.org/jenseng/hair_trigger]
-
-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 or 4
-
-If you are using Rails 3 or 4, 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::Specification.find_by_name('hairtrigger').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
-
-* Ruby 1.8.7+
-* Rails 2.3+
-* Postgres 8.0+
-* MySQL 5.0.10+
-* SQLite 3.3.8+
-
-== Version History
-
-* 0.2.4 Rails 4 and Ruby 2 support
-* 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 (c) 2011-2013 Jon Jensen. See LICENSE.txt for further details.