hairtrigger 0.1.2 → 0.1.3

data/Gemfile

@@ -1,7 +1,7 @@
 source "http://rubygems.org"
 gem "activerecord", ">=2.3.0", "<3.0"
 group :development do
-  gem "rspec", ">= 2.3.0"
+  gem "rspec", "~> 2.3.0"
   gem "bundler", "~> 1.0.0"
   gem "jeweler", "~> 1.5.2"
   gem "rcov", ">= 0"

data/README.rdoc

@@ -1,23 +1,32 @@
 = HairTrigger
 
 HairTrigger lets you create and manage database triggers in a concise,
-db-agnostic, Rails-y way.
+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.
 
 == Install
 
-Assuming you're using bundler:
+=== Step 1.
 
-1. install the gem
-2. let rails know about it (via Gemfile, environment.rb, whatever)
-3. create lib/tasks/hair_trigger.rake with the following:
+If you are using bundler, just put hairtrigger in your Gemfile. 
+
+If you're not using bundler, you can "gem install hairtrigger" and then put 
+hairtrigger in environment.rb
+
+=== Step 2.
+
+If you plan to use model triggers (which you should ;) you'll need to 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 }
 
-An alternative to steps 2 and 3 is to unpack it in vendor/plugins and delete
-its Gemfile.
+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:
@@ -33,34 +42,69 @@ and then:
  rake db:generate_trigger_migration
 
 This will create a db-agnostic migration for the trigger that mirrors the
-model declaration. You can also manage triggers manually in your migrations
-(via create_trigger/drop_trigger), though that ends up being more work.
-
-Note that these auto-generated create_trigger statements 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 from previous migrations.
+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 from previous migrations.
+
+=== 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. An sample trigger:
+
+ create_trigger.on(:users).after(:insert) do
+   "UPDATE accounts SET user_count = user_count + 1 WHERE id = NEW.account_id;"
+ end
 
-== Chainable Methods
+=== 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/MySQL allow :statement.
-* before(*events): Shorthand for timing(:before).events(*events).
-* after(*events): Shorthand for timing(:after).events(*events).
-* where(conditions): Optional, limits when the trigger will fire.
-* 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). MySQL/SQLite only support one action.
-* all: Noop, useful for trigger groups (see below).
+==== name(trigger_name)
+Optional, inferred from other calls.
+
+==== on(table_name)
+Ignored in models, required in migrations.
+
+==== for_each(item)
+Defaults to :row, PostgreSQL/MySQL allow :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.
 
-== Trigger Groups
+==== 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,
@@ -96,10 +140,27 @@ create.
 
 == Warnings and Errors
 
-If you try something your adapter doesn't support (e.g. multiple triggering
-events for MySQL), you will get an error. If your adapter does support it, you
-will just get a warning to let you know your trigger is not portable. You can
-silence warnings via `HairTrigger::Builder.show_warnings = false`
+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 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 approriate 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 database
 you want to support.
@@ -125,10 +186,17 @@ you want to support.
 == Compatibility
 
 * Rails 2.3.x
-* Postgres 9.0+
+* Postgres 8.0+
 * MySQL 5.0+
 * SQLite 3.0+
 
+== Version History
+
+* 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 Jon Jensen. See LICENSE.txt for further details.

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.1.3

data/lib/hair_trigger/builder.rb

@@ -1,13 +1,17 @@
 module HairTrigger
   class Builder
+    class DeclarationError < StandardError; end
+    class GenerationError < StandardError; end
+  
     attr_accessor :options
     attr_reader :triggers # nil unless this is a trigger group
     attr_reader :prepared_actions, :prepared_where # after delayed interpolation
 
     def initialize(name = nil, options = {})
-      @adapter = options[:adapter] || ActiveRecord::Base.connection rescue nil
+      @adapter = options[:adapter]
       @options = {}
       @chained_calls = []
+      @errors = []
       set_name(name) if name
       {:timing => :after, :for_each => :row}.update(options).each do |key, value|
         if respond_to?("set_#{key}")
@@ -22,6 +26,7 @@ module HairTrigger
       @trigger_group = other
       @triggers = nil
       @chained_calls = []
