Subject: Confusing link in streaming replication section

From: Thom Brown <[email-masked]>
Date: Wed, 10 Feb 2010 22:43:13 +0000

Hi all,

I'm looking at the latest docs for PostgreSQL 9.0
(http://developer.postgresql.org/pgdocs/postgres/streaming-replication.html)
and under the description of primary_conninfo, there's a link to
section 30.1 (http://developer.postgresql.org/pgdocs/postgres/libpq-connect.html)
which is supposed to describe the string format.  Having looked at
that page, however, it's not crystal clear what is meant by this
string format.  One can only assume it's referring to the
PQconnectdbParams section and the keywords that can be used for it,
which would also apply to a connection string, but there's no mention
of a "format" on that page.

I'm wondering if there should be another area added to the
documentation which simplifies this information, or at least presents
it differently, so that it isn't only within the context of the libpq
C library.  Either that, or clarify what information should be gleaned
from the page being linked to.

Thanks

Thom

---

From: Fujii Masao <[email-masked]>
Date: Fri, 12 Feb 2010 10:57:53 +0900

> of a "format" on that page.

Thanks for the report!

Though at first PQconnectdb() had been linked by the SR doc, instead
PQconnectdbParams() seems to have been linked wrongly when it was committed.
How about changing the link so as to point to PQconnectdb() again? Or
copy-pasting the following description from PQconnectdb() to the SR doc?

-----------
The passed string can be empty to use all default parameters, or it can
contain one or more parameter settings separated by whitespace. Each
parameter setting is in the form keyword = value. Spaces around the equal
sign are optional. To write an empty value, or a value containing spaces,
surround it with single quotes, e.g., keyword = 'a value'. Single quotes
and backslashes within the value must be escaped with a backslash,
i.e., \' and \\.

The currently recognized parameter key words are the same as above.
-----------

Regards,

-- 
Fujii Masao
NIPPON TELEGRAPH AND TELEPHONE CORPORATION
NTT Open Source Software Center

---

From: Thom Brown <[email-masked]>
Date: Fri, 12 Feb 2010 16:15:03 +0000

> copy-pasting the following description from PQconnectdb() to the SR doc?

Hmmm... well that last sentence refers to parameter key words which
won't appear on the SR page unless you copy and paste all that
information too.

I think the problem I have with there being a link to the libpq
control functions page is that the context of the settings isn't the
same, meaning the text on that page is specifically targetting people
looking for libpq info, rather than providing more generic information
which may be better placed in an appendix or something similar.

May I suggest a page on connection paramaters/connection strings which
can be referenced by multiple locations?  Otherwise I can imagine the
same information being presented a number of times throughout the
documentation.

Thanks

Thom

---

From: Thom Brown <[email-masked]>
Date: Wed, 24 Feb 2010 13:45:18 +0000

> same information being presented a number of times throughout the

Anyone had any thoughts on this?

Thom

---

From: Fujii Masao <[email-masked]>
Date: Thu, 25 Feb 2010 11:45:18 +0900

Sorry for the delay.

> which may be better placed in an appendix or something similar.

Since conninfo is tied closely to libpq, its information should
be in libpq chapter rather than an appendix or another chapter. No?

Regards,

---

From: Thom Brown <[email-masked]>
Date: Thu, 25 Feb 2010 08:03:44 +0000

> be in libpq chapter rather than an appendix or another chapter. No?

Yes, you're probably right since that's what the parameters are really for.

It looks as if Heikki has already changed the page anyway, which
includes and example of a parameter setting for primary_conninfo and
removes links to the libpq connection stuff.  Problem solved :)

Thom

---

From: Fujii Masao <[email-masked]>
Date: Thu, 25 Feb 2010 17:20:26 +0900

> removes links to the libpq connection stuff.  Problem solved :)

Yeah, Heikki removed the link from
http://developer.postgresql.org/pgdocs/postgres/streaming-replication.html#STREAMING-REPLICATION-SETUP

but it still exists in
http://developer.postgresql.org/pgdocs/postgres/standby-settings.html

So I think that we still need to modify the document about
primary_conninfo to suit your need. No?

Regards,

---

From: Heikki Linnakangas <[email-masked]>
Date: Thu, 25 Feb 2010 11:15:18 +0200

> primary_conninfo to suit your need. No?

Yeah, it's not very clear as it is.

How about this:

--- a/doc/src/sgml/recovery-config.sgml
+++ b/doc/src/sgml/recovery-config.sgml
@@ -193,7 +193,8 @@ restore_command = 'copy "C:\\server\\archivedir\\%f"
"%p"'
         <listitem>
          <para>
           Specifies a connection string to be used for the standby server
-          to connect with the primary. This string is in the same format as
+          to connect with the primary. This string is in the format
+          accepted by the libpq <function>PQconnectdb</function> function,
           described in <xref linkend="libpq-connect">. If any option is
           unspecified in this string, then the corresponding environment
           variable (see <xref linkend="libpq-envars">) is checked. If the

-- 
  Heikki Linnakangas
  EnterpriseDB   http://www.enterprisedb.com

---

From: Thom Brown <[email-masked]>
Date: Thu, 25 Feb 2010 09:19:43 +0000

>           variable (see <xref linkend="libpq-envars">) is checked. If the

Yes, that'll do :)

Thanks

Thom

---

From: Fujii Masao <[email-masked]>
Date: Thu, 25 Feb 2010 18:34:12 +0900

>           variable (see <xref linkend="libpq-envars">) is checked. If the

The following description in the document about PQconnectdb() doesn't fit
primary_conninfo because of restriction of readRecoveryCommandFile().

---------------
To write an empty value, or a value containing spaces,
surround it with single quotes, e.g., keyword = 'a value'. Single quotes
and backslashes within the value must be escaped with a backslash,
i.e., \' and \\.
---------------

So I'd like to copy and paste the description about conninfo except the
above. Thought? Here is the patch.

Regards,

-- 
Fujii Masao
NIPPON TELEGRAPH AND TELEPHONE CORPORATION
NTT Open Source Software Center
*** a/doc/src/sgml/recovery-config.sgml
--- b/doc/src/sgml/recovery-config.sgml
***************
*** 216,227 **** restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
          <listitem>
           <para>
            Specifies a connection string to be used for the standby server
!           to connect with the primary. This string is in the same format as
!           described in <xref linkend="libpq-connect">. If any option is
!           unspecified in this string, then the corresponding environment
!           variable (see <xref linkend="libpq-envars">) is checked. If the
!           environment variable is not set either, then
!           defaults are used.
           </para>
           <para>
            The built-in replication requires that a host name (or host address)
--- 216,229 ----
          <listitem>
           <para>
            Specifies a connection string to be used for the standby server
!           to connect with the primary. This string can contain one or more
!           parameter settings separated by whitespace. Each parameter setting
!           is in the form <literal>keyword = value</literal>. Spaces around
!           the equal sign are optional. The currently recognized parameter
!           key words are the same as described in <xref linkend="libpq-connect">.
!           If any option is unspecified in this string, then the corresponding
!           environment variable (see <xref linkend="libpq-envars">) is checked.
!           If the environment variable is not set either, then defaults are used.
           </para>
           <para>
            The built-in replication requires that a host name (or host address)

---

From: Heikki Linnakangas <[email-masked]>
Date: Thu, 25 Feb 2010 11:36:05 +0200

>>           variable (see <xref linkend="libpq-envars">) is checked. If the

Ok, committed.

---

From: Heikki Linnakangas <[email-masked]>
Date: Thu, 25 Feb 2010 12:41:35 +0200

> primary_conninfo because of restriction of readRecoveryCommandFile().

Hmm, so how does one escape quotes in recovery.conf? That would be valid
information, if readRecoveryCommandFile() didn't choke on quotes.

At some point we'll have to make the recovery.conf parsing smarter, if
only for consistency with postgresql.conf, or merge them completely...

---

From: Fujii Masao <[email-masked]>
Date: Thu, 25 Feb 2010 20:04:03 +0900

> information, if readRecoveryCommandFile() didn't choke on quotes.

Probably we can't.

> only for consistency with postgresql.conf, or merge them completely...

+10

Regards,