pg_sql_triggers 1.1.0 → 1.2.0

data/docs/api-reference.md

@@ -114,6 +114,102 @@ end
 
 **Returns**: `true` if all triggers are valid
 
+### `PgSqlTriggers::Registry.enable(trigger_name, actor:, confirmation: nil)`
+
+Enables a trigger with permission and kill switch checks.
+
+```ruby
+# Enable trigger
+PgSqlTriggers::Registry.enable(
+  "users_email_validation",
+  actor: { type: "user", id: "admin@example.com" },
+  confirmation: "EXECUTE TRIGGER_ENABLE"
+)
+
+# With current user as actor
+actor = { type: "user", id: current_user.email }
+PgSqlTriggers::Registry.enable("billing_trigger", actor: actor, confirmation: "EXECUTE TRIGGER_ENABLE")
+```
+
+**Parameters**:
+- `trigger_name` (String): The name of the trigger to enable
+- `actor` (Hash): Information about who is performing the operation (requires `:type` and `:id` keys)
+- `confirmation` (String, optional): Kill switch confirmation text
+
+**Raises**: `PgSqlTriggers::PermissionError`, `PgSqlTriggers::KillSwitchError`, `ArgumentError`
+
+**Returns**: `true` on success
+
+### `PgSqlTriggers::Registry.disable(trigger_name, actor:, confirmation: nil)`
+
+Disables a trigger with permission and kill switch checks.
+
+```ruby
+# Disable trigger
+PgSqlTriggers::Registry.disable(
+  "users_email_validation",
+  actor: { type: "user", id: "admin@example.com" },
+  confirmation: "EXECUTE TRIGGER_DISABLE"
+)
+```
+
+**Parameters**:
+- `trigger_name` (String): The name of the trigger to disable
+- `actor` (Hash): Information about who is performing the operation
+- `confirmation` (String, optional): Kill switch confirmation text
+
+**Raises**: `PgSqlTriggers::PermissionError`, `PgSqlTriggers::KillSwitchError`, `ArgumentError`
+
+**Returns**: `true` on success
+
+### `PgSqlTriggers::Registry.drop(trigger_name, actor:, reason:, confirmation: nil)`
+
+Drops a trigger from the database and removes it from the registry.
+
+```ruby
+# Drop trigger
+PgSqlTriggers::Registry.drop(
+  "old_trigger",
+  actor: { type: "user", id: "admin@example.com" },
+  reason: "No longer needed in production",
+  confirmation: "EXECUTE TRIGGER_DROP"
+)
+```
+
+**Parameters**:
+- `trigger_name` (String): The name of the trigger to drop
+- `actor` (Hash): Information about who is performing the operation (Admin permission required)
+- `reason` (String): Required explanation for why the trigger is being dropped (logged for audit)
+- `confirmation` (String, optional): Kill switch confirmation text
+
+**Raises**: `PgSqlTriggers::PermissionError`, `PgSqlTriggers::KillSwitchError`, `ArgumentError`
+
+**Returns**: `true` on success
+
+### `PgSqlTriggers::Registry.re_execute(trigger_name, actor:, reason:, confirmation: nil)`
+
+Re-executes a trigger by dropping and recreating it from the registry definition. Useful for fixing drifted triggers.
+
+```ruby
+# Re-execute drifted trigger
+PgSqlTriggers::Registry.re_execute(
+  "drifted_trigger",
+  actor: { type: "user", id: "admin@example.com" },
+  reason: "Fix drift detected in production",
+  confirmation: "EXECUTE TRIGGER_RE_EXECUTE"
+)
+```
+
+**Parameters**:
+- `trigger_name` (String): The name of the trigger to re-execute
+- `actor` (Hash): Information about who is performing the operation (Admin permission required)
+- `reason` (String): Required explanation for why the trigger is being re-executed (logged for audit)
+- `confirmation` (String, optional): Kill switch confirmation text
+
+**Raises**: `PgSqlTriggers::PermissionError`, `PgSqlTriggers::KillSwitchError`, `ArgumentError`
+
+**Returns**: `true` on success
+
 ## Migrator API
 
 The Migrator API manages trigger migrations programmatically.
@@ -318,6 +414,124 @@ end
 
 **Returns**: Result of the block
 
+## SQL Capsule API
+
+The SQL Capsule API provides emergency SQL execution capabilities with safety checks.
+
+### `PgSqlTriggers::SQL::Capsule.new(name:, environment:, purpose:, sql:, created_at: nil)`
+
+Creates a new SQL capsule for emergency operations.
+
+```ruby
+capsule = PgSqlTriggers::SQL::Capsule.new(
+  name: "fix_user_permissions",
+  environment: "production",
+  purpose: "Emergency fix for user permission issue after deployment",
+  sql: "UPDATE users SET role = 'admin' WHERE email = 'admin@example.com';"
+)
+```
+
+**Parameters**:
+- `name` (String): Unique name for the capsule (alphanumeric, underscores, hyphens only)
+- `environment` (String): Target environment (e.g., "production", "staging")
+- `purpose` (String): Description of what the capsule does and why (required for audit trail)
+- `sql` (String): The SQL statement(s) to execute
+- `created_at` (Time, optional): Creation timestamp (defaults to current time)
+
+**Raises**: `ArgumentError` if validation fails
+
+### `capsule.checksum`
+
+Returns the SHA256 checksum of the SQL content.
+
+```ruby
+capsule = PgSqlTriggers::SQL::Capsule.new(name: "fix", ...)
+puts capsule.checksum
+# => "a3f5b8c9d2e..."
+```
+
+**Returns**: String (SHA256 hash)
+
+### `capsule.to_h`
+
+Converts the capsule to a hash for storage or serialization.
+
+```ruby
+capsule_data = capsule.to_h
+# => {
+#   name: "fix_user_permissions",
+#   environment: "production",
+#   purpose: "Emergency fix...",
+#   sql: "UPDATE users...",
+#   checksum: "a3f5b8c9d2e...",
+#   created_at: 2026-01-01 12:00:00 UTC
+# }
+```
+
+**Returns**: Hash
+
+## SQL Executor API
+
+The SQL Executor API handles safe execution of SQL capsules with comprehensive logging.
+
+### `PgSqlTriggers::SQL::Executor.execute(capsule, actor:, confirmation: nil, dry_run: false)`
+
+Executes a SQL capsule with safety checks and logging.
+
+```ruby
+capsule = PgSqlTriggers::SQL::Capsule.new(
+  name: "emergency_fix",
+  environment: "production",
+  purpose: "Fix critical data corruption",
+  sql: "UPDATE orders SET status = 'completed' WHERE id IN (123, 456);"
+)
+
+# Execute the capsule
+result = PgSqlTriggers::SQL::Executor.execute(
+  capsule,
+  actor: { type: "user", id: "admin@example.com" },
+  confirmation: "EXECUTE SQL"
+)
+
+if result[:success]
+  puts "SQL executed successfully"
+  puts "Rows affected: #{result[:data][:rows_affected]}"
+else
+  puts "Execution failed: #{result[:message]}"
+end
+```
+
+**Parameters**:
+- `capsule` (Capsule): The SQL capsule to execute
+- `actor` (Hash): Information about who is executing (Admin permission required)
+- `confirmation` (String, optional): Kill switch confirmation text
+- `dry_run` (Boolean): If true, validates without executing (default: false)
+
+**Returns**: Hash with `:success`, `:message`, and `:data` keys
+
+**Raises**: Permission and kill switch errors are returned in the result hash
+
+### `PgSqlTriggers::SQL::Executor.execute_capsule(capsule_name, actor:, confirmation: nil, dry_run: false)`
+
+Executes a previously stored SQL capsule by name from the registry.
+
+```ruby
+# Execute a capsule stored in the registry
+result = PgSqlTriggers::SQL::Executor.execute_capsule(
+  "emergency_fix",
+  actor: { type: "user", id: "admin@example.com" },
+  confirmation: "EXECUTE SQL"
+)
+```
+
+**Parameters**:
+- `capsule_name` (String): Name of the capsule in the registry
+- `actor` (Hash): Information about who is executing
+- `confirmation` (String, optional): Kill switch confirmation text
+- `dry_run` (Boolean): If true, validates without executing
+
+**Returns**: Hash with execution results
+
 ## DSL API
 
 The DSL API is used to define triggers in your application.
@@ -487,17 +701,51 @@ trigger.disable!(confirmation: "EXECUTE TRIGGER_DISABLE")
 
 **Returns**: `true` on success
 
