pg_sql_triggers 1.3.0 → 1.5.0

data/docs/getting-started.md

@@ -34,6 +34,20 @@ This will:
 2. Create migrations for the registry table
 3. Mount the engine at `/pg_sql_triggers`
 
+## Gem schema migrations
+
+The gem’s Rails schema migrations live under `db/migrate/` in this repository. Versions use the standard **`YYYYMMDDHHMMSS`** prefix (14 digits: date and clock time). Rails runs them in version order.
+
+Run order (oldest first):
+
+1. `20251222104327_create_pg_sql_triggers_tables.rb` — creates `pg_sql_triggers_registry`
+2. `20251229071916_add_timing_to_pg_sql_triggers_registry.rb` — adds `timing` on the registry
+3. `20260103114508_create_pg_sql_triggers_audit_log.rb` — creates `pg_sql_triggers_audit_log`
+4. `20260228162233_add_for_each_to_pg_sql_triggers_registry.rb` — adds `for_each` on the registry
+5. `20260412185841_add_constraint_deferral_to_pg_sql_triggers_registry.rb` — adds `constraint_trigger`, `deferrable`, `initially` on the registry
+
+If you upgrade the gem and rename migration files locally, update the corresponding rows in `schema_migrations` so the version strings match these filenames.
+
 ## Verify Installation
 
 After installation, you should have:
@@ -45,9 +59,19 @@ After installation, you should have:
 
 ## Quick Start Example
 
-### 1. Create Your First Trigger Definition
+### 1. Scaffold a Trigger (DSL + Migration)
+
+Use the CLI generator to create both files at once:
+
+```bash
+rails generate pg_sql_triggers:trigger users_email_validation users insert update --timing before --function validate_user_email
+```
+
+This creates:
+- `app/triggers/users_email_validation.rb` — DSL stub
+- `db/triggers/TIMESTAMP_users_email_validation.rb` — migration with function + trigger SQL
 
-Create a trigger definition file:
+Edit the DSL stub to match your requirements:
 
 ```ruby
 # app/triggers/users_email_validation.rb
@@ -56,21 +80,12 @@ PgSqlTriggers::DSL.pg_sql_trigger "users_email_validation" do
   on :insert, :update
   function :validate_user_email
 
-  version 1
-  enabled false
-
-  when_env :production
+  self.version = 1
+  self.enabled = true
+  timing :before
 end
 ```
 
-### 2. Generate a Migration
-
-Create a trigger migration to implement the function:
-
-```bash
-rails generate trigger:migration add_email_validation
-```
-
 Edit the generated migration in `db/triggers/`:
 
 ```ruby
@@ -104,7 +119,7 @@ class AddEmailValidation < PgSqlTriggers::Migration
 end
 ```
 
-### 3. Run the Migration
+### 2. Run the Migration
 
 Apply the trigger migration:
 
@@ -112,7 +127,7 @@ Apply the trigger migration:
 rake trigger:migrate
 ```
 
-### 4. Access the Web UI
+### 3. Access the Web UI
 
 Open your browser and navigate to:
 

data/docs/permissions.md

@@ -18,7 +18,7 @@ The permission system provides three levels of access:
 
 - **Viewer**: Read-only access to view triggers and their status
 - **Operator**: Can enable/disable triggers, apply migrations, generate triggers
-- **Admin**: Full access including drop, re-execute, and SQL capsule execution
+- **Admin**: Full access including drop, re-execute, and the reserved `execute_sql` permission action for host-defined privileged SQL
 
 By default, all permissions are allowed (permissive mode). **You must configure permissions in production** to enforce access controls.
 
@@ -49,7 +49,7 @@ Admins have full access:
 - All Operator permissions
 - Drop triggers
 - Re-execute triggers
-- Execute SQL capsules
+- `execute_sql` (privileged SQL; for custom integrations — not used by built-in UI)
 - Override drift detection
 
 ## Actions and Required Roles
@@ -67,7 +67,7 @@ The following actions are mapped to permission levels:
 | `generate_trigger` | Operator | Generate triggers via UI |
 | `test_trigger` | Operator | Test trigger functions |
 | `drop_trigger` | Admin | Drop a trigger from database |
-| `execute_sql` | Admin | Execute SQL capsules |
+| `execute_sql` | Admin | Privileged SQL (`permission_checker` / custom tooling; not used by built-in UI) |
 | `override_drift` | Admin | Override drift detection warnings |
 
 ## Configuration
@@ -272,12 +272,9 @@ PgSqlTriggers::Registry.drop(
   confirmation: "EXECUTE TRIGGER_DROP"
 )
 
-# Execute SQL capsule (requires Admin)
-PgSqlTriggers::SQL::Executor.execute(
-  capsule,
-  actor: current_user,
-  confirmation: "EXECUTE SQL"
-)
+# Custom tooling: gate raw SQL with the Admin-level :execute_sql action (requires Admin)
+PgSqlTriggers::Permissions.check!(current_user, :execute_sql)
+# ... your application's SQL execution ...
 ```
 
 ### Permission Errors in Console

