public inbox for [email protected]help / color / mirror / Atom feed
Confusing link in streaming replication section 13+ messages / 3 participants [nested] [flat]
* Confusing link in streaming replication section @ 2010-02-10 22:43 Thom Brown <[email protected]> 0 siblings, 1 reply; 13+ messages in thread From: Thom Brown @ 2010-02-10 22:43 UTC (permalink / raw) To: pgsql-docs 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 ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Confusing link in streaming replication section @ 2010-02-12 01:57 Fujii Masao <[email protected]> parent: Thom Brown <[email protected]> 0 siblings, 1 reply; 13+ messages in thread From: Fujii Masao @ 2010-02-12 01:57 UTC (permalink / raw) To: Thom Brown <[email protected]>; +Cc: pgsql-docs On Thu, Feb 11, 2010 at 7:43 AM, Thom Brown <[email protected]> wrote: > 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. 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 ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Confusing link in streaming replication section @ 2010-02-12 16:15 Thom Brown <[email protected]> parent: Fujii Masao <[email protected]> 0 siblings, 2 replies; 13+ messages in thread From: Thom Brown @ 2010-02-12 16:15 UTC (permalink / raw) To: Fujii Masao <[email protected]>; +Cc: pgsql-docs On 12 February 2010 01:57, Fujii Masao <[email protected]> wrote: > On Thu, Feb 11, 2010 at 7:43 AM, Thom Brown <[email protected]> wrote: >> 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. > > 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. > ----------- 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 ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Confusing link in streaming replication section @ 2010-02-24 13:45 Thom Brown <[email protected]> parent: Thom Brown <[email protected]> 1 sibling, 0 replies; 13+ messages in thread From: Thom Brown @ 2010-02-24 13:45 UTC (permalink / raw) To: Fujii Masao <[email protected]>; +Cc: pgsql-docs On 12 February 2010 16:15, Thom Brown <[email protected]> wrote: > On 12 February 2010 01:57, Fujii Masao <[email protected]> wrote: >> On Thu, Feb 11, 2010 at 7:43 AM, Thom Brown <[email protected]> wrote: >>> 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. >> >> 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. >> ----------- > > 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 > Anyone had any thoughts on this? Thom ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Confusing link in streaming replication section @ 2010-02-25 02:45 Fujii Masao <[email protected]> parent: Thom Brown <[email protected]> 1 sibling, 1 reply; 13+ messages in thread From: Fujii Masao @ 2010-02-25 02:45 UTC (permalink / raw) To: Thom Brown <[email protected]>; +Cc: pgsql-docs Sorry for the delay. On Sat, Feb 13, 2010 at 1:15 AM, Thom Brown <[email protected]> wrote: > 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. Since conninfo is tied closely to libpq, its information should be in libpq chapter rather than an appendix or another chapter. No? Regards, -- Fujii Masao NIPPON TELEGRAPH AND TELEPHONE CORPORATION NTT Open Source Software Center ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Confusing link in streaming replication section @ 2010-02-25 08:03 Thom Brown <[email protected]> parent: Fujii Masao <[email protected]> 0 siblings, 1 reply; 13+ messages in thread From: Thom Brown @ 2010-02-25 08:03 UTC (permalink / raw) To: Fujii Masao <[email protected]>; +Cc: pgsql-docs On 25 February 2010 02:45, Fujii Masao <[email protected]> wrote: > Sorry for the delay. > > On Sat, Feb 13, 2010 at 1:15 AM, Thom Brown <[email protected]> wrote: >> 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. > > Since conninfo is tied closely to libpq, its information should > 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 ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Confusing link in streaming replication section @ 2010-02-25 08:20 Fujii Masao <[email protected]> parent: Thom Brown <[email protected]> 0 siblings, 1 reply; 13+ messages in thread From: Fujii Masao @ 2010-02-25 08:20 UTC (permalink / raw) To: Thom Brown <[email protected]>; +Cc: pgsql-docs On Thu, Feb 25, 2010 at 5:03 PM, Thom Brown <[email protected]> wrote: > 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 :) Yeah, Heikki removed the link from http://developer.postgresql.org/pgdocs/postgres/streaming-replication.html#STREAMING-REPLICATION-SET... 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, -- Fujii Masao NIPPON TELEGRAPH AND TELEPHONE CORPORATION NTT Open Source Software Center ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Confusing link in streaming replication section @ 2010-02-25 09:15 Heikki Linnakangas <[email protected]> parent: Fujii Masao <[email protected]> 0 siblings, 2 replies; 13+ messages in thread From: Heikki Linnakangas @ 2010-02-25 09:15 UTC (permalink / raw) To: Fujii Masao <[email protected]>; +Cc: Thom Brown <[email protected]>; pgsql-docs Fujii Masao wrote: > On Thu, Feb 25, 2010 at 5:03 PM, Thom Brown <[email protected]> wrote: >> 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 :) > > Yeah, Heikki removed the link from > http://developer.postgresql.org/pgdocs/postgres/streaming-replication.html#STREAMING-REPLICATION-SET... > > 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? 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 ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Confusing link in streaming replication section @ 2010-02-25 09:19 Thom Brown <[email protected]> parent: Heikki Linnakangas <[email protected]> 1 sibling, 1 reply; 13+ messages in thread From: Thom Brown @ 2010-02-25 09:19 UTC (permalink / raw) To: Heikki Linnakangas <[email protected]>; +Cc: Fujii Masao <[email protected]>; pgsql-docs On 25 February 2010 09:15, Heikki Linnakangas <[email protected]> wrote: > Fujii Masao wrote: >> On Thu, Feb 25, 2010 at 5:03 PM, Thom Brown <[email protected]> wrote: >>> 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 :) >> >> Yeah, Heikki removed the link from >> http://developer.postgresql.org/pgdocs/postgres/streaming-replication.html#STREAMING-REPLICATION-SET... >> >> 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? > > 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 > Yes, that'll do :) Thanks Thom ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Confusing link in streaming replication section @ 2010-02-25 09:34 Fujii Masao <[email protected]> parent: Heikki Linnakangas <[email protected]> 1 sibling, 1 reply; 13+ messages in thread From: Fujii Masao @ 2010-02-25 09:34 UTC (permalink / raw) To: Heikki Linnakangas <[email protected]>; +Cc: Thom Brown <[email protected]>; pgsql-docs On Thu, Feb 25, 2010 at 6:15 PM, Heikki Linnakangas <[email protected]> wrote: > 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 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 Attachments: [text/x-patch] primary_conninfo_doc.patch (1.7K, 2-primary_conninfo_doc.patch) download | inline diff: *** 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) ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Confusing link in streaming replication section @ 2010-02-25 09:36 Heikki Linnakangas <[email protected]> parent: Thom Brown <[email protected]> 0 siblings, 0 replies; 13+ messages in thread From: Heikki Linnakangas @ 2010-02-25 09:36 UTC (permalink / raw) To: Thom Brown <[email protected]>; +Cc: Fujii Masao <[email protected]>; pgsql-docs Thom Brown wrote: > On 25 February 2010 09:15, Heikki Linnakangas > <[email protected]> wrote: >> Fujii Masao wrote: >>> On Thu, Feb 25, 2010 at 5:03 PM, Thom Brown <[email protected]> wrote: >>>> 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 :) >>> Yeah, Heikki removed the link from >>> http://developer.postgresql.org/pgdocs/postgres/streaming-replication.html#STREAMING-REPLICATION-SET... >>> >>> 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? >> 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 >> > > Yes, that'll do :) Ok, committed. -- Heikki Linnakangas EnterpriseDB http://www.enterprisedb.com ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Confusing link in streaming replication section @ 2010-02-25 10:41 Heikki Linnakangas <[email protected]> parent: Fujii Masao <[email protected]> 0 siblings, 1 reply; 13+ messages in thread From: Heikki Linnakangas @ 2010-02-25 10:41 UTC (permalink / raw) To: Fujii Masao <[email protected]>; +Cc: Thom Brown <[email protected]>; pgsql-docs Fujii Masao wrote: > On Thu, Feb 25, 2010 at 6:15 PM, Heikki Linnakangas > <[email protected]> wrote: >> 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 > > 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 \\. > --------------- 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... -- Heikki Linnakangas EnterpriseDB http://www.enterprisedb.com ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Confusing link in streaming replication section @ 2010-02-25 11:04 Fujii Masao <[email protected]> parent: Heikki Linnakangas <[email protected]> 0 siblings, 0 replies; 13+ messages in thread From: Fujii Masao @ 2010-02-25 11:04 UTC (permalink / raw) To: Heikki Linnakangas <[email protected]>; +Cc: Thom Brown <[email protected]>; pgsql-docs On Thu, Feb 25, 2010 at 7:41 PM, Heikki Linnakangas <[email protected]> wrote: > Hmm, so how does one escape quotes in recovery.conf? That would be valid > information, if readRecoveryCommandFile() didn't choke on quotes. Probably we can't. > At some point we'll have to make the recovery.conf parsing smarter, if > only for consistency with postgresql.conf, or merge them completely... +10 Regards, -- Fujii Masao NIPPON TELEGRAPH AND TELEPHONE CORPORATION NTT Open Source Software Center ^ permalink raw reply [nested|flat] 13+ messages in thread
end of thread, other threads:[~2010-02-25 11:04 UTC | newest] Thread overview: 13+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2010-02-10 22:43 Confusing link in streaming replication section Thom Brown <[email protected]> 2010-02-12 01:57 ` Fujii Masao <[email protected]> 2010-02-12 16:15 ` Thom Brown <[email protected]> 2010-02-24 13:45 ` Thom Brown <[email protected]> 2010-02-25 02:45 ` Fujii Masao <[email protected]> 2010-02-25 08:03 ` Thom Brown <[email protected]> 2010-02-25 08:20 ` Fujii Masao <[email protected]> 2010-02-25 09:15 ` Heikki Linnakangas <[email protected]> 2010-02-25 09:19 ` Thom Brown <[email protected]> 2010-02-25 09:36 ` Heikki Linnakangas <[email protected]> 2010-02-25 09:34 ` Fujii Masao <[email protected]> 2010-02-25 10:41 ` Heikki Linnakangas <[email protected]> 2010-02-25 11:04 ` Fujii Masao <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox