doc/src/sgml/ref/set_session_auth.sgml

   1 <!-- $PostgreSQL$ -->
   2 <refentry id="SQL-SET-SESSION-AUTHORIZATION">
   3  <refmeta>
   4   <refentrytitle id="sql-set-session-authorization-title">SET SESSION AUTHORIZATION</refentrytitle>
   5   <manvolnum>7</manvolnum>
   6   <refmiscinfo>SQL - Language Statements</refmiscinfo>
   7  </refmeta>
   8
   9  <refnamediv>
  10   <refname>SET SESSION AUTHORIZATION</refname>
  11   <refpurpose>set the session user identifier and the current user identifier of the current session</refpurpose>
  12  </refnamediv>
  13
  14  <indexterm zone="sql-set-session-authorization">
  15   <primary>SET SESSION AUTHORIZATION</primary>
  16  </indexterm>
  17
  18  <refsynopsisdiv>
  19 <synopsis>
  20 SET [ SESSION | LOCAL ] SESSION AUTHORIZATION <replaceable class="parameter">username</replaceable>
  21 SET [ SESSION | LOCAL ] SESSION AUTHORIZATION DEFAULT
  22 RESET SESSION AUTHORIZATION
  23 </synopsis>
  24  </refsynopsisdiv>
  25
  26  <refsect1>
  27   <title>Description</title>
  28
  29   <para>
  30    This command sets the session user identifier and the current user
  31    identifier of the current SQL session to be <replaceable
  32    class="parameter">username</replaceable>.  The user name can be
  33    written as either an identifier or a string literal.  Using this
  34    command, it is possible, for example, to temporarily become an
  35    unprivileged user and later switch back to being a superuser.
  36   </para>
  37
  38   <para>
  39    The session user identifier is initially set to be the (possibly
  40    authenticated) user name provided by the client.  The current user
  41    identifier is normally equal to the session user identifier, but
  42    might change temporarily in the context of <literal>SECURITY DEFINER</>
  43    functions and similar mechanisms; it can also be changed by
  44    <xref linkend="sql-set-role" endterm="sql-set-role-title">.
  45    The current user identifier is relevant for permission checking.
  46   </para>
  47
  48   <para>
  49    The session user identifier can be changed only if the initial session
  50    user (the <firstterm>authenticated user</firstterm>) had the
  51    superuser privilege.  Otherwise, the command is accepted only if it
  52    specifies the authenticated user name.
  53   </para>
  54
  55   <para>
  56    The <literal>SESSION</> and <literal>LOCAL</> modifiers act the same
  57    as for the regular <xref linkend="SQL-SET" endterm="SQL-SET-title">
  58    command.
  59   </para>
  60
  61   <para>
  62    The <literal>DEFAULT</> and <literal>RESET</> forms reset the session
  63    and current user identifiers to be the originally authenticated user
  64    name.  These forms can be executed by any user.
  65   </para>
  66  </refsect1>
  67
  68  <refsect1>
  69   <title>Notes</title>
  70
  71   <para>
  72    <command>SET SESSION AUTHORIZATION</> cannot be used within a
  73    <literal>SECURITY DEFINER</> function.
  74   </para>
  75  </refsect1>
  76
  77  <refsect1>
  78   <title>Examples</title>
  79
  80 <programlisting>
  81 SELECT SESSION_USER, CURRENT_USER;
  82
  83  session_user | current_user
  84 --------------+--------------
  85  peter        | peter
  86
  87 SET SESSION AUTHORIZATION 'paul';
  88
  89 SELECT SESSION_USER, CURRENT_USER;
  90
  91  session_user | current_user
  92 --------------+--------------
  93  paul         | paul
  94 </programlisting>
  95  </refsect1>
  96
  97  <refsect1>
  98   <title>Compatibility</title>
  99
 100   <para>
 101    The SQL standard allows some other expressions to appear in place
 102    of the literal <replaceable>username</replaceable>, but these options
 103    are not important in practice.  <productname>PostgreSQL</productname>
 104    allows identifier syntax (<literal>"username"</literal>), which SQL
 105    does not.  SQL does not allow this command during a transaction;
 106    <productname>PostgreSQL</productname> does not make this
 107    restriction because there is no reason to.
 108    The <literal>SESSION</> and <literal>LOCAL</> modifiers are a
 109    <productname>PostgreSQL</productname> extension, as is the
 110    <literal>RESET</> syntax.
 111   </para>
 112
 113   <para>
 114    The privileges necessary to execute this command are left
 115    implementation-defined by the standard.
 116   </para>
 117  </refsect1>
 118
 119  <refsect1>
 120   <title>See Also</title>
 121
 122   <simplelist type="inline">
 123    <member><xref linkend="sql-set-role" endterm="sql-set-role-title"></member>
 124   </simplelist>
 125  </refsect1>
 126 </refentry>