doc/src/sgml/ref/set_session_auth.sgml

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