+      @errors = []
       @options = @options.dup
       @options.delete(:name) # this will be inferred (or set further down the line)
       @options.each do |key, value|
@@ -34,18 +39,18 @@ module HairTrigger
     end
 
     def name(name)
-      raise_or_warn "trigger name cannot exceed 63 for postgres", :postgresql if name.to_s.size > 63
+      @errors << ["trigger name cannot exceed 63 for postgres", :postgresql] if name.to_s.size > 63
       options[:name] = name.to_s
     end
 
     def on(table)
-      raise "table has already been specified" if options[:table]
+      raise DeclarationError, "table has already been specified" if options[:table]
       options[:table] = table.to_s
     end
 
     def for_each(for_each)
-      raise_or_warn "sqlite doesn't support FOR EACH STATEMENT triggers", :sqlite if for_each == :statement
-      raise "invalid for_each" unless [:row, :statement].include?(for_each)
+      @errors << ["sqlite doesn't support FOR EACH STATEMENT triggers", :sqlite] if for_each == :statement
+      raise DeclarationError, "invalid for_each" unless [:row, :statement].include?(for_each)
       options[:for_each] = for_each.to_s.upcase
     end
 
@@ -68,27 +73,27 @@ module HairTrigger
     end
 
     def security(user)
-      # sqlite default is n/a, mysql default is :definer, postgres default is :invoker
-      raise_or_warn "sqlite doesn't support trigger security", :sqlite
-      raise_or_warn "postgresql doesn't support arbitrary users for trigger security", :postgresql unless [:definer, :invoker].include?(user)
-      if user == :invoker
-        raise_or_warn "mysql doesn't support invoker trigger security", :mysql
-      elsif user != :definer && !(user.to_s =~ /\A'[^']+'@'[^']+'\z/) && !(user.to_s.downcase =~ /\Acurrent_user(\(\))?\z/)
-        raise_or_warn "mysql trigger security should be :definer, CURRENT_USER, or a valid mysql user (e.g. 'user'@'host')", :mysql
+      unless [:invoker, :definer].include?(user) || user.to_s =~ /\A'[^']+'@'[^']+'\z/ || user.to_s.downcase =~ /\Acurrent_user(\(\))?\z/
+        raise DeclarationError, "trigger security should be :invoker, :definer, CURRENT_USER, or a valid user (e.g. 'user'@'host')"
       end
+      # sqlite default is n/a, mysql default is :definer, postgres default is :invoker
+      @errors << ["sqlite doesn't support trigger security", :sqlite]
+      @errors << ["postgresql doesn't support arbitrary users for trigger security", :postgresql] unless [:definer, :invoker].include?(user)
+      @errors << ["mysql doesn't support invoker trigger security", :mysql] if user == :invoker
       options[:security] = user
     end
 
     def timing(timing)
-      raise "invalid timing" unless [:before, :after].include?(timing)
+      raise DeclarationError, "invalid timing" unless [:before, :after].include?(timing)
       options[:timing] = timing.to_s.upcase
     end
 
     def events(*events)
       events << :insert if events.delete(:create)
       events << :delete if events.delete(:destroy)
-      raise "invalid events" unless events & [:insert, :update, :delete] == events
-      raise_or_warn "sqlite and mysql triggers may not be shared by multiple actions", :mysql, :sqlite if events.size > 1
+      raise DeclarationError, "invalid events" unless events & [:insert, :update, :delete, :truncate] == events
+      @errors << ["sqlite and mysql triggers may not be shared by multiple actions", :mysql, :sqlite] if events.size > 1
+      @errors << ["sqlite and mysql do not support truncate triggers", :mysql, :sqlite] if events.include?(:truncate)
       options[:events] = events.map{ |e| e.to_s.upcase }
     end
 
@@ -107,7 +112,7 @@ module HairTrigger
           def #{method}(*args)
             @chained_calls << :#{method}
             if @triggers || @trigger_group
-              raise_or_warn "mysql doesn't support #{method} within a trigger group", :mysql unless [:name, :where, :all].include?(:#{method})
+              @errors << ["mysql doesn't support #{method} within a trigger group", :mysql] unless [:name, :where, :all].include?(:#{method})
             end
             set_#{method}(*args, &(block_given? ? Proc.new : nil))
           end
@@ -138,16 +143,31 @@ module HairTrigger
       @prepared_actions = interpolate(@actions).rstrip if @actions
     end
 
-    def generate
-      return @triggers.map(&:generate).flatten if @triggers && !create_grouped_trigger?
+    def validate!(direction = :down)
+      @errors.each do |(error, *adapters)|
+        raise GenerationError, error if adapters.include?(adapter_name)
+        $stderr.puts "WARNING: " + message if self.class.show_warnings
+      end
+      if direction != :up
+        @triggers.each{ |t| t.validate!(:down) } if @triggers
+      end
+      if direction != :down
+        @trigger_group.validate!(:up) if @trigger_group
+      end
+    end
+
+    def generate(validate = true)
+      validate!(@trigger_group ? :both : :down) if validate
+
+      return @triggers.map{ |t| t.generate(false) }.flatten if @triggers && !create_grouped_trigger?
       prepare!
-      raise "need to specify the table" unless options[:table]
+      raise GenerationError, "need to specify the table" unless options[:table]
       if options[:drop]
         generate_drop_trigger
       else
-        raise "no actions specified" if @triggers && create_grouped_trigger? ? @triggers.any?{ |t| t.prepared_actions.nil? } : prepared_actions.nil?
-        raise "need to specify the event(s) (:insert, :update, :delete)" if !options[:events] || options[:events].empty?
-        raise "need to specify the timing (:before/:after)" unless options[:timing]
+        raise GenerationError, "no actions specified" if @triggers && create_grouped_trigger? ? @triggers.any?{ |t| t.prepared_actions.nil? } : prepared_actions.nil?
+        raise GenerationError, "need to specify the event(s) (:insert, :update, :delete)" if !options[:events] || options[:events].empty?
+        raise GenerationError, "need to specify the timing (:before/:after)" unless options[:timing]
 
         ret = [generate_drop_trigger]
         ret << case adapter_name
@@ -158,7 +178,7 @@ module HairTrigger
           when :postgresql
             generate_trigger_postgresql
           else
-            raise "don't know how to build #{adapter_name} triggers yet"
+            raise GenerationError, "don't know how to build #{adapter_name} triggers yet"
         end
         ret
       end
@@ -203,6 +223,10 @@ module HairTrigger
       [self.options.hash, self.prepared_actions.hash, self.prepared_where.hash, self.triggers.hash].hash
     end
 
+    def errors
+      (@triggers || []).inject(@errors){ |errors, t| errors + t.errors }
+    end
+
     private
 
     def chained_calls_to_ruby(join_str = '.')
@@ -230,21 +254,25 @@ module HairTrigger
 
     def maybe_execute(&block)
       if block.arity > 0 # we're creating a trigger group, so set up some stuff and pass the buck
-        raise_or_warn "trigger group must specify timing and event(s)", :mysql unless options[:timing] && options[:events]
-        raise_or_warn "nested trigger groups are not supported for mysql", :mysql if create_grouped_trigger? && @trigger_group
+        @errors << ["trigger group must specify timing and event(s) for mysql", :mysql] unless options[:timing] && options[:events]
+        @errors << ["nested trigger groups are not supported for mysql", :mysql] if @trigger_group
         @triggers = []
         block.call(self)
-        raise "trigger group did not define any triggers" if @triggers.empty?
+        raise DeclarationError, "trigger group did not define any triggers" if @triggers.empty?
       else
         @actions = block.call
       end
       # only the top-most block actually executes
-      Array(generate).each{ |action| @adapter.execute(action)} if options[:execute] && !@trigger_group
+      Array(generate).each{ |action| adapter.execute(action)} if options[:execute] && !@trigger_group
       self
     end
 
     def adapter_name
-      @adapter_name ||= @adapter.adapter_name.downcase.to_sym
+      @adapter_name ||= adapter.adapter_name.downcase.to_sym
+    end
+
+    def adapter
+      @adapter ||= ActiveRecord::Base.connection
     end
 
     def infer_name
@@ -264,7 +292,7 @@ module HairTrigger
         when :postgresql
           "DROP TRIGGER IF EXISTS #{prepared_name} ON #{options[:table]};\nDROP FUNCTION IF EXISTS #{prepared_name}();\n"
         else
-          raise "don't know how to drop #{adapter_name} triggers yet"
+          raise GenerationError, "don't know how to drop #{adapter_name} triggers yet"
       end
     end
 
@@ -279,16 +307,26 @@ END;
     end
 
     def generate_trigger_postgresql
+      raise GenerationError, "truncate triggers are only supported on postgres 8.4 and greater" if version < 80400 && options[:events].include?('TRUNCATE')
+      raise GenerationError, "FOR EACH ROW triggers may not be triggered by truncate events" if options[:for_each] == 'ROW' && options[:events].include?('TRUNCATE')
       security = options[:security] if options[:security] && options[:security] != :invoker
-      <<-SQL
+      sql = <<-SQL
 CREATE FUNCTION #{prepared_name}()
 RETURNS TRIGGER AS $$
 BEGIN
-#{normalize(prepared_actions, 1).rstrip}
+      SQL
+      if prepared_where && version < 90000
+        sql << normalize("IF #{prepared_where} THEN", 1)
+        sql << normalize(prepared_actions, 2)
+        sql << normalize("END IF;", 1)
+      else
+        sql << normalize(prepared_actions, 1)
+      end
+      sql << <<-SQL
 END;
 $$ LANGUAGE plpgsql#{security ? " SECURITY #{security.to_s.upcase}" : ""};
 CREATE TRIGGER #{prepared_name} #{options[:timing]} #{options[:events].join(" OR ")} ON #{options[:table]}
-FOR EACH #{options[:for_each]}#{prepared_where ? " WHEN (" + prepared_where + ')': ''} EXECUTE PROCEDURE #{prepared_name}();
+FOR EACH #{options[:for_each]}#{prepared_where && version >= 90000 ? " WHEN (" + prepared_where + ')': ''} EXECUTE PROCEDURE #{prepared_name}();
       SQL
     end
 
@@ -311,6 +349,13 @@ BEGIN
       sql << "END\n";
     end
 
+    def version
+      @version ||= case adapter_name
+        when :postgresql
+          adapter.send(:postgresql_version)
+      end
+    end
+
     def interpolate(str)
       eval("%@#{str.gsub('@', '\@')}@")
     end
@@ -327,14 +372,6 @@ BEGIN
       text.rstrip + "\n"
     end
 
-    def raise_or_warn(message, *adapters)
-      if adapters.include?(adapter_name)
-        raise message
-      else
-        $stderr.puts "WARNING: " + message if self.class.show_warnings
-      end
-    end
-
     class << self
       attr_writer :tab_spacing
       attr_writer :show_warnings

data/spec/builder_spec.rb

@@ -5,8 +5,11 @@ HairTrigger::Builder.show_warnings = false
 
 class MockAdapter
   attr_reader :adapter_name
-  def initialize(type)
+  def initialize(type, methods = {})
     @adapter_name = type
+    methods.each do |key, value|
+      instance_eval("def #{key}; #{value.inspect}; end")
+    end
   end
 end
 
@@ -42,7 +45,7 @@ describe "builder" do
             t.where('BAR'){ 'BAR' }
             t.where('BAZ'){ 'BAZ' }
           }
-        }
+        }.generate
       }.should raise_error
     end
 
