Michael Paquier <mich...@paquier.xyz> writes:
> On Wed, May 26, 2021 at 05:40:45AM +0000, tanghy.f...@fujitsu.com wrote:
>> You're right, backtick notation doesn't work at my windows machine.
>> But I made the fix in accordance with the pg-doc as below. So maybe
>> we need a fix there, too?
>>
>> https://www.postgresql.org/docs/current/libpq-pgservice.html
>> a system-wide file at `pg_config --sysconfdir`/pg_service.conf
> Using catalog/pg_type_d.h sounds enough to me as well. While on it,
> we could adjust include/common/relpath.h in pgbuffercache.sgml? We
> tend to include the full path for things not generated.
I doubt we can drop the reference to pg_config in libpq-pgservice.html,
because otherwise we'd have to just say "etc/" which is not very
definite. However, we should avoid the use of backticks since that's
a platform-specific thing.
I set out to rewrite that, but the more I looked at that section the
more help it seemed to need. I thought the para was quite confusing
about which environment variables affect what; and I also noticed
that nowhere do we explain how service-file settings interact with
other settings. (If that had been better specified to begin with,
maybe I'd not have made the mistake fixed in ea8013854.)
So I ended up with the attached --- what do you think?
Also, looking at this, I note that "~/.pg_service.conf" is still a
platform-ism. We could make that slightly better by writing
"$HOME/.pg_service.conf", but is that good enough?
regards, tom lane
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 875950b83c..ca231f43c4 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -8091,26 +8091,30 @@ 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 located
+ at <filename>~/.pg_service.conf</filename>; this can be overridden 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:
@@ -8121,9 +8125,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>
