Date: Wed, 16 Oct 2024 16:54:43 -0400
From: Bruce Momjian <bruce@momjian.us>
To: "David G. Johnston" <david.g.johnston@gmail.com>
Cc: marc@msys.ch, pgsql-docs@lists.postgresql.org
Subject: Re: Documentation of .pgpass for Unix is incomplete
Message-ID: <ZxAoE-V74KRR26Jb@momjian.us>
References: <172311029184.915368.14898011794686876553@wrigleys.postgresql.org>
 <ZsPd_1ahHdqcQjgA@momjian.us>
 <CAKFQuwZ-T-zsVM7gApS9-XU9vGxC7Oa-UyRQPVcJFagNU=AjOw@mail.gmail.com>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="2KCFEcop39rxdjOr"
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: 
 <CAKFQuwZ-T-zsVM7gApS9-XU9vGxC7Oa-UyRQPVcJFagNU=AjOw@mail.gmail.com>
Archived-At: 
 <https://www.postgresql.org/message-id/ZxAoE-V74KRR26Jb%40momjian.us>
Precedence: bulk


--2KCFEcop39rxdjOr
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit

On Mon, Aug 19, 2024 at 05:42:33PM -0700, David G. Johnston wrote:
> On Mon, Aug 19, 2024 at 5:06 PM Bruce Momjian <bruce@momjian.us> wrote:
>     Well, it is more complicated than checking just HOME because it calls
>     getpwuid_r() if HOME is not set:
> 
>             https://doxygen.postgresql.org/fe-connect_8c.html#
>     a3f49cbb20595c1765bd0db5ff434c9c3
> 
>     Is it worth going into that detail in the docs?
> 
> 
> 
> Yes, "the user's home directory" and the "HOME" environment variable are
> distinct things.  The current docs are wrong.
> 
> The .pgpass file, located in $HOME (a.k.a. ~) on non-Microsoft Windows systems,
> can contain passwords...  In the absence of the HOME environment variable, the
> path recorded as the user's home directory in the operating system's passwd
> file will be checked.  This is not a fallback mechanism - if HOME is set, and
> the file is not present there, this directory will not be checked).  On
> Microsoft Windows... Alternatively, the password file to use ...
> 
> I"m somewhat loath to repeat that in:
> https://www.postgresql.org/docs/16/libpq-connect.html#LIBPQ-CONNECT-PASSFILE
> 
> passfile
> Specifies the name of the file used to store passwords (see Section 34.16).
> Defaults to ~/.pgpass, or %APPDATA%\postgresql\pgpass.conf on Microsoft
> Windows. (No error is reported if this file does not exist.)
> 
> So I'd suggest just removing the talk of defaults, changing it to:
> 
> "Specifies the name of the file used to store passwords.  See Section 34.16 for
> details, including the default file name and path resolution mechanics."

I have written the attached patch to add the home directory details.  I
specified in one place and referenced it to two others.  Did I miss any
places?

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  When a patient asks the doctor, "Am I going to die?", he means 
  "Am I going to die soon?"

--2KCFEcop39rxdjOr
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="home.diff"

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index afc9346757a..bfefb1289e8 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -9256,7 +9256,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
    The file <filename>.pgpass</filename> in a user's home directory can
    contain passwords to
    be used if the connection requires a password (and no password has been
-   specified otherwise). On Microsoft Windows the file is named
+   specified otherwise). On Unix systems, the directory can be specified by
+   the <envar>HOME</envar> environment variable, or if undefined, the home
+   directory of the effective user.  On Microsoft Windows the file is named
    <filename>%APPDATA%\postgresql\pgpass.conf</filename> (where
    <filename>%APPDATA%</filename> refers to the Application Data subdirectory in
    the user's profile).
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 627bb5ab5cc..188e8f0b4d0 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -194,7 +194,9 @@ OPTIONS (ADD password_required 'false');
     user can potentially use any client certificates,
     <filename>.pgpass</filename>,
     <filename>.pg_service.conf</filename> etc. in the unix home directory of the
-    system user the postgres server runs as. They can also use any trust
+    system user the postgres server runs as.   (For details on how home
+    directories are found, see <xref linkend="libpq-pgpass"/>.)  They can
+    also use any trust
     relationship granted by authentication modes like <literal>peer</literal>
     or <literal>ident</literal> authentication.
    </para>
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index b825ca96a23..e42073ed748 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1048,7 +1048,8 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1
         <para>
          Changes the current working directory to
          <replaceable>directory</replaceable>. Without argument, changes
-         to the current user's home directory.
+         to the current user's home directory.  For details on how home
+         directories are found, see <xref linkend="libpq-pgpass"/>.
         </para>
 
         <tip>

--2KCFEcop39rxdjOr--