-#### `drop!(confirmation: nil)`
+#### `drop!(reason:, confirmation: nil, actor: nil)`
 
-Drops the trigger from the database.
+Drops the trigger from the database and removes it from the registry.
 
 ```ruby
-trigger = PgSqlTriggers::TriggerRegistry.find_by(trigger_name: "users_email_validation")
-trigger.drop!(confirmation: "EXECUTE TRIGGER_DROP")
+trigger = PgSqlTriggers::TriggerRegistry.find_by(trigger_name: "old_trigger")
+
+# Drop with reason (required)
+trigger.drop!(
+  reason: "No longer needed in production",
+  confirmation: "EXECUTE TRIGGER_DROP",
+  actor: { type: "user", id: "admin@example.com" }
+)
 ```
 
 **Parameters**:
+- `reason` (String, required): Explanation for why the trigger is being dropped (logged for audit trail)
 - `confirmation` (String, optional): Kill switch confirmation text
+- `actor` (Hash, optional): Information about who is performing the operation
+
+**Raises**: `ArgumentError` if reason is blank, `PgSqlTriggers::KillSwitchError`
+
+**Returns**: `true` on success
+
+#### `re_execute!(reason:, confirmation: nil, actor: nil)`
+
+Re-executes the trigger by dropping and recreating it from the registry definition. Useful for fixing drifted triggers.
+
+```ruby
+trigger = PgSqlTriggers::TriggerRegistry.find_by(trigger_name: "drifted_trigger")
+
+# Re-execute to fix drift
+trigger.re_execute!(
+  reason: "Fix drift detected after manual database changes",
+  confirmation: "EXECUTE TRIGGER_RE_EXECUTE",
+  actor: { type: "user", id: "admin@example.com" }
+)
+```
+
+**Parameters**:
+- `reason` (String, required): Explanation for why the trigger is being re-executed (logged for audit trail)
+- `confirmation` (String, optional): Kill switch confirmation text
+- `actor` (Hash, optional): Information about who is performing the operation
+
+**Raises**: `ArgumentError` if reason is blank or function_body is missing, `PgSqlTriggers::KillSwitchError`, `StandardError`
 
 **Returns**: `true` on success
 

data/docs/getting-started.md

@@ -132,4 +132,4 @@ You should see your trigger listed in the dashboard.
 
 ## Examples Repository
 
-For working examples and a complete demonstration of PgSqlTriggers in action, check out the [example repository](https://github.com/samaswin87/pg_triggers_example).
+For working examples and a complete demonstration of PgSqlTriggers in action, check out the [example repository](https://github.com/samaswin/pg_triggers_example).

data/docs/kill-switch.md

@@ -422,21 +422,21 @@ All kill switch events are logged with comprehensive information.
 Operation was prevented:
 
 ```
-[KILL_SWITCH] BLOCKED: operation=trigger_migrate environment=production actor=CLI:ashwin reason=no_override
+[KILL_SWITCH] BLOCKED: operation=trigger_migrate environment=production actor=CLI:samaswin reason=no_override
 ```
 
 #### OVERRIDDEN
 Operation allowed with valid override:
 
 ```
-[KILL_SWITCH] OVERRIDDEN: operation=trigger_migrate environment=production actor=CLI:ashwin source=env_with_confirmation confirmation=EXECUTE TRIGGER_MIGRATE
+[KILL_SWITCH] OVERRIDDEN: operation=trigger_migrate environment=production actor=CLI:samaswin source=env_with_confirmation confirmation=EXECUTE TRIGGER_MIGRATE
 ```
 
 #### ALLOWED
 Operation allowed (not in protected environment):
 
 ```
-[KILL_SWITCH] ALLOWED: operation=trigger_migrate environment=development actor=CLI:ashwin reason=not_protected_environment
+[KILL_SWITCH] ALLOWED: operation=trigger_migrate environment=development actor=CLI:samaswin reason=not_protected_environment
 ```
 
 ### Audit Information

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/generators/pg_sql_triggers/templates/README

@@ -31,6 +31,6 @@ Next steps:
 
 5. Visit http://localhost:3000/pg_sql_triggers to access the UI
 
-For more information, see: https://github.com/samaswin87/pg_sql_triggers
+For more information, see: https://github.com/samaswin/pg_sql_triggers
 
 ===============================================================================

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