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.

Author: tglsfdc

doc/src/sgml/ref/create_function.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.77 2007/09/03 18:46:29 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.78 2007/09/11 00:06:41 tgl Exp $
 -->
 
 <refentry id="SQL-CREATEFUNCTION">
@@ -475,11 +475,11 @@ CREATE FUNCTION foo(int, out text) ...
    </para>
 
    <para>
-    If any <literal>SET</> clauses are attached to a function, then
+    If a <literal>SET</> clause is attached to a function, then
     the effects of a <command>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 <literal>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
     <command>SET</> command (without <literal>LOCAL</>) overrides the
     <literal>SET</> clause, much as it would do for a previous <command>SET
     LOCAL</> command: the effects of such a command will persist after

doc/src/sgml/ref/prepare_transaction.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.5 2006/09/16 00:30:19 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.6 2007/09/11 00:06:41 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -94,7 +94,8 @@ PREPARE TRANSACTION <replaceable class="PARAMETER">transaction_id</replaceable>
   </para>
 
   <para>
-   If the transaction modified any run-time parameters with <command>SET</>,
+   If the transaction modified any run-time parameters with <command>SET</>
+   (without the <literal>LOCAL</> option),
    those effects persist after <command>PREPARE TRANSACTION</>, and will not
    be affected by any later <command>COMMIT PREPARED</command> or 
    <command>ROLLBACK PREPARED</command>.  Thus, in this one respect

doc/src/sgml/ref/reset.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/reset.sgml,v 1.35 2007/04/26 16:13:09 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/reset.sgml,v 1.36 2007/09/11 00:06:41 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -44,13 +44,16 @@ SET <replaceable class="parameter">configuration_parameter</replaceable> TO DEFA
    have had, if no <command>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 <xref
-   linkend="runtime-config"> for details.
+   or per-database or per-user default settings.  This is subtly different
+   from defining it as <quote>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 <xref linkend="runtime-config"> for details.
   </para>
 
   <para>
-   See the <command>SET</> reference page for details on the
-   transaction behavior of <command>RESET</>.
+   The transactional behavior of <command>RESET</> is the same as
+   <command>SET</>: its effects will be undone by transaction rollback.
   </para>
  </refsect1>
 
@@ -62,8 +65,9 @@ SET <replaceable class="parameter">configuration_parameter</replaceable> TO DEFA
     <term><replaceable class="PARAMETER">configuration_parameter</replaceable></term>
     <listitem>
      <para>
-      The name of a run-time parameter. See <xref linkend="sql-set"
-      endterm="sql-set-title"> for a list.
+      Name of a settable run-time parameter.  Available parameters are
+      documented in <xref linkend="runtime-config"> and on the
+      <xref linkend="sql-set" endterm="sql-set-title"> reference page.
      </para>
     </listitem>
    </varlistentry>
@@ -83,9 +87,9 @@ SET <replaceable class="parameter">configuration_parameter</replaceable> TO DEFA
   <title>Examples</title>
 
   <para>
-   Set the <varname>geqo</> configuration variable to its default value:
+   Set the <varname>timezone</> configuration variable to its default value:
 <screen>
-RESET geqo;
+RESET timezone;
 </screen>
   </para>
  </refsect1>
@@ -97,4 +101,13 @@ RESET geqo;
    <command>RESET</command> is a <productname>PostgreSQL</productname> extension.
   </para>
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="SQL-SET" endterm="SQL-SET-title"></member>
+   <member><xref linkend="SQL-SHOW" endterm="SQL-SHOW-title"></member>
+  </simplelist>
+ </refsect1>
 </refentry>

doc/src/sgml/ref/set.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/set.sgml,v 1.90 2006/09/22 16:20:00 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/set.sgml,v 1.91 2007/09/11 00:06:41 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -40,13 +40,10 @@ SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="PARAMETER">timezone</rep
   </para>
 
   <para>
-   If <command>SET</command> or <command>SET SESSION</command> is issued
-   within a transaction that is later aborted, the effects of the
+   If <command>SET</command> (or equivalently <command>SET SESSION</command>)
+   is issued within a transaction that is later aborted, the effects of the
    <command>SET</command> command disappear when the transaction is rolled
-   back.  (This behavior represents a change from
-   <productname>PostgreSQL</productname> versions prior to 7.3, where
-   the effects of <command>SET</command> 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
    <command>SET</command>.
   </para>
@@ -59,6 +56,36 @@ SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="PARAMETER">timezone</rep
    seen until the end of the transaction, but afterwards (if the transaction
    is committed) the <command>SET</command> value will take effect.
   </para>
+
+  <para>
+   The effects of <command>SET</command> or <command>SET LOCAL</command> are
+   also canceled by rolling back to a savepoint that is earlier than the
+   command.
+  </para>
+
+  <para>
+   If <command>SET LOCAL</command> is used within a function that has a
+   <literal>SET</> option for the same variable (see
+   <xref linkend="sql-createfunction" endterm="sql-createfunction-title">),
+   the effects of the <command>SET LOCAL</command> command disappear at
+   function exit; that is, the value in effect when the function was called is
+   restored anyway.  This allows <command>SET LOCAL</command> to be used for
+   dynamic or repeated changes of a parameter within a function, while still
+   having the convenience of using the <literal>SET</> option to save and
+   restore the caller's value.  However, a regular <command>SET</> command
+   overrides any surrounding function's <literal>SET</> option; its effects
+   will persist unless rolled back.
+  </para>
+
+  <note>
+   <para>
+    In <productname>PostgreSQL</productname> versions 8.0 through 8.2,
+    the effects of a <command>SET LOCAL</command> would be canceled by
+    releasing an earlier savepoint, or by successful exit from a
+    <application>PL/pgSQL</application> exception block.  This behavior
+    has been changed because it was deemed unintuitive.
+   </para>
+  </note>
  </refsect1>
 
  <refsect1>
@@ -106,8 +133,11 @@ SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="PARAMETER">timezone</rep
      <para>
       New value of parameter.  Values can be specified as string
       constants, identifiers, numbers, or comma-separated lists of
-      these.  <literal>DEFAULT</literal> can be used to specify
-      resetting the parameter to its default value.
+      these, as appropriate for the particular parameter.
+      <literal>DEFAULT</literal> can be written to specify
+      resetting the parameter to its default value (that is, whatever
+      value it would have had if no <command>SET</> had been executed
+      in the current session).
      </para>
     </listitem>
    </varlistentry>
@@ -200,7 +230,9 @@ SELECT setseed(<replaceable>value</replaceable>);
          <term><literal>DEFAULT</literal></term>
          <listitem>
           <para>
-           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 <varname>timezone</>; if this
+           has not been explicitly set anywhere, it will be the zone that
            the server's operating system defaults to).
           </para>
          </listitem>
@@ -221,7 +253,10 @@ SELECT setseed(<replaceable>value</replaceable>);
 
   <para>
    The function <function>set_config</function> provides equivalent
-   functionality. See <xref linkend="functions-admin">.
+   functionality; see <xref linkend="functions-admin">.
+   Also, it is possible to UPDATE the
+   <link linkend="view-pg-settings"><structname>pg_settings</structname></link>
+   system view to perform the equivalent of <command>SET</>.
   </para>
  </refsect1>
 

doc/src/sgml/ref/show.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/show.sgml,v 1.42 2006/09/16 00:30:20 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/show.sgml,v 1.43 2007/09/11 00:06:41 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -36,7 +36,7 @@ SHOW ALL
    the <envar>PGOPTIONS</envar> environmental variable (when using
    <application>libpq</> or a <application>libpq</>-based
    application), or through command-line flags when starting the
-   <command>postgres</command>.  See <xref
+   <command>postgres</command> server.  See <xref
    linkend="runtime-config"> for details.
   </para>
  </refsect1>
@@ -130,7 +130,11 @@ SHOW ALL
 
   <para>
    The function <function>current_setting</function> produces
-   equivalent output. See <xref linkend="functions-admin">.
+   equivalent output; see <xref linkend="functions-admin">.
+   Also, the
+   <link linkend="view-pg-settings"><structname>pg_settings</structname></link>
+   system view produces the same information.
+
   </para>
  </refsect1>
 

src/backend/utils/adt/ri_triggers.c

@@ -15,7 +15,7 @@
  *
  * Portions Copyright (c) 1996-2007, PostgreSQL Global Development Group
  *
- * $PostgreSQL: pgsql/src/backend/utils/adt/ri_triggers.c,v 1.96 2007/08/15 19:15:46 tgl Exp $
+ * $PostgreSQL: pgsql/src/backend/utils/adt/ri_triggers.c,v 1.97 2007/09/11 00:06:42 tgl Exp $
  *
  * ----------
  */
@@ -2749,7 +2749,7 @@ RI_Initial_Check(Trigger *trigger, Relation fk_rel, Relation pk_rel)
 	snprintf(workmembuf, sizeof(workmembuf), "%d", maintenance_work_mem);
 	(void) set_config_option("work_mem", workmembuf,
 							 PGC_USERSET, PGC_S_SESSION,
-							 true, true);
+							 GUC_ACTION_LOCAL, true);
 
 	if (SPI_connect() != SPI_OK_CONNECT)
 		elog(ERROR, "SPI_connect failed");
@@ -2832,13 +2832,12 @@ RI_Initial_Check(Trigger *trigger, Relation fk_rel, Relation pk_rel)
 
 	/*
 	 * Restore work_mem for the remainder of the current transaction. This is
-	 * another SET LOCAL, so it won't affect the session value, nor any
-	 * tentative value if there is one.
+	 * another SET LOCAL, so it won't affect the session value.
 	 */
 	snprintf(workmembuf, sizeof(workmembuf), "%d", old_work_mem);
 	(void) set_config_option("work_mem", workmembuf,
 							 PGC_USERSET, PGC_S_SESSION,
-							 true, true);
+							 GUC_ACTION_LOCAL, true);
 
 	return true;
 }

src/backend/utils/fmgr/fmgr.c

@@ -8,7 +8,7 @@
  *
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/backend/utils/fmgr/fmgr.c,v 1.109 2007/09/03 00:39:18 tgl Exp $
+ *	  $PostgreSQL: pgsql/src/backend/utils/fmgr/fmgr.c,v 1.110 2007/09/11 00:06:42 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -925,20 +925,18 @@ fmgr_security_definer(PG_FUNCTION_ARGS)
 
 		if (fcache->proconfig)
 		{
-			/* The options are processed as if by SET LOCAL var = val */
 			ProcessGUCArray(fcache->proconfig,
 							(superuser() ? PGC_SUSET : PGC_USERSET),
 							PGC_S_SESSION,
-							true);
+							GUC_ACTION_SAVE);
 		}
 
 		result = FunctionCallInvoke(fcinfo);
 	}
 	PG_CATCH();
 	{
 		fcinfo->flinfo = save_flinfo;
-		if (fcache->proconfig)
-			AtEOXact_GUC(false, save_nestlevel);
+		/* We don't need to restore GUC settings, outer xact abort will */
 		if (OidIsValid(fcache->userid))
 			SetUserId(save_userid);
 		PG_RE_THROW();

src/backend/utils/init/miscinit.c

@@ -8,7 +8,7 @@
  *
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/backend/utils/init/miscinit.c,v 1.163 2007/09/03 00:39:18 tgl Exp $
+ *	  $PostgreSQL: pgsql/src/backend/utils/init/miscinit.c,v 1.164 2007/09/11 00:06:42 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -453,7 +453,7 @@ InitializeSessionUserId(const char *rolename)
 		 * right to insert an option into pg_authid was checked when it was
 		 * inserted.
 		 */
-		ProcessGUCArray(a, PGC_SUSET, PGC_S_USER, false);
+		ProcessGUCArray(a, PGC_SUSET, PGC_S_USER, GUC_ACTION_SET);
 	}
 
 	ReleaseSysCache(roleTup);

src/backend/utils/init/postinit.c

@@ -8,7 +8,7 @@
  *
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/backend/utils/init/postinit.c,v 1.177 2007/09/03 00:39:18 tgl Exp $
+ *	  $PostgreSQL: pgsql/src/backend/utils/init/postinit.c,v 1.178 2007/09/11 00:06:42 tgl Exp $
  *
  *
  *-------------------------------------------------------------------------
@@ -255,7 +255,7 @@ CheckMyDatabase(const char *name, bool am_superuser)
 			 * right to insert an option into pg_database was checked when it
 			 * was inserted.
 			 */
-			ProcessGUCArray(a, PGC_SUSET, PGC_S_DATABASE, false);
+			ProcessGUCArray(a, PGC_SUSET, PGC_S_DATABASE, GUC_ACTION_SET);
 		}
 	}