Thread: 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], 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]), so IMO these instances should be changed to <literal>FULL</full> to eliminate that ambiguity. ~~~ PSA patch v1 which implements the above changes. ------ [1] https://www.postgresql.org/message-id/CAA4eK1J8R-qS97cu27sF2%3DqzjhuQNkv%2BZvgaTzFv7rs-LA4c2w%40mail.gmail.com [2] https://www.postgresql.org/docs/current/sql-altertable.html#SQL-ALTERTABLE-REPLICA-IDENTITY Kind Regards, Peter Smith. Fujitsu Australia
Attachment
A rebase was needed due to the recent REPLICA IDENTITY push [1]. PSA v2. ------ [1] https://github.com/postgres/postgres/commit/89e46da5e511a6970e26a020f265c9fb4b72b1d2 Kind Regards, Peter Smith. Fujitsu Australia
Attachment
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 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 > Thanks for giving some feedback on my patch. PSA v3 which is changed per your suggestion. ------ Kind Regards, Peter Smith. Fujitsu Australia
Attachment
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
Attachment
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
Attachment
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.