On Thu, May 1, 2025 at 10:19 PM jian he <jian.universal...@gmail.com> wrote:
>
> hi.
>
> catalog.sgml:
>
> <row>
> <entry role="catalog_table_entry"><para role="column_definition">
> <structfield>convalidated</structfield> <type>bool</type>
> </para>
> <para>
> Has the constraint been validated?
> Currently, can be false only for foreign keys and CHECK constraints
> </para></entry>
> </row>
>
> with NOT NULL NOT VALID,
> we need rephrase it to something like:
> "Currently, can be false only for foreign keys, CHECK and not-null
> constraints"
> I am also ok with just deleting it.
>
I actually think this mix of VALID / ENFORCED is a little convoluted
for end users, but I don't think the system catalog documentation is
the best place to work that out, and I see we've also not added this
type of extra information to other columns in the table that have
similar restrictions, so I think removing it is the right move.
As such, attached patch removes the above, and attempts some clean up
of the documentation in ALTER TABLE to better clarify the behavior
around valid/not valid, enforced/not enforced, and how it affects
different constraints, with some additional literal tag formatting
changes.
>
> BTW, I happen to notice a minor issue:
> some pg_catalog table column entry descriptions ending with a period,
> some didn't.
>
I don't know if it is intentional, but this seems to be determined by
a rough heuristic on if the description contains a complete
sentence(s) or not, but I would agree there are cases that don't
follow that, and some that could probably be argued either way. If it
were me I'd probably add punctuation to all of the entries, but others
may feel different.
Robert Treat
https://xzilla.net
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index cbd4e40a320..018f6e3e08b 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -2629,7 +2629,6 @@ SCRAM-SHA-256$<replaceable><iteration
count></replaceable>:<replaceable>&l
</para>
<para>
Has the constraint been validated?
- Currently, can be false only for foreign keys and CHECK constraints
</para></entry>
</row>
diff --git a/doc/src/sgml/ref/alter_table.sgml
b/doc/src/sgml/ref/alter_table.sgml
index d63f3a621ac..e47e7c4e3ef 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -243,7 +243,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
entire table; however, if a valid <literal>CHECK</literal> constraint is
found which proves no <literal>NULL</literal> can exist, then the
table scan is skipped.
- If a column has an invalid not-null constraint,
+ If a column has an invalid <literal>NOT NULL</literal> constraint,
<literal>SET NOT NULL</literal> validates it.
</para>
@@ -459,9 +459,10 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
<listitem>
<para>
This form adds a new constraint to a table using the same constraint
- syntax as <link linkend="sql-createtable"><command>CREATE
TABLE</command></link>, plus the option <literal>NOT
- VALID</literal>, which is currently only allowed for foreign key,
- <literal>CHECK</literal> constraints and not-null constraints.
+ syntax as <link linkend="sql-createtable"><command>CREATE
TABLE</command></link>,
+ plus the option <literal>NOT VALID</literal>, which is currently only
+ allowed for <literal>FOREIGN KEY</literal>, <literal>CHECK</literal>,
+ and <literal>NOT NULL</literal> constraints.
</para>
<para>
@@ -469,7 +470,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
existing rows in the table satisfy the new constraint. But if
the <literal>NOT VALID</literal> option is used, this
potentially-lengthy scan is skipped. The constraint will still be
- enforced against subsequent inserts or updates (that is, they'll fail
+ applied against subsequent inserts or updates (that is, they'll fail
unless there is a matching row in the referenced table, in the case
of foreign keys, or they'll fail unless the new row matches the
specified check condition). But the
@@ -571,8 +572,8 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
<listitem>
<para>
These forms modify a inheritable constraint so that it becomes not
- inheritable, or vice-versa. Only not-null constraints may be altered
- in this fashion at present.
+ inheritable, or vice-versa. Only <literal>NOT NULL</literal> constraints
+ may be altered in this fashion at present.
In addition to changing the inheritability status of the constraint,
in the case where a non-inheritable constraint is being marked
inheritable, if the table has children, an equivalent constraint
@@ -588,10 +589,12 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
<term><literal>VALIDATE CONSTRAINT</literal></term>
<listitem>
<para>
- This form validates a foreign key, check, or not-null constraint that was
- previously created as <literal>NOT VALID</literal>, by scanning the
+ This form validates a <literal>FOREIGN KEY</literal>,
+ <literal>CHECK</literal>, or <literal>NOT NULL</literal> constraint that
+ was previously created as <literal>NOT VALID</literal>, by scanning the
table to ensure there are no rows for which the constraint is not
- satisfied. If the constraint is not enforced, an error is thrown.
+ satisfied. If the constraint was created as
+ <literal>NOT ENFORCED</literal>, an error is thrown.
Nothing happens if the constraint is already marked valid.
(See <xref linkend="sql-altertable-notes"/> below for an explanation
of the usefulness of this command.)
@@ -1466,11 +1469,11 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
</para>
<para>
- Adding an enforced <literal>CHECK</literal> or <literal>NOT NULL</literal>
- constraint requires scanning the table to verify that existing rows meet
the
- constraint, but does not require a table rewrite. If a
<literal>CHECK</literal>
- constraint is added as <literal>NOT ENFORCED</literal>, the validation will
- not be performed.
+ Adding a <literal>CHECK</literal> or <literal>NOT NULL</literal>
+ constraint requires scanning the table to verify that existing rows meet
+ the constraint, but does not require a table rewrite. IF a
+ <literal>CHECK</literal> constraint is added as
+ <literal>NOT ENFORCED</literal>, no verification is performed.
</para>
<para>
@@ -1485,7 +1488,8 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
</para>
<para>
- Scanning a large table to verify a new foreign key or check constraint
+ Scanning a large table to verify new <literal>FOREIGN KEY</literal>,
+ <literal>CHECK</literal>, or <literal>NOT NULL</literal> constraints
can take a long time, and other updates to the table are locked out
until the <command>ALTER TABLE ADD CONSTRAINT</command> command is
committed. The main purpose of the <literal>NOT VALID</literal>
