diff options
| -rw-r--r-- | doc/src/sgml/libpq.sgml | 57 |
1 files changed, 40 insertions, 17 deletions
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 4542ea6b3d4..861359b3ff7 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -7454,9 +7454,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> @@ -7716,11 +7718,11 @@ 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 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). - 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> @@ -7779,26 +7781,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: @@ -7809,9 +7819,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> |