pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedImprove "3.6. Inheritance" tutorial
8+ messages / 4 participants
[nested] [flat]
* Improve "3.6. Inheritance" tutorial
@ 2026-10-01 18:55 PG Doc comments form <noreply@postgresql.org>
0 siblings, 2 replies; 8+ messages in thread
From: PG Doc comments form @ 2026-10-01 18:55 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: matematica.a3k@gmail.com
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/18/tutorial-inheritance.html
Description:
I propose the following modifications:
- "... cities. If you're really clever you might invent some scheme like
this:"
I think it's a joke which didn't age well, "Suppose you invent..." should be
better.
- "This works OK as far as querying goes, but it gets ugly when you need to
update several rows, for one thing.
A better solution is this:"
"In this sense, a better solution is:" should be better.
- "In this case, a row of capitals inherits all columns (name, population,
and elevation) from its parent, cities. The type of the column name is text,
a native PostgreSQL type for variable length character strings. The capitals
table has an additional column, state, which shows its state abbreviation.
In PostgreSQL, a table can inherit from zero or more other tables."
This may be refactored into:
"In this case, a row of capitals inherits all columns (name, population, and
elevation) from its parent, cities. The capitals table has an additional
column, state, which shows its state abbreviation.
In PostgreSQL, a table can inherit from zero or more other tables, and a
query can reference either all rows of a table or all rows of a table plus
all of its descendant tables. The latter behavior is the default."
- "which returns:"
"Given the sample data from the PostgreSQL tutorial (see Section 2.1), this
returns::" should be clearer
- "Note
Although inheritance is frequently useful, it has not been integrated with
unique constraints or foreign keys, which limits its usefulness. See Section
5.11 for more detail."
"Inheritance has not been integrated with unique constraints or foreign
keys, which limits its usefulness. See Section 5.11 for a complete
description of the feature." should be more precise
Regards,
Rodrigo
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Improve "3.6. Inheritance" tutorial
@ 2026-10-02 06:56 David G. Johnston <david.g.johnston@gmail.com>
parent: PG Doc comments form <noreply@postgresql.org>
1 sibling, 0 replies; 8+ messages in thread
From: David G. Johnston @ 2026-10-02 06:56 UTC (permalink / raw)
To: matematica.a3k@gmail.com <matematica.a3k@gmail.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Thursday, October 1, 2026, PG Doc comments form <noreply@postgresql.org>
wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/18/tutorial-inheritance.html
> Description:
>
> I propose the following modifications:
I suggest going further and removing it from the tutorial altogether. The
inheritance chapter in data definition is sufficient, IMO.
Or maybe just make this page a simple pointer to that one.
I agree the tutorial, partly by virtue of being part of the formal
documentation, has become outdated in quite a few ways. I’m not a fan of
trying to modernize the tutorial within the confines of the formal
documentation though, when the wiki is a much more appropriate medium.
David J.
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Improve "3.6. Inheritance" tutorial
@ 2026-10-02 06:58 Laurenz Albe <laurenz.albe@cybertec.at>
parent: PG Doc comments form <noreply@postgresql.org>
1 sibling, 1 reply; 8+ messages in thread
From: Laurenz Albe @ 2026-10-02 06:58 UTC (permalink / raw)
To: matematica.a3k@gmail.com; pgsql-docs@lists.postgresql.org
On Thu, 2026-10-01 at 18:55 +0000, PG Doc comments form wrote:
> Page: https://www.postgresql.org/docs/18/tutorial-inheritance.html
>
> I propose the following modifications: [...]
Do I get you right that you don't have any problems with the
technical content, but are unhappy about the style?
I think a tutorial is free to use sloppier language, but
then that's just my opinion.
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Improve "3.6. Inheritance" tutorial
@ 2026-10-02 15:23 Matemática A3K <matematica.a3k@gmail.com>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 8+ messages in thread
From: Matemática A3K @ 2026-10-02 15:23 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: pgsql-docs@lists.postgresql.org
On Fri, Oct 2, 2026 at 3:58 AM Laurenz Albe <laurenz.albe@cybertec.at>
wrote:
> On Thu, 2026-10-01 at 18:55 +0000, PG Doc comments form wrote:
> > Page: https://www.postgresql.org/docs/18/tutorial-inheritance.html
> >
> > I propose the following modifications: [...]
>
> Do I get you right that you don't have any problems with the
> technical content, but are unhappy about the style?
>
No, I'm unhappy with both, my suggestions go in both directions.
The main technical concern is that querying is not explained on it, it's
explained on the "details page".
More in concrete, if you add "In PostgreSQL, a table can inherit from zero
or more other tables, and a query can reference either all rows of a table
or all rows of a table plus all of its descendant tables. The latter
behavior is the default." should be a "complete" explanation of the feature.
> I think a tutorial is free to use sloppier language, but
> then that's just my opinion.
>
I understand
>
> Yours,
> Laurenz Albe
>
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Improve "3.6. Inheritance" tutorial
@ 2026-10-07 14:43 Laurenz Albe <laurenz.albe@cybertec.at>
parent: Matemática A3K <matematica.a3k@gmail.com>
0 siblings, 1 reply; 8+ messages in thread
From: Laurenz Albe @ 2026-10-07 14:43 UTC (permalink / raw)
To: Matemática A3K <matematica.a3k@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
On Fri, 2026-10-02 at 12:23 -0300, Matemática A3K wrote:
> On Fri, Oct 2, 2026 at 3:58 AM Laurenz Albe <laurenz.albe@cybertec.at> wrote:
> > On Thu, 2026-10-01 at 18:55 +0000, PG Doc comments form wrote:
> > > Page: https://www.postgresql.org/docs/18/tutorial-inheritance.html
> > >
> > > I propose the following modifications: [...]
> >
> > Do I get you right that you don't have any problems with the
> > technical content, but are unhappy about the style?
>
> No, I'm unhappy with both, my suggestions go in both directions.
I must say that I perfer the original style.
But let's discuss the technical content:
> The main technical concern is that querying is not explained on it, it's
> explained on the "details page".
>
> More in concrete, if you add "In PostgreSQL, a table can inherit from zero
> or more other tables, and a query can reference either all rows of a table
> or all rows of a table plus all of its descendant tables. The latter behavior
> is the default." should be a "complete" explanation of the feature.
I think the explanation in the tutorial is quite clear:
Here the ONLY before cities indicates that the query should be run over
only the cities table, and not tables below cities in the inheritance
hierarchy. Many of the commands that we have already discussed — SELECT,
UPDATE, and DELETE — support this ONLY notation.
A tutorial is not supposed to provide a rigorous definition. Such a
definition should be in the reference manual. And indeed I find in
https://www.postgresql.org/docs/18/sql-select.html
If ONLY is specified before the table name, only that table is scanned.
If ONLY is not specified, the table and all its descendant tables
(if any) are scanned.
I'm happy with the page the way it is...
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Improve "3.6. Inheritance" tutorial
@ 2026-10-07 19:28 Matemática A3K <matematica.a3k@gmail.com>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 8+ messages in thread
From: Matemática A3K @ 2026-10-07 19:28 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: pgsql-docs@lists.postgresql.org
On Wed, Oct 7, 2026 at 11:43 AM Laurenz Albe <laurenz.albe@cybertec.at>
wrote:
> On Fri, 2026-10-02 at 12:23 -0300, Matemática A3K wrote:
> > On Fri, Oct 2, 2026 at 3:58 AM Laurenz Albe <laurenz.albe@cybertec.at>
> wrote:
> > > On Thu, 2026-10-01 at 18:55 +0000, PG Doc comments form wrote:
> > > > Page: https://www.postgresql.org/docs/18/tutorial-inheritance.html
> > > >
> > > > I propose the following modifications: [...]
> > >
> > > Do I get you right that you don't have any problems with the
> > > technical content, but are unhappy about the style?
> >
> > No, I'm unhappy with both, my suggestions go in both directions.
>
> I must say that I perfer the original style.
> But let's discuss the technical content:
>
OK
> > The main technical concern is that querying is not explained on it, it's
> > explained on the "details page".
> >
> > More in concrete, if you add "In PostgreSQL, a table can inherit from
> zero
> > or more other tables, and a query can reference either all rows of a
> table
> > or all rows of a table plus all of its descendant tables. The latter
> behavior
> > is the default." should be a "complete" explanation of the feature.
>
> I think the explanation in the tutorial is quite clear:
>
> Here the ONLY before cities indicates that the query should be run over
> only the cities table, and not tables below cities in the inheritance
> hierarchy. Many of the commands that we have already discussed — SELECT,
> UPDATE, and DELETE — support this ONLY notation.
>
Here, "quite clear" is the discrepancy.
After careful re-reading, the concepts are there, so it is "technically
correct" in that sense.
My point arose from the first iteration on it. If you follow the link at
the end of the page for more details, you end up reading an extended
tutorial, which I find to be "complete" on the subject.
Once you read the extended tutorial, the "summarized" tutorial (the page we
are discussing) becomes "clear" and "technically correct".
My impression is that this happens *after* you read the full version, adding
that sentence to the summary would make it more clear for some users.
> A tutorial is not supposed to provide a rigorous definition. Such a
> definition should be in the reference manual.
And indeed I find in
> https://www.postgresql.org/docs/18/sql-select.html
>
> If ONLY is specified before the table name, only that table is scanned.
> If ONLY is not specified, the table and all its descendant tables
> (if any) are scanned.
>
> I'm happy with the page the way it is...
>
OK, an "arguably" improvement is not worth submitting, can you confirm this
so this conversation becomes "finished" to me? Thanks!
> Yours,
> Laurenz Albe
>
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Improve "3.6. Inheritance" tutorial
@ 2026-10-07 21:00 Laurenz Albe <laurenz.albe@cybertec.at>
parent: Matemática A3K <matematica.a3k@gmail.com>
0 siblings, 1 reply; 8+ messages in thread
From: Laurenz Albe @ 2026-10-07 21:00 UTC (permalink / raw)
To: Matemática A3K <matematica.a3k@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
On Wed, 2026-10-07 at 16:28 -0300, Matemática A3K wrote:
> On Wed, Oct 7, 2026 at 11:43 AM Laurenz Albe <laurenz.albe@cybertec.at> wrote:
> > On Fri, 2026-10-02 at 12:23 -0300, Matemática A3K wrote:
> >
> >
> > > The main technical concern is that querying is not explained on it, it's
> > > explained on the "details page".
> > >
> > > More in concrete, if you add "In PostgreSQL, a table can inherit from zero
> > > or more other tables, and a query can reference either all rows of a table
> > > or all rows of a table plus all of its descendant tables. The latter behavior
> > > is the default." should be a "complete" explanation of the feature.
> >
> > I think the explanation in the tutorial is quite clear:
> >
> > Here the ONLY before cities indicates that the query should be run over
> > only the cities table, and not tables below cities in the inheritance
> > hierarchy. Many of the commands that we have already discussed — SELECT,
> > UPDATE, and DELETE — support this ONLY notation.
>
> Here, "quite clear" is the discrepancy.
>
> [...]
>
> My impression is that this happens *after* you read the full version, adding that
> sentence to the summary would make it more clear for some users.
I personally am not convinced, but perhaps others agree with you.
Do you want to prepare a patch?
I think it would be best if we can avoid repeating the same information
in several places. Such redundancy inflates the documentation and makes
it harder to find all places that have to be fixed when something changes.
Perhaps you can move things around to avoid that.
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Improve "3.6. Inheritance" tutorial
@ 2026-10-08 16:05 Matemática A3K <matematica.a3k@gmail.com>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 0 replies; 8+ messages in thread
From: Matemática A3K @ 2026-10-08 16:05 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: pgsql-docs@lists.postgresql.org
On Wed, Oct 7, 2026 at 6:00 PM Laurenz Albe <laurenz.albe@cybertec.at>
wrote:
> On Wed, 2026-10-07 at 16:28 -0300, Matemática A3K wrote:
> > On Wed, Oct 7, 2026 at 11:43 AM Laurenz Albe <laurenz.albe@cybertec.at>
> wrote:
> > > On Fri, 2026-10-02 at 12:23 -0300, Matemática A3K wrote:
> > >
> > >
> > > > The main technical concern is that querying is not explained on it,
> it's
> > > > explained on the "details page".
> > > >
> > > > More in concrete, if you add "In PostgreSQL, a table can inherit
> from zero
> > > > or more other tables, and a query can reference either all rows of a
> table
> > > > or all rows of a table plus all of its descendant tables. The latter
> behavior
> > > > is the default." should be a "complete" explanation of the feature.
> > >
> > > I think the explanation in the tutorial is quite clear:
> > >
> > > Here the ONLY before cities indicates that the query should be run
> over
> > > only the cities table, and not tables below cities in the inheritance
> > > hierarchy. Many of the commands that we have already discussed —
> SELECT,
> > > UPDATE, and DELETE — support this ONLY notation.
> >
> > Here, "quite clear" is the discrepancy.
> >
> > [...]
> >
> > My impression is that this happens *after* you read the full version,
> adding that
> > sentence to the summary would make it more clear for some users.
>
> I personally am not convinced, but perhaps others agree with you.
>
No one is speaking up so far, let's see if we can come up with something
more clear or better.
Do you want to prepare a patch?
No problem, but let's keep iterating on this to see if we can arrive at an
even better solution.
>
> I think it would be best if we can avoid repeating the same information
> in several places. Such redundancy inflates the documentation and makes
> it harder to find all places that have to be fixed when something changes.
> Perhaps you can move things around to avoid that.
>
In this direction, if the "basic" tutorial is sourced from the "full"
tutorial, a comment on the
documentation should be put ("This is sourced as a basic tutorial, this
section should give
an overview of the feature and be self-contained.") and then, rewrite the
following to glue it.
The full tutorial should be:
- Overview
- Details
- Caveats
and the basic tutorial should be:
- Source from Overview
- Note: "If you find this feature useful for your case, continue reading
here where you will find
a more detailed discussion and the caveats to consider."
Something like this is what came to your mind?
^ permalink raw reply [nested|flat] 8+ messages in thread
end of thread, other threads:[~2026-10-08 16:05 UTC | newest]
Thread overview: 8+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2026-10-01 18:55 Improve "3.6. Inheritance" tutorial PG Doc comments form <noreply@postgresql.org>
2026-10-02 06:56 ` David G. Johnston <david.g.johnston@gmail.com>
2026-10-02 06:58 ` Laurenz Albe <laurenz.albe@cybertec.at>
2026-10-02 15:23 ` Matemática A3K <matematica.a3k@gmail.com>
2026-10-07 14:43 ` Laurenz Albe <laurenz.albe@cybertec.at>
2026-10-07 19:28 ` Matemática A3K <matematica.a3k@gmail.com>
2026-10-07 21:00 ` Laurenz Albe <laurenz.albe@cybertec.at>
2026-10-08 16:05 ` 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