begriffs open source - ai-pg/blob - full-docs/man7/SET_ROLE.7

   1 '\" t
   2 .\"     Title: SET ROLE
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "SET ROLE" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 SET_ROLE \- set the current user identifier of the current session
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 SET [ SESSION | LOCAL ] ROLE \fIrole_name\fR
  36 SET [ SESSION | LOCAL ] ROLE NONE
  37 RESET ROLE
  38 .fi
  39 .SH "DESCRIPTION"
  40 .PP
  41 This command sets the current user identifier of the current SQL session to be
  42 \fIrole_name\fR\&. The role name can be written as either an identifier or a string literal\&. After
  43 \fBSET ROLE\fR, permissions checking for SQL commands is carried out as though the named role were the one that had logged in originally\&. Note that
  44 \fBSET ROLE\fR
  45 and
  46 \fBSET SESSION AUTHORIZATION\fR
  47 are exceptions; permissions checks for those continue to use the current session user and the initial session user (the
  48 authenticated user), respectively\&.
  49 .PP
  50 The current session user must have the
  51 SET
  52 option for the specified
  53 \fIrole_name\fR, either directly or indirectly via a chain of memberships with the
  54 SET
  55 option\&. (If the session user is a superuser, any role can be selected\&.)
  56 .PP
  57 The
  58 SESSION
  59 and
  60 LOCAL
  61 modifiers act the same as for the regular
  62 \fBSET\fR
  63 command\&.
  64 .PP
  65 SET ROLE NONE
  66 sets the current user identifier to the current session user identifier, as returned by
  67 \fBsession_user\fR\&.
  68 RESET ROLE
  69 sets the current user identifier to the connection\-time setting specified by the
  70 command\-line options,
  71 \fBALTER ROLE\fR, or
  72 \fBALTER DATABASE\fR, if any such settings exist\&. Otherwise,
  73 RESET ROLE
  74 sets the current user identifier to the current session user identifier\&. These forms can be executed by any user\&.
  75 .SH "NOTES"
  76 .PP
  77 Using this command, it is possible to either add privileges or restrict one\*(Aqs privileges\&. If the session user role has been granted memberships
  78 WITH INHERIT TRUE, it automatically has all the privileges of every such role\&. In this case,
  79 \fBSET ROLE\fR
  80 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
  81 WITH INHERIT FALSE, the privileges of the granted roles can\*(Aqt be accessed by default\&. However, if the role was granted
  82 WITH SET TRUE, the session user can use
  83 \fBSET ROLE\fR
  84 to drop the privileges assigned directly to the session user and instead acquire the privileges available to the named role\&. If the role was granted
  85 WITH INHERIT FALSE, SET FALSE
  86 then the privileges of that role cannot be exercised either with or without
  87 SET ROLE\&.
  88 .PP
  89 \fBSET ROLE\fR
  90 has effects comparable to
  91 \fBSET SESSION AUTHORIZATION\fR, but the privilege checks involved are quite different\&. Also,
  92 \fBSET SESSION AUTHORIZATION\fR
  93 determines which roles are allowable for later
  94 \fBSET ROLE\fR
  95 commands, whereas changing roles with
  96 \fBSET ROLE\fR
  97 does not change the set of roles allowed to a later
  98 \fBSET ROLE\fR\&.
  99 .PP
 100 \fBSET ROLE\fR
 101 does not process session variables as specified by the role\*(Aqs
 102 \fBALTER ROLE\fR
 103 settings; this only happens during login\&.
 104 .PP
 105 \fBSET ROLE\fR
 106 cannot be used within a
 107 SECURITY DEFINER
 108 function\&.
 109 .SH "EXAMPLES"
 110 .sp
 111 .if n \{\
 112 .RS 4
 113 .\}
 114 .nf
 115 SELECT SESSION_USER, CURRENT_USER;
 116
 117  session_user | current_user
 118 \-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 119  peter        | peter
 120
 121 SET ROLE \*(Aqpaul\*(Aq;
 122
 123 SELECT SESSION_USER, CURRENT_USER;
 124
 125  session_user | current_user
 126 \-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 127  peter        | paul
 128 .fi
 129 .if n \{\
 130 .RE
 131 .\}
 132 .SH "COMPATIBILITY"
 133 .PP
 134 PostgreSQL
 135 allows identifier syntax ("\fIrolename\fR"), while the SQL standard requires the role name to be written as a string literal\&. SQL does not allow this command during a transaction;
 136 PostgreSQL
 137 does not make this restriction because there is no reason to\&. The
 138 SESSION
 139 and
 140 LOCAL
 141 modifiers are a
 142 PostgreSQL
 143 extension, as is the
 144 RESET
 145 syntax\&.
 146 .SH "SEE ALSO"
 147 SET SESSION AUTHORIZATION (\fBSET_SESSION_AUTHORIZATION\fR(7))