From 1d55400adba93381d8a08249c95e4e16fb9a5945 Mon Sep 17 00:00:00 2001 From: "David G. Johnston" Date: Fri, 2 Feb 2024 14:16:24 -0700 Subject: [PATCH v3] Clarify error message about specifying --config-file When running without any arguments 'postgres' suggests to specify either --config-file or -D option. This is somewhat confusing since --config-file is a GUC and thus not directly described in the --help message. This patch reduces the amount of confusion. Besides affecting the error message the patch clarifies corresponding articles in the documentation. David Johnston, Aleksander Alekseev. Reviewed by Nathan Bossart and Peter Eisentraut. Reported by Alexey Palazhchenko. Discussion: https://postgr.es/m/CAJ7c6TMkuLiLfrA%2BEFCPYfhXoMKRxxssB5c86%2Bibxfaz6%2B%3DSdg%40mail.gmail.com --- 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 e93208b2e6..3777cfa52a 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -334,9 +334,10 @@ UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter During server startup, parameter settings can be passed to the postgres command via the - command-line parameter. For example, + command-line parameter, or its equivalent + variation. For example, -postgres -c log_connections=yes -c log_destination='syslog' +postgres -c log_connections=yes --log-destination='syslog' Settings provided in this way override those set via postgresql.conf or ALTER SYSTEM, @@ -353,10 +354,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 PGOPTIONS is similar to that used when launching the postgres - command; specifically, the flag must be specified. - For example, + command; specifically, the , or prepended + --, before the name must be specified. For example, -env PGOPTIONS="-c geqo=off -c statement_timeout=5min" psql +env PGOPTIONS="-c geqo=off --statement-timeout=5min" psql diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 1d32c226d8..a445e4f280 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1421,9 +1421,10 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname Specifies command-line options to send to the server at connection - start. For example, setting this to -c geqo=off sets the - session's value of the geqo parameter to - off. Spaces within this string are considered to + start. For example, setting this to -c geqo=off + or --geoq=off sets the session's value of the + geqo parameter to off. + Spaces within this string are considered to separate command-line arguments, unless escaped with a backslash (\); write \\ 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 . Most of the other command line options are in fact short forms of such a parameter assignment. can appear multiple times - to set multiple parameters. + to set multiple parameters. See the + option below for an alternate syntax. @@ -342,8 +343,9 @@ PostgreSQL documentation - Sets a named run-time parameter; a shorter form of - . + Sets the named run-time parameter; a shorter form of + . See + for a listing of parameters. diff --git a/src/backend/main/main.c b/src/backend/main/main.c index bfd0c5ed65..22ffcb1516 100644 --- a/src/backend/main/main.c +++ b/src/backend/main/main.c @@ -323,7 +323,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")); @@ -340,7 +340,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 3fb6803998..e5ae0784d2 100644 --- a/src/backend/utils/misc/guc.c +++ b/src/backend/utils/misc/guc.c @@ -1828,7 +1828,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.45.0