agora inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedincorrect (incomplete) description for "alter domain"
9+ messages / 6 participants
[nested] [flat]
* incorrect (incomplete) description for "alter domain"
@ 2024-07-29 11:02 PG Doc comments form <noreply@postgresql.org>
0 siblings, 2 replies; 9+ messages in thread
From: PG Doc comments form @ 2024-07-29 11:02 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: elionescu@yahoo.com
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/16/sql-alterdomain.html
Description:
In the Synopsis section of
https://www.postgresql.org/docs/current/sql-alterdomain.html
this is incorrect (incomplete):
"ALTER DOMAIN name ADD domain_constraint [ NOT VALID ]"
It should be
"ALTER DOMAIN name ADD CONSTRAINT domain_constraint [ NOT VALID ]"
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: incorrect (incomplete) description for "alter domain"
@ 2024-07-29 12:56 Erik Wienhold <ewie@ewie.name>
parent: PG Doc comments form <noreply@postgresql.org>
1 sibling, 0 replies; 9+ messages in thread
From: Erik Wienhold @ 2024-07-29 12:56 UTC (permalink / raw)
To: elionescu@yahoo.com; pgsql-docs@lists.postgresql.org
On 2024-07-29 13:02 +0200, PG Doc comments form wrote:
> In the Synopsis section of
> https://www.postgresql.org/docs/current/sql-alterdomain.html
> this is incorrect (incomplete):
> "ALTER DOMAIN name ADD domain_constraint [ NOT VALID ]"
> It should be
> "ALTER DOMAIN name ADD CONSTRAINT domain_constraint [ NOT VALID ]"
No, the docs are correct. domain_constraint refers to this syntax
defined by CREATE DOMAIN:
"where constraint is:
[ CONSTRAINT constraint_name ]
{ NOT NULL | NULL | CHECK (expression) }"
Also, PG 17 renames this to "domain_constraint" with commit 9895b35cb8
to align ALTER DOMAIN with CREATE DOMAIN.
--
Erik
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: incorrect (incomplete) description for "alter domain"
@ 2024-07-29 12:56 David G. Johnston <david.g.johnston@gmail.com>
parent: PG Doc comments form <noreply@postgresql.org>
1 sibling, 1 reply; 9+ messages in thread
From: David G. Johnston @ 2024-07-29 12:56 UTC (permalink / raw)
To: elionescu@yahoo.com <elionescu@yahoo.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Monday, July 29, 2024, PG Doc comments form <noreply@postgresql.org>
wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/16/sql-alterdomain.html
> Description:
>
> In the Synopsis section of
> https://www.postgresql.org/docs/current/sql-alterdomain.html
> this is incorrect (incomplete):
> "ALTER DOMAIN name ADD domain_constraint [ NOT VALID ]"
> It should be
> "ALTER DOMAIN name ADD CONSTRAINT domain_constraint [ NOT VALID ]"
>
The definition of “domain_constraint” includes the optional “constraint
constraint_name” clause. Though reading the page and seeing the number of
times we say “alter domain add constraint” I even more inclined to agree
that bringing the word constraint there is desirable. I am not a huge fan
of the indirect syntax references anyway. But I think your proposed fix is
technically wrong since the word constraint is optional but your change
makes it mandatory.
David J.
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: incorrect (incomplete) description for "alter domain"
@ 2024-07-29 14:58 Tom Lane <tgl@sss.pgh.pa.us>
parent: David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 1 reply; 9+ messages in thread
From: Tom Lane @ 2024-07-29 14:58 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: elionescu@yahoo.com <elionescu@yahoo.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
"David G. Johnston" <david.g.johnston@gmail.com> writes:
> On Monday, July 29, 2024, PG Doc comments form <noreply@postgresql.org>
> wrote:
>> In the Synopsis section of
>> https://www.postgresql.org/docs/current/sql-alterdomain.html
>> this is incorrect (incomplete):
>> "ALTER DOMAIN name ADD domain_constraint [ NOT VALID ]"
>> It should be
>> "ALTER DOMAIN name ADD CONSTRAINT domain_constraint [ NOT VALID ]"
> The definition of “domain_constraint” includes the optional “constraint
> constraint_name” clause. Though reading the page and seeing the number of
> times we say “alter domain add constraint” I even more inclined to agree
> that bringing the word constraint there is desirable. I am not a huge fan
> of the indirect syntax references anyway.
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. Is that the same thing
you're thinking, or did you have a different idea?
regards, tom lane
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: incorrect (incomplete) description for "alter domain"
@ 2024-07-29 15:17 Tom Lane <tgl@sss.pgh.pa.us>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 3 replies; 9+ messages in thread
From: Tom Lane @ 2024-07-29 15:17 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: elionescu@yahoo.com <elionescu@yahoo.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
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.
regards, tom lane
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: incorrect (incomplete) description for "alter domain"
@ 2024-07-29 17:43 David G. Johnston <david.g.johnston@gmail.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
2 siblings, 0 replies; 9+ messages in thread
From: David G. Johnston @ 2024-07-29 17:43 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: elionescu@yahoo.com <elionescu@yahoo.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Mon, Jul 29, 2024 at 8:17 AM Tom Lane <tgl@sss.pgh.pa.us> 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.
>
Agreed
> 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.
>
>
The inconsistency here and with create/alter table makes me want to make
alter domain work as well. But I agree it isn't really worth the effort
when one is supposed to use "drop not null" to accomplish the effect of
making a domain nullable. But it does open the question of why we document
"alter table alter column add null" - which does not get mentioned as being
a non-standard option on the alter table page.
Both create table and create domain say:
NULL: This clause is only intended for compatibility with nonstandard SQL
databases. Its use is discouraged in new applications.
But then create table goes on to say under Compatibility:
The NULL “constraint” (actually a non-constraint) is a PostgreSQL extension
to the SQL standard ...
But create domain has no matching language; it claims full conformity.
That this "non-constraint" can have a name given seems unusual though done
for ease of syntax I presume.
David J.
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: incorrect (incomplete) description for "alter domain"
@ 2024-07-31 05:22 Peter Eisentraut <peter@eisentraut.org>
parent: Tom Lane <tgl@sss.pgh.pa.us>
2 siblings, 0 replies; 9+ messages in thread
From: Peter Eisentraut @ 2024-07-31 05:22 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; David G. Johnston <david.g.johnston@gmail.com>; +Cc: elionescu@yahoo.com <elionescu@yahoo.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
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.
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: incorrect (incomplete) description for "alter domain"
@ 2024-10-16 21:11 Bruce Momjian <bruce@momjian.us>
parent: Tom Lane <tgl@sss.pgh.pa.us>
2 siblings, 1 reply; 9+ messages in thread
From: Bruce Momjian @ 2024-10-16 21:11 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: David G. Johnston <david.g.johnston@gmail.com>; elionescu@yahoo.com <elionescu@yahoo.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Mon, Jul 29, 2024 at 11:17:41AM -0400, 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.
I have written the attached patch to document this. I assume this
should be backpatched to PG 12.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
When a patient asks the doctor, "Am I going to die?", he means
"Am I going to die soon?"
Attachments:
[text/x-diff] domain.diff (1.4K, ../../ZxAsGmcyYk8es5ac@momjian.us/2-domain.diff)
download | inline diff:
diff --git a/doc/src/sgml/ref/alter_domain.sgml b/doc/src/sgml/ref/alter_domain.sgml
index f6704d7557a..74855172222 100644
--- a/doc/src/sgml/ref/alter_domain.sgml
+++ b/doc/src/sgml/ref/alter_domain.sgml
@@ -41,6 +41,11 @@ ALTER DOMAIN <replaceable class="parameter">name</replaceable>
RENAME TO <replaceable class="parameter">new_name</replaceable>
ALTER DOMAIN <replaceable class="parameter">name</replaceable>
SET SCHEMA <replaceable class="parameter">new_schema</replaceable>
+
+<phrase>where <replaceable class="parameter">domain_constraint</replaceable> is:</phrase>
+
+[ CONSTRAINT <replaceable class="parameter">constraint_name</replaceable> ]
+{ NOT NULL | CHECK (<replaceable class="parameter">expression</replaceable>) }
</synopsis>
</refsynopsisdiv>
@@ -79,8 +84,7 @@ ALTER DOMAIN <replaceable class="parameter">name</replaceable>
<term><literal>ADD <replaceable class="parameter">domain_constraint</replaceable> [ NOT VALID ]</literal></term>
<listitem>
<para>
- This form adds a new constraint to a domain using the same syntax as
- <link linkend="sql-createdomain"><command>CREATE DOMAIN</command></link>.
+ This form adds a new constraint to a domain.
When a new constraint is added to a domain, all columns using that
domain will be checked against the newly added constraint. These
checks can be suppressed by adding the new constraint using the
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: incorrect (incomplete) description for "alter domain"
@ 2024-11-01 17:54 Bruce Momjian <bruce@momjian.us>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 0 replies; 9+ messages in thread
From: Bruce Momjian @ 2024-11-01 17:54 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: David G. Johnston <david.g.johnston@gmail.com>; elionescu@yahoo.com <elionescu@yahoo.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Wed, Oct 16, 2024 at 05:11:54PM -0400, Bruce Momjian wrote:
> > 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.
>
> I have written the attached patch to document this. I assume this
> should be backpatched to PG 12.
Patch applied back to PG 12.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
When a patient asks the doctor, "Am I going to die?", he means
"Am I going to die soon?"
^ permalink raw reply [nested|flat] 9+ messages in thread
end of thread, other threads:[~2024-11-01 17:54 UTC | newest]
Thread overview: 9+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2024-07-29 11:02 incorrect (incomplete) description for "alter domain" PG Doc comments form <noreply@postgresql.org>
2024-07-29 12:56 ` Erik Wienhold <ewie@ewie.name>
2024-07-29 12:56 ` David G. Johnston <david.g.johnston@gmail.com>
2024-07-29 14:58 ` Tom Lane <tgl@sss.pgh.pa.us>
2024-07-29 15:17 ` Tom Lane <tgl@sss.pgh.pa.us>
2024-07-29 17:43 ` David G. Johnston <david.g.johnston@gmail.com>
2024-07-31 05:22 ` Peter Eisentraut <peter@eisentraut.org>
2024-10-16 21:11 ` Bruce Momjian <bruce@momjian.us>
2024-11-01 17:54 ` Bruce Momjian <bruce@momjian.us>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox