Re: [HACKERS] expand_dbname in postgres_fdw

Tom Lane <tgl@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-ars@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 (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers