Improve "3.6. Inheritance" tutorial
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
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.
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
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
Show quoted text
Yours,
Laurenz Albe
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
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!
Show quoted text
Yours,
Laurenz Albe
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
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?
On Thu, Oct 8, 2026 at 9:06 AM Matemática A3K <matematica.a3k@gmail.com>
wrote:
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
- Caveatsand 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?
Seems like an all-or-nothing proposal that is quite different from what is
done today and doesn't contribute significant added value.
The interplay between the tutorial and the authoritative reference sections
are substantially correct today. I'd advise making any changes try and fit
within the current setup rather than trying to redesign the entire thing.
David J.
"David G. Johnston" <david.g.johnston@gmail.com> writes:
Seems like an all-or-nothing proposal that is quite different from what is
done today and doesn't contribute significant added value.
The interplay between the tutorial and the authoritative reference sections
are substantially correct today. I'd advise making any changes try and fit
within the current setup rather than trying to redesign the entire thing.
Not too long ago there was discussion of removing the tutorial's
discussion of inheritance entirely, on the grounds that it's a legacy
feature people don't use much anymore. (They do use partitioning,
which is built on much the same infrastructure, but it presents as a
completely different thing.) I could see doing that, or replacing
the section with something about partitioning, but I can't get excited
about putting significant work into that section with its current
charter.
regards, tom lane
On Thu, Oct 8, 2026 at 3:09 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
"David G. Johnston" <david.g.johnston@gmail.com> writes:
Seems like an all-or-nothing proposal that is quite different from what
is
done today and doesn't contribute significant added value.
The interplay between the tutorial and the authoritative referencesections
are substantially correct today. I'd advise making any changes try and
fit
within the current setup rather than trying to redesign the entire thing.
I also agree with this point
Not too long ago there was discussion of removing the tutorial's
discussion of inheritance entirely, on the grounds that it's a legacy
feature people don't use much anymore. (They do use partitioning,
which is built on much the same infrastructure, but it presents as a
completely different thing.) I could see doing that, or replacing
the section with something about partitioning, but I can't get excited
about putting significant work into that section with its current
charter.
I see other people have come to similar concerns than me - I personally
find this feature may induce
bad database design from my POV and only make sense for partitioning.
However, the feature
is there, so the docs should reflect it. It should be removed from the docs
if the feature is dropped, but
that would be a discussion for other mailing list.
I also share your impression about partitioning, a tutorial should be made
for it as it is done for inheritance.
I'll make a proposal for it after I finish my first iteration on the book
in a new thread.
I'm stuck in this thread, I can't resolve the contradiction between "This
is small improvement" and "Maybe
but isn't worthy", in my mind both are right.
I'll accept the second, have a new direction with what Tom said and have
better documentation guidelines.
This is what I can make out of the effort put in this, so it's not wasted.
Thanks everyone!
Show quoted text
regards, tom lane
On Thu, Oct 8, 2026 at 11:54 AM Matemática A3K <matematica.a3k@gmail.com>
wrote:
However, the feature
is there, so the docs should reflect it. It should be removed from the docs
if the feature is dropped, but
that would be a discussion for other mailing list.
This stays:
https://www.postgresql.org/docs/current/ddl-inherit.html
This goes:
https://www.postgresql.org/docs/current/tutorial-inheritance.html
It's still documented; it isn't worth having in the tutorial.
David J.