pg_sql_triggers 1.0.0 → 1.1.0

data/README.md

@@ -21,37 +21,28 @@ Rails teams use PostgreSQL triggers for data integrity, performance, and billing
 - UI control
 - Emergency SQL escape hatches
 
-## Installation
+## Requirements
 
-Add this line to your application's Gemfile:
+- **Ruby 3.0+**
+- **Rails 6.1+**
+- **PostgreSQL** (any supported version)
 
-```ruby
-gem 'pg_sql_triggers'
-```
+## Quick Start
 
-And then execute:
+### Installation
 
-```bash
-$ bundle install
+```ruby
+# Gemfile
+gem 'pg_sql_triggers'
 ```
 
-Run the installer:
-
 ```bash
-$ rails generate pg_sql_triggers:install
-$ rails db:migrate
+bundle install
+rails generate pg_sql_triggers:install
+rails db:migrate
 ```
 
-This will:
-1. Create an initializer at `config/initializers/pg_sql_triggers.rb`
-2. Create migrations for registry table
-3. Mount the engine at `/pg_sql_triggers`
-
-## Usage
-
-### 1. Declaring Triggers
-
-Create trigger definitions using the Ruby DSL:
+### Define a Trigger
 
 ```ruby
 # app/triggers/users_email_validation.rb
@@ -59,222 +50,59 @@ PgSqlTriggers::DSL.pg_sql_trigger "users_email_validation" do
   table :users
   on :insert, :update
   function :validate_user_email
-
   version 1
   enabled false
-
   when_env :production
 end
 ```
 
-### 2. Trigger Migrations
-
-Generate and run trigger migrations similar to Rails schema migrations:
+### Create and Run Migration
 
 ```bash
-# Generate a new trigger migration
-rails generate trigger:migration add_validation_trigger
-
-# Run pending trigger migrations
+rails generate trigger:migration add_email_validation
 rake trigger:migrate
-
-# Rollback last trigger migration
-rake trigger:rollback
-
-# Rollback multiple steps
-rake trigger:rollback STEP=3
-
-# Check migration status
-rake trigger:migrate:status
-
-# Run a specific migration up
-rake trigger:migrate:up VERSION=20231215120000
-
-# Run a specific migration down
-rake trigger:migrate:down VERSION=20231215120000
-
-# Redo last migration
-rake trigger:migrate:redo
-```
-
-**Web UI Migration Management:**
-
-You can also manage migrations directly from the web dashboard:
-
-- **Apply All Pending Migrations**: Click the "Apply All Pending Migrations" button to run all pending migrations at once
-- **Rollback Last Migration**: Use the "Rollback Last Migration" button to undo the most recent migration
-- **Redo Last Migration**: Click "Redo Last Migration" to rollback and re-apply the last migration
-- **Individual Migration Actions**: Each migration in the status table has individual "Up", "Down", or "Redo" buttons for granular control
-
-All migration actions include confirmation dialogs and provide feedback via flash messages.
-
-Trigger migrations are stored in `db/triggers/` and follow the same naming convention as Rails migrations (`YYYYMMDDHHMMSS_name.rb`).
-
-Example trigger migration:
-
-```ruby
-# db/triggers/20231215120000_add_validation_trigger.rb
-class AddValidationTrigger < PgSqlTriggers::Migration
-  def up
-    execute <<-SQL
-      CREATE OR REPLACE FUNCTION validate_user_email()
-      RETURNS TRIGGER AS $$
-      BEGIN
-        IF NEW.email !~ '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$' THEN
-          RAISE EXCEPTION 'Invalid email format';
-        END IF;
-        RETURN NEW;
-      END;
-      $$ LANGUAGE plpgsql;
-
-      CREATE TRIGGER user_email_validation
-      BEFORE INSERT OR UPDATE ON users
-      FOR EACH ROW
-      EXECUTE FUNCTION validate_user_email();
-    SQL
-  end
-
-  def down
-    execute <<-SQL
-      DROP TRIGGER IF EXISTS user_email_validation ON users;
-      DROP FUNCTION IF EXISTS validate_user_email();
-    SQL
-  end
-end
 ```
 
-### 3. Combined Schema and Trigger Migrations
+### Access the Web UI
 
-Run both schema and trigger migrations together:
+Navigate to `http://localhost:3000/pg_sql_triggers` to manage triggers visually.
 
-```bash
-# Run both schema and trigger migrations
-rake db:migrate:with_triggers
+Screenshots are available in the [docs/screenshots](docs/screenshots/) directory.
 
-# Rollback both (rolls back the most recent migration)
-rake db:rollback:with_triggers
+## Documentation
 
-# Check status of both
-rake db:migrate:status:with_triggers
+Comprehensive documentation is available in the [docs](docs/) directory:
 
-# Get versions of both
-rake db:version:with_triggers
-```
+- **[Getting Started](docs/getting-started.md)** - Installation and basic setup
+- **[Usage Guide](docs/usage-guide.md)** - DSL syntax, migrations, and drift detection
+- **[Web UI](docs/web-ui.md)** - Using the web dashboard
+- **[Kill Switch](docs/kill-switch.md)** - Production safety features
+- **[Configuration](docs/configuration.md)** - Complete configuration reference
+- **[API Reference](docs/api-reference.md)** - Console API and programmatic access
 
-### 4. Console Introspection
+## Key Features
 
-Access trigger information from the Rails console:
+### Trigger DSL
+Define triggers using a Rails-native Ruby DSL with versioning and environment control.
 
-```ruby
-# List all triggers
-PgSqlTriggers::Registry.list
-
-# List enabled triggers
-PgSqlTriggers::Registry.enabled
+### Migration System
+Manage trigger functions and definitions with a migration system similar to Rails schema migrations.
 
-# List disabled triggers
-PgSqlTriggers::Registry.disabled
+### Drift Detection
+Automatically detect when database triggers drift from your DSL definitions.
 
-# Get triggers for a specific table
-PgSqlTriggers::Registry.for_table(:users)
+### Production Kill Switch
+Multi-layered safety mechanism preventing accidental destructive operations in production environments.
 
-# Check for drift
-PgSqlTriggers::Registry.diff
-
-# Validate all triggers
-PgSqlTriggers::Registry.validate!
-```
+### Web Dashboard
+Visual interface for managing triggers, running migrations, and executing SQL capsules.
 
-### 5. Web UI
+### Permissions
+Three-tier permission system (Viewer, Operator, Admin) with customizable authorization.
 
-Access the web UI at `http://localhost:3000/pg_sql_triggers` to:
+## Examples
 
-- View all triggers and their status
-- Enable/disable triggers
-- View drift states
-- Execute SQL capsules
-- Manage trigger lifecycle
-- **Run trigger migrations** (up/down/redo) directly from the dashboard
-  - Apply all pending migrations with a single click
-  - Rollback the last migration
-  - Redo the last migration
-  - Individual migration controls for each migration in the status table
-
-<img width="3360" height="2506" alt="screencapture-localhost-3000-pg-triggers-2025-12-27-17_04_29" src="https://github.com/user-attachments/assets/a7f5904b-1172-41fc-ba3f-c05587cb1fe8" />
-
-<img width="3360" height="3420" alt="screencapture-localhost-3000-pg-triggers-generator-new-2025-12-27-17_04_49" src="https://github.com/user-attachments/assets/fc9e53f2-f540-489d-8e41-6075dab8d731" />
-
-
-### 6. Permissions
-
-PgSqlTriggers supports three permission levels:
-
-- **Viewer**: Read-only access (view triggers, diffs)
-- **Operator**: Can enable/disable triggers, apply generated triggers
-- **Admin**: Full access including dropping triggers and executing SQL
-
-Configure custom permission checking:
-
-```ruby
-# config/initializers/pg_sql_triggers.rb
-PgSqlTriggers.configure do |config|
-  config.permission_checker = ->(actor, action, environment) {
-    # Your custom permission logic
-    user = User.find(actor[:id])
-    user.has_permission?(action)
-  }
-end
-```
-
-### 7. Drift Detection
-
-PgSqlTriggers automatically detects drift between your DSL definitions and the actual database state:
-
-- **Managed & In Sync**: Trigger matches DSL definition
-- **Managed & Drifted**: Trigger exists but doesn't match DSL
-- **Manual Override**: Trigger was modified outside of PgSqlTriggers
-- **Disabled**: Trigger is disabled
-- **Dropped**: Trigger was dropped but still in registry
-- **Unknown**: Trigger exists in DB but not in registry
-
-### 8. Production Kill Switch
-
-By default, PgSqlTriggers blocks destructive operations in production:
-
-```ruby
-# config/initializers/pg_sql_triggers.rb
-PgSqlTriggers.configure do |config|
-  # Enable production kill switch (default: true)
-  config.kill_switch_enabled = true
-end
-```
-
-Override for specific operations:
-
-```ruby
-PgSqlTriggers::SQL.override_kill_switch do
-  # Dangerous operation here
-end
-```
-
-## Configuration
-
-```ruby
-# config/initializers/pg_sql_triggers.rb
-PgSqlTriggers.configure do |config|
-  # Kill switch for production (default: true)
-  config.kill_switch_enabled = true
-
-  # Environment detection (default: -> { Rails.env })
-  config.default_environment = -> { Rails.env }
-
-  # Custom permission checker
-  config.permission_checker = ->(actor, action, environment) {
-    # Return true/false based on your authorization logic
-    true
-  }
-end
-```
+For working examples and complete demonstrations, check out the [example repository](https://github.com/samaswin87/pg_triggers_example).
 
 ## Core Principles
 
@@ -285,10 +113,20 @@ end
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Run `rake spec` to run tests. Run `bin/console` for an interactive prompt.
+
+To install this gem locally, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and run `bundle exec rake release`.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## Test Coverage
+
+See [COVERAGE.md](COVERAGE.md) for detailed coverage information.
+
+**Total Coverage: 84.97%**
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/samaswin87/pg_sql_triggers.
+
+## License
+
+See [LICENSE](LICENSE) file for details.

data/app/controllers/pg_sql_triggers/application_controller.rb

@@ -9,6 +9,9 @@ module PgSqlTriggers
 
     before_action :check_permissions?
 
+    # Helper methods available in views
+    helper_method :current_environment, :kill_switch_active?, :expected_confirmation_text
+
     private
 
     def check_permissions?
@@ -31,5 +34,48 @@ module PgSqlTriggers
     def current_user_id
       "unknown"
     end
+
+    # ========== Kill Switch Helpers ==========
+
+    # Returns the current environment
+    def current_environment
+      Rails.env
+    end
+
+    # Checks if kill switch is active for the current environment
+    def kill_switch_active?
+      PgSqlTriggers::SQL::KillSwitch.active?(environment: current_environment)
+    end
+
+    # Checks kill switch before executing a dangerous operation
+    # Raises KillSwitchError if the operation is blocked
+    #
+    # @param operation [Symbol] The operation being performed
+    # @param confirmation [String, nil] Optional confirmation text from params
+    def check_kill_switch(operation:, confirmation: nil)
+      PgSqlTriggers::SQL::KillSwitch.check!(
+        operation: operation,
+        environment: current_environment,
+        confirmation: confirmation,
+        actor: current_actor
+      )
+    end
+
+    # Before action to require kill switch override for an action
+    # Add to specific controller actions that need protection:
+    #   before_action -> { require_kill_switch_override(:operation_name) }, only: [:dangerous_action]
+    def require_kill_switch_override(operation, confirmation: nil)
+      check_kill_switch(operation: operation, confirmation: confirmation)
+    end
+
+    # Returns the expected confirmation text for an operation (for use in views)
+    def expected_confirmation_text(operation)
+      if PgSqlTriggers.respond_to?(:kill_switch_confirmation_pattern) &&
+         PgSqlTriggers.kill_switch_confirmation_pattern.respond_to?(:call)
+        PgSqlTriggers.kill_switch_confirmation_pattern.call(operation)
+      else
+        "EXECUTE #{operation.to_s.upcase}"
+      end
+    end
   end
 end

data/app/controllers/pg_sql_triggers/dashboard_controller.rb

@@ -4,11 +4,14 @@ module PgSqlTriggers
   class DashboardController < ApplicationController
     def index
       @triggers = PgSqlTriggers::TriggerRegistry.order(created_at: :desc)
+
+      # Get drift summary
+      drift_summary = PgSqlTriggers::Drift::Reporter.summary
       @stats = {
         total: @triggers.count,
         enabled: @triggers.enabled.count,
         disabled: @triggers.disabled.count,
-        drifted: 0 # Will be calculated by Drift::Detector
+        drifted: drift_summary[:drifted]
       }
 
       # Migration status with pagination

data/app/controllers/pg_sql_triggers/generator_controller.rb

@@ -8,7 +8,16 @@ module PgSqlTriggers
     # GET /generator/new
     # Display the multi-step form wizard
     def new
-      @form = PgSqlTriggers::Generator::Form.new
+      # Restore form data from session if available (when user clicks "Back to Edit")
+      session_data = session[:generator_form_data]
+      if session_data
+        # Convert to hash and symbolize keys for Form initialization
+        form_data = session_data.is_a?(Hash) ? session_data.symbolize_keys : session_data.to_h.symbolize_keys
+        @form = PgSqlTriggers::Generator::Form.new(form_data)
+        session.delete(:generator_form_data)
+      else
+        @form = PgSqlTriggers::Generator::Form.new
+      end
       @available_tables = fetch_available_tables
     end
 
@@ -17,7 +26,19 @@ module PgSqlTriggers
     def preview
       @form = PgSqlTriggers::Generator::Form.new(generator_params)
 
+      # If user clicked "Back to Edit", store form data in session and redirect
+      if params[:back_to_edit].present?
+        # Store form data as a hash (convert ActionController::Parameters to hash)
+        session[:generator_form_data] = generator_params.to_h
+        redirect_to new_generator_path
+        return
+      end
+
       if @form.valid?
+        # Store form data in session so it can be restored if user clicks "Back to Edit"
+        # Convert ActionController::Parameters to hash
+        session[:generator_form_data] = generator_params.to_h
+
         # Validate SQL function body (required field)
         @sql_validation = validate_function_sql(@form)
 
@@ -36,6 +57,9 @@ module PgSqlTriggers
     # POST /generator/create
     # Actually create the files and register in TriggerRegistry
     def create
+      # Check kill switch before generating trigger
+      check_kill_switch(operation: :ui_trigger_generate, confirmation: params[:confirmation_text])
+
       @form = PgSqlTriggers::Generator::Form.new(generator_params)
 
       if @form.valid?
@@ -55,6 +79,8 @@ module PgSqlTriggers
         result = PgSqlTriggers::Generator::Service.create_trigger(@form, actor: current_actor)
 
         if result[:success]
+          # Clear session data after successful creation
+          session.delete(:generator_form_data)
           files_msg = "Migration: #{result[:migration_path]}, DSL: #{result[:dsl_path]}"
           redirect_to root_path,
                       notice: "Trigger generated successfully. Files created: #{files_msg}"
@@ -67,6 +93,9 @@ module PgSqlTriggers
         @available_tables = fetch_available_tables
         render :new
       end
+    rescue PgSqlTriggers::KillSwitchError => e
+      flash[:error] = e.message
+      redirect_to root_path
     end
 
     # POST /generator/validate_table (AJAX)
@@ -96,10 +125,10 @@ module PgSqlTriggers
     private
 
     def generator_params
-      params.expect(
-        pg_sql_triggers_generator_form: [:trigger_name, :table_name, :function_name, :version,
-                                         :enabled, :condition, :generate_function_stub, :function_body,
-                                         { events: [], environments: [] }]
+      params.require(:pg_sql_triggers_generator_form).permit(
+        :trigger_name, :table_name, :function_name, :version,
+        :enabled, :condition, :timing, :generate_function_stub, :function_body,
+        events: [], environments: []
       )
     end
 
@@ -131,13 +160,52 @@ module PgSqlTriggers
       return nil if form.function_body.blank?
 
       # Create a temporary trigger registry object for validation
-      temp_registry = PgSqlTriggers::TriggerRegistry.new(
+      # Only include condition if the column exists
+      registry_attributes = {
         trigger_name: form.trigger_name,
+        table_name: form.table_name,
         function_body: form.function_body
-      )
+      }
+      # Only set condition if the column exists in the database
+      if PgSqlTriggers::TriggerRegistry.column_names.include?("condition")
+        registry_attributes[:condition] = form.condition
+      end
+
+      temp_registry = PgSqlTriggers::TriggerRegistry.new(registry_attributes)
+
+      # Build definition JSON for condition validation
+      definition = {
+        name: form.trigger_name,
+        table_name: form.table_name,
+        function_name: form.function_name,
+        events: form.events.compact_blank,
+        version: form.version,
+        enabled: form.enabled,
+        environments: form.environments.compact_blank,
+        condition: form.condition,
+        timing: form.timing || "before",
+        function_body: form.function_body
+      }
+      temp_registry.definition = definition.to_json
 
       validator = PgSqlTriggers::Testing::SyntaxValidator.new(temp_registry)
-      validator.validate_function_syntax
+
+      # Validate function syntax
+      function_result = validator.validate_function_syntax
+      return function_result unless function_result[:valid]
+
+      # Validate condition if present
+      if form.condition.present?
+        condition_result = validator.validate_condition
+        unless condition_result[:valid]
+          return {
+            valid: false,
+            error: "WHEN condition validation failed: #{condition_result[:error]}"
+          }
+        end
+      end
+
+      function_result
     rescue StandardError => e
       { valid: false, error: "Validation error: #{e.message}" }
     end

data/app/controllers/pg_sql_triggers/migrations_controller.rb

@@ -5,6 +5,9 @@ module PgSqlTriggers
   # Provides actions to run migrations up, down, and redo
   class MigrationsController < ApplicationController
     def up
+      # Check kill switch before running migration
+      check_kill_switch(operation: :ui_migration_up, confirmation: params[:confirmation_text])
+
       target_version = params[:version]&.to_i
       PgSqlTriggers::Migrator.ensure_migrations_table!
 
@@ -22,6 +25,9 @@ module PgSqlTriggers
         end
       end
       redirect_to root_path
+    rescue PgSqlTriggers::KillSwitchError => e
+      flash[:error] = e.message
+      redirect_to root_path
     rescue StandardError => e
       Rails.logger.error("Migration up failed: #{e.message}\n#{e.backtrace.join("\n")}")
       flash[:error] = "Failed to apply migration: #{e.message}"
@@ -29,6 +35,9 @@ module PgSqlTriggers
     end
 
     def down
+      # Check kill switch before rolling back migration
+      check_kill_switch(operation: :ui_migration_down, confirmation: params[:confirmation_text])
+
       target_version = params[:version]&.to_i
       PgSqlTriggers::Migrator.ensure_migrations_table!
 
@@ -48,6 +57,9 @@ module PgSqlTriggers
         flash[:success] = "Rolled back last migration successfully."
       end
       redirect_to root_path
+    rescue PgSqlTriggers::KillSwitchError => e
+      flash[:error] = e.message
+      redirect_to root_path
     rescue StandardError => e
       Rails.logger.error("Migration down failed: #{e.message}\n#{e.backtrace.join("\n")}")
       flash[:error] = "Failed to rollback migration: #{e.message}"
@@ -55,6 +67,9 @@ module PgSqlTriggers
     end
 
     def redo
+      # Check kill switch before redoing migration
+      check_kill_switch(operation: :ui_migration_redo, confirmation: params[:confirmation_text])
+
       target_version = params[:version]&.to_i
       PgSqlTriggers::Migrator.ensure_migrations_table!
 
@@ -75,6 +90,9 @@ module PgSqlTriggers
         flash[:success] = "Last migration redone successfully."
       end
       redirect_to root_path
+    rescue PgSqlTriggers::KillSwitchError => e
+      flash[:error] = e.message
+      redirect_to root_path
     rescue StandardError => e
       Rails.logger.error("Migration redo failed: #{e.message}\n#{e.backtrace.join("\n")}")
       flash[:error] = "Failed to redo migration: #{e.message}"