pg_sql_triggers 1.0.0 → 1.0.1

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
-
-Run both schema and trigger migrations together:
-
-```bash
-# Run both schema and trigger migrations
-rake db:migrate:with_triggers
-
-# Rollback both (rolls back the most recent migration)
-rake db:rollback:with_triggers
-
-# Check status of both
-rake db:migrate:status:with_triggers
-
-# Get versions of both
-rake db:version:with_triggers
 ```
 
-### 4. Console Introspection
-
-Access trigger information from the Rails console:
-
-```ruby
-# List all triggers
-PgSqlTriggers::Registry.list
-
-# List enabled triggers
-PgSqlTriggers::Registry.enabled
-
-# List disabled triggers
-PgSqlTriggers::Registry.disabled
-
-# Get triggers for a specific table
-PgSqlTriggers::Registry.for_table(:users)
-
-# Check for drift
-PgSqlTriggers::Registry.diff
-
-# Validate all triggers
-PgSqlTriggers::Registry.validate!
-```
-
-### 5. Web UI
-
-Access the web UI at `http://localhost:3000/pg_sql_triggers` to:
-
-- 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" />
+### Access the Web UI
 
-<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" />
+Navigate to `http://localhost:3000/pg_sql_triggers` to manage triggers visually.
 
+Screenshots are available in the [docs/screenshots](docs/screenshots/) directory.
 
-### 6. Permissions
+## Documentation
 
-PgSqlTriggers supports three permission levels:
+Comprehensive documentation is available in the [docs](docs/) directory:
 
-- **Viewer**: Read-only access (view triggers, diffs)
-- **Operator**: Can enable/disable triggers, apply generated triggers
-- **Admin**: Full access including dropping triggers and executing SQL
+- **[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
 
-Configure custom permission checking:
+## Key Features
 
-```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
-```
+### Trigger DSL
+Define triggers using a Rails-native Ruby DSL with versioning and environment control.
 
-### 7. Drift Detection
+### Migration System
+Manage trigger functions and definitions with a migration system similar to Rails schema migrations.
 
-PgSqlTriggers automatically detects drift between your DSL definitions and the actual database state:
+### Drift Detection
+Automatically detect when database triggers drift from your DSL definitions.
 
-- **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
+### Production Kill Switch
+Multi-layered safety mechanism preventing accidental destructive operations in production environments.
 
-### 8. Production Kill Switch
+### Web Dashboard
+Visual interface for managing triggers, running migrations, and executing SQL capsules.
 
-By default, PgSqlTriggers blocks destructive operations in production:
+### Permissions
+Three-tier permission system (Viewer, Operator, Admin) with customizable authorization.
 
-```ruby
-# config/initializers/pg_sql_triggers.rb
-PgSqlTriggers.configure do |config|
-  # Enable production kill switch (default: true)
-  config.kill_switch_enabled = true
-end
-```
+## Examples
 
-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,14 @@ 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 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).
+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`.
 
 ## 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/generator_controller.rb

@@ -36,6 +36,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?
@@ -67,6 +70,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 +102,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, :generate_function_stub, :function_body,
+        events: [], environments: []
       )
     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}"

data/app/models/pg_sql_triggers/trigger_registry.rb

@@ -24,7 +24,16 @@ module PgSqlTriggers
       PgSqlTriggers::Drift.detect(trigger_name)
     end
 
-    def enable!
+    def enable!(confirmation: nil)
+      # Check kill switch before enabling trigger
+      # Use Rails.env for kill switch check, not the trigger's environment field
+      PgSqlTriggers::SQL::KillSwitch.check!(
+        operation: :trigger_enable,
+        environment: Rails.env,
+        confirmation: confirmation,
+        actor: { type: "Console", id: "TriggerRegistry#enable!" }
+      )
+
       # Check if trigger exists in database before trying to enable it
       trigger_exists = false
       begin
@@ -50,7 +59,16 @@ module PgSqlTriggers
       update!(enabled: true)
     end
 
-    def disable!
+    def disable!(confirmation: nil)
+      # Check kill switch before disabling trigger
+      # Use Rails.env for kill switch check, not the trigger's environment field
+      PgSqlTriggers::SQL::KillSwitch.check!(
+        operation: :trigger_disable,
+        environment: Rails.env,
+        confirmation: confirmation,
+        actor: { type: "Console", id: "TriggerRegistry#disable!" }
+      )
+
       # Check if trigger exists in database before trying to disable it
       trigger_exists = false
       begin

data/app/views/layouts/pg_sql_triggers/application.html.erb

@@ -24,6 +24,8 @@
   </nav>
 
   <main style="max-width: 1200px; margin: 2rem auto; padding: 0 1rem;">
+    <%= render 'pg_sql_triggers/shared/kill_switch_status' %>
+
     <% if flash[:success] %>
       <div style="background: #d4edda; color: #155724; padding: 1rem; margin-bottom: 1rem; border-radius: 4px; border-left: 4px solid #28a745;">
         <%= flash[:success] %>
@@ -32,7 +34,38 @@
 
     <% if flash[:error] %>
       <div style="background: #f8d7da; color: #721c24; padding: 1rem; margin-bottom: 1rem; border-radius: 4px; border-left: 4px solid #dc3545;">
-        <%= flash[:error] %>
+        <% error_message = flash[:error].to_s %>
+        <% if error_message.include?("Kill switch is active") %>
+          <%# Format kill switch error messages nicely %>
+          <% lines = error_message.split("\n") %>
+
+          <%# Main error header with clear start %>
+          <div style="display: flex; align-items: flex-start; margin-bottom: 1rem; padding-bottom: 1rem; border-bottom: 2px solid #f5c6cb;">
+            <span style="font-size: 1.8em; margin-right: 0.75rem; line-height: 1.2;">⚠️</span>
+            <div style="flex: 1;">
+              <div style="font-weight: bold; font-size: 1.15em; margin-bottom: 0.5rem;">
+                Operation Blocked
+              </div>
+              <% lines[0..1].each do |line| %>
+                <% next if line.strip.empty? %>
+                <div style="margin: 0.25rem 0;"><%= line.strip %></div>
+              <% end %>
+            </div>
+          </div>
+
+          <%# Instructions section with preserved formatting %>
+          <div style="margin-top: 0.5rem;">
+            <%# Extract and format the instructions portion %>
+            <% instructions_start = error_message.index("To override") || 0 %>
+            <% instructions_text = error_message[instructions_start..-1] %>
+            <div style="white-space: pre-wrap; word-wrap: break-word; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif; line-height: 1.6;">
+              <%= instructions_text.strip %>
+            </div>
+          </div>
+        <% else %>
+          <%# Regular error message - preserve formatting %>
+          <div style="white-space: pre-wrap; word-wrap: break-word;"><%= error_message %></div>
+        <% end %>
       </div>
     <% end %>