pg_sql_triggers 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f8d9043692145293beaf91342280ca01702979a6e50190fd5930d8578170291
-  data.tar.gz: 18e9eaaa03de9932f9916bcc2110e9896a271c555a3b94f13348baf1e37c584c
+  metadata.gz: 3009d08e9604d3cad9af352b595fe76fb2688c7f1bf80cfbb92bbb9bbadeb996
+  data.tar.gz: 0155742bcf1ad97690f42c8193da6ff408f09dab26f8684c84a6954c8438f28f
 SHA512:
-  metadata.gz: 8ed71a10f16385f318a4a596a444c07d2cb00a7d07119043c921cf43b1d2199db6d36cc30b5ea523bcbb527a817b97fbe7c507ac81a4cec3931f887c2a4606ca
-  data.tar.gz: af0162bab6005904e1649619e5a68e1c1f36733e4f8d34f0306c9a64af07356e9f19165dda1a60f19606b36b517ee1ad34224a50b479b02b0b8efd340175f1fc
+  metadata.gz: f76fc2c48a00922e7265acce7d8c87e0477686540b4749aef94bbd1d4b914f7cdf76a0c28cc3f3dd816489c24606ee6b2fe424d309dbc03e70cf160fba6daad8
+  data.tar.gz: 4988c497e39a54d517e1f96a4328609de0bb0451658d228b46a4bd2d448267b7866ede607eb702430510a88b16fb328d801fc81a00e0d93c231ad7d94caff216

data/CHANGELOG.md

@@ -5,7 +5,259 @@ 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).
 
