pg_sql_triggers 1.3.0 → 1.5.0

data/lib/generators/pg_sql_triggers/trigger_generator.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+require "active_support/core_ext/string/inflections"
+
+module PgSqlTriggers
+  module Generators
+    class TriggerGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generates a pg_sql_triggers DSL file and migration for a new trigger."
+
+      argument :trigger_name, type: :string,
+                              desc: "Name of the trigger (e.g. notify_on_insert_users)"
+      argument :table_name, type: :string,
+                            desc: "Database table the trigger attaches to (e.g. users)"
+      argument :events, type: :array, default: ["insert"], banner: "EVENT ...",
+                        desc: "Trigger events: insert, update, delete (default: insert)"
+
+      class_option :timing, type: :string, default: "before",
+                            desc: "Trigger timing: before or after (default: before)"
+      class_option :function, type: :string,
+                              desc: "Function name (default: TRIGGER_NAME_function)"
+
+      def self.next_migration_number(_dirname)
+        existing = if Rails.root.join("db/triggers").exist?
+                     Rails.root.glob("db/triggers/*.rb")
+                          .map { |f| File.basename(f, ".rb").split("_").first.to_i }
+                          .reject(&:zero?)
+                          .max || 0
+                   else
+                     0
+                   end
+
+        now = Time.now.utc
+        base = now.strftime("%Y%m%d%H%M%S").to_i
+        base = existing + 1 if existing.positive? && base <= existing
+        base
+      end
+
+      def create_dsl_file
+        template "trigger_dsl.rb.tt", "app/triggers/#{trigger_name}.rb"
+      end
+
+      def create_migration_file
+        template "trigger_migration_full.rb.tt", "db/triggers/#{migration_file_name}.rb"
+      end
+
+      private
+
+      def function_name
+        options[:function].presence || "#{trigger_name}_function"
+      end
+
+      def timing
+        options[:timing]
+      end
+
+      def events_list
+        events.map { |e| ":#{e}" }.join(", ")
+      end
+
+      def events_sql
+        events.map(&:upcase).join(" OR ")
+      end
+
+      def trigger_class_name
+        "Add#{trigger_name.camelize}"
+      end
+
+      def migration_file_name
+        "#{migration_number}_#{trigger_name}"
+      end
+
+      def migration_number
+        self.class.next_migration_number(nil)
+      end
+    end
+  end
+end

data/lib/pg_sql_triggers/alerting.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module PgSqlTriggers
+  # Drift alerting: configurable callback when drift detection finds drifted, dropped, or unknown
+  # triggers. Use with +trigger:check_drift+ or +PgSqlTriggers::Alerting.check_and_notify+.
+  module Alerting
+    ALERTABLE_STATES = [
+      PgSqlTriggers::DRIFT_STATE_DRIFTED,
+      PgSqlTriggers::DRIFT_STATE_DROPPED,
+      PgSqlTriggers::DRIFT_STATE_UNKNOWN
+    ].freeze
+
+    class << self
+      # @param result [Hash] a single drift result from {Drift::Detector}
+      # @return [Boolean]
+      def alertable?(result)
+        ALERTABLE_STATES.include?(result[:state])
+      end
+
+      # @param results [Array<Hash>] drift results from {Drift::Detector.detect_all}
+      # @return [Array<Hash>]
+      def filter_alertable(results)
+        results.select { |r| alertable?(r) }
+      end
+
+      # Runs drift detection for all triggers, invokes +PgSqlTriggers.drift_notifier+ when configured
+      # and there is at least one alertable result, and emits +ActiveSupport::Notifications+ when
+      # available.
+      #
+      # The notifier receives one argument: an Array of alertable result hashes (same shape as
+      # {Drift::Detector}). For advanced use, a second keyword argument +all_results:+ is passed
+      # with the full result set.
+      #
+      # @return [Hash] +:results+ (all), +:alertable+ (subset), +:notified+ (Boolean)
+      def check_and_notify
+        results = PgSqlTriggers::Drift::Detector.detect_all
+        alertable = filter_alertable(results)
+        notified = false
+
+        payload = {
+          results: results,
+          alertable: alertable,
+          alertable_count: alertable.size,
+          total_count: results.size,
+          notified: false
+        }
+
+        instrument("pg_sql_triggers.drift_check", payload) do
+          if alertable.any? && PgSqlTriggers.drift_notifier
+            begin
+              PgSqlTriggers.drift_notifier.call(alertable, all_results: results)
+              notified = true
+            rescue StandardError => e
+              payload[:notifier_error] = e.message
+              if defined?(Rails.logger) && Rails.logger
+                Rails.logger.error("PgSqlTriggers drift_notifier failed: #{e.class}: #{e.message}")
+              end
+            end
+          end
+          payload[:notified] = notified
+        end
+
+        { results: results, alertable: alertable, notified: notified }
+      end
+
+      private
+
+      def instrument(name, payload, &block)
+        if defined?(ActiveSupport::Notifications)
+          ActiveSupport::Notifications.instrument(name, payload, &block)
+        else
+          block.call
+        end
+      end
+    end
+  end
+end

