pg.ddx.io  pgsql-docs@postgresql.org mailing list archive  
help / color / mirror / Atom feed
5.12.2.1. Example
7+ messages / 4 participants
[nested] [flat]

* 5.12.2.1. Example
@ 2026-10-21 14:47 PG Doc comments form <noreply@postgresql.org>
  2026-10-23 08:11 ` Re: 5.12.2.1. Example Daniel Gustafsson <daniel@yesql.se>
  0 siblings, 1 reply; 7+ messages in thread

From: PG Doc comments form @ 2026-10-21 14:47 UTC (permalink / raw)
  To: pgsql-docs@lists.postgresql.org; +Cc: jonas.rosenthal@protechninjas.com

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






^ permalink  raw  reply  [nested|flat] 7+ messages in thread

* Re: 5.12.2.1. Example
  2026-10-21 14:47 5.12.2.1. Example PG Doc comments form <noreply@postgresql.org>
@ 2026-10-23 08:11 ` Daniel Gustafsson <daniel@yesql.se>
  2026-10-23 08:33   ` Re: 5.12.2.1. Example David Rowley <dgrowleyml@gmail.com>
  0 siblings, 1 reply; 7+ messages in thread

From: Daniel Gustafsson @ 2026-10-23 08:11 UTC (permalink / raw)
  To: jonas.rosenthal@protechninjas.com; pgsql-docs@lists.postgresql.org

> 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







^ permalink  raw  reply  [nested|flat] 7+ messages in thread

* Re: 5.12.2.1. Example
  2026-10-21 14:47 5.12.2.1. Example PG Doc comments form <noreply@postgresql.org>
  2026-10-23 08:11 ` Re: 5.12.2.1. Example Daniel Gustafsson <daniel@yesql.se>
@ 2026-10-23 08:33   ` David Rowley <dgrowleyml@gmail.com>
  2026-10-23 08:34     ` Re: 5.12.2.1. Example David Rowley <dgrowleyml@gmail.com>
  2026-10-23 08:44     ` Re: 5.12.2.1. Example Daniel Gustafsson <daniel@yesql.se>
  0 siblings, 2 replies; 7+ messages in thread

From: David Rowley @ 2026-10-23 08:33 UTC (permalink / raw)
  To: Daniel Gustafsson <daniel@yesql.se>; +Cc: jonas.rosenthal@protechninjas.com; pgsql-docs@lists.postgresql.org

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





^ permalink  raw  reply  [nested|flat] 7+ messages in thread

* Re: 5.12.2.1. Example
  2026-10-21 14:47 5.12.2.1. Example PG Doc comments form <noreply@postgresql.org>
  2026-10-23 08:11 ` Re: 5.12.2.1. Example Daniel Gustafsson <daniel@yesql.se>
  2026-10-23 08:33   ` Re: 5.12.2.1. Example David Rowley <dgrowleyml@gmail.com>
@ 2026-10-23 08:34     ` David Rowley <dgrowleyml@gmail.com>
  1 sibling, 0 replies; 7+ messages in thread

From: David Rowley @ 2026-10-23 08:34 UTC (permalink / raw)
  To: Daniel Gustafsson <daniel@yesql.se>; +Cc: jonas.rosenthal@protechninjas.com; pgsql-docs@lists.postgresql.org

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






^ permalink  raw  reply  [nested|flat] 7+ messages in thread

* Re: 5.12.2.1. Example
  2026-10-21 14:47 5.12.2.1. Example PG Doc comments form <noreply@postgresql.org>
  2026-10-23 08:11 ` Re: 5.12.2.1. Example Daniel Gustafsson <daniel@yesql.se>
  2026-10-23 08:33   ` Re: 5.12.2.1. Example David Rowley <dgrowleyml@gmail.com>
@ 2026-10-23 08:44     ` Daniel Gustafsson <daniel@yesql.se>
  2026-10-23 08:53       ` Re: 5.12.2.1. Example David Rowley <dgrowleyml@gmail.com>
  1 sibling, 1 reply; 7+ messages in thread

From: Daniel Gustafsson @ 2026-10-23 08:44 UTC (permalink / raw)
  To: David Rowley <dgrowleyml@gmail.com>; +Cc: jonas.rosenthal@protechninjas.com; pgsql-docs@lists.postgresql.org

> 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






^ permalink  raw  reply  [nested|flat] 7+ messages in thread

* Re: 5.12.2.1. Example
  2026-10-21 14:47 5.12.2.1. Example PG Doc comments form <noreply@postgresql.org>
  2026-10-23 08:11 ` Re: 5.12.2.1. Example Daniel Gustafsson <daniel@yesql.se>
  2026-10-23 08:33   ` Re: 5.12.2.1. Example David Rowley <dgrowleyml@gmail.com>
  2026-10-23 08:44     ` Re: 5.12.2.1. Example Daniel Gustafsson <daniel@yesql.se>
@ 2026-10-23 08:53       ` David Rowley <dgrowleyml@gmail.com>
  2026-10-23 15:38         ` Re: 5.12.2.1. Example Matemática A3K <matematica.a3k@gmail.com>
  0 siblings, 1 reply; 7+ messages in thread

From: David Rowley @ 2026-10-23 08:53 UTC (permalink / raw)
  To: Daniel Gustafsson <daniel@yesql.se>; +Cc: jonas.rosenthal@protechninjas.com; pgsql-docs@lists.postgresql.org

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






^ permalink  raw  reply  [nested|flat] 7+ messages in thread

* Re: 5.12.2.1. Example
  2026-10-21 14:47 5.12.2.1. Example PG Doc comments form <noreply@postgresql.org>
  2026-10-23 08:11 ` Re: 5.12.2.1. Example Daniel Gustafsson <daniel@yesql.se>
  2026-10-23 08:33   ` Re: 5.12.2.1. Example David Rowley <dgrowleyml@gmail.com>
  2026-10-23 08:44     ` Re: 5.12.2.1. Example Daniel Gustafsson <daniel@yesql.se>
  2026-10-23 08:53       ` Re: 5.12.2.1. Example David Rowley <dgrowleyml@gmail.com>
@ 2026-10-23 15:38         ` Matemática A3K <matematica.a3k@gmail.com>
  0 siblings, 0 replies; 7+ messages in thread

From: Matemática A3K @ 2026-10-23 15:38 UTC (permalink / raw)
  To: David Rowley <dgrowleyml@gmail.com>; +Cc: Daniel Gustafsson <daniel@yesql.se>; jonas.rosenthal@protechninjas.com; pgsql-docs@lists.postgresql.org

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.






^ permalink  raw  reply  [nested|flat] 7+ messages in thread


end of thread, other threads:[~2026-10-23 15:38 UTC | newest]

Thread overview: 7+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2026-10-21 14:47 5.12.2.1. Example PG Doc comments form <noreply@postgresql.org>
2026-10-23 08:11 ` Daniel Gustafsson <daniel@yesql.se>
2026-10-23 08:33   ` David Rowley <dgrowleyml@gmail.com>
2026-10-23 08:34     ` David Rowley <dgrowleyml@gmail.com>
2026-10-23 08:44     ` Daniel Gustafsson <daniel@yesql.se>
2026-10-23 08:53       ` David Rowley <dgrowleyml@gmail.com>
2026-10-23 15:38         ` Matemática A3K <matematica.a3k@gmail.com>

This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox