Connection string parameter 'replication' in documentation

Started by Takashi Ohnishiover 10 years ago5 messages

bwtakacy@gmail.com

over 10 years ago

1 attachment(s)

Hi,

I found that it can be set like 'replication = true' in connection
parameter as documentation says in "50.3. Streaming Replication Protocol",
but this parameter is not denoted in "31.1.2. Parameter Key Words".

How about adding notation about this paramter in 31.1.2.?
Attached is a patch for that.

Regards,

=====
Takashi Ohnishi

Attachments:

connect-parameter-replication.patchapplication/octet-stream; name=connect-parameter-replication.patchDownload

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 0ee018e..2989aae 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -966,6 +966,17 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       </listitem>
      </varlistentry>
 
+     <varlistentry id="libpq-connect-replication" xreflabel="replication">
+      <term><literal>replication</literal></term>
+      <listitem>
+      <para>
+       Connect with Streaming Replication Protocol (see <xref linkend="protocol-replication">).
+       This allows the value to be either boolean or the string 'database'.
+       The latter connects to a specific database given by <literal>dbName</>.
+      </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry id="libpq-connect-user" xreflabel="user">
       <term><literal>user</literal></term>
       <listitem>

Kyotaro HORIGUCHI

horiguchi.kyotaro@lab.ntt.co.jp

over 10 years ago

