pg_sql_triggers 1.1.1 → 1.2.0

data/docs/web-ui.md

@@ -93,9 +93,56 @@ Available actions depend on trigger state and your permissions:
 - **Enable/Disable**: Toggle trigger activation
 - **Apply**: Apply generated trigger definition
 - **Drop**: Remove trigger from database (Admin only)
+- **Re-Execute**: Drop and recreate trigger from registry definition (Admin only)
 - **View SQL**: See the trigger's SQL definition
 - **View Diff**: Compare DSL vs database state
 
+### Drop Trigger
+
+The drop action permanently removes a trigger from the database and registry.
+
+1. Navigate to the trigger detail page
+2. Click the "Drop Trigger" button
+3. A modal will appear requiring:
+   - **Reason**: Explanation for dropping the trigger (required for audit trail)
+   - **Confirmation**: In protected environments, type the exact confirmation text shown
+4. Review the warning message
+5. Click "Drop Trigger" to confirm
+
+**Important Notes**:
+- This action is **irreversible** - the trigger will be permanently removed
+- Requires **Admin** permission level
+- Protected by kill switch in production environments
+- Reason is logged for compliance and audit purposes
+- The trigger is removed from both the database and the registry
+
+### Re-Execute Trigger
+
+The re-execute action fixes drifted triggers by dropping and recreating them from the registry definition.
+
+1. Navigate to the trigger detail page
+2. If the trigger is drifted, you'll see a drift warning
+3. Click the "Re-Execute" button
+4. A modal will appear showing:
+   - **Drift Comparison**: Differences between database state and registry definition
+   - **Reason Field**: Explanation for re-executing (required for audit trail)
+   - **Confirmation**: In protected environments, type the exact confirmation text shown
+5. Review the drift differences to understand what will change
+6. Click "Re-Execute Trigger" to confirm
+
+**What Happens**:
+1. Current trigger is dropped from the database
+2. New trigger is created using the registry definition (function_body, events, timing, condition)
+3. Registry is updated with execution timestamp
+4. Operation is logged with reason and actor information
+
+**Important Notes**:
+- Requires **Admin** permission level
+- Protected by kill switch in production environments
+- Reason is logged for compliance and audit purposes
+- Executes in a database transaction (rolls back on error)
+- Best used to fix triggers that have drifted from their DSL definition
+
 ## Migration Management
 
 The Web UI provides full migration management capabilities.
@@ -159,33 +206,51 @@ After each migration action:
 
 ## SQL Capsules
 
-SQL Capsules provide emergency escape hatches for executing SQL directly.
+SQL Capsules provide emergency escape hatches for executing SQL directly with comprehensive safety checks and audit logging.
 
 ### When to Use SQL Capsules
 
 Use SQL Capsules for:
 - Emergency fixes in production
-- Quick database queries
+- Critical data corrections
 - Testing SQL functions
 - Debugging trigger behavior
-
-### Executing SQL
-
-1. Navigate to "SQL Capsules" tab
-2. Enter your SQL query:
-   ```sql
-   SELECT * FROM pg_sql_triggers_registry;
-   ```
-3. Click "Execute"
-4. In production, enter confirmation text: `EXECUTE SQL`
-5. Review results in the output panel
+- One-off database operations
+
+### Creating and Executing SQL Capsules
+
+1. Navigate to "SQL Capsules" → "New SQL Capsule"
+2. Fill in the capsule form:
+   - **Name**: Unique identifier (alphanumeric, underscores, hyphens only)
+   - **Environment**: Target environment (e.g., production, staging)
+   - **Purpose**: Detailed explanation of what the SQL does and why (required for audit trail)
+   - **SQL**: The SQL statement(s) to execute
+3. Click "Create and Execute" or "Save for Later"
+4. Review the capsule details on the confirmation page
+5. In protected environments, enter confirmation text when prompted
+6. Click "Execute" to run the SQL
+7. Review the execution results
+
+### Viewing Capsule History
+
+1. Navigate to "SQL Capsules" → "History"
+2. View list of previously executed capsules with:
+   - Name and purpose
+   - Environment and timestamp
+   - SQL checksum
+   - Execution status
+3. Click on a capsule to view details
+4. Re-execute historical capsules if needed
 
 ### Safety Features
 
