From 9cbaf7217747d6b5c88ba9b500a37b8372f185c9 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Fri, 25 Apr 2003 19:45:10 +0000 Subject: In the continuing saga of FE/BE protocol revisions, add reporting of initial values and runtime changes in selected parameters. This gets rid of the need for an initial 'select pg_client_encoding()' query in libpq, bringing us back to one message transmitted in each direction for a standard connection startup. To allow server version to be sent using the same GUC mechanism that handles other parameters, invent the concept of a never-settable GUC parameter: you can 'show server_version' but it's not settable by any GUC input source. Create 'lc_collate' and 'lc_ctype' never-settable parameters so that people can find out these settings without need for pg_controldata. (These side ideas were all discussed some time ago in pgsql-hackers, but not yet implemented.) --- doc/src/sgml/protocol.sgml | 17 +++++++---- doc/src/sgml/ref/set.sgml | 30 +++++++------------ doc/src/sgml/ref/show.sgml | 73 +++++++++++++++++++++++++++++++++++++++++----- 3 files changed, 89 insertions(+), 31 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 7b5f9593a98..70c255f00ce 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1,4 +1,4 @@ - + Frontend/Backend Protocol @@ -328,7 +328,7 @@ is being started, and the frontend is just an interested bystander. It is still possible for the startup attempt to fail (ErrorResponse), but in the normal case the backend will send - BackendKeyData, some ParameterStatus messages, and finally ReadyForQuery. + some ParameterStatus messages, BackendKeyData, and finally ReadyForQuery. @@ -900,9 +900,9 @@ At present there is a hard-wired set of parameters for which ParameterStatus will be generated: they are - version (backend version, - a pseudo-parameter that cannot change after startup); - database_encoding (also not presently changeable after start); + server_version (a pseudo-parameter that cannot change after + startup); + server_encoding (also not presently changeable after start); client_encoding, and DateStyle. This set might change in the future, or even become configurable. @@ -3881,6 +3881,13 @@ The CopyInResponse and CopyOutResponse messages carry a field indicating whether the COPY operation is text or binary. + +The backend sends ParameterStatus ('S') messages during connection +startup for all parameters it considers interesting to the client library. +Subsequently, a ParameterStatus message is sent whenever the active value +changes for any of these parameters. + + The CursorResponse ('P') message is no longer generated by the backend. diff --git a/doc/src/sgml/ref/set.sgml b/doc/src/sgml/ref/set.sgml index 23b77dff5c5..75dc366c3f9 100644 --- a/doc/src/sgml/ref/set.sgml +++ b/doc/src/sgml/ref/set.sgml @@ -1,5 +1,5 @@ @@ -52,7 +52,7 @@ SET [ SESSION | LOCAL ] TIME ZONE { timezonevariable - A settable run-time parameter. + Name of a settable run-time parameter. @@ -79,8 +79,9 @@ SET [ SESSION | LOCAL ] TIME ZONE { timezone The SET command changes run-time configuration - parameters. Many of the run-time parameters listed in the - can be changed on-the-fly with SET. + parameters. Many of the run-time parameters listed in + can be changed on-the-fly with + SET. (But some require superuser privileges to change, and others cannot be changed after server or session start.) Note that SET only affects the value used by the current @@ -123,7 +124,7 @@ SET [ SESSION | LOCAL ] TIME ZONE { timezone Choose the date/time representation style. Two separate - settings are involved: the default date/time output and the + settings are involved: the default date/time output format and the interpretation of ambiguous input. @@ -147,7 +148,7 @@ SET [ SESSION | LOCAL ] TIME ZONE { timezone Use Oracle/Ingres-style dates and times. Note that this style has nothing to do with SQL (which mandates ISO 8601 - style), the naming of this option is a historical accident. + style); the naming of this option is a historical accident. @@ -283,17 +284,6 @@ SELECT setseed(value); - - SERVER_ENCODING - - - Shows the server-side multibyte encoding. (At present, this - parameter can be shown but not set, because the encoding is - determined at initdb time.) - - - - TIME ZONE TIMEZONE @@ -410,7 +400,7 @@ SELECT setseed(value); - ERROR: 'name is not a + ERROR: 'name' is not a valid option name @@ -447,7 +437,7 @@ SELECT setseed(value); Notes - The function set_config provides the equivalent + The function set_config provides equivalent capability. See . @@ -517,6 +507,8 @@ SELECT CURRENT_TIMESTAMP AS today; See Also + , + , , , diff --git a/doc/src/sgml/ref/show.sgml b/doc/src/sgml/ref/show.sgml index 832c4392cbf..0fec5fcce55 100644 --- a/doc/src/sgml/ref/show.sgml +++ b/doc/src/sgml/ref/show.sgml @@ -1,5 +1,5 @@ @@ -52,12 +52,13 @@ SHOW ALL Description - SHOW will display the current setting of a - run-time parameter. These variables can be set using the + SHOW will display the current setting of + run-time parameters. These variables can be set using the SET statement, by editing the - postgresql.conf, through the - PGOPTIONS environmental variable, or through a - command-line flag when starting the + postgresql.conf configuration file, through the + PGOPTIONS environmental variable (when using libpq + or a libpq-based application), or through + command-line flags when starting the postmaster. @@ -66,6 +67,64 @@ SHOW ALL does not start a new transaction block. See the autocommit section in for details. + + + Available parameters are documented in + and on the + reference page. + In addition, there are a few parameters that can be shown but not set: + + + + + SERVER_VERSION + + + Shows the server's version number. + + + + + + SERVER_ENCODING + + + Shows the server-side multibyte encoding. At present, this + parameter can be shown but not set, because the encoding is + determined at database creation time. + + + + + + LC_COLLATE + + + Shows the database's locale setting for collation (text ordering). + At present, this parameter can be shown but not set, because the + setting is determined at initdb time. + + + + + + LC_CTYPE + + + Shows the database's locale setting for character set considerations. + At present, this parameter can be shown but not set, because the + setting is determined at initdb time. + + + + + + + + + Use to set the value + of settable parameters. + @@ -79,7 +138,7 @@ SHOW ALL Message returned if name does - not stand for an existing parameter. + not stand for a known parameter. -- cgit v1.2.3