pg_sql_triggers 1.2.0 → 1.4.0

data/lib/generators/pg_sql_triggers/templates/trigger_dsl.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+PgSqlTriggers::DSL.pg_sql_trigger "<%= trigger_name %>" do
+  table :<%= table_name %>
+  on <%= events_list %>
+  function :<%= function_name %>
+
+  version 1
+  enabled true
+  timing :<%= timing %>
+end

data/lib/generators/pg_sql_triggers/templates/trigger_migration_full.rb.tt

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class <%= trigger_class_name %> < PgSqlTriggers::Migration
+  def up
+    execute <<-SQL
+      CREATE OR REPLACE FUNCTION <%= function_name %>()
+      RETURNS TRIGGER AS $$
+      BEGIN
+        -- TODO: implement trigger logic
+        RETURN NEW;
+      END;
+      $$ LANGUAGE plpgsql;
+    SQL
+
+    execute <<-SQL
+      CREATE TRIGGER <%= trigger_name %>
+      <%= timing.upcase %> <%= events_sql %> ON <%= table_name %>
+      FOR EACH ROW
+      EXECUTE FUNCTION <%= function_name %>();
+    SQL
+  end
+
+  def down
+    execute <<-SQL
+      DROP TRIGGER IF EXISTS <%= trigger_name %> ON <%= table_name %>;
+      DROP FUNCTION IF EXISTS <%= function_name %>();
+    SQL
+  end
+end

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/drift/db_queries.rb

@@ -22,12 +22,12 @@ module PgSqlTriggers
             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
@@ -49,10 +49,10 @@ module PgSqlTriggers
             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
 
@@ -75,12 +75,12 @@ module PgSqlTriggers
             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 +92,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

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,39 @@ 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)
 
           # 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"
           ].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 +128,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/dsl/trigger_definition.rb

@@ -3,16 +3,18 @@
 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
+      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"
       end
 
       def table(table_name)
@@ -27,23 +29,22 @@ module PgSqlTriggers
         @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 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 +52,6 @@ module PgSqlTriggers
         @condition = condition_sql
       end
 
-      def timing(timing_value = nil)
-        if timing_value.nil?
-          @timing
-        else
-          @timing = timing_value.to_s
-        end
-      end
-
       def function_body
         nil # DSL definitions don't include function_body directly
       end
@@ -73,7 +66,8 @@ module PgSqlTriggers
           enabled: @enabled,
           environments: @environments,
           condition: @condition,
-          timing: @timing
+          timing: @timing,
+          for_each: @for_each
         }
       end
     end

data/lib/pg_sql_triggers/engine.rb

@@ -25,5 +25,19 @@ module PgSqlTriggers
     rake_tasks do
       load root.join("lib/tasks/trigger_migrations.rake")
     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
+      if PgSqlTriggers.permission_checker.nil? && defined?(Rails) && Rails.env.production?
+        Rails.logger.warn(
+          "[PgSqlTriggers] SECURITY WARNING: No permission_checker is configured. " \
+          "All actions are permitted by default, including admin-level operations " \
+          "(drop_trigger, execute_sql, override_drift). " \
+          "Set PgSqlTriggers.permission_checker in an initializer before deploying to production."
+        )
+      end
+    end
   end
 end

data/lib/pg_sql_triggers/errors.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module PgSqlTriggers
+  # Base error class for all PgSqlTriggers errors
+  #
+  # All errors in PgSqlTriggers inherit from this base class and include
+  # error codes for programmatic handling, standardized messages, and
+  # recovery suggestions.
+  class Error < StandardError
+    attr_reader :error_code, :recovery_suggestion, :context
+
+    def initialize(message = nil, error_code: nil, recovery_suggestion: nil, context: {})
+      @context = context || {}
+      @error_code = error_code || default_error_code
+      @recovery_suggestion = recovery_suggestion || default_recovery_suggestion
+      super(message || default_message)
+    end
+
+    # Returns a user-friendly error message suitable for UI display
+    def user_message
+      msg = message
+      msg += "\n\nRecovery: #{recovery_suggestion}" if recovery_suggestion
+      msg
+    end
+
+    # Returns error details as a hash for programmatic access
+    def to_h
+      {
+        error_class: self.class.name,
+        error_code: error_code,
+        message: message,
+        recovery_suggestion: recovery_suggestion,
+        context: context
+      }
+    end
+
+    protected
+
+    def default_error_code
+      # Convert class name to error code (e.g., "PermissionError" -> "PERMISSION_ERROR")
+      class_name = self.class.name.split("::").last
+      class_name.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                .upcase
+    end
+
+    def default_message
+      "An error occurred in PgSqlTriggers"
+    end
+
+    def default_recovery_suggestion
+      "Please check the logs for more details and contact support if the issue persists."
+    end
+  end
+
+  # Error raised when permission checks fail
+  #
+  # @example
+  #   raise PgSqlTriggers::PermissionError.new(
+  #     "Permission denied: enable_trigger requires Operator level access",
+  #     error_code: "PERMISSION_DENIED",
+  #     recovery_suggestion: "Contact your administrator to request Operator or Admin access",
+  #     context: { action: :enable_trigger, required_role: "Operator" }
+  #   )
+  class PermissionError < Error
+    def default_error_code
+      "PERMISSION_DENIED"
+    end
+
+    def default_message
+      "Permission denied for this operation"
+    end
+
+    def default_recovery_suggestion
+      if context[:required_role]
+        "This operation requires #{context[:required_role]} level access. " \
+          "Contact your administrator to request appropriate permissions."
+      else
+        "This operation requires elevated permissions. Contact your administrator."
+      end
+    end
+  end
+
+  # Error raised when kill switch blocks an operation
+  #
+  # @example
+  #   raise PgSqlTriggers::KillSwitchError.new(
+  #     "Kill switch is active for production environment",
+  #     error_code: "KILL_SWITCH_ACTIVE",
+  #     recovery_suggestion: "Provide confirmation text to override: EXECUTE OPERATION_NAME",
+  #     context: { operation: :trigger_enable, environment: "production" }
+  #   )
+  class KillSwitchError < Error
+    def default_error_code
+      "KILL_SWITCH_ACTIVE"
+    end
+
+    def default_message
+      "Kill switch is active for this environment"
+    end
+
+    def default_recovery_suggestion
+      ctx = @context || {}
+      ctx[:operation] || "this operation"
+      environment = ctx[:environment] || "this environment"
+      "Kill switch is active for #{environment}. " \
+        "To override, provide the required confirmation text. " \
+        "For CLI/rake tasks, use: KILL_SWITCH_OVERRIDE=true CONFIRMATION_TEXT=\"...\" rake your:task"
+    end
+  end
+
+  # Error raised when drift is detected
+  #
+  # @example
+  #   raise PgSqlTriggers::DriftError.new(
+  #     "Trigger 'users_email_validation' has drifted from definition",
+  #     error_code: "DRIFT_DETECTED",
+  #     recovery_suggestion: "Run migration to sync trigger, or re-execute trigger to apply current definition",
+  #     context: { trigger_name: "users_email_validation", drift_type: "function_body" }
+  #   )
+  class DriftError < Error
+    def default_error_code
+      "DRIFT_DETECTED"
+    end
+
+    def default_message
+      "Trigger has drifted from its definition"
+    end
+
+    def default_recovery_suggestion
+      trigger_name = context[:trigger_name] || "trigger"
+      "Trigger '#{trigger_name}' has drifted. " \
+        "Run 'rake trigger:migrate' to sync the trigger, or use the re-execute feature " \
+        "to apply the current definition."
+    end
+  end
+
+  # Error raised when validation fails
+  #
+  # @example
+  #   raise PgSqlTriggers::ValidationError.new(
+  #     "Invalid trigger definition: table name is required",
+  #     error_code: "VALIDATION_FAILED",
+  #     recovery_suggestion: "Ensure all required fields are provided in the trigger definition",
+  #     context: { field: :table_name, errors: ["is required"] }
+  #   )
+  class ValidationError < Error
+    def default_error_code
+      "VALIDATION_FAILED"
+    end
+
+    def default_message
+      "Validation failed"
+    end
+
+    def default_recovery_suggestion
+      if context[:field]
+        "Please fix the #{context[:field]} field and try again."
+      else
+        "Please review the input and ensure all required fields are provided."
+      end
+    end
+  end
+
+  # Error raised when SQL execution fails
+  #
+  # @example
+  #   raise PgSqlTriggers::ExecutionError.new(
+  #     "SQL execution failed: syntax error near 'INVALID'",
+  #     error_code: "EXECUTION_FAILED",
+  #     recovery_suggestion: "Review SQL syntax and ensure all references are valid",
+  #     context: { sql: "SELECT * FROM...", database_error: "..." }
+  #   )
+  class ExecutionError < Error
+    def default_error_code
+      "EXECUTION_FAILED"
+    end
+
+    def default_message
+      "SQL execution failed"
+    end
+
+    def default_recovery_suggestion
+      if context[:database_error]
+        "Review the SQL syntax and database error. Ensure all table and column names are correct."
+      else
+        "Review the SQL and ensure it is valid PostgreSQL syntax."
+      end
+    end
+  end
+
+  # Error raised when unsafe migrations are attempted
+  #
+  # @example
+  #   raise PgSqlTriggers::UnsafeMigrationError.new(
+  #     "Migration contains unsafe DROP + CREATE operations",
+  #     error_code: "UNSAFE_MIGRATION",
+  #     recovery_suggestion: "Review migration safety or set allow_unsafe_migrations=true",
+  #     context: { violations: [...] }
+  #   )
+  class UnsafeMigrationError < Error
+    def default_error_code
+      "UNSAFE_MIGRATION"
+    end
+
+    def default_message
+      "Migration contains unsafe operations"
+    end
+
+    def default_recovery_suggestion
+      "Review the migration for unsafe operations. " \
+        "If you are certain the migration is safe, you can set " \
+        "PgSqlTriggers.configure { |c| c.allow_unsafe_migrations = true } " \
+        "or use the kill switch override mechanism."
+    end
+  end
+
+  # Error raised when a trigger is not found
+  #
+  # @example
+  #   raise PgSqlTriggers::NotFoundError.new(
+  #     "Trigger 'users_email_validation' not found",
+  #     error_code: "TRIGGER_NOT_FOUND",
+  #     recovery_suggestion: "Verify trigger name or create the trigger first",
+  #     context: { trigger_name: "users_email_validation" }
+  #   )
+  class NotFoundError < Error
+    def default_error_code
+      "NOT_FOUND"
+    end
+
+    def default_message
+      "Resource not found"
+    end
+
+    def default_recovery_suggestion
+      if context[:trigger_name]
+        "Trigger '#{context[:trigger_name]}' not found. " \
+          "Verify the trigger name or create the trigger first using the generator or DSL."
+      else
+        "The requested resource was not found. Verify the identifier and try again."
+      end
+    end
+  end
+end