Tom Lane <t...@sss.pgh.pa.us> writes: > I really don't see anything wrong with the FDW's documentation. To claim > that it's not clear, you have to suppose that a connstring's dbname field > is allowed to recursively contain a connstring. However, if you've got a > concrete suggestion about improving the wording, let's see it. > > Now on the other hand, libpq's documentation seems a little confusing > on this point independently of the FDW: so far as I can see, what "certain > contexts" means is not clearly defined anywhere, and for that matter > "checked for extended formats" is a masterpiece of unhelpful obfuscation. > > regards, tom lane
I have to admit that you are right: strictly speaking, FDW doc says it accepts the same options as libpq connstring => libpq connstring itself can't contain another connstring => expansion is not allowed. However, we might probably save the readers a few mental cycles if we avoid the words 'connection strings' and just say that recognized options are the same as of libpq ones, with (probably, see below) an explicit addition that dbname is not expanded. Regarding "checking for extended formats" phrase, I see three solutions: 1) In the description of 'dbname' parameter mention all the cases where it is possibly expanded, which doesn't sound as a good idea; 2) Specify whether dbname is expanded in every reference to the list of libpq options, which is arguably better. 3) We can also replace "In certain contexts" with "Where explicitly mentioned" in the desciption of 'dbname', and, while referencing options, never say anything about dbname if it is not expanded. Besides, why not substitute "checked for extended formats" with "might be recognized as a connection string" -- are there any other formats than connstr? The changes with point 3 chosen might look as in attached file.
>From 96d74f050724a8373c04e48205510a5a7e80d447 Mon Sep 17 00:00:00 2001 From: Arseny Sher <sher-...@yandex.ru> Date: Thu, 27 Jul 2017 22:45:04 +0300 Subject: [PATCH] libpq docs: dbname param is expanded only when explicitly mentioned. Also, avoid mentioning connstring in the desciption of parameters accepted by postgres_fdw server. --- doc/src/sgml/libpq.sgml | 7 +++---- doc/src/sgml/postgres-fdw.sgml | 6 +++--- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index ad5e9b95b4..dde6647fc5 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1040,10 +1040,9 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <term><literal>dbname</literal></term> <listitem> <para> - The database name. Defaults to be the same as the user name. - In certain contexts, the value is checked for extended - formats; see <xref linkend="libpq-connstring"> for more details on - those. + The database name. Defaults to be the same as the user name. Where + explicitly said, the value can be recognized as a connection string; + see <xref linkend="libpq-connstring"> for more details on those. </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml index d83fc9e52b..e3c41bfd97 100644 --- a/doc/src/sgml/postgres-fdw.sgml +++ b/doc/src/sgml/postgres-fdw.sgml @@ -100,9 +100,9 @@ <para> A foreign server using the <filename>postgres_fdw</> foreign data wrapper - can have the same options that <application>libpq</> accepts in - connection strings, as described in <xref linkend="libpq-paramkeywords">, - except that these options are not allowed: + can have the same options that are recognized by <application>libpq</>, as + described in <xref linkend="libpq-paramkeywords">, except that these + options are not allowed: <itemizedlist spacing="compact"> <listitem> -- 2.11.0
-- Sent via pgsql-hackers mailing list (email@example.com) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers