pg_sql_triggers 1.2.0 → 1.3.0

data/docs/web-ui.md

@@ -9,6 +9,7 @@ The PgSqlTriggers web interface provides a visual dashboard for managing trigger
 - [Managing Triggers](#managing-triggers)
 - [Migration Management](#migration-management)
 - [SQL Capsules](#sql-capsules)
+- [Audit Log](#audit-log)
 - [Permissions and Safety](#permissions-and-safety)
 
 ## Accessing the Web UI
@@ -34,11 +35,12 @@ The dashboard provides a comprehensive view of your trigger ecosystem.
 
 ### Main Features
 
-1. **Trigger List**: View all triggers with their current status
+1. **Trigger List**: View all triggers with their current status and "Last Applied" timestamps
 2. **Drift Detection**: Visual indicators for drift states
 3. **Migration Status**: See pending and applied migrations
-4. **Quick Actions**: Enable/disable triggers, run migrations
+4. **Quick Actions**: Enable/disable triggers, drop/re-execute triggers (based on permissions), run migrations
 5. **Kill Switch Status**: Production environment indicator
+6. **Audit Trail**: All operations are logged with actor information and viewable via Audit Log UI
 
 ![Dashboard Screenshot](screenshots/dashboard.png)
 
@@ -50,32 +52,116 @@ The dashboard provides a comprehensive view of your trigger ecosystem.
 - **○ Gray**: Disabled
 - **? Purple**: Unknown
 
+## Database Tables & Triggers
+
+The Database Tables & Triggers page provides a comprehensive view of all tables in your database and their associated triggers. This page helps you understand which tables have triggers and which don't, making it easier to manage your trigger ecosystem.
+
+### Accessing the Tables Page
+
+1. Click "View Tables" from the dashboard
+2. Or navigate directly to `/pg_sql_triggers/tables`
+
+### Statistics Overview
+
+The page displays three key statistics:
+- **Tables with Triggers**: Count of tables that have at least one trigger
+- **Tables without Triggers**: Count of tables that have no triggers
+- **Total Tables**: Total count of all tables in the database
+
+### Filtering Tables
+
+Use the filter controls to view different subsets of tables:
+- **All Tables**: Shows all tables regardless of trigger status
+- **With Triggers**: Shows only tables that have at least one trigger (default)
+- **Without Triggers**: Shows only tables that have no triggers
+
+The active filter is highlighted with a colored background. Click any filter button to switch views.
+
+### Pagination
+
+When you have many tables, the list is paginated for better performance:
+- **Default**: 20 tables per page
+- **Configurable**: Choose 10, 20, 50, or 100 tables per page
+- **Navigation**: Use Previous/Next buttons to move between pages
+- **Filter Preservation**: Your selected filter is preserved when navigating pages
+
+### Table Information
+
+Each table row displays:
+- **Table Name**: The name of the database table
+- **Trigger Count**: Number of triggers on the table (badge indicator)
+- **Trigger Names & Functions**: List of all triggers with their function names
+  - Registry triggers (blue border) - Triggers managed by pg_sql_triggers
+  - Database-only triggers (yellow border) - Triggers not in the registry
+- **Status**: Summary of enabled/disabled triggers
+- **Actions**: 
+  - "View Details" - Navigate to the table detail page
+  - "Create Trigger" - Generate a new trigger for this table
+
+### Table Detail Page
+
+Click "View Details" on any table to see:
+- **Table Columns**: Complete list of columns with data types and nullability
+- **Registered Triggers**: All triggers managed by pg_sql_triggers with full details
+- **Database Triggers**: Triggers that exist in the database but aren't in the registry
+
+From the table detail page, you can:
+- Enable/disable individual triggers (Operator+ permission)
+- Drop triggers (Admin permission)
+- Re-execute drifted triggers (Admin permission)
+- Create new triggers for the table
+
 ## Managing Triggers
 
 ### Viewing Trigger Details
 
-Click on any trigger to view:
-- Current status and drift state
+Click on any trigger name (from dashboard or table view) to access the trigger detail page. The detail page includes:
+
+#### Navigation
+- **Breadcrumb Navigation**: Dashboard → Tables → Table Name → Trigger Name
+- **Quick Links**: Back to Dashboard, View Table
+
+#### Summary Panel
+- Current status and drift state with visual indicators
 - Table and function information
-- Version history
-- Enabled/disabled state
-- Environment configuration
+- Version, source (DSL/generated/manual_sql), and environment
+- **Last Applied**: Human-readable timestamp showing when trigger was last applied (e.g., "2 hours ago")
+- **Last Verified**: Timestamp of last drift verification
+- **Created At**: Original creation timestamp
+
+#### SQL Information
+- **Function Body**: Complete PL/pgSQL function code
+- **Trigger Configuration**: Events, timing, conditions
+- **SQL Diff View**: If drift detected, shows expected vs actual SQL side-by-side
+
+#### Actions
+All action buttons available based on permissions:
+- Enable/Disable (Operator+)
+- Re-Execute (Admin, shown only when drift detected)
+- Drop (Admin)
 
 ### Enabling/Disabling Triggers
 
+Triggers can be enabled or disabled from multiple locations:
+- **Dashboard**: Quick action buttons in the trigger table (Operator+ permission)
+- **Table Detail Page**: Action buttons for each trigger (Operator+ permission)
+- **Trigger Detail Page**: Full action panel (Operator+ permission)
+
 #### Enable a Trigger
 
-1. Navigate to the trigger in the dashboard
-2. Click the "Enable" button
+1. Navigate to the trigger (dashboard, table view, or trigger detail page)
+2. Click the "Enable" button (green button)
 3. In production environments, enter the confirmation text when prompted
-4. Confirm the action
+4. Confirm the action in the modal
+5. The trigger will be enabled and the operation logged to the audit trail
 
 #### Disable a Trigger
 
-1. Navigate to the trigger in the dashboard
-2. Click the "Disable" button
+1. Navigate to the trigger (dashboard, table view, or trigger detail page)
+2. Click the "Disable" button (red button)
 3. In production environments, enter the confirmation text when prompted
-4. Confirm the action
+4. Confirm the action in the modal
+5. The trigger will be disabled and the operation logged to the audit trail
 
 ### Viewing Drift Status
 
@@ -99,14 +185,18 @@ Available actions depend on trigger state and your permissions:
 
 ### Drop Trigger
 
-The drop action permanently removes a trigger from the database and registry.
+The drop action permanently removes a trigger from the database and registry. Available from:
+- **Dashboard**: "Drop" button in trigger table (Admin only)
+- **Table Detail Page**: "Drop Trigger" button (Admin only)
+- **Trigger Detail Page**: "Drop Trigger" button (Admin only)
 
-1. Navigate to the trigger detail page
-2. Click the "Drop Trigger" button
+**Steps**:
+1. Navigate to the trigger (any view with drop button)
+2. Click the "Drop Trigger" button (gray button with warning icon)
 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
+4. Review the warning message carefully
 5. Click "Drop Trigger" to confirm
 
 **Important Notes**:
@@ -115,26 +205,34 @@ The drop action permanently removes a trigger from the database and registry.
 - 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
+- Operation is logged to audit trail with actor information and state changes
 
 ### Re-Execute Trigger
 
-The re-execute action fixes drifted triggers by dropping and recreating them from the registry definition.
+The re-execute action fixes drifted triggers by dropping and recreating them from the registry definition. Available from:
+- **Dashboard**: "Re-Execute" button in trigger table (Admin only, shown only when drift detected)
+- **Table Detail Page**: "Re-Execute Trigger" button (Admin only, shown only when drift detected)
+- **Trigger Detail Page**: "Re-Execute Trigger" button (Admin only, shown only when drift detected)
 
-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
+**Steps**:
+1. Navigate to the trigger (any view with re-execute button)
+2. If the trigger is drifted, you'll see a drift warning and the "Re-Execute" button will be visible
+3. Click the "Re-Execute" button (yellow/warning button)
 4. A modal will appear showing:
-   - **Drift Comparison**: Differences between database state and registry definition
+   - **Drift Comparison**: Side-by-side differences between expected (registry) and actual (database) SQL
    - **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
+5. Review the drift differences carefully 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
+4. Operation is logged to audit trail with:
+   - Reason and actor information
+   - Before and after state
+   - SQL diff information
 
 **Important Notes**:
 - Requires **Admin** permission level
@@ -142,6 +240,7 @@ The re-execute action fixes drifted triggers by dropping and recreating them fro
 - 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
+- Button only appears when drift is detected
 
 ## Migration Management
 
@@ -281,6 +380,92 @@ SELECT * FROM pg_sql_triggers_registry
 WHERE trigger_name = 'users_email_validation';
 ```
 
+## Audit Log
+
+The Audit Log provides a comprehensive view of all trigger operations performed through the web UI, console APIs, and CLI. This feature is essential for compliance, debugging, and tracking changes to your trigger ecosystem.
+
+### Accessing the Audit Log
+
+1. Navigate to the "Audit Log" link in the main navigation menu
+2. Or visit `/pg_sql_triggers/audit_logs` directly
+
+### Viewing Audit Log Entries
+
+The audit log displays all operations with the following information:
+
+- **Time**: When the operation occurred (relative time with exact timestamp on hover)
+- **Trigger**: The trigger name (clickable link to trigger detail page if available)
+- **Operation**: The type of operation performed (e.g., `trigger_enable`, `trigger_drop`, `trigger_re_execute`)
+- **Status**: Success or failure indicator
+- **Environment**: The environment where the operation was performed
+- **Actor**: Who performed the operation (e.g., `UI:user_id`, `Console:email`)
+- **Reason**: Explanation for the operation (for drop/re-execute operations)
+- **Error**: Error message if the operation failed
+
+### Filtering Audit Logs
+
+The audit log supports multiple filters to help you find specific entries:
+
+1. **Trigger Name**: Filter by specific trigger name
+2. **Operation**: Filter by operation type (enable, disable, drop, re_execute, etc.)
+3. **Status**: Filter by success or failure
+4. **Environment**: Filter by environment (production, staging, development, etc.)
+5. **Sort Order**: Sort by date (newest first or oldest first)
+
+Click "Apply Filters" to update the view, or "Clear" to remove all filters.
+
+### Exporting Audit Logs
+
+To export audit log entries:
+
+1. Apply any desired filters
+2. Click the "Export CSV" button
+3. The CSV file will include all entries matching your filters (not just the current page)
+4. File is named with timestamp: `audit_logs_YYYYMMDD_HHMMSS.csv`
+
+The CSV export includes:
+- ID, Trigger Name, Operation, Status, Environment
+- Actor Type and ID
+- Reason and Error Message
+- Created At timestamp
+
+### Pagination
+
+The audit log uses pagination to handle large datasets:
+
+- Default: 50 entries per page (adjustable via URL parameter)
+- Maximum: 200 entries per page
+- Navigate using "Previous" and "Next" buttons
+- Page numbers and total count displayed
+
+### What Gets Logged
+
+All of the following operations are logged to the audit log:
+
+- **Enable Trigger**: Success/failure, before/after state
+- **Disable Trigger**: Success/failure, before/after state
+- **Drop Trigger**: Success/failure, reason, state changes
+- **Re-execute Trigger**: Success/failure, reason, drift diff information
+- **SQL Capsule Execution**: Success/failure, capsule details
+- **Migration Operations**: Up, down, and redo operations (infrastructure ready)
+
+Each log entry includes:
+- Complete actor information (who performed the operation)
+- Before and after state (for state-changing operations)
+- Operation metadata (reason, confirmation text, environment)
+- Error details (if the operation failed)
+- Timestamp of the operation
+
+### Use Cases
+
+Common use cases for the audit log:
+
+- **Compliance**: Track all changes for audit requirements
+- **Debugging**: Understand what operations were performed before an issue
+- **Accountability**: See who performed specific operations
+- **Troubleshooting**: Review failed operations and their error messages
+- **Change History**: Track the evolution of your trigger ecosystem over time
+
 ## Permissions and Safety
 
 ### Permission Levels
@@ -322,7 +507,13 @@ In protected environments (production, staging), the Web UI enforces additional
 1. **Status Indicator**: Kill switch badge shows protection status
 2. **Confirmation Required**: Dangerous operations require typed confirmation
 3. **Warning Banners**: Visual alerts for production environment
-4. **Audit Logging**: All protected operations are logged
+4. **Audit Logging**: All protected operations are logged with complete audit trail:
+   - Actor information (who performed the operation)
+   - Before and after state
+   - Operation details (reason, confirmation text)
+   - Success/failure status
+   - Error messages (if failed)
+   - Timestamp of operation
 
 ### Configuring Permissions
 
@@ -332,20 +523,26 @@ Set up custom permission checking in the initializer:
 # config/initializers/pg_sql_triggers.rb
 PgSqlTriggers.configure do |config|
   config.permission_checker = ->(actor, action, environment) {
-    user = User.find(actor[:id])
+    user = User.find_by(id: actor[:id])
+    return false unless user
 
     case action
-    when :view
-      user.present?
-    when :operate
-      user.admin? || user.operator?
-    when :admin
-      user.admin?
+    when :view_triggers, :view_diffs
+      user.present? # Viewer level
+    when :enable_trigger, :disable_trigger, :apply_trigger, :generate_trigger, :test_trigger, :dry_run_sql
+      user.operator? || user.admin? # Operator level
+    when :drop_trigger, :execute_sql, :override_drift
+      user.admin? # Admin level
     else
       false
     end
   }
 end
+```else
+      false
+    end
+  }
+end
 ```
 
 ## Screenshots
@@ -379,13 +576,39 @@ The preview page displays:
 ### SQL Capsules
 ![SQL Capsules](screenshots/sql-capsules.png)
 
+## Dashboard Enhancements (v1.3.0+)
+
+### Last Applied Column
+
+The dashboard now includes a "Last Applied" column showing when each trigger was last applied to the database:
+- **Human-readable format**: Displays relative time (e.g., "2 hours ago", "3 days ago")
+- **Tooltip**: Hover over the timestamp to see exact date and time
+- **Default sorting**: Dashboard sorted by most recently applied triggers first
+- **Never applied**: Shows "Never" if trigger has never been applied
+
+This helps you quickly identify:
+- Which triggers are actively maintained
+- How recently triggers were updated
+- Triggers that may need attention
+
+### Quick Actions in Dashboard
+
+The dashboard trigger table now includes quick action buttons:
+- **Enable/Disable**: Toggle trigger state (Operator+ permission)
+- **Drop**: Remove trigger permanently (Admin only)
+- **Re-Execute**: Fix drifted triggers (Admin only, shown only when drift detected)
+
+All actions respect permission levels and show/hide buttons based on your role.
+
 ## Tips and Best Practices
 
 1. **Check Status Regularly**: Monitor drift detection to catch unexpected changes
 2. **Use Confirmations**: Don't bypass production confirmations without understanding the impact
 3. **Test in Development**: Always test UI actions in development before production
-4. **Review Logs**: Check application logs after important operations
-5. **Document Changes**: Add comments when making manual changes via SQL Capsules
+4. **Review Logs**: Check application logs and audit trail after important operations
+5. **Document Changes**: Add detailed reasons when dropping or re-executing triggers
+6. **Monitor Last Applied**: Use the "Last Applied" column to track trigger maintenance activity
+7. **Breadcrumb Navigation**: Use breadcrumbs on trigger detail page for easy navigation
 
 ## Troubleshooting
 

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