@@ -56,19 +59,27 @@ describe "builder" do
     end
 
     it "should reject :invoker security" do
-      lambda { builder.on(:foos).after(:update).security(:invoker){ "FOO" } }.
-        should raise_error
+      lambda {
+        builder.on(:foos).after(:update).security(:invoker){ "FOO" }.generate
+      }.should raise_error
     end
 
-    it "should reject multiple timings" do
-      lambda { builder.on(:foos).after(:update, :delete){ "FOO" } }.
-        should raise_error
+    it "should reject multiple events" do
+      lambda {
+        builder.on(:foos).after(:update, :delete){ "FOO" }.generate
+      }.should raise_error
+    end
+
+    it "should reject truncate" do
+      lambda {
+        builder.on(:foos).after(:truncate){ "FOO" }.generate
+      }.should raise_error
     end
   end
 
   context "postgresql" do
     before(:each) do
-      @adapter = MockAdapter.new("postgresql")
+      @adapter = MockAdapter.new("postgresql", :postgresql_version => 90000)
     end
 
     it "should create multiple triggers for a group" do
@@ -98,18 +109,47 @@ describe "builder" do
     end
 
     it "should reject arbitrary user security" do
-      lambda { builder.on(:foos).after(:update).security("'user'@'host'"){ "FOO" } }.
-        should raise_error
+      lambda {
+        builder.on(:foos).after(:update).security("'user'@'host'"){ "FOO" }.
+        generate
+      }.should raise_error
     end
 
