mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Doc: clarify location of libpq's default service file on Windows.

Browse Source 
The documentation didn't specify the name of the per-user service file
on Windows, and extrapolating from the pattern used for other config
files gave the wrong answer.  The fact that it isn't consistent with the
others sure seems like a bug, but it's far too late to change that now;
we'd just penalize people who worked it out in the past.  So, simply
document the true state of affairs.

In passing, fix some gratuitous differences between the discussions
of the service file and the password file.

Julien Rouhaud, per question from Dominique Devienne.

Backpatch to all supported branches.  I (tgl) also chose to back-patch
the part of commit ba356a397 that touched libpq.sgml's description of
the service file --- in hindsight, I'm not sure why I didn't do so at
the time, as it includes some fairly essential information.

Discussion: https://postgr.es/m/CAFCRh-_mdLrh8eYVzhRzu4c8bAFEBn=rwoHOmFJcQOTsCy5nig@mail.gmail.com
This commit is contained in:
Tom Lane 2022-05-19 18:36:07 -04:00
parent 5fd0cccc11
commit 227c180efe
1 changed files with 40 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
doc/src/sgml/libpq.sgml
View File

@ -7103,9 +7103,11 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGSERVICEFILE</envar></primary>
</indexterm>
<envar>PGSERVICEFILE</envar> specifies the name of the per-user
connection service file. If not set, it defaults
to <filename>~/.pg_service.conf</filename>
connection service file
(see <xref linkend="libpq-pgservice"/>).
Defaults to <filename>~/.pg_service.conf</filename>, or
<filename>%APPDATA%\postgresql\.pg_service.conf</filename> on
Microsoft Windows.
</para>
</listitem>
@ -7389,7 +7391,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<filename>%APPDATA%\postgresql\pgpass.conf</filename> (where
<filename>%APPDATA%</filename> refers to the Application Data subdirectory in
the user's profile).
Alternatively, a password file can be specified
Alternatively, the password file to use can be specified
using the connection parameter <xref linkend="libpq-connect-passfile"/>
or the environment variable <envar>PGPASSFILE</envar>.
</para>
@ -7448,26 +7450,34 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<para>
The connection service file allows libpq connection parameters to be
associated with a single service name. That service name can then be
specified by a libpq connection, and the associated settings will be
specified in a libpq connection string, and the associated settings will be
used. This allows connection parameters to be modified without requiring
a recompile of the libpq application. The service name can also be
a recompile of the libpq-using application. The service name can also be
specified using the <envar>PGSERVICE</envar> environment variable.
</para>
<para>
The connection service file can be a per-user service file
at <filename>~/.pg_service.conf</filename> or the location
specified by the environment variable <envar>PGSERVICEFILE</envar>,
or it can be a system-wide file
at <filename>`pg_config --sysconfdir`/pg_service.conf</filename> or in the directory
specified by the environment variable
<envar>PGSYSCONFDIR</envar>. If service definitions with the same
name exist in the user and the system file, the user file takes
precedence.
Service names can be defined in either a per-user service file or a
system-wide file. If the same service name exists in both the user
and the system file, the user file takes precedence.
By default, the per-user service file is named
<filename>~/.pg_service.conf</filename>.
On Microsoft Windows, it is named
<filename>%APPDATA%\postgresql\.pg_service.conf</filename> (where
<filename>%APPDATA%</filename> refers to the Application Data subdirectory
in the user's profile). A different file name can be specified by
setting the environment variable <envar>PGSERVICEFILE</envar>.
The system-wide file is named <filename>pg_service.conf</filename>.
By default it is sought in the <filename>etc</filename> directory
of the <productname>PostgreSQL</productname> installation
(use <literal>pg_config --sysconfdir</literal> to identify this
directory precisely). Another directory, but not a different file
name, can be specified by setting the environment variable
<envar>PGSYSCONFDIR</envar>.
</para>
<para>
The file uses an <quote>INI file</quote> format where the section
Either service file uses an <quote>INI file</quote> format where the section
name is the service name and the parameters are connection
parameters; see <xref linkend="libpq-paramkeywords"/> for a list. For
example:
@ -7478,9 +7488,22 @@ host=somehost
port=5433
user=admin
</programlisting>
An example file is provided at
An example file is provided in
the <productname>PostgreSQL</productname> installation at
<filename>share/pg_service.conf.sample</filename>.
</para>
<para>
Connection parameters obtained from a service file are combined with
parameters obtained from other sources. A service file setting
overrides the corresponding environment variable, and in turn can be
overridden by a value given directly in the connection string.
For example, using the above service file, a connection string
<literal>service=mydb port=5434</literal> will use
host <literal>somehost</literal>, port <literal>5434</literal>,
user <literal>admin</literal>, and other parameters as set by
environment variables or built-in defaults.
</para>
</sect1>