data/lib/pg_sql_triggers/deferral_checksum.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module PgSqlTriggers
+  # Normalizes deferrable / initially metadata for checksum calculation so
+  # {Registry::Manager}, {TriggerRegistry#calculate_checksum}, and {Drift::Detector}
+  # stay aligned with PostgreSQL's pg_trigger flags.
+  module DeferralChecksum
+    module_function
+
+    # @return [Array<String>] always three elements: constraint flag, deferrable mode, initially mode
+    def parts(constraint_trigger:, deferrable:, initially:)
+      constraint = ActiveModel::Type::Boolean.new.cast(constraint_trigger)
+      return ["0", "", ""] unless constraint
+
+      deferrable_sym =
+        if deferrable.nil? || deferrable.to_s.strip.empty?
+          nil
+        else
+          deferrable.to_sym
+        end
+
+      deferrable_key = deferrable_sym == :deferrable ? "deferrable" : "not_deferrable"
+
+      initially_key = if deferrable_key == "deferrable"
+                        case initially&.to_sym
+                        when :deferred then "deferred"
+                        else "immediate"
+                        end
+                      else
+                        ""
+                      end
+
+      ["1", deferrable_key, initially_key]
+    end
+
+    # @param db_trigger [Hash] row from {Drift::DbQueries} including tgconstraint, tgdeferrable, tginitdeferred
+    # @return [Array<String>] three elements matching {.parts}
+    def parts_from_db(db_trigger)
+      constraint = db_trigger["tgconstraint"].to_i.nonzero?
+      return ["0", "", ""] unless constraint
+
+      deferrable = ActiveModel::Type::Boolean.new.cast(db_trigger["tgdeferrable"])
+      deferrable_key = deferrable ? "deferrable" : "not_deferrable"
+
+      initially_key = if deferrable
+                        ActiveModel::Type::Boolean.new.cast(db_trigger["tginitdeferred"]) ? "deferred" : "immediate"
+                      else
+                        ""
+                      end
+
+      ["1", deferrable_key, initially_key]
+    end
+  end
+end

data/lib/pg_sql_triggers/drift/db_queries.rb

@@ -2,7 +2,7 @@
 
 module PgSqlTriggers
   module Drift
-    module DbQueries
+    module DbQueries # rubocop:disable Metrics/ModuleLength -- trigger introspection SQL in one place
       class << self
         # Fetch all triggers from database
         def all_triggers
@@ -16,18 +16,21 @@ module PgSqlTriggers
               pg_get_triggerdef(t.oid) AS trigger_definition,
               pg_get_functiondef(p.oid) AS function_definition,
               t.tgenabled AS enabled,
-              t.tgisinternal AS is_internal
+              t.tgisinternal AS is_internal,
+              t.tgconstraint AS tgconstraint,
+              t.tgdeferrable AS tgdeferrable,
+              t.tginitdeferred AS tginitdeferred
             FROM pg_trigger t
             JOIN pg_class c ON t.tgrelid = c.oid
             JOIN pg_namespace n ON c.relnamespace = n.oid
             JOIN pg_proc p ON t.tgfoid = p.oid
             WHERE NOT t.tgisinternal
-              AND n.nspname = 'public'
+              AND n.nspname = $1
               AND t.tgname NOT LIKE 'RI_%'
             ORDER BY c.relname, t.tgname;
           SQL
 
-          execute_query(sql)
+          execute_query(sql, [schema_name])
         end
 
         # Fetch single trigger
@@ -42,17 +45,20 @@ module PgSqlTriggers
               pg_get_triggerdef(t.oid) AS trigger_definition,
               pg_get_functiondef(p.oid) AS function_definition,
               t.tgenabled AS enabled,
