pg_sql_triggers 1.4.0 → 1.5.0

data/lib/pg_sql_triggers/registry/validator.rb

@@ -1,21 +1,26 @@
 # frozen_string_literal: true
 
 require "json"
+require "set"
+require "tsort"
 
 module PgSqlTriggers
   module Registry
-    class Validator
+    class Validator # rubocop:disable Metrics/ClassLength -- validation rules grouped in one class
       VALID_EVENTS = %w[insert update delete truncate].freeze
       VALID_TIMINGS = %w[before after instead_of].freeze
       VALID_FOR_EACH = %w[row statement].freeze
 
       def self.validate!
         errors = []
+        dsl_triggers = PgSqlTriggers::TriggerRegistry.where(source: "dsl").to_a
 
-        PgSqlTriggers::TriggerRegistry.where(source: "dsl").find_each do |trigger|
+        dsl_triggers.each do |trigger|
           errors.concat(validate_dsl_trigger(trigger))
         end
 
+        errors.concat(collect_dependency_and_order_errors(dsl_triggers))
+
         return true if errors.empty?
 
         raise PgSqlTriggers::ValidationError.new(
@@ -24,9 +29,137 @@ module PgSqlTriggers
           context: { errors: errors }
         )
       end
+
+      # Returns dependency-related errors (missing refs, cycles, incompatible pairs, name order).
+      # Used by rake trigger:validate_order and included in {.validate!}.
+      def self.trigger_order_validation_errors
+        dsl_triggers = PgSqlTriggers::TriggerRegistry.where(source: "dsl").to_a
+        collect_dependency_and_order_errors(dsl_triggers)
+      end
+
+      # Prerequisite and dependent DSL triggers for the trigger detail page.
+      def self.related_triggers_for_show(trigger_record)
+        empty = { prerequisites: [], dependents: [] }
+        return empty if trigger_record.blank? || trigger_record.source != "dsl"
+
+        defn = parse_definition(trigger_record.definition)
+        prerequisite_names = normalize_depends_on(defn)
+        prerequisites = prerequisite_names.filter_map do |dep_name|
+          PgSqlTriggers::TriggerRegistry.find_by(source: "dsl", trigger_name: dep_name)
+        end
+
+        dependents = []
+        PgSqlTriggers::TriggerRegistry.where(source: "dsl").find_each do |row|
+          next if row.id == trigger_record.id
+
+          other = parse_definition(row.definition)
+          dependents << row if normalize_depends_on(other).include?(trigger_record.trigger_name)
+        end
+
+        {
+          prerequisites: prerequisites.sort_by(&:trigger_name),
+          dependents: dependents.sort_by(&:trigger_name)
+        }
+      end
+
       class << self
         private
 
+        def normalize_depends_on(defn)
+          raw = defn["depends_on"]
+          list = case raw
+                 when nil then []
+                 when Array then raw
+                 else [raw]
+                 end
+          list.flatten.compact.map { |entry| entry.to_s.strip }.reject(&:empty?).uniq
+        end
+
+        def effective_timing(defn)
+          return "after" if ActiveModel::Type::Boolean.new.cast(defn["constraint_trigger"])
+
+          (defn["timing"].presence || "before").to_s
+        end
+
+        def for_each_level(defn)
+          (defn["for_each"].presence || "row").to_s
+        end
+
+        def event_names_for_overlap(defn)
+          Array(defn["events"]).to_set(&:to_s)
+        end
+
+        def compatibility_errors(child_row, child_defn, parent_row, parent_defn)
+          child_name = child_row.trigger_name
+          parent_name = parent_row.trigger_name
+          errs = []
+          if child_row.table_name != parent_row.table_name
+            errs << "Trigger '#{child_name}': depends_on '#{parent_name}' must reference a trigger on the same " \
+                    "table (#{child_row.table_name} vs #{parent_row.table_name})"
+          end
+          if effective_timing(child_defn) != effective_timing(parent_defn)
+            errs << "Trigger '#{child_name}': depends_on '#{parent_name}' requires the same timing " \
+                    "(#{effective_timing(child_defn)} vs #{effective_timing(parent_defn)})"
+          end
+          if for_each_level(child_defn) != for_each_level(parent_defn)
+            errs << "Trigger '#{child_name}': depends_on '#{parent_name}' requires the same FOR EACH " \
+                    "(#{for_each_level(child_defn)} vs #{for_each_level(parent_defn)})"
+          end
+          ch_ev = event_names_for_overlap(child_defn)
+          pa_ev = event_names_for_overlap(parent_defn)
+          if (ch_ev & pa_ev).empty?
+            errs << "Trigger '#{child_name}': depends_on '#{parent_name}' requires overlapping events"
+          end
+          errs
+        end
+
+        def collect_dependency_and_order_errors(dsl_triggers)
+          errors = []
+          by_name = dsl_triggers.index_by(&:trigger_name)
+          valid_edges = []
+
+          dsl_triggers.each do |child|
+            child_name = child.trigger_name
+            child_defn = parse_definition(child.definition)
+            deps = normalize_depends_on(child_defn)
+            deps.each do |parent_name|
+              if parent_name == child_name
+                errors << "Trigger '#{child_name}': depends_on cannot reference itself"
+                next
+              end
+
+              parent = by_name[parent_name]
+              unless parent
+                errors << "Trigger '#{child_name}': depends_on references unknown trigger '#{parent_name}'"
+                next
+              end
+
+              parent_defn = parse_definition(parent.definition)
+              compat = compatibility_errors(child, child_defn, parent, parent_defn)
+              errors.concat(compat)
+              next if compat.any?
+
+              valid_edges << [parent_name, child_name]
+              unless parent_name < child_name
+                errors << "Trigger '#{child_name}': depends_on '#{parent_name}' must sort before " \
+                          "'#{child_name}' alphabetically (PostgreSQL fires same-kind triggers in name order)"
+              end
+            end
+          end
+
+          errors.concat(cycle_dependency_errors(valid_edges))
+          errors
+        end
+
+        def cycle_dependency_errors(edges)
+          return [] if edges.empty?
+
+          DependsOnSorter.new(edges).tsort
+          []
+        rescue TSort::Cyclic
+          ["depends_on: circular dependency chain detected among DSL triggers"]
+        end
+
         def validate_dsl_trigger(trigger)
           errors = []
           name = trigger.trigger_name
@@ -46,6 +179,8 @@ module PgSqlTriggers
 
           errors << "Trigger '#{name}': missing function_name" if definition["function_name"].blank?
 
+          errors.concat(validate_update_columns(name, events, definition))
+
           timing = definition["timing"].to_s
           if timing.present? && VALID_TIMINGS.exclude?(timing)
             errors << "Trigger '#{name}': invalid timing '#{timing}' (valid: #{VALID_TIMINGS.inspect})"
@@ -56,9 +191,78 @@ module PgSqlTriggers
             errors << "Trigger '#{name}': invalid for_each '#{for_each}' (valid: #{VALID_FOR_EACH.inspect})"
           end
 
+          errors.concat(validate_deferral(name, definition, timing))
+
+          errors
+        end
+
+        def validate_deferral(name, definition, timing)
+          constraint = ActiveModel::Type::Boolean.new.cast(definition["constraint_trigger"])
+          deferrable_val = definition["deferrable"].presence&.to_s
+          initially_val = definition["initially"].presence&.to_s
+
+          errors = []
+          errors.concat(constraint_deferral_errors(name, constraint, timing, definition))
+          errors.concat(deferral_value_errors(name, deferrable_val, initially_val))
+          errors
+        end
+
+        def constraint_deferral_errors(name, constraint, timing, definition)
+          deferrable_val = definition["deferrable"].presence&.to_s
+          initially_val = definition["initially"].presence&.to_s
+          errors = []
+          if (deferrable_val.present? || initially_val.present?) && !constraint
+            errors << "Trigger '#{name}': deferrable/initially require constraint_trigger (CONSTRAINT TRIGGER)"
+          end
+          if constraint && timing.to_s != "after"
+            errors << "Trigger '#{name}': constraint triggers must use after timing"
+          end
+          if constraint && events_include_truncate?(definition)
+            errors << "Trigger '#{name}': constraint triggers cannot use TRUNCATE events"
+          end
+          errors
+        end
+
+        VALID_DEFERRABLE = %w[deferrable not_deferrable].freeze
+        VALID_INITIALLY = %w[deferred immediate].freeze
+        private_constant :VALID_DEFERRABLE, :VALID_INITIALLY
+
+        def deferral_value_errors(name, deferrable_val, initially_val)
+          errors = []
+          if deferrable_val.present? && VALID_DEFERRABLE.exclude?(deferrable_val)
+            errors << "Trigger '#{name}': invalid deferrable '#{deferrable_val}' (valid: #{VALID_DEFERRABLE.inspect})"
+          end
+          if initially_val.present? && VALID_INITIALLY.exclude?(initially_val)
+            errors << "Trigger '#{name}': invalid initially '#{initially_val}' (valid: #{VALID_INITIALLY.inspect})"
+          end
+          if initially_val.present? && deferrable_val != "deferrable"
+            errors << "Trigger '#{name}': initially requires deferrable to be 'deferrable'"
+          end
           errors
         end
 
+        def events_include_truncate?(definition)
+          Array(definition["events"]).map(&:to_s).include?("truncate")
+        end
+
+        def validate_update_columns(name, events, definition)
+          errs = []
+          cols = Array(definition["columns"]).flatten.compact.map(&:to_s).map(&:strip).reject(&:empty?)
+          return errs if cols.empty?
+
+          unless events.map(&:to_s).include?("update")
+            errs << "Trigger '#{name}': columns require an update event " \
+                    "(use on_update_of or include :update)"
+          end
+
+          cols.each do |col|
+            next if col.match?(/\A[a-zA-Z_][a-zA-Z0-9_]*\z/)
+
+            errs << "Trigger '#{name}': invalid column name #{col.inspect} (use simple SQL identifiers, no quoting)"
+          end
+          errs
+        end
+
         def parse_definition(definition_json)
           return {} if definition_json.blank?
 
@@ -67,6 +271,26 @@ module PgSqlTriggers
           {}
         end
       end
+
+      # Internal helper for cycle detection using Ruby's TSort.
+      class DependsOnSorter # :nodoc:
+        include TSort
+
+        def initialize(edges)
+          @adjacency = Hash.new { |h, k| h[k] = [] }
+          edges.each { |(from, to)| @adjacency[from] << to }
+          @nodes = (@adjacency.keys | @adjacency.values.flatten).uniq
+        end
+
+        def tsort_each_node(&block)
+          @nodes.each(&block)
+        end
+
+        def tsort_each_child(node, &block)
+          Array(@adjacency[node]).each(&block)
+        end
+      end
+      private_constant :DependsOnSorter
     end
   end
 end

data/lib/pg_sql_triggers/schema_dumper_extension.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module PgSqlTriggers
+  # Prepended onto ActiveRecord::SchemaDumper to document that triggers live outside schema.rb.
+  module SchemaDumperExtension
+    def trailer(stream)
+      stream.puts PgSqlTriggers::TriggerStructureDumper.schema_rb_annotation(connection: @connection) if append_notes?
+      super
+    end
+
+    private
+
+    def append_notes?
+      PgSqlTriggers.append_trigger_notes_to_schema_dump &&
+        defined?(Rails) &&
+        Rails.application &&
+        ruby_schema_format?
+    end
+
+    def ruby_schema_format?
+      cfg = Rails.application.config
+      # Minimal Rails apps (e.g. tests without ActiveRecord::Railtie) have no config.active_record.
+      return true unless cfg.respond_to?(:active_record)
+
+      ar_cfg = cfg.active_record
+      return true unless ar_cfg.respond_to?(:schema_format)
+
+      format = ar_cfg.schema_format
+      format.nil? || format.to_sym == :ruby
+    end
+  end
+end

data/lib/pg_sql_triggers/sql/kill_switch.rb

@@ -51,7 +51,8 @@ module PgSqlTriggers
         if PgSqlTriggers.respond_to?(:default_environment) && PgSqlTriggers.default_environment.respond_to?(:call)
           begin
             return PgSqlTriggers.default_environment.call.to_s