-- **Production Protection**: Requires confirmation in protected environments
-- **Read-Only Mode**: Optional configuration for limiting to SELECT queries
-- **Query Logging**: All SQL execution is logged
-- **Permission Checks**: Requires Admin permission level
+- **Admin Permission Required**: Only Admin users can create and execute SQL capsules
+- **Production Protection**: Requires typed confirmation in protected environments
+- **Kill Switch Integration**: All executions are protected by kill switch
+- **Comprehensive Logging**: All operations logged with actor, timestamp, and checksum
+- **Transactional Execution**: SQL runs in a transaction and rolls back on error
+- **Registry Storage**: All capsules are stored in the registry with checksums
+- **Purpose Tracking**: Required purpose field ensures all executions are documented
 
 ### Example SQL Capsules
 

data/lib/pg_sql_triggers/registry/manager.rb

@@ -33,8 +33,13 @@ module PgSqlTriggers
           trigger_name = definition.name
 
           # Use cached lookup if available to avoid N+1 queries during trigger file loading
-          existing = _registry_cache[trigger_name] ||=
-            PgSqlTriggers::TriggerRegistry.find_by(trigger_name: trigger_name)
+          # Explicitly check cache first to avoid query in some Ruby versions where ||= may evaluate RHS
+          existing = if _registry_cache.key?(trigger_name)
+                       _registry_cache[trigger_name]
+                     else
+                       _registry_cache[trigger_name] =
+                         PgSqlTriggers::TriggerRegistry.find_by(trigger_name: trigger_name)
+                     end
 
           # Calculate checksum using field-concatenation (consistent with TriggerRegistry model)
           checksum = calculate_checksum(definition)
@@ -51,17 +56,27 @@ module PgSqlTriggers
           }
 
           if existing
-            begin
-              existing.update!(attributes)
-              # Update cache with the modified record (reload to get fresh data)
-              reloaded = existing.reload
-              _registry_cache[trigger_name] = reloaded
-              reloaded
-            rescue ActiveRecord::RecordNotFound
-              # Cached record was deleted, create a new one
-              new_record = PgSqlTriggers::TriggerRegistry.create!(attributes)
-              _registry_cache[trigger_name] = new_record
-              new_record
+            # Check if attributes have actually changed to avoid unnecessary queries
+            attributes_changed = attributes.any? do |key, value|
+              existing.send(key) != value
+            end
+
+            if attributes_changed
+              begin
+                existing.update!(attributes)
+                # Update cache with the modified record (reload to get fresh data)
+                reloaded = existing.reload
+                _registry_cache[trigger_name] = reloaded
+                reloaded
+              rescue ActiveRecord::RecordNotFound
+                # Cached record was deleted, create a new one
+                new_record = PgSqlTriggers::TriggerRegistry.create!(attributes)
+                _registry_cache[trigger_name] = new_record
+                new_record
+              end
+            else
+              # No changes, return cached record without any queries
+              existing
             end
           else
             new_record = PgSqlTriggers::TriggerRegistry.create!(attributes)

data/lib/pg_sql_triggers/registry.rb

@@ -32,5 +32,46 @@ module PgSqlTriggers
     def self.validate!
       Validator.validate!
     end
+
+    # Console APIs for trigger operations
+    # These methods provide a convenient interface for managing triggers from the Rails console
+
+    def self.enable(trigger_name, actor:, confirmation: nil)
+      check_permission!(actor, :enable_trigger)
+      trigger = find_trigger!(trigger_name)
+      trigger.enable!(confirmation: confirmation)
+    end
+
+    def self.disable(trigger_name, actor:, confirmation: nil)
+      check_permission!(actor, :disable_trigger)
+      trigger = find_trigger!(trigger_name)
+      trigger.disable!(confirmation: confirmation)
+    end
+
+    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
+
+    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)
+      trigger.re_execute!(reason: reason, confirmation: confirmation, actor: actor)
+    end
+
+    # Private helper methods
+
+    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"
+    end
+    private_class_method :find_trigger!
+
+    def self.check_permission!(actor, action)
+      PgSqlTriggers::Permissions.check!(actor, action)
+    end
+    private_class_method :check_permission!
   end
 end

data/lib/pg_sql_triggers/sql/capsule.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module PgSqlTriggers
+  module SQL
+    # Capsule represents a named SQL capsule with environment declaration and purpose
+    # Used for emergency operations and manual SQL execution
+    #
+    # @example Creating a SQL capsule
+    #   capsule = PgSqlTriggers::SQL::Capsule.new(
+    #     name: "fix_user_permissions",
+    #     environment: "production",
+    #     purpose: "Emergency fix for user permission issue",
+    #     sql: "UPDATE users SET role = 'admin' WHERE email = 'admin@example.com';"
+    #   )
+    #
+    class Capsule
+      attr_reader :name, :environment, :purpose, :sql, :created_at
+
+      # @param name [String] The name of the SQL capsule
+      # @param environment [String] The environment this capsule is intended for
+      # @param purpose [String] Description of what this capsule does and why
+      # @param sql [String] The SQL to execute
+      # @param created_at [Time, nil] The timestamp when the capsule was created (defaults to now)
+      def initialize(name:, environment:, purpose:, sql:, created_at: nil)
+        @name = name
+        @environment = environment
+        @purpose = purpose
+        @sql = sql
+        @created_at = created_at || Time.current
+        validate!
+      end
+
+      # Calculates the checksum of the SQL content
+      # @return [String] The SHA256 checksum of the SQL
+      def checksum
+        @checksum ||= Digest::SHA256.hexdigest(sql.to_s)
+      end
+
+      # Converts the capsule to a hash suitable for storage
+      # @return [Hash] The capsule data
+      def to_h
+        {
+          name: name,
+          environment: environment,
+          purpose: purpose,
+          sql: sql,
+          checksum: checksum,
+          created_at: created_at
+        }
+      end
+
+      # Returns the registry trigger name for this capsule
+      # SQL capsules are stored in the registry with a special naming pattern
+      # @return [String] The trigger name for registry storage
+      def registry_trigger_name
+        "sql_capsule_#{name}"
+      end
+
+      private
+
+      def validate!
+        errors = []
+        errors << "Name cannot be blank" if name.nil? || name.to_s.strip.empty?
+        errors << "Environment cannot be blank" if environment.nil? || environment.to_s.strip.empty?
+        errors << "Purpose cannot be blank" if purpose.nil? || purpose.to_s.strip.empty?
+        errors << "SQL cannot be blank" if sql.nil? || sql.to_s.strip.empty?
+
+        # Validate name format (alphanumeric, underscores, hyphens only)
+        unless name.to_s.match?(/\A[a-z0-9_-]+\z/i)
+          errors << "Name must contain only letters, numbers, underscores, and hyphens"
+        end
+
+        raise ArgumentError, "Invalid capsule: #{errors.join(', ')}" if errors.any?
+      end
+    end
+  end
+end

