Horton
Menu

Thread

  1. Documentation weirdness

    Igor Korot <ikorot01@gmail.com> — 2026-03-02T01:38:35Z

    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.

  2. Re: Documentation weirdness

    Adrian Klaver <adrian.klaver@aklaver.com> — 2026-03-02T01:52:42Z

    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

  3. Re: Documentation weirdness

    David G. Johnston <david.g.johnston@gmail.com> — 2026-03-02T02:08:48Z

    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.

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> closing element 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>
(table constraint 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.

  4. Re: Documentation weirdness

    Igor Korot <ikorot01@gmail.com> — 2026-03-02T02:49:09Z

    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 closely matches 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> closing element 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> (table constraint 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.
>
>

  5. Re: Documentation weirdness

    Peter J. Holzer <hjp-pgsql@hjp.at> — 2026-03-02T18:29:08Z

    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!"

  6. Re: Documentation weirdness

    David G. Johnston <david.g.johnston@gmail.com> — 2026-03-02T18:36:09Z

    On Monday, March 2, 2026, Peter J. Holzer <hjp-pgsql@hjp.at> wrote:

> 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.
>
>
Not sure, but I don’t like that as the sole solution anyway.  Too subtle.
If three words is too long, replacing constraint with variant, instead of
adding it, would suffice IMO.

David J.

  7. Re: Documentation weirdness

    Tom Lane <tgl@sss.pgh.pa.us> — 2026-03-02T18:42:26Z

    "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

  8. Re: Documentation weirdness

    David G. Johnston <david.g.johnston@gmail.com> — 2026-03-02T23:27:35Z

    On Mon, Mar 2, 2026 at 11:42 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:

> "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.
>
>
The apparent reason the entire row is monospace is because it's all within
a <term> element inside a <varlistentry>.  We'd probably have to put
something around the <term> to make this work - I have no clue what if
anything that might be.  If someone knows the solution here, ok, but the
wording change is more than enough to solve the problem (and this probably
the only instance of this "problem" in the docs) so I don't intend to go
diving down that rabbit hole.

<varlistentry id="sql-createtable-parms-primary-key">
<term><literal>PRIMARY KEY</literal> (column constraint)</term>
<term><literal>PRIMARY KEY...(table constraint)</term>

Can't just move the </term> before the (... constraint) labels.

David J.

  9. Re: Documentation weirdness

    David G. Johnston <david.g.johnston@gmail.com> — 2026-03-02T23:32:44Z

    On Mon, Mar 2, 2026 at 4:27 PM David G. Johnston <david.g.johnston@gmail.com>
wrote:

> (and this probably the only instance of this "problem" in the docs)
>

Wrote that too quickly...the REFERENCES/FOREIGN KEY description entry on
the same page needs the same label wording changes.  The markup for that is
correct.

Those exact labels do not appear elsewhere in the repo, which seems
reasonable.

David J.

  10. Re: Documentation weirdness

    David G. Johnston <david.g.johnston@gmail.com> — 2026-04-03T17:26:19Z

    On Mon, Mar 2, 2026 at 3:32 PM David G. Johnston <david.g.johnston@gmail.com>
wrote:

> On Mon, Mar 2, 2026 at 4:27 PM David G. Johnston <
> david.g.johnston@gmail.com> wrote:
>
>> (and this probably the only instance of this "problem" in the docs)
>>
>
> Wrote that too quickly...the REFERENCES/FOREIGN KEY description entry on
> the same page needs the same label wording changes.  The markup for that is
> correct.
>
> Those exact labels do not appear elsewhere in the repo, which seems
> reasonable.
>
>
I've moved this over to -hackers.

https://www.postgresql.org/message-id/CAKFQuwbsGWx5msYbRsWrRs+ss1k0utDHEhVq5unAKODQ9YOf9w@mail.gmail.com

David J.