-              t.tgisinternal AS is_internal
+              t.tgisinternal AS is_internal,
+              t.tgconstraint AS tgconstraint,
+              t.tgdeferrable AS tgdeferrable,
+              t.tginitdeferred AS tginitdeferred
             FROM pg_trigger t
             JOIN pg_class c ON t.tgrelid = c.oid
             JOIN pg_namespace n ON c.relnamespace = n.oid
             JOIN pg_proc p ON t.tgfoid = p.oid
             WHERE t.tgname = $1
               AND NOT t.tgisinternal
-              AND n.nspname = 'public';
+              AND n.nspname = $2;
           SQL
 
-          result = execute_query(sql, [trigger_name])
+          result = execute_query(sql, [trigger_name, schema_name])
           result.first
         end
 
@@ -68,19 +74,22 @@ module PgSqlTriggers
               pg_get_triggerdef(t.oid) AS trigger_definition,
               pg_get_functiondef(p.oid) AS function_definition,
               t.tgenabled AS enabled,
-              t.tgisinternal AS is_internal
+              t.tgisinternal AS is_internal,
+              t.tgconstraint AS tgconstraint,
+              t.tgdeferrable AS tgdeferrable,
+              t.tginitdeferred AS tginitdeferred
             FROM pg_trigger t
             JOIN pg_class c ON t.tgrelid = c.oid
             JOIN pg_namespace n ON c.relnamespace = n.oid
             JOIN pg_proc p ON t.tgfoid = p.oid
             WHERE c.relname = $1
               AND NOT t.tgisinternal
-              AND n.nspname = 'public'
+              AND n.nspname = $2
               AND t.tgname NOT LIKE 'RI_%'
             ORDER BY t.tgname;
           SQL
 
-          execute_query(sql, [table_name])
+          execute_query(sql, [table_name, schema_name])
         end
 
         # Fetch function body by function name
@@ -92,15 +101,19 @@ module PgSqlTriggers
             FROM pg_proc p
             JOIN pg_namespace n ON p.pronamespace = n.oid
             WHERE p.proname = $1
-              AND n.nspname = 'public';
+              AND n.nspname = $2;
           SQL
 
-          result = execute_query(sql, [function_name])
+          result = execute_query(sql, [function_name, schema_name])
           result.first
         end
 
         private
 
+        def schema_name
+          PgSqlTriggers.db_schema.to_s
+        end
+
         def execute_query(sql, params = [])
           if params.any?
             # Use ActiveRecord's connection to execute parameterized queries
@@ -111,6 +124,6 @@ module PgSqlTriggers
           end
         end
       end
-    end
+    end # rubocop:enable Metrics/ModuleLength
   end
 end

data/lib/pg_sql_triggers/drift/detector.rb

@@ -11,27 +11,7 @@ module PgSqlTriggers
         def detect(trigger_name)
           registry_entry = TriggerRegistry.find_by(trigger_name: trigger_name)
           db_trigger = DbQueries.find_trigger(trigger_name)
-
-          # State 1: DISABLED - Registry entry disabled
-          return disabled_state(registry_entry, db_trigger) if registry_entry&.enabled == false
-
-          # State 2: MANUAL_OVERRIDE - Marked as manual SQL
-          return manual_override_state(registry_entry, db_trigger) if registry_entry&.source == "manual_sql"
-
-          # State 3: DROPPED - Registry entry exists, DB trigger missing
-          return dropped_state(registry_entry) if registry_entry && !db_trigger
-
-          # State 4: UNKNOWN - DB trigger exists, no registry entry
-          return unknown_state(db_trigger) if !registry_entry && db_trigger
-
-          # State 5: DRIFTED - Checksum mismatch
-          if registry_entry && db_trigger
-            checksum_match = checksums_match?(registry_entry, db_trigger)
-            return drifted_state(registry_entry, db_trigger) unless checksum_match
-          end
-
-          # State 6: IN_SYNC - Everything matches
-          in_sync_state(registry_entry, db_trigger)
+          detect_with_preloaded(registry_entry, db_trigger)
         end
 
         # Detect drift for all triggers
@@ -39,13 +19,14 @@ module PgSqlTriggers
           registry_entries = TriggerRegistry.all.to_a
           db_triggers = DbQueries.all_triggers
 
-          # Check each registry entry
+          db_trigger_map = db_triggers.index_by { |t| t["trigger_name"] }
+
           results = registry_entries.map do |entry|
-            detect(entry.trigger_name)
+            detect_with_preloaded(entry, db_trigger_map[entry.trigger_name])
           end
 
           # Find unknown (external) triggers not in registry
-          registry_trigger_names = registry_entries.map(&:trigger_name)
+          registry_trigger_names = registry_entries.to_set(&:trigger_name)
           db_triggers.each do |db_trigger|
             next if registry_trigger_names.include?(db_trigger["trigger_name"])
 
