pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedPostgreSQL 15 minor fixes in protocol.sgml
8+ messages / 5 participants
[nested] [flat]
* PostgreSQL 15 minor fixes in protocol.sgml
@ 2022-08-01 20:00 Ekaterina Kiryanova <e.kiryanova@postgrespro.ru>
0 siblings, 1 reply; 8+ messages in thread
From: Ekaterina Kiryanova @ 2022-08-01 20:00 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
Hello!
I've come across some typos in protocol.sgml for PostgreSQL 15 so please
have a look at the attached patch.
I didn't include it in the patch but I also suggest removing single
quotes around 'method' for the COMPRESSION option to help avoid
confusion. (All the supported compression methods consist of a single
word so in my opinion there is no need to use quotes in this case.)
-- <term><literal>COMPRESSION</literal>
<replaceable>'method'</replaceable></term>
I've also noticed that there are two ways to describe an option: "If set
to true" / "If true". As far as I know, the option here is specified by
its name rather than being explicitly set to true so "if true" seems to
be more correct, and this could be a slight improvement for this page.
Please correct me if I'm wrong.
Another point worth mentioning is that only this file contains the
phrase "two-phase transaction". I believe that "two-phase commit
transaction" or "transaction prepared for two-phase commit" depending on
the situation would be better wording.
And finally, could you please clarify this part?
-- The end LSN of the prepare transaction.
Is it a typo of "prepared transaction"? Or is it the LSN of the
transaction for Prepare?
If it's the latter, perhaps it'd make more sense to capitalize it.
--
Best regards,
Ekaterina Kiryanova
Technical Writer
Postgres Professional
the Russian PostgreSQL Company
Attachments:
[text/x-patch] protocol.patch (11.8K, ../../745414e7-efb2-a6ae-5b83-fcbdf35aabc8@postgrespro.ru/2-protocol.patch)
download | inline diff:
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 393311d304..f832aebfa6 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -2727,42 +2727,42 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<varlistentry>
<term><literal>COMPRESSION</literal> <replaceable>'method'</replaceable></term>
<listitem>
<para>
Instructs the server to compress the backup using the specified
method. Currently, the supported methods are <literal>gzip</literal>,
<literal>lz4</literal>, and <literal>zstd</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>COMPRESSION_DETAIL</literal> <replaceable>detail</replaceable></term>
<listitem>
<para>
Specifies details for the chosen compression method. This should only
be used in conjunction with the <literal>COMPRESSION</literal>
option. If the value is an integer, it specifies the compression
level. Otherwise, it should be a comma-separated list of items,
- each of the form <literal>keyword</literal> or
- <literal>keyword=value</literal>. Currently, the supported keywords
+ each of the form <replaceable>keyword</replaceable> or
+ <replaceable>keyword=value</replaceable>. Currently, the supported keywords
are <literal>level</literal> and <literal>workers</literal>.
</para>
<para>
The <literal>level</literal> keyword sets the compression level.
For <literal>gzip</literal> the compression level should be an
integer between 1 and 9, for <literal>lz4</literal> an integer
between 1 and 12, and for <literal>zstd</literal> an integer
between 1 and 22.
</para>
<para>
The <literal>workers</literal> keyword sets the number of threads
that should be used for parallel compression. Parallel compression
is supported only for <literal>zstd</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -2887,111 +2887,111 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
After the second regular result set, a CopyOutResponse will be sent.
The payload of each CopyData message will contain a message in one of
the following formats:
</para>
<variablelist>
<varlistentry>
<term>new archive (B)</term>
<listitem>
<variablelist>
<varlistentry>
<term>Byte1('n')</term>
<listitem><para>
- Identifes the messaage as indicating the start of a new archive.
+ Identifies the message as indicating the start of a new archive.
There will be one archive for the main data directory and one
for each additional tablespace; each will use tar format
(following the <quote>ustar interchange format</quote> specified
in the POSIX 1003.1-2008 standard).
</para></listitem>
</varlistentry>
<varlistentry>
<term>String</term>
<listitem><para>
The file name for this archive.
</para></listitem>
</varlistentry>
<varlistentry>
<term>String</term>
<listitem><para>
For the main data directory, an empty string. For other
tablespaces, the full path to the directory from which this
archive was created.
</para></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term>manifest (B)</term>
<listitem>
<variablelist>
<varlistentry>
<term>Byte1('m')</term>
<listitem><para>
- Identifes the message as indicating the start of the backup
+ Identifies the message as indicating the start of the backup
manifest.
</para></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term>archive or manifest data (B)</term>
<listitem>
<variablelist>
<varlistentry>
<term>Byte1('d')</term>
<listitem><para>
- Identifes the message as containing archive or manifest data.
+ Identifies the message as containing archive or manifest data.
</para></listitem>
</varlistentry>
<varlistentry>
<term>Byte<replaceable>n</replaceable></term>
<listitem><para>
Data bytes.
</para></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term>progress report (B)</term>
<listitem>
<variablelist>
<varlistentry>
<term>Byte1('p')</term>
<listitem><para>
- Identifes the message as a progress report.
+ Identifies the message as a progress report.
</para></listitem>
</varlistentry>
<varlistentry>
<term>Int64</term>
<listitem><para>
The number of bytes from the current tablespace for which
processing has been completed.
</para></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
<para>
After the CopyOutResponse, or all such responses, have been sent, a
final ordinary result set will be sent, containing the WAL end position
of the backup, in the same format as the start position.
</para>
@@ -6924,41 +6924,41 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<para>
Prepare timestamp of the transaction. The value is in number
of microseconds since PostgreSQL epoch (2000-01-01).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Int32 (TransactionId)</term>
<listitem>
<para>
Xid of the transaction.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>String</term>
<listitem>
<para>
- The user defined GID of the two-phase transaction.
+ The user-defined GID of the two-phase transaction.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry id="protocol-logicalrep-message-formats-Prepare">
<term>Prepare</term>
<listitem>
<variablelist>
<varlistentry>
<term>Byte1('P')</term>
<listitem>
<para>
Identifies the message as a two-phase prepared transaction message.
</para>
</listitem>
</varlistentry>
@@ -6995,41 +6995,41 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<para>
Prepare timestamp of the transaction. The value is in number
of microseconds since PostgreSQL epoch (2000-01-01).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Int32 (TransactionId)</term>
<listitem>
<para>
Xid of the transaction.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>String</term>
<listitem>
<para>
- The user defined GID of the two-phase transaction.
+ The user-defined GID of the two-phase transaction.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry id="protocol-logicalrep-message-formats-Commit-Prepared">
<term>Commit Prepared</term>
<listitem>
<variablelist>
<varlistentry>
<term>Byte1('K')</term>
<listitem>
<para>
Identifies the message as the commit of a two-phase transaction message.
</para>
</listitem>
</varlistentry>
@@ -7066,41 +7066,41 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<para>
Commit timestamp of the transaction. The value is in number
of microseconds since PostgreSQL epoch (2000-01-01).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Int32 (TransactionId)</term>
<listitem>
<para>
Xid of the transaction.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>String</term>
<listitem>
<para>
- The user defined GID of the two-phase transaction.
+ The user-defined GID of the two-phase transaction.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry id="protocol-logicalrep-message-formats-Rollback-Prepared">
<term>Rollback Prepared</term>
<listitem>
<variablelist>
<varlistentry>
<term>Byte1('r')</term>
<listitem>
<para>
Identifies the message as the rollback of a two-phase transaction message.
</para>
</listitem>
</varlistentry>
@@ -7147,41 +7147,41 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<para>
Rollback timestamp of the transaction. The value is in number
of microseconds since PostgreSQL epoch (2000-01-01).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Int32 (TransactionId)</term>
<listitem>
<para>
Xid of the transaction.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>String</term>
<listitem>
<para>
- The user defined GID of the two-phase transaction.
+ The user-defined GID of the two-phase transaction.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry id="protocol-logicalrep-message-formats-Stream-Prepare">
<term>Stream Prepare</term>
<listitem>
<variablelist>
<varlistentry>
<term>Byte1('p')</term>
<listitem>
<para>
Identifies the message as a two-phase stream prepare message.
</para>
</listitem>
</varlistentry>
@@ -7218,41 +7218,41 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<para>
Prepare timestamp of the transaction. The value is in number
of microseconds since PostgreSQL epoch (2000-01-01).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Int32 (TransactionId)</term>
<listitem>
<para>
Xid of the transaction.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>String</term>
<listitem>
<para>
- The user defined GID of the two-phase transaction.
+ The user-defined GID of the two-phase transaction.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
<para>
The following message parts are shared by the above messages.
</para>
<variablelist>
<varlistentry id="protocol-logicalrep-message-formats-TupleData">
<term>TupleData</term>
<listitem>
<variablelist>
<varlistentry>
<term>Int16</term>
<listitem>
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: PostgreSQL 15 minor fixes in protocol.sgml
@ 2022-08-02 10:58 Michael Paquier <michael@paquier.xyz>
parent: Ekaterina Kiryanova <e.kiryanova@postgrespro.ru>
0 siblings, 1 reply; 8+ messages in thread
From: Michael Paquier @ 2022-08-02 10:58 UTC (permalink / raw)
To: Ekaterina Kiryanova <e.kiryanova@postgrespro.ru>; +Cc: pgsql-docs@lists.postgresql.org, Amit Kapila <amit.kapila16@gmail.com>
On Mon, Aug 01, 2022 at 11:00:20PM +0300, Ekaterina Kiryanova wrote:
> I didn't include it in the patch but I also suggest removing single quotes
> around 'method' for the COMPRESSION option to help avoid confusion. (All the
> supported compression methods consist of a single word so in my opinion
> there is no need to use quotes in this case.)
> -- <term><literal>COMPRESSION</literal>
> <replaceable>'method'</replaceable></term>
Other options use quotes as well in their description in this area.
> I've also noticed that there are two ways to describe an option: "If set to
> true" / "If true". As far as I know, the option here is specified by its
> name rather than being explicitly set to true so "if true" seems to be more
> correct, and this could be a slight improvement for this page. Please
> correct me if I'm wrong.
Both sound pretty much the same to me.
> Another point worth mentioning is that only this file contains the phrase
> "two-phase transaction". I believe that "two-phase commit transaction" or
> "transaction prepared for two-phase commit" depending on the situation would
> be better wording.
"Prepare for two-phase commit" may be clearer?
> And finally, could you please clarify this part?
> -- The end LSN of the prepare transaction.
> Is it a typo of "prepared transaction"? Or is it the LSN of the transaction
> for Prepare?
> If it's the latter, perhaps it'd make more sense to capitalize it.
Hmm. The internals of 63cf61c refer to a "STREAM PREPARE", still the
protocol docs are quite messy ("prepare", "prepare timestamp", etc.)
so more consistency would be appropriate, it seems. Amit?
The part for the protocol messages with 2PC and logical replication
could use a larger rework. I have left these for now, and fixed the
rest of the typos you have found.
--
Michael
Attachments:
[application/pgp-signature] signature.asc (832B, ../../YukDQhptDrHv2jrz@paquier.xyz/2-signature.asc)
download
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: PostgreSQL 15 minor fixes in protocol.sgml
@ 2022-08-03 03:57 Amit Kapila <amit.kapila16@gmail.com>
parent: Michael Paquier <michael@paquier.xyz>
0 siblings, 2 replies; 8+ messages in thread
From: Amit Kapila @ 2022-08-03 03:57 UTC (permalink / raw)
To: Michael Paquier <michael@paquier.xyz>; Peter Smith <smithpb2250@gmail.com>; PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>; +Cc: Ekaterina Kiryanova <e.kiryanova@postgrespro.ru>; pgsql-docs@lists.postgresql.org
On Tue, Aug 2, 2022 at 4:28 PM Michael Paquier <michael@paquier.xyz> wrote:
>
> On Mon, Aug 01, 2022 at 11:00:20PM +0300, Ekaterina Kiryanova wrote:
>
> > Another point worth mentioning is that only this file contains the phrase
> > "two-phase transaction". I believe that "two-phase commit transaction" or
> > "transaction prepared for two-phase commit" depending on the situation would
> > be better wording.
>
> "Prepare for two-phase commit" may be clearer?
>
I think we can use just "Prepared transaction" instead. So, the
message "The user defined GID of the two-phase transaction." can be
changed to "The user defined GID of the prepared transaction.".
Similarly, the message "Identifies the message as a two-phase prepared
transaction message." could be changed to: "Identifies the message as
a prepared transaction message."
> > And finally, could you please clarify this part?
> > -- The end LSN of the prepare transaction.
> > Is it a typo of "prepared transaction"?
I think in this case it should be a "prepared transaction".
Thanks for the report and Thanks Michael for including me. I am just
redirecting it to -hackers so that others involved in this feature
also can share their views.
--
With Regards,
Amit Kapila.
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: PostgreSQL 15 minor fixes in protocol.sgml
@ 2022-08-03 05:26 Peter Smith <smithpb2250@gmail.com>
parent: Amit Kapila <amit.kapila16@gmail.com>
1 sibling, 1 reply; 8+ messages in thread
From: Peter Smith @ 2022-08-03 05:26 UTC (permalink / raw)
To: Amit Kapila <amit.kapila16@gmail.com>; +Cc: Michael Paquier <michael@paquier.xyz>; PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>; Ekaterina Kiryanova <e.kiryanova@postgrespro.ru>; pgsql-docs@lists.postgresql.org
On Wed, Aug 3, 2022 at 1:58 PM Amit Kapila <amit.kapila16@gmail.com> wrote:
>
> On Tue, Aug 2, 2022 at 4:28 PM Michael Paquier <michael@paquier.xyz> wrote:
> >
> > On Mon, Aug 01, 2022 at 11:00:20PM +0300, Ekaterina Kiryanova wrote:
> >
> > > Another point worth mentioning is that only this file contains the phrase
> > > "two-phase transaction". I believe that "two-phase commit transaction" or
> > > "transaction prepared for two-phase commit" depending on the situation would
> > > be better wording.
> >
> > "Prepare for two-phase commit" may be clearer?
> >
>
> I think we can use just "Prepared transaction" instead. So, the
> message "The user defined GID of the two-phase transaction." can be
> changed to "The user defined GID of the prepared transaction.".
> Similarly, the message "Identifies the message as a two-phase prepared
> transaction message." could be changed to: "Identifies the message as
> a prepared transaction message."
>
> > > And finally, could you please clarify this part?
> > > -- The end LSN of the prepare transaction.
> > > Is it a typo of "prepared transaction"?
>
> I think in this case it should be a "prepared transaction".
>
>
> Thanks for the report and Thanks Michael for including me. I am just
> redirecting it to -hackers so that others involved in this feature
> also can share their views.
>
PSA a patch to modify the descriptions as suggested by Amit.
------
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
[application/octet-stream] v1-0001-modify-protocol-message-descriptions-for-2PC.patch (5.3K, ../../CAHut+Ps8TLKFL0P4ghgERdTcDeB4y61zWm128524h88BhnYmfA@mail.gmail.com/2-v1-0001-modify-protocol-message-descriptions-for-2PC.patch)
download | inline diff:
From 0ec9b7c35ae046e7b3700f945c2543fde4fab005 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Wed, 3 Aug 2022 15:15:50 +1000
Subject: [PATCH v1] modify protocol message descriptions for 2PC.
---
doc/src/sgml/protocol.sgml | 28 ++++++++++++++--------------
1 file changed, 14 insertions(+), 14 deletions(-)
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 0d4b720..87870c5 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -6895,7 +6895,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Byte1('b')</term>
<listitem>
<para>
- Identifies the message as the beginning of a two-phase transaction message.
+ Identifies the message as the beginning of a prepared transaction message.
</para>
</listitem>
</varlistentry>
@@ -6941,7 +6941,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>String</term>
<listitem>
<para>
- The user defined GID of the two-phase transaction.
+ The user defined GID of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -6957,7 +6957,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Byte1('P')</term>
<listitem>
<para>
- Identifies the message as a two-phase prepared transaction message.
+ Identifies the message as a prepared transaction message.
</para>
</listitem>
</varlistentry>
@@ -7012,7 +7012,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>String</term>
<listitem>
<para>
- The user defined GID of the two-phase transaction.
+ The user defined GID of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7028,7 +7028,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Byte1('K')</term>
<listitem>
<para>
- Identifies the message as the commit of a two-phase transaction message.
+ Identifies the message as the commit of a prepared transaction message.
</para>
</listitem>
</varlistentry>
@@ -7046,7 +7046,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int64 (XLogRecPtr)</term>
<listitem>
<para>
- The LSN of the commit prepared.
+ The LSN of the commit of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7055,7 +7055,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int64 (XLogRecPtr)</term>
<listitem>
<para>
- The end LSN of the commit prepared transaction.
+ The end LSN of the commit of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7083,7 +7083,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>String</term>
<listitem>
<para>
- The user defined GID of the two-phase transaction.
+ The user defined GID of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7099,7 +7099,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Byte1('r')</term>
<listitem>
<para>
- Identifies the message as the rollback of a two-phase transaction message.
+ Identifies the message as the rollback of a prepared transaction message.
</para>
</listitem>
</varlistentry>
@@ -7126,7 +7126,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int64 (XLogRecPtr)</term>
<listitem>
<para>
- The end LSN of the rollback prepared transaction.
+ The end LSN of the rollback of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7164,7 +7164,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>String</term>
<listitem>
<para>
- The user defined GID of the two-phase transaction.
+ The user defined GID of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7180,7 +7180,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Byte1('p')</term>
<listitem>
<para>
- Identifies the message as a two-phase stream prepare message.
+ Identifies the message as a stream prepared transaction message.
</para>
</listitem>
</varlistentry>
@@ -7207,7 +7207,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int64 (XLogRecPtr)</term>
<listitem>
<para>
- The end LSN of the prepare transaction.
+ The end LSN of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7235,7 +7235,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>String</term>
<listitem>
<para>
- The user defined GID of the two-phase transaction.
+ The user defined GID of the prepared transaction.
</para>
</listitem>
</varlistentry>
--
1.8.3.1
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: PostgreSQL 15 minor fixes in protocol.sgml
@ 2022-08-03 10:53 Alvaro Herrera <alvherre@alvh.no-ip.org>
parent: Amit Kapila <amit.kapila16@gmail.com>
1 sibling, 1 reply; 8+ messages in thread
From: Alvaro Herrera @ 2022-08-03 10:53 UTC (permalink / raw)
To: Amit Kapila <amit.kapila16@gmail.com>; +Cc: Michael Paquier <michael@paquier.xyz>; Peter Smith <smithpb2250@gmail.com>; PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>; Ekaterina Kiryanova <e.kiryanova@postgrespro.ru>
On 2022-Aug-03, Amit Kapila wrote:
> Thanks for the report and Thanks Michael for including me. I am just
> redirecting it to -hackers so that others involved in this feature
> also can share their views.
I'm sorry, but our policy is that crossposts are not allowed. I think
this policy is bad, precisely because it prevents legitimate cases like
this one; but it is what it is.
I think we should change the policy, not back to allow indiscriminate
cross-posting, but to allow some limited form of it. For example I
think pg-bugs+pg-hackers and pg-docs+pg-hackers should be allowed
combinations. Just saying.
--
Álvaro Herrera Breisgau, Deutschland — https://www.EnterpriseDB.com/
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: PostgreSQL 15 minor fixes in protocol.sgml
@ 2022-08-04 03:04 Amit Kapila <amit.kapila16@gmail.com>
parent: Peter Smith <smithpb2250@gmail.com>
0 siblings, 1 reply; 8+ messages in thread
From: Amit Kapila @ 2022-08-04 03:04 UTC (permalink / raw)
To: Peter Smith <smithpb2250@gmail.com>; +Cc: Michael Paquier <michael@paquier.xyz>; Ekaterina Kiryanova <e.kiryanova@postgrespro.ru>; pgsql-docs@lists.postgresql.org, Ajin Cherian <itsajin@gmail.com>
On Wed, Aug 3, 2022 at 10:56 AM Peter Smith <smithpb2250@gmail.com> wrote:
>
> PSA a patch to modify the descriptions as suggested by Amit.
>
*
<para>
- The end LSN of the commit prepared transaction.
+ The end LSN of the commit of the prepared transaction.
...
...
- Identifies the message as the commit of a two-phase
transaction message.
+ Identifies the message as the commit of a prepared
transaction message.
In the above messages, we can even directly say "commit prepared
transaction" but as you have written appears clear to me.
*
For timestamp, related messages, we have three different messages:
Commit timestamp of the transaction. The value is in number of
microseconds since PostgreSQL epoch (2000-01-01).
Prepare timestamp of the transaction. The value is in number of
microseconds since PostgreSQL epoch (2000-01-01).
Rollback timestamp of the transaction. The value is in number of
microseconds since PostgreSQL epoch (2000-01-01).
We can improve by saying "Timestamp of prepared transaction" for the
second one but it will make it bit inconsistent with others, so not
sure if changing it makes sense or if there is a better way to change
all the three messages.
Thoughts?
--
With Regards,
Amit Kapila.
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: PostgreSQL 15 minor fixes in protocol.sgml
@ 2022-08-04 03:06 Amit Kapila <amit.kapila16@gmail.com>
parent: Alvaro Herrera <alvherre@alvh.no-ip.org>
0 siblings, 0 replies; 8+ messages in thread
From: Amit Kapila @ 2022-08-04 03:06 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@alvh.no-ip.org>; +Cc: Michael Paquier <michael@paquier.xyz>; Peter Smith <smithpb2250@gmail.com>; PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>; Ekaterina Kiryanova <e.kiryanova@postgrespro.ru>
On Wed, Aug 3, 2022 at 4:23 PM Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:
>
> On 2022-Aug-03, Amit Kapila wrote:
>
> > Thanks for the report and Thanks Michael for including me. I am just
> > redirecting it to -hackers so that others involved in this feature
> > also can share their views.
>
> I'm sorry, but our policy is that crossposts are not allowed. I think
> this policy is bad, precisely because it prevents legitimate cases like
> this one; but it is what it is.
>
> I think we should change the policy, not back to allow indiscriminate
> cross-posting, but to allow some limited form of it. For example I
> think pg-bugs+pg-hackers and pg-docs+pg-hackers should be allowed
> combinations. Just saying.
>
+1.
--
With Regards,
Amit Kapila.
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: PostgreSQL 15 minor fixes in protocol.sgml
@ 2022-08-09 01:05 Peter Smith <smithpb2250@gmail.com>
parent: Amit Kapila <amit.kapila16@gmail.com>
0 siblings, 0 replies; 8+ messages in thread
From: Peter Smith @ 2022-08-09 01:05 UTC (permalink / raw)
To: Amit Kapila <amit.kapila16@gmail.com>; +Cc: Michael Paquier <michael@paquier.xyz>; Ekaterina Kiryanova <e.kiryanova@postgrespro.ru>; pgsql-docs@lists.postgresql.org, Ajin Cherian <itsajin@gmail.com>
On Thu, Aug 4, 2022 at 1:04 PM Amit Kapila <amit.kapila16@gmail.com> wrote:
>
> On Wed, Aug 3, 2022 at 10:56 AM Peter Smith <smithpb2250@gmail.com> wrote:
> >
> > PSA a patch to modify the descriptions as suggested by Amit.
> >
>
> *
> <para>
> - The end LSN of the commit prepared transaction.
> + The end LSN of the commit of the prepared transaction.
> ...
> ...
> - Identifies the message as the commit of a two-phase
> transaction message.
> + Identifies the message as the commit of a prepared
> transaction message.
>
> In the above messages, we can even directly say "commit prepared
> transaction" but as you have written appears clear to me.
>
> *
> For timestamp, related messages, we have three different messages:
> Commit timestamp of the transaction. The value is in number of
> microseconds since PostgreSQL epoch (2000-01-01).
> Prepare timestamp of the transaction. The value is in number of
> microseconds since PostgreSQL epoch (2000-01-01).
> Rollback timestamp of the transaction. The value is in number of
> microseconds since PostgreSQL epoch (2000-01-01).
>
> We can improve by saying "Timestamp of prepared transaction" for the
> second one but it will make it bit inconsistent with others, so not
> sure if changing it makes sense or if there is a better way to change
> all the three messages.
>
> Thoughts?
>
There was no feedback for Amit's previous post [1], so I am just
attaching the same [2] patch again, but this time for both HEAD and
REL_15_STABLE.
------
[1] https://www.postgresql.org/message-id/CAA4eK1LHSDb3KVRZZnYeBF0-SodMKYP%3DV%2B2VmrVBvRNK%3Dej1Tw%40ma...
[2] https://www.postgresql.org/message-id/CAHut%2BPs8TLKFL0P4ghgERdTcDeB4y61zWm128524h88BhnYmfA%40mail.g...
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
[application/octet-stream] v2-HEAD-0001-modify-protocol-message-descriptions-for-2PC.patch (5.3K, ../../CAHut+PvdPqGif+Wz1TDLi-XmhHSuUJRYwCkBTZO8ijbCF9zZKQ@mail.gmail.com/2-v2-HEAD-0001-modify-protocol-message-descriptions-for-2PC.patch)
download | inline diff:
From 1a707b2d850027a41493644ef841da6494c7747d Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Tue, 9 Aug 2022 10:29:22 +1000
Subject: [PATCH v2] modify protocol message descriptions for 2PC.
---
doc/src/sgml/protocol.sgml | 28 ++++++++++++++--------------
1 file changed, 14 insertions(+), 14 deletions(-)
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 0d4b720..87870c5 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -6895,7 +6895,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Byte1('b')</term>
<listitem>
<para>
- Identifies the message as the beginning of a two-phase transaction message.
+ Identifies the message as the beginning of a prepared transaction message.
</para>
</listitem>
</varlistentry>
@@ -6941,7 +6941,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>String</term>
<listitem>
<para>
- The user defined GID of the two-phase transaction.
+ The user defined GID of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -6957,7 +6957,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Byte1('P')</term>
<listitem>
<para>
- Identifies the message as a two-phase prepared transaction message.
+ Identifies the message as a prepared transaction message.
</para>
</listitem>
</varlistentry>
@@ -7012,7 +7012,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>String</term>
<listitem>
<para>
- The user defined GID of the two-phase transaction.
+ The user defined GID of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7028,7 +7028,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Byte1('K')</term>
<listitem>
<para>
- Identifies the message as the commit of a two-phase transaction message.
+ Identifies the message as the commit of a prepared transaction message.
</para>
</listitem>
</varlistentry>
@@ -7046,7 +7046,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int64 (XLogRecPtr)</term>
<listitem>
<para>
- The LSN of the commit prepared.
+ The LSN of the commit of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7055,7 +7055,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int64 (XLogRecPtr)</term>
<listitem>
<para>
- The end LSN of the commit prepared transaction.
+ The end LSN of the commit of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7083,7 +7083,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>String</term>
<listitem>
<para>
- The user defined GID of the two-phase transaction.
+ The user defined GID of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7099,7 +7099,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Byte1('r')</term>
<listitem>
<para>
- Identifies the message as the rollback of a two-phase transaction message.
+ Identifies the message as the rollback of a prepared transaction message.
</para>
</listitem>
</varlistentry>
@@ -7126,7 +7126,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int64 (XLogRecPtr)</term>
<listitem>
<para>
- The end LSN of the rollback prepared transaction.
+ The end LSN of the rollback of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7164,7 +7164,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>String</term>
<listitem>
<para>
- The user defined GID of the two-phase transaction.
+ The user defined GID of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7180,7 +7180,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Byte1('p')</term>
<listitem>
<para>
- Identifies the message as a two-phase stream prepare message.
+ Identifies the message as a stream prepared transaction message.
</para>
</listitem>
</varlistentry>
@@ -7207,7 +7207,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int64 (XLogRecPtr)</term>
<listitem>
<para>
- The end LSN of the prepare transaction.
+ The end LSN of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7235,7 +7235,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>String</term>
<listitem>
<para>
- The user defined GID of the two-phase transaction.
+ The user defined GID of the prepared transaction.
</para>
</listitem>
</varlistentry>
--
1.8.3.1
[application/octet-stream] v2-PG15-0001-modify-protocol-message-descriptions-for-2PC.patch (5.3K, ../../CAHut+PvdPqGif+Wz1TDLi-XmhHSuUJRYwCkBTZO8ijbCF9zZKQ@mail.gmail.com/3-v2-PG15-0001-modify-protocol-message-descriptions-for-2PC.patch)
download | inline diff:
From 291227de50dae85020344d674a0e024637038135 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Tue, 9 Aug 2022 10:57:03 +1000
Subject: [PATCH v2] modify protocol message descriptions for 2PC.
---
doc/src/sgml/protocol.sgml | 28 ++++++++++++++--------------
1 file changed, 14 insertions(+), 14 deletions(-)
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index d3296b3..c549c08 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -6895,7 +6895,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Byte1('b')</term>
<listitem>
<para>
- Identifies the message as the beginning of a two-phase transaction message.
+ Identifies the message as the beginning of a prepared transaction message.
</para>
</listitem>
</varlistentry>
@@ -6941,7 +6941,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>String</term>
<listitem>
<para>
- The user defined GID of the two-phase transaction.
+ The user defined GID of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -6957,7 +6957,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Byte1('P')</term>
<listitem>
<para>
- Identifies the message as a two-phase prepared transaction message.
+ Identifies the message as a prepared transaction message.
</para>
</listitem>
</varlistentry>
@@ -7012,7 +7012,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>String</term>
<listitem>
<para>
- The user defined GID of the two-phase transaction.
+ The user defined GID of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7028,7 +7028,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Byte1('K')</term>
<listitem>
<para>
- Identifies the message as the commit of a two-phase transaction message.
+ Identifies the message as the commit of a prepared transaction message.
</para>
</listitem>
</varlistentry>
@@ -7046,7 +7046,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int64 (XLogRecPtr)</term>
<listitem>
<para>
- The LSN of the commit prepared.
+ The LSN of the commit of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7055,7 +7055,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int64 (XLogRecPtr)</term>
<listitem>
<para>
- The end LSN of the commit prepared transaction.
+ The end LSN of the commit of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7083,7 +7083,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>String</term>
<listitem>
<para>
- The user defined GID of the two-phase transaction.
+ The user defined GID of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7099,7 +7099,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Byte1('r')</term>
<listitem>
<para>
- Identifies the message as the rollback of a two-phase transaction message.
+ Identifies the message as the rollback of a prepared transaction message.
</para>
</listitem>
</varlistentry>
@@ -7126,7 +7126,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int64 (XLogRecPtr)</term>
<listitem>
<para>
- The end LSN of the rollback prepared transaction.
+ The end LSN of the rollback of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7164,7 +7164,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>String</term>
<listitem>
<para>
- The user defined GID of the two-phase transaction.
+ The user defined GID of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7180,7 +7180,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Byte1('p')</term>
<listitem>
<para>
- Identifies the message as a two-phase stream prepare message.
+ Identifies the message as a stream prepared transaction message.
</para>
</listitem>
</varlistentry>
@@ -7207,7 +7207,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int64 (XLogRecPtr)</term>
<listitem>
<para>
- The end LSN of the prepare transaction.
+ The end LSN of the prepared transaction.
</para>
</listitem>
</varlistentry>
@@ -7235,7 +7235,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>String</term>
<listitem>
<para>
- The user defined GID of the two-phase transaction.
+ The user defined GID of the prepared transaction.
</para>
</listitem>
</varlistentry>
--
1.8.3.1
^ permalink raw reply [nested|flat] 8+ messages in thread
end of thread, other threads:[~2022-08-09 01:05 UTC | newest]
Thread overview: 8+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2022-08-01 20:00 PostgreSQL 15 minor fixes in protocol.sgml Ekaterina Kiryanova <e.kiryanova@postgrespro.ru>
2022-08-02 10:58 ` Michael Paquier <michael@paquier.xyz>
2022-08-03 03:57 ` Amit Kapila <amit.kapila16@gmail.com>
2022-08-03 05:26 ` Peter Smith <smithpb2250@gmail.com>
2022-08-04 03:04 ` Amit Kapila <amit.kapila16@gmail.com>
2022-08-09 01:05 ` Peter Smith <smithpb2250@gmail.com>
2022-08-03 10:53 ` Alvaro Herrera <alvherre@alvh.no-ip.org>
2022-08-04 03:06 ` Amit Kapila <amit.kapila16@gmail.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox