2005-07-27 01:24:02 +02:00
|
|
|
<!--
|
2010-09-20 22:08:53 +02:00
|
|
|
doc/src/sgml/ref/set_role.sgml
|
2005-07-27 01:24:02 +02:00
|
|
|
PostgreSQL documentation
|
|
|
|
-->
|
|
|
|
|
2017-10-20 03:16:39 +02:00
|
|
|
<refentry id="sql-set-role">
|
2014-02-24 03:25:35 +01:00
|
|
|
<indexterm zone="sql-set-role">
|
|
|
|
<primary>SET ROLE</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
2005-07-26 00:12:34 +02:00
|
|
|
<refmeta>
|
2010-04-03 09:23:02 +02:00
|
|
|
<refentrytitle>SET ROLE</refentrytitle>
|
2008-11-14 11:22:48 +01:00
|
|
|
<manvolnum>7</manvolnum>
|
2005-07-26 00:12:34 +02:00
|
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
|
|
</refmeta>
|
|
|
|
|
|
|
|
<refnamediv>
|
|
|
|
<refname>SET ROLE</refname>
|
|
|
|
<refpurpose>set the current user identifier of the current session</refpurpose>
|
|
|
|
</refnamediv>
|
|
|
|
|
|
|
|
<refsynopsisdiv>
|
|
|
|
<synopsis>
|
2009-09-19 12:23:27 +02:00
|
|
|
SET [ SESSION | LOCAL ] ROLE <replaceable class="parameter">role_name</replaceable>
|
2005-07-26 00:12:34 +02:00
|
|
|
SET [ SESSION | LOCAL ] ROLE NONE
|
|
|
|
RESET ROLE
|
|
|
|
</synopsis>
|
|
|
|
</refsynopsisdiv>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Description</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
This command sets the current user
|
2008-01-03 22:23:15 +01:00
|
|
|
identifier of the current SQL session to be <replaceable
|
2009-09-19 12:23:27 +02:00
|
|
|
class="parameter">role_name</replaceable>. The role name can be
|
2005-07-27 01:24:02 +02:00
|
|
|
written as either an identifier or a string literal.
|
2017-10-09 03:44:17 +02:00
|
|
|
After <command>SET ROLE</command>, permissions checking for SQL commands
|
2005-07-27 01:24:02 +02:00
|
|
|
is carried out as though the named role were the one that had logged
|
2024-04-15 21:03:24 +02:00
|
|
|
in originally. Note that <command>SET ROLE</command> and
|
|
|
|
<command>SET SESSION AUTHORIZATION</command> are exceptions; permissions
|
|
|
|
checks for those continue to use the current session user and the initial
|
|
|
|
session user (the <firstterm>authenticated user</firstterm>), respectively.
|
2005-07-26 00:12:34 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2024-03-24 21:23:55 +01:00
|
|
|
The current session user must have the <literal>SET</literal> option for the
|
|
|
|
specified <replaceable class="parameter">role_name</replaceable>, either
|
|
|
|
directly or indirectly via a chain of memberships with the
|
|
|
|
<literal>SET</literal> option.
|
2005-07-26 00:12:34 +02:00
|
|
|
(If the session user is a superuser, any role can be selected.)
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
The <literal>SESSION</literal> and <literal>LOCAL</literal> modifiers act the same
|
Improve <xref> vs. <command> formatting in the documentation
SQL commands are generally marked up as <command>, except when a link
to a reference page is used using <xref>. But the latter doesn't
create monospace markup, so this looks strange especially when a
paragraph contains a mix of links and non-links.
We considered putting <command> in the <refentrytitle> on the target
side, but that creates some formatting side effects elsewhere.
Generally, it seems safer to solve this on the link source side.
We can't put the <xref> inside the <command>; the DTD doesn't allow
this. DocBook 5 would allow the <command> to have the linkend
attribute itself, but we are not there yet.
So to solve this for now, convert the <xref>s to <link> plus
<command>. This gives the correct look and also gives some more
flexibility what we can put into the link text (e.g., subcommands or
other clauses). In the future, these could then be converted to
DocBook 5 style.
I haven't converted absolutely all xrefs to SQL command reference
pages, only those where we care about the appearance of the link text
or where it was otherwise appropriate to make the appearance match a
bit better. Also in some cases, the links where repetitive, so in
those cases the links where just removed and replaced by a plain
<command>. In cases where we just want the link and don't
specifically care about the generated link text (typically phrased
"for further information see <xref ...>") the xref is kept.
Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
2020-10-03 16:16:51 +02:00
|
|
|
as for the regular <link linkend="sql-set"><command>SET</command></link>
|
2005-07-26 00:12:34 +02:00
|
|
|
command.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2021-04-02 19:48:42 +02:00
|
|
|
<literal>SET ROLE NONE</literal> sets the current user identifier to the
|
|
|
|
current session user identifier, as returned by
|
|
|
|
<function>session_user</function>. <literal>RESET ROLE</literal> sets the
|
|
|
|
current user identifier to the connection-time setting specified by the
|
|
|
|
<link linkend="libpq-connect-options">command-line options</link>,
|
|
|
|
<link linkend="sql-alterrole"><command>ALTER ROLE</command></link>, or
|
|
|
|
<link linkend="sql-alterdatabase"><command>ALTER DATABASE</command></link>,
|
|
|
|
if any such settings exist. Otherwise, <literal>RESET ROLE</literal> sets
|
|
|
|
the current user identifier to the current session user identifier. These
|
|
|
|
forms can be executed by any user.
|
2005-07-26 00:12:34 +02:00
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
2005-07-27 01:24:02 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Notes</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Using this command, it is possible to either add privileges or restrict
|
2022-08-29 16:10:09 +02:00
|
|
|
one's privileges. If the session user role has been granted memberships
|
|
|
|
<literal>WITH INHERIT TRUE</literal>, it automatically has all the
|
|
|
|
privileges of every such role. In this case, <command>SET ROLE</command>
|
|
|
|
effectively drops all the privileges except for those which the target role
|
|
|
|
directly possesses or inherits. On the other hand, if the session user role
|
|
|
|
has been granted memberships <literal>WITH INHERIT FALSE</literal>, the
|
Add a SET option to the GRANT command.
Similar to how the INHERIT option controls whether or not the
permissions of the granted role are automatically available to the
grantee, the new SET permission controls whether or not the grantee
may use the SET ROLE command to assume the privileges of the granted
role.
In addition, the new SET permission controls whether or not it
is possible to transfer ownership of objects to the target role
or to create new objects owned by the target role using commands
such as CREATE DATABASE .. OWNER. We could alternatively have made
this controlled by the INHERIT option, or allow it when either
option is given. An advantage of this approach is that if you
are granted a predefined role with INHERIT TRUE, SET FALSE, you
can't go and create objects owned by that role.
The underlying theory here is that the ability to create objects
as a target role is not a privilege per se, and thus does not
depend on whether you inherit the target role's privileges. However,
it's surely something you could do anyway if you could SET ROLE
to the target role, and thus making it contingent on whether you
have that ability is reasonable.
Design review by Nathan Bossat, Wolfgang Walther, Jeff Davis,
Peter Eisentraut, and Stephen Frost.
Discussion: http://postgr.es/m/CA+Tgmob+zDSRS6JXYrgq0NWdzCXuTNzT5eK54Dn2hhgt17nm8A@mail.gmail.com
2022-11-18 18:32:50 +01:00
|
|
|
privileges of the granted roles can't be accessed by default. However, if
|
|
|
|
the role was granted <literal>WITH SET TRUE</literal>, the
|
2022-08-29 16:10:09 +02:00
|
|
|
session user can use <command>SET ROLE</command> to drop the privileges
|
|
|
|
assigned directly to the session user and instead acquire the privileges
|
Add a SET option to the GRANT command.
Similar to how the INHERIT option controls whether or not the
permissions of the granted role are automatically available to the
grantee, the new SET permission controls whether or not the grantee
may use the SET ROLE command to assume the privileges of the granted
role.
In addition, the new SET permission controls whether or not it
is possible to transfer ownership of objects to the target role
or to create new objects owned by the target role using commands
such as CREATE DATABASE .. OWNER. We could alternatively have made
this controlled by the INHERIT option, or allow it when either
option is given. An advantage of this approach is that if you
are granted a predefined role with INHERIT TRUE, SET FALSE, you
can't go and create objects owned by that role.
The underlying theory here is that the ability to create objects
as a target role is not a privilege per se, and thus does not
depend on whether you inherit the target role's privileges. However,
it's surely something you could do anyway if you could SET ROLE
to the target role, and thus making it contingent on whether you
have that ability is reasonable.
Design review by Nathan Bossat, Wolfgang Walther, Jeff Davis,
Peter Eisentraut, and Stephen Frost.
Discussion: http://postgr.es/m/CA+Tgmob+zDSRS6JXYrgq0NWdzCXuTNzT5eK54Dn2hhgt17nm8A@mail.gmail.com
2022-11-18 18:32:50 +01:00
|
|
|
available to the named role. If the role was granted <literal>WITH INHERIT
|
|
|
|
FALSE, SET FALSE</literal> then the privileges of that role cannot be
|
|
|
|
exercised either with or without <literal>SET ROLE</literal>.
|
2005-07-27 01:24:02 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
<command>SET ROLE</command> has effects comparable to
|
Improve <xref> vs. <command> formatting in the documentation
SQL commands are generally marked up as <command>, except when a link
to a reference page is used using <xref>. But the latter doesn't
create monospace markup, so this looks strange especially when a
paragraph contains a mix of links and non-links.
We considered putting <command> in the <refentrytitle> on the target
side, but that creates some formatting side effects elsewhere.
Generally, it seems safer to solve this on the link source side.
We can't put the <xref> inside the <command>; the DTD doesn't allow
this. DocBook 5 would allow the <command> to have the linkend
attribute itself, but we are not there yet.
So to solve this for now, convert the <xref>s to <link> plus
<command>. This gives the correct look and also gives some more
flexibility what we can put into the link text (e.g., subcommands or
other clauses). In the future, these could then be converted to
DocBook 5 style.
I haven't converted absolutely all xrefs to SQL command reference
pages, only those where we care about the appearance of the link text
or where it was otherwise appropriate to make the appearance match a
bit better. Also in some cases, the links where repetitive, so in
those cases the links where just removed and replaced by a plain
<command>. In cases where we just want the link and don't
specifically care about the generated link text (typically phrased
"for further information see <xref ...>") the xref is kept.
Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
2020-10-03 16:16:51 +02:00
|
|
|
<link linkend="sql-set-session-authorization"><command>SET SESSION AUTHORIZATION</command></link>, but the privilege
|
2005-07-27 01:24:02 +02:00
|
|
|
checks involved are quite different. Also,
|
2017-10-09 03:44:17 +02:00
|
|
|
<command>SET SESSION AUTHORIZATION</command> determines which roles are
|
|
|
|
allowable for later <command>SET ROLE</command> commands, whereas changing
|
|
|
|
roles with <command>SET ROLE</command> does not change the set of roles
|
|
|
|
allowed to a later <command>SET ROLE</command>.
|
2005-07-27 01:24:02 +02:00
|
|
|
</para>
|
2008-01-03 22:23:15 +01:00
|
|
|
|
2009-03-28 04:26:02 +01:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
<command>SET ROLE</command> does not process session variables as specified by
|
Improve <xref> vs. <command> formatting in the documentation
SQL commands are generally marked up as <command>, except when a link
to a reference page is used using <xref>. But the latter doesn't
create monospace markup, so this looks strange especially when a
paragraph contains a mix of links and non-links.
We considered putting <command> in the <refentrytitle> on the target
side, but that creates some formatting side effects elsewhere.
Generally, it seems safer to solve this on the link source side.
We can't put the <xref> inside the <command>; the DTD doesn't allow
this. DocBook 5 would allow the <command> to have the linkend
attribute itself, but we are not there yet.
So to solve this for now, convert the <xref>s to <link> plus
<command>. This gives the correct look and also gives some more
flexibility what we can put into the link text (e.g., subcommands or
other clauses). In the future, these could then be converted to
DocBook 5 style.
I haven't converted absolutely all xrefs to SQL command reference
pages, only those where we care about the appearance of the link text
or where it was otherwise appropriate to make the appearance match a
bit better. Also in some cases, the links where repetitive, so in
those cases the links where just removed and replaced by a plain
<command>. In cases where we just want the link and don't
specifically care about the generated link text (typically phrased
"for further information see <xref ...>") the xref is kept.
Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
2020-10-03 16:16:51 +02:00
|
|
|
the role's <link linkend="sql-alterrole"><command>ALTER ROLE</command></link> settings; this only happens during
|
2009-03-28 04:26:02 +01:00
|
|
|
login.
|
|
|
|
</para>
|
|
|
|
|
2008-01-03 22:23:15 +01:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
<command>SET ROLE</command> cannot be used within a
|
|
|
|
<literal>SECURITY DEFINER</literal> function.
|
2008-01-03 22:23:15 +01:00
|
|
|
</para>
|
2005-07-27 01:24:02 +02:00
|
|
|
</refsect1>
|
|
|
|
|
2005-07-26 00:12:34 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Examples</title>
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
SELECT SESSION_USER, CURRENT_USER;
|
|
|
|
|
2022-04-20 17:04:28 +02:00
|
|
|
session_user | current_user
|
2005-07-26 00:12:34 +02:00
|
|
|
--------------+--------------
|
|
|
|
peter | peter
|
|
|
|
|
|
|
|
SET ROLE 'paul';
|
|
|
|
|
|
|
|
SELECT SESSION_USER, CURRENT_USER;
|
|
|
|
|
2022-04-20 17:04:28 +02:00
|
|
|
session_user | current_user
|
2005-07-26 00:12:34 +02:00
|
|
|
--------------+--------------
|
|
|
|
peter | paul
|
|
|
|
</programlisting>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Compatibility</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<productname>PostgreSQL</productname>
|
2017-10-09 03:44:17 +02:00
|
|
|
allows identifier syntax (<literal>"<replaceable>rolename</replaceable>"</literal>), while
|
2005-07-26 00:12:34 +02:00
|
|
|
the SQL standard requires the role name to be written as a string
|
|
|
|
literal. SQL does not allow this command during a transaction;
|
|
|
|
<productname>PostgreSQL</productname> does not make this
|
|
|
|
restriction because there is no reason to.
|
2017-10-09 03:44:17 +02:00
|
|
|
The <literal>SESSION</literal> and <literal>LOCAL</literal> modifiers are a
|
2005-07-26 00:12:34 +02:00
|
|
|
<productname>PostgreSQL</productname> extension, as is the
|
2017-10-09 03:44:17 +02:00
|
|
|
<literal>RESET</literal> syntax.
|
2005-07-26 00:12:34 +02:00
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>See Also</title>
|
|
|
|
|
|
|
|
<simplelist type="inline">
|
2017-11-23 15:39:47 +01:00
|
|
|
<member><xref linkend="sql-set-session-authorization"/></member>
|
2005-07-26 00:12:34 +02:00
|
|
|
</simplelist>
|
|
|
|
</refsect1>
|
|
|
|
</refentry>
|