data/lib/pg_sql_triggers/sql/executor.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module PgSqlTriggers
+  module SQL
+    # Executor handles the execution of SQL capsules with safety checks and logging
+    #
+    # @example Execute a SQL capsule
+    #   capsule = PgSqlTriggers::SQL::Capsule.new(name: "fix", ...)
+    #   result = PgSqlTriggers::SQL::Executor.execute(capsule, actor: current_actor, confirmation: "EXECUTE FIX")
+    #
+    class Executor
+      class << self
+        # Executes a SQL capsule with safety checks
+        #
+        # @param capsule [Capsule] The SQL capsule to execute
+        # @param actor [Hash] Information about who is executing the capsule
+        # @param confirmation [String, nil] The confirmation text for kill switch
+        # @param dry_run [Boolean] If true, only validate without executing
+        # @return [Hash] Result of the execution with :success, :message, and :data keys
+        def execute(capsule, actor:, confirmation: nil, dry_run: false)
+          validate_capsule!(capsule)
+
+          # Check permissions
+          check_permissions!(actor)
+
+          # Check kill switch
+          check_kill_switch!(capsule, actor, confirmation)
+
+          # Log the execution attempt
+          log_execution_attempt(capsule, actor, dry_run)
+
+          if dry_run
+            return {
+              success: true,
+              message: "Dry run successful. SQL would be executed.",
+              data: { checksum: capsule.checksum }
+            }
+          end
+
+          # Execute in transaction
+          result = execute_in_transaction(capsule, actor)
+
+          # Update registry after successful execution
+          update_registry(capsule) if result[:success]
+
+          # Log the result
+          log_execution_result(capsule, actor, result)
+
+          result
+        rescue StandardError => e
+          log_execution_error(capsule, actor, e)
+          {
+            success: false,
+            message: "Execution failed: #{e.message}",
+            error: e
+          }
+        end
+
+        # Executes a SQL capsule by name from the registry
+        #
+        # @param capsule_name [String] The name of the capsule to execute
+        # @param actor [Hash] Information about who is executing the capsule
+        # @param confirmation [String, nil] The confirmation text for kill switch
+        # @param dry_run [Boolean] If true, only validate without executing
+        # @return [Hash] Result of the execution
+        def execute_capsule(capsule_name, actor:, confirmation: nil, dry_run: false)
+          capsule = load_capsule_from_registry(capsule_name)
+
+          unless capsule
+            return {
+              success: false,
+              message: "Capsule '#{capsule_name}' not found in registry"
+            }
+          end
+
+          execute(capsule, actor: actor, confirmation: confirmation, dry_run: dry_run)
+        end
+
+        private
+
+        def validate_capsule!(capsule)
+          raise ArgumentError, "Capsule must be a PgSqlTriggers::SQL::Capsule" unless capsule.is_a?(Capsule)
+        end
+
+        def check_permissions!(actor)
+          PgSqlTriggers::Permissions.check!(actor, :execute_sql)
+        rescue PgSqlTriggers::PermissionError => e
+          raise PgSqlTriggers::PermissionError,
+                "SQL capsule execution requires Admin role: #{e.message}"
+        end
+
+        def check_kill_switch!(_capsule, actor, confirmation)
+          PgSqlTriggers::SQL::KillSwitch.check!(
+            operation: :execute_sql_capsule,
+            environment: Rails.env,
+            confirmation: confirmation,
+            actor: actor
+          )
+        end
+
+        def execute_in_transaction(capsule, _actor)
+          ActiveRecord::Base.transaction do
+            result = ActiveRecord::Base.connection.execute(capsule.sql)
+
+            {
+              success: true,
+              message: "SQL capsule '#{capsule.name}' executed successfully",
+              data: {
+                checksum: capsule.checksum,
+                rows_affected: result.cmd_tuples || 0
+              }
+            }
+          end
+        end
+
+        def update_registry(capsule)
+          # Check if capsule already exists in registry
+          registry_entry = PgSqlTriggers::TriggerRegistry.find_or_initialize_by(
+            trigger_name: capsule.registry_trigger_name
+          )
+
+          registry_entry.assign_attributes(
+            table_name: "manual_sql_execution",
+            version: Time.current.to_i,
+            checksum: capsule.checksum,
+            source: "manual_sql",
+            function_body: capsule.sql,
+            condition: capsule.purpose,
+            environment: capsule.environment,
+            enabled: true,
+            last_executed_at: Time.current
+          )
+
+          registry_entry.save!
+        rescue StandardError => e
+          logger&.error "[SQL_CAPSULE] Failed to update registry: #{e.message}"
+          # Don't fail the execution if registry update fails
+        end
+
+        def load_capsule_from_registry(capsule_name)
+          trigger_name = "sql_capsule_#{capsule_name}"
+          registry_entry = PgSqlTriggers::TriggerRegistry.find_by(
+            trigger_name: trigger_name,
+            source: "manual_sql"
+          )
+
+          return nil unless registry_entry
+
+          Capsule.new(
+            name: capsule_name,
+            environment: registry_entry.environment || Rails.env.to_s,
+            purpose: registry_entry.condition || "No purpose specified",
+            sql: registry_entry.function_body,
+            created_at: registry_entry.created_at
+          )
+        end
+
+        # Logging methods
+
+        def log_execution_attempt(capsule, actor, dry_run)
+          mode = dry_run ? "DRY_RUN" : "EXECUTE"
+          logger&.info "[SQL_CAPSULE] #{mode} ATTEMPT: name=#{capsule.name} " \
+                       "environment=#{capsule.environment} actor=#{format_actor(actor)}"
+        end
+
+        def log_execution_result(capsule, actor, result)
+          status = result[:success] ? "SUCCESS" : "FAILED"
+          logger&.info "[SQL_CAPSULE] #{status}: name=#{capsule.name} " \
+                       "environment=#{capsule.environment} actor=#{format_actor(actor)} " \
+                       "checksum=#{capsule.checksum}"
+        end
+
+        def log_execution_error(capsule, actor, error)
+          # Handle case where capsule might not be valid
+          capsule_name = capsule.respond_to?(:name) ? capsule.name : "invalid_capsule"
+          environment = capsule.respond_to?(:environment) ? capsule.environment : "unknown"
+
+          logger&.error "[SQL_CAPSULE] ERROR: name=#{capsule_name} " \
+                        "environment=#{environment} actor=#{format_actor(actor)} " \
+                        "error=#{error.class.name} message=#{error.message}"
+        end
+
+        def format_actor(actor)
+          return "unknown" if actor.nil?
+          return actor.to_s unless actor.is_a?(Hash)
+
+          "#{actor[:type] || 'unknown'}:#{actor[:id] || 'unknown'}"
+        end
+
+        def logger
+          if PgSqlTriggers.respond_to?(:logger) && PgSqlTriggers.logger
+            PgSqlTriggers.logger
+          elsif defined?(Rails) && Rails.respond_to?(:logger)
+            Rails.logger
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pg_sql_triggers/version.rb