@@ -60,13 +41,14 @@ module PgSqlTriggers
           registry_entries = TriggerRegistry.for_table(table_name).to_a
           db_triggers = DbQueries.find_triggers_for_table(table_name)
 
-          # Check each registry entry for this table
+          db_trigger_map = db_triggers.index_by { |t| t["trigger_name"] }
+
           results = registry_entries.map do |entry|
-            detect(entry.trigger_name)
+            detect_with_preloaded(entry, db_trigger_map[entry.trigger_name])
           end
 
           # Find unknown triggers on this table
-          registry_trigger_names = registry_entries.map(&:trigger_name)
+          registry_trigger_names = registry_entries.to_set(&:trigger_name)
           db_triggers.each do |db_trigger|
             next if registry_trigger_names.include?(db_trigger["trigger_name"])
 
@@ -78,6 +60,20 @@ module PgSqlTriggers
 
         private
 
+        # Core state computation using pre-loaded data — no additional DB queries.
+        def detect_with_preloaded(registry_entry, db_trigger)
+          return disabled_state(registry_entry, db_trigger) if registry_entry&.enabled == false
+          return manual_override_state(registry_entry, db_trigger) if registry_entry&.source == "manual_sql"
+          return dropped_state(registry_entry) if registry_entry && !db_trigger
+          return unknown_state(db_trigger) if !registry_entry && db_trigger
+
+          if registry_entry && db_trigger && !checksums_match?(registry_entry, db_trigger)
+            return drifted_state(registry_entry, db_trigger)
+          end
+
+          in_sync_state(registry_entry, db_trigger)
+        end
+
         # Compare registry checksum with calculated DB checksum
         def checksums_match?(registry_entry, db_trigger)
           db_checksum = calculate_db_checksum(registry_entry, db_trigger)
@@ -86,32 +82,47 @@ module PgSqlTriggers
 
         # Calculate checksum from DB trigger (must match registry algorithm)
         def calculate_db_checksum(registry_entry, db_trigger)
-          # Extract function body from the function definition
-          function_body = extract_function_body(db_trigger)
+          function_body = if registry_entry.source == "dsl"
+                            db_trigger["function_definition"] || ""
+                          else
+                            extract_function_body(db_trigger) || ""
+                          end
 
-          # Extract condition from trigger definition
+          # Extract condition and for_each granularity from trigger definition
           condition = extract_trigger_condition(db_trigger)
+          db_for_each = extract_trigger_for_each(db_trigger)
+
+          deferral = PgSqlTriggers::DeferralChecksum.parts_from_db(db_trigger)
+
+          events_segment = PgSqlTriggers::EventsChecksum.canonical_from_pg_triggerdef(
+            db_trigger["trigger_definition"]
+          )
 
           # Use same algorithm as TriggerRegistry#calculate_checksum
           Digest::SHA256.hexdigest([
             registry_entry.trigger_name,
             registry_entry.table_name,
             registry_entry.version,
-            function_body || "",
-            condition || ""
+            function_body,
+            condition || "",
+            registry_entry.timing || "before",
+            db_for_each || "row",
+            events_segment,
+            *deferral
           ].join)
         end
 
-        # Extract function body from pg_get_functiondef output
+        # Extract just the PL/pgSQL body from pg_get_functiondef output.
+        # pg_get_functiondef() returns the full CREATE OR REPLACE FUNCTION statement;
+        # we extract only the content between the dollar-quote delimiters so the
+        # comparison is format-agnostic (handles $$ and $function$ styles).
         def extract_function_body(db_trigger)
           function_def = db_trigger["function_definition"]
           return nil unless function_def
 
-          # The function definition includes CREATE OR REPLACE FUNCTION header
-          # We need to extract just the body for comparison
-          # For now, return the full definition
-          # TODO: Parse and extract just the body if needed
-          function_def
+          # Match any dollar-quoted string: $tag$body$tag$ (tag may be empty)
+          match = function_def.match(/\$([^$]*)\$(.*?)\$\1\$/m)
+          match ? match[2].strip : function_def.strip
         end
 
         # Extract WHEN condition from trigger definition
@@ -125,6 +136,16 @@ module PgSqlTriggers
           match ? match[1].strip : nil
         end
 
