CREATE/ALTER PUBLICATION improvements for syntax synopsis
During some recent reviews in this area, I noticed both CREATE/ALTER
PUBLICATION synopses say:
----------
where publication_object is one of:
TABLE [ ONLY ] table_name [ * ] [ ( column_name [, ... ] ) ] [
WHERE ( expression ) ] [, ... ]
TABLES IN SCHEMA { schema_name | CURRENT_SCHEMA } [, ... ]
----------
IMO it would be better to include another pair of { } preceding the
TABLE ellipsis:
a) for consistency with the second (TABLES IN SCHEMA) case
b) to help remove ambiguity, what part of the syntax the TABLE ellipsis is for
e.g.
----------
TABLE { [ ONLY ] table_name [ * ] [ ( column_name [, ... ] ) ] [
WHERE ( expression ) ] } [, ... ]
TABLES IN SCHEMA { schema_name | CURRENT_SCHEMA } [, ... ]
----------
I attached a v1 patch to do this.
Thoughts?
======
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
v1-0001-Add-curly-brackets-before-ellipsis.patchapplication/octet-stream; name=v1-0001-Add-curly-brackets-before-ellipsis.patchDownload
From fbb5b638b2e9dde0694bbd706c08aa298852cdf1 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Tue, 12 Aug 2025 13:25:17 +1000
Subject: [PATCH v1] Add curly brackets before ellipsis
---
doc/src/sgml/ref/alter_publication.sgml | 2 +-
doc/src/sgml/ref/create_publication.sgml | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index d5ea383..2aedc99 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -30,7 +30,7 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE { [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] } [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
</synopsis>
</refsynopsisdiv>
diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
index 802630f..3c2dd9a 100644
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -28,7 +28,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE { [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] } [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
</synopsis>
</refsynopsisdiv>
--
1.8.3.1
Added a CF entry [1]https://commitfest.postgresql.org/patch/6062/ for this.
======
[1]: https://commitfest.postgresql.org/patch/6062/
Kind Regards,
Peter Smith.
Fujitsu Australia
A rebase was needed. Here is patch v2.
======
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
v2-0001-Add-curly-brackets-before-ellipsis.patchapplication/octet-stream; name=v2-0001-Add-curly-brackets-before-ellipsis.patchDownload
From c00cc899a11ea4322b6e7774c5ebf70eb15b4482 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Tue, 4 Nov 2025 13:38:22 +1100
Subject: [PATCH v2] Add curly brackets before ellipsis
---
doc/src/sgml/ref/alter_publication.sgml | 2 +-
doc/src/sgml/ref/create_publication.sgml | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index c36e754..971ba5f 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -30,7 +30,7 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE { [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] } [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
</synopsis>
</refsynopsisdiv>
diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
index 66a70e5..cde4235 100644
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -27,7 +27,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE { [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] } [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
<phrase>where <replaceable class="parameter">all_publication_object</replaceable> is one of:</phrase>
--
1.8.3.1
A rebase was needed. Here is patch v3.
======
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
v3-0001-Add-curly-brackets-before-ellipsis.patchapplication/octet-stream; name=v3-0001-Add-curly-brackets-before-ellipsis.patchDownload
From 7b05b2bc1f4d044434a15e2f418f695636a42362 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Fri, 14 Nov 2025 12:15:13 +1100
Subject: [PATCH v3] Add curly brackets before ellipsis
---
doc/src/sgml/ref/alter_publication.sgml | 4 ++--
doc/src/sgml/ref/create_publication.sgml | 2 +-
2 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index 8dd250d..1275935 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -30,12 +30,12 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE { [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] } [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
<phrase>where <replaceable class="parameter">publication_drop_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ... ]
+ TABLE { [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] } [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
</synopsis>
</refsynopsisdiv>
diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
index 66a70e5..cde4235 100644
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -27,7 +27,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE { [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] } [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
<phrase>where <replaceable class="parameter">all_publication_object</replaceable> is one of:</phrase>
--
1.8.3.1
On Fri, Nov 14, 2025 at 10:23 AM Peter Smith <smithpb2250@gmail.com> wrote:
A rebase was needed. Here is patch v3.
Thanks for the patch! LGTM.
For example, in the CREATE PUBLICATION synopsis, the part that can be
repeated is "[ ONLY ] table_name ... [ WHERE ( expression ) ]" not just
the WHERE clause, so using curly brackets around that seems correct.
Regards,
--
Fujii Masao
On Nov 14, 2025, at 15:47, Fujii Masao <masao.fujii@gmail.com> wrote:
On Fri, Nov 14, 2025 at 10:23 AM Peter Smith <smithpb2250@gmail.com> wrote:
A rebase was needed. Here is patch v3.
Thanks for the patch! LGTM.
For example, in the CREATE PUBLICATION synopsis, the part that can be
repeated is "[ ONLY ] table_name ... [ WHERE ( expression ) ]" not just
the WHERE clause, so using curly brackets around that seems correct.
I disagree. {…} means “choose exactly one of the following alternatives”, but not for grouping for repetition.
For example:
```
GRANT { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER | MAINTAIN }
[, ...] | ALL [ PRIVILEGES ] }
ON { [ TABLE ] table_name [, ...]
| ALL TABLES IN SCHEMA schema_name [, ...] }
TO role_specification [, ...] [ WITH GRANT OPTION ]
[ GRANTED BY role_specification ]
```
The two levels of {} are all for alternatives.
So, I think the correct way is like:
```
TABLE table_spec [, TABLE table_spec … ]
```
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
On Fri, Nov 14, 2025 at 7:02 PM Chao Li <li.evan.chao@gmail.com> wrote:
On Nov 14, 2025, at 15:47, Fujii Masao <masao.fujii@gmail.com> wrote:
On Fri, Nov 14, 2025 at 10:23 AM Peter Smith <smithpb2250@gmail.com> wrote:
A rebase was needed. Here is patch v3.
Thanks for the patch! LGTM.
For example, in the CREATE PUBLICATION synopsis, the part that can be
repeated is "[ ONLY ] table_name ... [ WHERE ( expression ) ]" not just
the WHERE clause, so using curly brackets around that seems correct.I disagree. {…} means “choose exactly one of the following alternatives”, but not for grouping for repetition.
For example:
```
GRANT { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER | MAINTAIN }
[, ...] | ALL [ PRIVILEGES ] }
ON { [ TABLE ] table_name [, ...]
| ALL TABLES IN SCHEMA schema_name [, ...] }
TO role_specification [, ...] [ WITH GRANT OPTION ]
[ GRANTED BY role_specification ]
```The two levels of {} are all for alternatives.
So, I think the correct way is like:
```
TABLE table_spec [, TABLE table_spec … ]
```
Fair point. I've changed v4 to use a syntax similar to your suggestion:
But, instead of "TABLE <table_spec> [, <table_spec> ...]", I am just
using "TABLE <table_spec> [,...]". Maybe it is not strictly correct,
but AFAICT it is consistent with how [,...] is used elsewhere in this
and other synopses.
e.g. we don't say "<column_name> [, <column_name> ...]"
~~~
Actually, I had a couple of other changes in the pipeline for the
synopsis that I was going to post as separate patches, but since this
has become a larger change, it is probably more appropriate to address
them all at once instead of churning the same synopsis multiple times.
So, now this patch makes the following 3 changes:
#1.
My original change, to fix the [, ...] grouping to remove ambiguity.
#2
Now renames "all_publication_object" to "publication_all_objects".
This is a simple name change that does not affect anything. I felt
everything ought to have the prefix of the object it belongs to (e.g.
"publication_name", "publication_parameter", "table_name",
"schema_name", column_name" all follow this rule, but prefix "all_"
was the odd-one-out).
#3
Rearranged the synopsis order from general to detailed. Again, there
is no functional difference; I just felt it was better to use the
natural logical order: e.g., "publication_all_objects" >
"publication_object"
======
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
v4-0001-Fix-synopsis.patchapplication/octet-stream; name=v4-0001-Fix-synopsis.patchDownload
From 055ceac32bc0d79cf7a8eb4e00eb512b22da450d Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Mon, 17 Nov 2025 11:20:30 +1100
Subject: [PATCH v4] Fix synopsis
---
doc/src/sgml/ref/alter_publication.sgml | 8 ++++++--
doc/src/sgml/ref/create_publication.sgml | 14 +++++++++-----
2 files changed, 15 insertions(+), 7 deletions(-)
diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index 8dd250d..ba58cdd 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -30,13 +30,17 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
+ TABLE <replaceable class="parameter">table_spec</replaceable> [, ... ]
+
+ <phrase>where <replaceable class="parameter">table_spec</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ]
<phrase>where <replaceable class="parameter">publication_drop_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
+ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ... ]
</synopsis>
</refsynopsisdiv>
diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
index 66a70e5..c50c8f6 100644
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -22,18 +22,22 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
- [ FOR { <replaceable class="parameter">publication_object</replaceable> [, ... ] | <replaceable class="parameter">all_publication_object</replaceable> [, ... ] } ]
+ [ FOR { <replaceable class="parameter">publication_all_objects</replaceable> [, ... ] | <replaceable class="parameter">publication_object</replaceable> [, ... ] } ]
[ WITH ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) ]
+<phrase>where <replaceable class="parameter">publication_all_objects</replaceable> is one of:</phrase>
+
+ ALL TABLES
+ ALL SEQUENCES
+
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
+ TABLE <replaceable class="parameter">table_spec</replaceable> [, ... ]
-<phrase>where <replaceable class="parameter">all_publication_object</replaceable> is one of:</phrase>
+ <phrase>where <replaceable class="parameter">table_spec</replaceable> is:</phrase>
- ALL TABLES
- ALL SEQUENCES
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ]
</synopsis>
</refsynopsisdiv>
--
1.8.3.1
On Nov 17, 2025, at 08:30, Peter Smith <smithpb2250@gmail.com> wrote:
On Fri, Nov 14, 2025 at 7:02 PM Chao Li <li.evan.chao@gmail.com> wrote:
On Nov 14, 2025, at 15:47, Fujii Masao <masao.fujii@gmail.com> wrote:
On Fri, Nov 14, 2025 at 10:23 AM Peter Smith <smithpb2250@gmail.com> wrote:
A rebase was needed. Here is patch v3.
Thanks for the patch! LGTM.
For example, in the CREATE PUBLICATION synopsis, the part that can be
repeated is "[ ONLY ] table_name ... [ WHERE ( expression ) ]" not just
the WHERE clause, so using curly brackets around that seems correct.I disagree. {…} means “choose exactly one of the following alternatives”, but not for grouping for repetition.
For example:
```
GRANT { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER | MAINTAIN }
[, ...] | ALL [ PRIVILEGES ] }
ON { [ TABLE ] table_name [, ...]
| ALL TABLES IN SCHEMA schema_name [, ...] }
TO role_specification [, ...] [ WITH GRANT OPTION ]
[ GRANTED BY role_specification ]
```The two levels of {} are all for alternatives.
So, I think the correct way is like:
```
TABLE table_spec [, TABLE table_spec … ]
```Fair point. I've changed v4 to use a syntax similar to your suggestion:
But, instead of "TABLE <table_spec> [, <table_spec> ...]", I am just
using "TABLE <table_spec> [,...]". Maybe it is not strictly correct,
but AFAICT it is consistent with how [,...] is used elsewhere in this
and other synopses.
e.g. we don't say "<column_name> [, <column_name> ...]"~~~
Actually, I had a couple of other changes in the pipeline for the
synopsis that I was going to post as separate patches, but since this
has become a larger change, it is probably more appropriate to address
them all at once instead of churning the same synopsis multiple times.So, now this patch makes the following 3 changes:
#1.
My original change, to fix the [, ...] grouping to remove ambiguity.#2
Now renames "all_publication_object" to "publication_all_objects".
This is a simple name change that does not affect anything. I felt
everything ought to have the prefix of the object it belongs to (e.g.
"publication_name", "publication_parameter", "table_name",
"schema_name", column_name" all follow this rule, but prefix "all_"
was the odd-one-out).
I don’t like this renaming. Or at lease don’t use plural.
#3
Rearranged the synopsis order from general to detailed. Again, there
is no functional difference; I just felt it was better to use the
natural logical order: e.g., "publication_all_objects" >
"publication_object"
I think PG doc usually place the most common form first. For publications, TABLE is used far more than TABLES IN SCHEMA. For example, if you look at https://www.postgresql.org/docs/18/sql-grant.html, it doesn’t follow the general->detailed rule.
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
On Nov 17, 2025, at 14:48, Chao Li <li.evan.chao@gmail.com> wrote:
#2
Now renames "all_publication_object" to "publication_all_objects".
This is a simple name change that does not affect anything. I felt
everything ought to have the prefix of the object it belongs to (e.g.
"publication_name", "publication_parameter", "table_name",
"schema_name", column_name" all follow this rule, but prefix "all_"
was the odd-one-out).I don’t like this renaming. Or at lease don’t use plural.
I incidentally clicked on “Send” too quick. I’d add a few words on this.
Here, “all_public_object” refers to “ALL TABLES” or “ALL SEQUENCES”. In this context, the thing is “ALL” instead of multiple objects, that’s why I don’t like the renaming, or at lease the new name should not use plural.
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
On Mon, Nov 17, 2025 at 5:49 PM Chao Li <li.evan.chao@gmail.com> wrote:
...
#1.
My original change, to fix the [, ...] grouping to remove ambiguity.#2
Now renames "all_publication_object" to "publication_all_objects".
This is a simple name change that does not affect anything. I felt
everything ought to have the prefix of the object it belongs to (e.g.
"publication_name", "publication_parameter", "table_name",
"schema_name", column_name" all follow this rule, but prefix "all_"
was the odd-one-out).I don’t like this renaming. Or at lease don’t use plural.
#3
Rearranged the synopsis order from general to detailed. Again, there
is no functional difference; I just felt it was better to use the
natural logical order: e.g., "publication_all_objects" >
"publication_object"I think PG doc usually place the most common form first. For publications, TABLE is used far more than TABLES IN SCHEMA. For example, if you look at https://www.postgresql.org/docs/18/sql-grant.html, it doesn’t follow the general->detailed rule.
PSA v5 with some changes per your v4 review:
#1.
This is the original fix for the [, ...] grouping to remove ambiguity.
I also noticed a missing object for the ALTER DROP case, so I added
that as well. So now there are names:
- table_spec
- table_spec_drop
Got any better suggestions?
#2
Removed the plural -- now "publication_all_object"
#3
I didn't recognise that the synopsis was already in order of "common
usage", so I discarded my idea to reorder it.
======
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
v5-0001-Fix-synopsis.patchapplication/octet-stream; name=v5-0001-Fix-synopsis.patchDownload
From 4ee71241b92f4613ac1e7582c332d858fb347b4e Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Tue, 18 Nov 2025 16:16:55 +1100
Subject: [PATCH v5] Fix synopsis
---
doc/src/sgml/ref/alter_publication.sgml | 12 ++++++++++--
doc/src/sgml/ref/create_publication.sgml | 10 +++++++---
2 files changed, 17 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index 8dd250d..dd37c19 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -30,13 +30,21 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE <replaceable class="parameter">table_spec</replaceable> [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
+ <phrase>where <replaceable class="parameter">table_spec</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ]
+
<phrase>where <replaceable class="parameter">publication_drop_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ... ]
+ TABLE <replaceable class="parameter">table_spec_drop</replaceable> [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
+
+ <phrase>where <replaceable class="parameter">table_spec_drop</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
</synopsis>
</refsynopsisdiv>
diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
index 66a70e5..b49635b 100644
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -22,15 +22,19 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
- [ FOR { <replaceable class="parameter">publication_object</replaceable> [, ... ] | <replaceable class="parameter">all_publication_object</replaceable> [, ... ] } ]
+ [ FOR { <replaceable class="parameter">publication_object</replaceable> [, ... ] | <replaceable class="parameter">publication_all_object</replaceable> [, ... ] } ]
[ WITH ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) ]
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE <replaceable class="parameter">table_spec</replaceable> [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
-<phrase>where <replaceable class="parameter">all_publication_object</replaceable> is one of:</phrase>
+ <phrase>where <replaceable class="parameter">table_spec</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ]
+
+<phrase>where <replaceable class="parameter">publication_all_object</replaceable> is one of:</phrase>
ALL TABLES
ALL SEQUENCES
--
1.8.3.1
On Nov 18, 2025, at 13:31, Peter Smith <smithpb2250@gmail.com> wrote:
On Mon, Nov 17, 2025 at 5:49 PM Chao Li <li.evan.chao@gmail.com> wrote:
...#1.
My original change, to fix the [, ...] grouping to remove ambiguity.#2
Now renames "all_publication_object" to "publication_all_objects".
This is a simple name change that does not affect anything. I felt
everything ought to have the prefix of the object it belongs to (e.g.
"publication_name", "publication_parameter", "table_name",
"schema_name", column_name" all follow this rule, but prefix "all_"
was the odd-one-out).I don’t like this renaming. Or at lease don’t use plural.
#3
Rearranged the synopsis order from general to detailed. Again, there
is no functional difference; I just felt it was better to use the
natural logical order: e.g., "publication_all_objects" >
"publication_object"I think PG doc usually place the most common form first. For publications, TABLE is used far more than TABLES IN SCHEMA. For example, if you look at https://www.postgresql.org/docs/18/sql-grant.html, it doesn’t follow the general->detailed rule.
PSA v5 with some changes per your v4 review:
#1.
This is the original fix for the [, ...] grouping to remove ambiguity.I also noticed a missing object for the ALTER DROP case, so I added
that as well. So now there are names:
- table_spec
- table_spec_dropGot any better suggestions?
#2
Removed the plural -- now "publication_all_object"#3
I didn't recognise that the synopsis was already in order of "common
usage", so I discarded my idea to reorder it.
Thanks for addressing the comments. V5 looks good to me.
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
On Tue, Nov 18, 2025 at 5:27 PM Chao Li <li.evan.chao@gmail.com> wrote:
Thanks for addressing the comments. V5 looks good to me.
Thanks both for the patch and review!
-<phrase>where <replaceable
class="parameter">all_publication_object</replaceable> is one
of:</phrase>
+ <phrase>where <replaceable
class="parameter">table_spec</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable
class="parameter">table_name</replaceable> [ * ] [ ( <replaceable
class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE (
<replaceable class="parameter">expression</replaceable> ) ]
+
+<phrase>where <replaceable
class="parameter">publication_all_object</replaceable> is one
of:</phrase>
In other documentation files (e.g., merge.sgml, analyze.sgml), the definitions
of each element are chained using "and". For example, in merge.sgml:
where data_source is:
...
and when_clause is:
...
and merge_insert is:
...
I think create_publication.sgml and alter_publication.sgml should follow
the same style for consistency. For example, in create_publication.sgml
we would have:
where publication_object
...
and publication_all_object
...
and table_spec
...
It seems better to put these sections in the same order that the elements
appear in the syntax. So I placed publication_all_object before table_spec
in the above example.
-<phrase>where <replaceable
class="parameter">all_publication_object</replaceable> is one
of:</phrase>
+ <phrase>where <replaceable
class="parameter">table_spec</replaceable> is:</phrase>
Regarding terminology: analyze.sgml uses table_and_columns for
a similar syntax, and personally I think table_and_columns is clearer than
table_spec.
Regards,
--
Fujii Masao
Hi Fuji-San.
Thanks for your suggestions! I've attached a new patch v6 to incorporate them.
On Thu, Nov 20, 2025 at 4:50 AM Fujii Masao <masao.fujii@gmail.com> wrote:
On Tue, Nov 18, 2025 at 5:27 PM Chao Li <li.evan.chao@gmail.com> wrote:
Thanks for addressing the comments. V5 looks good to me.
Thanks both for the patch and review!
-<phrase>where <replaceable
class="parameter">all_publication_object</replaceable> is one
of:</phrase>
+ <phrase>where <replaceable
class="parameter">table_spec</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable
class="parameter">table_name</replaceable> [ * ] [ ( <replaceable
class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE (
<replaceable class="parameter">expression</replaceable> ) ]
+
+<phrase>where <replaceable
class="parameter">publication_all_object</replaceable> is one
of:</phrase>In other documentation files (e.g., merge.sgml, analyze.sgml), the definitions
of each element are chained using "and". For example, in merge.sgml:where data_source is:
...
and when_clause is:
...
and merge_insert is:
...I think create_publication.sgml and alter_publication.sgml should follow
the same style for consistency. For example, in create_publication.sgml
we would have:where publication_object
...
and publication_all_object
...
and table_spec
...
+1. I never noticed this before.
It seems better to put these sections in the same order that the elements
appear in the syntax. So I placed publication_all_object before table_spec
in the above example.-<phrase>where <replaceable
class="parameter">all_publication_object</replaceable> is one
of:</phrase>
+ <phrase>where <replaceable
class="parameter">table_spec</replaceable> is:</phrase>
OK. Done in v6.
Regarding terminology: analyze.sgml uses table_and_columns for
a similar syntax, and personally I think table_and_columns is clearer than
table_spec.
Thanks for the other example usages.
+1 for naming it as 'table_and_columns' to be the same as everywhere else.
Also, to match that, I renamed 'table_spec_drop' to 'table'.
======
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
v6-0001-Fix-synopsis.patchapplication/octet-stream; name=v6-0001-Fix-synopsis.patchDownload
From bab9756ce336c7e4a89074e843cbb6a15020c904 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Thu, 20 Nov 2025 09:03:04 +1100
Subject: [PATCH v6] Fix synopsis
---
doc/src/sgml/ref/alter_publication.sgml | 14 +++++++++++---
doc/src/sgml/ref/create_publication.sgml | 10 +++++++---
2 files changed, 18 insertions(+), 6 deletions(-)
diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index 8dd250d..6c69ec6 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -30,13 +30,21 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE <replaceable class="parameter">table_and_columns</replaceable> [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
-<phrase>where <replaceable class="parameter">publication_drop_object</replaceable> is one of:</phrase>
+<phrase>and <replaceable class="parameter">publication_drop_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ... ]
+ TABLE <replaceable class="parameter">table</replaceable> [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
+
+<phrase>and <replaceable class="parameter">table_and_columns</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ]
+
+<phrase>and <replaceable class="parameter">table</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
</synopsis>
</refsynopsisdiv>
diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
index 66a70e5..75a508b 100644
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -22,18 +22,22 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
- [ FOR { <replaceable class="parameter">publication_object</replaceable> [, ... ] | <replaceable class="parameter">all_publication_object</replaceable> [, ... ] } ]
+ [ FOR { <replaceable class="parameter">publication_object</replaceable> [, ... ] | <replaceable class="parameter">publication_all_object</replaceable> [, ... ] } ]
[ WITH ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) ]
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE <replaceable class="parameter">table_and_columns</replaceable> [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
-<phrase>where <replaceable class="parameter">all_publication_object</replaceable> is one of:</phrase>
+<phrase>and <replaceable class="parameter">publication_all_object</replaceable> is one of:</phrase>
ALL TABLES
ALL SEQUENCES
+
+<phrase>and <replaceable class="parameter">table_and_columns</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ]
</synopsis>
</refsynopsisdiv>
--
1.8.3.1
On Nov 20, 2025, at 06:18, Peter Smith <smithpb2250@gmail.com> wrote:
Hi Fuji-San.
Thanks for your suggestions! I've attached a new patch v6 to incorporate them.
On Thu, Nov 20, 2025 at 4:50 AM Fujii Masao <masao.fujii@gmail.com> wrote:
On Tue, Nov 18, 2025 at 5:27 PM Chao Li <li.evan.chao@gmail.com> wrote:
Thanks for addressing the comments. V5 looks good to me.
Thanks both for the patch and review!
-<phrase>where <replaceable
class="parameter">all_publication_object</replaceable> is one
of:</phrase>
+ <phrase>where <replaceable
class="parameter">table_spec</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable
class="parameter">table_name</replaceable> [ * ] [ ( <replaceable
class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE (
<replaceable class="parameter">expression</replaceable> ) ]
+
+<phrase>where <replaceable
class="parameter">publication_all_object</replaceable> is one
of:</phrase>In other documentation files (e.g., merge.sgml, analyze.sgml), the definitions
of each element are chained using "and". For example, in merge.sgml:where data_source is:
...
and when_clause is:
...
and merge_insert is:
...I think create_publication.sgml and alter_publication.sgml should follow
the same style for consistency. For example, in create_publication.sgml
we would have:where publication_object
...
and publication_all_object
...
and table_spec
...+1. I never noticed this before.
It seems better to put these sections in the same order that the elements
appear in the syntax. So I placed publication_all_object before table_spec
in the above example.-<phrase>where <replaceable
class="parameter">all_publication_object</replaceable> is one
of:</phrase>
+ <phrase>where <replaceable
class="parameter">table_spec</replaceable> is:</phrase>OK. Done in v6.
Regarding terminology: analyze.sgml uses table_and_columns for
a similar syntax, and personally I think table_and_columns is clearer than
table_spec.Thanks for the other example usages.
+1 for naming it as 'table_and_columns' to be the same as everywhere else.
+1 as well.
V6 looks better. However, there is a typo:
In alter_publication.sgml:
```
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ... ]
+ TABLE <replaceable class="parameter">table</replaceable> [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
```
<replaceable class="parameter">table</replaceable> should be <replaceable class="parameter">table_and_columns</replaceable>.Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
On Thu, Nov 20, 2025 at 11:02 AM Chao Li <li.evan.chao@gmail.com> wrote:
On Nov 20, 2025, at 06:18, Peter Smith <smithpb2250@gmail.com> wrote:
Hi Fuji-San.
Thanks for your suggestions! I've attached a new patch v6 to incorporate them.
On Thu, Nov 20, 2025 at 4:50 AM Fujii Masao <masao.fujii@gmail.com> wrote:
On Tue, Nov 18, 2025 at 5:27 PM Chao Li <li.evan.chao@gmail.com> wrote:
Thanks for addressing the comments. V5 looks good to me.
Thanks both for the patch and review!
-<phrase>where <replaceable
class="parameter">all_publication_object</replaceable> is one
of:</phrase>
+ <phrase>where <replaceable
class="parameter">table_spec</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable
class="parameter">table_name</replaceable> [ * ] [ ( <replaceable
class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE (
<replaceable class="parameter">expression</replaceable> ) ]
+
+<phrase>where <replaceable
class="parameter">publication_all_object</replaceable> is one
of:</phrase>In other documentation files (e.g., merge.sgml, analyze.sgml), the definitions
of each element are chained using "and". For example, in merge.sgml:where data_source is:
...
and when_clause is:
...
and merge_insert is:
...I think create_publication.sgml and alter_publication.sgml should follow
the same style for consistency. For example, in create_publication.sgml
we would have:where publication_object
...
and publication_all_object
...
and table_spec
...+1. I never noticed this before.
It seems better to put these sections in the same order that the elements
appear in the syntax. So I placed publication_all_object before table_spec
in the above example.-<phrase>where <replaceable
class="parameter">all_publication_object</replaceable> is one
of:</phrase>
+ <phrase>where <replaceable
class="parameter">table_spec</replaceable> is:</phrase>OK. Done in v6.
Regarding terminology: analyze.sgml uses table_and_columns for
a similar syntax, and personally I think table_and_columns is clearer than
table_spec.Thanks for the other example usages.
+1 for naming it as 'table_and_columns' to be the same as everywhere else.
+1 as well.
V6 looks better. However, there is a typo:
In alter_publication.sgml: ``` - TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ... ] + TABLE <replaceable class="parameter">table</replaceable> [, ... ] TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ] ``` <replaceable class="parameter">table</replaceable> should be <replaceable class="parameter">table_and_columns</replaceable>.
I think 'table' is correct. It renders like:
------
where publication_object is one of:
TABLE table_and_columns [, ... ]
TABLES IN SCHEMA { schema_name | CURRENT_SCHEMA } [, ... ]
and publication_drop_object is one of:
TABLE table [, ... ]
TABLES IN SCHEMA { schema_name | CURRENT_SCHEMA } [, ... ]
and table_and_columns is:
[ ONLY ] table_name [ * ] [ ( column_name [, ... ] ) ] [ WHERE (
expression ) ]
and table is:
[ ONLY ] table_name [ * ]
------
The publication_drop_object cannot use 'table_and_columns' because the
columns/where-clause are not allowed for DROP. That difference was the
whole reason for making publication_drop_object in the first place.
Or is there some other typo I am missing?
======
Kind Regards,
Peter Smith.
Fujitsu Australia
On Thu, Nov 20, 2025 at 9:02 AM Chao Li <li.evan.chao@gmail.com> wrote:
V6 looks better.
+1. Thanks for updating the patch!
+<phrase>and <replaceable class="parameter">table</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]I have one question: in lock.sgml and truncate.sgml, the syntax
"[ ONLY ] name [ * ] [, ... ]" seems shown as acceptable (though
I'm not entirely sure it's actually valid). If that form is allowed,
then this change may not be necessary?
Regards,
--
Fujii Masao
On Thu, Nov 20, 2025 at 12:03 PM Fujii Masao <masao.fujii@gmail.com> wrote:
On Thu, Nov 20, 2025 at 9:02 AM Chao Li <li.evan.chao@gmail.com> wrote:
V6 looks better.
+1. Thanks for updating the patch!
+<phrase>and <replaceable class="parameter">table</replaceable> is:</phrase> + + [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]I have one question: in lock.sgml and truncate.sgml, the syntax
"[ ONLY ] name [ * ] [, ... ]" seems shown as acceptable (though
I'm not entirely sure it's actually valid). If that form is allowed,
then this change may not be necessary?
I think if this were strict BNF rules, then the bindings of the "..."
are not correct. I think the Postgres documentation is a bit loose
with the rules (e.g. your TRUNCATE example is deemed acceptable)
A user might also wonder if "ONLY a,b" means the same as "ONLY a", "ONLY b"?
But, in the interest of not bloating the ALTER PUBLICATION synopsis
too much, and still being consistent with what seems accepted by
existing PG docs, I am happy to remove that extra 'table' replacement
class. Maybe it's a bit ambiguous, but it seems mostly harmless.
Thoughts?
======
Kind Regards,
Peter Smith.
Fujitsu Australia
On Nov 20, 2025, at 09:41, Peter Smith <smithpb2250@gmail.com> wrote:
On Thu, Nov 20, 2025 at 12:03 PM Fujii Masao <masao.fujii@gmail.com> wrote:
On Thu, Nov 20, 2025 at 9:02 AM Chao Li <li.evan.chao@gmail.com> wrote:
V6 looks better.
+1. Thanks for updating the patch!
+<phrase>and <replaceable class="parameter">table</replaceable> is:</phrase> + + [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]I have one question: in lock.sgml and truncate.sgml, the syntax
"[ ONLY ] name [ * ] [, ... ]" seems shown as acceptable (though
I'm not entirely sure it's actually valid). If that form is allowed,
then this change may not be necessary?I think if this were strict BNF rules, then the bindings of the "..."
are not correct. I think the Postgres documentation is a bit loose
with the rules (e.g. your TRUNCATE example is deemed acceptable)A user might also wonder if "ONLY a,b" means the same as "ONLY a", "ONLY b"?
But, in the interest of not bloating the ALTER PUBLICATION synopsis
too much, and still being consistent with what seems accepted by
existing PG docs, I am happy to remove that extra 'table' replacement
class. Maybe it's a bit ambiguous, but it seems mostly harmless.Thoughts?
I think the new code of publication_drop_object has changed the original meaning.
Old code:
```
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ... ]
```
Means the drop clause can be:
```
ALTER PUBLICATION DROP TABLE ONLY t1*, TABLE ONLY t2*
```
Now, the new code:
```
+ TABLE <replaceable class="parameter">table</replaceable> [, … ]
<phrase>and <replaceable class="parameter">table</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
```Changes the meaning to:
```
ALTER PUBLICATION DROP TABLE ONLY t1*, ONLY t2*
```
So, I think we should keep the old code.
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
On Thu, Nov 20, 2025 at 2:06 PM Chao Li <li.evan.chao@gmail.com> wrote:
On Nov 20, 2025, at 09:41, Peter Smith <smithpb2250@gmail.com> wrote:
On Thu, Nov 20, 2025 at 12:03 PM Fujii Masao <masao.fujii@gmail.com> wrote:
On Thu, Nov 20, 2025 at 9:02 AM Chao Li <li.evan.chao@gmail.com> wrote:
V6 looks better.
+1. Thanks for updating the patch!
+<phrase>and <replaceable class="parameter">table</replaceable> is:</phrase> + + [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]I have one question: in lock.sgml and truncate.sgml, the syntax
"[ ONLY ] name [ * ] [, ... ]" seems shown as acceptable (though
I'm not entirely sure it's actually valid). If that form is allowed,
then this change may not be necessary?I think if this were strict BNF rules, then the bindings of the "..."
are not correct. I think the Postgres documentation is a bit loose
with the rules (e.g. your TRUNCATE example is deemed acceptable)A user might also wonder if "ONLY a,b" means the same as "ONLY a", "ONLY b"?
But, in the interest of not bloating the ALTER PUBLICATION synopsis
too much, and still being consistent with what seems accepted by
existing PG docs, I am happy to remove that extra 'table' replacement
class. Maybe it's a bit ambiguous, but it seems mostly harmless.Thoughts?
I think the new code of publication_drop_object has changed the original meaning.
Old code:
```
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ... ]
```Means the drop clause can be:
```
ALTER PUBLICATION DROP TABLE ONLY t1*, TABLE ONLY t2*
```Now, the new code: ``` + TABLE <replaceable class="parameter">table</replaceable> [, … ] <phrase>and <replaceable class="parameter">table</replaceable> is:</phrase> + + [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] ```Changes the meaning to:
```
ALTER PUBLICATION DROP TABLE ONLY t1*, ONLY t2*
```
There are 2 sets of ellipses:
Here: "publication_drop_object [, ...]"
And here "TABLE <replaceable class="parameter">table</replaceable> [, … ]"
So I think there is no change of meaning. AFAICT all variations are
possible, same as they always were. It just depends which way you
squint at the syntax -- e.g. are you conceptually expanding another
"publication_drop_objecr" replacement or expanding another "table"
replacement.
So, I think we should keep the old code.
Anyway, I am happy to go back to the old code. I'll post another patch
later to do that.
======
Kind Regards,
Peter Smith.
Fujitsu Australia
I've reverted the ALTER 'publication_drop_object' part to be the same
as master (i.e. removed the v6 'table' replacement) after Fujii-San
showed [1]/messages/by-id/CAHGQGwHOQJCG-THQ1iBE7rTncjYXmXa7TSfDZn5RP+jM35wnsQ@mail.gmail.com that the original synopsis style is present on some other
documentation pages.
PSS new patch v7.
======
[1]: /messages/by-id/CAHGQGwHOQJCG-THQ1iBE7rTncjYXmXa7TSfDZn5RP+jM35wnsQ@mail.gmail.com
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
v7-0001-Fix-synopsis.patchapplication/octet-stream; name=v7-0001-Fix-synopsis.patchDownload
From 2a622f07c990937d8a67ca32a0f9e315d0ca1a98 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Fri, 21 Nov 2025 08:02:39 +1100
Subject: [PATCH v7] Fix synopsis
---
doc/src/sgml/ref/alter_publication.sgml | 8 ++++++--
doc/src/sgml/ref/create_publication.sgml | 10 +++++++---
2 files changed, 13 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index 8dd250d..028770f 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -30,13 +30,17 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE <replaceable class="parameter">table_and_columns</replaceable> [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
-<phrase>where <replaceable class="parameter">publication_drop_object</replaceable> is one of:</phrase>
+<phrase>and <replaceable class="parameter">publication_drop_object</replaceable> is one of:</phrase>
TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
+
+<phrase>and <replaceable class="parameter">table_and_columns</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ]
</synopsis>
</refsynopsisdiv>
diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
index 66a70e5..75a508b 100644
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -22,18 +22,22 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
- [ FOR { <replaceable class="parameter">publication_object</replaceable> [, ... ] | <replaceable class="parameter">all_publication_object</replaceable> [, ... ] } ]
+ [ FOR { <replaceable class="parameter">publication_object</replaceable> [, ... ] | <replaceable class="parameter">publication_all_object</replaceable> [, ... ] } ]
[ WITH ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) ]
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE <replaceable class="parameter">table_and_columns</replaceable> [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
-<phrase>where <replaceable class="parameter">all_publication_object</replaceable> is one of:</phrase>
+<phrase>and <replaceable class="parameter">publication_all_object</replaceable> is one of:</phrase>
ALL TABLES
ALL SEQUENCES
+
+<phrase>and <replaceable class="parameter">table_and_columns</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ]
</synopsis>
</refsynopsisdiv>
--
1.8.3.1
On Nov 21, 2025, at 05:08, Peter Smith <smithpb2250@gmail.com> wrote:
I've reverted the ALTER 'publication_drop_object' part to be the same
as master (i.e. removed the v6 'table' replacement) after Fujii-San
showed [1] that the original synopsis style is present on some other
documentation pages.PSS new patch v7.
======
[1] /messages/by-id/CAHGQGwHOQJCG-THQ1iBE7rTncjYXmXa7TSfDZn5RP+jM35wnsQ@mail.gmail.comKind Regards,
Peter Smith.
Fujitsu Australia
<v7-0001-Fix-synopsis.patch>
I rendered the html pages with v7 patched. LGTM.
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
On Fri, Nov 21, 2025 at 3:27 PM Chao Li <li.evan.chao@gmail.com> wrote:
On Nov 21, 2025, at 05:08, Peter Smith <smithpb2250@gmail.com> wrote:
I've reverted the ALTER 'publication_drop_object' part to be the same
as master (i.e. removed the v6 'table' replacement) after Fujii-San
showed [1] that the original synopsis style is present on some other
documentation pages.PSS new patch v7.
Thanks for updating the patch! LGTM.
One question: do we want to backpatch this? If so, to which versions?
If we decide to backpatch, it would be helpful if you could provide versions
of the patch that apply cleanly to those older branches.
I rendered the html pages with v7 patched. LGTM.
+1
Regards,
--
Fujii Masao
On Nov 25, 2025, at 18:42, Fujii Masao <masao.fujii@gmail.com> wrote:
On Fri, Nov 21, 2025 at 3:27 PM Chao Li <li.evan.chao@gmail.com> wrote:
On Nov 21, 2025, at 05:08, Peter Smith <smithpb2250@gmail.com> wrote:
I've reverted the ALTER 'publication_drop_object' part to be the same
as master (i.e. removed the v6 'table' replacement) after Fujii-San
showed [1] that the original synopsis style is present on some other
documentation pages.PSS new patch v7.
Thanks for updating the patch! LGTM.
One question: do we want to backpatch this? If so, to which versions?
If we decide to backpatch, it would be helpful if you could provide versions
of the patch that apply cleanly to those older branches.
I just checked the docs version by version, looks like the back-port can go down to 15.
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
On Tue, Nov 25, 2025 at 10:47 PM Chao Li <li.evan.chao@gmail.com> wrote:
On Nov 25, 2025, at 18:42, Fujii Masao <masao.fujii@gmail.com> wrote:
On Fri, Nov 21, 2025 at 3:27 PM Chao Li <li.evan.chao@gmail.com> wrote:
On Nov 21, 2025, at 05:08, Peter Smith <smithpb2250@gmail.com> wrote:
I've reverted the ALTER 'publication_drop_object' part to be the same
as master (i.e. removed the v6 'table' replacement) after Fujii-San
showed [1] that the original synopsis style is present on some other
documentation pages.PSS new patch v7.
Thanks for updating the patch! LGTM.
One question: do we want to backpatch this? If so, to which versions?
If we decide to backpatch, it would be helpful if you could provide versions
of the patch that apply cleanly to those older branches.I just checked the docs version by version, looks like the back-port can go down to 15.
Here are the back patches as requested. I hope they are OK.
~~~
v8-PG19devel - same as v7.
v8-PG18 - same as above, except the CREATE 'publication_all_object' is
not needed because FOR ALL SEQUENCES did not exist
v8-PG17 - same as above
v8-PG16 - same as above
v8-PG15 - same as above
======
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
v8-0001-PG18.-Fix-synopsis.patchapplication/octet-stream; name=v8-0001-PG18.-Fix-synopsis.patchDownload
From aa1e8344aab9e2b9108a0c35cae9960be0c858a2 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Thu, 27 Nov 2025 08:43:49 +1100
Subject: [PATCH v8] PG18. Fix synopsis
---
doc/src/sgml/ref/alter_publication.sgml | 8 ++++++--
doc/src/sgml/ref/create_publication.sgml | 6 +++++-
2 files changed, 11 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index 01b45bc..d7f1a5a 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -30,13 +30,17 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE <replaceable class="parameter">table_and_columns</replaceable> [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
-<phrase>where <replaceable class="parameter">publication_drop_object</replaceable> is one of:</phrase>
+<phrase>and <replaceable class="parameter">publication_drop_object</replaceable> is one of:</phrase>
TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
+
+<phrase>and <replaceable class="parameter">table_and_columns</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ]
</synopsis>
</refsynopsisdiv>
diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
index 802630f..092a141 100644
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -28,8 +28,12 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE <replaceable class="parameter">table_and_columns</replaceable> [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
+
+<phrase>and <replaceable class="parameter">table_and_columns</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ]
</synopsis>
</refsynopsisdiv>
--
1.8.3.1
v8-0001-PG16.-Fix-synopsis.patchapplication/octet-stream; name=v8-0001-PG16.-Fix-synopsis.patchDownload
From eff9a8b72826a38f365d1eb1bfbe7712c1dc9170 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Thu, 27 Nov 2025 09:08:17 +1100
Subject: [PATCH v8] PG16. Fix synopsis
---
doc/src/sgml/ref/alter_publication.sgml | 8 ++++++--
doc/src/sgml/ref/create_publication.sgml | 6 +++++-
2 files changed, 11 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index c209011..d9cae77 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -30,13 +30,17 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE <replaceable class="parameter">table_and_columns</replaceable> [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
-<phrase>where <replaceable class="parameter">publication_drop_object</replaceable> is one of:</phrase>
+<phrase>and <replaceable class="parameter">publication_drop_object</replaceable> is one of:</phrase>
TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
+
+<phrase>and <replaceable class="parameter">table_and_columns</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ]
</synopsis>
</refsynopsisdiv>
diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
index 606aa64..1c198ea 100644
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -28,8 +28,12 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE <replaceable class="parameter">table_and_columns</replaceable> [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
+
+<phrase>and <replaceable class="parameter">table_and_columns</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ]
</synopsis>
</refsynopsisdiv>
--
1.8.3.1
v8-0001-PG17.-Fix-synopsis.patchapplication/octet-stream; name=v8-0001-PG17.-Fix-synopsis.patchDownload
From 6d789f198c906d437e329e6674fa979f6f4e462f Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Thu, 27 Nov 2025 09:02:16 +1100
Subject: [PATCH v8] PG17. Fix synopsis
---
doc/src/sgml/ref/alter_publication.sgml | 8 ++++++--
doc/src/sgml/ref/create_publication.sgml | 6 +++++-
2 files changed, 11 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index a3bab19..3d865ab 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -30,13 +30,17 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE <replaceable class="parameter">table_and_columns</replaceable> [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
-<phrase>where <replaceable class="parameter">publication_drop_object</replaceable> is one of:</phrase>
+<phrase>and <replaceable class="parameter">publication_drop_object</replaceable> is one of:</phrase>
TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
+
+<phrase>and <replaceable class="parameter">table_and_columns</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ]
</synopsis>
</refsynopsisdiv>
diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
index fd9c5de..6aedf15 100644
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -28,8 +28,12 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE <replaceable class="parameter">table_and_columns</replaceable> [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
+
+<phrase>and <replaceable class="parameter">table_and_columns</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ]
</synopsis>
</refsynopsisdiv>
--
1.8.3.1
v8-0001-PG15.-Fix-synopsis.patchapplication/octet-stream; name=v8-0001-PG15.-Fix-synopsis.patchDownload
From 3238ec139f6078287e31af36076b55a63f988ed1 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Thu, 27 Nov 2025 09:18:54 +1100
Subject: [PATCH v8] PG15. Fix synopsis
---
doc/src/sgml/ref/alter_publication.sgml | 8 ++++++--
doc/src/sgml/ref/create_publication.sgml | 6 +++++-
2 files changed, 11 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index 9e7f60a..858daec 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -30,13 +30,17 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE <replaceable class="parameter">table_and_columns</replaceable> [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
-<phrase>where <replaceable class="parameter">publication_drop_object</replaceable> is one of:</phrase>
+<phrase>and <replaceable class="parameter">publication_drop_object</replaceable> is one of:</phrase>
TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
+
+<phrase>and <replaceable class="parameter">table_and_columns</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ]
</synopsis>
</refsynopsisdiv>
diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
index 7ab7e77..787750b 100644
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -28,8 +28,12 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE <replaceable class="parameter">table_and_columns</replaceable> [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
+
+<phrase>and <replaceable class="parameter">table_and_columns</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ]
</synopsis>
</refsynopsisdiv>
--
1.8.3.1
v8-0001-PG19devel.-Fix-synopsis.patchapplication/octet-stream; name=v8-0001-PG19devel.-Fix-synopsis.patchDownload
From 6ae90ab3462fd3fc96ee22b8523afb8a1bd3936b Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Thu, 27 Nov 2025 08:23:25 +1100
Subject: [PATCH v8] PG19devel. Fix synopsis
---
doc/src/sgml/ref/alter_publication.sgml | 8 ++++++--
doc/src/sgml/ref/create_publication.sgml | 10 +++++++---
2 files changed, 13 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index 8dd250d..028770f 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -30,13 +30,17 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE <replaceable class="parameter">table_and_columns</replaceable> [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
-<phrase>where <replaceable class="parameter">publication_drop_object</replaceable> is one of:</phrase>
+<phrase>and <replaceable class="parameter">publication_drop_object</replaceable> is one of:</phrase>
TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
+
+<phrase>and <replaceable class="parameter">table_and_columns</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ]
</synopsis>
</refsynopsisdiv>
diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
index 66a70e5..75a508b 100644
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -22,18 +22,22 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
- [ FOR { <replaceable class="parameter">publication_object</replaceable> [, ... ] | <replaceable class="parameter">all_publication_object</replaceable> [, ... ] } ]
+ [ FOR { <replaceable class="parameter">publication_object</replaceable> [, ... ] | <replaceable class="parameter">publication_all_object</replaceable> [, ... ] } ]
[ WITH ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) ]
<phrase>where <replaceable class="parameter">publication_object</replaceable> is one of:</phrase>
- TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
+ TABLE <replaceable class="parameter">table_and_columns</replaceable> [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
-<phrase>where <replaceable class="parameter">all_publication_object</replaceable> is one of:</phrase>
+<phrase>and <replaceable class="parameter">publication_all_object</replaceable> is one of:</phrase>
ALL TABLES
ALL SEQUENCES
+
+<phrase>and <replaceable class="parameter">table_and_columns</replaceable> is:</phrase>
+
+ [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ]
</synopsis>
</refsynopsisdiv>
--
1.8.3.1
On Thu, Nov 27, 2025 at 7:25 AM Peter Smith <smithpb2250@gmail.com> wrote:
Here are the back patches as requested. I hope they are OK.
Thanks for the patches! I've pushed them.
Regards,
--
Fujii Masao
On Fri, Nov 28, 2025 at 1:34 AM Fujii Masao <masao.fujii@gmail.com> wrote:
On Thu, Nov 27, 2025 at 7:25 AM Peter Smith <smithpb2250@gmail.com> wrote:
Here are the back patches as requested. I hope they are OK.
Thanks for the patches! I've pushed them.
Thanks for pushing! I enjoyed the discussions in this thread and
learned some new things along the way. The result looks much better
than my original patch :-|
======
Kind Regards,
Peter Smith.
Fujitsu Australia