@@ -11,5 +11,5 @@
 # 3. Run: bundle exec rake release
 # See RELEASE.md for detailed release instructions
 module PgSqlTriggers
-  VERSION = "1.1.1"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pg_sql_triggers
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - samaswin
@@ -201,7 +201,9 @@ files:
 - app/controllers/pg_sql_triggers/dashboard_controller.rb
 - app/controllers/pg_sql_triggers/generator_controller.rb
 - app/controllers/pg_sql_triggers/migrations_controller.rb
+- app/controllers/pg_sql_triggers/sql_capsules_controller.rb
 - app/controllers/pg_sql_triggers/tables_controller.rb
+- app/controllers/pg_sql_triggers/triggers_controller.rb
 - app/models/pg_sql_triggers/application_record.rb
 - app/models/pg_sql_triggers/trigger_registry.rb
 - app/views/layouts/pg_sql_triggers/application.html.erb
@@ -210,8 +212,13 @@ files:
 - app/views/pg_sql_triggers/generator/preview.html.erb
 - app/views/pg_sql_triggers/shared/_confirmation_modal.html.erb
 - app/views/pg_sql_triggers/shared/_kill_switch_status.html.erb
+- app/views/pg_sql_triggers/sql_capsules/new.html.erb
+- app/views/pg_sql_triggers/sql_capsules/show.html.erb
 - app/views/pg_sql_triggers/tables/index.html.erb
 - app/views/pg_sql_triggers/tables/show.html.erb
+- app/views/pg_sql_triggers/triggers/_drop_modal.html.erb
+- app/views/pg_sql_triggers/triggers/_re_execute_modal.html.erb
+- app/views/pg_sql_triggers/triggers/show.html.erb
 - config/initializers/pg_sql_triggers.rb
 - config/routes.rb
 - db/migrate/20251222000001_create_pg_sql_triggers_tables.rb
@@ -258,6 +265,8 @@ files:
 - lib/pg_sql_triggers/registry/manager.rb
 - lib/pg_sql_triggers/registry/validator.rb
 - lib/pg_sql_triggers/sql.rb
+- lib/pg_sql_triggers/sql/capsule.rb
+- lib/pg_sql_triggers/sql/executor.rb
 - lib/pg_sql_triggers/sql/kill_switch.rb
 - lib/pg_sql_triggers/testing.rb
 - lib/pg_sql_triggers/testing/dry_run.rb