pg_sql_triggers 1.3.0 → 1.5.0

data/docs/api-reference.md

@@ -11,6 +11,8 @@ Complete reference for using PgSqlTriggers programmatically from the Rails conso
 - [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
 
 The Registry API provides methods for inspecting and managing triggers.
@@ -485,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.
@@ -616,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
 ```
 
@@ -651,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)`
 
@@ -664,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**:
@@ -712,7 +607,110 @@ 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
+#### `on_update_of(*columns)`
+
+Column-level trigger. Sets the event to `update` and records the column list; the generated
+SQL emits `UPDATE OF "col1", "col2"` so the trigger only fires when those columns change.
+
+```ruby
+on_update_of :email, :status
+```
+
+**Parameters**:
+- `columns` (Symbols or Strings): One or more simple SQL identifiers
+
+Notes: calling `on(...)` clears the column list. The column list is part of the checksum.
+Names must match `[a-zA-Z_][a-zA-Z0-9_]*` — invalid identifiers are rejected by the validator.
+
+#### `constraint_trigger!` / `self.deferrable =` / `self.initially =`
+
+Declares a `CREATE CONSTRAINT TRIGGER` (instead of a regular `CREATE TRIGGER`) and optionally
+makes it deferrable.
+
+```ruby
+constraint_trigger!
+self.deferrable = :deferrable
+self.initially  = :deferred
+```
+
+**Valid values**:
+- `deferrable`: `:deferrable`, `:not_deferrable`, or `nil`
+- `initially`: `:deferred`, `:immediate`, or `nil` (only when `deferrable == :deferrable`)
+
+**Rules** enforced by `Registry::Validator`:
+- `deferrable` / `initially` require `constraint_trigger!`.
+- Constraint triggers must use `timing :after` and cannot use `:truncate` events.
+- `initially` requires `deferrable = :deferrable`.
+
+Drift detection reads deferral state from `pg_trigger.tgdeferrable` and `pg_trigger.tginitdeferred`,
+so out-of-band modifications are detected.
+
+#### `depends_on(*names)`
+
+Declares that this trigger must run after the named trigger(s) on the same table. PostgreSQL
+fires same-kind triggers in **alphabetical name order**, so `depends_on` does not change runtime
+ordering — it is a metadata hint that `Registry::Validator` uses to verify declared intent
+matches naming.
+
+```ruby
+depends_on "validate_user_email"
+depends_on "a_trigger", "b_trigger"
+```
+
+**Validation** (`rake trigger:validate_order` or `Registry.validate!`) checks:
+- Referenced triggers exist as DSL entries.
+- Prerequisite is on the same table with the same timing and `FOR EACH` granularity.
+- Events overlap with the dependent.
+- No circular dependencies.
+- The prerequisite's name sorts alphabetically before the dependent's.
+
+Related DSL triggers are surfaced on the trigger detail page via
+`Registry::Validator.related_triggers_for_show`.
+
+## Drift Alerting API
+
+### `PgSqlTriggers::Drift.check_and_notify`
+
+Convenience wrapper for `PgSqlTriggers::Alerting.check_and_notify`. Runs full drift detection,
+invokes `PgSqlTriggers.drift_notifier` when any result is in a drifted / dropped / unknown
+state, and emits an `ActiveSupport::Notifications` event `pg_sql_triggers.drift_check`.
+
+```ruby
+outcome = PgSqlTriggers::Drift.check_and_notify
+outcome[:results]    # All drift detection results
+outcome[:alertable]  # Subset that triggered notification
+outcome[:notified]   # true if the drift_notifier was called successfully
+```
+
+**Notifier signature**:
+```ruby
+PgSqlTriggers.drift_notifier = lambda do |drift_results, all_results:|
+  # drift_results: Array of alertable hashes (drifted / dropped / unknown)
+  # all_results: full result set for context
+end
+```
+
+Errors raised by the notifier are caught, logged to `Rails.logger`, and surfaced via the
+`:notifier_error` key on the `pg_sql_triggers.drift_check` notification payload.
+
+## Registry Validator API
+
+### `PgSqlTriggers::Registry::Validator.validate!`
+
+Loads all DSL triggers from the registry and raises `PgSqlTriggers::ValidationError` when any
+are misconfigured. Validates events, timing, `for_each`, column lists, deferral combinations,
+and `depends_on` references (existence, table/timing/granularity/event overlap, cycles, and
+alphabetical name order).
+
+### `PgSqlTriggers::Registry::Validator.trigger_order_validation_errors`
+
+Returns only the dependency/order error messages (without raising). Used by
+`rake trigger:validate_order`.
+
+### `PgSqlTriggers::Registry::Validator.related_triggers_for_show(record)`
+
+Returns `{ prerequisites: [...], dependents: [...] }` — arrays of `TriggerRegistry` records
+declared via `depends_on`. Used by the trigger detail view.
 
 ## TriggerRegistry Model
 
@@ -728,12 +726,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
@@ -816,7 +815,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
 
@@ -885,6 +884,34 @@ prod_triggers = PgSqlTriggers::TriggerRegistry.for_environment("production")
 
 **Returns**: Array of `TriggerRegistry` records
 
+## Rake Tasks
+
+| Task | Description |
+|------|-------------|
+| `trigger:migrate` | Apply pending trigger migrations (respects kill switch). |
+| `trigger:rollback [STEP=n]` | Rollback trigger migrations. |
+| `trigger:migrate:status` | Show status of all trigger migrations. |
+| `trigger:migrate:up VERSION=…` | Run a specific migration up. |
+| `trigger:migrate:down VERSION=…` | Run a specific migration down. |
+| `trigger:migrate:redo [STEP=n\|VERSION=…]` | Rollback and re-apply. |
+| `trigger:version` | Print the current trigger migration version. |
+| `trigger:abort_if_pending_migrations` | Raise if pending trigger migrations exist. |
+| `trigger:check_drift [FAIL_ON_DRIFT=1]` | Run drift detection; invoke `drift_notifier`; optionally exit non-zero on drift. |
+| `trigger:validate_order` | Validate `depends_on` references, cycles, compatibility, and PostgreSQL name order. |
+| `trigger:dump [FILE=…]` | Write managed triggers to `db/trigger_structure.sql` (or `FILE=…`). |
+| `trigger:load [FILE=…]` | Execute SQL from the snapshot file (respects kill switch). |
+| `db:migrate:with_triggers` | Run `db:migrate` then `trigger:migrate`. |
+| `db:rollback:with_triggers` | Rollback the most recent schema or trigger migration. |
+| `db:migrate:status:with_triggers` | Show both schema and trigger migration status. |
+| `db:version:with_triggers` | Show both schema and trigger current versions. |
+
+`ENV` flags that apply across tasks:
+
+- `CONFIRMATION_TEXT=…` — satisfy the kill switch in protected environments.
+- `SKIP_TRIGGER_MIGRATE_AFTER_SCHEMA_LOAD=1` — skip the `db:schema:load` → `trigger:migrate`
+  hook for a single invocation.
+- `TRIGGER_STRUCTURE_SQL=path` — alternative to `FILE=path` for `trigger:dump` / `trigger:load`.
+
 ## Usage Examples
 
 ### Complete Workflow
@@ -904,10 +931,6 @@ triggers = PgSqlTriggers::Registry.list
 puts "Total triggers: #{triggers.count}"
 
 # 4. Check for drift
-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
@@ -955,16 +978,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
@@ -976,6 +999,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}"

