1 files changed, 130 insertions, 0 deletions
diff --git a/doc/src/sgml/ref/set_session_auth.sgml b/doc/src/sgml/ref/set_session_auth.sgml
new file mode 100644
index 0000000..f8fcafc
--- /dev/null
+++ b/doc/src/sgml/ref/set_session_auth.sgml
@@ -0,0 +1,130 @@
+<!--
+doc/src/sgml/ref/set_session_auth.sgml
+PostgreSQL documentation
+-->
+
+<refentry id="sql-set-session-authorization">
+ <indexterm zone="sql-set-session-authorization">
+  <primary>SET SESSION AUTHORIZATION</primary>
+ </indexterm>
+
+ <refmeta>
+  <refentrytitle>SET SESSION AUTHORIZATION</refentrytitle>
+  <manvolnum>7</manvolnum>
+  <refmiscinfo>SQL - Language Statements</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+  <refname>SET SESSION AUTHORIZATION</refname>
+  <refpurpose>set the session user identifier and the current user identifier of the current session</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+SET [ SESSION | LOCAL ] SESSION AUTHORIZATION <replaceable class="parameter">user_name</replaceable>
+SET [ SESSION | LOCAL ] SESSION AUTHORIZATION DEFAULT
+RESET SESSION AUTHORIZATION
+</synopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+  <title>Description</title>
+
+  <para>
+   This command sets the session user identifier and the current user
+   identifier of the current SQL session to be <replaceable
+   class="parameter">user_name</replaceable>.  The user name can be
+   written as either an identifier or a string literal.  Using this
+   command, it is possible, for example, to temporarily become an
+   unprivileged user and later switch back to being a superuser.
+  </para>
+
+  <para>
+   The session user identifier is initially set to be the (possibly
+   authenticated) user name provided by the client.  The current user
+   identifier is normally equal to the session user identifier, but
+   might change temporarily in the context of <literal>SECURITY DEFINER</literal>
+   functions and similar mechanisms; it can also be changed by
+   <link linkend="sql-set-role"><command>SET ROLE</command></link>.
+   The current user identifier is relevant for permission checking.
+  </para>
+
+  <para>
+   The session user identifier can be changed only if the initial session
+   user (the <firstterm>authenticated user</firstterm>) had the
+   superuser privilege.  Otherwise, the command is accepted only if it
+   specifies the authenticated user name.
+  </para>
+
+  <para>
+   The <literal>SESSION</literal> and <literal>LOCAL</literal> modifiers act the same
+   as for the regular <link linkend="sql-set"><command>SET</command></link>
+   command.
+  </para>
+
+  <para>
+   The <literal>DEFAULT</literal> and <literal>RESET</literal> forms reset the session
+   and current user identifiers to be the originally authenticated user
+   name.  These forms can be executed by any user.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Notes</title>
+
+  <para>
+   <command>SET SESSION AUTHORIZATION</command> cannot be used within a
+   <literal>SECURITY DEFINER</literal> function.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Examples</title>
+
+<programlisting>
+SELECT SESSION_USER, CURRENT_USER;
+
+ session_user | current_user
+--------------+--------------
+ peter        | peter
+
+SET SESSION AUTHORIZATION 'paul';
+
+SELECT SESSION_USER, CURRENT_USER;
+
+ session_user | current_user
+--------------+--------------
+ paul         | paul
+</programlisting>
+ </refsect1>
+
+ <refsect1>
+  <title>Compatibility</title>
+
+  <para>
+   The SQL standard allows some other expressions to appear in place
+   of the literal <replaceable>user_name</replaceable>, but these options
+   are not important in practice.  <productname>PostgreSQL</productname>
+   allows identifier syntax (<literal>"<replaceable>username</replaceable>"</literal>), which SQL
+   does not.  SQL does not allow this command during a transaction;
+   <productname>PostgreSQL</productname> does not make this
+   restriction because there is no reason to.
+   The <literal>SESSION</literal> and <literal>LOCAL</literal> modifiers are a
+   <productname>PostgreSQL</productname> extension, as is the
+   <literal>RESET</literal> syntax.
+  </para>
+
+  <para>
+   The privileges necessary to execute this command are left
+   implementation-defined by the standard.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-set-role"/></member>
+  </simplelist>
+ </refsect1>
+</refentry>