pg_sql_triggers 1.4.0 → 1.5.0

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,7 +16,10 @@ 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
@@ -42,7 +45,10 @@ 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
@@ -68,7 +74,10 @@ 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
@@ -115,6 +124,6 @@ module PgSqlTriggers
           end
         end
       end
-    end
+    end # rubocop:enable Metrics/ModuleLength
   end
 end

data/lib/pg_sql_triggers/drift/detector.rb

@@ -92,6 +92,12 @@ module PgSqlTriggers
           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,
@@ -100,7 +106,9 @@ module PgSqlTriggers
             function_body,
             condition || "",
             registry_entry.timing || "before",
-            db_for_each || "row"
+            db_for_each || "row",
+            events_segment,
+            *deferral
           ].join)
         end
 

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,7 +3,8 @@
 module PgSqlTriggers
   module DSL
     class TriggerDefinition
-      attr_accessor :name, :table_name, :events, :function_name, :environments, :condition, :version, :enabled
+      attr_accessor :name, :table_name, :events, :function_name, :environments, :condition, :version, :enabled,
+                    :columns, :deferrable, :initially
       attr_reader :timing, :for_each
 
       def initialize(name)
@@ -15,6 +16,21 @@ module PgSqlTriggers
         @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)
@@ -23,6 +39,12 @@ 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)
@@ -33,6 +55,10 @@ module PgSqlTriggers
         @timing = val.to_s
       end
 
+      def constraint_trigger!
+        self.constraint_trigger = true
+      end
+
       def for_each_row
         @for_each = "row"
       end
@@ -52,6 +78,22 @@ module PgSqlTriggers
         @condition = condition_sql
       end
 
+      # 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
@@ -67,9 +109,21 @@ module PgSqlTriggers
           environments: @environments,
           condition: @condition,
           timing: @timing,
-          for_each: @for_each
+          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

data/lib/pg_sql_triggers/engine.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "schema_dumper_extension"
+require_relative "trigger_structure_dumper"
+
 module PgSqlTriggers
   class Engine < ::Rails::Engine
     isolate_namespace PgSqlTriggers
@@ -26,10 +29,20 @@ module PgSqlTriggers
       load root.join("lib/tasks/trigger_migrations.rake")
     end
 
+    initializer "pg_sql_triggers.schema_integration", before: :load_config_initializers do
+      ActiveSupport.on_load(:active_record) do
+        unless ActiveRecord::SchemaDumper.ancestors.include?(PgSqlTriggers::SchemaDumperExtension)
+          ActiveRecord::SchemaDumper.prepend(PgSqlTriggers::SchemaDumperExtension)
+        end
+      end
+    end
+
     # Warn at startup if no permission_checker is set in a protected environment.
     # The default is to allow all actions (including admin-level ones), which is
     # unsafe in production without an explicit checker configured.
     config.after_initialize do
+      install_schema_load_trigger_hook
+
       if PgSqlTriggers.permission_checker.nil? && defined?(Rails) && Rails.env.production?
         Rails.logger.warn(
           "[PgSqlTriggers] SECURITY WARNING: No permission_checker is configured. " \
@@ -39,5 +52,27 @@ module PgSqlTriggers
         )
       end
     end
+
+    def self.install_schema_load_trigger_hook
+      return if @schema_load_trigger_hook_installed
+      return unless PgSqlTriggers.migrate_triggers_after_schema_load
+      return if ENV["SKIP_TRIGGER_MIGRATE_AFTER_SCHEMA_LOAD"].present?
+      return unless defined?(Rake::Task)
+
+      if defined?(Rails.application) && Rails.application.respond_to?(:load_tasks)
+        Rails.application.load_tasks
+      end
+
+      return unless Rake::Task.task_defined?("db:schema:load")
+
+      @schema_load_trigger_hook_installed = true
+
+      Rake::Task["db:schema:load"].enhance do
+        next unless PgSqlTriggers.migrate_triggers_after_schema_load
+        next if ENV["SKIP_TRIGGER_MIGRATE_AFTER_SCHEMA_LOAD"].present?
+
+        Rake::Task["trigger:migrate"].invoke
+      end
+    end
   end
 end