-    it "should accept multiple timings" do
+    it "should accept multiple events" do
       builder.on(:foos).after(:update, :delete){ "FOO" }.generate.
         grep(/UPDATE OR DELETE/).size.should eql(1)
     end
 
     it "should reject long names" do
-      lambda { builder.name('A'*65).on(:foos).after(:update){ "FOO" }}.
-        should raise_error
+      lambda {
+        builder.name('A'*65).on(:foos).after(:update){ "FOO" }.generate
+      }.should raise_error
+    end
+
+    it "should allow truncate with for_each statement" do
+      builder.on(:foos).after(:truncate).for_each(:statement){ "FOO" }.generate.
+      grep(/TRUNCATE.*FOR EACH STATEMENT/m).size.should eql(1)
+    end
+
+    it "should reject truncate with for_each row" do
+      lambda {
+        builder.on(:foos).after(:truncate){ "FOO" }.generate
+      }.should raise_error
+    end
+
+    context "legacy" do
+      it "should reject truncate pre-8.4" do
+        @adapter = MockAdapter.new("postgresql", :postgresql_version => 80300)
+        lambda {
+          builder.on(:foos).after(:truncate).for_each(:statement){ "FOO" }.generate
+        }.should raise_error
+      end
+
+      it "should use conditionals pre-9.0" do
+        @adapter = MockAdapter.new("postgresql", :postgresql_version => 80400)
+        builder.on(:foos).after(:insert).where("BAR"){ "FOO" }.generate.
+        grep(/IF BAR/).size.should eql(1)
+      end
     end
   end
 
