Re: incorrect (incomplete) description for "alter domain"

On 29.07.24 17:17, Tom Lane wrote:
> I wrote:
>> I think the page is technically correct, but I'm inclined to duplicate
>> this text from the CREATE DOMAIN page:
> 
>>     where domain_constraint is:
>>     [ CONSTRAINT constraint_name ]
>>     { NOT NULL | NULL | CHECK (expression) }
> 
>> rather than making readers go look that up.
> 
> Actually, there *is* a bug in the description, because experimentation
> shows that CREATE DOMAIN accepts NULL in this syntax (as advertised)
> but ALTER DOMAIN does not.  We could alternatively decide that that's
> a code bug and make ALTER DOMAIN take it, but I don't think it's worth
> any effort (and this behavior may actually have been intentional, too).
> I think we should just add
> 
>     where domain_constraint is:
> 
>     [ CONSTRAINT constraint_name ]
>     { NOT NULL | CHECK (expression) }
> 
> to the ALTER DOMAIN page, and then remove the claim that it's
> identical to CREATE DOMAIN.

There was some discussion about these issues (ALTER DOMAIN vs CREATE 
DOMAIN reference page, as well as the NOT NULL constraint syntax) in and 
around 
<https://www.postgresql.org/message-id/a4a344ea-9e79-4c42-a9af-899f85bd753b@eisentraut.org>. 
  All that ended up dying because the NOT NULL constraints feature was 
reverted.  But there were some subtle details about why the syntax is 
the way it is and/or whether that's really intentional and how to 
document it.  Might be worth reviewing again.