In reply to: Takashi Ohnishi (#1)

Re: Connection string parameter 'replication' in documentation

Hello,

At Fri, 2 Oct 2015 23:13:24 +0900, Takashi Ohnishi <bwtakacy@gmail.com> wrote in <CAO38NOp66ST2K_0xGpQYe3cfsvSAgbkF4fYUg55b=U2dwPLQHw@mail.gmail.com>

I found that it can be set like 'replication = true' in connection
parameter as documentation says in "50.3. Streaming Replication Protocol",
but this parameter is not denoted in "31.1.2. Parameter Key Words".

This is introduced by the commit 5a991ef, which allows logical
decoding via walsender interface. The paramter replication has
been there far from the commit intentionary as an 'undocumented
paramter'. This is, I suppose, because it is treated as a part of
the replication ptorocol, not a matter of ordinary clients at
all.

How about adding notation about this paramter in 31.1.2.?
Attached is a patch for that.

Since it has no meaning out of the context of replication agents,
it seems reasonable that the parameter is not documented in the
section.

Instead, the comment for libpqrcv_connect@libpqwalreceiver.c has
become outedated by the commit.

* We use the expand_dbname parameter to process the connection string (or
* URI), and pass some extra options. The deliberately undocumented
* parameter "replication=true" makes it a replication connection. The

This should be synced with the document.

Thoughts?

===============
diff --git a/src/backend/replication/libpqwalreceiver/libpqwalreceiver.c b/src/backend/replication/libpqwalreceiver/libpqwalreceiver.c
index b7bbcf6..e58c35a 100644
--- a/src/backend/replication/libpqwalreceiver/libpqwalreceiver.c
+++ b/src/backend/replication/libpqwalreceiver/libpqwalreceiver.c
@@ -94,10 +94,11 @@ libpqrcv_connect(char *conninfo)

 	/*
 	 * We use the expand_dbname parameter to process the connection string (or
-	 * URI), and pass some extra options. The deliberately undocumented
-	 * parameter "replication=true" makes it a replication connection. The
-	 * database name is ignored by the server in replication mode, but specify
-	 * "replication" for .pgpass lookup.
+	 * URI), and pass some extra options. The paramter "replication"
+	 * deliberately documented out of the section for the ordiary client
+	 * protocol, having "true" makes it a physical replication connection. The
+	 * database name is ignored by the server in physical replication mode,
+	 * but specify "replication" for .pgpass lookup.
 	 */
 	keys[0] = "dbname";
 	vals[0] = conninfo;
==========

regards,

--
Kyotaro Horiguchi
NTT Open Source Software Center

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Takashi Ohnishi

bwtakacy@gmail.com

over 10 years ago

In reply to: Kyotaro HORIGUCHI (#2)

Re: Connection string parameter 'replication' in documentation

Thanks for your answer:)

This is introduced by the commit 5a991ef, which allows logical
decoding via walsender interface. The paramter replication has
been there far from the commit intentionary as an 'undocumented
paramter'. This is, I suppose, because it is treated as a part of
the replication ptorocol, not a matter of ordinary clients at
all.

Ah, this is intentional!

Since it has no meaning out of the context of replication agents,
it seems reasonable that the parameter is not documented in the
section.

I see.
But, if this parameter is for logical decoding, I think it is better that
"46.3. Streaming Replication Protocol Interface" tells about this.

Instead, the comment for libpqrcv_connect@libpqwalreceiver.c has
become outedated by the commit.

* We use the expand_dbname parameter to process the connection string (or
* URI), and pass some extra options. The deliberately undocumented
* parameter "replication=true" makes it a replication connection. The

This should be synced with the document.

Agreed.

--
Takashi Ohnishi

2015-10-05 19:07 GMT+09:00 Kyotaro HORIGUCHI <
horiguchi.kyotaro@lab.ntt.co.jp>:

Show quoted text

Hello,

At Fri, 2 Oct 2015 23:13:24 +0900, Takashi Ohnishi <bwtakacy@gmail.com>
wrote in <CAO38NOp66ST2K_0xGpQYe3cfsvSAgbkF4fYUg55b=
U2dwPLQHw@mail.gmail.com>

I found that it can be set like 'replication = true' in connection
parameter as documentation says in "50.3. Streaming Replication

Protocol",

but this parameter is not denoted in "31.1.2. Parameter Key Words".

This is introduced by the commit 5a991ef, which allows logical
decoding via walsender interface. The paramter replication has
been there far from the commit intentionary as an 'undocumented
paramter'. This is, I suppose, because it is treated as a part of
the replication ptorocol, not a matter of ordinary clients at
all.

How about adding notation about this paramter in 31.1.2.?
Attached is a patch for that.

Since it has no meaning out of the context of replication agents,
it seems reasonable that the parameter is not documented in the
section.

Instead, the comment for libpqrcv_connect@libpqwalreceiver.c has
become outedated by the commit.

* We use the expand_dbname parameter to process the connection string (or
* URI), and pass some extra options. The deliberately undocumented
* parameter "replication=true" makes it a replication connection. The

This should be synced with the document.

Thoughts?
===============
diff --git a/src/backend/replication/libpqwalreceiver/libpqwalreceiver.c
b/src/backend/replication/libpqwalreceiver/libpqwalreceiver.c
index b7bbcf6..e58c35a 100644
--- a/src/backend/replication/libpqwalreceiver/libpqwalreceiver.c
+++ b/src/backend/replication/libpqwalreceiver/libpqwalreceiver.c
@@ -94,10 +94,11 @@ libpqrcv_connect(char *conninfo)
/*
* We use the expand_dbname parameter to process the connection
string (or
-        * URI), and pass some extra options. The deliberately undocumented
-        * parameter "replication=true" makes it a replication connection.
The
-        * database name is ignored by the server in replication mode, but
specify
-        * "replication" for .pgpass lookup.
+        * URI), and pass some extra options. The paramter "replication"
+        * deliberately documented out of the section for the ordiary
client
+        * protocol, having "true" makes it a physical replication
connection. The
+        * database name is ignored by the server in physical replication
mode,
+        * but specify "replication" for .pgpass lookup.
*/
keys[0] = "dbname";
vals[0] = conninfo;
==========
regards,

--
Kyotaro Horiguchi
NTT Open Source Software Center

Robert Haas

robertmhaas@gmail.com

over 10 years ago

In reply to: Kyotaro HORIGUCHI (#2)

Re: Connection string parameter 'replication' in documentation

On Mon, Oct 5, 2015 at 6:07 AM, Kyotaro HORIGUCHI
<horiguchi.kyotaro@lab.ntt.co.jp> wrote:

/*
* We use the expand_dbname parameter to process the connection string (or
-        * URI), and pass some extra options. The deliberately undocumented
-        * parameter "replication=true" makes it a replication connection. The
-        * database name is ignored by the server in replication mode, but specify
-        * "replication" for .pgpass lookup.
+        * URI), and pass some extra options. The paramter "replication"
+        * deliberately documented out of the section for the ordiary client
+        * protocol, having "true" makes it a physical replication connection. The
+        * database name is ignored by the server in physical replication mode,
+        * but specify "replication" for .pgpass lookup.
*/

I don't think this is an improvement, even ignoring the fact that
you've spelled a couple of words incorrectly. The original text seems
clear enough, and the new text isn't really fully accurate either: the
discussion of when the database name is ignored really shouldn't be
linked to whether this is logical or physical replication.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Kyotaro HORIGUCHI

horiguchi.kyotaro@lab.ntt.co.jp

over 10 years ago

In reply to: Robert Haas (#4)

Re: Connection string parameter 'replication' in documentation

Ouch!

At Tue, 6 Oct 2015 17:22:17 -0400, Robert Haas <robertmhaas@gmail.com> wrote in <CA+TgmobZVq6E+LwuM=Sva358SQ-FrD-qEim8wPZka9sHWna6mw@mail.gmail.com>

On Mon, Oct 5, 2015 at 6:07 AM, Kyotaro HORIGUCHI
<horiguchi.kyotaro@lab.ntt.co.jp> wrote:
/*
* We use the expand_dbname parameter to process the connection string (or
-        * URI), and pass some extra options. The deliberately undocumented
-        * parameter "replication=true" makes it a replication connection. The
-        * database name is ignored by the server in replication mode, but specify
-        * "replication" for .pgpass lookup.
+        * URI), and pass some extra options. The paramter "replication"
+        * deliberately documented out of the section for the ordiary client
+        * protocol, having "true" makes it a physical replication connection. The
+        * database name is ignored by the server in physical replication mode,
+        * but specify "replication" for .pgpass lookup.
*/
I don't think this is an improvement, even ignoring the fact that
you've spelled a couple of words incorrectly. The original text seems
clear enough, and the new text isn't really fully accurate either: the
discussion of when the database name is ignored really shouldn't be
linked to whether this is logical or physical replication.

Thank you for your kindly replying this. I agree to the comment
above. It is my mistake that "in physical.." looks to qualify
"ignored" but no future in polishing it.

regards,

--
Kyotaro Horiguchi
NTT Open Source Software Center

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers