Support enforced: option on foreign keys

[yahonda]

Mirrors rails/rails#57377 (merged commit 6cb88eae), which adds an enforced: option to add_foreign_key (and a change_foreign_key helper) for PostgreSQL 18.4+ NOT ENFORCED constraints. The Ruby option name enforced: follows the [NOT] ENFORCED constraint characteristic introduced in SQL:2011 and carried forward into SQL:2016 (see References below); Oracle does not implement the [NOT] ENFORCED keyword. Instead, oracle-enhanced exposes Oracle's pre-existing 4-state constraint model via the independent enforced: and validate: Ruby options.

The 4-state matrix

enforced:	validate:	Oracle state	DML on child table
true (default)	true (default)	ENABLE VALIDATE	enforced, existing data valid
true (default)	false	ENABLE NOVALIDATE	enforced for new DML only
false	true (default)	DISABLE VALIDATE	blocked (ORA-25128) — read-only
false	false	DISABLE NOVALIDATE	not enforced (≈ PG NOT ENFORCED)

# enforced + validate, both defaults: ENABLE VALIDATE
add_foreign_key :articles, :authors

# Skip existing-data check, still enforce new DML
add_foreign_key :articles, :authors, validate: false

# DISABLE VALIDATE - constraint disabled, data marked validated, DML blocked
add_foreign_key :articles, :authors, enforced: false

# Cross-DB compatible "not enforced" semantics (mirrors PG NOT ENFORCED)
add_foreign_key :articles, :authors, enforced: false, validate: false

# Toggle enforced state on an existing FK
change_foreign_key :articles, :authors, enforced: true

The Ruby-API defaults are kept independent (validate: defaults to true regardless of enforced:) so all 4 states are reachable from idiomatic Rails code. The framework does not "protect" the user from DISABLE VALIDATE because Oracle itself allows it — the matrix above is reproduced as a comment above visit_ForeignKeyDefinition so this is discoverable in source.

Changes

• supports_enforced_foreign_keys? returns true unconditionally — Oracle's DISABLE/ENABLE constraint state has been available across every Oracle release this gem supports.
• visit_ForeignKeyDefinition appends DISABLE when enforced: false. When validate: is true (the Rails default) and enforced: false, VALIDATE is also emitted explicitly because Oracle's bare DISABLE clause defaults to NOVALIDATE — without the explicit keyword we couldn't reach DISABLE VALIDATE. The full 4-state matrix is documented in a comment above the method.
• foreign_keys introspection selects c.status from all_constraints and maps 'DISABLED' to options[:enforced] = false. c.validated is mapped independently to options[:validate] = false — the two flags are not coupled. The dumped output preserves both, so every Oracle state round-trips.
• change_foreign_key issues ALTER TABLE ... MODIFY CONSTRAINT ... ENABLE|DISABLE via the existing foreign_key_for! lookup helper. MODIFY ... DISABLE resets the validated state to NOT VALIDATED, so disabling an enforced FK reports both enforced: false and validate: false.

Schema dumping relies on the abstract ActiveRecord::ConnectionAdapters::SchemaDumper#foreign_keys, which since rails/rails#57377 emits enforced: false whenever foreign_key.enforced? is false (where enforced? is options.fetch(:enforced, true) on ForeignKeyDefinition). No adapter-level dumper override is needed.

Tests

• 5 specs in schema_statements_spec.rb exercising all 4 states + both change_foreign_key directions. ORA-25128 (DML blocked under DISABLE VALIDATE) is asserted, not avoided.
• 3 specs in schema_dumper_spec.rb covering enforced: false emission and full dump-and-load round-trips for both DISABLE VALIDATE and DISABLE NOVALIDATE.

269 examples pass against FREEPDB1 (Oracle 23ai).

References

[NOT] ENFORCED (the Rails option name)

• Upstream Rails PR (merged): Add enforced: option for foreign keys on PostgreSQL 18.4+ rails/rails#57377 — merged commit rails/rails@6cb88ea
• pgsql-hackers thread (accessible primary reference, since the SQL standard itself is behind ISO's paywall): https://postgrespro.com/list/thread-id/1770540 — Simon Riggs's 2010 proposal cites SQL:2011 §4.17.2: "Table constraints are either enforced or not enforced. Domain constraints and assertions are always enforced."
• SQL:2016 (ISO/IEC 9075-2:2016) carries the same syntax forward. Relevant subclauses:
  • §4.17 — definition of enforced / not enforced integrity constraints
  • §11.6 <table constraint definition> — <constraint characteristics> syntactic slot
  • §11.8 <referential constraint definition> — accepts <constraint characteristics> (this is the FK path)
  • §11.9 <check constraint definition> — accepts <constraint characteristics>
  • Annex F — feature taxonomy, including F815 Not enforced check constraints
  • Grammar: <constraint enforcement> ::= ENFORCED | NOT ENFORCED
• PostgreSQL feature table src/backend/catalog/sql_features.txt references F815; the entry was updated for FK support in PostgreSQL commit b663b9436e.

ENABLE / DISABLE / VALIDATE / NOVALIDATE (the Oracle-side translation)

• Oracle 8i SQL Reference, Release 3 (8.1.7) — constraint_clause: https://docs.oracle.com/cd/A87860_01/doc/server.817/a85397/state14a.htm — documents the constraint_state clause (ENABLE / DISABLE, VALIDATE / NOVALIDATE) as applicable to foreign-key (referential) constraints. The four-state model and its semantic definitions ("ENABLE VALIDATE … guarantees that all data is and will continue to be valid"; "DISABLE NOVALIDATE signifies that Oracle makes no effort to maintain the constraint") are already present in 8i and have been carried forward to current releases unchanged. The DML-blocking behavior of DISABLE VALIDATE (ORA-25128 — "No insert/update/delete on table with constraint (…) disabled and validated") is part of the same long-standing semantics.

[yahonda]

rails/rails#57377 has been opened to Rails.

[yahonda]

rails/rails#57377 has been merged.