Documentation Clarification: ALTER CONSTRAINT Enforceability Wording

Core Problem

The thread identifies a documentation clarity issue introduced by commit 342051d73, which added support for altering CHECK constraint enforceability in PostgreSQL 19. The specific problem is that the ALTER TABLE documentation's ALTER CONSTRAINT section contains the phrase "but see below" that creates ambiguity about what capabilities exist for which constraint types.

The Ambiguity

The documentation states:

"Currently FOREIGN KEY and CHECK constraints may be altered in this fashion, but see below."

The phrase "but see below" is a holdover from when only FOREIGN KEY constraints supported ALTER CONSTRAINT. It ostensibly refers to the ALTER CONSTRAINT ... INHERIT / NO INHERIT paragraph below, which states "Only not-null constraints may be altered in this fashion at present." However, this creates confusion because:

1. The reader naturally expects "see below" to elaborate on FOREIGN KEY and CHECK alterability, but the referenced text discusses NOT NULL constraints and inheritability — a completely different attribute.
2. The documentation fails to clearly delineate which attributes can be altered for which constraint types:
   • Deferrability (DEFERRABLE/NOT DEFERRABLE, INITIALLY DEFERRED/INITIALLY IMMEDIATE): Only FOREIGN KEY constraints
   • Enforceability (ENFORCED/NOT ENFORCED): Both FOREIGN KEY and CHECK constraints (CHECK support new in v19 via commit 342051d73)
   • Inheritability (INHERIT/NO INHERIT): Only NOT NULL constraints

Architectural Context

The ALTER CONSTRAINT mechanism in PostgreSQL has grown incrementally:

• Originally it only supported changing deferrability attributes of foreign key constraints
• Enforceability was later added for foreign keys
• Commit 342051d73 extended enforceability alteration to CHECK constraints in v19

This incremental growth means the documentation paragraph was written with a single constraint type in mind and has been patched without holistic revision, leading to the current confusion.

Proposed Solution

The author proposes a documentation patch that restructures the wording to explicitly enumerate which attributes can be altered for which constraint types, eliminating the vague "but see below" cross-reference. The patch aims to make it unambiguous that:

• Deferrability is FOREIGN KEY-only
• Enforceability applies to both FOREIGN KEY and CHECK
• Inheritability is NOT NULL-only

Thread Resolution

The author self-closed this thread after discovering a related bug in the same feature (the CHECK constraint enforceability alteration). They proposed merging discussion into the bug-fix thread at https://postgr.es/m/E74C57FA-1DD0-4C8E-8FB1-538034752592@gmail.com, which is a practical approach — bundling the documentation fix with the code fix ensures both land together.

Technical Significance

While this is "just" a documentation issue, it matters because:

1. ALTER CONSTRAINT's growing surface area across constraint types requires clear documentation of which operations apply to which types
2. Enforceability is a relatively new concept in PostgreSQL constraints, and users testing v19 features (as the author was doing) rely on documentation accuracy
3. The "but see below" anti-pattern in documentation creates a maintenance burden as features are added incrementally