pg_sql_triggers 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 868dfd4da507455302b3e00e6dd27a8cc5440c6e81c60e978e10a031a339e8c1
+  data.tar.gz: e8b013e8485431fac4d30bfd7f3faade2130b4b55d1be4cfbf0f9ffdbad2ef6f
+SHA512:
+  metadata.gz: 1265add39a041703438f7406a6a4b9c6f7b6e5dcf06240c8dc53c53f97c747cea850f1fa603d9eacbe072a43fbc4fe0cc371536e2bd8a215f30609171ccb8ffa
+  data.tar.gz: e0d649df16316ef840fd5d42ef199b5dcf9f22d4ebe20134250ffe8b369d52c16f3774640ab95294ca487f4cb065d624bb7e386d1c223de536fc3dfc16d03511

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,120 @@
+require:
+  - rubocop-rspec
+  - rubocop-rspec_rails
+
+plugins:
+  - rubocop-rails
+  - rubocop-capybara
+  - rubocop-factory_bot
+
+AllCops:
+  TargetRubyVersion: 2.7
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'bin/**/*'
+    - 'vendor/**/*'
+    - 'node_modules/**/*'
+    - 'db/schema.rb'
+    - 'tmp/**/*'
+    - 'spec/dummy/**/*'
+
+# Metrics
+Metrics/AbcSize:
+  Max: 65
+  Exclude:
+    - 'spec/**/*'
+    - 'app/controllers/**/*'
+    - 'lib/generators/**/*'
+    - 'lib/pg_sql_triggers/testing/**/*'
+
+Metrics/BlockLength:
+  Max: 50
+  Exclude:
+    - 'spec/**/*'
+    - 'config/routes.rb'
+    - '*.gemspec'
+    - 'lib/tasks/**/*'
+
+Metrics/ClassLength:
+  Max: 200
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/CyclomaticComplexity:
+  Max: 18
+  Exclude:
+    - 'app/controllers/**/*'
+    - 'lib/pg_sql_triggers/testing/**/*'
+
+Metrics/MethodLength:
+  Max: 55
+  Exclude:
+    - 'spec/**/*'
+    - 'app/controllers/**/*'
+    - 'lib/generators/**/*'
+    - 'lib/pg_sql_triggers/testing/**/*'
+
+Metrics/PerceivedComplexity:
+  Max: 15
+  Exclude:
+    - 'app/controllers/**/*'
+    - 'lib/pg_sql_triggers/testing/**/*'
+
+# Style
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+# Layout
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - 'spec/**/*'
+
+# Gemspec
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+# Rails
+Rails:
+  Enabled: true
+
+Rails/I18nLocaleTexts:
+  Enabled: false
+
+# RSpec
+RSpec/ExampleLength:
+  Max: 10
+  Exclude:
+    - 'spec/**/*_spec.rb'
+
+RSpec/FilePath:
+  Enabled: false
+
+RSpec/InstanceVariable:
+  Enabled: false
+
+RSpec/MessageChain:
+  Enabled: false
+
+RSpec/MessageSpies:
+  Enabled: false
+
+RSpec/MultipleDescribes:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Max: 10
+
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+# Capybara
+Capybara/RSpec/PredicateMatcher:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-12-27
+
+### Added
+- Initial gem structure
+- PostgreSQL trigger DSL for defining triggers with version and environment support
+- Trigger registry system for tracking trigger metadata (trigger_name, table_name, version, enabled, checksum, source, environment)
+- Drift detection between DSL definitions and database state (Managed & In Sync, Managed & Drifted, Manual Override, Disabled, Dropped, Unknown)
+- Permission system with three levels (Viewer, Operator, Admin)
+- Mountable Rails Engine with web UI for trigger management
+- Production kill switch for safety (blocks destructive operations in production by default)
+- Console introspection APIs (list, enabled, disabled, for_table, diff, validate!)
+- Migration system for registry table
+- Install generator (`rails generate pg_sql_triggers:install`)
+- Trigger migration system similar to Rails schema migrations
+  - Generate trigger migrations
+  - Run pending migrations (`rake trigger:migrate`)
+  - Rollback migrations (`rake trigger:rollback`)
+  - Migration status and individual migration controls
+- Combined schema and trigger migration tasks (`rake db:migrate:with_triggers`)
+- Web UI for trigger migrations (up/down/redo)
+  - Apply all pending migrations from dashboard
+  - Rollback last migration
+  - Redo last migration
+  - Individual migration actions (up/down/redo) for each migration
+  - Flash messages for success, error, warning, and info states
+- Database introspection for trigger state detection
+- SQL execution support with safety checks
+- Trigger generator with form and service layer
+- Testing utilities for safe execution and syntax validation
+
+### Changed
+- Initial release
+
+### Deprecated
+- Nothing yet
+
+### Removed
+- Nothing yet
+
+### Fixed
+- Initial release
+
+### Security
+- Production kill switch prevents destructive operations in production environments
+- Permission system enforces role-based access control (Viewer, Operator, Admin)

data/Goal.md

@@ -0,0 +1,294 @@
+You are building a **production-grade Ruby on Rails gem** named **pg_sql_triggers**.
+
+This gem is **not a toy generator**.
+It is a **PostgreSQL Trigger Control Plane for Rails**, designed for real teams running production systems.
+
+You must follow everything below strictly.
+
+---
+
+## 1. Problem Statement
+
+Rails teams use PostgreSQL triggers for:
+- data integrity
+- performance
+- billing logic
+
+But triggers today are:
+- managed manually
+- invisible to Rails
+- unsafe to deploy
+- easy to drift
+
+This gem brings triggers into the Rails ecosystem with:
+- lifecycle management
+- safe deploys
+- versioning
+- UI control
+- emergency SQL escape hatches
+
+---
+
+## 2. Core Philosophy
+
+- Rails-native
+- Explicit over magic
+- Safe by default
+- Power with guardrails
+
+This gem **manages lifecycle**, not business logic.
+
+---
+
+## 3. Supported Capabilities (MUST IMPLEMENT)
+
+### A. Trigger Declaration (DSL)
+
+Developers declare triggers using Ruby DSL:
+
+```ruby
+pg_sql_trigger "users_email_validation" do
+  table :users
+  on :insert, :update
+  function :validate_user_email
+
+  version 3
+  enabled true
+
+  when_env :production
+end
+```
+
+Rules:
+- DSL generates metadata, NOT raw SQL
+- Every trigger has a version
+- Triggers are environment-aware
+- Triggers can be enabled or disabled
+
+---
+
+### B. Trigger Generation
+
+The gem must generate triggers safely.
+
+Generators create:
+1. Trigger DSL file
+2. Function stub (PL/pgSQL)
+3. Manifest metadata
+
+Rules:
+- Generated triggers are **disabled by default**
+- Nothing executes automatically
+- Developers must explicitly apply
+
+---
+
+### C. Trigger Registry (Source of Truth)
+
+All triggers must be tracked in a registry table.
+
+Registry tracks:
+- trigger_name
+- table_name
+- version
+- enabled
+- checksum
+- source (dsl / generated / manual_sql)
+- environment
+- installed_at
+- last_verified_at
+
+Rails must always know:
+- what exists
+- how it was created
+- whether it drifted
+
+---
+
+### D. Safe Apply & Deploy
+
+Applying triggers must:
+- Run in a transaction
+- Diff expected vs actual
+- Never blindly DROP + CREATE
+- Support rollback on failure
+- Update registry atomically
+
+---
+
+### E. Drift Detection
+
+System must detect:
+- Missing triggers
+- Version mismatch
+- Function body drift
+- Manual SQL overrides
+- Unknown external triggers
+
+Drift states:
+1. Managed & In Sync
+2. Managed & Drifted
+3. Manual Override
+4. Disabled
+5. Dropped (Recorded)
+6. Unknown (External)
+
+---
+
+### F. Rails Console Introspection
+
+Provide console APIs:
+
+PgSqlTrigger.list
+PgSqlTrigger.enabled
+PgSqlTrigger.disabled
+PgSqlTrigger.for_table(:users)
+PgSqlTrigger.diff
+PgSqlTrigger.validate!
+
+No raw SQL required by users.
+
+---
+
+## 4. Free-Form SQL Execution (MANDATORY)
+
+The gem MUST support free-form SQL execution.
+
+This is required for:
+- emergency fixes
+- complex migrations
+- DB-owner workflows
+
+### SQL Capsules
+
+Free-form SQL is wrapped in **named SQL capsules**:
+
+- Must be named
+- Must declare environment
+- Must declare purpose
+- Must be applied explicitly
+
+Rules:
+- Runs in a transaction
+- Checksum verified
+- Registry updated
+- Marked as `source = manual_sql`
+
+---
+
+## 5. Permissions Model v1
+
+Three permission levels:
+
+### Viewer
+- Read-only
+- View triggers
+- View diffs
+
+### Operator
+- Enable / Disable triggers
+- Apply generated triggers
+- Re-execute triggers in non-prod
+- Dry-run SQL
+
+### Admin
+- Drop triggers
+- Execute free-form SQL
+- Re-execute triggers in any env
+- Override drift
+
+Permissions enforced in:
+- UI
+- CLI
+- Console
+
+---
+
+## 6. Kill Switch for Production SQL (MANDATORY)
+
+Production mutations must be gated.
+
+### Levels:
+1. Global disable (default)
+2. Runtime ENV override
+3. Explicit confirmation text
+4. Optional time-window auto-lock
+
+Kill switch must:
+- Block UI
+- Block CLI
+- Block console
+- Always log attempts
+
+---
+
+## 8. UI (Mountable Rails Engine)
+
+UI is operational, not decorative.
+
+### Dashboard
+- Trigger name
+- Table
+- Version
+- Status
+- Source
+- Drift state
+- Environment
+- Last applied
+
+### Trigger Detail Page
+- Summary panel
+- SQL diff
+- Registry state
+
+### Actions (State-Based)
+- Enable
+- Disable
+- Drop
+- Re-execute
+- Execute SQL capsule
+
+Buttons must:
+- Be permission-aware
+- Be env-aware
+- Respect kill switch
+
+---
+
+## 9. Drop & Re-Execute Flow (CRITICAL)
+
+Re-execute must:
+1. Show diff
+2. Require reason
+3. Require typed confirmation
+4. Execute transactionally
+5. Update registry
+
+No silent operations allowed.
+
+---
+
+## 10. What This Gem Is NOT
+
+- Not a raw SQL editor
+- Not a trigger playground
+- Not auto-executing
+- Not unsafe
+- Not magic
+
+---
+
+## 11. Non-Negotiable Constraints
+
+- No silent prod changes
+- No hidden state
+- No bypassing registry
+- No bypassing permissions
+
+---
+
+## 12. Final Framing (VERY IMPORTANT)
+
+This gem must be described as:
+
+> **A PostgreSQL Trigger Control Plane for Rails**

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 samaswin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.