Обсуждение: Documentation weirdness

Hi, ALL,
I'm looking at https://www.postgresql.org/docs/current/sql-createtable.html
and see some weird stuff.

When I try to search for "PRIMARY KEY" I eventually hit following:

[quote]
PRIMARY KEY (column constraint)
PRIMARY KEY ( column_name [, ... ] [, column_name WITHOUT OVERLAPS ] )
[ INCLUDE ( column_name [, ...]) ] (table constraint)
[/quote]

Now I want to check what "column_constraint" is.

Going all the way up and start searching I see that its:

[quote]

where column_constraint is:

[ CONSTRAINT constraint_name ]
{ NOT NULL [ NO INHERIT ]  |
  NULL |
  CHECK ( expression ) [ NO INHERIT ] |
  DEFAULT default_expr |
  GENERATED ALWAYS AS ( generation_expr ) [ STORED | VIRTUAL ] |
  GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( sequence_options ) ] |
  UNIQUE [ NULLS [ NOT ] DISTINCT ] index_parameters |
  PRIMARY KEY index_parameters |
  REFERENCES reftable [ ( refcolumn ) ] [ MATCH FULL | MATCH PARTIAL |
MATCH SIMPLE ]
    [ ON DELETE referential_action ] [ ON UPDATE referential_action ] }
[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY
IMMEDIATE ] [ ENFORCED | NOT ENFORCED ]
[/quote]

which already contains "PRIMARY KEY".

And so according to the documentation one can write:

CREATE TABLE foo( id SERIAL PRIMARY KEY PRIMARY KEY, ... );

which unfortunately will be illegal.

Or not?

Thank you.

On 3/1/26 5:38 PM, Igor Korot wrote:
> Hi, ALL,
> I'm looking at https://www.postgresql.org/docs/current/sql-createtable.html
> and see some weird stuff.
> 
> When I try to search for "PRIMARY KEY" I eventually hit following:
> 
> [quote]
> PRIMARY KEY (column constraint)
> PRIMARY KEY ( column_name [, ... ] [, column_name WITHOUT OVERLAPS ] )
> [ INCLUDE ( column_name [, ...]) ] (table constraint)
> [/quote]

What the above is telling you is that PK can be defined as part of the 
column definition:

some_fld some_type PRIMARY KEY

or as part of the overall table definition:

CREATE TABLE

...
some_fld some_type,
other_fld other_type'
...

PRIMARY KEY (some_fld, other_fld);

Look at the top of documentation under:

"where column_constraint is:"

and

"and table_constraint is:"

respectively.

> 
> And so according to the documentation one can write:
> 
> CREATE TABLE foo( id SERIAL PRIMARY KEY PRIMARY KEY, ... );
> 
> which unfortunately will be illegal.
> 
> Or not?



> 
> Thank you.
> 
> 


-- 
Adrian Klaver
adrian.klaver@aklaver.com

Thx for the quick reply.

Agreed.

On Sun, Mar 1, 2026 at 8:09 PM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>
> On Sun, Mar 1, 2026 at 6:38 PM Igor Korot <ikorot01@gmail.com> wrote:
>>
>> Hi, ALL,
>> I'm looking at https://www.postgresql.org/docs/current/sql-createtable.html
>> and see some weird stuff.
>>
>> When I try to search for "PRIMARY KEY" I eventually hit following:
>>
>> [quote]
>> PRIMARY KEY (column constraint)
>> PRIMARY KEY ( column_name [, ... ] [, column_name WITHOUT OVERLAPS ] )
>> [ INCLUDE ( column_name [, ...]) ] (table constraint)
>> [/quote]
>>
>> Now I want to check what "column_constraint" is.
>
>
> You read in an underscore in the parenthetical that isn't there.  That said, I concur that using a label here that so
closelymatches something that exists within the page, to mean something else, is just asking for this kind of
confusion.
>
> Looking at this, I did find a real sgml markup mistake.  The highlighting in dark mode makes it obvious since the
whole"literal" should be shaded differently but a couple of parts are not. 
>
> The diff below fixes the sgml problem by removing the inner <literal> close/open pair and placing the <optional>
closingelement inside the closing <literal> element. 
>
> I have also added the word "variant" to the two labels to make it clear they are indeed two variants of the same
thing(as described below) as opposed to some kind of syntax element. 
>
>
> diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
> index 982532fe725..befadf1d696 100644
> --- a/doc/src/sgml/ref/create_table.sgml
> +++ b/doc/src/sgml/ref/create_table.sgml
> @@ -1067,9 +1067,9 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
>     </varlistentry>
>
>     <varlistentry id="sql-createtable-parms-primary-key">
> -    <term><literal>PRIMARY KEY</literal> (column constraint)</term>
> -    <term><literal>PRIMARY KEY ( <replaceable class="parameter">column_name</replaceable> [, ... ] [, <replaceable
class="parameter">column_name</replaceable>WITHOUT OVERLAPS ] )</literal> 
> -    <optional> <literal>INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ...])</literal>
</optional>(table constraint)</term> 
> +    <term><literal>PRIMARY KEY</literal> (column constraint variant)</term>
> +    <term><literal>PRIMARY KEY ( <replaceable class="parameter">column_name</replaceable> [, ... ] [, <replaceable
class="parameter">column_name</replaceable>WITHOUT OVERLAPS ] ) 
> +    <optional> INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ...])</optional></literal>
(tableconstraint variant)</term> 
>      <listitem>
>       <para>
>        The <literal>PRIMARY KEY</literal> constraint specifies that a column or
>
> I'll forward this onto -hackers if no one decides to quickly handle it from here.
>
> David J.
>
>

On 2026-03-01 19:08:48 -0700, David G. Johnston wrote:
> On Sun, Mar 1, 2026 at 6:38 PM Igor Korot <ikorot01@gmail.com> wrote:
>
>     Hi, ALL,
>     I'm looking at https://www.postgresql.org/docs/current/sql-createtable.html
>     and see some weird stuff.
>
>     When I try to search for "PRIMARY KEY" I eventually hit following:
>
>     [quote]
>     PRIMARY KEY (column constraint)
>     PRIMARY KEY ( column_name [, ... ] [, column_name WITHOUT OVERLAPS ] )
>     [ INCLUDE ( column_name [, ...]) ] (table constraint)
>     [/quote]
>
>     Now I want to check what "column_constraint" is.
>
>
> You read in an underscore in the parenthetical that isn't there.  That said, I
> concur that using a label here that so closely matches something that exists
> within the page, to mean something else, is just asking for this kind of
> confusion.

Would it be possible to set (column constraint) and (table constraint)
in the normal body font instead of monospace? That would make it clearer
that these phrases aren't part of the syntax but descriptive.

        hjp

--
   _  | Peter J. Holzer    | Story must make more sense than reality.
|_|_) |                    |
| |   | hjp@hjp.at         |    -- Charles Stross, "Creative writing
__/   | http://www.hjp.at/ |       challenge!"

On 2026-03-01 19:08:48 -0700, David G. Johnston wrote:
> On Sun, Mar 1, 2026 at 6:38 PM Igor Korot <ikorot01@gmail.com> wrote:
>
>     Hi, ALL,
>     I'm looking at https://www.postgresql.org/docs/current/sql-createtable.html
>     and see some weird stuff.
>
>     When I try to search for "PRIMARY KEY" I eventually hit following:
>
>     [quote]
>     PRIMARY KEY (column constraint)
>     PRIMARY KEY ( column_name [, ... ] [, column_name WITHOUT OVERLAPS ] )
>     [ INCLUDE ( column_name [, ...]) ] (table constraint)
>     [/quote]
>
>     Now I want to check what "column_constraint" is.
>
>
> You read in an underscore in the parenthetical that isn't there.  That said, I
> concur that using a label here that so closely matches something that exists
> within the page, to mean something else, is just asking for this kind of
> confusion.

Would it be possible to set (column constraint) and (table constraint)
in the normal body font instead of monospace? That would make it clearer
that these phrases aren't part of the syntax but descriptive.

"David G. Johnston" <david.g.johnston@gmail.com> writes:
> On Monday, March 2, 2026, Peter J. Holzer <hjp-pgsql@hjp.at> wrote:
>> Would it be possible to set (column constraint) and (table constraint)
>> in the normal body font instead of monospace? That would make it clearer
>> that these phrases aren't part of the syntax but descriptive.

> Not sure, but I don’t like that as the sole solution anyway.  Too subtle.

Agreed, but we could/should do it along with modifying the text.
I thought your addition of "variant" was a good idea.
I didn't look closely at the rest of your diff.

            regards, tom lane