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 <[email protected]> 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 <[email protected]> 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?"
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>
