pg_sql_triggers 1.2.0 → 1.4.0

data/lib/pg_sql_triggers/migrator/pre_apply_comparator.rb

@@ -12,25 +12,24 @@ module PgSqlTriggers
         # Compare expected state from migration with actual database state
         # Returns a comparison result with diff information
         def compare(migration_instance, direction: :up)
-          expected = extract_expected_state(migration_instance, direction)
+          captured_sql = capture_sql(migration_instance, direction)
+          compare_sql(captured_sql)
+        end
+
+        # Compare using pre-captured SQL (avoids re-instantiating the migration class).
+        # Returns a comparison result with diff information.
+        def compare_sql(captured_sql)
+          expected = parse_sql_to_state(captured_sql)
           actual = extract_actual_state(expected)
           generate_diff(expected, actual)
         end
 
         private
 
-        # Extract expected SQL and state from migration instance
-        def extract_expected_state(migration_instance, direction)
-          captured_sql = capture_sql(migration_instance, direction)
-          parse_sql_to_state(captured_sql)
-        end
-
         # Capture SQL that would be executed by the migration
         def capture_sql(migration_instance, direction)
           captured = []
 
-          # Override execute to capture SQL instead of executing
-          # Since we use a separate instance for comparison, we don't need to restore
           migration_instance.define_singleton_method(:execute) do |sql|
             captured << sql.to_s.strip
           end

data/lib/pg_sql_triggers/migrator/safety_validator.rb

@@ -34,26 +34,41 @@ module PgSqlTriggers
           raise UnsafeOperationError.new(error_message, violations)
         end
 
+        # Validate using pre-captured SQL (avoids re-instantiating the migration class).
+        # Raises UnsafeOperationError if unsafe patterns are detected.
+        def validate_sql!(captured_sql, direction: :up, allow_unsafe: false) # rubocop:disable Lint/UnusedMethodArgument
+          return if allow_unsafe
+
+          violations = detect_unsafe_patterns_from_sql(captured_sql)
+          return if violations.empty?
+
+          error_message = build_error_message(violations, "(migration)")
+          raise UnsafeOperationError.new(error_message, violations)
+        end
+
         # Detect unsafe patterns in migration SQL
         # Returns array of violation hashes
         def detect_unsafe_patterns(migration_instance, direction)
-          violations = []
-
-          # Capture SQL that would be executed
           captured_sql = capture_sql(migration_instance, direction)
+          detect_unsafe_patterns_from_sql(captured_sql)
+        end
 
-          # Parse SQL to detect unsafe patterns
-          sql_operations = parse_sql_operations(captured_sql)
+        private
 
-          # Check for explicit DROP + CREATE patterns (the main safety concern)
+        # Core detection logic that works on pre-captured SQL.
+        def detect_unsafe_patterns_from_sql(captured_sql)
+          violations = []
+          sql_operations = parse_sql_operations(captured_sql)
           violations.concat(detect_drop_create_patterns(sql_operations))
-
           violations
         end
 
-        private
-
-        # Capture SQL that would be executed by the migration
+        # Capture SQL that would be executed by the migration.
+        # Runs the migration inside a transaction that is always rolled back so
+        # that any ActiveRecord migration helpers (add_column, create_table, …)
+        # that are called alongside explicit +execute+ calls produce no lasting
+        # side effects.  The singleton override of +execute+ still intercepts
+        # raw SQL strings before they reach the database.
         def capture_sql(migration_instance, direction)
           captured = []
 
@@ -62,8 +77,13 @@ module PgSqlTriggers
             captured << sql.to_s.strip
           end
 
-          # Call the migration method (up or down) to capture SQL
-          migration_instance.public_send(direction)
+          # Run inside a transaction and roll it back so that any AR helpers
+          # called by the migration (add_column, create_table, etc.) do not
+          # persist their side effects during the capture phase.
+          ActiveRecord::Base.transaction do
+            migration_instance.public_send(direction)
+            raise ActiveRecord::Rollback
+          end
 
           captured
         end

data/lib/pg_sql_triggers/migrator.rb

@@ -191,13 +191,17 @@ module PgSqlTriggers
           end
         end
 
+        # Capture SQL once from a single inspection instance so that both the
+        # safety validator and comparator work from the same snapshot without
+        # running the migration code a second time.
+        captured_sql = capture_migration_sql(migration_class.new, direction)
+
         # Perform safety validation (prevent unsafe DROP + CREATE operations)
-        validation_instance = migration_class.new
         begin
           allow_unsafe = ENV["ALLOW_UNSAFE_MIGRATIONS"] == "true" ||
                          (defined?(PgSqlTriggers) && PgSqlTriggers.allow_unsafe_migrations == true)
 
-          SafetyValidator.validate!(validation_instance, direction: direction, allow_unsafe: allow_unsafe)
+          SafetyValidator.validate_sql!(captured_sql, direction: direction, allow_unsafe: allow_unsafe)
         rescue SafetyValidator::UnsafeOperationError => e
           # Safety validation failed - block the migration
           error_msg = "\n#{e.message}\n\n"
@@ -212,11 +216,9 @@ module PgSqlTriggers
           end
         end
 
-        # Perform pre-apply comparison (diff expected vs actual)
-        # Create a separate instance for comparison to avoid side effects
-        comparison_instance = migration_class.new
+        # Perform pre-apply comparison (diff expected vs actual) using the same captured SQL
         begin
-          diff_result = PreApplyComparator.compare(comparison_instance, direction: direction)
+          diff_result = PreApplyComparator.compare_sql(captured_sql)
 
           # Log the comparison result
           if diff_result[:has_differences]
@@ -261,6 +263,8 @@ module PgSqlTriggers
             cleanup_orphaned_registry_entries
           end
         end
+
+        enforce_disabled_triggers if direction == :up
       rescue LoadError => e
         raise StandardError, "Error loading trigger migration #{migration.filename}: #{e.message}"
       rescue StandardError => e
@@ -295,6 +299,49 @@ module PgSqlTriggers
         current_version
       end
 
+      private
+
+      # Capture the SQL statements a migration would execute for a given direction
+      # without committing any side effects.  The migration's +execute+ method is
+      # overridden on the singleton so raw SQL strings are intercepted, and the
+      # whole run is wrapped in a transaction that is always rolled back so that
+      # any ActiveRecord migration helpers (add_column, create_table, …) don't
+      # persist their effects during the inspection phase.
+      def capture_migration_sql(migration_instance, direction)
+        captured = []
+
+        migration_instance.define_singleton_method(:execute) do |sql|
+          captured << sql.to_s.strip
+        end
+
+        ActiveRecord::Base.transaction do
+          migration_instance.public_send(direction)
+          raise ActiveRecord::Rollback
+        end
+
+        captured
+      end
+
+      def enforce_disabled_triggers
+        return unless ActiveRecord::Base.connection.table_exists?("pg_sql_triggers_registry")
+
+        introspection = PgSqlTriggers::DatabaseIntrospection.new
+        PgSqlTriggers::TriggerRegistry.disabled.each do |registry|
+          next unless introspection.trigger_exists?(registry.trigger_name)
+
+          conn           = ActiveRecord::Base.connection
+          quoted_table   = conn.quote_table_name(registry.table_name.to_s)
+          quoted_trigger = conn.quote_table_name(registry.trigger_name.to_s)
+          conn.execute("ALTER TABLE #{quoted_table} DISABLE TRIGGER #{quoted_trigger};")
+        rescue StandardError => e
+          if defined?(Rails.logger)
+            Rails.logger.warn("[MIGRATOR] Could not disable trigger #{registry.trigger_name}: #{e.message}")
+          end
+        end
+      end
+
+      public
+
       # Clean up registry entries for triggers that no longer exist in the database
       # This is called after rolling back migrations to keep the registry in sync
       def cleanup_orphaned_registry_entries

data/lib/pg_sql_triggers/permissions/checker.rb

@@ -22,8 +22,15 @@ module PgSqlTriggers
         unless can?(actor, action, environment: environment)
           action_sym = action.to_sym
           required_level = Permissions::ACTIONS[action_sym] || "unknown"
-          raise PgSqlTriggers::PermissionError,
-                "Permission denied: #{action_sym} requires #{required_level} level access"
+          message = "Permission denied: #{action_sym} requires #{required_level} level access"
+          recovery = "Contact your administrator to request #{required_level} level access for this operation."
+
+          raise PgSqlTriggers::PermissionError.new(
+            message,
+            error_code: "PERMISSION_DENIED",
+            recovery_suggestion: recovery,
+            context: { action: action_sym, required_role: required_level, environment: environment }
+          )
         end
         true
       end

data/lib/pg_sql_triggers/registry/manager.rb

@@ -3,15 +3,19 @@
 module PgSqlTriggers
   module Registry
     class Manager
+      REGISTRY_CACHE_MUTEX = Mutex.new
+      private_constant :REGISTRY_CACHE_MUTEX
+
       class << self
-        # Request-level cache to avoid N+1 queries when loading multiple trigger files
-        # This cache is cleared after each request/transaction to ensure data consistency
+        # Request-level cache to avoid N+1 queries when loading multiple trigger files.
+        # Access to @_registry_cache is guarded by REGISTRY_CACHE_MUTEX so that
+        # concurrent threads cannot observe a partially-initialised hash.
         def _registry_cache
-          @_registry_cache ||= {}
+          REGISTRY_CACHE_MUTEX.synchronize { @_registry_cache ||= {} }
         end
 
         def _clear_registry_cache
-          @_registry_cache = {}
+          REGISTRY_CACHE_MUTEX.synchronize { @_registry_cache = {} }
         end
 
         # Batch load existing triggers into cache to avoid N+1 queries
@@ -52,7 +56,8 @@ module PgSqlTriggers
             source: "dsl",
             environment: definition.environments.join(","),
             definition: definition.to_h.to_json,
-            checksum: checksum
+            checksum: checksum,
+            for_each: definition.for_each || "row"
           }
 
           if existing
@@ -60,6 +65,7 @@ module PgSqlTriggers
             attributes_changed = attributes.any? do |key, value|
               existing.send(key) != value
             end
+            enabled_changed = existing.enabled != definition.enabled
 
             if attributes_changed
               begin
@@ -67,6 +73,9 @@ module PgSqlTriggers
                 # Update cache with the modified record (reload to get fresh data)
                 reloaded = existing.reload
                 _registry_cache[trigger_name] = reloaded
+                if enabled_changed
+                  sync_postgresql_enabled_state(existing.trigger_name, existing.table_name, definition.enabled)
+                end
                 reloaded
               rescue ActiveRecord::RecordNotFound
                 # Cached record was deleted, create a new one
@@ -82,6 +91,9 @@ module PgSqlTriggers
             new_record = PgSqlTriggers::TriggerRegistry.create!(attributes)
             # Cache the newly created record
             _registry_cache[trigger_name] = new_record
+            unless definition.enabled
+              sync_postgresql_enabled_state(new_record.trigger_name, new_record.table_name, definition.enabled)
+            end
             new_record
           end
         end
@@ -127,22 +139,35 @@ module PgSqlTriggers
         private
 
         def calculate_checksum(definition)
-          # DSL definitions don't have function_body, so use placeholder
-          # Generator forms have function_body, so calculate real checksum
           function_body_value = definition.respond_to?(:function_body) ? definition.function_body : nil
-          return "placeholder" if function_body_value.blank?
 
-          # Use field-concatenation algorithm (consistent with TriggerRegistry#calculate_checksum)
+          # Use field-concatenation algorithm (consistent with TriggerRegistry#calculate_checksum).
+          # DSL definitions have no function_body — use "" so the checksum is real and comparable
+          # with what Drift::Detector#calculate_db_checksum computes for DSL-source triggers.
           require "digest"
           Digest::SHA256.hexdigest([
             definition.name,
             definition.table_name,
             definition.version,
-            function_body_value,
+            function_body_value || "",
             definition.condition || "",
-            definition.timing || "before"
+            definition.timing || "before",
+            definition.for_each || "row"
           ].join)
         end
+
+        def sync_postgresql_enabled_state(trigger_name, table_name, enabled)
+          introspection = PgSqlTriggers::DatabaseIntrospection.new
+          return unless introspection.trigger_exists?(trigger_name)
+
+          conn           = ActiveRecord::Base.connection
+          quoted_table   = conn.quote_table_name(table_name.to_s)
+          quoted_trigger = conn.quote_table_name(trigger_name.to_s)
+          verb           = enabled ? "ENABLE" : "DISABLE"
+          conn.execute("ALTER TABLE #{quoted_table} #{verb} TRIGGER #{quoted_trigger};")
+        rescue StandardError => e
+          Rails.logger.warn("[REGISTER] Could not sync trigger enabled state: #{e.message}") if defined?(Rails.logger)
+        end
       end
     end
   end

data/lib/pg_sql_triggers/registry/validator.rb

@@ -1,15 +1,72 @@
 # frozen_string_literal: true
 
+require "json"
+
 module PgSqlTriggers
   module Registry
     class Validator
-      # rubocop:disable Naming/PredicateMethod
+      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!
-        # Validates all registry entries
-        # This is a placeholder implementation
-        true
+        errors = []
+
+        PgSqlTriggers::TriggerRegistry.where(source: "dsl").find_each do |trigger|
+          errors.concat(validate_dsl_trigger(trigger))
+        end
+
+        return true if errors.empty?
+
+        raise PgSqlTriggers::ValidationError.new(
+          "Registry validation failed:\n#{errors.map { |e| "  - #{e}" }.join("\n")}",
+          error_code: "VALIDATION_FAILED",
+          context: { errors: errors }
+        )
+      end
+      class << self
+        private
+
+        def validate_dsl_trigger(trigger)
+          errors = []
+          name = trigger.trigger_name
+          definition = parse_definition(trigger.definition)
+
+          errors << "Trigger '#{name}': missing table_name" if definition["table_name"].blank?
+
+          events = Array(definition["events"])
+          if events.empty?
+            errors << "Trigger '#{name}': events cannot be empty"
+          else
+            invalid = events - VALID_EVENTS
+            if invalid.any?
+              errors << "Trigger '#{name}': invalid events #{invalid.inspect} (valid: #{VALID_EVENTS.inspect})"
+            end
+          end
+
+          errors << "Trigger '#{name}': missing function_name" if definition["function_name"].blank?
+
+          timing = definition["timing"].to_s
+          if timing.present? && VALID_TIMINGS.exclude?(timing)
+            errors << "Trigger '#{name}': invalid timing '#{timing}' (valid: #{VALID_TIMINGS.inspect})"
+          end
+
+          for_each = definition["for_each"].to_s
+          if for_each.present? && VALID_FOR_EACH.exclude?(for_each)
+            errors << "Trigger '#{name}': invalid for_each '#{for_each}' (valid: #{VALID_FOR_EACH.inspect})"
+          end
+
+          errors
+        end
+
+        def parse_definition(definition_json)
+          return {} if definition_json.blank?
+
+          JSON.parse(definition_json)
+        rescue JSON::ParserError
+          {}
+        end
       end
-      # rubocop:enable Naming/PredicateMethod
     end
   end
 end

data/lib/pg_sql_triggers/registry.rb

@@ -1,59 +1,187 @@
 # frozen_string_literal: true
 
 module PgSqlTriggers
+  # Registry module provides a unified API for querying and managing triggers.
+  #
+  # @example Query triggers
+  #   # List all triggers
+  #   triggers = PgSqlTriggers::Registry.list
+  #
+  #   # Get enabled/disabled triggers
+  #   enabled = PgSqlTriggers::Registry.enabled
+  #   disabled = PgSqlTriggers::Registry.disabled
+  #
+  #   # Get triggers for a specific table
+  #   user_triggers = PgSqlTriggers::Registry.for_table(:users)
+  #
+  #   # Check for drift
+  #   drift_info = PgSqlTriggers::Registry.diff
+  #
+  # @example Manage triggers
+  #   # Enable a trigger
+  #   PgSqlTriggers::Registry.enable("users_email_validation",
+  #                                   actor: current_user,
+  #                                   confirmation: "EXECUTE TRIGGER_ENABLE")
+  #
+  #   # Disable a trigger
+  #   PgSqlTriggers::Registry.disable("users_email_validation",
+  #                                    actor: current_user,
+  #                                    confirmation: "EXECUTE TRIGGER_DISABLE")
+  #
+  #   # Drop a trigger
+  #   PgSqlTriggers::Registry.drop("old_trigger",
+  #                                 actor: current_user,
+  #                                 reason: "No longer needed",
+  #                                 confirmation: "EXECUTE TRIGGER_DROP")
+  #
+  #   # Re-execute a trigger
+  #   PgSqlTriggers::Registry.re_execute("drifted_trigger",
+  #                                       actor: current_user,
+  #                                       reason: "Fix drift",
+  #                                       confirmation: "EXECUTE TRIGGER_RE_EXECUTE")
   module Registry
     autoload :Manager, "pg_sql_triggers/registry/manager"
     autoload :Validator, "pg_sql_triggers/registry/validator"
 
+    # Registers a trigger definition in the registry.
+    #
+    # @param definition [PgSqlTriggers::DSL::TriggerDefinition] The trigger definition to register
+    # @return [PgSqlTriggers::TriggerRegistry] The registered trigger record
     def self.register(definition)
       Manager.register(definition)
     end
 
+    # Returns all registered triggers.
+    #
+    # @return [ActiveRecord::Relation<PgSqlTriggers::TriggerRegistry>] All trigger records
     def self.list
       Manager.list
     end
 
+    # Returns only enabled triggers.
+    #
+    # @return [ActiveRecord::Relation<PgSqlTriggers::TriggerRegistry>] Enabled trigger records
     def self.enabled
       Manager.enabled
     end
 
+    # Returns only disabled triggers.
+    #
+    # @return [ActiveRecord::Relation<PgSqlTriggers::TriggerRegistry>] Disabled trigger records
     def self.disabled
       Manager.disabled
     end
 
+    # Returns triggers for a specific table.
+    #
+    # @param table_name [String, Symbol] The table name to filter by
+    # @return [ActiveRecord::Relation<PgSqlTriggers::TriggerRegistry>] Triggers for the specified table
     def self.for_table(table_name)
       Manager.for_table(table_name)
     end
 
-    def self.diff
-      Manager.diff
+    # Checks for drift between DSL definitions and database state.
+    #
+    # @param trigger_name [String, nil] Optional trigger name to check specific trigger, or nil for all triggers
+    # @return [Hash] Drift information with keys: :in_sync, :drifted, :manual_override, :disabled, :dropped, :unknown
+    def self.diff(trigger_name = nil)
+      Manager.diff(trigger_name)
     end
 
+    # Returns all triggers that have drifted from their expected state.
+    #
+    # @return [Array<Hash>] Array of drift result hashes for drifted triggers
+    def self.drifted
+      Manager.drifted
+    end
+
+    # Returns all triggers that are in sync with their expected state.
+    #
+    # @return [Array<Hash>] Array of drift result hashes for in-sync triggers
+    def self.in_sync
+      Manager.in_sync
+    end
+
+    # Returns all unknown (external) triggers not managed by this gem.
+    #
+    # @return [Array<Hash>] Array of drift result hashes for unknown triggers
+    def self.unknown_triggers
+      Manager.unknown_triggers
+    end
+
+    # Returns all triggers that have been dropped from the database.
+    #
+    # @return [Array<Hash>] Array of drift result hashes for dropped triggers
+    def self.dropped
+      Manager.dropped
+    end
+
+    # Validates all triggers in the registry.
+    #
+    # @raise [PgSqlTriggers::ValidationError] If validation fails
+    # @return [true] If validation passes
     def self.validate!
       Validator.validate!
     end
 
-    # Console APIs for trigger operations
-    # These methods provide a convenient interface for managing triggers from the Rails console
-
+    # Enables a trigger by name.
+    #
+    # @param trigger_name [String] The name of the trigger to enable
+    # @param actor [Hash] Information about who is performing the action (must have :type and :id keys)
+    # @param confirmation [String, nil] Optional confirmation text for kill switch protection
+    # @raise [PgSqlTriggers::PermissionError] If actor lacks permission
+    # @raise [PgSqlTriggers::KillSwitchError] If kill switch blocks the operation
+    # @raise [PgSqlTriggers::NotFoundError] If trigger not found
+    # @return [PgSqlTriggers::TriggerRegistry] The updated trigger record
     def self.enable(trigger_name, actor:, confirmation: nil)
       check_permission!(actor, :enable_trigger)
       trigger = find_trigger!(trigger_name)
-      trigger.enable!(confirmation: confirmation)
+      trigger.enable!(confirmation: confirmation, actor: actor)
     end
 
+    # Disables a trigger by name.
+    #
+    # @param trigger_name [String] The name of the trigger to disable
+    # @param actor [Hash] Information about who is performing the action (must have :type and :id keys)
+    # @param confirmation [String, nil] Optional confirmation text for kill switch protection
+    # @raise [PgSqlTriggers::PermissionError] If actor lacks permission
+    # @raise [PgSqlTriggers::KillSwitchError] If kill switch blocks the operation
+    # @raise [PgSqlTriggers::NotFoundError] If trigger not found
+    # @return [PgSqlTriggers::TriggerRegistry] The updated trigger record
     def self.disable(trigger_name, actor:, confirmation: nil)
       check_permission!(actor, :disable_trigger)
       trigger = find_trigger!(trigger_name)
-      trigger.disable!(confirmation: confirmation)
+      trigger.disable!(confirmation: confirmation, actor: actor)
     end
 
+    # Drops a trigger by name.
+    #
+    # @param trigger_name [String] The name of the trigger to drop
+    # @param actor [Hash] Information about who is performing the action (must have :type and :id keys)
+    # @param reason [String] Required reason for dropping the trigger
+    # @param confirmation [String, nil] Optional confirmation text for kill switch protection
+    # @raise [PgSqlTriggers::PermissionError] If actor lacks permission
+    # @raise [PgSqlTriggers::KillSwitchError] If kill switch blocks the operation
+    # @raise [PgSqlTriggers::NotFoundError] If trigger not found
+    # @raise [ArgumentError] If reason is missing or empty
+    # @return [true] If drop succeeds
     def self.drop(trigger_name, actor:, reason:, confirmation: nil)
       check_permission!(actor, :drop_trigger)
       trigger = find_trigger!(trigger_name)
       trigger.drop!(reason: reason, confirmation: confirmation, actor: actor)
     end
 
+    # Re-executes a trigger by name (drops and recreates it).
+    #
+    # @param trigger_name [String] The name of the trigger to re-execute
+    # @param actor [Hash] Information about who is performing the action (must have :type and :id keys)
+    # @param reason [String] Required reason for re-executing the trigger
+    # @param confirmation [String, nil] Optional confirmation text for kill switch protection
+    # @raise [PgSqlTriggers::PermissionError] If actor lacks permission
+    # @raise [PgSqlTriggers::KillSwitchError] If kill switch blocks the operation
+    # @raise [PgSqlTriggers::NotFoundError] If trigger not found
+    # @raise [ArgumentError] If reason is missing or empty
+    # @return [PgSqlTriggers::TriggerRegistry] The updated trigger record
     def self.re_execute(trigger_name, actor:, reason:, confirmation: nil)
       check_permission!(actor, :drop_trigger) # Re-execute requires same permission as drop
       trigger = find_trigger!(trigger_name)
@@ -65,7 +193,12 @@ module PgSqlTriggers
     def self.find_trigger!(trigger_name)
       PgSqlTriggers::TriggerRegistry.find_by!(trigger_name: trigger_name)
     rescue ActiveRecord::RecordNotFound
-      raise ArgumentError, "Trigger '#{trigger_name}' not found in registry"
+      raise PgSqlTriggers::NotFoundError.new(
+        "Trigger '#{trigger_name}' not found in registry",
+        error_code: "TRIGGER_NOT_FOUND",
+        recovery_suggestion: "Verify the trigger name or create the trigger first using the generator or DSL.",
+        context: { trigger_name: trigger_name }
+      )
     end
     private_class_method :find_trigger!