Better document that SET ROLE does not uset ALTER ROLE SET settings;

bmomjian · bmomjian · commit 8fbef1090bb2 · 2009-03-28T03:26:02.000Z
suggested wording from Josh Berkus.
diff --git a/doc/src/sgml/ref/alter_role.sgml b/doc/src/sgml/ref/alter_role.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/alter_role.sgml,v 1.11 2008/11/14 10:22:45 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/alter_role.sgml,v 1.12 2009/03/28 03:26:02 momjian Exp $
 PostgreSQL documentation
 -->
 
@@ -79,19 +79,18 @@ ALTER ROLE <replaceable class="PARAMETER">name</replaceable> RESET ALL
    password is <literal>MD5</>-encrypted.
   </para>
 
-  <para>
-   The remaining variants change a role's session default for
-   a specified configuration variable.  Whenever the role subsequently
-   starts a new session, the specified value becomes the session default,
-   overriding whatever setting is present in <filename>postgresql.conf</>
-   or has been received from the <command>postgres</command> command line.
-   (For a role without <literal>LOGIN</> privilege, session defaults have
-   no effect.)
-   Ordinary roles can change their own session defaults.
-   Superusers can change anyone's session defaults.
-   Roles having <literal>CREATEROLE</> privilege can change defaults for
-   non-superuser roles.
-   Certain variables cannot be set this way, or can only be
+  <para> 
+   The remaining variants change a role's session default for a
+   specified configuration variable. Whenever the role subsequently
+   starts a new session, the specified value becomes the session
+   default, overriding whatever setting is present in
+   <filename>postgresql.conf</> or has been received from the postgres
+   command line. This only happens at login time, so configuration
+   settings associated with a role to which you've <xref
+   linkend="sql-set-role" endterm="sql-set-role-title"> will be ignored.
+   Superusers can change anyone's session defaults. Roles having
+   <literal>CREATEROLE</> privilege can change defaults for non-superuser
+   roles. Certain variables cannot be set this way, or can only be
    set if a superuser issues the command.
   </para>
  </refsect1>
@@ -162,6 +161,12 @@ ALTER ROLE <replaceable class="PARAMETER">name</replaceable> RESET ALL
         the parameter as the role-specific value.
        </para>
 
+       <para>
+        Role-specific variable setting take effect only at login;
+        <xref linkend="sql-set-role" endterm="sql-set-role-title">
+        does not process role-specific variable settings.
+       </para>
+
        <para>
         See <xref linkend="sql-set" endterm="sql-set-title"> and <xref
         linkend="runtime-config"> for more information about allowed
diff --git a/doc/src/sgml/ref/set_role.sgml b/doc/src/sgml/ref/set_role.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/set_role.sgml,v 1.6 2008/11/14 10:22:47 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/set_role.sgml,v 1.7 2009/03/28 03:26:02 momjian Exp $
 PostgreSQL documentation
 -->
 
@@ -91,6 +91,13 @@ RESET ROLE
    allowed to a later <command>SET ROLE</>.
   </para>
 
+  <para>
+   <command>SET ROLE</> does not process session variables as specified by
+   the role's <xref linkend="sql-alterrole"
+   endterm="sql-alterrole-title"> settings;  this only happens during
+   login.
+  </para>
+
   <para>
    <command>SET ROLE</> cannot be used within a
    <literal>SECURITY DEFINER</> function.
