pg_sql_triggers 1.1.1 → 1.3.0

data/README.md

@@ -95,11 +95,66 @@ Automatically detect when database triggers drift from your DSL definitions.
 Multi-layered safety mechanism preventing accidental destructive operations in production environments.
 
 ### Web Dashboard
-Visual interface for managing triggers, running migrations, and executing SQL capsules.
+Visual interface for managing triggers, running migrations, and executing SQL capsules. Includes:
+- **Quick Actions**: Enable/disable, drop, and re-execute triggers from dashboard
+- **Last Applied Tracking**: See when triggers were last applied with human-readable timestamps
+- **Breadcrumb Navigation**: Easy navigation between dashboard, tables, and triggers
+- **Permission-Aware UI**: Buttons show/hide based on user role
+
+### Audit Logging
+Comprehensive audit trail for all trigger operations:
+- Track who performed each operation (actor tracking)
+- Before and after state capture
+- Success/failure logging with error messages
+- Reason tracking for drop and re-execute operations
+
+### SQL Capsules
+Emergency SQL execution feature for critical operations with Admin permission requirements, kill switch protection, and comprehensive logging.
+
+### Drop & Re-Execute Flow
+Operational controls for trigger lifecycle management with drop and re-execute capabilities, drift comparison, and required reason logging.
 
 ### Permissions
 Three-tier permission system (Viewer, Operator, Admin) with customizable authorization.
 
+## Console API
+
+PgSqlTriggers provides a comprehensive console API for managing triggers programmatically:
+
+```ruby
+# Query triggers
+triggers = PgSqlTriggers::Registry.list
+enabled = PgSqlTriggers::Registry.enabled
+disabled = PgSqlTriggers::Registry.disabled
+user_triggers = PgSqlTriggers::Registry.for_table(:users)
+
+# Check drift status
+drift_info = PgSqlTriggers::Registry.diff
+drifted = PgSqlTriggers::Registry.drifted
+in_sync = PgSqlTriggers::Registry.in_sync
+unknown = PgSqlTriggers::Registry.unknown_triggers
+dropped = PgSqlTriggers::Registry.dropped
+
+# Enable/disable triggers
+PgSqlTriggers::Registry.enable("users_email_validation", actor: current_user, confirmation: "EXECUTE TRIGGER_ENABLE")
+PgSqlTriggers::Registry.disable("users_email_validation", actor: current_user, confirmation: "EXECUTE TRIGGER_DISABLE")
+
+# Drop and re-execute triggers
+PgSqlTriggers::Registry.drop("old_trigger", actor: current_user, reason: "No longer needed", confirmation: "EXECUTE TRIGGER_DROP")
+PgSqlTriggers::Registry.re_execute("drifted_trigger", actor: current_user, reason: "Fix drift", confirmation: "EXECUTE TRIGGER_RE_EXECUTE")
+
+# Execute SQL capsules
+capsule = PgSqlTriggers::SQL::Capsule.new(
+  name: "emergency_fix",
+  environment: "production",
+  purpose: "Fix critical data issue",
+  sql: "UPDATE users SET status = 'active' WHERE id = 123"
+)
+PgSqlTriggers::SQL::Executor.execute(capsule, actor: current_user, confirmation: "EXECUTE SQL")
+```
+
+See the [API Reference](docs/api-reference.md) for complete documentation of all console APIs.
+
 ## Examples
 
 For working examples and complete demonstrations, check out the [example repository](https://github.com/samaswin/pg_triggers_example).

data/app/assets/javascripts/pg_sql_triggers/trigger_actions.js

@@ -0,0 +1,50 @@
+// AJAX handlers for trigger actions
+(function() {
+  'use strict';
+
+  // Handle AJAX form submissions
+  document.addEventListener('DOMContentLoaded', function() {
+    // Set up AJAX error handling
+    document.addEventListener('ajax:error', function(event) {
+      const detail = event.detail || [];
+      const error = detail[0] || {};
+      const status = error.status || 500;
+      const message = error.message || 'An error occurred';
+
+      alert('Error: ' + message);
+      console.error('AJAX Error:', error);
+    });
+
+    // Handle AJAX success for trigger actions
+    document.addEventListener('ajax:success', function(event) {
+      const [data, status, xhr] = event.detail;
+      
+      // If the response contains a redirect, follow it
+      if (xhr.getResponseHeader('Location')) {
+        window.location.href = xhr.getResponseHeader('Location');
+      } else {
+        // Otherwise, reload the page to show updated state
+        window.location.reload();
+      }
+    });
+
+    // Handle AJAX complete to show loading states
+    document.addEventListener('ajax:before', function(event) {
+      const form = event.target;
+      const submitButton = form.querySelector('button[type="submit"], button[type="button"]');
+      if (submitButton) {
+        submitButton.disabled = true;
+        submitButton.textContent = 'Processing...';
+      }
+    });
+
+    document.addEventListener('ajax:complete', function(event) {
+      const form = event.target;
+      const submitButton = form.querySelector('button[type="submit"], button[type="button"]');
+      if (submitButton) {
+        submitButton.disabled = false;
+      }
+    });
+  });
+})();
+

data/app/controllers/concerns/pg_sql_triggers/error_handling.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module PgSqlTriggers
+  module ErrorHandling
+    extend ActiveSupport::Concern
+
+    # Handles errors and formats them for display.
+    # Returns a formatted error message for flash display.
+    #
+    # @param error [Exception] The error to format
+    # @return [String] Formatted error message
+    def format_error_for_flash(error)
+      return error.to_s unless error.is_a?(PgSqlTriggers::Error)
+
+      # Use user_message which includes recovery suggestions
+      error.user_message
+    end
+
+    # Rescues from PgSqlTriggers errors and sets appropriate flash messages.
+    #
+    # @param error [Exception] The error to handle
+    # @return [void]
+    def rescue_pg_sql_triggers_error(error)
+      Rails.logger.error("#{error.class.name}: #{error.message}")
+      Rails.logger.error(error.backtrace.join("\n")) if Rails.env.development? && error.respond_to?(:backtrace)
+
+      flash[:error] = if error.is_a?(PgSqlTriggers::Error)
+                        format_error_for_flash(error)
+                      else
+                        "An unexpected error occurred: #{error.message}"
+                      end
+    end
+
+    # Handles kill switch errors with appropriate flash message and redirect.
+    #
+    # @param error [PgSqlTriggers::KillSwitchError] The kill switch error
+    # @param redirect_path [String, nil] Optional redirect path (defaults to root_path)
+    # @return [void]
+    def handle_kill_switch_error(error, redirect_path: nil)
+      flash[:error] = error.message
+      redirect_to redirect_path || root_path
+    end
+
+    # Handles standard errors with logging and flash message.
+    #
+    # @param error [Exception] The error to handle
+    # @param operation [String] Description of the operation that failed
+    # @param redirect_path [String, nil] Optional redirect path (defaults to root_path)
+    # @return [void]
+    def handle_standard_error(error, operation:, redirect_path: nil)
+      Rails.logger.error("#{operation} failed: #{error.message}\n#{error.backtrace.join("\n")}")
+      flash[:error] = "#{operation}: #{error.message}"
+      redirect_to redirect_path || root_path
+    end
+  end
+end

data/app/controllers/concerns/pg_sql_triggers/kill_switch_protection.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module PgSqlTriggers
+  module KillSwitchProtection
+    extend ActiveSupport::Concern
+
+    included do
+      # Helper method available in views
+      helper_method :kill_switch_active?, :expected_confirmation_text, :current_environment
+    end
+
+    # Checks if kill switch is active for the current environment.
+    #
+    # @return [Boolean] true if kill switch is active, false otherwise
+    def kill_switch_active?
+      PgSqlTriggers::SQL::KillSwitch.active?(environment: current_environment)
+    end
+
+    # Checks kill switch before executing a dangerous operation.
+    # Raises KillSwitchError if the operation is blocked.
+    #
+    # @param operation [Symbol] The operation being performed
+    # @param confirmation [String, nil] Optional confirmation text from params
+    # @raise [PgSqlTriggers::KillSwitchError] If the operation is blocked
+    # @return [true] If the operation is allowed
+    def check_kill_switch(operation:, confirmation: nil)
+      PgSqlTriggers::SQL::KillSwitch.check!(
+        operation: operation,
+        environment: current_environment,
+        confirmation: confirmation,
+        actor: current_actor
+      )
+    end
+
+    # Before action to require kill switch override for an action.
+    # Add to specific controller actions that need protection:
+    #   before_action -> { require_kill_switch_override(:operation_name) }, only: [:dangerous_action]
+    #
+    # @param operation [Symbol] The operation name
+    # @param confirmation [String, nil] Optional confirmation text
+    # @raise [PgSqlTriggers::KillSwitchError] If the operation is blocked
+    def require_kill_switch_override(operation, confirmation: nil)
+      check_kill_switch(operation: operation, confirmation: confirmation)
+    end
+
+    # Returns the expected confirmation text for an operation (for use in views).
+    #
+    # @param operation [Symbol] The operation name
+    # @return [String] The expected confirmation text
+    def expected_confirmation_text(operation)
+      if PgSqlTriggers.respond_to?(:kill_switch_confirmation_pattern) &&
+         PgSqlTriggers.kill_switch_confirmation_pattern.respond_to?(:call)
+        PgSqlTriggers.kill_switch_confirmation_pattern.call(operation)
+      else
+        "EXECUTE #{operation.to_s.upcase}"
+      end
+    end
+
+    # Returns the current environment.
+    #
+    # @return [String] The current Rails environment
+    def current_environment
+      Rails.env
+    end
+  end
+end

data/app/controllers/concerns/pg_sql_triggers/permission_checking.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module PgSqlTriggers
+  module PermissionChecking
+    extend ActiveSupport::Concern
+
+    included do
+      # Helper methods available in views
+      helper_method :current_actor, :can_view_triggers?, :can_enable_disable_triggers?,
+                    :can_drop_triggers?, :can_execute_sql?, :can_generate_triggers?, :can_apply_triggers?
+    end
+
+    # Returns the current actor (user) performing the action.
+    # Override this method in host application to provide actual user.
+    #
+    # @return [Hash] Actor information with :type and :id keys
+    def current_actor
+      {
+        type: current_user_type,
+        id: current_user_id
+      }
+    end
+
+    # Returns the current user type.
+    # Override this method in host application.
+    #
+    # @return [String] User type (default: "User")
+    def current_user_type
+      "User"
+    end
+
+    # Returns the current user ID.
+    # Override this method in host application.
+    #
+    # @return [String] User ID (default: "unknown")
+    def current_user_id
+      "unknown"
+    end
+
+    # Checks if current actor has viewer permissions.
+    #
+    # @raise [ActionController::RedirectError] Redirects if permission denied
+    def check_viewer_permission
+      can_access = begin
+        PgSqlTriggers::Permissions.can?(current_actor, :view_triggers, environment: current_environment)
+      rescue StandardError => e
+        Rails.logger.error("Permission check failed: #{e.message}\n#{e.backtrace.join("\n")}")
+        false
+      end
+      return if can_access
+
+      redirect_to root_path, alert: "Insufficient permissions. Viewer role required."
+    end
+
+    # Checks if current actor has operator permissions (enable/disable/apply).
+    #
+    # @raise [ActionController::RedirectError] Redirects if permission denied
+    def check_operator_permission
+      can_access = begin
+        PgSqlTriggers::Permissions.can?(current_actor, :enable_trigger, environment: current_environment)
+      rescue StandardError => e
+        Rails.logger.error("Permission check failed: #{e.message}\n#{e.backtrace.join("\n")}")
+        false
+      end
+      return if can_access
+
+      redirect_to root_path, alert: "Insufficient permissions. Operator role required."
+    end
+
+    # Checks if current actor has admin permissions (drop/re-execute/execute SQL).
+    #
+    # @raise [ActionController::RedirectError] Redirects if permission denied
+    def check_admin_permission
+      can_access = begin
+        PgSqlTriggers::Permissions.can?(current_actor, :drop_trigger, environment: current_environment)
+      rescue StandardError => e
+        Rails.logger.error("Permission check failed: #{e.message}\n#{e.backtrace.join("\n")}")
+        false
+      end
+      return if can_access
+
+      redirect_to root_path, alert: "Insufficient permissions. Admin role required."
+    end
+
+    # Permission helper methods for views
+
+    # @return [Boolean] true if current actor can view triggers
+    def can_view_triggers?
+      PgSqlTriggers::Permissions.can?(current_actor, :view_triggers, environment: current_environment)
+    end
+
+    # @return [Boolean] true if current actor can enable/disable triggers
+    def can_enable_disable_triggers?
+      PgSqlTriggers::Permissions.can?(current_actor, :enable_trigger, environment: current_environment)
+    end
+
+    # @return [Boolean] true if current actor can drop triggers
+    def can_drop_triggers?
+      PgSqlTriggers::Permissions.can?(current_actor, :drop_trigger, environment: current_environment)
+    end
+
+    # @return [Boolean] true if current actor can execute SQL capsules
+    def can_execute_sql?
+      PgSqlTriggers::Permissions.can?(current_actor, :execute_sql, environment: current_environment)
+    end
+
+    # @return [Boolean] true if current actor can generate triggers
+    def can_generate_triggers?
+      PgSqlTriggers::Permissions.can?(current_actor, :apply_trigger, environment: current_environment)
+    end
+
+    # @return [Boolean] true if current actor can apply triggers
+    def can_apply_triggers?
+      PgSqlTriggers::Permissions.can?(current_actor, :apply_trigger, environment: current_environment)
+    end
+  end
+end

data/app/controllers/pg_sql_triggers/application_controller.rb

@@ -1,81 +1,29 @@
 # frozen_string_literal: true
 
 module PgSqlTriggers
+  # Base controller for all pg_sql_triggers controllers.
+  # Includes common concerns for kill switch protection, permission checking, and error handling.
   class ApplicationController < ActionController::Base
     include PgSqlTriggers::Engine.routes.url_helpers
+    include PgSqlTriggers::KillSwitchProtection
+    include PgSqlTriggers::PermissionChecking
+    include PgSqlTriggers::ErrorHandling
 
     protect_from_forgery with: :exception
     layout "pg_sql_triggers/application"
 
     before_action :check_permissions?
 
-    # Helper methods available in views
-    helper_method :current_environment, :kill_switch_active?, :expected_confirmation_text
+    # Include permissions helper for view helpers
+    include PgSqlTriggers::PermissionsHelper
 
     private
 
+    # Override this method in host application to implement custom permission checks.
+    #
+    # @return [Boolean] true if permissions check passes
     def check_permissions?
-      # Override this method in host application to implement custom permission checks
       true
     end
-
-    def current_actor
-      # Override this in host application to provide actual user
-      {
-        type: current_user_type,
-        id: current_user_id
-      }
-    end
-
-    def current_user_type
-      "User"
-    end
-
-    def current_user_id
-      "unknown"
-    end
-
-    # ========== Kill Switch Helpers ==========
-
-    # Returns the current environment
-    def current_environment
-      Rails.env
-    end
-
-    # Checks if kill switch is active for the current environment
-    def kill_switch_active?
-      PgSqlTriggers::SQL::KillSwitch.active?(environment: current_environment)
-    end
-
-    # Checks kill switch before executing a dangerous operation
-    # Raises KillSwitchError if the operation is blocked
-    #
-    # @param operation [Symbol] The operation being performed
-    # @param confirmation [String, nil] Optional confirmation text from params
-    def check_kill_switch(operation:, confirmation: nil)
-      PgSqlTriggers::SQL::KillSwitch.check!(
-        operation: operation,
-        environment: current_environment,
-        confirmation: confirmation,
-        actor: current_actor
-      )
-    end
-
-    # Before action to require kill switch override for an action
-    # Add to specific controller actions that need protection:
-    #   before_action -> { require_kill_switch_override(:operation_name) }, only: [:dangerous_action]
-    def require_kill_switch_override(operation, confirmation: nil)
-      check_kill_switch(operation: operation, confirmation: confirmation)
-    end
-
-    # Returns the expected confirmation text for an operation (for use in views)
-    def expected_confirmation_text(operation)
-      if PgSqlTriggers.respond_to?(:kill_switch_confirmation_pattern) &&
-         PgSqlTriggers.kill_switch_confirmation_pattern.respond_to?(:call)
-        PgSqlTriggers.kill_switch_confirmation_pattern.call(operation)
-      else
-        "EXECUTE #{operation.to_s.upcase}"
-      end
-    end
   end
 end

data/app/controllers/pg_sql_triggers/audit_logs_controller.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module PgSqlTriggers
+  class AuditLogsController < ApplicationController
+    before_action :check_viewer_permission
+
+    # GET /audit_logs
+    # Display audit log entries with filtering and sorting
+    def index
+      @audit_logs = PgSqlTriggers::AuditLog.all
+
+      # Filter by trigger name
+      @audit_logs = @audit_logs.for_trigger(params[:trigger_name]) if params[:trigger_name].present?
+
+      # Filter by operation
+      @audit_logs = @audit_logs.for_operation(params[:operation]) if params[:operation].present?
+
+      # Filter by status
+      if params[:status].present? && %w[success failure].include?(params[:status])
+        @audit_logs = @audit_logs.where(status: params[:status])
+      end
+
+      # Filter by environment
+      @audit_logs = @audit_logs.for_environment(params[:environment]) if params[:environment].present?
+
+      # Filter by actor (search in JSONB field)
+      @audit_logs = @audit_logs.where("actor->>'id' = ?", params[:actor_id]) if params[:actor_id].present?
+
+      # Sort by date (default: most recent first)
+      sort_direction = params[:sort] == "asc" ? :asc : :desc
+      @audit_logs = @audit_logs.order(created_at: sort_direction)
+
+      # Pagination
+      @per_page = (params[:per_page] || 50).to_i
+      @per_page = [@per_page, 200].min # Cap at 200
+      @page = (params[:page] || 1).to_i
+      @total_count = @audit_logs.count
+      @total_pages = @total_count.positive? ? (@total_count.to_f / @per_page).ceil : 1
+      @page = @page.clamp(1, @total_pages)
+
+      offset = (@page - 1) * @per_page
+      @audit_logs = @audit_logs.offset(offset).limit(@per_page)
+
+      # Get distinct values for filter dropdowns
+      @available_trigger_names = PgSqlTriggers::AuditLog.distinct.pluck(:trigger_name).compact.sort
+      @available_operations = PgSqlTriggers::AuditLog.distinct.pluck(:operation).compact.sort
+      @available_environments = PgSqlTriggers::AuditLog.distinct.pluck(:environment).compact.sort
+
+      respond_to do |format|
+        format.html
+        format.csv do
+          send_data generate_csv, filename: "audit_logs_#{Time.current.strftime('%Y%m%d_%H%M%S')}.csv",
+                                  type: "text/csv", disposition: "attachment"
+        end
+      end
+    end
+
+    private
+
+    def generate_csv
+      require "csv"
+
+      # Get all audit logs (no pagination for CSV)
+      audit_logs = PgSqlTriggers::AuditLog.all
+
+      # Apply filters
+      audit_logs = audit_logs.for_trigger(params[:trigger_name]) if params[:trigger_name].present?
+      audit_logs = audit_logs.for_operation(params[:operation]) if params[:operation].present?
+      if params[:status].present? && %w[success failure].include?(params[:status])
+        audit_logs = audit_logs.where(status: params[:status])
+      end
+      audit_logs = audit_logs.for_environment(params[:environment]) if params[:environment].present?
+      audit_logs = audit_logs.where("actor->>'id' = ?", params[:actor_id]) if params[:actor_id].present?
+
+      CSV.generate(headers: true) do |csv|
+        csv << [
+          "ID", "Trigger Name", "Operation", "Status", "Environment",
+          "Actor Type", "Actor ID", "Reason", "Error Message",
+          "Created At"
+        ]
+
+        audit_logs.order(created_at: :desc).find_each do |log|
+          actor_type = log.actor.is_a?(Hash) ? log.actor["type"] || log.actor[:type] : nil
+          actor_id = log.actor.is_a?(Hash) ? log.actor["id"] || log.actor[:id] : nil
+
+          csv << [
+            log.id,
+            log.trigger_name || "",
+            log.operation,
+            log.status,
+            log.environment || "",
+            actor_type || "",
+            actor_id || "",
+            log.reason || "",
+            log.error_message || "",
+            log.created_at&.iso8601 || ""
+          ]
+        end
+      end
+    end
+  end
+end

data/app/controllers/pg_sql_triggers/dashboard_controller.rb

@@ -2,8 +2,13 @@
 
 module PgSqlTriggers
   class DashboardController < ApplicationController
+    before_action :check_viewer_permission
+
     def index
-      @triggers = PgSqlTriggers::TriggerRegistry.order(created_at: :desc)
+      # Sort by installed_at descending (most recent first), fallback to created_at
+      @triggers = PgSqlTriggers::TriggerRegistry.order(
+        Arel.sql("COALESCE(installed_at, created_at) DESC")
+      )
 
       # Get drift summary
       drift_summary = PgSqlTriggers::Drift::Reporter.summary

data/app/controllers/pg_sql_triggers/migrations_controller.rb

@@ -4,6 +4,8 @@ module PgSqlTriggers
   # Controller for managing trigger migrations via web UI
   # Provides actions to run migrations up, down, and redo
   class MigrationsController < ApplicationController
+    before_action :check_operator_permission
+
     def up
       # Check kill switch before running migration
       check_kill_switch(operation: :ui_migration_up, confirmation: params[:confirmation_text])
@@ -73,18 +75,16 @@ module PgSqlTriggers
       target_version = params[:version]&.to_i
       PgSqlTriggers::Migrator.ensure_migrations_table!
 
+      current_version = PgSqlTriggers::Migrator.current_version
+      if current_version.zero?
+        flash[:warning] = "No migrations to redo."
+        redirect_to root_path
+        return
+      end
+
       if target_version
-        PgSqlTriggers::Migrator.run_down(target_version)
-        PgSqlTriggers::Migrator.run_up(target_version)
-        flash[:success] = "Migration #{target_version} redone successfully."
+        redo_target_migration(target_version, current_version)
       else
-        current_version = PgSqlTriggers::Migrator.current_version
-        if current_version.zero?
-          flash[:warning] = "No migrations to redo."
-          redirect_to root_path
-          return
-        end
-
         PgSqlTriggers::Migrator.run_down
         PgSqlTriggers::Migrator.run_up
         flash[:success] = "Last migration redone successfully."
@@ -98,5 +98,57 @@ module PgSqlTriggers
       flash[:error] = "Failed to redo migration: #{e.message}"
       redirect_to root_path
     end
+
+    private
+
+    def check_operator_permission
+      return if PgSqlTriggers::Permissions.can?(current_actor, :apply_trigger)
+
+      redirect_to root_path, alert: "Insufficient permissions. Operator role required."
+    end
+
+    def redo_target_migration(target_version, current_version)
+      # For redo, we need to rollback the specific migration and re-apply it
+      # If target_version is the current version, rollback the last migration
+      # Otherwise, rollback to one version before target, then run up to target
+      if current_version == target_version
+        # Rollback the last migration (which is the target)
+        PgSqlTriggers::Migrator.run_down
+      elsif current_version > target_version
+        rollback_to_before_target(target_version)
+      else
+        # Target version is not applied yet, just run it up
+        PgSqlTriggers::Migrator.run_up(target_version)
+        flash[:success] = "Migration #{target_version} redone successfully."
+        redirect_to root_path
+        return
+      end
+
+      # Now run up to the target version
+      PgSqlTriggers::Migrator.run_up(target_version)
+      flash.now[:success] = "Migration #{target_version} redone successfully."
+    end
+
+    def rollback_to_before_target(target_version)
+      # Rollback to one version before target (this will rollback target_version too)
+      # Find the migration just before target_version
+      all_migrations = PgSqlTriggers::Migrator.migrations.sort_by(&:version)
+      prev_migration = all_migrations.find { |m| m.version < target_version }
+      if prev_migration
+        # Rollback to the previous migration (this rolls back target_version)
+        PgSqlTriggers::Migrator.run_down(prev_migration.version)
+      else
+        # No previous migration, target_version is the first migration
+        # Rollback all migrations until we're below target_version
+        rollback_until_below_target(target_version)
+      end
+    end
+
+    def rollback_until_below_target(target_version)
+      while PgSqlTriggers::Migrator.current_version >= target_version
+        PgSqlTriggers::Migrator.run_down
+        break if PgSqlTriggers::Migrator.current_version.zero?
+      end
+    end
   end
 end