pg_sql_triggers 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f8d9043692145293beaf91342280ca01702979a6e50190fd5930d8578170291
-  data.tar.gz: 18e9eaaa03de9932f9916bcc2110e9896a271c555a3b94f13348baf1e37c584c
+  metadata.gz: 7adcec137e32ecf9e1013a7dbb98a16844a5f8082b0d910a7380903cd2151678
+  data.tar.gz: b285ecac25cf7806a56f0205fca527a158b48c7f26b99adb4c1c304b3b2d17d7
 SHA512:
-  metadata.gz: 8ed71a10f16385f318a4a596a444c07d2cb00a7d07119043c921cf43b1d2199db6d36cc30b5ea523bcbb527a817b97fbe7c507ac81a4cec3931f887c2a4606ca
-  data.tar.gz: af0162bab6005904e1649619e5a68e1c1f36733e4f8d34f0306c9a64af07356e9f19165dda1a60f19606b36b517ee1ad34224a50b479b02b0b8efd340175f1fc
+  metadata.gz: 0aeb0cb7beee89da7f9c8993fd166b569c4cacb684e1b82222c104d083c970b9878da4ae368449aeeda63839c991522148e6dc4996c0ffce79ca04e49063b1e0
+  data.tar.gz: 0d0034cf4c0ee07dc9f868fa44924a9fd737861ac1d067c67b189ae5f08172af8f9596fc625b029f5dce8d36fe00ec287e0bbb2ace5a4725ce43eabdfe66907a

data/.rubocop.yml

@@ -1,9 +1,7 @@
-require:
-  - rubocop-rspec
-  - rubocop-rspec_rails
-
 plugins:
   - rubocop-rails
+  - rubocop-rspec
+  - rubocop-rspec_rails
   - rubocop-capybara
   - rubocop-factory_bot
 
@@ -24,18 +22,14 @@ 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:
@@ -44,21 +38,17 @@ Metrics/ClassLength:
 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
@@ -97,9 +87,6 @@ RSpec/ExampleLength:
   Exclude:
     - 'spec/**/*_spec.rb'
 
-RSpec/FilePath:
-  Enabled: false
-
 RSpec/InstanceVariable:
   Enabled: false
 
@@ -115,6 +102,9 @@ RSpec/MultipleDescribes:
 RSpec/MultipleExpectations:
   Max: 10
 
+RSpec/MultipleMemoizedHelpers:
+  Max: 8
+
 RSpec/SpecFilePathFormat:
   Enabled: false
 

data/AGENTS.md

@@ -0,0 +1,8 @@
+# Agent / contributor notes
+
+## This repository
+
+- Run Ruby tooling (**bundle**, **rubocop**, **rspec**) via **WSL** with **asdf** (use a login shell, e.g. `wsl bash -lic '…'`).
+- **PostgreSQL** is expected in **Docker**; for local tests use **`aswin` / `aswin`** (`TEST_DB_USER`, `TEST_DB_PASSWORD`, or `DATABASE_URL` as appropriate).
+
+More detail and example commands: `.cursor/rules/dev-environment.mdc`.

data/CHANGELOG.md