-          rescue NameError, NoMethodError => e # rubocop:disable Lint/ShadowedException
+          rescue NameError => e
+            # NoMethodError inherits from NameError, so both are rescued by this clause.
             logger&.debug "[KILL_SWITCH] Could not resolve default_environment: #{e.message}"
           end
         end

data/lib/pg_sql_triggers/testing/function_tester.rb

@@ -7,122 +7,60 @@ module PgSqlTriggers
         @trigger = trigger_registry
       end
 
-      # Test ONLY the function, not the trigger
-      # rubocop:disable Lint/UnusedMethodArgument
+      FUNCTION_NAME_PATTERN = /CREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\(/i
+
+      # Test ONLY the function, not the trigger.
+      #
+      # +test_context+ is accepted for API compatibility with future invocation logic.
+      # It is normalised to an empty hash when +nil+ so callers can pass either.
       def test_function_only(test_context: {})
+        test_context ||= {}
         results = {
           function_created: false,
           function_executed: false,
           errors: [],
-          output: []
+          output: [],
+          context: test_context
         }
 
-        # Check if function_body is present
-        if @trigger.function_body.blank?
-          results[:success] = false
-          results[:errors] << "Function body is missing"
-          return results
+        return fail_result(results, "Function body is missing") if @trigger.function_body.blank?
+        unless extract_function_name_from_body
+          return fail_result(results, "Function body does not contain a valid CREATE FUNCTION statement")
         end
 
-        # Extract function name to verify it matches
-        function_name_from_body = nil
-        if @trigger.function_body.present?
-          pattern = /CREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\(/i
-          match = @trigger.function_body.match(pattern)
-          function_name_from_body = match[1] if match
-        end
+        run_function_test_transaction(results)
+        results[:output] << "\n⚠ Function rolled back (test mode)"
+        results
+      end
 
-        # If function_body doesn't contain a valid function definition, fail early
-        unless function_name_from_body
-          results[:success] = false
-          results[:errors] << "Function body does not contain a valid CREATE FUNCTION statement"
-          return results
-        end
+      private
+
+      def fail_result(results, error_message)
+        results[:success] = false
+        results[:errors] << error_message
+        results
+      end
+
+      def extract_function_name_from_body
+        return nil if @trigger.function_body.blank?
+
+        match = @trigger.function_body.match(FUNCTION_NAME_PATTERN)
+        match && match[1]
+      end
+
+      def extract_function_name_from_definition
+        return nil if @trigger.definition.blank?
+
+        definition = JSON.parse(@trigger.definition)
+        definition["function_name"] || definition["name"]
+      rescue StandardError
+        nil
+      end
 
-        # rubocop:disable Metrics/BlockLength
+      def run_function_test_transaction(results)
         ActiveRecord::Base.transaction do
-          # Create function in transaction
-          begin
-            ActiveRecord::Base.connection.execute(@trigger.function_body)
-            results[:function_created] = true
-            results[:output] << "✓ Function created in test transaction"
-          rescue ActiveRecord::StatementInvalid, StandardError => e
-            results[:success] = false
-            results[:errors] << "Error during function creation: #{e.message}"
-            # Don't raise here, let it fall through to ensure block for rollback
-          end
-
-          # Try to invoke function directly (if test context provided)
-          # Note: Empty hash {} is not "present" in Rails, so check if it's not nil
-          if results[:function_created]
-            # This would require custom invocation logic
-            # For now, just verify it was created - if function was successfully created,
-            # we can assume it exists and is executable within the transaction
-            function_name = nil
-
-            # First, try to extract from function_body (most reliable)
-            if @trigger.function_body.present?
-              # Extract function name from CREATE FUNCTION statement
-              # Match: CREATE [OR REPLACE] FUNCTION function_name(...)
-              pattern = /CREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\(/i
-              match = @trigger.function_body.match(pattern)
-              function_name = match[1] if match
-            end
-
-            # Fallback to definition JSON if function_body extraction failed
-            if function_name.blank? && @trigger.definition.present?
-              definition = begin
-                JSON.parse(@trigger.definition)
-              rescue StandardError
-                {}
-              end
-              function_name = definition["function_name"] || definition[:function_name] ||
-                              definition["name"] || definition[:name]
-            end
-
-            # Verify function exists in database by checking pg_proc
-            # Try to verify via query if function_name is available
-            if function_name.present?
-              begin
-                sanitized_name = begin
-                  ActiveRecord::Base.connection.quote_string(function_name)
-                rescue StandardError => e
-                  # If quote_string fails, use the function name as-is (less safe but allows test to continue)
-                  results[:errors] << "Error during function name sanitization: #{e.message}"
-                  function_name
-                end
-                check_sql = <<~SQL.squish
-                  SELECT COUNT(*) as count
-                  FROM pg_proc p
-                  JOIN pg_namespace n ON p.pronamespace = n.oid
-                  WHERE p.proname = '#{sanitized_name}'
-                  AND n.nspname = 'public'
-                SQL
-
-                result = ActiveRecord::Base.connection.execute(check_sql).first
-                results[:function_executed] = result && result["count"].to_i.positive?
-                results[:output] << if results[:function_executed]
-                                      "✓ Function exists and is callable"
-                                    else
-                                      "✓ Function created (verified via successful creation)"
-                                    end
-              rescue ActiveRecord::StatementInvalid, StandardError => e
-                results[:function_executed] = false
-                results[:success] = false
-                results[:errors] << "Error during function verification: #{e.message}"
-                # Also add the original error message to ensure it's searchable in tests
-                results[:errors] << e.message unless results[:errors].include?(e.message)
-                results[:output] << "✓ Function created (verification failed)"
-              end
-            else
-              # If we can't extract function name, assume it was created successfully
-              # since function_created is true
-              results[:function_executed] = true
-              results[:output] << "✓ Function created (execution verified via successful creation)"
-            end
-          end
-
-          # Set success to true only if no errors occurred and function was created
+          create_function_in_transaction(results)
+          verify_function_in_transaction(results) if results[:function_created]
           results[:success] = results[:errors].empty? && results[:function_created]
         rescue ActiveRecord::StatementInvalid, StandardError => e
           results[:success] = false
@@ -130,11 +68,63 @@ module PgSqlTriggers
         ensure
           raise ActiveRecord::Rollback
         end
+      end
 
-        results[:output] << "\n⚠ Function rolled back (test mode)"
-        results
+      def create_function_in_transaction(results)
+        ActiveRecord::Base.connection.execute(@trigger.function_body)
+        results[:function_created] = true
+        results[:output] << "✓ Function created in test transaction"
+      rescue ActiveRecord::StatementInvalid, StandardError => e
+        results[:success] = false
+        results[:errors] << "Error during function creation: #{e.message}"
+      end
+
+      def verify_function_in_transaction(results)
+        function_name = extract_function_name_from_body || extract_function_name_from_definition
+
+        if function_name.blank?
+          results[:function_executed] = true
+          results[:output] << "✓ Function created (execution verified via successful creation)"
+          return
+        end
+
+        verify_function_in_pg_proc(function_name, results)
       end
-      # rubocop:enable Lint/UnusedMethodArgument, Metrics/BlockLength
+
+      def verify_function_in_pg_proc(function_name, results)
+        sanitized_name = safe_quote_function_name(function_name, results)
+        check_sql = <<~SQL.squish
+          SELECT COUNT(*) as count
+          FROM pg_proc p
+          JOIN pg_namespace n ON p.pronamespace = n.oid
+          WHERE p.proname = '#{sanitized_name}'
+          AND n.nspname = 'public'
+        SQL
+
+        result = ActiveRecord::Base.connection.execute(check_sql).first
+        results[:function_executed] = result && result["count"].to_i.positive?
+        results[:output] << if results[:function_executed]
+                              "✓ Function exists and is callable"
+                            else
+                              "✓ Function created (verified via successful creation)"
+                            end
+      rescue ActiveRecord::StatementInvalid, StandardError => e
+        results[:function_executed] = false
+        results[:success] = false
+        results[:errors] << "Error during function verification: #{e.message}"
+        results[:errors] << e.message unless results[:errors].include?(e.message)
+        results[:output] << "✓ Function created (verification failed)"
+      end
+
+      def safe_quote_function_name(function_name, results)
+        ActiveRecord::Base.connection.quote_string(function_name)
+      rescue StandardError => e
+        # If quote_string fails, use the function name as-is (less safe but allows test to continue)
+        results[:errors] << "Error during function name sanitization: #{e.message}"
+        function_name
+      end
+
+      public
 
       # Check if function already exists in database
       def function_exists?

data/lib/pg_sql_triggers/trigger_structure_dumper.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "time"
+
+module PgSqlTriggers
+  # Builds a SQL snapshot of PostgreSQL triggers for db/trigger_structure.sql and
+  # emits schema.rb annotations so teams know triggers are outside schema.rb.
+  class TriggerStructureDumper
+    class << self
+      def resolve_path(override = nil)
+        base = override || PgSqlTriggers.trigger_structure_sql_path
+        resolved = base.respond_to?(:call) ? base.call : base
+        resolved ||= default_path
+        Pathname(resolved.to_s)
+      end
+
+      def default_path
+        raise "Rails.root is required" unless defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+
+        Rails.root.join("db/trigger_structure.sql")
+      end
+
+      def dump_to(path = nil, connection: ActiveRecord::Base.connection)
+        target = resolve_path(path)
+        target.dirname.mkpath
+        target.write(generate_sql(connection: connection))
+        target
+      end
+
+      def load_from(path = nil, connection: ActiveRecord::Base.connection)
+        target = resolve_path(path)
+        raise Errno::ENOENT, target.to_s unless target.file?
+
+        sql = target.read
+        return if sql.strip.empty?
+
+        connection.raw_connection.exec(sql)
+        nil
+      end
+
+      def generate_sql(connection: ActiveRecord::Base.connection)
+        header = <<~SQL
+          -- pg_sql_triggers trigger_structure.sql
+          -- Generated at: #{Time.now.utc.iso8601}
+          --
+          -- Apply with: bin/rails trigger:load
+          -- Prefer checking this file into version control alongside db/triggers migrations.
+        SQL
+
+        rows = trigger_rows(connection)
+        parts = [header]
+
+        rows.each do |row|
+          trigger_name = row["trigger_name"] || row[:trigger_name]
+          parts << ""
+          parts << "-- Trigger: #{trigger_name}"
+          append_definition(parts, row["function_definition"] || row[:function_definition])
+          append_definition(parts, row["trigger_definition"] || row[:trigger_definition])
+        end
+
+        parts.join("\n").strip.concat("\n")
+      end
+
+      def schema_rb_annotation(connection: ActiveRecord::Base.connection)
+        names = managed_trigger_names(connection)
+        lines = []
+        lines << "  # ---------------------------------------------------------------------------"
+        lines << "  # pg_sql_triggers: PostgreSQL triggers are not captured in schema.rb."
+        lines << "  # After db:schema:load, run: bin/rails trigger:migrate (or trigger:load)."
+        lines << "  # SQL snapshot: db/trigger_structure.sql (bin/rails trigger:dump)."
+        lines << "  # For full fidelity use config.active_record.schema_format = :sql."
+        lines << if names.any?
+                   "  # Managed triggers (#{names.length}): #{names.join(', ')}"
+                 else
+                   "  # Managed triggers: (none registered in pg_sql_triggers_registry)"
+                 end
+        lines << "  # ---------------------------------------------------------------------------"
+        lines.join("\n")
+      end
+
+      def managed_trigger_names(connection)
+        return [] unless connection.table_exists?("pg_sql_triggers_registry")
+
+        connection.select_values(
+          "SELECT trigger_name FROM pg_sql_triggers_registry ORDER BY trigger_name"
+        )
+      end
+
+      private
+
+      def trigger_rows(connection)
+        if connection.table_exists?("pg_sql_triggers_registry")
+          managed_trigger_names(connection).filter_map do |name|
+            PgSqlTriggers::Drift::DbQueries.find_trigger(name)
+          end
+        else
+          PgSqlTriggers::Drift::DbQueries.all_triggers
+        end
+      end
+
+      def append_definition(parts, definition)
+        stmt = definition.to_s.strip
+        return if stmt.empty?
+
+        stmt += ";" unless stmt.end_with?(";")
+        parts << stmt
+      end
+    end
+  end
+end