pg_sql_triggers 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3009d08e9604d3cad9af352b595fe76fb2688c7f1bf80cfbb92bbb9bbadeb996
-  data.tar.gz: 0155742bcf1ad97690f42c8193da6ff408f09dab26f8684c84a6954c8438f28f
+  metadata.gz: 7adcec137e32ecf9e1013a7dbb98a16844a5f8082b0d910a7380903cd2151678
+  data.tar.gz: b285ecac25cf7806a56f0205fca527a158b48c7f26b99adb4c1c304b3b2d17d7
 SHA512:
-  metadata.gz: f76fc2c48a00922e7265acce7d8c87e0477686540b4749aef94bbd1d4b914f7cdf76a0c28cc3f3dd816489c24606ee6b2fe424d309dbc03e70cf160fba6daad8
-  data.tar.gz: 4988c497e39a54d517e1f96a4328609de0bb0451658d228b46a4bd2d448267b7866ede607eb702430510a88b16fb328d801fc81a00e0d93c231ad7d94caff216
+  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

@@ -5,6 +5,108 @@ 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]
+
+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
@@ -15,7 +117,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `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
+  (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
@@ -26,7 +128,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   [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))
+  [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
 

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 |
 
 ---
 

data/README.md

@@ -42,6 +42,8 @@ rails generate pg_sql_triggers:install
 rails db:migrate
 ```
 
+Schema migrations bundled with the gem are listed in [Getting Started — Gem schema migrations](docs/getting-started.md#gem-schema-migrations) (ordered `db/migrate/*.rb` filenames).
+
 ### Define a Trigger
 
 ```ruby
@@ -97,9 +99,27 @@ Files land in `app/triggers/` and `db/triggers/` for code review like any other
 ### Migration System
 Manage trigger functions and definitions with a migration system similar to Rails schema migrations.
 
+### schema.rb, structure.sql, and trigger snapshots
+
+`db:schema:dump` does not capture PostgreSQL triggers. This gem addresses that in three ways:
+
+1. **Comments in `schema.rb`** — When using the default Ruby schema format, `rails db:schema:dump` appends a short note listing managed triggers and pointing to `trigger:migrate` / `trigger:load`. Disable with `PgSqlTriggers.append_trigger_notes_to_schema_dump = false`.
+2. **`db/trigger_structure.sql`** — Run `rails trigger:dump` to write `CREATE FUNCTION` / `CREATE TRIGGER` statements for registered triggers (or all non-internal triggers in `public` if the registry table is absent). Apply on a fresh DB with `rails trigger:load` (runs arbitrary SQL; kill switch applies in protected environments). Override the path with `FILE=...` or `TRIGGER_STRUCTURE_SQL=...`, or set `PgSqlTriggers.trigger_structure_sql_path`.
+3. **`db:schema:load`** — After loading `schema.rb`, `trigger:migrate` runs automatically so pending trigger migrations apply. Opt out with `SKIP_TRIGGER_MIGRATE_AFTER_SCHEMA_LOAD=1` or `PgSqlTriggers.migrate_triggers_after_schema_load = false`.
+
+For a single SQL artifact that includes tables and triggers, set `config.active_record.schema_format = :sql` and use Rails’ `structure.sql` workflow; keep `db/triggers` migrations as the source of truth and refresh `db/trigger_structure.sql` when you want a portable trigger-only snapshot.
+
 ### Drift Detection
 Automatically detect when database triggers drift from your DSL definitions. N+1-free bulk detection across all triggers.
 
+### Drift Alerting
+Configure `PgSqlTriggers.drift_notifier` to push alerts to Slack, PagerDuty, email, or any external system when drift detection finds drifted, dropped, or unknown triggers. Schedule `rake trigger:check_drift` (with optional `FAIL_ON_DRIFT=1`) for CI or cron-based monitoring. An `ActiveSupport::Notifications` event `pg_sql_triggers.drift_check` is emitted on every run for APM instrumentation.
+
+### Advanced PostgreSQL Trigger Features
+- **Column-level `UPDATE OF` triggers** — `on_update_of(:email, :status)` fires only when specific columns change, a common audit/performance optimisation.
+- **Constraint triggers with deferral** — `constraint_trigger!` plus `deferrable` / `initially` options emit `CREATE CONSTRAINT TRIGGER ... DEFERRABLE INITIALLY DEFERRED` for referential-integrity patterns that need to fire at transaction commit.
+- **Ordering hints** — `depends_on "other_trigger"` captures intended firing order among same-table triggers. PostgreSQL fires same-kind triggers alphabetically; `rake trigger:validate_order` (and `Registry.validate!`) verifies declared dependencies, flags cycles, and enforces name-ordering so declared order matches execution order.
+
 ### Production Kill Switch
 Multi-layered safety mechanism preventing accidental destructive operations in production environments.
 
@@ -109,6 +129,7 @@ Visual interface for managing triggers and running migrations. Includes:
 - **Last Applied Tracking**: See when triggers were last applied with human-readable timestamps
 - **Breadcrumb Navigation**: Easy navigation between dashboard, tables, and triggers
 - **Permission-Aware UI**: Buttons show/hide based on user role
+- **Search, Filter, and Pagination**: Filter triggers by table, drift state, or source; full-text search on name/table; offset/limit pagination (`?table=users&state=drifted&source=dsl&q=email&trigger_page=2&trigger_per_page=20`)
 
 ### Audit Logging
 Comprehensive audit trail for all trigger operations:
@@ -171,9 +192,9 @@ To install this gem locally, run `bundle exec rake install`. To release a new ve
 
 ## Test Coverage
 
-See [COVERAGE.md](COVERAGE.md) for detailed coverage information.
-
-**Total Coverage: 84.97%**
+See [COVERAGE.md](COVERAGE.md) for detailed coverage information. The bundled report was
+generated against an earlier tree and will be regenerated as part of the next release cycle
+(run `bundle exec rspec` with SimpleCov, then `ruby scripts/generate_coverage_report.rb`).
 
 ## Contributing
 

data/Rakefile

@@ -6,6 +6,11 @@
 # - rake release: Build, tag, push to git, and publish to RubyGems.org
 require "bundler/gem_tasks"
 
+# Minimal Rails + engine task load so `bundle exec rake trigger:*` works from this repo
+# (host apps load these via Rails::Engine#rake_tasks instead).
+Dir[File.expand_path("rakelib/**/*.rake", __dir__)].each { |f| load f }
+load File.expand_path("lib/tasks/trigger_migrations.rake", __dir__)
+
 # RSpec tasks:
 # - rake spec: Run the test suite
 require "rspec/core/rake_task"

data/app/controllers/concerns/pg_sql_triggers/permission_checking.rb

@@ -7,7 +7,7 @@ module PgSqlTriggers
     included do
       # Helper methods available in views
       helper_method :current_actor, :can_view_triggers?, :can_enable_disable_triggers?,
-                    :can_drop_triggers?, :can_execute_sql?, :can_generate_triggers?, :can_apply_triggers?
+                    :can_drop_triggers?, :can_execute_sql_operations?, :can_generate_triggers?, :can_apply_triggers?
     end
 
     # Returns the current actor (user) performing the action.
@@ -67,7 +67,7 @@ module PgSqlTriggers
       redirect_to root_path, alert: "Insufficient permissions. Operator role required."
     end
 
-    # Checks if current actor has admin permissions (drop/re-execute/execute SQL).
+    # Checks if current actor has admin permissions (drop/re-execute).
     #
     # @raise [ActionController::RedirectError] Redirects if permission denied
     def check_admin_permission
@@ -99,14 +99,15 @@ module PgSqlTriggers
       PgSqlTriggers::Permissions.can?(current_actor, :drop_trigger, environment: current_environment)
     end
 
-    # @return [Boolean] true if current actor can execute SQL capsules
-    def can_execute_sql?
+    # @return [Boolean] true if the +:execute_sql+ action is allowed (privileged SQL for host apps;
+    #   not used by built-in UI)
+    def can_execute_sql_operations?
       PgSqlTriggers::Permissions.can?(current_actor, :execute_sql, environment: current_environment)
     end
 
     # @return [Boolean] true if current actor can generate triggers
     def can_generate_triggers?
-      PgSqlTriggers::Permissions.can?(current_actor, :apply_trigger, environment: current_environment)
+      PgSqlTriggers::Permissions.can?(current_actor, :generate_trigger, environment: current_environment)
     end
 
     # @return [Boolean] true if current actor can apply triggers