granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/set_role.sgml

   1 <!--
   2 doc/src/sgml/ref/set_role.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-SET-ROLE">
   7  <refmeta>
   8   <refentrytitle>SET ROLE</refentrytitle>
   9   <manvolnum>7</manvolnum>
  10   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>SET ROLE</refname>
  15   <refpurpose>set the current user identifier of the current session</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="sql-set-role">
  19   <primary>SET ROLE</primary>
  20  </indexterm>
  21
  22  <refsynopsisdiv>
  23 <synopsis>
  24 SET [ SESSION | LOCAL ] ROLE <replaceable class="parameter">role_name</replaceable>
  25 SET [ SESSION | LOCAL ] ROLE NONE
  26 RESET ROLE
  27 </synopsis>
  28  </refsynopsisdiv>
  29
  30  <refsect1>
  31   <title>Description</title>
  32
  33   <para>
  34    This command sets the current user
  35    identifier of the current SQL session to be <replaceable
  36    class="parameter">role_name</replaceable>.  The role name can be
  37    written as either an identifier or a string literal.
  38    After <command>SET ROLE</>, permissions checking for SQL commands
  39    is carried out as though the named role were the one that had logged
  40    in originally.
  41   </para>
  42
  43   <para>
  44    The specified <replaceable class="parameter">role_name</replaceable>
  45    must be a role that the current session user is a member of.
  46    (If the session user is a superuser, any role can be selected.)
  47   </para>
  48
  49   <para>
  50    The <literal>SESSION</> and <literal>LOCAL</> modifiers act the same
  51    as for the regular <xref linkend="SQL-SET">
  52    command.
  53   </para>
  54
  55   <para>
  56    The <literal>NONE</> and <literal>RESET</> forms reset the current
  57    user identifier to be the current session user identifier.
  58    These forms can be executed by any user.
  59   </para>
  60  </refsect1>
  61
  62  <refsect1>
  63   <title>Notes</title>
  64
  65   <para>
  66    Using this command, it is possible to either add privileges or restrict
  67    one's privileges.  If the session user role has the <literal>INHERITS</>
  68    attribute, then it automatically has all the privileges of every role that
  69    it could <command>SET ROLE</> to; in this case <command>SET ROLE</>
  70    effectively drops all the privileges assigned directly to the session user
  71    and to the other roles it is a member of, leaving only the privileges
  72    available to the named role.  On the other hand, if the session user role
  73    has the <literal>NOINHERITS</> attribute, <command>SET ROLE</> drops the
  74    privileges assigned directly to the session user and instead acquires the
  75    privileges available to the named role.
  76   </para>
  77
  78   <para>
  79    In particular, when a superuser chooses to <command>SET ROLE</> to a
  80    non-superuser role, she loses her superuser privileges.
  81   </para>
  82
  83   <para>
  84    <command>SET ROLE</> has effects comparable to
  85    <xref linkend="sql-set-session-authorization">, but the privilege
  86    checks involved are quite different.  Also,
  87    <command>SET SESSION AUTHORIZATION</> determines which roles are
  88    allowable for later <command>SET ROLE</> commands, whereas changing
  89    roles with <command>SET ROLE</> does not change the set of roles
  90    allowed to a later <command>SET ROLE</>.
  91   </para>
  92
  93   <para>
  94    <command>SET ROLE</> does not process session variables as specified by
  95    the role's <xref linkend="sql-alterrole"> settings;  this only happens during
  96    login.
  97   </para>
  98
  99   <para>
 100    <command>SET ROLE</> cannot be used within a
 101    <literal>SECURITY DEFINER</> function.
 102   </para>
 103  </refsect1>
 104
 105  <refsect1>
 106   <title>Examples</title>
 107
 108 <programlisting>
 109 SELECT SESSION_USER, CURRENT_USER;
 110
 111  session_user | current_user
 112 --------------+--------------
 113  peter        | peter
 114
 115 SET ROLE 'paul';
 116
 117 SELECT SESSION_USER, CURRENT_USER;
 118
 119  session_user | current_user
 120 --------------+--------------
 121  peter        | paul
 122 </programlisting>
 123  </refsect1>
 124
 125  <refsect1>
 126   <title>Compatibility</title>
 127
 128   <para>
 129    <productname>PostgreSQL</productname>
 130    allows identifier syntax (<literal>"rolename"</literal>), while
 131    the SQL standard requires the role name to be written as a string
 132    literal.  SQL does not allow this command during a transaction;
 133    <productname>PostgreSQL</productname> does not make this
 134    restriction because there is no reason to.
 135    The <literal>SESSION</> and <literal>LOCAL</> modifiers are a
 136    <productname>PostgreSQL</productname> extension, as is the
 137    <literal>RESET</> syntax.
 138   </para>
 139  </refsect1>
 140
 141  <refsect1>
 142   <title>See Also</title>
 143
 144   <simplelist type="inline">
 145    <member><xref linkend="sql-set-session-authorization"></member>
 146   </simplelist>
 147  </refsect1>
 148 </refentry>