Re: Doc limitation update proposal: include out-of-line OID usage per TOAST-ed columns

On Wed, Apr 26, 2023 at 4:48 AM David Rowley <dgrowleyml@gmail.com> wrote:
>
> On Sun, 23 Apr 2023, 3:42 am Gurjeet Singh, <gurjeet@singh.im> wrote:
>>
>> I anticipate that edits to Appendix K Postgres Limits will prompt
>> improving the note in there about the maximum column limit, That note
>> is too wordy, and sometimes confusing, especially for the audience
>> that it's written for: newcomers to Postgres ecosystem.
>
>
> I doubt it, but feel free to submit a patch yourself which improves it without losing the information which the paragraph is trying to convey.

I could not think of a way to reduce the wordiness without losing
information. But since this page is usually consulted by those who are
new to Postgres, usually sent here by a search engine, I believe the
page can be improved for that audience, without losing much in terms
of accuracy.

I agree the information provided in the paragraph about max-columns is
pertinent. But since the limits section is most often consulted by
people migrating from other database systems (hence the claim that
they're new to the Postgres ecosystem), I imagine the terminology used
there may cause confusion for the reader. So my suggestion is to make
that paragraph, and perhaps even that page, use fewer hacker/internals
terms.

Technically, there may be a difference between table vs. relation, row
vs. tuple, and column vs. field. But using those terms, seemingly
interchangeably on that page does not help the reader. The page
neither describes the terms, nor links to their definitions, so a
reader is left with more questions than before. For example,

> rows per table:: limited by the number of tuples that can fit onto 4,294,967,295 pages

A newcomer> what's a tuple in this context, and how is it similar
to/different from a row?

Please see attached the proposed patch, which attempts to make that
language newcomer-friendly. The patch adds one link for TOAST, and
replaces Postgres-specific terms with generic ones.

PS: I've retained line boundaries, so that `git diff --color-words
doc/src/sgml/limits.sgml` would make it easy to see the changes.

Best regards,
Gurjeet
http://Gurje.et