-## [Unreleased]
+## [1.4.0] - 2026-03-01
+
+### Added
+
+- **[Feature 4.1] `FOR EACH ROW` / `FOR EACH STATEMENT` DSL support** — Every PostgreSQL trigger
+  requires a row-level or statement-level execution granularity, but the gem previously hard-coded
+  `FOR EACH ROW` with no way for callers to change it. Two new DSL methods, `for_each_row` and
+  `for_each_statement`, let trigger definitions declare the desired granularity explicitly. The
+  value defaults to `"row"` so all existing definitions continue to produce `FOR EACH ROW` triggers
+  without modification. The field is stored in a new `for_each` column on the registry table
+  (migration `20260228000001_add_for_each_to_pg_sql_triggers_registry.rb`), included in all three
+  checksum computations (`TriggerRegistry#calculate_checksum`, `Registry::Manager#calculate_checksum`,
+  and `Drift::Detector#calculate_db_checksum`), extracted from live trigger definitions via a new
+  `extract_trigger_for_each` helper, and validated by `Registry::Validator` (only `"row"` and
+  `"statement"` are accepted). The SQL reconstructed by `TriggerRegistry#build_trigger_sql_from_definition`
+  during `re_execute!` now honours the stored `for_each` value.
+  ([lib/pg_sql_triggers/dsl/trigger_definition.rb](lib/pg_sql_triggers/dsl/trigger_definition.rb),
+  [lib/pg_sql_triggers/registry/manager.rb](lib/pg_sql_triggers/registry/manager.rb),
+  [lib/pg_sql_triggers/registry/validator.rb](lib/pg_sql_triggers/registry/validator.rb),
+  [lib/pg_sql_triggers/drift/detector.rb](lib/pg_sql_triggers/drift/detector.rb),
+  [app/models/pg_sql_triggers/trigger_registry.rb](app/models/pg_sql_triggers/trigger_registry.rb),
+  [db/migrate/20260228000001_add_for_each_to_pg_sql_triggers_registry.rb](db/migrate/20260228000001_add_for_each_to_pg_sql_triggers_registry.rb))
+
+### Changed
+
+- **[Refactor 5.1] `SQL::KillSwitch` reduced from 329 to 166 lines** — The module was inflated by
+  four separate single-purpose log helpers (`log_allowed`, `log_override`, `log_blocked`,
+  `format_actor`), a `raise_blocked_error` method whose two heredocs (`message` and `recovery`)
+  duplicated each other across 30 lines, verbose per-method comments, and a
+  `rubocop:disable Metrics/ModuleLength` suppressor. Collapsed the four log helpers into one
+  private `log(level, status, op, env, actor, extra = nil)` method; inlined `raise_blocked_error`
+  as a concise 5-line `raise` call; removed all comment padding; renamed `detect_environment` →
+  `resolve_environment` for clarity. All three-layer semantics (config → ENV override → explicit
+  confirmation), public API (`active?`, `check!`, `override`, `validate_confirmation!`), log
+  message formats, and error message content are unchanged — all existing specs continue to pass.
+  ([lib/pg_sql_triggers/sql/kill_switch.rb](lib/pg_sql_triggers/sql/kill_switch.rb))
+
+- **[Design] Eliminated N+1 queries in drift detection** — `Drift::Detector.detect_all` and
+  `detect_for_table` previously called `detect(trigger_name)` per registry entry, which issued a
+  `TriggerRegistry.find_by` and a `DbQueries.find_trigger` DB query for every row (N+1 pattern).
+  These methods now build an `index_by` hash from the bulk-fetched result of `DbQueries.all_triggers`
+  and map over pre-loaded registry entries, eliminating all per-entry lookups. A new private method
+  `detect_with_preloaded(registry_entry, db_trigger)` performs state computation with zero
+  additional queries.
+  ([lib/pg_sql_triggers/drift/detector.rb](lib/pg_sql_triggers/drift/detector.rb))
+
+- **[Design] Thread-safe registry cache** — `Registry::Manager._registry_cache` was stored in a
+  class-level instance variable mutated without synchronisation, creating a race condition on
+  multi-threaded Puma servers. A `REGISTRY_CACHE_MUTEX = Mutex.new` constant now guards all reads
+  and writes to `@_registry_cache` via `REGISTRY_CACHE_MUTEX.synchronize`.
+  ([lib/pg_sql_triggers/registry/manager.rb](lib/pg_sql_triggers/registry/manager.rb))
+
+- **[Design] Configurable PostgreSQL schema** — Every SQL query in `Drift::DbQueries` hard-coded
+  `n.nspname = 'public'`, making the gem unusable in applications that manage triggers in
+  non-public schemas. A new configuration attribute `PgSqlTriggers.db_schema` (default: `"public"`)
+  replaces all hard-coded schema literals; the value is passed as a bind parameter via a private
+  `schema_name` helper. Override in an initialiser:
+  `PgSqlTriggers.db_schema = "app"`.
+  ([lib/pg_sql_triggers.rb](lib/pg_sql_triggers.rb),
+  [lib/pg_sql_triggers/drift/db_queries.rb](lib/pg_sql_triggers/drift/db_queries.rb))
+
+- **[Design] Idiomatic DSL accessor methods** — `TriggerDefinition#version`, `#enabled`, and
+  `#timing` used a dual-purpose getter/setter pattern (`def version(v = nil)`) that silently
+  returned the current value when called with no argument, making typos invisible. Replaced with
+  standard `attr_accessor :version, :enabled` and a custom `timing=(val)` writer that converts to
+  string, matching the Ruby/Rails `attr_accessor` convention. DSL block syntax changes from
+  `version 1` to `self.version = 1` and `enabled true` to `self.enabled = true`.
+  ([lib/pg_sql_triggers/dsl/trigger_definition.rb](lib/pg_sql_triggers/dsl/trigger_definition.rb))
+
+- **[Design] `capture_state` now includes `function_body`** — The audit snapshot captured by
+  `TriggerRegistry#capture_state` (used in before/after diffs for all audit log entries) omitted
+  `function_body`, making it impossible to see the actual function content in audit trail diffs.
+  The field is now included in all captured state hashes.
+  ([app/models/pg_sql_triggers/trigger_registry.rb](app/models/pg_sql_triggers/trigger_registry.rb))
+
+- **[Design 5.4] `Migrator#run_migration` reduced from three migration instances to two** —
+  `run_migration` previously instantiated the migration class three times: once for
+  `SafetyValidator`, once for `PreApplyComparator`, and once for actual execution. This meant
+  the migration code ran twice before execution, making the behaviour unpredictable if the
+  migration had side effects that escaped the `execute` override. A new private
+  `capture_migration_sql(instance, direction)` helper (wrapped in a rolled-back transaction)
+  captures SQL once from a single inspection instance. `SafetyValidator.validate_sql!` and
+  `PreApplyComparator.compare_sql` are new entry points that accept pre-captured SQL directly,
+  avoiding a second run of the migration code. Execution still uses a fresh instance. The
+  existing `validate!` and `compare` instance-based APIs are retained for backward compatibility
+  with specs.
+  ([lib/pg_sql_triggers/migrator.rb](lib/pg_sql_triggers/migrator.rb),
+  [lib/pg_sql_triggers/migrator/safety_validator.rb](lib/pg_sql_triggers/migrator/safety_validator.rb),
+  [lib/pg_sql_triggers/migrator/pre_apply_comparator.rb](lib/pg_sql_triggers/migrator/pre_apply_comparator.rb))
+
+### Deprecated
+
+- **`DSL::TriggerDefinition#when_env`** — Environment-specific trigger declarations cause schema
+  drift between environments and make triggers impossible to test fully outside production.
+  `when_env` now emits a `warn`-level deprecation message on every call and will be removed in a
+  future major version. Use application-level configuration to gate trigger behaviour by
+  environment instead.
+  ([lib/pg_sql_triggers/dsl/trigger_definition.rb](lib/pg_sql_triggers/dsl/trigger_definition.rb))
+
+### Removed
+
+- **[Refactor 5.3] Web UI trigger generator removed; replaced with Rails CLI generator** —
+  `GeneratorController` provided a browser form for generating trigger DSL files and migrations
+  at runtime, writing files directly to the server's filesystem. This is a security and
+  auditability concern in production (server-side file writes, no code review gate). The
+  controller, its two views (`new`, `preview`), the `/generator` routes, `Generator::Service`,
+  `Generator::Form`, and all related specs have been removed. Code generation is now a local,
+  CLI-driven action via a new `pg_sql_triggers:trigger` Rails generator:
+  ```
+  rails generate pg_sql_triggers:trigger TRIGGER_NAME TABLE_NAME [EVENTS...] [--timing before|after] [--function fn_name]
+  ```
+  The generator produces `app/triggers/TRIGGER_NAME.rb` (DSL stub) and
+  `db/triggers/TIMESTAMP_TRIGGER_NAME.rb` (migration with function + trigger SQL) directly into
+  the working tree, where they go through version control and code review like any other source
+  file. The `autoload :Generator` entry is also removed from `PgSqlTriggers`.
+  ([lib/generators/pg_sql_triggers/trigger_generator.rb](lib/generators/pg_sql_triggers/trigger_generator.rb),
+  [config/routes.rb](config/routes.rb))
+
+- **[Refactor 5.2] `SQL::Capsule` and `SQL::Executor` removed** — These classes implemented a
+  named-SQL-snippet execution system ("SQL capsules") for emergency operations. The feature is a
+  general-purpose dangerous-SQL runner that has nothing specifically to do with trigger management;
+  bundling it in this gem conflated concerns and enlarged the web UI's attack surface. Removed:
+  `lib/pg_sql_triggers/sql/capsule.rb`, `lib/pg_sql_triggers/sql/executor.rb`,
+  `app/controllers/pg_sql_triggers/sql_capsules_controller.rb`, the two associated views, the
+  `/sql_capsules` routes, and all related specs. `SQL::KillSwitch` is retained — it continues to
+  gate trigger re-execution and migration operations. The `PgSqlTriggers::SQL.execute_capsule`
+  convenience method is also removed.
+  ([lib/pg_sql_triggers/sql.rb](lib/pg_sql_triggers/sql.rb),
+  [config/routes.rb](config/routes.rb))
+
+- **Duplicate `trigger:migration` generator namespace** — Two generator namespaces existed for the
+  same task: `rails g pg_sql_triggers:trigger_migration` and `rails g trigger:migration`. The
+  `Trigger::Generators::MigrationGenerator` (`lib/generators/trigger/`) has been removed; use
+  `rails g pg_sql_triggers:trigger_migration` exclusively.
+  ([lib/generators/trigger/migration_generator.rb](lib/generators/trigger/migration_generator.rb))
+
+### Security
+
+- **[High] Production warning when no `permission_checker` is configured** — The gem's default
+  behaviour is to allow all actions (including admin-level operations such as `drop_trigger`,
+  `execute_sql`, and `override_drift`) when no `permission_checker` is set. A newly deployed
+  application with no extra configuration silently granted every actor full admin access.
+  The engine now emits a `Rails.logger.warn` at startup when the app boots in production and
+  `PgSqlTriggers.permission_checker` is still `nil`, making the misconfiguration visible in
+  production logs immediately on deploy.
+  ([lib/pg_sql_triggers/engine.rb](lib/pg_sql_triggers/engine.rb))
+
+- **[High] `Registry::Validator` was a no-op stub** — `Validator.validate!` returned `true`
+  unconditionally, meaning malformed DSL definitions (missing `table_name`, empty or invalid
+  `events`, missing `function_name`, unrecognised `timing` values) silently passed validation
+  and were written to the registry. Replaced the stub with real validation: every `source: "dsl"`
+  entry in the registry has its stored `definition` JSON parsed and checked against required
+  fields and allowed values (`insert / update / delete / truncate` for events;
+  `before / after / instead_of` for timing). All errors are collected across all triggers and
+  surfaced in a single `ValidationError` listing every violation. Non-DSL entries are not
+  validated. Unparseable JSON is treated as an empty definition, which itself fails validation.
+  ([lib/pg_sql_triggers/registry/validator.rb](lib/pg_sql_triggers/registry/validator.rb))
+
+### Fixed
+- **[High] `enabled: false` DSL option was cosmetic — trigger still fired in PostgreSQL** —
+  The `enabled` field was stored in the registry and surfaced in drift reports, but no
+  `ALTER TABLE … DISABLE TRIGGER` was ever issued across three code paths, so the trigger
+  continued to fire regardless of the DSL flag.
+
+  *Gap 1 — `Registry::Manager#register`*: A new private `sync_postgresql_enabled_state` helper
+  is called after every create or update that affects the `enabled` field. On **create**, the
+  helper fires only when `definition.enabled` is falsy (a newly created PostgreSQL trigger is
+  always enabled by default). On **update**, `enabled_changed` is captured before the `update!`
+  call so the comparison is always against the old value; the sync fires only when `enabled`
+  actually flipped. The helper checks `DatabaseIntrospection#trigger_exists?` before issuing
+  any SQL, making it safe to call at app boot before migrations have run, and rescues any error
+  with a `Rails.logger.warn` so a transient DB issue cannot crash the registration path.
+
+  *Gap 2 — `Migrator#run_migration` (`:up`)*: `CREATE TRIGGER` always leaves the trigger
+  enabled in PostgreSQL. A new private `enforce_disabled_triggers` method is called after each
+  `:up` migration transaction commits; it iterates over all `TriggerRegistry.disabled` entries
+  and issues `ALTER TABLE … DISABLE TRIGGER` for any that exist in the database. A per-iteration
+  `rescue` ensures one failure does not block the rest.
+
+  *Gap 3 — `TriggerRegistry#update_registry_after_re_execute`*: `re_execute!` drops and
+  recreates the trigger, leaving it always enabled in PostgreSQL. The method previously also
+  forced `enabled: true` into the registry `update!` call, overwriting any previously stored
+  `false` value. The `enabled: true` is removed from the `update!` so the stored state is
+  preserved; if `enabled` is `false`, an `ALTER TABLE … DISABLE TRIGGER` is issued immediately
+  after the registry update, within the same transaction.
+
+  Spec coverage added for all three gaps:
+  - `registry_spec.rb` — four cases in a new `"with PostgreSQL enabled state sync"` context:
+    create with `enabled: false` when trigger exists in DB, create when trigger not yet in DB
+    (no SQL, no error), update `true → false`, and update `false → true`.
+  - `trigger_registry_spec.rb` — new `"when registry entry has enabled: false"` context inside
+    `#re_execute!`: verifies `enabled` is not flipped to `true` and that `DISABLE TRIGGER` SQL
+    is issued after recreation.
+  - `migrator_spec.rb` — new `".run_migration with enforce_disabled_triggers"` describe block:
+    runs a real migration that creates a trigger, confirms `tgenabled = 'D'` in `pg_trigger`
+    afterward.
+
+  ([lib/pg_sql_triggers/registry/manager.rb](lib/pg_sql_triggers/registry/manager.rb),
+  [lib/pg_sql_triggers/migrator.rb](lib/pg_sql_triggers/migrator.rb),
+  [app/models/pg_sql_triggers/trigger_registry.rb](app/models/pg_sql_triggers/trigger_registry.rb),
+  [spec/pg_sql_triggers/registry_spec.rb](spec/pg_sql_triggers/registry_spec.rb),
+  [spec/pg_sql_triggers/trigger_registry_spec.rb](spec/pg_sql_triggers/trigger_registry_spec.rb),
+  [spec/pg_sql_triggers/migrator_spec.rb](spec/pg_sql_triggers/migrator_spec.rb))
+
+- **[Medium] `enabled` defaulted to `false` in the DSL** — Every newly declared trigger had
+  `@enabled = false`, meaning triggers were silently disabled unless the author explicitly added
+  `self.enabled = true`. Deployments that omitted the flag would register a disabled trigger that
+  appears in the registry but never fires, with no warning. Changed the default to `true` so
+  triggers are active unless explicitly disabled.
+  ([lib/pg_sql_triggers/dsl/trigger_definition.rb](lib/pg_sql_triggers/dsl/trigger_definition.rb))
+
+- **[Critical] Drift detector checksum excluded `timing` field** — `Drift::Detector#calculate_db_checksum`
+  was hashing without the `timing` attribute, while `TriggerRegistry#calculate_checksum` and
+  `Registry::Manager#calculate_checksum` both include it. Any trigger with a non-default timing
+  value (`"after"`) permanently showed as `DRIFTED` even when fully in sync.
+  ([lib/pg_sql_triggers/drift/detector.rb](lib/pg_sql_triggers/drift/detector.rb))
+
+- **[Critical] `extract_function_body` returned the full `CREATE FUNCTION` statement** —
+  `pg_get_functiondef()` returns the complete DDL including the `CREATE OR REPLACE FUNCTION`
+  header and language clause. The detector was hashing that entire string while the registry
+  stores only the PL/pgSQL body, so checksums never matched and every trigger appeared `DRIFTED`.
+  Fixed by extracting only the content between dollar-quote delimiters (`$$` / `$function$`).
+  ([lib/pg_sql_triggers/drift/detector.rb](lib/pg_sql_triggers/drift/detector.rb))
+
+- **[Critical] DSL triggers stored `"placeholder"` as checksum causing permanent false drift** —
+  `Registry::Manager#calculate_checksum` returned the literal string `"placeholder"` whenever
+  `function_body` was blank (the normal case for DSL-defined triggers). The drift detector then
+  computed a real SHA256 hash and compared it to `"placeholder"`, so all DSL triggers always
+  appeared `DRIFTED`. Fixed by computing a real checksum using `""` for `function_body`, and
+  teaching the detector to also use `""` for `function_body` when the registry source is `"dsl"`.
+  ([lib/pg_sql_triggers/registry/manager.rb](lib/pg_sql_triggers/registry/manager.rb),
+  [lib/pg_sql_triggers/drift/detector.rb](lib/pg_sql_triggers/drift/detector.rb))
+
+- **[Critical] `re_execute!` always raised for DSL-defined triggers** —
+  `TriggerRegistry#re_execute!` raised `StandardError` immediately when `function_body` was
+  blank, which is always the case for DSL triggers (the primary use path). Added a
+  `build_trigger_sql_from_definition` private helper that reconstructs a valid `CREATE TRIGGER`
+  SQL statement from the stored DSL definition JSON (`function_name`, `timing`, `events`,
+  `condition`). `re_execute!` now falls back to this reconstructed SQL when `function_body` is
+  absent, making the method functional for DSL triggers.
+  ([app/models/pg_sql_triggers/trigger_registry.rb](app/models/pg_sql_triggers/trigger_registry.rb))
+
+- **[High] `SafetyValidator#capture_sql` executed migration side effects during capture** —
+  `capture_sql` monkey-patched only the `execute` method, so any ActiveRecord migration helpers
+  (`add_column`, `create_table`, etc.) called by the migration ran for real as a side effect of
+  the safety check. Wrapped the migration invocation in
+  `ActiveRecord::Base.transaction { …; raise ActiveRecord::Rollback }` so all schema changes
+  are rolled back after SQL capture.
+  ([lib/pg_sql_triggers/migrator/safety_validator.rb](lib/pg_sql_triggers/migrator/safety_validator.rb))
+
+- **[Low] Dead `trigger_name` expression in `drop!`** — A bare `trigger_name` expression inside
+  the `drop!` transaction block was a no-op whose return value was silently discarded. Removed.
+  ([app/models/pg_sql_triggers/trigger_registry.rb](app/models/pg_sql_triggers/trigger_registry.rb))
 
 ## [1.3.0] - 2026-01-05
 

data/GEM_ANALYSIS.md

@@ -0,0 +1,368 @@
+# pg_sql_triggers — Gem Analysis
+
+> Analysed against version **1.3.0** · February 2026
+
+---
+
+## Table of Contents
+1. [Critical Bugs](#1-critical-bugs)
+2. [Design Issues](#2-design-issues)
+3. [Security Concerns](#3-security-concerns)
+4. [Missing Features](#4-missing-features)
+5. [Unnecessary / Over-engineered Features](#5-unnecessary--over-engineered-features)
+6. [Low-coverage Hotspots](#6-low-coverage-hotspots)
+7. [Summary Table](#7-summary-table)
+
+---
+
+## 1. Critical Bugs
+
+### 1.1 Checksum Algorithm Is Inconsistent — Will Always Report False Drift
+
+Three places compute a trigger checksum. They use different field sets:
+
+| Location | Fields included |
+|---|---|
+| `TriggerRegistry#calculate_checksum` | `trigger_name, table_name, version, function_body, condition, timing` |
+| `Registry::Manager#calculate_checksum` | `name, table_name, version, function_body, condition, timing` |
+| `Drift::Detector#calculate_db_checksum` | `trigger_name, table_name, version, function_body, condition` ← **missing `timing`** |
+
+Because the registry stores a checksum that includes `timing`, but the drift detector recomputes the checksum without `timing`, **every trigger that has a non-default timing value will permanently show as `DRIFTED`** even when fully in sync.
+
+Files:
+- [lib/pg_sql_triggers/drift/detector.rb:88-103](lib/pg_sql_triggers/drift/detector.rb#L88-L103)
+- [app/models/pg_sql_triggers/trigger_registry.rb:318-327](app/models/pg_sql_triggers/trigger_registry.rb#L318-L327)
+- [lib/pg_sql_triggers/registry/manager.rb:129-145](lib/pg_sql_triggers/registry/manager.rb#L129-L145)
+
+---
+
+### 1.2 `extract_function_body` Returns the Full `CREATE FUNCTION` Statement
+
+`Detector#extract_function_body` returns `function_def` unchanged — the full output of `pg_get_functiondef()`, including the `CREATE OR REPLACE FUNCTION` header. The registry stores only the PL/pgSQL body. These two strings will never match, so **the drift detector will report every trigger as DRIFTED regardless of actual state**.
+
+```ruby
+# lib/pg_sql_triggers/drift/detector.rb:106-114
+def extract_function_body(db_trigger)
+  function_def = db_trigger["function_definition"]
+  return nil unless function_def
+
+  # TODO: Parse and extract just the body if needed
+  function_def  # ← returns entire CREATE FUNCTION definition
+end
+```
+
+The `# TODO` comment confirms this is incomplete.
+
+---
+
+### 1.3 DSL Triggers Store `"placeholder"` as Checksum → Permanent False Drift
+
+When a DSL trigger definition has no `function_body` (which is the normal case — `TriggerDefinition#function_body` always returns `nil`), `Manager#calculate_checksum` detects `function_body_value.blank?` and stores the literal string `"placeholder"` in the registry. The drift detector then computes a real SHA256 hash from the database and compares it to `"placeholder"`, so **all DSL-defined triggers always appear DRIFTED**.
+
+```ruby
+# lib/pg_sql_triggers/registry/manager.rb:133
+return "placeholder" if function_body_value.blank?
+```
+
+---
+
+### 1.4 `re_execute!` Is Broken for All DSL-Defined Triggers
+
+`TriggerRegistry#re_execute!` raises immediately if `function_body` is blank:
+
+```ruby
+raise StandardError, "Cannot re-execute: missing function_body" if function_body.blank?
+```
+
+Since `TriggerDefinition#function_body` always returns `nil`, DSL-defined triggers (the primary usage path) can **never be re-executed** through this method. The method is effectively dead for the main use case.
+
+File: [app/models/pg_sql_triggers/trigger_registry.rb:289](app/models/pg_sql_triggers/trigger_registry.rb#L289)
+
+---
+
+### 1.5 `SafetyValidator#capture_sql` Actually Executes the Migration
+
+The safety validator captures SQL by monkey-patching the instance's `execute` method, then calling the migration's `up`/`down` method:
+
+```ruby
+# lib/pg_sql_triggers/migrator/safety_validator.rb:57-68
+def capture_sql(migration_instance, direction)
+  captured = []
+  migration_instance.define_singleton_method(:execute) do |sql|
+    captured << sql.to_s.strip
+  end
+  migration_instance.public_send(direction)  # ← runs the migration method
+  captured
+end
+```
+
+If the migration does anything other than call `execute` (e.g. calls `add_column`, `create_table`, or any other ActiveRecord migration helper), those side effects run for real during the safety check. Then `run_migration` creates two more instances and runs them again — meaning a single migration run can execute the migration's code path **three times**.
+
+---
+
+### 1.6 Dead Code in `drop!`
+
+Inside `drop!`, there is a bare expression `trigger_name` on its own line that does nothing:
+
+```ruby
+# app/models/pg_sql_triggers/trigger_registry.rb:249-251
+ActiveRecord::Base.transaction do
+  drop_trigger_from_database
+  trigger_name   # ← no-op; return value is discarded
+  destroy!
+```
+
+This is likely a leftover from an assignment like `name = trigger_name` that was refactored away.
+
+---
+
+## 2. Design Issues
+
+### 2.1 N+1 Queries in All Drift Registry Methods
+
+`Registry::Manager#drifted`, `#in_sync`, `#unknown_triggers`, and `#dropped` all call `Drift::Detector.detect_all`, which loops over every registry entry and calls `detect(entry.trigger_name)` per entry. Each `detect` call performs `TriggerRegistry.find_by(trigger_name:)` — an individual SQL query. For N triggers, this is N+1 queries.
+
+```ruby
+# lib/pg_sql_triggers/drift/detector.rb:38-56
+def detect_all
+  registry_entries = TriggerRegistry.all.to_a   # 1 query
+  db_triggers = DbQueries.all_triggers           # 1 query
+  results = registry_entries.map do |entry|
+    detect(entry.trigger_name)                   # 1 query per entry ← N+1
+  end
+```
+
+---
+
+### 2.2 Class-Level Cache Is Not Thread-Safe
+
+`Registry::Manager._registry_cache` is stored in a class-level instance variable (`@_registry_cache`). In a multi-threaded Puma server, concurrent requests share and mutate this hash without synchronisation, creating a potential race condition where one thread's cache write corrupts another thread's lookup.
+
+File: [lib/pg_sql_triggers/registry/manager.rb:9-15](lib/pg_sql_triggers/registry/manager.rb#L9-L15)
+
+---
+
+### 2.3 `DbQueries` Hard-Codes the `public` Schema
+
+Every SQL query filters `n.nspname = 'public'`. Applications using non-public schemas (multi-tenant schemas, `app`, `audit`, etc.) cannot use this gem at all.
+
+File: [lib/pg_sql_triggers/drift/db_queries.rb](lib/pg_sql_triggers/drift/db_queries.rb) — lines 27, 51, 78, 93
+
+---
+
+### 2.4 `when_env` DSL Option Is an Anti-Pattern
+
+The DSL supports environment-specific triggers:
+
+```ruby
+PgSqlTriggers::DSL.pg_sql_trigger "users_email_validation" do
+  when_env :production
+end
+```
+
+Having triggers that exist only in production but not in staging or development makes it impossible to test them fully. Schema drift between environments is guaranteed and bugs will only surface in production. Environment-specific behavior belongs in configuration, not in trigger definitions.
+
+---
+
+### 2.5 Dual Generator Paths Create Ambiguity
+
+Two separate generator namespaces exist for the same task:
+
+- `lib/generators/pg_sql_triggers/trigger_migration_generator.rb` → invoked with `rails g pg_sql_triggers:trigger_migration`
+- `lib/generators/trigger/migration_generator.rb` → invoked with `rails g trigger:migration`
+
+There is no documentation explaining which to prefer, and having both increases maintenance surface without benefit.
+
+---
+
+### 2.6 `capture_state` Does Not Include `function_body`
+
+The audit log state snapshot captures `enabled`, `version`, `checksum`, `table_name`, `source`, `environment`, and `installed_at` — but not `function_body`. Diffs recorded in audit logs will not show what the function body was before/after an operation, making the audit trail incomplete for the most important change: the function itself.
+
+File: [app/models/pg_sql_triggers/trigger_registry.rb:414-424](app/models/pg_sql_triggers/trigger_registry.rb#L414-L424)
+
+---
+
+### 2.7 `enabled` and `version` Use Non-Idiomatic Dual-Purpose Methods in DSL
+
+```ruby
+def version(version = nil)
+  if version.nil?
+    @version
+  else
+    @version = version
+  end
+end
+```
+
+Ruby DSLs conventionally use `attr_accessor` for simple getters/setters or separate `def version=(v)` / `def version` methods. The current pattern is confusing because calling `version` with no arguments returns the current value rather than raising `ArgumentError`, making typos silent.
+
+---
+
+## 3. Security Concerns
+
+### 3.1 Default Permissions Allow Everything
+
+`Permissions::Checker#can?` returns `true` for all actors and all actions when no `permission_checker` is configured:
+
+```ruby
+# lib/pg_sql_triggers/permissions/checker.rb:16-17
+# Default behavior: allow all permissions
+true
+```
+
+A newly installed gem with no extra configuration grants every user full ADMIN access (including `drop_trigger`, `execute_sql`, `override_drift`). The comment says "This should be overridden in production via configuration", but there is no warning in the initializer or README to flag this as a critical step before go-live.
+
+---
+
+### 3.2 `Registry::Validator` Is a No-Op
+
+The validator that should catch invalid DSL definitions before they are registered is a stub that always returns `true`:
+
+```ruby
+# lib/pg_sql_triggers/registry/validator.rb:7-11
+def self.validate!
+  # This is a placeholder implementation
+  true
+end
+```
+
+Its test confirms only that it returns `true`. No actual validation (duplicate names, missing table, invalid events, etc.) occurs. Malformed definitions silently pass.
+
+---
+
+## 4. Missing Features
+
+### 4.1 No `FOR EACH ROW` / `FOR EACH STATEMENT` DSL Support
+
+PostgreSQL requires every trigger to specify row-level or statement-level execution. The gem's DSL has no `row_level` or `statement_level` option. The generated SQL presumably hard-codes one, but users have no way to choose.
+
+### 4.2 No Multi-Schema Support
+
+As noted in §2.3, the entire introspection layer is hard-coded to the `public` schema. There is no `schema` DSL option, no configuration for a default schema, and no way to manage triggers in non-public schemas.
+
+### 4.3 No Column-Level Trigger Support (`OF column_name`)
+
+PostgreSQL `UPDATE OF col1, col2` triggers (which fire only when specific columns change) are not representable in the DSL. This is a common performance optimisation for audit triggers.
+
+### 4.4 No Deferred Trigger Support
+
+The DSL provides no way to declare `DEFERRABLE INITIALLY DEFERRED` or `DEFERRABLE INITIALLY IMMEDIATE` triggers, which are essential for some referential integrity patterns.
+
+### 4.5 No `schema.rb` / `structure.sql` Integration
+
+Trigger definitions are managed in a separate `db/triggers/` migration system that is invisible to `rails db:schema:dump`. Restoring a database from `schema.rb` will not recreate triggers. The gem should hook into Rails' structure dump (or document clearly that `structure.sql` must be used and provide a rake task to populate it).
+
+### 4.6 No External Alerting for Drift
+
+Drift detection runs on demand (web UI check or API call) but there is no mechanism to push alerts to Slack, PagerDuty, or email when drift is detected. A cron-triggered rake task with configurable notification hooks would make this production-ready.
+
+### 4.7 No Search or Filter in the Web UI
+
+The dashboard and trigger list pages have no search, filter by table, filter by drift state, or pagination. At scale (many triggers), the UI becomes unwieldy.
+
+### 4.8 No Trigger Dependency or Ordering Declaration
+
+When multiple triggers fire on the same event for the same table, PostgreSQL fires them in alphabetical order by name. There is no DSL primitive to declare intended ordering or express that trigger A must run before trigger B.
+
+### 4.9 No Export / Import of Trigger Definitions
+
+There is no way to export the current state of all triggers to a portable format (JSON, YAML) or import definitions from another project. This makes it hard to migrate or share trigger libraries between applications.
+
+---
+
+## 5. Unnecessary / Over-engineered Features
+
+### 5.1 `SQL::KillSwitch` Is ~1,200 Lines for a Three-Layer Check
+
+The kill switch provides three layers of protection (config, ENV override, confirmation text). The core logic is straightforward, but the module spans over 1,200 lines. Much of this length is verbose logging, repeated helper methods, and defensive checks that could be reduced to ~100 lines without losing functionality. The complexity also means it accounts for 96% of its own test coverage (4% uncovered in a safety-critical module).
+
+### 5.2 SQL Capsules Are a Separate Concern
+
+`SQL::Capsule` and `SQL::Executor` implement a named-SQL-snippet execution system for "emergency operations". This is a useful concept, but it has nothing specifically to do with trigger management — it is a general-purpose dangerous-SQL runner. Bundling it in this gem conflates concerns and increases the attack surface of the gem's web UI.
+
+### 5.3 Web UI Generator Is Code-Generation Against the Principle of Code-First
+
+The `GeneratorController` provides a browser form for generating trigger DSL files and migrations. In practice, triggers are infrastructure — they should be authored in code review, not through a web UI. The UI generator produces files on disk on the server at runtime, which is a security and auditability concern in production environments.
+
+**Recommendation:** Apply options A + C together.
+
+1. **Immediately restrict routes to dev/test** (one-liner, no behaviour change in production):
+   ```ruby
+   # config/routes.rb
+   if Rails.env.development? || Rails.env.test?
+     mount PgSqlTriggers::Engine => "/pg_sql_triggers"
+   end
+   ```
+
+2. **Replace the web generator with a Rails generator** so code generation is a local, CLI-driven action that produces files that go straight into version control:
+   ```bash
+   rails generate pg_sql_triggers:trigger users after_insert
+   ```
+   Once the Rails generator exists, the `GeneratorController` routes and views can be removed entirely. This is the idiomatic Rails pattern and eliminates server-side file writes at runtime.
+
+### 5.4 Three Migration Instances Per Migration Run
+
+`Migrator#run_migration` instantiates the migration class three separate times:
+1. `validation_instance` — for `SafetyValidator` (which calls `direction` on it)
+2. `comparison_instance` — for `PreApplyComparator`
+3. `migration_instance` — for actual execution
+
+If either the safety validator or comparator raises a non-`StandardError` or has side effects, the behaviour is unpredictable. A single instance should be captured once for SQL inspection, then a clean instance used for execution.
+
+### 5.5 `enabled` Defaults to `false` in the DSL
+
+The DSL initialises `@enabled = false`, meaning every newly declared trigger is disabled by default. This is a surprising default — users who forget to add `enabled true` will deploy triggers that silently do nothing, with no warning.
+
+```ruby
+# lib/pg_sql_triggers/dsl/trigger_definition.rb:12
+@enabled = false
+```
+
+---
+
+## 6. Low-coverage Hotspots
+
+| File | Coverage | Risk |
+|---|---|---|
+| `config/routes.rb` | 12% | Route misconfiguration goes undetected |
+| `migrations_controller.rb` | 82.76% | Error paths in the most dangerous controller |
+| `permission_checking.rb` | 85.37% | Security-critical concern with gaps |
+| `testing/function_tester.rb` | 89.71% | Testing utilities that are themselves untested |
+| `sql/kill_switch.rb` | 96.04% | Safety mechanism with 4% uncovered paths |
+
+---
+
+## 7. Summary Table
+
+| # | Category | Severity | Description |
+|---|---|---|---|
+| 1.1 | Bug | **Critical** | Checksum algorithm omits `timing` in drift detector — false drift always reported |
+| 1.2 | Bug | **Critical** | `extract_function_body` returns full `CREATE FUNCTION` SQL — checksum never matches |
+| 1.3 | Bug | **Critical** | DSL triggers store `"placeholder"` checksum — always shows as DRIFTED |
+| 1.4 | Bug | **Critical** | `re_execute!` always raises for DSL triggers — feature is broken for primary use case |
+| 1.5 | Bug | **High** | `SafetyValidator` executes migration code as side effect of capture |
+| 1.6 | Bug | **Low** | Dead `trigger_name` expression in `drop!` |
+| 2.1 | Design | **High** | N+1 queries in all drift state filter methods |
+| 2.2 | Design | **High** | Class-level registry cache is not thread-safe |
+| 2.3 | Design | **High** | Hard-coded `public` schema — multi-schema apps unsupported |
+| 2.4 | Design | **Medium** | `when_env` DSL anti-pattern guarantees env drift |
+| 2.5 | Design | **Low** | Duplicate generator namespaces with no guidance |
+| 2.6 | Design | **Medium** | Audit state snapshot omits `function_body` |
+| 2.7 | Design | **Low** | Non-idiomatic dual-purpose DSL methods |
+| 3.1 | Security | **High** | Default permissions allow all actions — no safe default |
+| 3.2 | Security | **High** | `Registry::Validator` is a stub that accepts any input |
+| 4.1 | Missing | **High** | No `FOR EACH ROW` / `FOR EACH STATEMENT` DSL option |
+| 4.2 | Missing | **High** | No multi-schema support |
+| 4.3 | Missing | **Medium** | No column-level trigger (`UPDATE OF col`) |
+| 4.4 | Missing | **Medium** | No deferred trigger support |
+| 4.5 | Missing | **High** | No `schema.rb` / `structure.sql` integration |
+| 4.6 | Missing | **Medium** | No external alerting for detected drift |
+| 4.7 | Missing | **Low** | No search/filter in web UI |
+| 4.8 | Missing | **Low** | No trigger ordering or dependency declaration |
+| 4.9 | Missing | **Low** | No export/import of trigger definitions |
+| 5.1 | Unnecessary | **Low** | Kill switch is ~1,200 lines for a 3-layer check |
+| 5.2 | Unnecessary | **Medium** | SQL Capsules are an unrelated concern bundled in the gem |
+| 5.3 | Unnecessary | **Medium** | Web UI generator creates files on production server |
+| 5.4 | Unnecessary | **Medium** | Three migration instances per run (safety + compare + execute) |
+| 5.5 | Unnecessary | **Medium** | `enabled false` default silently disables triggers in production |