PGDOCS - Replica Identity quotes
PGDOCS - Replica Identity quotes
Hi,
Here are some trivial quote changes to a paragraph describing REPLICA IDENTITY.
These changes were previously made in another ongoing R.I. patch
v28-0001 [1]/messages/by-id/CAA4eK1J8R-qS97cu27sF2=qzjhuQNkv+ZvgaTzFv7rs-LA4c2w@mail.gmail.com, but it was decided that since they are not strictly
related to that patch they should done separately.
======
logical-replication.sgml
Section 31.1 Publication
A published table must have a “replica identity” configured in order
to be able to replicate UPDATE and DELETE operations, so that
appropriate rows to update or delete can be identified on the
subscriber side. By default, this is the primary key, if there is one.
Another unique index (with certain additional requirements) can also
be set to be the replica identity. If the table does not have any
suitable key, then it can be set to replica identity “full”, which
means the entire row becomes the key. This, however, is very
inefficient and should only be used as a fallback if no other solution
is possible. If a replica identity other than “full” is set on the
publisher side, a replica identity comprising the same or fewer
columns must also be set on the subscriber side. See REPLICA IDENTITY
for details on how to set the replica identity. If a table without a
replica identity is added to a publication that replicates UPDATE or
DELETE operations then subsequent UPDATE or DELETE operations will
cause an error on the publisher. INSERT operations can proceed
regardless of any replica identity.
~~
Suggested changes:
1.
The quoted "replica identity" should not be quoted -- This is the
first time this term is used on this page so I think it should be
using <firstterm> SGML tag, just the same as how
<firstterm>publication</firstterm> looks at the top of this section.
2.
The quoted "full" should also not be quoted. Replicate identities are
not specified using text string "full" - they are specified as FULL
(see [2]https://www.postgresql.org/docs/current/sql-altertable.html#SQL-ALTERTABLE-REPLICA-IDENTITY), so IMO these instances should be changed to
<literal>FULL</full> to eliminate that ambiguity.
~~~
PSA patch v1 which implements the above changes.
------
[1]: /messages/by-id/CAA4eK1J8R-qS97cu27sF2=qzjhuQNkv+ZvgaTzFv7rs-LA4c2w@mail.gmail.com
[2]: https://www.postgresql.org/docs/current/sql-altertable.html#SQL-ALTERTABLE-REPLICA-IDENTITY
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
v1-0001-PGDOCS-replica-identity-quotes.patchapplication/octet-stream; name=v1-0001-PGDOCS-replica-identity-quotes.patchDownload
From c765ba9d094d1e815dee61036731565539be43da Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Tue, 7 Mar 2023 18:15:27 +1100
Subject: [PATCH v1] PGDOCS - replica identity quotes
---
doc/src/sgml/logical-replication.sgml | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 1bd5660..caaf46c 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -124,17 +124,17 @@
</para>
<para>
- A published table must have a <quote>replica identity</quote> configured in
+ A published table must have a <firstterm>replica identity</firstterm> configured in
order to be able to replicate <command>UPDATE</command>
and <command>DELETE</command> operations, so that appropriate rows to
update or delete can be identified on the subscriber side. By default,
this is the primary key, if there is one. Another unique index (with
certain additional requirements) can also be set to be the replica
identity. If the table does not have any suitable key, then it can be set
- to replica identity <quote>full</quote>, which means the entire row becomes
+ to replica identity <literal>FULL</literal>, which means the entire row becomes
the key. This, however, is very inefficient and should only be used as a
fallback if no other solution is possible. If a replica identity other
- than <quote>full</quote> is set on the publisher side, a replica identity
+ than <literal>FULL</literal> is set on the publisher side, a replica identity
comprising the same or fewer columns must also be set on the subscriber
side. See <xref linkend="sql-altertable-replica-identity"/> for details on
how to set the replica identity. If a table without a replica identity is
--
1.8.3.1
A rebase was needed due to the recent REPLICA IDENTITY push [1]https://github.com/postgres/postgres/commit/89e46da5e511a6970e26a020f265c9fb4b72b1d2.
PSA v2.
------
[1]: https://github.com/postgres/postgres/commit/89e46da5e511a6970e26a020f265c9fb4b72b1d2
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
v2-0001-PGDOCS-replica-identity-quotes.patchapplication/octet-stream; name=v2-0001-PGDOCS-replica-identity-quotes.patchDownload
From f32dd6636de7eb6faf16613f9fe881660ec9094a Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Fri, 17 Mar 2023 10:43:01 +1100
Subject: [PATCH v2] PGDOCS - replica identity quotes
---
doc/src/sgml/logical-replication.sgml | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 6b0e300..967c311 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -124,24 +124,24 @@
</para>
<para>
- A published table must have a <quote>replica identity</quote> configured in
+ A published table must have a <firstterm>replica identity</firstterm> configured in
order to be able to replicate <command>UPDATE</command>
and <command>DELETE</command> operations, so that appropriate rows to
update or delete can be identified on the subscriber side. By default,
this is the primary key, if there is one. Another unique index (with
certain additional requirements) can also be set to be the replica
identity. If the table does not have any suitable key, then it can be set
- to replica identity <quote>full</quote>, which means the entire row becomes
- the key. When replica identity <quote>full</quote> is specified,
+ to <literal>REPLICA IDENTITY FULL</literal>, which means the entire row becomes
+ the key. When <literal>REPLICA IDENTITY FULL</literal> is specified,
indexes can be used on the subscriber side for searching the rows. Candidate
indexes must be btree, non-partial, and have at least one column reference
(i.e. cannot consist of only expressions). These restrictions
on the non-unique index properties adhere to some of the restrictions that
are enforced for primary keys. If there are no such suitable indexes,
the search on the subscriber side can be very inefficient, therefore
- replica identity <quote>full</quote> should only be used as a
+ <literal>REPLICA IDENTITY FULL</literal> should only be used as a
fallback if no other solution is possible. If a replica identity other
- than <quote>full</quote> is set on the publisher side, a replica identity
+ than <literal>FULL</literal> is set on the publisher side, a replica identity
comprising the same or fewer columns must also be set on the subscriber
side. See <xref linkend="sql-altertable-replica-identity"/> for details on
how to set the replica identity. If a table without a replica identity is
--
1.8.3.1
On 2023-03-16 4:46 p.m., Peter Smith wrote:
A rebase was needed due to the recent REPLICA IDENTITY push [1].
PSA v2.
<para> - A published table must have a <quote>replica identity</quote> configured in + A published table must have a <firstterm>replica identity</firstterm> configured in
+1
order to be able to replicate <command>UPDATE</command> and <command>DELETE</command> operations, so that appropriate rows to update or delete can be identified on the subscriber side. By default, this is the primary key, if there is one. Another unique index (with certain additional requirements) can also be set to be the replica identity. If the table does not have any suitable key, then it can be set - to replica identity <quote>full</quote>, which means the entire row becomes - the key. When replica identity <quote>full</quote> is specified, + to <literal>REPLICA IDENTITY FULL</literal>, which means the entire row becomes + the key. When <literal>REPLICA IDENTITY FULL</literal> is specified, indexes can be used on the subscriber side for searching the rows. Candidate indexes must be btree, non-partial, and have at least one column reference (i.e. cannot consist of only expressions). These restrictions on the non-unique index properties adhere to some of the restrictions that are enforced for primary keys. If there are no such suitable indexes, the search on the subscriber side can be very inefficient, therefore - replica identity <quote>full</quote> should only be used as a + <literal>REPLICA IDENTITY FULL</literal> should only be used as a fallback if no other solution is possible. If a replica identity other
IMO, it would be better just change "full" to "FULL". On one side, it
can emphasize that "FULL" is one of the specific values (DEFAULT | USING
INDEX index_name | FULL | NOTHING); on the other side, it leaves
"replica identity" in lowercase to be more consistent with the
terminology used in this entire paragraph.
- than <quote>full</quote> is set on the publisher side, a replica identity + than <literal>FULL</literal> is set on the publisher side, a replica identity
+1
comprising the same or fewer columns must also be set on the subscriber
side. See <xref linkend="sql-altertable-replica-identity"/> for details on
how to set the replica identity. If a table without a replica identity is
David
On Sat, May 6, 2023 at 5:28 AM David Zhang <david.zhang@highgo.ca> wrote:
On 2023-03-16 4:46 p.m., Peter Smith wrote:
A rebase was needed due to the recent REPLICA IDENTITY push [1].
PSA v2.
<para> - A published table must have a <quote>replica identity</quote> configured in + A published table must have a <firstterm>replica identity</firstterm> configured in+1
order to be able to replicate <command>UPDATE</command> and <command>DELETE</command> operations, so that appropriate rows to update or delete can be identified on the subscriber side. By default, this is the primary key, if there is one. Another unique index (with certain additional requirements) can also be set to be the replica identity. If the table does not have any suitable key, then it can be set - to replica identity <quote>full</quote>, which means the entire row becomes - the key. When replica identity <quote>full</quote> is specified, + to <literal>REPLICA IDENTITY FULL</literal>, which means the entire row becomes + the key. When <literal>REPLICA IDENTITY FULL</literal> is specified, indexes can be used on the subscriber side for searching the rows. Candidate indexes must be btree, non-partial, and have at least one column reference (i.e. cannot consist of only expressions). These restrictions on the non-unique index properties adhere to some of the restrictions that are enforced for primary keys. If there are no such suitable indexes, the search on the subscriber side can be very inefficient, therefore - replica identity <quote>full</quote> should only be used as a + <literal>REPLICA IDENTITY FULL</literal> should only be used as a fallback if no other solution is possible. If a replica identity otherIMO, it would be better just change "full" to "FULL". On one side, it
can emphasize that "FULL" is one of the specific values (DEFAULT | USING
INDEX index_name | FULL | NOTHING); on the other side, it leaves
"replica identity" in lowercase to be more consistent with the
terminology used in this entire paragraph.- than <quote>full</quote> is set on the publisher side, a replica identity + than <literal>FULL</literal> is set on the publisher side, a replica identity+1
comprising the same or fewer columns must also be set on the subscriber
side. See <xref linkend="sql-altertable-replica-identity"/> for details on
how to set the replica identity. If a table without a replica identity is
Thanks for giving some feedback on my patch.
PSA v3 which is changed per your suggestion.
------
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
v3-0001-PGDOCS-replica-identity-quotes.patchapplication/octet-stream; name=v3-0001-PGDOCS-replica-identity-quotes.patchDownload
From 6e938d818ea2d026b22243c0bb880a1bde1d48e0 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Mon, 8 May 2023 10:20:48 +1000
Subject: [PATCH v3] PGDOCS - replica identity quotes
---
doc/src/sgml/logical-replication.sgml | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index c65f4aa..8f17260 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -124,24 +124,24 @@
</para>
<para>
- A published table must have a <quote>replica identity</quote> configured in
+ A published table must have a <firstterm>replica identity</firstterm> configured in
order to be able to replicate <command>UPDATE</command>
and <command>DELETE</command> operations, so that appropriate rows to
update or delete can be identified on the subscriber side. By default,
this is the primary key, if there is one. Another unique index (with
certain additional requirements) can also be set to be the replica
identity. If the table does not have any suitable key, then it can be set
- to replica identity <quote>full</quote>, which means the entire row becomes
- the key. When replica identity <quote>full</quote> is specified,
+ to replica identity <literal>FULL</literal>, which means the entire row becomes
+ the key. When replica identity <literal>FULL</literal> is specified,
indexes can be used on the subscriber side for searching the rows. Candidate
indexes must be btree, non-partial, and have at least one column reference
(i.e. cannot consist of only expressions). These restrictions
on the non-unique index properties adhere to some of the restrictions that
are enforced for primary keys. If there are no such suitable indexes,
the search on the subscriber side can be very inefficient, therefore
- replica identity <quote>full</quote> should only be used as a
+ replica identity <literal>FULL</literal> should only be used as a
fallback if no other solution is possible. If a replica identity other
- than <quote>full</quote> is set on the publisher side, a replica identity
+ than <literal>FULL</literal> is set on the publisher side, a replica identity
comprising the same or fewer columns must also be set on the subscriber
side. See <xref linkend="sql-altertable-replica-identity"/> for details on
how to set the replica identity. If a table without a replica identity is
--
1.8.3.1
On Mon, May 08, 2023 at 10:29:50AM +1000, Peter Smith wrote:
Thanks for giving some feedback on my patch.
Looks OK.
While on it, looking at logical-replication.sgml, it seems to me that
these two are also incorrect, and we should use <literal> markups:
implemented by <quote>walsender</quote> and <quote>apply</quote>
--
Michael
On Mon, May 8, 2023 at 1:09 PM Michael Paquier <michael@paquier.xyz> wrote:
On Mon, May 08, 2023 at 10:29:50AM +1000, Peter Smith wrote:
Thanks for giving some feedback on my patch.
Looks OK.
While on it, looking at logical-replication.sgml, it seems to me that
these two are also incorrect, and we should use <literal> markups:
implemented by <quote>walsender</quote> and <quote>apply</quote>
--
I agree. Do you want me to make a new v4 patch to also do that, or
will you handle them in passing?
------
Kind Regards,
Peter Smith.
Fujitsu Australia
On Mon, May 08, 2023 at 01:57:33PM +1000, Peter Smith wrote:
I agree. Do you want me to make a new v4 patch to also do that, or
will you handle them in passing?
I'll just go handle them on the way, no need to send an updated
patch.
--
Michael
On Mon, May 8, 2023 at 2:05 PM Michael Paquier <michael@paquier.xyz> wrote:
On Mon, May 08, 2023 at 01:57:33PM +1000, Peter Smith wrote:
I agree. Do you want me to make a new v4 patch to also do that, or
will you handle them in passing?I'll just go handle them on the way, no need to send an updated
patch.
Thanks for pushing this yesterday, and for handling the other quotes.
------
Kind Regards,
Peter Smith.
Fujitsu Australia.