public inbox for [email protected]
help / color / mirror / Atom feedFrom: Peter Smith <[email protected]>
To: PostgreSQL Hackers <[email protected]>
Subject: DOCS: Describe some missing parameters on CREATE/ALTER PUBLICATION pages
Date: Wed, 8 Apr 2026 15:10:50 +1000
Message-ID: <CAHut+Ptekz+TO4ui8-fiBm4Y+O2v=HQnkK_cW4G=w9ep8654EA@mail.gmail.com> (raw)
Hi.
I noticed that the CREATE PUBLICATION and ALTER PUBLICATION sysnopses
contain some user-specified parameters which are not defined, and not
even mentioned anywhere else.
For example,
ALTER PUBLICATION
- defines 'name', 'table_name', 'schema_name'
- never mentions 'column_name'
CREATE PUBLICATION
- defines 'name'
- never mentions 'table_name', 'schema_name', 'column_name'
~~~
It seems wrong to include undefined synopsis parameters and just
assume they will be self-explanatory.
It is ad-hoc; some terms are described on one page but not on the other.
~
PSA a small patch to make these parameter descriptions more complete
and consistent.
In passing, I also added some missing <varlistentry> "id"s for the
ALTER PUBLICATION page.
======
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
[application/octet-stream] v1-0001-Add-missing-parameters.patch (6.7K, 2-v1-0001-Add-missing-parameters.patch)
download | inline diff:
From 5d394e65625393561cc8a9b99ef897d3b74157fd Mon Sep 17 00:00:00 2001
From: Peter Smith <[email protected]>
Date: Wed, 8 Apr 2026 13:33:21 +1000
Subject: [PATCH v1] Add missing parameters
---
doc/src/sgml/ref/alter_publication.sgml | 32 +++++++++++-----
doc/src/sgml/ref/create_publication.sgml | 48 ++++++++++++++++++++----
2 files changed, 62 insertions(+), 18 deletions(-)
diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index aa32bb169e9..9853ee5ff91 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -163,19 +163,21 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
<listitem>
<para>
Name of an existing table. If <literal>ONLY</literal> is specified before the
- table name, only that table is affected. If <literal>ONLY</literal> is not
- specified, the table and all its descendant tables (if any) are
- affected. Optionally, <literal>*</literal> can be specified after the table
- name to explicitly indicate that descendant tables are included.
+ <replaceable class="parameter">table_name</replaceable>, only that table
+ is affected. If <literal>ONLY</literal> is not specified, the table and
+ all its descendant tables (if any) are affected. Optionally,
+ <literal>*</literal> can be specified after the
+ <replaceable class="parameter">table_name</replaceable> to explicitly
+ indicate that descendant tables are included.
</para>
<para>
- Optionally, a column list can be specified. See <xref
- linkend="sql-createpublication"/> for details. Note that a subscription
- having several publications in which the same table has been published
- with different column lists is not supported. See
- <xref linkend="logical-replication-col-list-combining"/> for details of
- potential problems when altering column lists.
+ Optionally, a <replaceable class="parameter">column_name</replaceable>
+ list can be specified. See <xref linkend="sql-createpublication"/> for
+ details. Note that a subscription having several publications in which
+ the same table has been published with different column lists is not
+ supported. See <xref linkend="logical-replication-col-list-combining"/>
+ for details of potential problems when altering column lists.
</para>
<para>
@@ -189,6 +191,16 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><replaceable class="parameter">column_name</replaceable></term>
+ <listitem>
+ <para>
+ Name of an existing column of table
+ <replaceable class="parameter">table_name</replaceable>
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><replaceable class="parameter">schema_name</replaceable></term>
<listitem>
diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
index 0ac576d3f10..d26d75c7962 100644
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -79,15 +79,45 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
</listitem>
</varlistentry>
+ <varlistentry id="sql-createpublication-params-table_name">
+ <term><replaceable class="parameter">table_name</replaceable></term>
+ <listitem>
+ <para>
+ Name of an existing table.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="sql-createpublication-params-column_name">
+ <term><replaceable class="parameter">column_name</replaceable></term>
+ <listitem>
+ <para>
+ Name of an existing column of table
+ <replaceable class="parameter">table_name</replaceable>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="sql-createpublication-params-schema_name">
+ <term><replaceable class="parameter">schmema_name</replaceable></term>
+ <listitem>
+ <para>
+ Name of an existing schema.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry id="sql-createpublication-params-for-table">
<term><literal>FOR TABLE</literal></term>
<listitem>
<para>
Specifies a list of tables to add to the publication. If
- <literal>ONLY</literal> is specified before the table name, only
+ <literal>ONLY</literal> is specified before the
+ <replaceable class="parameter">table_name</replaceable>, only
that table is added to the publication. If <literal>ONLY</literal> is not
specified, the table and all its descendant tables (if any) are added.
- Optionally, <literal>*</literal> can be specified after the table name to
+ Optionally, <literal>*</literal> can be specified after the
+ <replaceable class="parameter">table_name</replaceable> to
explicitly indicate that descendant tables are included.
This does not apply to a partitioned table, however. The partitions of
a partitioned table are always implicitly considered part of the
@@ -104,7 +134,8 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
</para>
<para>
- When a column list is specified, only the named columns are replicated.
+ When a <replaceable class="parameter">column_name</replaceable> list is
+ specified, only the named columns are replicated.
The column list can contain stored generated columns as well. If the
column list is omitted, the publication will replicate all non-generated
columns (including any added in the future) by default. Stored generated
@@ -202,11 +233,12 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
</para>
<para>
For inherited tables, if <literal>ONLY</literal> is specified before the
- table name, only that table is excluded from the publication. If
- <literal>ONLY</literal> is not specified, the table and all its descendant
- tables (if any) are excluded. Optionally, <literal>*</literal> can be
- specified after the table name to explicitly indicate that descendant
- tables are excluded.
+ <replaceable class="parameter">table_name</replaceable>, only that table
+ is excluded from the publication. If <literal>ONLY</literal> is not
+ specified, the table and all its descendant tables (if any) are excluded.
+ Optionally, <literal>*</literal> can be specified after the
+ <replaceable class="parameter">table_name</replaceable> to explicitly
+ indicate that descendant tables are excluded.
</para>
<para>
For partitioned tables, only the root partitioned table may be specified
--
2.47.3
[application/octet-stream] v1-0002-Add-missing-varlistentry-ids.patch (2.9K, 3-v1-0002-Add-missing-varlistentry-ids.patch)
download | inline diff:
From d85da98643831023e885d76132be11cf38f8781d Mon Sep 17 00:00:00 2001
From: Peter Smith <[email protected]>
Date: Wed, 8 Apr 2026 13:40:42 +1000
Subject: [PATCH v1] Add missing varlistentry ids
---
doc/src/sgml/ref/alter_publication.sgml | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index 9853ee5ff91..3cf4bcbc17f 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -149,7 +149,7 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
<title>Parameters</title>
<variablelist>
- <varlistentry>
+ <varlistentry id="sql-alterpublication-params-name">
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
@@ -158,7 +158,7 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-alterpublication-params-table_name">
<term><replaceable class="parameter">table_name</replaceable></term>
<listitem>
<para>
@@ -191,7 +191,7 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-alterpublication-params-column_name">
<term><replaceable class="parameter">column_name</replaceable></term>
<listitem>
<para>
@@ -201,7 +201,7 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-alterpublication-params-schema_name">
<term><replaceable class="parameter">schema_name</replaceable></term>
<listitem>
<para>
@@ -210,7 +210,7 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-alterpublication-params-set-parameter">
<term><literal>SET ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
<listitem>
<para>
@@ -236,7 +236,7 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-alterpublication-params-new_owner">
<term><replaceable class="parameter">new_owner</replaceable></term>
<listitem>
<para>
@@ -245,7 +245,7 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-alterpublication-params-new_name">
<term><replaceable class="parameter">new_name</replaceable></term>
<listitem>
<para>
--
2.47.3
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected]
Subject: Re: DOCS: Describe some missing parameters on CREATE/ALTER PUBLICATION pages
In-Reply-To: <CAHut+Ptekz+TO4ui8-fiBm4Y+O2v=HQnkK_cW4G=w9ep8654EA@mail.gmail.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox