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

   1 '\" t
   2 .\"     Title: ALTER 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 "ALTER 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 ALTER_ROLE \- change a database role
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 ALTER ROLE \fIrole_specification\fR [ WITH ] \fIoption\fR [ \&.\&.\&. ]
  36
  37 where \fIoption\fR can be:
  38
  39       SUPERUSER | NOSUPERUSER
  40     | CREATEDB | NOCREATEDB
  41     | CREATEROLE | NOCREATEROLE
  42     | INHERIT | NOINHERIT
  43     | LOGIN | NOLOGIN
  44     | REPLICATION | NOREPLICATION
  45     | BYPASSRLS | NOBYPASSRLS
  46     | CONNECTION LIMIT \fIconnlimit\fR
  47     | [ ENCRYPTED ] PASSWORD \*(Aq\fIpassword\fR\*(Aq | PASSWORD NULL
  48     | VALID UNTIL \*(Aq\fItimestamp\fR\*(Aq
  49
  50 ALTER ROLE \fIname\fR RENAME TO \fInew_name\fR
  51
  52 ALTER ROLE { \fIrole_specification\fR | ALL } [ IN DATABASE \fIdatabase_name\fR ] SET \fIconfiguration_parameter\fR { TO | = } { \fIvalue\fR | DEFAULT }
  53 ALTER ROLE { \fIrole_specification\fR | ALL } [ IN DATABASE \fIdatabase_name\fR ] SET \fIconfiguration_parameter\fR FROM CURRENT
  54 ALTER ROLE { \fIrole_specification\fR | ALL } [ IN DATABASE \fIdatabase_name\fR ] RESET \fIconfiguration_parameter\fR
  55 ALTER ROLE { \fIrole_specification\fR | ALL } [ IN DATABASE \fIdatabase_name\fR ] RESET ALL
  56
  57 where \fIrole_specification\fR can be:
  58
  59     \fIrole_name\fR
  60   | CURRENT_ROLE
  61   | CURRENT_USER
  62   | SESSION_USER
  63 .fi
  64 .SH "DESCRIPTION"
  65 .PP
  66 \fBALTER ROLE\fR
  67 changes the attributes of a
  68 PostgreSQL
  69 role\&.
  70 .PP
  71 The first variant of this command listed in the synopsis can change many of the role attributes that can be specified in
  72 \fBCREATE ROLE\fR\&. (All the possible attributes are covered, except that there are no options for adding or removing memberships; use
  73 \fBGRANT\fR
  74 and
  75 \fBREVOKE\fR
  76 for that\&.) Attributes not mentioned in the command retain their previous settings\&. Database superusers can change any of these settings for any role, except for changing the
  77 SUPERUSER
  78 property for the
  79 bootstrap superuser\&. Non\-superuser roles having
  80 CREATEROLE
  81 privilege can change most of these properties, but only for non\-superuser and non\-replication roles for which they have been granted
  82 ADMIN OPTION\&. Non\-superusers cannot change the
  83 SUPERUSER
  84 property and can change the
  85 CREATEDB,
  86 REPLICATION, and
  87 BYPASSRLS
  88 properties only if they possess the corresponding property themselves\&. Ordinary roles can only change their own password\&.
  89 .PP
  90 The second variant changes the name of the role\&. Database superusers can rename any role\&. Roles having
  91 CREATEROLE
  92 privilege can rename non\-superuser roles for which they have been granted
  93 ADMIN OPTION\&. The current session user cannot be renamed\&. (Connect as a different user if you need to do that\&.) Because
  94 MD5\-encrypted passwords use the role name as cryptographic salt, renaming a role clears its password if the password is
  95 MD5\-encrypted\&.
  96 .PP
  97 The remaining variants change a role\*(Aqs session default for a configuration variable, either for all databases or, when the
  98 IN DATABASE
  99 clause is specified, only for sessions in the named database\&. If
 100 ALL
 101 is specified instead of a role name, this changes the setting for all roles\&. Using
 102 ALL
 103 with
 104 IN DATABASE
 105 is effectively the same as using the command
 106 ALTER DATABASE \&.\&.\&. SET \&.\&.\&.\&.
 107 .PP
 108 Whenever the role subsequently starts a new session, the specified value becomes the session default, overriding whatever setting is present in
 109 postgresql\&.conf
 110 or has been received from the
 111 \fBpostgres\fR
 112 command line\&. This only happens at login time; executing
 113 \fBSET ROLE\fR
 114 or
 115 \fBSET SESSION AUTHORIZATION\fR
 116 does not cause new configuration values to be set\&. Settings set for all databases are overridden by database\-specific settings attached to a role\&. Settings for specific databases or specific roles override settings for all roles\&.
 117 .PP
 118 Superusers can change anyone\*(Aqs session defaults\&. Roles having
 119 CREATEROLE
 120 privilege can change defaults for non\-superuser roles for which they have been granted
 121 ADMIN OPTION\&. Ordinary roles can only set defaults for themselves\&. Certain configuration variables cannot be set this way, or can only be set if a superuser issues the command\&. Only superusers can change a setting for all roles in all databases\&.
 122 .SH "PARAMETERS"
 123 .PP
 124 \fIname\fR
 125 .RS 4
 126 The name of the role whose attributes are to be altered\&.
 127 .RE
 128 .PP
 129 CURRENT_ROLE
 130 .br
 131 CURRENT_USER
 132 .RS 4
 133 Alter the current user instead of an explicitly identified role\&.
 134 .RE
 135 .PP
 136 SESSION_USER
 137 .RS 4
 138 Alter the current session user instead of an explicitly identified role\&.
 139 .RE
 140 .PP
 141 SUPERUSER
 142 .br
 143 NOSUPERUSER
 144 .br
 145 CREATEDB
 146 .br
 147 NOCREATEDB
 148 .br
 149 CREATEROLE
 150 .br
 151 NOCREATEROLE
 152 .br
 153 INHERIT
 154 .br
 155 NOINHERIT
 156 .br
 157 LOGIN
 158 .br
 159 NOLOGIN
 160 .br
 161 REPLICATION
 162 .br
 163 NOREPLICATION
 164 .br
 165 BYPASSRLS
 166 .br
 167 NOBYPASSRLS
 168 .br
 169 CONNECTION LIMIT \fIconnlimit\fR
 170 .br
 171 [ ENCRYPTED ] PASSWORD \*(Aq\fIpassword\fR\*(Aq
 172 .br
 173 PASSWORD NULL
 174 .br
 175 VALID UNTIL \*(Aq\fItimestamp\fR\*(Aq
 176 .RS 4
 177 These clauses alter attributes originally set by
 178 \fBCREATE ROLE\fR\&. For more information, see the
 179 \fBCREATE ROLE\fR
 180 reference page\&.
 181 .RE
 182 .PP
 183 \fInew_name\fR
 184 .RS 4
 185 The new name of the role\&.
 186 .RE
 187 .PP
 188 \fIdatabase_name\fR
 189 .RS 4
 190 The name of the database the configuration variable should be set in\&.
 191 .RE
 192 .PP
 193 \fIconfiguration_parameter\fR
 194 .br
 195 \fIvalue\fR
 196 .RS 4
 197 Set this role\*(Aqs session default for the specified configuration parameter to the given value\&. If
 198 \fIvalue\fR
 199 is
 200 DEFAULT
 201 or, equivalently,
 202 RESET
 203 is used, the role\-specific variable setting is removed, so the role will inherit the system\-wide default setting in new sessions\&. Use
 204 RESET ALL
 205 to clear all role\-specific settings\&.
 206 SET FROM CURRENT
 207 saves the session\*(Aqs current value of the parameter as the role\-specific value\&. If
 208 IN DATABASE
 209 is specified, the configuration parameter is set or removed for the given role and database only\&.
 210 .sp
 211 Role\-specific variable settings take effect only at login;
 212 \fBSET ROLE\fR
 213 and
 214 \fBSET SESSION AUTHORIZATION\fR
 215 do not process role\-specific variable settings\&.
 216 .sp
 217 See
 218 \fBSET\fR(7)
 219 and
 220 Chapter\ \&19
 221 for more information about allowed parameter names and values\&.
 222 .RE
 223 .SH "NOTES"
 224 .PP
 225 Use
 226 \fBCREATE ROLE\fR
 227 to add new roles, and
 228 \fBDROP ROLE\fR
 229 to remove a role\&.
 230 .PP
 231 \fBALTER ROLE\fR
 232 cannot change a role\*(Aqs memberships\&. Use
 233 \fBGRANT\fR
 234 and
 235 \fBREVOKE\fR
 236 to do that\&.
 237 .PP
 238 Caution must be exercised when specifying an unencrypted password with this command\&. The password will be transmitted to the server in cleartext, and it might also be logged in the client\*(Aqs command history or the server log\&.
 239 \fBpsql\fR(1)
 240 contains a command
 241 \fB\epassword\fR
 242 that can be used to change a role\*(Aqs password without exposing the cleartext password\&.
 243 .PP
 244 It is also possible to tie a session default to a specific database rather than to a role; see
 245 ALTER DATABASE (\fBALTER_DATABASE\fR(7))\&. If there is a conflict, database\-role\-specific settings override role\-specific ones, which in turn override database\-specific ones\&.
 246 .SH "EXAMPLES"
 247 .PP
 248 Change a role\*(Aqs password:
 249 .sp
 250 .if n \{\
 251 .RS 4
 252 .\}
 253 .nf
 254 ALTER ROLE davide WITH PASSWORD \*(Aqhu8jmn3\*(Aq;
 255 .fi
 256 .if n \{\
 257 .RE
 258 .\}
 259 .PP
 260 Remove a role\*(Aqs password:
 261 .sp
 262 .if n \{\
 263 .RS 4
 264 .\}
 265 .nf
 266 ALTER ROLE davide WITH PASSWORD NULL;
 267 .fi
 268 .if n \{\
 269 .RE
 270 .\}
 271 .PP
 272 Change a password expiration date, specifying that the password should expire at midday on 4th May 2015 using the time zone which is one hour ahead of
 273 UTC:
 274 .sp
 275 .if n \{\
 276 .RS 4
 277 .\}
 278 .nf
 279 ALTER ROLE chris VALID UNTIL \*(AqMay 4 12:00:00 2015 +1\*(Aq;
 280 .fi
 281 .if n \{\
 282 .RE
 283 .\}
 284 .PP
 285 Make a password valid forever:
 286 .sp
 287 .if n \{\
 288 .RS 4
 289 .\}
 290 .nf
 291 ALTER ROLE fred VALID UNTIL \*(Aqinfinity\*(Aq;
 292 .fi
 293 .if n \{\
 294 .RE
 295 .\}
 296 .PP
 297 Give a role the ability to manage other roles and create new databases:
 298 .sp
 299 .if n \{\
 300 .RS 4
 301 .\}
 302 .nf
 303 ALTER ROLE miriam CREATEROLE CREATEDB;
 304 .fi
 305 .if n \{\
 306 .RE
 307 .\}
 308 .PP
 309 Give a role a non\-default setting of the
 310 maintenance_work_mem
 311 parameter:
 312 .sp
 313 .if n \{\
 314 .RS 4
 315 .\}
 316 .nf
 317 ALTER ROLE worker_bee SET maintenance_work_mem = 100000;
 318 .fi
 319 .if n \{\
 320 .RE
 321 .\}
 322 .PP
 323 Give a role a non\-default, database\-specific setting of the
 324 client_min_messages
 325 parameter:
 326 .sp
 327 .if n \{\
 328 .RS 4
 329 .\}
 330 .nf
 331 ALTER ROLE fred IN DATABASE devel SET client_min_messages = DEBUG;
 332 .fi
 333 .if n \{\
 334 .RE
 335 .\}
 336 .SH "COMPATIBILITY"
 337 .PP
 338 The
 339 \fBALTER ROLE\fR
 340 statement is a
 341 PostgreSQL
 342 extension\&.
 343 .SH "SEE ALSO"
 344 CREATE ROLE (\fBCREATE_ROLE\fR(7)), DROP ROLE (\fBDROP_ROLE\fR(7)), ALTER DATABASE (\fBALTER_DATABASE\fR(7)), \fBSET\fR(7)