data/lib/pg_sql_triggers/events_checksum.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module PgSqlTriggers
+  # Normalizes trigger event lists (including PostgreSQL +UPDATE OF col1, col2+) for checksums so
+  # {TriggerRegistry#calculate_checksum}, {Registry::Manager#calculate_checksum}, and
+  # {Drift::Detector#calculate_db_checksum} stay aligned.
+  module EventsChecksum
+    module_function
+
+    # @param defn [Hash] parsed registry +definition+ JSON (string or symbol keys)
+    # @return [String] canonical token string, or empty when +events+ is missing/empty
+    def canonical_from_definition(defn)
+      hash = stringify(defn)
+      events = Array(hash["events"]).map(&:to_s).map(&:downcase)
+      return "" if events.empty?
+
+      columns = normalized_columns(hash["columns"])
+      build_tokens(events, columns).sort.join("|")
+    end
+
+    # @param definition_json [String, nil]
+    def segment_from_definition_json(definition_json)
+      return "" if definition_json.blank?
+
+      canonical_from_definition(JSON.parse(definition_json))
+    rescue JSON::ParserError
+      ""
+    end
+
+    # @param trigger_def [String] +pg_get_triggerdef+ output
+    def canonical_from_pg_triggerdef(trigger_def)
+      return "" if trigger_def.blank?
+
+      clause = extract_events_clause(trigger_def)
+      return "" if clause.blank?
+
+      parse_events_clause(clause).sort.join("|")
+    end
+
+    # SQL fragment for the event list (e.g. +INSERT OR UPDATE OF "email"+), preserving DSL event order.
+    def events_sql_fragment(defn, quote_column:)
+      hash = stringify(defn)
+      events = Array(hash["events"]).map(&:to_s).map(&:downcase)
+      columns = ordered_columns(hash["columns"])
+      return "INSERT" if events.empty?
+
+      events.map do |ev|
+        if ev == "update" && columns.any?
+          quoted = columns.map { |c| quote_column.call(c) }.join(", ")
+          "UPDATE OF #{quoted}"
+        else
+          ev.upcase
+        end
+      end.join(" OR ")
+    end
+
+    def normalized_columns(raw)
+      ordered_columns(raw).map(&:downcase).sort
+    end
+
+    def ordered_columns(raw)
+      Array(raw).flatten.compact.map { |c| c.to_s.strip }.reject(&:empty?)
+    end
+
+    def build_tokens(events, sorted_lowercase_columns)
+      cols_join = sorted_lowercase_columns.join(",")
+      events.map do |ev|
+        if ev == "update" && cols_join.present?
+          "update:#{cols_join}"
+        else
+          ev
+        end
+      end
+    end
+
+    def extract_events_clause(trigger_def)
+      s = trigger_def.to_s.squish
+      m = s.match(/(?:BEFORE|AFTER|INSTEAD\s+OF)\s+(.+?)\s+ON\s+/i)
+      return "" unless m
+
+      m.captures.first.to_s.strip
+    end
+
+    def parse_events_clause(clause)
+      clause.split(/\s+OR\s+/i).filter_map do |part|
+        part = part.strip
+        next if part.empty?
+
+        um = part.match(/\AUPDATE\s+OF\s+(.+)\z/i)
+        if um
+          cols = um[1].split(",").map { |c| normalize_pg_identifier(c) }.sort
+          "update:#{cols.join(',')}"
+        else
+          part.downcase
+        end
+      end
+    end
+
+    def normalize_pg_identifier(fragment)
+      f = fragment.to_s.strip
+      if f.start_with?('"') && f.end_with?('"') && f.length >= 2
+        f[1...-1].gsub('""', '"').downcase
+      else
+        f.downcase
+      end
+    end
+
+    def stringify(defn)
+      return {} if defn.nil?
+
+      defn.transform_keys(&:to_s)
+    end
+  end
+end

data/lib/pg_sql_triggers/migration.rb

@@ -4,12 +4,11 @@ module PgSqlTriggers
   class Migration < ActiveRecord::Migration[6.1]
     # Base class for trigger migrations
     # Similar to ActiveRecord::Migration but for trigger-specific migrations
-
-    # rubocop:disable Rails/Delegate
-    # delegate doesn't work here due to argument forwarding issues in this context
-    def execute(sql)
-      connection.execute(sql)
+    #
+    # Cannot use `delegate` here: ActiveRecord::Migration defines a class-method
+    # `delegate` (schema DSL) that shadows Module's `delegate` on Rails 8+.
+    def execute(...)
+      connection.execute(...)
     end
-    # rubocop:enable Rails/Delegate
   end
 end