DOCS - Generated Column Replication Examples

Hi,

A recent commit [1] added a new section "29.6. Generated Column
Replication" to the documentation [2]. But, no "Examples" were
included.

I've created this new thread to make a case for adding an "Examples"
subsection to that page.

(the proposed examples patch is attached)

======

1. Reasons AGAINST Adding Examples to this section (and why I disagree):

1a. The necessary information to describe the feature can already be
found in the text.

Yes, the documentation describes the feature, as it should. However,
examples serve a different purpose: they reinforce understanding by
demonstrating how the feature works in practice. They don’t introduce
new details; they clarify and illustrate existing ones.

1b. I can understand the feature without needing examples.

PostgreSQL serves a diverse user base with different levels of
expertise and learning styles. While experienced users might grasp the
feature quickly, others may struggle with dense explanatory text and
behaviour matrices. Why knowingly make it harder for them? If examples
can help some users, and others can simply skip them, there's no
downside to including them.

1c. Too many examples will swamp the page.

Agreed—too many examples would be excessive. That’s why the proposed
patch includes only a couple of well-chosen cases, rather than
covering every possible combination. This keeps the documentation
focused and useful without overwhelming the reader.

~~~

2. Reasons FOR Adding Examples to this section:

2a. To emphasise some special and/or subtle rules.

Some critical details—like how publication column lists override the
publish_generated_columns setting—are easy to overlook in a dense set
of behaviour rules. An example makes this clear by demonstrating the
effect directly, ensuring users don't miss it.

2b. To make it easy for users to try it themselves.

These examples are self-contained including the necessary
publication/subscription and tables. A user can simply cut/paste these
to PSQL and begin experimenting with the feature immediately, instead
of piecing together a working setup from scattered explanations. This
reduces friction and encourages hands-on learning.

2c. It may become inevitable later anyway.

With the eventual introduction of VIRTUAL generated columns,
replication behaviour will become even more complex, requiring more
rules and expanded behaviour matrices. Including examples now lays the
groundwork for future enhancements

~~~

Thoughts?

======
[1] https://github.com/postgres/postgres/commit/6252b1eaf82bb8db361341d1c8651e43b29be816#diff-e593b875ae1b49848e9954e7a3ea26fb34de7454b338a0029aec72b0fb25bb0a
[2] https://www.postgresql.org/docs/devel/logical-replication-gencols.html

Kind Regards,
Peter Smith.
Fujitsu Australia.