pg_sql_triggers 1.2.0 → 1.4.0

data/docs/README.md

@@ -9,12 +9,16 @@ Welcome to the PgSqlTriggers documentation. This directory contains comprehensiv
 
 ### Core Guides
 - **[Usage Guide](usage-guide.md)** - DSL syntax, migrations, and drift detection
-- **[Web UI Guide](web-ui.md)** - Using the web dashboard
+- **[UI Guide](ui-guide.md)** - Quick start guide for the web interface
+- **[Web UI Guide](web-ui.md)** - Comprehensive web dashboard documentation
 - **[Kill Switch Guide](kill-switch.md)** - Production safety features
+- **[Permissions Guide](permissions.md)** - Configuring and using permissions
+- **[Audit Trail Guide](audit-trail.md)** - Viewing and exporting audit logs
 
 ### Reference
 - **[Configuration Reference](configuration.md)** - Complete configuration options
 - **[API Reference](api-reference.md)** - Console API and programmatic usage
+- **[Troubleshooting Guide](troubleshooting.md)** - Common issues and solutions
 
 ## Quick Links
 
@@ -30,20 +34,26 @@ See [Usage Guide - Declaring Triggers](usage-guide.md#declaring-triggers)
 See [Usage Guide - Trigger Migrations](usage-guide.md#trigger-migrations)
 
 #### Use the web dashboard
-See [Web UI Documentation](web-ui.md)
+Start with [UI Guide](ui-guide.md) or see [Web UI Documentation](web-ui.md) for comprehensive details
+
+#### Configure permissions
+See [Permissions Guide](permissions.md) or [Configuration - Permission System](configuration.md#permission-system)
+
+#### View audit logs
+See [Audit Trail Guide](audit-trail.md)
 
 #### Protect production
 See [Kill Switch Documentation](kill-switch.md)
 
-#### Configure permissions
-See [Configuration - Permission System](configuration.md#permission-system)
-
 #### Use the console API
 See [API Reference](api-reference.md)
 
 #### Handle drift detection
 See [Usage Guide - Drift Detection](usage-guide.md#drift-detection)
 
+#### Troubleshoot issues
+See [Troubleshooting Guide](troubleshooting.md)
+
 ## Screenshots
 
 Screenshots referenced in the documentation are stored in the [screenshots](screenshots/) directory.

data/docs/api-reference.md

@@ -9,6 +9,9 @@ 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)
+
+> **Removed in 1.4.0**: `SQL::Capsule` and `SQL::Executor` have been removed. See [CHANGELOG](../CHANGELOG.md) for details.
 
 ## Registry API
 
@@ -97,6 +100,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.
@@ -414,124 +487,6 @@ 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.
@@ -545,10 +500,10 @@ PgSqlTriggers::DSL.pg_sql_trigger "users_email_validation" do
   table :users
   on :insert, :update
   function :validate_user_email
-  version 1
-  enabled false
+  self.version = 1
+  self.enabled = true
   timing :before
-  when_env :production
+  for_each_row
 end
 ```
 
@@ -580,7 +535,7 @@ on :insert, :update, :delete
 ```
 
 **Parameters**:
-- `events` (Symbols): One or more of `:insert`, `:update`, `:delete`
+- `events` (Symbols): One or more of `:insert`, `:update`, `:delete`, `:truncate`
 
 #### `function(function_name)`
 
@@ -593,37 +548,48 @@ function :validate_user_email
 **Parameters**:
 - `function_name` (Symbol): Function name
 
-#### `version(number)`
+#### `self.version = number`
 
 Sets the trigger version.
 
 ```ruby
-version 1
-version 2
+self.version = 1  # Increment when trigger logic changes
+self.version = 2
 ```
 
 **Parameters**:
 - `number` (Integer): Version number
 
-#### `enabled(state)`
+#### `self.enabled = state`
 
-Sets the initial enabled state.
+Sets the initial enabled state. Defaults to `true`.
 
 ```ruby
-enabled true
-enabled false
+self.enabled = true   # Trigger is active (default)
+self.enabled = false  # Trigger is inactive
 ```
 
 **Parameters**:
 - `state` (Boolean): Initial state
 
+#### `for_each_row` / `for_each_statement`
+
+Specifies PostgreSQL execution granularity. Defaults to `for_each_row`.
+
+```ruby
+for_each_row       # FOR EACH ROW (default)
+for_each_statement # FOR EACH STATEMENT
+```
+
+Stored in the `for_each` column on the registry table and included in checksum calculation.
+
 #### `when_env(*environments)`
 
-Restricts trigger to specific environments.
+**Deprecated.** Restricts trigger to specific environments. Emits a deprecation warning on every call and will be removed in a future major version. Use application-level configuration to gate trigger behaviour by environment instead.
 
 ```ruby
-when_env :production
-when_env :production, :staging
+when_env :production           # Deprecated — avoid in new code
+when_env :production, :staging # Deprecated — avoid in new code
 ```
 
 **Parameters**:
@@ -641,8 +607,6 @@ timing :after   # Trigger fires after constraint checks
 **Parameters**:
 - `timing_value` (Symbol or String): Either `:before` or `:after`
 
-**Returns**: Current timing value if called without argument
-
 ## TriggerRegistry Model
 
 The `TriggerRegistry` ActiveRecord model represents a trigger in the registry.
@@ -657,12 +621,13 @@ trigger.table_name         # => "users"
 trigger.function_name      # => "validate_user_email"
 trigger.events             # => ["insert", "update"]
 trigger.version            # => 1
-trigger.enabled             # => false
-trigger.timing              # => "before" or "after"
-trigger.environments        # => ["production"]
-trigger.condition           # => "NEW.status = 'active'" or nil
-trigger.created_at          # => 2023-12-15 12:00:00 UTC
-trigger.updated_at          # => 2023-12-15 12:00:00 UTC
+trigger.enabled            # => true
+trigger.timing             # => "before" or "after"
+trigger.for_each           # => "row" or "statement"
+trigger.environments       # => [] (when_env is deprecated)
+trigger.condition          # => "NEW.status = 'active'" or nil
+trigger.created_at         # => 2023-12-15 12:00:00 UTC
+trigger.updated_at         # => 2023-12-15 12:00:00 UTC
 ```
 
 ### Instance Methods
@@ -745,7 +710,7 @@ trigger.re_execute!(
 - `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`
+**Raises**: `ArgumentError` if reason is blank, `PgSqlTriggers::KillSwitchError`, `StandardError`
 
 **Returns**: `true` on success
 
@@ -833,8 +798,12 @@ triggers = PgSqlTriggers::Registry.list
 puts "Total triggers: #{triggers.count}"
 
 # 4. Check for drift
-drift = PgSqlTriggers::Registry.diff
-puts "Drifted triggers: #{drift[:drifted].count}"
+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")
@@ -876,16 +845,16 @@ end
 ### Inspection and Reporting
 
 ```ruby
-# Generate a drift report
-drift = PgSqlTriggers::Registry.diff
-
+# Generate a drift report using dedicated query methods
 puts "=== Drift Report ==="
-puts "In Sync: #{drift[:in_sync].count}"
-puts "Drifted: #{drift[:drifted].count}"
+puts "In Sync: #{PgSqlTriggers::Registry.in_sync.count}"
+puts "Drifted: #{PgSqlTriggers::Registry.drifted.count}"
+puts "Dropped: #{PgSqlTriggers::Registry.dropped.count}"
+puts "Unknown: #{PgSqlTriggers::Registry.unknown_triggers.count}"
+
+# Or get the full categorised hash
+drift = PgSqlTriggers::Registry.diff
 puts "Manual Override: #{drift[:manual_override].count}"
-puts "Disabled: #{drift[:disabled].count}"
-puts "Dropped: #{drift[:dropped].count}"
-puts "Unknown: #{drift[:unknown].count}"
 
 # List all triggers with details
 triggers = PgSqlTriggers::Registry.list
@@ -897,6 +866,7 @@ triggers.each do |trigger|
   puts "  Function: #{trigger.function_name}"
   puts "  Events: #{trigger.events.join(', ')}"
   puts "  Timing: #{trigger.timing}"
+  puts "  For Each: #{trigger.for_each}"
   puts "  Version: #{trigger.version}"
   puts "  Enabled: #{trigger.enabled}"
   puts "  Drift: #{trigger.drift_status}"
@@ -922,6 +892,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