On Mon, Jan 15, 2024 at 4:35 AM Aleksander Alekseev <
aleksan...@timescale.com> wrote:
> PFA the patch. It's short but I think it mitigates the problem.
>
>
I took a look at where these options are discussed in the documentation and
now feel that we should make these options clear more broadly (config and
libpq, plus pointing to --name from -c in a couple of places). It doesn't
add much verbosity and, frankly, if I was to pick one "--name=value" would
win and so I'd rather document it, leaving -c alone for historical reasons.
I've attached a replacement patch with the additional changes.
David J.
From adc6c807d2bc0d73271b47e4d1908e5c069e5b24 Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <david.g.johns...@gmail.com>
Date: Fri, 2 Feb 2024 14:16:24 -0700
Subject: [PATCH] v4 configs review
---
doc/src/sgml/config.sgml | 11 ++++++-----
doc/src/sgml/libpq.sgml | 7 ++++---
doc/src/sgml/ref/postgres-ref.sgml | 8 +++++---
src/backend/main/main.c | 4 ++--
src/backend/utils/misc/guc.c | 2 +-
5 files changed, 18 insertions(+), 14 deletions(-)
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 61038472c5..1eb58c0793 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -333,9 +333,10 @@ UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter
<para>
During server startup, parameter settings can be
passed to the <command>postgres</command> command via the
- <option>-c</option> command-line parameter. For example,
+ <option>-c name=value</option> command-line parameter, or its equivalent
+ <option>--name=value</option> variation. For example,
<programlisting>
-postgres -c log_connections=yes -c log_destination='syslog'
+postgres -c log_connections=yes --log_destination='syslog'
</programlisting>
Settings provided in this way override those set via
<filename>postgresql.conf</filename> or <command>ALTER SYSTEM</command>,
@@ -352,10 +353,10 @@ postgres -c log_connections=yes -c log_destination='syslog'
of the session, but do not affect other sessions.
For historical reasons, the format of <envar>PGOPTIONS</envar> is
similar to that used when launching the <command>postgres</command>
- command; specifically, the <option>-c</option> flag must be specified.
- For example,
+ command; specifically, the <option>-c </option>, or prepended
+ <literal>--</literal>, before the name must be specified. For example,
<programlisting>
-env PGOPTIONS="-c geqo=off -c statement_timeout=5min" psql
+env PGOPTIONS="-c geqo=off --statement_timeout=5min" psql
</programlisting>
</para>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index d0d5aefadc..89f7aa590d 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1374,9 +1374,10 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
<listitem>
<para>
Specifies command-line options to send to the server at connection
- start. For example, setting this to <literal>-c geqo=off</literal> sets the
- session's value of the <varname>geqo</varname> parameter to
- <literal>off</literal>. Spaces within this string are considered to
+ start. For example, setting this to <literal>-c geqo=off</literal>
+ or <literal>--geoq=off</literal> sets the session's value of the
+ <varname>geqo</varname> parameter to <literal>off</literal>.
+ Spaces within this string are considered to
separate command-line arguments, unless escaped with a backslash
(<literal>\</literal>); write <literal>\\</literal> to represent a literal
backslash. For a detailed discussion of the available
diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml
index b13a16a117..cbf06d86cb 100644
--- a/doc/src/sgml/ref/postgres-ref.sgml
+++ b/doc/src/sgml/ref/postgres-ref.sgml
@@ -123,7 +123,8 @@ PostgreSQL documentation
described in <xref linkend="runtime-config"/>. Most of the
other command line options are in fact short forms of such a
parameter assignment. <option>-c</option> can appear multiple times
- to set multiple parameters.
+ to set multiple parameters. See the <option>--name</option>
+ option below for an alternate syntax.
</para>
</listitem>
</varlistentry>
@@ -342,8 +343,9 @@ PostgreSQL documentation
<term><option>--<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
<listitem>
<para>
- Sets a named run-time parameter; a shorter form of
- <option>-c</option>.
+ Sets the named run-time parameter; a shorter form of
+ <option>-c</option>. See <xref linkend="runtime-config"/>
+ for a listing of parameters.
</para>
</listitem>
</varlistentry>
diff --git a/src/backend/main/main.c b/src/backend/main/main.c
index 51ffb8e773..f1b88faa5c 100644
--- a/src/backend/main/main.c
+++ b/src/backend/main/main.c
@@ -324,7 +324,7 @@ help(const char *progname)
printf(_("Usage:\n %s [OPTION]...\n\n"), progname);
printf(_("Options:\n"));
printf(_(" -B NBUFFERS number of shared buffers\n"));
- printf(_(" -c NAME=VALUE set run-time parameter\n"));
+ printf(_(" -c NAME=VALUE set run-time parameter (see also --NAME)\n"));
printf(_(" -C NAME print value of run-time parameter, then exit\n"));
printf(_(" -d 1-5 debugging level\n"));
printf(_(" -D DATADIR database directory\n"));
@@ -341,7 +341,7 @@ help(const char *progname)
printf(_(" -s show statistics after each query\n"));
printf(_(" -S WORK-MEM set amount of memory for sorts (in kB)\n"));
printf(_(" -V, --version output version information, then exit\n"));
- printf(_(" --NAME=VALUE set run-time parameter\n"));
+ printf(_(" --NAME=VALUE set run-time parameter, a shorter form of -c\n"));
printf(_(" --describe-config describe configuration parameters, then exit\n"));
printf(_(" -?, --help show this help, then exit\n"));
diff --git a/src/backend/utils/misc/guc.c b/src/backend/utils/misc/guc.c
index 8f65ef3d89..297eb1af4f 100644
--- a/src/backend/utils/misc/guc.c
+++ b/src/backend/utils/misc/guc.c
@@ -1822,7 +1822,7 @@ SelectConfigFiles(const char *userDoption, const char *progname)
else
{
write_stderr("%s does not know where to find the server configuration file.\n"
- "You must specify the --config-file or -D invocation "
+ "You must specify the --config-file (or equivalent -c) or -D invocation "
"option or set the PGDATA environment variable.\n",
progname);
return false;
--
2.34.1
