Skip to content

Commit 5df99f6

Browse files
tglsfdctglsfdc
committed
Improve FILES section of psql reference page.
Primarily, explain where to find the system-wide psqlrc file, per recent gripe from John Sutton. Do some general wordsmithing and improve the markup, too. Also adjust psqlrc.sample so its comments about file location are somewhat trustworthy. (Not sure why we bother with this file when it's empty, but whatever.) Back-patch to 9.2 where the startup file naming scheme was last changed.
1 parent 061b079 commit 5df99f6

File tree

2 files changed

+41
-29
lines changed

2 files changed

+41
-29
lines changed

‎doc/src/sgml/ref/psql-ref.sgml

Lines changed: 37 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -3513,55 +3513,66 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
35133513
<refsect1>
35143514
<title>Files</title>
35153515

3516-
<itemizedlist>
3516+
<variablelist>
3517+
<varlistentry>
3518+
<term><filename>psqlrc</filename> and <filename>~/.psqlrc</filename></term>
35173519
<listitem>
35183520
<para>
3519-
Unless it is passed an <option>-X</option>
3520-
or <option>-c</option> option,
3521-
<application>psql</application> attempts to
3522-
read and execute commands from the system-wide
3523-
<filename>psqlrc</filename> file and the user's
3524-
<filename>~/.psqlrc</filename> file before starting up.
3525-
(On Windows, the user's startup file is named
3526-
<filename>%APPDATA%\postgresql\psqlrc.conf</filename>.)
3527-
See <filename><replaceable>PREFIX</>/share/psqlrc.sample</>
3528-
for information on setting up the system-wide file. It could be used
3529-
to set up the client or the server to taste (using the <command>\set
3530-
</command> and <command>SET</command> commands).
3521+
Unless it is passed an <option>-X</option> or <option>-c</option> option,
3522+
<application>psql</application> attempts to read and execute commands
3523+
from the system-wide startup file (<filename>psqlrc</filename>) and then
3524+
the user's personal startup file (<filename>~/.psqlrc</filename>), after
3525+
connecting to the database but before accepting normal commands.
3526+
These files can be used to set up the client and/or the server to taste,
3527+
typically with <command>\set</command> and <command>SET</command>
3528+
commands.
35313529
</para>
35323530
<para>
3533-
The location of the user's <filename>~/.psqlrc</filename> file can
3534-
also be set explicitly via the <envar>PSQLRC</envar> environment
3535-
setting.
3531+
The system-wide startup file is named <filename>psqlrc</filename> and is
3532+
sought in the installation's <quote>system configuration</> directory,
3533+
which is most reliably identified by running <literal>pg_config
3534+
--sysconfdir</>. By default this directory will be <filename>../etc/</>
3535+
relative to the directory containing
3536+
the <productname>PostgreSQL</productname> executables. The name of this
3537+
directory can be set explicitly via the <envar>PGSYSCONFDIR</envar>
3538+
environment variable.
3539+
</para>
3540+
<para>
3541+
The user's personal startup file is named <filename>.psqlrc</filename>
3542+
and is sought in the invoking user's home directory. On Windows, which
3543+
lacks such a concept, the personal startup file is named
3544+
<filename>%APPDATA%\postgresql\psqlrc.conf</filename>.
3545+
The location of the user's startup file can be set explicitly via
3546+
the <envar>PSQLRC</envar> environment variable.
35363547
</para>
3537-
</listitem>
3538-
3539-
<listitem>
35403548
<para>
3541-
Both the system-wide <filename>psqlrc</filename> file and the user's
3542-
<filename>~/.psqlrc</filename> file can be made <application>psql</application>-version-specific
3549+
Both the system-wide startup file and the user's personal startup file
3550+
can be made <application>psql</application>-version-specific
35433551
by appending a dash and the <productname>PostgreSQL</productname>
3544-
major or minor <application>psql</application> release number,
3552+
major or minor release number to the file name,
35453553
for example <filename>~/.psqlrc-9.2</filename> or
35463554
<filename>~/.psqlrc-9.2.5</filename>. The most specific
35473555
version-matching file will be read in preference to a
35483556
non-version-specific file.
35493557
</para>
35503558
</listitem>
3559+
</varlistentry>
35513560

3561+
<varlistentry>
3562+
<term><filename>.psql_history</filename></term>
35523563
<listitem>
35533564
<para>
35543565
The command-line history is stored in the file
35553566
<filename>~/.psql_history</filename>, or
35563567
<filename>%APPDATA%\postgresql\psql_history</filename> on Windows.
35573568
</para>
35583569
<para>
3559-
The location of the history file can
3560-
also be set explicitly via the <envar>PSQL_HISTORY</envar> environment
3561-
setting.
3570+
The location of the history file can be set explicitly via
3571+
the <envar>PSQL_HISTORY</envar> environment variable.
35623572
</para>
35633573
</listitem>
3564-
</itemizedlist>
3574+
</varlistentry>
3575+
</variablelist>
35653576
</refsect1>
35663577

35673578

‎src/bin/psql/psqlrc.sample

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
--
2-
-- psql configuration file
2+
-- system-wide psql configuration file
33
--
44
-- This file is read before the .psqlrc file in the user's home directory.
55
--
6-
-- Copy this to your sysconf directory (typically /usr/local/pgsql/etc) and
7-
-- rename it psqlrc.
6+
-- Copy this to your installation's sysconf directory and rename it psqlrc.
7+
-- The sysconf directory can be identified via "pg_config --sysconfdir".
8+
--

0 commit comments

Comments
 (0)