From: Bruce Momjian <bruce@momjian.us>
To: David G. Johnston <david.g.johnston@gmail.com>
Cc: marc@msys.ch
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: Documentation of .pgpass for Unix is incomplete
Date: Wed, 16 Oct 2024 16:54:43 -0400
Message-ID: <ZxAoE-V74KRR26Jb@momjian.us> (raw)
In-Reply-To: <CAKFQuwZ-T-zsVM7gApS9-XU9vGxC7Oa-UyRQPVcJFagNU=AjOw@mail.gmail.com>
References: <172311029184.915368.14898011794686876553@wrigleys.postgresql.org>
<ZsPd_1ahHdqcQjgA@momjian.us>
<CAKFQuwZ-T-zsVM7gApS9-XU9vGxC7Oa-UyRQPVcJFagNU=AjOw@mail.gmail.com>
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?"
Attachments:
[text/x-diff] home.diff (2.3K, ../ZxAoE-V74KRR26Jb@momjian.us/2-home.diff)
download | inline diff:diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgmlindex 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.sgmlindex 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.sgmlindex 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>
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: bruce@momjian.us, david.g.johnston@gmail.com, marc@msys.ch, pgsql-docs@lists.postgresql.org
Subject: Re: Documentation of .pgpass for Unix is incomplete
In-Reply-To: <ZxAoE-V74KRR26Jb@momjian.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox