pg_sql_triggers 1.0.0

data/README.md

@@ -0,0 +1,294 @@
+# PgSqlTriggers
+
+> **A PostgreSQL Trigger Control Plane for Rails**
+
+Production-grade PostgreSQL trigger management for Rails with lifecycle management, safe deploys, versioning, drift detection, and a mountable UI.
+
+## Why PgSqlTriggers?
+
+Rails teams use PostgreSQL triggers for data integrity, performance, and billing logic. But triggers today are:
+
+- Managed manually
+- Invisible to Rails
+- Unsafe to deploy
+- Easy to drift
+
+**PgSqlTriggers** brings triggers into the Rails ecosystem with:
+
+- Lifecycle management
+- Safe deploys
+- Versioning
+- UI control
+- Emergency SQL escape hatches
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pg_sql_triggers'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Run the installer:
+
+```bash
+$ 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:
+
+```ruby
+# app/triggers/users_email_validation.rb
+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:
+
+```bash
+# Generate a new trigger migration
+rails generate trigger:migration add_validation_trigger
+
+# Run pending trigger migrations
+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" />
+
+<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
+```
+
+## Core Principles
+
+- **Rails-native**: Works seamlessly with Rails conventions
+- **Explicit over magic**: No automatic execution
+- **Safe by default**: Requires explicit confirmation for destructive actions
+- **Power with guardrails**: Emergency SQL escape hatches with safety checks
+
+## 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.
+
+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).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/samaswin87/pg_sql_triggers.

data/RELEASE.md

@@ -0,0 +1,270 @@
+# Gem Release Guide
+
+This guide walks you through the process of releasing a new version of `pg_sql_triggers` to RubyGems.
+
+## Prerequisites
+
+Before releasing, ensure you have:
+
+1. **RubyGems account**: You need an account at https://rubygems.org
+2. **API key**: Generate one at https://rubygems.org/api_keys
+3. **MFA enabled**: Your gemspec requires MFA (`rubygems_mfa_required = "true"`), so ensure MFA is enabled on your RubyGems account
+4. **Git access**: You need push access to the repository
+
+## Release Checklist
+
+### 1. Update Version Number
+
+Update the version in `lib/pg_sql_triggers/version.rb` following [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** (1.0.0 → 2.0.0): Breaking changes
+- **MINOR** (1.0.0 → 1.1.0): New features, backward compatible
+- **PATCH** (1.0.0 → 1.0.1): Bug fixes, backward compatible
+
+```ruby
+# lib/pg_sql_triggers/version.rb
+module PgSqlTriggers
+  VERSION = "1.0.1"  # Update this
+end
+```
+
+### 2. Update CHANGELOG.md
+
+Add a new entry to `CHANGELOG.md` following the existing format:
+
+```markdown
+## [1.0.1] - 2025-12-28
+
+### Added
+- New feature description
+
+### Changed
+- Change description
+
+### Fixed
+- Bug fix description
+```
+
+**Important**: Update the date to today's date and ensure all changes since the last release are documented.
+
+### 3. Run Tests
+
+Ensure all tests pass before releasing:
+
+```bash
+# Run the full test suite
+bundle exec rspec
+
+# Or use the rake task
+bundle exec rake spec
+```
+
+### 4. Check for Linting Issues
+
+Run RuboCop to ensure code quality:
+
+```bash
+bundle exec rubocop
+```
+
+Fix any issues before proceeding.
+
+### 5. Build the Gem Locally (Optional but Recommended)
+
+Build the gem locally to verify it works:
+
+```bash
+# Build the gem
+gem build pg_sql_triggers.gemspec
+
+# This creates pg_sql_triggers-1.0.1.gem
+# You can inspect it or test install it locally
+```
+
+### 6. Commit Your Changes
+
+Commit the version bump and CHANGELOG updates:
+
+```bash
+# Stage your changes
+git add lib/pg_sql_triggers/version.rb CHANGELOG.md
+
+# Commit with a descriptive message
+git commit -m "Bump version to 1.0.1"
+```
+
+### 7. Create a Git Tag
+
+The release process will create a tag automatically, but you can also create it manually:
+
+```bash
+# Create an annotated tag
+git tag -a v1.0.1 -m "Release version 1.0.1"
+
+# Or let the release task handle it (recommended)
+```
+
+### 8. Push to Git Repository
+
+Push your commits and tags:
+
+```bash
+# Push commits
+git push origin main  # or master, depending on your default branch
+
+# Push tags (if created manually)
+git push origin v1.0.1
+```
+
+### 9. Release to RubyGems
+
+Use the built-in Rake task to release:
+
+```bash
+# This will:
+# 1. Build the gem
+# 2. Create a git tag
+# 3. Push commits and tags to git
+# 4. Push the gem to RubyGems.org
+bundle exec rake release
+```
+
+**Note**: This command will:
+- Build the gem file
+- Create a git tag for the version
+- Push git commits and tags to the remote repository
+- Push the `.gem` file to RubyGems.org
+
+You'll be prompted for:
+- Your RubyGems credentials (username and password)
+- Your MFA code (if MFA is enabled, which it should be)
+
+### 10. Verify the Release
+
+After releasing, verify the gem is available:
+
+```bash
+# Check if the gem is available
+gem search pg_sql_triggers
+
+# Or visit https://rubygems.org/gems/pg_sql_triggers
+```
+
+### 11. Create a GitHub Release (Optional but Recommended)
+
+1. Go to https://github.com/samaswin87/pg_sql_triggers/releases
+2. Click "Draft a new release"
+3. Select the tag you just created (e.g., `v1.0.1`)
+4. Use the CHANGELOG entry as the release notes
+5. Publish the release
+
+## Quick Release Script
+
+For convenience, here's a quick release script you can run:
+
+```bash
+#!/bin/bash
+# release.sh
+
+set -e  # Exit on error
+
+VERSION=$1
+
+if [ -z "$VERSION" ]; then
+  echo "Usage: ./release.sh <version>"
+  echo "Example: ./release.sh 1.0.1"
+  exit 1
+fi
+
+echo "Releasing version $VERSION..."
+
+# Update version
+sed -i '' "s/VERSION = \".*\"/VERSION = \"$VERSION\"/" lib/pg_sql_triggers/version.rb
+
+# Run tests
+echo "Running tests..."
+bundle exec rspec
+
+# Run linter
+echo "Running linter..."
+bundle exec rubocop
+
+# Build gem
+echo "Building gem..."
+gem build pg_sql_triggers.gemspec
+
+# Commit changes
+echo "Committing changes..."
+git add lib/pg_sql_triggers/version.rb CHANGELOG.md
+git commit -m "Bump version to $VERSION"
+
+# Create tag
+echo "Creating tag..."
+git tag -a v$VERSION -m "Release version $VERSION"
+
+# Push
+echo "Pushing to git..."
+git push origin main
+git push origin v$VERSION
+
+# Release
+echo "Releasing to RubyGems..."
+bundle exec rake release
+
+echo "Release $VERSION complete!"
+```
+
+## Troubleshooting
+
+### MFA Required Error
+
+If you get an MFA error, ensure:
+1. MFA is enabled on your RubyGems account
+2. You're using the correct API key
+3. You have the latest version of the `gem` command
+
+### Authentication Issues
+
+If authentication fails:
+1. Check your RubyGems credentials: `gem credentials list`
+2. Update credentials: `gem signin`
+3. Verify your API key at https://rubygems.org/api_keys
+
+### Tag Already Exists
+
+If the tag already exists:
+```bash
+# Delete local tag
+git tag -d v1.0.1
+
+# Delete remote tag
+git push origin :refs/tags/v1.0.1
+
+# Then retry the release
+```
+
+### Gem Already Exists
+
+If the version already exists on RubyGems:
+1. You cannot overwrite a published gem version
+2. You must bump to a new version number
+3. Update the version in `version.rb` and try again
+
+## Best Practices
+
+1. **Always test before releasing**: Run the full test suite
+2. **Update CHANGELOG**: Document all changes for users
+3. **Follow semantic versioning**: Be consistent with version numbers
+4. **Create GitHub releases**: Helps with documentation and announcements
+5. **Release during business hours**: Easier to monitor and fix issues
+6. **Test the gem after release**: Install it in a test project to verify
+
+## Post-Release
+
+After a successful release:
+
+1. ✅ Verify the gem is installable: `gem install pg_sql_triggers -v 1.0.1`
+2. ✅ Check the RubyGems page: https://rubygems.org/gems/pg_sql_triggers
+3. ✅ Update any documentation that references version numbers
+4. ✅ Announce the release (if applicable) via blog, Twitter, etc.
+

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Bundler gem tasks provide:
+# - rake build: Build the gem file (creates pg_sql_triggers-X.X.X.gem)
+# - rake install: Build and install the gem locally
+# - rake release: Build, tag, push to git, and publish to RubyGems.org
+require "bundler/gem_tasks"
+
+# RSpec tasks:
+# - rake spec: Run the test suite
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+# Default task runs the test suite
+task default: :spec

data/app/assets/javascripts/pg_sql_triggers/application.js

@@ -0,0 +1,5 @@
+// This is a manifest file that'll be compiled into application.js
+//
+//= require_self
+
+// PgSqlTriggers JavaScript