Re: Documentation of .pgpass for Unix is incomplete

On Mon, Aug 19, 2024 at 5:06 PM Bruce Momjian <bruce(at)momjian(dot)us> wrote:

> On Thu, Aug 8, 2024 at 09:44:51AM +0000, PG Doc comments form wrote:
> > The following documentation comment has been logged on the website:
> >
> > Page: https://www.postgresql.org/docs/16/libpq-pgpass.html
> > Description:
> >
> > The documentation of the .pgpass password file is incomplete in the Unix
> > case (https://www.postgresql.org/docs/16/libpq-pgpass.html)
> >
> > It does not mention how the .pgpass File is actually found. One would
> > assume it uses the getpwent() function to find the current users
> > homedirectory and locate the .pgpass file there, but this is not the
> case.
> > It only looks at the HOME environment variable.
> >
> > If you change the user using setuid() and do not change HOME as well, the
> > file not be found. Or assume you start a DB client as root by using su
> to
> > change the user id, things will not work:
> >
> > # /bin/su -c "startx -- " - xpos
> >
> > This starts X11 and changes to the user xpos, but it does only change the
> > user id, not $HOME.
>
> 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."

David J.