@@ -7,6 +7,360 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+No changes yet.
+
+## [1.5.0] - 2026-04-15
+
+These notes follow the phased gap analysis in [`IMPLEMENTATION_PLAN.md`](IMPLEMENTATION_PLAN.md)
+(baseline **v1.4.0**). This release ships Phase 0 cleanup, Phase 1 routing-test hardening,
+Phase 2 production readiness (drift alerting, dashboard search/filter/pagination), Phase 3
+PostgreSQL feature parity (column-level `UPDATE OF`, constraint triggers with deferral,
+`schema.rb` / `structure.sql` integration), and Phase 4 trigger ordering hints.
+
+### Added
+
+- **Drift alerting** — Configurable `PgSqlTriggers.drift_notifier` for external notification when
+  drift detection finds drifted, dropped, or unknown triggers; `PgSqlTriggers::Alerting` module;
+  `PgSqlTriggers::Drift.check_and_notify`; Rake task `trigger:check_drift` with optional
+  `FAIL_ON_DRIFT=1`; `ActiveSupport::Notifications` event `pg_sql_triggers.drift_check`.
+  The gem’s root `Rakefile` loads `rakelib/pg_sql_triggers_environment.rake` and
+  `lib/tasks/trigger_migrations.rake` so `bundle exec rake trigger:*` works when developing the
+  gem (not only from a host app).
+  ([lib/pg_sql_triggers/alerting.rb](lib/pg_sql_triggers/alerting.rb),
+  [lib/tasks/trigger_migrations.rake](lib/tasks/trigger_migrations.rake),
+  [lib/pg_sql_triggers/rake_development_boot.rb](lib/pg_sql_triggers/rake_development_boot.rb),
+  [docs/configuration.md](docs/configuration.md))
+
+- **Column-level `UPDATE OF` triggers** — DSL method `on_update_of(*columns)` sets the event to
+  `update` and records column names; SQL generation and checksums use `EventsChecksum` so
+  `UPDATE OF "col1", "col2"` is represented consistently in drift detection. Registry validation
+  rejects column lists unless an update event is present.
+  ([lib/pg_sql_triggers/dsl/trigger_definition.rb](lib/pg_sql_triggers/dsl/trigger_definition.rb),
+  [lib/pg_sql_triggers/events_checksum.rb](lib/pg_sql_triggers/events_checksum.rb),
+  [lib/pg_sql_triggers/registry/validator.rb](lib/pg_sql_triggers/registry/validator.rb))
+
+- **Constraint triggers and deferral** — DSL supports `constraint_trigger!` with `deferrable` /
+  `initially` (constraint triggers only). Registry migration
+  `20260412185841_add_constraint_deferral_to_pg_sql_triggers_registry.rb` adds `constraint_trigger`,
+  `deferrable`, and `initially` columns. Validator and drift checksum paths normalize deferral using
+  catalog fields such as `tgdeferrable` / `tginitdeferred` where applicable.
+  ([db/migrate/20260412185841_add_constraint_deferral_to_pg_sql_triggers_registry.rb](db/migrate/20260412185841_add_constraint_deferral_to_pg_sql_triggers_registry.rb),
+  [lib/pg_sql_triggers/dsl/trigger_definition.rb](lib/pg_sql_triggers/dsl/trigger_definition.rb),
+  [lib/pg_sql_triggers/registry/validator.rb](lib/pg_sql_triggers/registry/validator.rb))
+
+- **Trigger ordering hints (`depends_on`)** — Optional `depends_on(*names)` on the DSL records
+  intended ordering relative to PostgreSQL’s alphabetical firing order. `Registry::Validator` checks
+  same-table scope, timing/`FOR EACH` consistency, absence of cycles, and name ordering; Rake task
+  `trigger:validate_order` runs the same rules from the CLI.
+  ([lib/pg_sql_triggers/dsl/trigger_definition.rb](lib/pg_sql_triggers/dsl/trigger_definition.rb),
+  [lib/pg_sql_triggers/registry/validator.rb](lib/pg_sql_triggers/registry/validator.rb),
+  [lib/tasks/trigger_migrations.rake](lib/tasks/trigger_migrations.rake))
+
+- **Dashboard search, filters, and pagination** — Trigger index supports query parameters
+  (`table`, `state`, `source`, `q`) with offset/limit pagination for large registries.
+  ([app/controllers/pg_sql_triggers/dashboard_controller.rb](app/controllers/pg_sql_triggers/dashboard_controller.rb))
+
+- **`schema.rb` awareness and trigger SQL snapshots** — `ActiveRecord::SchemaDumper` is prepended
+  with `SchemaDumperExtension` to append optional comments pointing at trigger workflows when
+  `PgSqlTriggers.append_trigger_notes_to_schema_dump` is true (default). Rake tasks `trigger:dump`
+  and `trigger:load` round-trip `db/trigger_structure.sql` via `TriggerStructureDumper`; path is
+  configurable with `PgSqlTriggers.trigger_structure_sql_path`. When
+  `PgSqlTriggers.migrate_triggers_after_schema_load` is true (default), `db:schema:load` can chain
+  to `trigger:migrate` (skippable with `SKIP_TRIGGER_MIGRATE_AFTER_SCHEMA_LOAD`).
+  ([lib/pg_sql_triggers/schema_dumper_extension.rb](lib/pg_sql_triggers/schema_dumper_extension.rb),
+  [lib/pg_sql_triggers/trigger_structure_dumper.rb](lib/pg_sql_triggers/trigger_structure_dumper.rb),
+  [lib/pg_sql_triggers/engine.rb](lib/pg_sql_triggers/engine.rb),
+  [lib/tasks/trigger_migrations.rake](lib/tasks/trigger_migrations.rake),
+  [lib/pg_sql_triggers.rb](lib/pg_sql_triggers.rb))
+
+- **Engine routing coverage** — Declarative routing specs for the mountable engine.
+  ([spec/routing/pg_sql_triggers_routes_spec.rb](spec/routing/pg_sql_triggers_routes_spec.rb))
+
+### Changed
+
+- **SQL permission helper naming** — View and controller helpers use `can_execute_sql_operations?`
+  instead of capsule-era `can_execute_sql?`, with comments aligned to migration-style SQL execution.
+  ([app/helpers/pg_sql_triggers/permissions_helper.rb](app/helpers/pg_sql_triggers/permissions_helper.rb),
+  [app/controllers/concerns/pg_sql_triggers/permission_checking.rb](app/controllers/concerns/pg_sql_triggers/permission_checking.rb))
+
+- **`TriggerRegistry#recreate_trigger`** — Uses an explicit `source == "dsl"` branch before the
+  `function_body` path so DSL re-execution is obvious to readers.
+  ([app/models/pg_sql_triggers/trigger_registry.rb](app/models/pg_sql_triggers/trigger_registry.rb))
+
+### Fixed
+
+- **`can_generate_triggers?` permission alignment** — Helper and concern both use the
+  `:generate_trigger` action so UI and controller authorization stay consistent.
+  ([app/helpers/pg_sql_triggers/permissions_helper.rb](app/helpers/pg_sql_triggers/permissions_helper.rb),
+  [app/controllers/concerns/pg_sql_triggers/permission_checking.rb](app/controllers/concerns/pg_sql_triggers/permission_checking.rb))
+
+### Planned
+
+- **Documentation accuracy** — Regenerate [`COVERAGE.md`](COVERAGE.md) from the current tree with
+  SimpleCov (plan §1.1); keep user-facing docs in sync with removed v1.4.0 features where files
+  still exist.
+
+- **Test hardening** — Additional request/controller specs for migration error paths and
+  permission edge cases (plan §4.2–4.3); extend coverage for notifier and dashboard filter
+  behaviour where gaps remain (plan Phase 1–2).
+
+- **Optional (Phase 4)** — Kill-switch time-window auto-lock; trigger definition export/import
+  (JSON/YAML) and related Rake tasks.
+
+## [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 `20260228162233_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/20260228162233_add_for_each_to_pg_sql_triggers_registry.rb](db/migrate/20260228162233_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
 
 ### Added

data/COVERAGE.md

@@ -1,8 +1,8 @@
 # Code Coverage Report
 
-**Total Coverage: 95.99%**
+**Total Coverage: 96.04%**
 
-Covered: 2319 / 2416 lines
+Covered: 2499 / 2602 lines
 
 ---
 
@@ -10,58 +10,56 @@ Covered: 2319 / 2416 lines
 
 | File | Coverage | Covered Lines | Missed Lines | Total Lines |
 |------|----------|---------------|--------------|-------------|
-| `lib/pg_sql_triggers/drift.rb` | 100.0% ✅ | 13 | 0 | 13 |
-| `lib/pg_sql_triggers/drift/db_queries.rb` | 100.0% ✅ | 24 | 0 | 24 |
-| `lib/pg_sql_triggers/dsl.rb` | 100.0% ✅ | 9 | 0 | 9 |
-| `lib/pg_sql_triggers/dsl/trigger_definition.rb` | 100.0% ✅ | 37 | 0 | 37 |
-| `lib/pg_sql_triggers/generator.rb` | 100.0% ✅ | 4 | 0 | 4 |
-| `lib/pg_sql_triggers/generator/form.rb` | 100.0% ✅ | 36 | 0 | 36 |
-| `lib/pg_sql_triggers/generator/service.rb` | 100.0% ✅ | 101 | 0 | 101 |
-| `lib/generators/pg_sql_triggers/install_generator.rb` | 100.0% ✅ | 18 | 0 | 18 |
-| `lib/generators/trigger/migration_generator.rb` | 100.0% ✅ | 27 | 0 | 27 |
 | `lib/pg_sql_triggers/migration.rb` | 100.0% ✅ | 4 | 0 | 4 |
+| `lib/pg_sql_triggers/migrator/pre_apply_comparator.rb` | 100.0% ✅ | 125 | 0 | 125 |
+| `lib/generators/pg_sql_triggers/install_generator.rb` | 100.0% ✅ | 18 | 0 | 18 |
+| `lib/pg_sql_triggers/dsl/trigger_definition.rb` | 100.0% ✅ | 60 | 0 | 60 |
+| `lib/pg_sql_triggers/dsl.rb` | 100.0% ✅ | 9 | 0 | 9 |
 | `lib/pg_sql_triggers/migrator/pre_apply_diff_reporter.rb` | 100.0% ✅ | 75 | 0 | 75 |
-| `lib/pg_sql_triggers/migrator/safety_validator.rb` | 100.0% ✅ | 110 | 0 | 110 |
+| `lib/pg_sql_triggers/sql.rb` | 100.0% ✅ | 7 | 0 | 7 |
+| `lib/pg_sql_triggers/migrator/safety_validator.rb` | 100.0% ✅ | 120 | 0 | 120 |
+| `lib/pg_sql_triggers/drift.rb` | 100.0% ✅ | 15 | 0 | 15 |
 | `lib/pg_sql_triggers/permissions.rb` | 100.0% ✅ | 11 | 0 | 11 |
-| `lib/pg_sql_triggers/permissions/checker.rb` | 100.0% ✅ | 17 | 0 | 17 |
-| `lib/pg_sql_triggers/registry/validator.rb` | 100.0% ✅ | 5 | 0 | 5 |
-| `lib/pg_sql_triggers/sql/capsule.rb` | 100.0% ✅ | 28 | 0 | 28 |
-| `lib/pg_sql_triggers/sql/executor.rb` | 100.0% ✅ | 63 | 0 | 63 |
-| `lib/pg_sql_triggers/testing.rb` | 100.0% ✅ | 6 | 0 | 6 |
-| `lib/pg_sql_triggers/testing/syntax_validator.rb` | 100.0% ✅ | 58 | 0 | 58 |
+| `lib/pg_sql_triggers/permissions/checker.rb` | 100.0% ✅ | 16 | 0 | 16 |
+| `app/controllers/pg_sql_triggers/triggers_controller.rb` | 100.0% ✅ | 76 | 0 | 76 |
+| `app/helpers/pg_sql_triggers/dashboard_helper.rb` | 100.0% ✅ | 7 | 0 | 7 |
+| `app/controllers/pg_sql_triggers/dashboard_controller.rb` | 100.0% ✅ | 72 | 0 | 72 |
+| `lib/pg_sql_triggers.rb` | 100.0% ✅ | 51 | 0 | 51 |
+| `lib/pg_sql_triggers/errors.rb` | 100.0% ✅ | 83 | 0 | 83 |
 | `lib/pg_sql_triggers/testing/dry_run.rb` | 100.0% ✅ | 24 | 0 | 24 |
-| `app/models/pg_sql_triggers/audit_log.rb` | 100.0% ✅ | 28 | 0 | 28 |
-| `app/models/pg_sql_triggers/trigger_registry.rb` | 100.0% ✅ | 176 | 0 | 176 |
+| `lib/pg_sql_triggers/testing/syntax_validator.rb` | 100.0% ✅ | 58 | 0 | 58 |
+| `lib/pg_sql_triggers/testing.rb` | 100.0% ✅ | 6 | 0 | 6 |
+| `config/initializers/pg_sql_triggers.rb` | 100.0% ✅ | 10 | 0 | 10 |
+| `app/models/pg_sql_triggers/application_record.rb` | 100.0% ✅ | 3 | 0 | 3 |
+| `app/models/pg_sql_triggers/audit_log.rb` | 100.0% ✅ | 32 | 0 | 32 |
 | `app/controllers/concerns/pg_sql_triggers/error_handling.rb` | 100.0% ✅ | 19 | 0 | 19 |
 | `app/controllers/concerns/pg_sql_triggers/kill_switch_protection.rb` | 100.0% ✅ | 17 | 0 | 17 |
-| `app/models/pg_sql_triggers/application_record.rb` | 100.0% ✅ | 3 | 0 | 3 |
+| `app/controllers/concerns/pg_sql_triggers/permission_checking.rb` | 100.0% ✅ | 41 | 0 | 41 |
 | `app/controllers/pg_sql_triggers/application_controller.rb` | 100.0% ✅ | 13 | 0 | 13 |
 | `app/helpers/pg_sql_triggers/permissions_helper.rb` | 100.0% ✅ | 16 | 0 | 16 |
-| `app/controllers/pg_sql_triggers/dashboard_controller.rb` | 100.0% ✅ | 26 | 0 | 26 |
-| `config/initializers/pg_sql_triggers.rb` | 100.0% ✅ | 10 | 0 | 10 |
-| `lib/pg_sql_triggers/errors.rb` | 100.0% ✅ | 83 | 0 | 83 |
-| `app/controllers/pg_sql_triggers/triggers_controller.rb` | 100.0% ✅ | 75 | 0 | 75 |
-| `lib/pg_sql_triggers.rb` | 100.0% ✅ | 40 | 0 | 40 |
-| `lib/pg_sql_triggers/migrator/pre_apply_comparator.rb` | 99.19% ✅ | 122 | 1 | 123 |
-| `lib/pg_sql_triggers/drift/detector.rb` | 98.48% ✅ | 65 | 1 | 66 |
-| `app/controllers/pg_sql_triggers/audit_logs_controller.rb` | 97.73% ✅ | 43 | 1 | 44 |
-| `app/controllers/pg_sql_triggers/sql_capsules_controller.rb` | 97.14% ✅ | 68 | 2 | 70 |
+| `app/controllers/pg_sql_triggers/audit_logs_controller.rb` | 100.0% ✅ | 55 | 0 | 55 |
+| `app/controllers/pg_sql_triggers/migrations_controller.rb` | 98.82% ✅ | 84 | 1 | 85 |
+| `lib/pg_sql_triggers/registry/manager.rb` | 98.81% ✅ | 83 | 1 | 84 |
+| `lib/pg_sql_triggers/events_checksum.rb` | 98.33% ✅ | 59 | 1 | 60 |
+| `app/models/pg_sql_triggers/trigger_registry.rb` | 97.69% ✅ | 211 | 5 | 216 |
+| `lib/pg_sql_triggers/sql/kill_switch.rb` | 96.51% ✅ | 83 | 3 | 86 |
 | `lib/generators/pg_sql_triggers/trigger_migration_generator.rb` | 96.3% ✅ | 26 | 1 | 27 |
-| `lib/pg_sql_triggers/sql/kill_switch.rb` | 96.04% ✅ | 97 | 4 | 101 |
-| `lib/pg_sql_triggers/migrator.rb` | 95.42% ✅ | 125 | 6 | 131 |
-| `lib/pg_sql_triggers/registry/manager.rb` | 95.08% ✅ | 58 | 3 | 61 |
-| `app/controllers/pg_sql_triggers/tables_controller.rb` | 94.74% ✅ | 18 | 1 | 19 |
+| `lib/pg_sql_triggers/alerting.rb` | 96.3% ✅ | 26 | 1 | 27 |
+| `lib/pg_sql_triggers/drift/db_queries.rb` | 96.15% ✅ | 25 | 1 | 26 |
+| `lib/pg_sql_triggers/deferral_checksum.rb` | 96.0% ✅ | 24 | 1 | 25 |
+| `lib/pg_sql_triggers/migrator.rb` | 95.78% ✅ | 159 | 7 | 166 |
+| `lib/pg_sql_triggers/registry/validator.rb` | 94.83% ✅ | 165 | 9 | 174 |
 | `lib/pg_sql_triggers/database_introspection.rb` | 94.29% ✅ | 66 | 4 | 70 |
 | `lib/pg_sql_triggers/drift/reporter.rb` | 94.12% ✅ | 96 | 6 | 102 |
-| `lib/pg_sql_triggers/engine.rb` | 92.86% ✅ | 13 | 1 | 14 |
+| `lib/pg_sql_triggers/drift/detector.rb` | 92.5% ✅ | 74 | 6 | 80 |
 | `lib/pg_sql_triggers/testing/safe_executor.rb` | 91.89% ✅ | 34 | 3 | 37 |
 | `lib/pg_sql_triggers/registry.rb` | 91.84% ✅ | 45 | 4 | 49 |
-| `app/controllers/pg_sql_triggers/generator_controller.rb` | 91.49% ✅ | 86 | 8 | 94 |
-| `lib/pg_sql_triggers/sql.rb` | 90.91% ✅ | 10 | 1 | 11 |
-| `lib/pg_sql_triggers/testing/function_tester.rb` | 89.71% ⚠️ | 61 | 7 | 68 |
-| `app/controllers/concerns/pg_sql_triggers/permission_checking.rb` | 85.37% ⚠️ | 35 | 6 | 41 |
-| `app/controllers/pg_sql_triggers/migrations_controller.rb` | 82.76% ⚠️ | 72 | 15 | 87 |
-| `config/routes.rb` | 12.0% ❌ | 3 | 22 | 25 |
+| `lib/pg_sql_triggers/trigger_structure_dumper.rb` | 90.32% ✅ | 56 | 6 | 62 |
+| `lib/pg_sql_triggers/testing/function_tester.rb` | 88.31% ⚠️ | 68 | 9 | 77 |
+| `app/controllers/pg_sql_triggers/tables_controller.rb` | 83.78% ⚠️ | 31 | 6 | 37 |
+| `lib/pg_sql_triggers/schema_dumper_extension.rb` | 73.33% ⚠️ | 11 | 4 | 15 |
+| `lib/pg_sql_triggers/engine.rb` | 72.97% ⚠️ | 27 | 10 | 37 |
+| `config/routes.rb` | 17.65% ❌ | 3 | 14 | 17 |
 
 ---