data/docs/audit-trail.md

@@ -385,7 +385,7 @@ PgSqlTriggers::AuditLog
 **Problem**: Operations are not being logged.
 
 **Solution**: 
-- Check that migrations are run (`rails db:migrate`)
+- Check that migrations are run (`rails db:migrate`). The audit log table is created by `20260103114508_create_pg_sql_triggers_audit_log.rb` (see [Gem schema migrations](getting-started.md#gem-schema-migrations)).
 - Verify the audit log table exists
 - Check Rails logs for audit logging errors
 

data/docs/configuration.md

@@ -10,6 +10,9 @@ Complete reference for configuring PgSqlTriggers in your Rails application.
 - [Kill Switch Configuration](#kill-switch-configuration)
 - [Permission System](#permission-system)
 - [Environment Detection](#environment-detection)
+- [Drift alerting](#drift-alerting)
+- [schema.rb and structure.sql integration](#schemarb-and-structuresql-integration)
+- [Migration and Safety Settings](#migration-and-safety-settings)
 - [Advanced Configuration](#advanced-configuration)
 - [Examples](#examples)
 
@@ -50,6 +53,25 @@ config.default_environment = -> {
 config.default_environment = -> { 'production' }
 ```
 
+### `db_schema`
+
+The PostgreSQL schema in which triggers are managed. All system catalog queries use this value. Override when your triggers live in a non-`public` schema.
+
+- **Type**: String
+- **Default**: `"public"`
+
+```ruby
+config.db_schema = "public"  # default
+
+# Use a custom schema
+config.db_schema = "app"
+```
+
+You can also set this at runtime:
+```ruby
+PgSqlTriggers.db_schema = "app"
+```
+
 ### `mount_path`
 
 Customize where the web UI is mounted (configured in routes, not initializer).
@@ -192,6 +214,8 @@ Custom authorization logic for the web UI and API.
 - **Returns**: Boolean
 - **Default**: `->(_actor, _action, _environment) { true }`
 
+> **Important**: If `permission_checker` is `nil` (not configured) and the app boots in **production**, the engine emits a `Rails.logger.warn` at startup. Configure a real checker before deploying to production.
+
 ```ruby
 # Default: allow all (development only!)
 config.permission_checker = ->(_actor, _action, _environment) { true }
@@ -210,9 +234,9 @@ config.permission_checker = ->(actor, action, environment) {
   case action
   when :view_triggers, :view_diffs
     user.present? # Viewer level
-  when :enable_trigger, :disable_trigger, :apply_trigger, :generate_trigger, :test_trigger, :dry_run_sql
+  when :enable_trigger, :disable_trigger, :apply_trigger, :test_trigger
     user.operator? || user.admin? # Operator level
-  when :drop_trigger, :execute_sql, :override_drift
+  when :drop_trigger, :override_drift
     user.admin? # Admin level
   else
     false
@@ -287,7 +311,7 @@ The permission checker should handle three levels:
 #### `:admin`
 - All `:operate` permissions
 - Drop triggers
-- Execute SQL capsules
+- Override drift
 - Modify registry directly
 
 ## Environment Detection
@@ -319,6 +343,175 @@ config.default_environment = -> {
 }
 ```
 
+## Drift alerting
+
+Drift checks can run from the web UI, Ruby API, or Rake. To push notifications when triggers are **drifted**, **dropped**, or **unknown** (external), set a notifier and schedule `trigger:check_drift` (for example via cron or your job runner).
+
+### `drift_notifier`
+
+- **Type**: `Proc`, `lambda`, or any object responding to `call`
+- **Default**: `nil` (no notifications)
+
+The callable receives:
+
+1. **First argument**: an Array of result hashes for problematic triggers only (same shape as `PgSqlTriggers::Drift::Detector.detect_all` elements).
+2. **Keyword argument** `all_results:`: the full result set from drift detection.
+
+```ruby
+PgSqlTriggers.configure do |config|
+  config.drift_notifier = lambda do |drift_results, all_results:|
+    next if drift_results.empty?
+
+    # Example: log, Slack, PagerDuty, email, etc.
+    Rails.logger.warn("[PgSqlTriggers] Drift: #{drift_results.map { |r| r[:state] }.tally.inspect}")
+  end
+end
+```
+
+### Rake task
+
+Run this from your **Rails application root** (tasks are loaded by the engine), or from the **gem repository** when developing the gem (the root `Rakefile` loads `rakelib/` so `trigger:*` tasks are available there too).
+
+```bash
+bundle exec rake trigger:check_drift
+```
+
+- Set `FAIL_ON_DRIFT=1` to exit with status **1** when any problematic trigger exists (useful in CI or monitoring scripts that treat non-zero as failure).
+- If problems exist and no notifier is configured, the task prints a reminder to set `drift_notifier`.
+
+### `ActiveSupport::Notifications`
+
+When Active Support is loaded, each run emits `pg_sql_triggers.drift_check` with payload keys including `:results`, `:alertable`, `:alertable_count`, `:total_count`, and `:notified`. Subscribe in an initializer to forward metrics to your APM or logging pipeline.
+
+### Example: Slack incoming webhook
+
+```ruby
+require "net/http"
+require "json"
+require "uri"
+
+PgSqlTriggers.configure do |config|
+  config.drift_notifier = lambda do |drift_results, all_results:|
+    uri = URI(ENV.fetch("SLACK_DRIFT_WEBHOOK_URL"))
+    text = "PgSqlTriggers drift: #{drift_results.size} issue(s)\n" +
+           drift_results.map { |r|
+             name = r[:registry_entry]&.trigger_name || r[:db_trigger]&.dig("trigger_name")
+             "- #{name}: #{r[:state]}"
+           }.join("\n")
+    Net::HTTP.post(uri, { text: text }.to_json, "Content-Type" => "application/json")
+  end
+end
+```
+
+### Example: PagerDuty Events API v2
+
+```ruby
+require "net/http"
+require "json"
+require "uri"
+
+PgSqlTriggers.configure do |config|
+  config.drift_notifier = lambda do |drift_results, all_results:|
+    uri = URI("https://events.pagerduty.com/v2/enqueue")
+    body = {
+      routing_key: ENV.fetch("PAGERDUTY_INTEGRATION_KEY"),
+      event_action: "trigger",
+      payload: {
+        summary: "PgSqlTriggers: #{drift_results.size} drift issue(s)",
+        severity: "error",
+        source: "pg_sql_triggers",
+        custom_details: { triggers: drift_results.map { |r| r.slice(:state, :details) } }
+      }
+    }
+    Net::HTTP.post(uri, body.to_json, "Content-Type" => "application/json")
+  end
+end
+```
+
+## schema.rb and structure.sql integration
+
+`rails db:schema:dump` cannot represent PostgreSQL triggers in `schema.rb`. PgSqlTriggers ships
+three opt-in hooks that keep triggers aligned with the Rails schema workflow.
+
+### `append_trigger_notes_to_schema_dump`
+
+When `true` (default), the engine prepends an extension onto `ActiveRecord::SchemaDumper` that
+appends a short comment block to `schema.rb` listing managed triggers and pointing at the
+relevant rake tasks. Disable it if you prefer `schema.rb` to be untouched.
+
+- **Type**: Boolean
+- **Default**: `true`
+
+```ruby
+config.append_trigger_notes_to_schema_dump = false
+```
+
+The annotation is suppressed automatically when `config.active_record.schema_format = :sql`.
+
+### `trigger_structure_sql_path`
+
+Path (or callable returning a path) for the SQL snapshot written by `rake trigger:dump` and
+read by `rake trigger:load`. Defaults to `Rails.root.join("db/trigger_structure.sql")`.
+
+- **Type**: `String`, `Pathname`, or callable returning one
+- **Default**: `nil` (uses `db/trigger_structure.sql`)
+
+```ruby
+config.trigger_structure_sql_path = Rails.root.join("db/triggers/snapshot.sql")
+
+# Or a lambda (useful for multi-tenant setups)
+config.trigger_structure_sql_path = -> {
+  Rails.root.join("db/triggers", "#{Apartment::Tenant.current}.sql")
+}
+```
+
+`FILE=path` or `TRIGGER_STRUCTURE_SQL=path` on the rake command line overrides this value per
+invocation.
+
+### `migrate_triggers_after_schema_load`
+
+When `true` (default), `db:schema:load` is enhanced to automatically invoke `trigger:migrate`
+after the schema has been loaded so pending trigger migrations apply to a freshly-loaded
+database.
+
+- **Type**: Boolean
+- **Default**: `true`
+
+```ruby
+config.migrate_triggers_after_schema_load = false
+```
+
+Set the environment variable `SKIP_TRIGGER_MIGRATE_AFTER_SCHEMA_LOAD=1` to skip the hook for a
+single invocation without changing configuration.
+
+## Migration and Safety Settings
+
+### `excluded_tables`
+
+Tables whose triggers are ignored by drift detection and registry listings. Useful when other
+systems (e.g. auditing extensions, logical replication) manage triggers on tables you do not
+want pg_sql_triggers to touch.
+
+- **Type**: Array of strings/symbols
+- **Default**: `[]`
+
+```ruby
+config.excluded_tables = %w[ar_internal_metadata schema_migrations]
+```
+
+### `allow_unsafe_migrations`
+
+When `false` (default), trigger migrations are vetted by `PgSqlTriggers::Migrator::SafetyValidator`
+before they execute. Setting this to `true` bypasses safety checks entirely — intended only for
+local development or one-off recovery operations.
+
+- **Type**: Boolean
+- **Default**: `false`
+
+```ruby
+config.allow_unsafe_migrations = Rails.env.development?
+```
+
 ## Advanced Configuration
 
 ### Complete Example