I noticed that the reference pages for initdb and pg_ctl claim in the
Environment section that libpq variables are used, which does not seem
correct to me. I think this was accidentally copied when this blurb was
added to other pages.
While I was checking around that, I also noticed that pg_amcheck and
pg_upgrade don't have Environment sections on their reference pages, so
I added them. For pg_amcheck I copied the standard text for client
programs. pg_upgrade has its own specific list of environment variables.
Patches attached. I think the first one is a bug fix.
From 3f573c5935d46b20de7e7129cd0bf69abed1df6c Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <pe...@eisentraut.org>
Date: Mon, 13 May 2024 10:10:21 +0200
Subject: [PATCH 1/3] doc: Remove claims that initdb and pg_ctl use libpq
environment variables
Erroneously introduced by 571df93cff8.
---
doc/src/sgml/ref/initdb.sgml | 6 ------
doc/src/sgml/ref/pg_ctl-ref.sgml | 7 -------
2 files changed, 13 deletions(-)
diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml
index 6c96c0c0681..74008a9a82f 100644
--- a/doc/src/sgml/ref/initdb.sgml
+++ b/doc/src/sgml/ref/initdb.sgml
@@ -632,12 +632,6 @@ <title>Environment</title>
</varlistentry>
</variablelist>
- <para>
- This utility, like most other <productname>PostgreSQL</productname>
utilities,
- also uses the environment variables supported by
<application>libpq</application>
- (see <xref linkend="libpq-envars"/>).
- </para>
-
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/ref/pg_ctl-ref.sgml b/doc/src/sgml/ref/pg_ctl-ref.sgml
index 46906966eb9..a0287bb81d6 100644
--- a/doc/src/sgml/ref/pg_ctl-ref.sgml
+++ b/doc/src/sgml/ref/pg_ctl-ref.sgml
@@ -578,13 +578,6 @@ <title>Environment</title>
unless <envar>PGDATA</envar> is set.
</para>
- <para>
- <command>pg_ctl</command>, like most other
<productname>PostgreSQL</productname>
- utilities,
- also uses the environment variables supported by
<application>libpq</application>
- (see <xref linkend="libpq-envars"/>).
- </para>
-
<para>
For additional variables that affect the server,
see <xref linkend="app-postgres"/>.
base-commit: 3ca43dbbb67fbfb96dec8de2e268b96790555148
--
2.44.0
From 362f6ed36bebc2d1f0bdaf00f54d9212b344d98f Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <pe...@eisentraut.org>
Date: Mon, 13 May 2024 10:12:02 +0200
Subject: [PATCH 2/3] doc: Add standard Environment section to pg_amcheck ref
page
---
doc/src/sgml/ref/pg_amcheck.sgml | 18 ++++++++++++++++++
1 file changed, 18 insertions(+)
diff --git a/doc/src/sgml/ref/pg_amcheck.sgml b/doc/src/sgml/ref/pg_amcheck.sgml
index 067c806b46d..2b9634b3ac2 100644
--- a/doc/src/sgml/ref/pg_amcheck.sgml
+++ b/doc/src/sgml/ref/pg_amcheck.sgml
@@ -644,6 +644,24 @@ <title>Options</title>
</para>
</refsect1>
+ <refsect1>
+ <title>Environment</title>
+
+ <para>
+ <command>pg_amcheck</command>, like most other
<productname>PostgreSQL</productname>
+ utilities,
+ also uses the environment variables supported by
<application>libpq</application>
+ (see <xref linkend="libpq-envars"/>).
+ </para>
+
+ <para>
+ The environment variable <envar>PG_COLOR</envar> specifies whether to use
+ color in diagnostic messages. Possible values are
+ <literal>always</literal>, <literal>auto</literal> and
+ <literal>never</literal>.
+ </para>
+ </refsect1>
+
<refsect1>
<title>Notes</title>
--
2.44.0
From f276cf62d1ebb6dc4c501a5d1b397aeea6630fcb Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <pe...@eisentraut.org>
Date: Mon, 13 May 2024 10:25:16 +0200
Subject: [PATCH 3/3] doc: Add standard Environment section to pg_upgrade ref
page
---
doc/src/sgml/ref/pgupgrade.sgml | 98 +++++++++++++++++++++++++++++++++
1 file changed, 98 insertions(+)
diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index 10c842adb14..9877f2f01c6 100644
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -939,6 +939,104 @@ <title>Reverting to old cluster</title>
</refsect1>
+ <refsect1>
+ <title>Environment</title>
+
+ <para>
+ Some environment variables can be used to provide defaults for command-line
options:
+
+ <variablelist>
+ <varlistentry>
+ <term><envar>PGBINOLD</envar></term>
+
+ <listitem>
+ <para>
+ The old PostgreSQL executable directory; option
+ <option>-b</option>/<option>--old-bindir</option>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><envar>PGBINNEW</envar></term>
+
+ <listitem>
+ <para>
+ The new PostgreSQL executable directory; option
+ <option>-B</option>/<option>--new-bindir</option>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><envar>PGDATAOLD</envar></term>
+
+ <listitem>
+ <para>
+ The old database cluster configuration directory; option
+ <option>-d</option>/<option>--old-datadir</option>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><envar>PGDATANEW</envar></term>
+
+ <listitem>
+ <para>
+ The new database cluster configuration directory; option
+ <option>-D</option>/<option>--new-datadir</option>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><envar>PGPORTOLD</envar></term>
+
+ <listitem>
+ <para>
+ The old cluster port number; option
+ <option>-p</option>/<option>--old-port</option>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><envar>PGPORTNEW</envar></term>
+
+ <listitem>
+ <para>
+ The new cluster port number; option
+ <option>-P</option>/<option>--new-port</option>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><envar>PGSOCKETDIR</envar></term>
+
+ <listitem>
+ <para>
+ Directory to use for postmaster sockets during upgrade; option
+ <option>-s</option>/<option>--socketdir</option>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><envar>PGUSER</envar></term>
+
+ <listitem>
+ <para>
+ Cluster's install user name; option
+ <option>-U</option>/<option>--username</option>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
<refsect1>
<title>Notes</title>
--
2.44.0