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.
v1-0001-DOCS-Generated-Column-Replication-Examples.patch
Description: Binary data
