pg_sql_triggers 1.2.0 → 1.3.0

data/docs/api-reference.md

@@ -9,6 +9,7 @@ Complete reference for using PgSqlTriggers programmatically from the Rails conso
 - [Kill Switch API](#kill-switch-api)
 - [DSL API](#dsl-api)
 - [TriggerRegistry Model](#triggerregistry-model)
+- [Audit Log API](#audit-log-api)
 
 ## Registry API
 
@@ -97,6 +98,76 @@ end
 
 **Returns**: Hash with drift categories
 
+### `PgSqlTriggers::Registry.drifted`
+
+Returns all triggers that have drifted from their expected state.
+
+```ruby
+drifted_triggers = PgSqlTriggers::Registry.drifted
+# => [
+#   { state: "drifted", trigger_name: "users_email_validation", ... },
+#   ...
+# ]
+
+drifted_triggers.each do |trigger|
+  puts "Drifted: #{trigger[:trigger_name]}"
+end
+```
+
+**Returns**: Array of drift result hashes for drifted triggers
+
+### `PgSqlTriggers::Registry.in_sync`
+
+Returns all triggers that are in sync with their expected state.
+
+```ruby
+in_sync_triggers = PgSqlTriggers::Registry.in_sync
+# => [
+#   { state: "in_sync", trigger_name: "billing_trigger", ... },
+#   ...
+# ]
+
+puts "In sync triggers: #{in_sync_triggers.count}"
+```
+
+**Returns**: Array of drift result hashes for in-sync triggers
+
+### `PgSqlTriggers::Registry.unknown_triggers`
+
+Returns all unknown (external) triggers not managed by this gem.
+
+```ruby
+unknown = PgSqlTriggers::Registry.unknown_triggers
+# => [
+#   { state: "unknown", trigger_name: "external_trigger", ... },
+#   ...
+# ]
+
+unknown.each do |trigger|
+  puts "External trigger: #{trigger[:trigger_name]}"
+end
+```
+
+**Returns**: Array of drift result hashes for unknown triggers
+
+### `PgSqlTriggers::Registry.dropped`
+
+Returns all triggers that have been dropped from the database.
+
+```ruby
+dropped_triggers = PgSqlTriggers::Registry.dropped
+# => [
+#   { state: "dropped", trigger_name: "old_trigger", ... },
+#   ...
+# ]
+
+dropped_triggers.each do |trigger|
+  puts "Dropped: #{trigger[:trigger_name]}"
+end
+```
+
+**Returns**: Array of drift result hashes for dropped triggers
+
 ### `PgSqlTriggers::Registry.validate!`
 
 Validates all triggers and raises an error if any are invalid.
@@ -836,6 +907,14 @@ puts "Total triggers: #{triggers.count}"
 drift = PgSqlTriggers::Registry.diff
 puts "Drifted triggers: #{drift[:drifted].count}"
 
+# Alternative: Use dedicated query methods
+drifted = PgSqlTriggers::Registry.drifted
+in_sync = PgSqlTriggers::Registry.in_sync
+unknown = PgSqlTriggers::Registry.unknown_triggers
+dropped = PgSqlTriggers::Registry.dropped
+
+puts "Drifted: #{drifted.count}, In Sync: #{in_sync.count}, Unknown: #{unknown.count}, Dropped: #{dropped.count}"
+
 # 5. Enable specific trigger
 trigger = PgSqlTriggers::TriggerRegistry.find_by(trigger_name: "users_email_validation")
 trigger.enable!(confirmation: "EXECUTE TRIGGER_ENABLE") if trigger
@@ -922,6 +1001,118 @@ rescue StandardError => e
 end
 ```
 
+## Audit Log API
+
+The Audit Log API provides methods for querying and managing audit log entries.
+
+### `PgSqlTriggers::AuditLog`
+
+The `AuditLog` model provides methods for querying audit log entries.
+
+#### Class Methods
+
+##### `AuditLog.for_trigger_name(trigger_name)`
+
+Get audit log entries for a specific trigger.
+
+**Parameters:**
+- `trigger_name` (String): The trigger name to query
+
+**Returns:** `ActiveRecord::Relation` - Audit log entries for the trigger, ordered by most recent first
+
+**Example:**
+```ruby
+# Get all audit log entries for a specific trigger
+entries = PgSqlTriggers::AuditLog.for_trigger_name("users_email_validation")
+entries.each do |entry|
+  puts "#{entry.operation}: #{entry.status} at #{entry.created_at}"
+end
+```
+
+##### `AuditLog.log_success(...)`
+
+Log a successful operation to the audit log.
+
+**Parameters:**
+- `operation:` (Symbol, String): The operation being performed (e.g., `:trigger_enable`)
+- `trigger_name:` (String, nil): The trigger name (if applicable)
+- `actor:` (Hash): Information about who performed the action (e.g., `{ type: "UI", id: "123" }`)
+- `environment:` (String, nil): The environment
+- `reason:` (String, nil): Reason for the operation
+- `confirmation_text:` (String, nil): Confirmation text used
+- `before_state:` (Hash, nil): State before operation
+- `after_state:` (Hash, nil): State after operation
+- `diff:` (String, nil): Diff information
+
+**Returns:** `AuditLog` instance or `nil` if logging fails
+
+**Example:**
+```ruby
+PgSqlTriggers::AuditLog.log_success(
+  operation: :trigger_enable,
+  trigger_name: "users_email_validation",
+  actor: { type: "Console", id: "admin@example.com" },
+  environment: "production",
+  before_state: { enabled: false },
+  after_state: { enabled: true }
+)
+```
+
+##### `AuditLog.log_failure(...)`
+
+Log a failed operation to the audit log.
+
+**Parameters:**
+- `operation:` (Symbol, String): The operation being performed
+- `trigger_name:` (String, nil): The trigger name (if applicable)
+- `actor:` (Hash): Information about who performed the action
+- `environment:` (String, nil): The environment
+- `error_message:` (String): Error message (required)
+- `reason:` (String, nil): Reason for the operation (if provided before failure)
+- `confirmation_text:` (String, nil): Confirmation text used
+- `before_state:` (Hash, nil): State before operation
+
+**Returns:** `AuditLog` instance or `nil` if logging fails
+
+**Example:**
+```ruby
+PgSqlTriggers::AuditLog.log_failure(
+  operation: :trigger_enable,
+  trigger_name: "users_email_validation",
+  actor: { type: "UI", id: "user_123" },
+  environment: "production",
+  error_message: "Trigger does not exist in database",
+  before_state: { enabled: false }
+)
+```
+
+#### Scopes
+
+The `AuditLog` model provides several useful scopes:
+
+- `AuditLog.for_trigger(trigger_name)` - Filter by trigger name
+- `AuditLog.for_operation(operation)` - Filter by operation type
+- `AuditLog.for_environment(env)` - Filter by environment
+- `AuditLog.successful` - Only successful operations
+- `AuditLog.failed` - Only failed operations
+- `AuditLog.recent` - Order by most recent first
+
+**Example:**
+```ruby
+# Get all failed operations in production
+failed_ops = PgSqlTriggers::AuditLog
+  .failed
+  .for_environment("production")
+  .recent
+  .limit(10)
+
+# Get all enable operations for a trigger
+enable_ops = PgSqlTriggers::AuditLog
+  .for_trigger("users_email_validation")
+  .for_operation("trigger_enable")
+  .recent
+```
+
 ## Next Steps
 
 - [Usage Guide](usage-guide.md) - Learn the DSL and migration system

data/docs/audit-trail.md

@@ -0,0 +1,413 @@
+# Audit Trail Guide
+
+PgSqlTriggers provides comprehensive audit logging for all trigger operations. This guide explains how to view, filter, and export audit logs.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Accessing Audit Logs](#accessing-audit-logs)
+- [Viewing Audit Logs](#viewing-audit-logs)
+- [Filtering Logs](#filtering-logs)
+- [Exporting Logs](#exporting-logs)
+- [Console API](#console-api)
+- [Logged Operations](#logged-operations)
+- [Audit Log Structure](#audit-log-structure)
+
+## Overview
+
+The audit trail captures:
+
+- **Who**: Actor information (user type and ID)
+- **What**: Operation performed (enable, disable, drop, re-execute, etc.)
+- **When**: Timestamp of the operation
+- **Where**: Environment where operation occurred
+- **Result**: Success or failure status
+- **Context**: Before/after state, reasons, confirmation text, error messages
+
+All operations are automatically logged, providing a complete audit trail for compliance and debugging.
+
+## Accessing Audit Logs
+
+### Via Web UI
+
+Navigate to the Audit Log page:
+
+1. Go to the PgSqlTriggers dashboard
+2. Click "Audit Log" in the navigation menu
+3. URL: `http://localhost:3000/pg_sql_triggers/audit_logs`
+
+### Via Console API
+
+```ruby
+# Get all audit logs
+PgSqlTriggers::AuditLog.all
+
+# Get logs for a specific trigger
+PgSqlTriggers::AuditLog.for_trigger_name("users_email_validation")
+
+# Get recent logs
+PgSqlTriggers::AuditLog.recent.limit(100)
+```
+
+## Viewing Audit Logs
+
+### Audit Log Table
+
+The audit log table displays:
+
+- **Timestamp**: When the operation occurred
+- **Operation**: Type of operation (enable, disable, drop, etc.)
+- **Trigger Name**: Affected trigger (if applicable)
+- **Actor**: Who performed the operation (type and ID)
+- **Environment**: Environment where operation occurred
+- **Status**: Success or failure
+- **Reason**: Reason provided (for drop/re-execute operations)
+
+### Viewing Details
+
+Click on any audit log entry to view detailed information:
+
+- **Before State**: State before the operation (enabled/disabled, function body, etc.)
+- **After State**: State after the operation
+- **Diff**: Changes made (for re-execute operations)
+- **Confirmation Text**: Confirmation text used (if applicable)
+- **Error Message**: Error details (for failed operations)
+
+## Filtering Logs
+
+### Filter Options
+
+Filter audit logs by:
+
+- **Trigger Name**: Filter by specific trigger
+- **Operation**: Filter by operation type (enable, disable, drop, etc.)
+- **Status**: Filter by success or failure
+- **Environment**: Filter by environment (production, staging, etc.)
+- **Sort Order**: Newest first or oldest first
+
+### Using Filters in UI
+
+1. Navigate to Audit Log page
+2. Use filter dropdowns at the top
+3. Click "Apply Filters"
+4. Use "Clear" to reset filters
+
+### Filtering via Console API
+
+```ruby
+# Filter by trigger
+PgSqlTriggers::AuditLog.for_trigger("users_email_validation")
+
+# Filter by operation
+PgSqlTriggers::AuditLog.for_operation("trigger_enable")
+
+# Filter by environment
+PgSqlTriggers::AuditLog.for_environment("production")
+
+# Filter by status
+PgSqlTriggers::AuditLog.successful
+PgSqlTriggers::AuditLog.failed
+
+# Combine filters
+PgSqlTriggers::AuditLog
+  .for_trigger("users_email_validation")
+  .for_operation("trigger_enable")
+  .successful
+  .recent
+  .limit(50)
+```
+
+### Advanced Filtering
+
+```ruby
+# Get failed operations in production
+PgSqlTriggers::AuditLog
+  .for_environment("production")
+  .failed
+  .recent
+
+# Get all drop operations
+PgSqlTriggers::AuditLog
+  .for_operation("trigger_drop")
+  .includes(:trigger_name)
+
+# Get operations by specific actor
+PgSqlTriggers::AuditLog
+  .where("actor->>'type' = ? AND actor->>'id' = ?", "User", "123")
+```
+
+## Exporting Logs
+
+### CSV Export via UI
+
+1. Apply any desired filters
+2. Click "Export CSV" button
+3. CSV file downloads with all visible entries
+4. Filters are preserved in the export
+
+### CSV Export Format
+
+The CSV includes all columns:
+
+- Timestamp
+- Operation
+- Trigger Name
+- Actor Type
+- Actor ID
+- Environment
+- Status
+- Reason
+- Error Message (for failures)
+- Created At
+
+### Programmatic Export
+
+```ruby
+# Export to CSV
+require 'csv'
+
+logs = PgSqlTriggers::AuditLog.recent.limit(1000)
+
+CSV.open("audit_logs.csv", "w") do |csv|
+  csv << ["Timestamp", "Operation", "Trigger", "Actor", "Environment", "Status", "Reason"]
+  
+  logs.each do |log|
+    csv << [
+      log.created_at,
+      log.operation,
+      log.trigger_name,
+      "#{log.actor['type']}:#{log.actor['id']}",
+      log.environment,
+      log.status,
+      log.reason
+    ]
+  end
+end
+```
+
+## Console API
+
+### Querying Audit Logs
+
+```ruby
+# Get logs for a trigger
+PgSqlTriggers::AuditLog.for_trigger_name("users_email_validation")
+
+# Returns: ActiveRecord::Relation ordered by most recent first
+```
+
+### Logging Operations
+
+Operations are automatically logged, but you can also log manually:
+
+```ruby
+# Log a successful operation
+PgSqlTriggers::AuditLog.log_success(
+  operation: :trigger_enable,
+  trigger_name: "users_email_validation",
+  actor: { type: "Console", id: "admin@example.com" },
+  environment: "production",
+  before_state: { enabled: false },
+  after_state: { enabled: true }
+)
+
+# Log a failed operation
+PgSqlTriggers::AuditLog.log_failure(
+  operation: :trigger_drop,
+  trigger_name: "old_trigger",
+  actor: { type: "UI", id: "user_123" },
+  environment: "production",
+  error_message: "Trigger not found",
+  reason: "Cleanup"
+)
+```
+
+## Logged Operations
+
+The following operations are automatically logged:
+
+### Trigger Operations
+
+- **`trigger_enable`**: Trigger enabled
+- **`trigger_disable`**: Trigger disabled
+- **`trigger_drop`**: Trigger dropped from database
+- **`trigger_re_execute`**: Trigger re-executed (drop and recreate)
+
+### Migration Operations
+
+- **`migration_up`**: Migration applied (up)
+- **`migration_down`**: Migration rolled back (down)
+
+### SQL Capsule Operations
+
+- **`sql_capsule_execute`**: SQL capsule executed
+- **`sql_capsule_dry_run`**: SQL capsule dry-run performed
+
+### Generator Operations
+
+- **`trigger_generate`**: Trigger generated via UI
+
+## Audit Log Structure
+
+### Database Schema
+
+The audit log table (`pg_sql_triggers_audit_log`) contains:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | integer | Primary key |
+| `trigger_name` | string | Trigger name (nullable) |
+| `operation` | string | Operation type |
+| `actor` | jsonb | Actor information (type, id) |
+| `environment` | string | Environment name |
+| `status` | string | "success" or "failure" |
+| `reason` | text | Reason for operation (nullable) |
+| `confirmation_text` | text | Confirmation text used (nullable) |
+| `before_state` | jsonb | State before operation (nullable) |
+| `after_state` | jsonb | State after operation (nullable) |
+| `diff` | text | Diff information (nullable) |
+| `error_message` | text | Error message (for failures) |
+| `created_at` | timestamp | When operation occurred |
+| `updated_at` | timestamp | Last update time |
+
+### Actor Format
+
+Actor information is stored as JSON:
+
+```json
+{
+  "type": "User",
+  "id": "123"
+}
+```
+
+Or for console operations:
+
+```json
+{
+  "type": "Console",
+  "id": "admin@example.com"
+}
+```
+
+### State Format
+
+Before and after states are stored as JSON:
+
+```json
+{
+  "enabled": true,
+  "function_body": "CREATE FUNCTION...",
+  "version": 1,
+  "drift_state": "in_sync"
+}
+```
+
+## Use Cases
+
+### Compliance Auditing
+
+Track who performed what operations for compliance:
+
+```ruby
+# Get all admin operations in production
+PgSqlTriggers::AuditLog
+  .for_environment("production")
+  .where("actor->>'type' = ?", "Admin")
+  .recent
+```
+
+### Debugging Failed Operations
+
+Find and analyze failed operations:
+
+```ruby
+# Get recent failures
+failures = PgSqlTriggers::AuditLog.failed.recent.limit(50)
+
+failures.each do |log|
+  puts "#{log.created_at}: #{log.operation} on #{log.trigger_name}"
+  puts "Error: #{log.error_message}"
+  puts "Actor: #{log.actor}"
+  puts "---"
+end
+```
+
+### Trigger History
+
+View complete history of a trigger:
+
+```ruby
+history = PgSqlTriggers::AuditLog.for_trigger_name("users_email_validation")
+
+history.each do |log|
+  puts "#{log.created_at}: #{log.operation} - #{log.status}"
+  if log.reason
+    puts "  Reason: #{log.reason}"
+  end
+end
+```
+
+### Operation Analysis
+
+Analyze operation patterns:
+
+```ruby
+# Count operations by type
+PgSqlTriggers::AuditLog
+  .group(:operation)
+  .count
+
+# Count failures by operation
+PgSqlTriggers::AuditLog
+  .failed
+  .group(:operation)
+  .count
+
+# Operations by environment
+PgSqlTriggers::AuditLog
+  .group(:environment)
+  .count
+```
+
+## Best Practices
+
+1. **Regular Reviews**: Review audit logs regularly for anomalies
+2. **Retention Policy**: Implement a retention policy for old logs
+3. **Monitoring**: Set up alerts for failed operations
+4. **Backup**: Include audit logs in your backup strategy
+5. **Analysis**: Use audit logs to understand usage patterns
+
+## Troubleshooting
+
+### Audit logs not appearing
+
+**Problem**: Operations are not being logged.
+
+**Solution**: 
+- Check that migrations are run (`rails db:migrate`)
+- Verify the audit log table exists
+- Check Rails logs for audit logging errors
+
+### Performance issues with large logs
+
+**Problem**: Audit log queries are slow.
+
+**Solution**:
+- Add indexes on frequently queried columns
+- Implement pagination
+- Archive old logs regularly
+- Use filtering to reduce result set size
+
+### Missing actor information
+
+**Problem**: Actor shows as "unknown".
+
+**Solution**: Ensure `current_actor` method is properly implemented in your controllers.
+
+## Related Documentation
+
+- [Web UI Guide](web-ui.md#audit-log) - Using the audit log UI
+- [API Reference](api-reference.md#audit-log-api) - Console API methods
+- [Configuration Reference](configuration.md) - Configuration options
+

data/docs/configuration.md

@@ -208,12 +208,12 @@ config.permission_checker = ->(actor, action, environment) {
   return false unless user
 
   case action
-  when :view
-    user.present?
-  when :operate
-    user.operator? || user.admin?
-  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