@@ -138,18 +178,27 @@ describe "builder" do
     end
 
     it "should reject security" do
-      lambda { builder.on(:foos).after(:update).security(:definer){ "FOO" } }.
-        should raise_error
+      lambda {
+        builder.on(:foos).after(:update).security(:definer){ "FOO" }.generate
+      }.should raise_error
     end
 
     it "should reject for_each :statement" do
-      lambda { builder.on(:foos).after(:update).for_each(:statement){ "FOO" } }.
-        should raise_error
+      lambda {
+        builder.on(:foos).after(:update).for_each(:statement){ "FOO" }.generate
+      }.should raise_error
+    end
+
+    it "should reject multiple events" do
+      lambda {
+        builder.on(:foos).after(:update, :delete){ "FOO" }.generate
+      }.should raise_error
     end
 
-    it "should reject multiple timings" do
-      lambda { builder.on(:foos).after(:update, :delete){ "FOO" } }.
-        should raise_error
+    it "should reject truncate" do
+      lambda {
+        builder.on(:foos).after(:truncate){ "FOO" }.generate
+      }.should raise_error
     end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: hairtrigger
 version: !ruby/object:Gem::Version 
-  hash: 31
+  hash: 29
   prerelease: 
   segments: 
   - 0
   - 1
-  - 2
-  version: 0.1.2
+  - 3
+  version: 0.1.3
 platform: ruby
 authors: 
 - Jon Jensen
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-23 00:00:00 -06:00
+date: 2011-03-24 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -45,7 +45,7 @@ dependencies:
   requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
-    - - ">="
+    - - ~>
       - !ruby/object:Gem::Version 
         hash: 3
         segments: