From 82a47982f37077a9bfe67c0e9cc87b4f9b16e34b Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Tue, 11 Sep 2007 00:06:42 +0000 Subject: Arrange for SET LOCAL's effects to persist until the end of the current top transaction, unless rolled back or overridden by a SET clause for the same variable attached to a surrounding function call. Per discussion, these seem the best semantics. Note that this is an INCOMPATIBLE CHANGE: in 8.0 through 8.2, SET LOCAL's effects disappeared at subtransaction commit (leading to behavior that made little sense at the SQL level). I took advantage of the opportunity to rewrite and simplify the GUC variable save/restore logic a little bit. The old idea of a "tentative" value is gone; it was a hangover from before we had a stack. Also, we no longer need a stack entry for every nesting level, but only for those in which a variable's value actually changed. --- doc/src/sgml/ref/create_function.sgml | 10 +++--- doc/src/sgml/ref/prepare_transaction.sgml | 5 +-- doc/src/sgml/ref/reset.sgml | 31 ++++++++++++----- doc/src/sgml/ref/set.sgml | 57 +++++++++++++++++++++++++------ doc/src/sgml/ref/show.sgml | 10 ++++-- 5 files changed, 83 insertions(+), 30 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml index b0cfe84db1c..8c542982d52 100644 --- a/doc/src/sgml/ref/create_function.sgml +++ b/doc/src/sgml/ref/create_function.sgml @@ -1,5 +1,5 @@ @@ -475,11 +475,11 @@ CREATE FUNCTION foo(int, out text) ... - If any SET clauses are attached to a function, then + If a SET clause is attached to a function, then the effects of a SET LOCAL command executed inside the - function are restricted to the function: the configuration parameter's - value is restored at function exit. This is true even for parameters - not mentioned in the SET clause(s). However, an ordinary + function for the same variable are restricted to the function: the + configuration parameter's prior value is still restored at function exit. + However, an ordinary SET command (without LOCAL) overrides the SET clause, much as it would do for a previous SET LOCAL command: the effects of such a command will persist after diff --git a/doc/src/sgml/ref/prepare_transaction.sgml b/doc/src/sgml/ref/prepare_transaction.sgml index 0c8293f0ec5..5874b799303 100644 --- a/doc/src/sgml/ref/prepare_transaction.sgml +++ b/doc/src/sgml/ref/prepare_transaction.sgml @@ -1,5 +1,5 @@ @@ -94,7 +94,8 @@ PREPARE TRANSACTION transaction_id - If the transaction modified any run-time parameters with SET, + If the transaction modified any run-time parameters with SET + (without the LOCAL option), those effects persist after PREPARE TRANSACTION, and will not be affected by any later COMMIT PREPARED or ROLLBACK PREPARED. Thus, in this one respect diff --git a/doc/src/sgml/ref/reset.sgml b/doc/src/sgml/ref/reset.sgml index 355de891287..c90843ff583 100644 --- a/doc/src/sgml/ref/reset.sgml +++ b/doc/src/sgml/ref/reset.sgml @@ -1,5 +1,5 @@ @@ -44,13 +44,16 @@ SET configuration_parameter TO DEFA have had, if no SET had ever been issued for it in the current session. The actual source of this value might be a compiled-in default, the configuration file, command-line options, - or per-database or per-user default settings. See for details. + or per-database or per-user default settings. This is subtly different + from defining it as the value that the parameter had at session + start, because if the value came from the configuration file, it + will be reset to whatever is specified by the configuration file now. + See for details. - See the SET reference page for details on the - transaction behavior of RESET. + The transactional behavior of RESET is the same as + SET: its effects will be undone by transaction rollback. @@ -62,8 +65,9 @@ SET configuration_parameter TO DEFA configuration_parameter - The name of a run-time parameter. See for a list. + Name of a settable run-time parameter. Available parameters are + documented in and on the + reference page. @@ -83,9 +87,9 @@ SET configuration_parameter TO DEFA Examples - Set the geqo configuration variable to its default value: + Set the timezone configuration variable to its default value: -RESET geqo; +RESET timezone; @@ -97,4 +101,13 @@ RESET geqo; RESET is a PostgreSQL extension. + + + See Also + + + + + + diff --git a/doc/src/sgml/ref/set.sgml b/doc/src/sgml/ref/set.sgml index 76e8decf5c5..26ee8594b44 100644 --- a/doc/src/sgml/ref/set.sgml +++ b/doc/src/sgml/ref/set.sgml @@ -1,5 +1,5 @@ @@ -40,13 +40,10 @@ SET [ SESSION | LOCAL ] TIME ZONE { timezone - If SET or SET SESSION is issued - within a transaction that is later aborted, the effects of the + If SET (or equivalently SET SESSION) + is issued within a transaction that is later aborted, the effects of the SET command disappear when the transaction is rolled - back. (This behavior represents a change from - PostgreSQL versions prior to 7.3, where - the effects of SET would not roll back after a later - error.) Once the surrounding transaction is committed, the effects + back. Once the surrounding transaction is committed, the effects will persist until the end of the session, unless overridden by another SET. @@ -59,6 +56,36 @@ SET [ SESSION | LOCAL ] TIME ZONE { timezoneSET value will take effect. + + + The effects of SET or SET LOCAL are + also canceled by rolling back to a savepoint that is earlier than the + command. + + + + If SET LOCAL is used within a function that has a + SET option for the same variable (see + ), + the effects of the SET LOCAL command disappear at + function exit; that is, the value in effect when the function was called is + restored anyway. This allows SET LOCAL to be used for + dynamic or repeated changes of a parameter within a function, while still + having the convenience of using the SET option to save and + restore the caller's value. However, a regular SET command + overrides any surrounding function's SET option; its effects + will persist unless rolled back. + + + + + In PostgreSQL versions 8.0 through 8.2, + the effects of a SET LOCAL would be canceled by + releasing an earlier savepoint, or by successful exit from a + PL/pgSQL exception block. This behavior + has been changed because it was deemed unintuitive. + + @@ -106,8 +133,11 @@ SET [ SESSION | LOCAL ] TIME ZONE { timezone New value of parameter. Values can be specified as string constants, identifiers, numbers, or comma-separated lists of - these. DEFAULT can be used to specify - resetting the parameter to its default value. + these, as appropriate for the particular parameter. + DEFAULT can be written to specify + resetting the parameter to its default value (that is, whatever + value it would have had if no SET had been executed + in the current session). @@ -200,7 +230,9 @@ SELECT setseed(value); DEFAULT - Set the time zone to your local time zone (the one that + Set the time zone to your local time zone (that is, the + server's default value of timezone; if this + has not been explicitly set anywhere, it will be the zone that the server's operating system defaults to). @@ -221,7 +253,10 @@ SELECT setseed(value); The function set_config provides equivalent - functionality. See . + functionality; see . + Also, it is possible to UPDATE the + pg_settings + system view to perform the equivalent of SET. diff --git a/doc/src/sgml/ref/show.sgml b/doc/src/sgml/ref/show.sgml index f43a0a50bd8..ab64f859428 100644 --- a/doc/src/sgml/ref/show.sgml +++ b/doc/src/sgml/ref/show.sgml @@ -1,5 +1,5 @@ @@ -36,7 +36,7 @@ SHOW ALL the PGOPTIONS environmental variable (when using libpq or a libpq-based application), or through command-line flags when starting the - postgres. See postgres server. See for details. @@ -130,7 +130,11 @@ SHOW ALL The function current_setting produces - equivalent output. See . + equivalent output; see . + Also, the + pg_settings + system view produces the same information. + -- cgit v1.2.3