public inbox for [email protected]
help / color / mirror / Atom feedFrom: Michael Paquier <[email protected]>
To: Magnus Hagander <[email protected]>
Cc: Andres Freund <[email protected]>
Cc: Michael Paquier <[email protected]>
Cc: Petr Jelinek <[email protected]>
Cc: Şahap Aşçı <[email protected]>
Cc: pgsql-docs <[email protected]>
Cc: Fujii Masao <[email protected]>
Subject: Re: libpq options
Date: Mon, 5 Mar 2018 13:44:39 +0900
Message-ID: <[email protected]> (raw)
In-Reply-To: <CABUevEzwbfDb5fUWc7opVFyGBeCXqChrq-S1KXRSYDDexSuthw@mail.gmail.com>
References: <[email protected]>
<CAB7nPqRZ-8BkUuF1UR+xzg3J+LDTcafbJ75DZGsfn+++iF5_aw@mail.gmail.com>
<CAB7nPqTMQYKO4AJ6xfz-btAtvL-=CWxYnkXUOVEQGNk4Ey1k=Q@mail.gmail.com>
<[email protected]>
<[email protected]>
<CABUevEzwbfDb5fUWc7opVFyGBeCXqChrq-S1KXRSYDDexSuthw@mail.gmail.com>
On Fri, Mar 02, 2018 at 12:58:50PM +0100, Magnus Hagander wrote:
> To nitpick:
>
> + protocol. A Boolean value of <literal>true</literal> tells the
> backend
>
> We don't really have boolean values here, do we? It's just the string true
> that's treated as a boolean by the backend. It just sounds really weird to
> me when written that way. Particularly since the next sentence talks about
> passing "database" as the same thing.
>
> I know that's pretty much nitpicking, but I want to make sure I haven't
> actually missed/forgotten how some part of that one is handled..
Yes, that's indeed a bit inconsistent with the other parameters able to
use boolean-like parameters, like sslcompression or sslmode (deprecated
in favor requiressl), still those two ones are frontend-only
parameters, so they are just able to use "1" or "0". Replication is
part of the startup packet which uses parse_bool() so valid values can
be true, false, yes, no, on, off, 1 or 0. And it is even possible to
use upper-case characters. So why not documenting all that precisely
then?
> It also talks separately about "going into walsender mode" (=physical
> replication) and "instructs the walsender to connect to the database". I
> think that's a bit confusing. I suggest just calling it "physical
> replication mode" and "logical replication mode", and not bother mentioning
> walsender since that's quite internal.
Indeed, this term is pretty spread across the documentation as well.
I have taken into account this feedback, and created the new version
attached, for a v2.
Thoughts?
--
Michael
Attachments:
[text/x-diff] replication-param-doc-v2.patch (3.4K, 2-replication-param-doc-v2.patch)
download | inline diff:
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2a8e1f2e07..8934559239 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1262,6 +1262,57 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
</listitem>
</varlistentry>
+ <varlistentry id="libpq-connect-replication" xreflabel="replication">
+ <term><literal>replication</literal></term>
+ <listitem>
+ <para>
+ This option determines if a backend should use the replication
+ protocol. For a detailed description about the replication protocol,
+ consult <xref linkend="protocol-replication"/>. The following values,
+ which are case-insensitive, are supported:
+ <variablelist>
+ <varlistentry>
+ <term>
+ <literal>true</literal>, <literal>on</literal>,
+ <literal>yes</literal> or <literal>1</literal>
+ </term>
+ <listitem>
+ <para>
+ The backend goes into physical replication mode, wherein a small
+ set of replication commands can be issued instead of SQL statements.
+ Only the simple query protocol can be used in this case.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>database</literal></term>
+ <listitem>
+ <para>
+ The backend goes into logical replication mode, as the value
+ instructs the backend to connect to the database specified in
+ the <literal>dbname</literal> parameter. Only the simple query
+ protocol can be used in this case.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>false</literal>, <literal>off</literal>,
+ <literal>no</literal> or <literal>0</literal>
+ </term>
+ <listitem>
+ <para>
+ The backend is a regular one, which is the default behavior.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry id="libpq-connect-sslmode" xreflabel="sslmode">
<term><literal>sslmode</literal></term>
<listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 3cec9e0b0c..2e231efac0 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1635,15 +1635,9 @@ that cannot support <literal>tls-unique</literal> for some reason.
<para>
To initiate streaming replication, the frontend sends the
-<literal>replication</literal> parameter in the startup message. A Boolean value
-of <literal>true</literal> tells the backend to go into walsender mode, wherein a
-small set of replication commands can be issued instead of SQL statements. Only
-the simple query protocol can be used in walsender mode.
-Replication commands are logged in the server log when
+<xref linkend="libpq-connect-replication"/> connection parameter in the
+startup message. Replication commands are logged in the server log when
<xref linkend="guc-log-replication-commands"/> is enabled.
-Passing <literal>database</literal> as the value instructs walsender to connect to
-the database specified in the <literal>dbname</literal> parameter, which will allow
-the connection to be used for logical replication from that database.
</para>
<para>
For the purpose of testing replication commands, you can make a replication
[application/pgp-signature] signature.asc (833B, 3-signature.asc)
download
view thread (13+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected]
Subject: Re: libpq options
In-Reply-To: <[email protected]>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox