5.12.2.1. Example

Started by PG Bug reporting formabout 1 month ago7 messagesdocs
Jump to latest
#1PG Bug reporting form
noreply@postgresql.org

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/18/ddl-partitioning.html
Description:

The syntax in the example do now allow the sub-partition to be created. The
sub partition errors out.

Thank You.

Jonas

#2Daniel Gustafsson
daniel@yesql.se
In reply to: PG Bug reporting form (#1)
Re: 5.12.2.1. Example

On 21 Oct 2026, at 16:47, PG Doc comments form <noreply@postgresql.org> wrote:

Page: https://www.postgresql.org/docs/18/ddl-partitioning.html
Description:

The syntax in the example do now allow the sub-partition to be created. The
sub partition errors out.

This page contains many examples, please specify which it is you find
problematic and paste the error message from postgres.

--
Daniel Gustafsson

#3David Rowley
dgrowleyml@gmail.com
In reply to: Daniel Gustafsson (#2)
Re: 5.12.2.1. Example

On Fri, 23 Oct 2026 at 21:12, Daniel Gustafsson <daniel@yesql.se> wrote:

This page contains many examples, please specify which it is you find
problematic and paste the error message from postgres.

Let's wait and see, but I suspect it's the "...".

Maybe those would be better as comments, something like?

CREATE TABLE measurement_y2006m03 PARTITION OF measurement
FOR VALUES FROM ('2006-03-01') TO ('2006-04-01');

-- plus y2006m04 .. y2007m10 (abbreviation for brevity)

CREATE TABLE measurement_y2007m11 PARTITION OF measurement
FOR VALUES FROM ('2007-11-01') TO ('2007-12-01');

David

#4David Rowley
dgrowleyml@gmail.com
In reply to: David Rowley (#3)
Re: 5.12.2.1. Example

On Fri, 23 Oct 2026 at 21:33, David Rowley <dgrowleyml@gmail.com> wrote:

-- plus y2006m04 .. y2007m10 (abbreviation for brevity)

"abbreviated" I meant to say.

David

#5Daniel Gustafsson
daniel@yesql.se
In reply to: David Rowley (#3)
Re: 5.12.2.1. Example

On 23 Oct 2026, at 10:33, David Rowley <dgrowleyml@gmail.com> wrote:

On Fri, 23 Oct 2026 at 21:12, Daniel Gustafsson <daniel@yesql.se> wrote:

This page contains many examples, please specify which it is you find
problematic and paste the error message from postgres.

Let's wait and see, but I suspect it's the "...".

Maybe those would be better as comments, something like?

CREATE TABLE measurement_y2006m03 PARTITION OF measurement
FOR VALUES FROM ('2006-03-01') TO ('2006-04-01');

-- plus y2006m04 .. y2007m10 (abbreviation for brevity)

Or perhaps "-- repeated for y2006m04 .. y2007m10 (abbreviated for brevity)"

CREATE TABLE measurement_y2007m11 PARTITION OF measurement
FOR VALUES FROM ('2007-11-01') TO ('2007-12-01');

If someone copy pastes the entire block I fear that they think it's a complete
example, and when it isn't then perhaps getting a syntax error is better?

That being said, replacing "..." is a good idea regardless of being a comment
or not, your suggestion makes the docs more readable,

--
Daniel Gustafsson

#6David Rowley
dgrowleyml@gmail.com
In reply to: Daniel Gustafsson (#5)
Re: 5.12.2.1. Example

On Fri, 23 Oct 2026 at 21:45, Daniel Gustafsson <daniel@yesql.se> wrote:

On 23 Oct 2026, at 10:33, David Rowley <dgrowleyml@gmail.com> wrote:
-- plus y2006m04 .. y2007m10 (abbreviation for brevity)

Or perhaps "-- repeated for y2006m04 .. y2007m10 (abbreviated for brevity)"

or "repeat", as in, we're asking them to do it.

If someone copy pastes the entire block I fear that they think it's a complete
example, and when it isn't then perhaps getting a syntax error is better?

I think as long as there are no errors to say table yNNNNmNN does not
exist between all the example there, it's probably fine. I do see the
trigger function example doesn't contain all the tables that were
created, but I think that's fine. Making that example longer to fix
that wouldn't make it any more readable. I don't think we promise
fully working examples. IMO, they're aimed to be a guide for learning.

That being said, replacing "..." is a good idea regardless of being a comment
or not, your suggestion makes the docs more readable,

I'm happy to review a patch.

David

#7Matemática A3K
matematica.a3k@gmail.com
In reply to: David Rowley (#6)
Re: 5.12.2.1. Example

On Fri, Oct 23, 2026 at 5:54 AM David Rowley <dgrowleyml@gmail.com> wrote:

On Fri, 23 Oct 2026 at 21:45, Daniel Gustafsson <daniel@yesql.se> wrote:

On 23 Oct 2026, at 10:33, David Rowley <dgrowleyml@gmail.com> wrote:
-- plus y2006m04 .. y2007m10 (abbreviation for brevity)

Or perhaps "-- repeated for y2006m04 .. y2007m10 (abbreviated for brevity)"

or "repeat", as in, we're asking them to do it.

If this example was what originated the message, your proposed changes
raises the
following in my mind:

The paragraph goes "So the commands might look like: (EXAMPLE)", to substitute
the ellipsis with "-- repeat for y2006m04 .. y2007m10 (abbreviated for
brevity)" will
add an inconsistency with that statement.

Using something like "-- statements for creating remaining partitions
to cover the whole space"
might be better, however, I think the ellipsis does a good job
conveying the idea with
greater brevity IMO.

The problem is not "an example does not run", if it was, then a fix
with a working example
should be delivered.

The problem, IMO, is "Misaligned expectations about examples from a part of the
audience". This seems to be the cause of several messages in the mailing list.

A solution for this would be adding "somewhere at the beginning" of
the doc something like
"Examples may not work, they are aimed to be a guide for learning. In
the case of
not working, understanding why will provide a better understanding of
what the example
is meant to convey".

When a message originating from this arrives, it can be handled by
routing to this explanation.