pg_sql_triggers 1.3.0 → 1.4.0

data/docs/getting-started.md

@@ -45,9 +45,19 @@ After installation, you should have:
 
 ## Quick Start Example
 
-### 1. Create Your First Trigger Definition
+### 1. Scaffold a Trigger (DSL + Migration)
 
-Create a trigger definition file:
+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
+
+Edit the DSL stub to match your requirements:
 
 ```ruby
 # app/triggers/users_email_validation.rb
@@ -56,21 +66,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 +105,7 @@ class AddEmailValidation < PgSqlTriggers::Migration
 end
 ```
 
-### 3. Run the Migration
+### 2. Run the Migration
 
 Apply the trigger migration:
 
@@ -112,7 +113,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/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):
 
@@ -97,76 +100,44 @@ PgSqlTriggers::DSL.pg_sql_trigger "orders_billing_trigger" do
   on :insert, :update
   function :calculate_order_total
 
-  version 2
-  enabled true
+  self.version = 2
+  self.enabled = true
   timing :after
-
-  when_env :production, :staging
+  for_each_row
 end
 ```
 
 ## Trigger Generator
 
-PgSqlTriggers provides a web-based generator and Rails generators for creating trigger definitions and migrations quickly.
+PgSqlTriggers provides a CLI generator that scaffolds a DSL definition and migration together from the command line.
 
-### Web UI Generator
+### CLI Generator
 
-The web UI generator provides a user-friendly interface for creating triggers:
-
-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
-
-The generator creates:
-- A DSL definition file in `app/triggers/`
-- A migration file in `db/triggers/`
-- A registry entry in the database
-
-### Rails Generators
+```bash
+rails generate pg_sql_triggers:trigger TRIGGER_NAME TABLE_NAME [EVENTS...] [--timing before|after] [--function fn_name]
+```
 
-You can also use Rails generators to create trigger migrations:
+Example:
 
 ```bash
-# Generate a trigger migration
-rails generate trigger:migration add_user_validation
-
-# Or using the full namespace
-rails generate pg_sql_triggers:trigger_migration add_user_validation
+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
 
-### Generator Features
+Files are written directly into the working tree and go through version control and code review like any other source file.
 
-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
+### Migration-Only Generator
 
-### Generator Edge Cases
+To generate a standalone trigger migration without a DSL stub:
+
+```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 +148,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/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

data/lib/generators/pg_sql_triggers/trigger_generator.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+require "active_support/core_ext/string/inflections"
+
+module PgSqlTriggers
+  module Generators
+    class TriggerGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generates a pg_sql_triggers DSL file and migration for a new trigger."
+
+      argument :trigger_name, type: :string,
+                              desc: "Name of the trigger (e.g. notify_on_insert_users)"
+      argument :table_name, type: :string,
+                            desc: "Database table the trigger attaches to (e.g. users)"
+      argument :events, type: :array, default: ["insert"], banner: "EVENT ...",
+                        desc: "Trigger events: insert, update, delete (default: insert)"
+
+      class_option :timing, type: :string, default: "before",
+                            desc: "Trigger timing: before or after (default: before)"
+      class_option :function, type: :string,
+                              desc: "Function name (default: TRIGGER_NAME_function)"
+
+      def self.next_migration_number(_dirname)
+        existing = if Rails.root.join("db/triggers").exist?
+                     Rails.root.glob("db/triggers/*.rb")
+                          .map { |f| File.basename(f, ".rb").split("_").first.to_i }
+                          .reject(&:zero?)
+                          .max || 0
+                   else
+                     0
+                   end
+
+        now = Time.now.utc
+        base = now.strftime("%Y%m%d%H%M%S").to_i
+        base = existing + 1 if existing.positive? && base <= existing
+        base
+      end
+
+      def create_dsl_file
+        template "trigger_dsl.rb.tt", "app/triggers/#{trigger_name}.rb"
+      end
+
+      def create_migration_file
+        template "trigger_migration_full.rb.tt", "db/triggers/#{migration_file_name}.rb"
+      end
+
+      private
+
+      def function_name
+        options[:function].presence || "#{trigger_name}_function"
+      end
+
+      def timing
+        options[:timing]
+      end
+
+      def events_list
+        events.map { |e| ":#{e}" }.join(", ")
+      end
+
+      def events_sql
+        events.map(&:upcase).join(" OR ")
+      end
+
+      def trigger_class_name
+        "Add#{trigger_name.camelize}"
+      end
+
+      def migration_file_name
+        "#{migration_number}_#{trigger_name}"
+      end
+
+      def migration_number
+        self.class.next_migration_number(nil)
+      end
+    end
+  end
+end

data/lib/pg_sql_triggers/drift/db_queries.rb

@@ -22,12 +22,12 @@ module PgSqlTriggers
             JOIN pg_namespace n ON c.relnamespace = n.oid
             JOIN pg_proc p ON t.tgfoid = p.oid
             WHERE NOT t.tgisinternal
-              AND n.nspname = 'public'
+              AND n.nspname = $1
               AND t.tgname NOT LIKE 'RI_%'
             ORDER BY c.relname, t.tgname;
           SQL
 
-          execute_query(sql)
+          execute_query(sql, [schema_name])
         end
 
         # Fetch single trigger
@@ -49,10 +49,10 @@ module PgSqlTriggers
             JOIN pg_proc p ON t.tgfoid = p.oid
             WHERE t.tgname = $1
               AND NOT t.tgisinternal
-              AND n.nspname = 'public';
+              AND n.nspname = $2;
           SQL
 
-          result = execute_query(sql, [trigger_name])
+          result = execute_query(sql, [trigger_name, schema_name])
           result.first
         end
 
@@ -75,12 +75,12 @@ module PgSqlTriggers
             JOIN pg_proc p ON t.tgfoid = p.oid
             WHERE c.relname = $1
               AND NOT t.tgisinternal
-              AND n.nspname = 'public'
+              AND n.nspname = $2
               AND t.tgname NOT LIKE 'RI_%'
             ORDER BY t.tgname;
           SQL
 
-          execute_query(sql, [table_name])
+          execute_query(sql, [table_name, schema_name])
         end
 
         # Fetch function body by function name
@@ -92,15 +92,19 @@ module PgSqlTriggers
             FROM pg_proc p
             JOIN pg_namespace n ON p.pronamespace = n.oid
             WHERE p.proname = $1
-              AND n.nspname = 'public';
+              AND n.nspname = $2;
           SQL
 
-          result = execute_query(sql, [function_name])
+          result = execute_query(sql, [function_name, schema_name])
           result.first
         end
 
         private
 
+        def schema_name
+          PgSqlTriggers.db_schema.to_s
+        end
+
         def execute_query(sql, params = [])
           if params.any?
             # Use ActiveRecord's connection to execute parameterized queries