data/docs/usage-guide.md

@@ -15,7 +15,7 @@ PgSqlTriggers provides a Ruby DSL for defining triggers. Trigger definitions are
 
 ### Basic Trigger Definition
 
-Create trigger definition files in `app/triggers/`:
+Create trigger definition files in `app/triggers/` (or scaffold them with the CLI generator — see below):
 
 ```ruby
 # app/triggers/users_email_validation.rb
@@ -24,11 +24,9 @@ PgSqlTriggers::DSL.pg_sql_trigger "users_email_validation" do
   on :insert, :update
   function :validate_user_email
 
-  version 1
-  enabled false
+  self.version = 1
+  self.enabled = true
   timing :before
-
-  when_env :production
 end
 ```
 
@@ -61,25 +59,30 @@ function :validate_user_email
 Version number for tracking changes:
 
 ```ruby
-version 1  # Increment when trigger logic changes
+self.version = 1  # Increment when trigger logic changes
 ```
 
 #### `enabled`
-Initial state of the trigger:
+Initial state of the trigger (defaults to `true`):
 
 ```ruby
-enabled true   # Trigger is active
-enabled false  # Trigger is inactive
+self.enabled = true   # Trigger is active (default)
+self.enabled = false  # Trigger is inactive
 ```
 
-#### `when_env`
-Environment-specific activation:
+#### `for_each_row` / `for_each_statement`
+PostgreSQL execution granularity (defaults to row-level):
 
 ```ruby
-when_env :production           # Only in production
-when_env :staging, :production # Multiple environments
+for_each_row       # FOR EACH ROW (default)
+for_each_statement # FOR EACH STATEMENT
 ```
 
+#### `when_env`
+**Deprecated.** Environment-specific trigger declarations cause schema drift between environments.
+Use application-level configuration to gate trigger behaviour by environment instead.
+Calling `when_env` emits a deprecation warning and will be removed in a future major version.
+
 #### `timing`
 Specifies when the trigger fires relative to the event (BEFORE or AFTER):
 
@@ -88,85 +91,127 @@ timing :before  # Trigger fires before constraint checks (default)
 timing :after   # Trigger fires after constraint checks
 ```
 
-### Complete Example
+#### `on_update_of`
+Declares a **column-level** trigger that fires only when specific columns change
+(PostgreSQL `UPDATE OF col1, col2`). This is a common performance optimisation for audit
+triggers: they run only when the columns you care about are modified.
 
 ```ruby
-# app/triggers/orders_billing_trigger.rb
-PgSqlTriggers::DSL.pg_sql_trigger "orders_billing_trigger" do
+on_update_of :email, :status   # Sets event to UPDATE and records columns
+```
+
+Notes:
+- `on_update_of` sets the event to `update` and stores the column list; calling `on(...)` again
+  clears the column list.
+- Column names must be simple SQL identifiers (`[a-zA-Z_][a-zA-Z0-9_]*`). The gem quotes them
+  in generated SQL, so pass them unquoted.
+- The column list is included in the checksum, so changing the list is detected as drift.
+
+#### `constraint_trigger!` / `deferrable` / `initially`
+Declares a **constraint trigger** (`CREATE CONSTRAINT TRIGGER`) with optional deferral. Constraint
+triggers must be `AFTER` triggers, cannot use `TRUNCATE`, and are the only triggers that can be
+deferred.
+
+```ruby
+PgSqlTriggers::DSL.pg_sql_trigger "orders_integrity_check" do
   table :orders
   on :insert, :update
-  function :calculate_order_total
+  function :check_orders_referential_integrity
+
+  constraint_trigger!         # Emits CREATE CONSTRAINT TRIGGER, forces timing :after
+  self.deferrable = :deferrable
+  self.initially  = :deferred # Evaluate at transaction commit
+end
+```
+
+Valid combinations:
+
+| `deferrable`        | `initially`                | SQL clause                          |
+|---------------------|----------------------------|-------------------------------------|
+| `:deferrable`       | `:deferred`                | `DEFERRABLE INITIALLY DEFERRED`     |
+| `:deferrable`       | `:immediate` (or `nil`)    | `DEFERRABLE INITIALLY IMMEDIATE`    |
+| `:not_deferrable`   | (must be `nil`)            | `NOT DEFERRABLE`                    |
+| `nil`               | `nil`                      | (no deferral clause)                |
 
-  version 2
-  enabled true
+`Registry::Validator` rejects `deferrable`/`initially` unless `constraint_trigger!` is set,
+and rejects constraint triggers that use `:before` timing or `TRUNCATE` events. Drift detection
+reads deferral state from `pg_trigger.tgdeferrable` / `tginitdeferred` so changes made outside
+the gem are surfaced as drift.
+
+#### `depends_on`
+Declares an **ordering hint** relative to another trigger on the same table. PostgreSQL fires
+same-kind triggers in alphabetical order by name; `depends_on` captures the intended order so the
+registry validator can verify that naming matches dependency declarations.
+
+```ruby
+PgSqlTriggers::DSL.pg_sql_trigger "log_user_change" do
+  table :users
+  on :insert, :update
+  function :log_user_change
   timing :after
 
-  when_env :production, :staging
+  depends_on "validate_user_email"   # Must exist on same table, same timing/FOR EACH, overlapping events
 end
 ```
 
-## Trigger Generator
+Run `rake trigger:validate_order` (or `PgSqlTriggers::Registry.validate!`) to enforce:
 
-PgSqlTriggers provides a web-based generator and Rails generators for creating trigger definitions and migrations quickly.
+- Referenced prerequisite triggers exist and are on the same table.
+- Prerequisites share timing (`before`/`after`), `FOR EACH` granularity, and have at least one
+  overlapping event with the dependent.
+- There are no circular dependencies.
+- Names sort alphabetically in the required order (the prerequisite's name must sort before
+  the dependent's).
 
-### Web UI Generator
+The trigger detail page in the web UI displays prerequisites and dependents for DSL triggers.
 
-The web UI generator provides a user-friendly interface for creating triggers:
+### Complete Example
 
-1. Navigate to `/pg_sql_triggers/generator/new` in your browser
-2. Fill in the trigger details:
-   - **Trigger Name**: Lowercase letters, numbers, and underscores only
-   - **Table Name**: The PostgreSQL table to attach the trigger to
-   - **Function Name**: The PostgreSQL function name (must match the function body)
-   - **Timing**: When the trigger fires - BEFORE (before constraint checks) or AFTER (after constraint checks)
-   - **Events**: Select one or more events (INSERT, UPDATE, DELETE, TRUNCATE)
-   - **Function Body**: The complete PostgreSQL function definition
-   - **Version**: Starting version number (default: 1)
-   - **Enabled**: Whether the trigger should be enabled initially
-   - **Environments**: Optional environment restrictions
-   - **Condition**: Optional WHEN condition for the trigger
-3. Preview the generated DSL and migration code (includes timing and condition display)
-4. Create the trigger files
+```ruby
+# app/triggers/orders_billing_trigger.rb
+PgSqlTriggers::DSL.pg_sql_trigger "orders_billing_trigger" do
+  table :orders
+  on :insert, :update
+  function :calculate_order_total
+
+  self.version = 2
+  self.enabled = true
+  timing :after
+  for_each_row
+end
+```
 
-The generator creates:
-- A DSL definition file in `app/triggers/`
-- A migration file in `db/triggers/`
-- A registry entry in the database
+## Trigger Generator
 
-### Rails Generators
+PgSqlTriggers provides a CLI generator that scaffolds a DSL definition and migration together from the command line.
 
-You can also use Rails generators to create trigger migrations:
+### CLI Generator
 
 ```bash
-# Generate a trigger migration
-rails generate trigger:migration add_user_validation
+rails generate pg_sql_triggers:trigger TRIGGER_NAME TABLE_NAME [EVENTS...] [--timing before|after] [--function fn_name]
+```
 
-# Or using the full namespace
-rails generate pg_sql_triggers:trigger_migration add_user_validation
+Example:
+
+```bash
+rails generate pg_sql_triggers:trigger users_email_validation users insert update --timing before --function validate_user_email
 ```
 
-This creates a migration file in `db/triggers/` that you can edit to add your trigger logic.
+This creates:
+- `app/triggers/users_email_validation.rb` — DSL stub
+- `db/triggers/TIMESTAMP_users_email_validation.rb` — migration with function + trigger SQL
+
+Files are written directly into the working tree and go through version control and code review like any other source file.
 
-### Generator Features
+### Migration-Only Generator
 
-The generator handles:
-- **Function Name Formatting**: Automatically quotes function names with special characters
-- **Multiple Environments**: Supports multiple environment restrictions
-- **Condition Escaping**: Properly escapes quotes in WHEN conditions
-- **Event Combinations**: Handles single or multiple events (INSERT, UPDATE, DELETE, TRUNCATE)
-- **Migration Numbering**: Automatically generates sequential migration numbers
-- **Error Handling**: Graceful error handling with detailed error messages
+To generate a standalone trigger migration without a DSL stub:
 
-### Generator Edge Cases
+```bash
+rails generate pg_sql_triggers:trigger_migration add_user_validation
+```
 
-The generator properly handles:
-- Function names with special characters (quoted vs unquoted)
-- Multiple environments in a single trigger
-- Complex WHEN conditions with quotes
-- All event type combinations
-- Standalone gem usage (without Rails context)
-- Migration number collisions
-- Blank events and environments (filtered automatically)
+This creates a timestamped file in `db/triggers/` that you can edit to add your trigger logic.
 
 ## Trigger Migrations
 
@@ -177,7 +222,7 @@ Trigger migrations work similarly to Rails schema migrations but are specificall
 Create a new trigger migration:
 
 ```bash
-rails generate trigger:migration add_validation_trigger
+rails generate pg_sql_triggers:trigger_migration add_validation_trigger
 ```
 
 This creates a timestamped file in `db/triggers/`:

data/docs/web-ui.md

@@ -8,7 +8,6 @@ The PgSqlTriggers web interface provides a visual dashboard for managing trigger
 - [Dashboard Overview](#dashboard-overview)
 - [Managing Triggers](#managing-triggers)
 - [Migration Management](#migration-management)
-- [SQL Capsules](#sql-capsules)
 - [Audit Log](#audit-log)
 - [Permissions and Safety](#permissions-and-safety)
 
@@ -96,7 +95,7 @@ Each table row displays:
 - **Status**: Summary of enabled/disabled triggers
 - **Actions**: 
   - "View Details" - Navigate to the table detail page
-  - "Create Trigger" - Generate a new trigger for this table
+  - "Create Trigger" - Scaffold a new trigger for this table using the CLI generator (see [Trigger Generator](usage-guide.md#trigger-generator))
 
 ### Table Detail Page
 
@@ -303,83 +302,6 @@ After each migration action:
 - **Error**: Red flash message with error details
 - **Warnings**: Yellow flash message if issues occurred
 
-## SQL Capsules
-
-SQL Capsules provide emergency escape hatches for executing SQL directly with comprehensive safety checks and audit logging.
-
-### When to Use SQL Capsules
-
-Use SQL Capsules for:
-- Emergency fixes in production
-- Critical data corrections
-- Testing SQL functions
-- Debugging trigger behavior
-- One-off database operations
-
-### Creating and Executing SQL Capsules
-
-1. Navigate to "SQL Capsules" → "New SQL Capsule"
-2. Fill in the capsule form:
-   - **Name**: Unique identifier (alphanumeric, underscores, hyphens only)
-   - **Environment**: Target environment (e.g., production, staging)
-   - **Purpose**: Detailed explanation of what the SQL does and why (required for audit trail)
-   - **SQL**: The SQL statement(s) to execute
-3. Click "Create and Execute" or "Save for Later"
-4. Review the capsule details on the confirmation page
-5. In protected environments, enter confirmation text when prompted
-6. Click "Execute" to run the SQL
-7. Review the execution results
-
-### Viewing Capsule History
-
-1. Navigate to "SQL Capsules" → "History"
-2. View list of previously executed capsules with:
-   - Name and purpose
-   - Environment and timestamp
-   - SQL checksum
-   - Execution status
-3. Click on a capsule to view details
-4. Re-execute historical capsules if needed
-
-### Safety Features
-
-- **Admin Permission Required**: Only Admin users can create and execute SQL capsules
-- **Production Protection**: Requires typed confirmation in protected environments
-- **Kill Switch Integration**: All executions are protected by kill switch
-- **Comprehensive Logging**: All operations logged with actor, timestamp, and checksum
-- **Transactional Execution**: SQL runs in a transaction and rolls back on error
-- **Registry Storage**: All capsules are stored in the registry with checksums
-- **Purpose Tracking**: Required purpose field ensures all executions are documented
-
-### Example SQL Capsules
-
-#### View All Triggers
-```sql
-SELECT
-  trigger_name,
-  event_object_table,
-  action_timing,
-  event_manipulation
-FROM information_schema.triggers
-WHERE trigger_schema = 'public';
-```
-
-#### Check Function Definitions
-```sql
-SELECT
-  routine_name,
-  routine_type
-FROM information_schema.routines
-WHERE routine_schema = 'public'
-  AND routine_name LIKE '%trigger%';
-```
-
-#### Verify Trigger State
-```sql
-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.
@@ -446,7 +368,6 @@ All of the following operations are logged to the audit log:
 - **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:
@@ -497,7 +418,6 @@ Cannot:
 #### Admin (Full Access)
 - All Operator permissions
 - Drop triggers
-- Execute SQL via capsules
 - Modify registry directly
 
 ### Kill Switch Protection
@@ -529,9 +449,9 @@ PgSqlTriggers.configure do |config|
     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
@@ -550,32 +470,12 @@ end
 ### Main Dashboard
 ![Main Dashboard](screenshots/dashboard.png)
 
-### Trigger Generator
-
-The trigger generator provides a comprehensive form for creating triggers:
-
-1. **Basic Information**: Trigger name, table name, function name, and function body
-2. **Trigger Events**: Select timing (BEFORE/AFTER) and events (INSERT, UPDATE, DELETE, TRUNCATE)
-3. **Configuration**: Version, environments, WHEN condition, and enabled state
-4. **Preview**: Review generated DSL and migration code with timing and condition information
-
-The preview page displays:
-- Generated DSL code with timing
-- Trigger configuration summary (timing, events, table, function, condition)
-- PL/pgSQL function body (editable)
-- SQL validation results
-
-![Trigger Generator](screenshots/generator.png)
-
 ### Migration Management
 ![Migration Management](screenshots/migrations.png)
 
 ### Kill Switch Protection
 ![Kill Switch](screenshots/kill-switch.png)
 
-### SQL Capsules
-![SQL Capsules](screenshots/sql-capsules.png)
-
 ## Dashboard Enhancements (v1.3.0+)
 
 ### Last Applied Column

data/lib/generators/pg_sql_triggers/templates/initializer.rb

@@ -66,4 +66,18 @@ PgSqlTriggers.configure do |config|
   # You can also override per-migration with ALLOW_UNSAFE_MIGRATIONS=true environment variable
   # Default: false (recommended for safety)
   config.allow_unsafe_migrations = false
+
+  # ========== Schema / structure.sql integration ==========
+  # Triggers are not included in db/schema.rb. After db:schema:load, the engine runs
+  # trigger:migrate by default. Set SKIP_TRIGGER_MIGRATE_AFTER_SCHEMA_LOAD=1 to skip.
+  # config.migrate_triggers_after_schema_load = true
+  #
+  # Optional: append comments to schema.rb pointing at db/trigger_structure.sql.
+  # config.append_trigger_notes_to_schema_dump = true
+  #
+  # Snapshot live trigger SQL: bin/rails trigger:dump (apply with trigger:load).
+  # config.trigger_structure_sql_path = Rails.root.join("db/trigger_structure.sql")
+  #
+  # For databases where triggers must appear in the main SQL dump, prefer:
+  #   config.active_record.schema_format = :sql
 end

data/lib/generators/pg_sql_triggers/templates/trigger_dsl.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+PgSqlTriggers::DSL.pg_sql_trigger "<%= trigger_name %>" do
+  table :<%= table_name %>
+  on <%= events_list %>
+  function :<%= function_name %>
+
+  version 1
+  enabled true
+  timing :<%= timing %>
+end

data/lib/generators/pg_sql_triggers/templates/trigger_migration_full.rb.tt

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class <%= trigger_class_name %> < PgSqlTriggers::Migration
+  def up
+    execute <<-SQL
+      CREATE OR REPLACE FUNCTION <%= function_name %>()
+      RETURNS TRIGGER AS $$
+      BEGIN
+        -- TODO: implement trigger logic
+        RETURN NEW;
+      END;
+      $$ LANGUAGE plpgsql;
+    SQL
+
+    execute <<-SQL
+      CREATE TRIGGER <%= trigger_name %>
+      <%= timing.upcase %> <%= events_sql %> ON <%= table_name %>
+      FOR EACH ROW
+      EXECUTE FUNCTION <%= function_name %>();
+    SQL
+  end
+
+  def down
+    execute <<-SQL
+      DROP TRIGGER IF EXISTS <%= trigger_name %> ON <%= table_name %>;
+      DROP FUNCTION IF EXISTS <%= function_name %>();
+    SQL
+  end
+end