+        # Extract FOR EACH ROW / FOR EACH STATEMENT from trigger definition.
+        # Returns "row" or "statement" (lowercase). Defaults to "row".
+        def extract_trigger_for_each(db_trigger)
+          trigger_def = db_trigger["trigger_definition"]
+          return "row" unless trigger_def
+
+          match = trigger_def.match(/FOR\s+EACH\s+(ROW|STATEMENT)/i)
+          match ? match[1].downcase : "row"
+        end
+
         # State helper methods
         def disabled_state(registry_entry, db_trigger)
           {

data/lib/pg_sql_triggers/drift.rb

@@ -23,5 +23,10 @@ module PgSqlTriggers
     def self.report(trigger_name)
       Reporter.report(trigger_name)
     end
+
+    # Runs full drift detection and optional external notification; see {PgSqlTriggers::Alerting}.
+    def self.check_and_notify
+      Alerting.check_and_notify
+    end
   end
 end

data/lib/pg_sql_triggers/dsl/trigger_definition.rb

@@ -3,16 +3,34 @@
 module PgSqlTriggers
   module DSL
     class TriggerDefinition
-      attr_accessor :name, :table_name, :events, :function_name, :environments, :condition
+      attr_accessor :name, :table_name, :events, :function_name, :environments, :condition, :version, :enabled,
+                    :columns, :deferrable, :initially
+      attr_reader :timing, :for_each
 
       def initialize(name)
         @name = name
         @events = []
         @version = 1
-        @enabled = false
+        @enabled = true
         @environments = []
         @condition = nil
         @timing = "before"
+        @for_each = "row"
+        @columns = nil
+        @constraint_trigger = false
+        @deferrable = nil
+        @initially = nil
+        @depends_on = []
+      end
+
+      # Intentionally not named `constraint_trigger?` — matches registry column and JSON key.
+      # The setter always casts to a boolean, and the initial value is `false`, so this returns
+      # the stored value directly without coercion.
+      attr_reader :constraint_trigger
+
+      def constraint_trigger=(value)
+        @constraint_trigger = ActiveModel::Type::Boolean.new.cast(value)
+        clear_deferral unless @constraint_trigger
       end
 
       def table(table_name)
@@ -21,29 +39,38 @@ module PgSqlTriggers
 
       def on(*events)
         @events = events.map(&:to_s)
+        @columns = nil
+      end
+
+      def on_update_of(*cols)
+        @events = ["update"]
+        @columns = cols.map(&:to_s)
       end
 
       def function(function_name)
         @function_name = function_name
       end
 
-      def version(version = nil)
-        if version.nil?
-          @version
-        else
-          @version = version
-        end
+      def timing=(val)
+        @timing = val.to_s
       end
 
-      def enabled(enabled = nil)
-        if enabled.nil?
-          @enabled
-        else
-          @enabled = enabled
-        end
+      def constraint_trigger!
+        self.constraint_trigger = true
+      end
+
+      def for_each_row
+        @for_each = "row"
+      end
+
+      def for_each_statement
+        @for_each = "statement"
       end
 
       def when_env(*environments)
+        warn "[DEPRECATION] `when_env` is deprecated and will be removed in a future version. " \
+             "Environment-specific trigger behavior causes schema drift between environments. " \
+             "Use application-level configuration instead."
         @environments = environments.map(&:to_s)
       end
 
@@ -51,14 +78,22 @@ module PgSqlTriggers
         @condition = condition_sql
       end
 
-      def timing(timing_value = nil)
-        if timing_value.nil?
-          @timing
-        else
-          @timing = timing_value.to_s
+      # Declares that this trigger must run after the named trigger(s) on the same table.
+      # PostgreSQL executes same-kind triggers in alphabetical order by name; use naming or
+      # validate with Registry.validate! / rake trigger:validate_order.
+      def depends_on(*names)
+        names.flatten.compact.each do |entry|
+          label = entry.to_s.strip
+          next if label.empty?
+
+          @depends_on << label unless @depends_on.include?(label)
         end
       end
 
+      def depends_on_names
+        @depends_on.dup
+      end
+
       def function_body
         nil # DSL definitions don't include function_body directly
       end
@@ -73,9 +108,22 @@ module PgSqlTriggers
           enabled: @enabled,
           environments: @environments,
           condition: @condition,
-          timing: @timing
+          timing: @timing,
+          for_each: @for_each,
+          columns: @columns,
+          constraint_trigger: @constraint_trigger == true,
+          deferrable: @deferrable&.to_s,
+          initially: @initially&.to_s,
+          depends_on: @depends_on.dup
         }
       end
+
+      private
+
+      def clear_deferral
+        @deferrable = nil
+        @initially = nil
+      end
     end
   end
 end