granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/alter_role.sgml

   1 <!--
   2 doc/src/sgml/ref/alter_role.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-ALTERROLE">
   7  <indexterm zone="sql-alterrole">
   8   <primary>ALTER ROLE</primary>
   9  </indexterm>
  10
  11  <refmeta>
  12   <refentrytitle>ALTER ROLE</refentrytitle>
  13   <manvolnum>7</manvolnum>
  14   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  15  </refmeta>
  16
  17  <refnamediv>
  18   <refname>ALTER ROLE</refname>
  19   <refpurpose>change a database role</refpurpose>
  20  </refnamediv>
  21
  22  <refsynopsisdiv>
  23 <synopsis>
  24 ALTER ROLE <replaceable class="PARAMETER">role_specification</replaceable> [ WITH ] <replaceable class="PARAMETER">option</replaceable> [ ... ]
  25
  26 <phrase>where <replaceable class="PARAMETER">option</replaceable> can be:</phrase>
  27
  28       SUPERUSER | NOSUPERUSER
  29     | CREATEDB | NOCREATEDB
  30     | CREATEROLE | NOCREATEROLE
  31     | INHERIT | NOINHERIT
  32     | LOGIN | NOLOGIN
  33     | REPLICATION | NOREPLICATION
  34     | BYPASSRLS | NOBYPASSRLS
  35     | CONNECTION LIMIT <replaceable class="PARAMETER">connlimit</replaceable>
  36     | [ ENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
  37     | VALID UNTIL '<replaceable class="PARAMETER">timestamp</replaceable>'
  38
  39 ALTER ROLE <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>new_name</replaceable>
  40
  41 ALTER ROLE { <replaceable class="PARAMETER">role_specification</replaceable> | ALL } [ IN DATABASE <replaceable class="PARAMETER">database_name</replaceable> ] SET <replaceable>configuration_parameter</replaceable> { TO | = } { <replaceable>value</replaceable> | DEFAULT }
  42 ALTER ROLE { <replaceable class="PARAMETER">role_specification</replaceable> | ALL } [ IN DATABASE <replaceable class="PARAMETER">database_name</replaceable> ] SET <replaceable>configuration_parameter</replaceable> FROM CURRENT
  43 ALTER ROLE { <replaceable class="PARAMETER">role_specification</replaceable> | ALL } [ IN DATABASE <replaceable class="PARAMETER">database_name</replaceable> ] RESET <replaceable>configuration_parameter</replaceable>
  44 ALTER ROLE { <replaceable class="PARAMETER">role_specification</replaceable> | ALL } [ IN DATABASE <replaceable class="PARAMETER">database_name</replaceable> ] RESET ALL
  45
  46 <phrase>where <replaceable class="PARAMETER">role_specification</replaceable> can be:</phrase>
  47
  48     [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable>
  49   | CURRENT_USER
  50   | SESSION_USER
  51 </synopsis>
  52  </refsynopsisdiv>
  53
  54  <refsect1>
  55   <title>Description</title>
  56
  57   <para>
  58    <command>ALTER ROLE</command> changes the attributes of a
  59    <productname>PostgreSQL</productname> role.
  60   </para>
  61
  62   <para>
  63    The first variant of this command listed in the synopsis can change
  64    many of the role attributes that can be specified in
  65    <xref linkend="sql-createrole">.
  66    (All the possible attributes are covered,
  67    except that there are no options for adding or removing memberships; use
  68    <xref linkend="SQL-GRANT"> and
  69    <xref linkend="SQL-REVOKE"> for that.)
  70    Attributes not mentioned in the command retain their previous settings.
  71    Database superusers can change any of these settings for any role.
  72    Roles having <literal>CREATEROLE</> privilege can change any of these
  73    settings, but only for non-superuser and non-replication roles.
  74    Ordinary roles can only change their own password.
  75   </para>
  76
  77   <para>
  78    The second variant changes the name of the role.
  79    Database superusers can rename any role.
  80    Roles having <literal>CREATEROLE</> privilege can rename non-superuser
  81    roles.
  82    The current session user cannot be renamed.
  83    (Connect as a different user if you need to do that.)
  84    Because <literal>MD5</>-encrypted passwords use the role name as
  85    cryptographic salt, renaming a role clears its password if the
  86    password is <literal>MD5</>-encrypted.
  87   </para>
  88
  89   <para>
  90    The remaining variants change a role's session default for a configuration
  91    variable, either for all databases or, when the <literal>IN
  92    DATABASE</literal> clause is specified, only for sessions in the named
  93    database.  If <literal>ALL</literal> is specified instead of a role name,
  94    this changes the setting for all roles.  Using <literal>ALL</literal>
  95    with <literal>IN DATABASE</literal> is effectively the same as using the
  96    command <literal>ALTER DATABASE ... SET ...</literal>.
  97   </para>
  98
  99   <para>
 100    Whenever the role subsequently
 101    starts a new session, the specified value becomes the session
 102    default, overriding whatever setting is present in
 103    <filename>postgresql.conf</> or has been received from the <command>postgres</command>
 104    command line. This only happens at login time; executing
 105    <xref linkend="sql-set-role"> or
 106    <xref linkend="sql-set-session-authorization"> does not cause new
 107    configuration values to be set.
 108    Settings set for all databases are overridden by database-specific settings
 109    attached to a role.  Settings for specific databases or specific roles override
 110    settings for all roles.
 111   </para>
 112
 113   <para>
 114    Superusers can change anyone's session defaults. Roles having
 115    <literal>CREATEROLE</> privilege can change defaults for non-superuser
 116    roles. Ordinary roles can only set defaults for themselves.
 117    Certain configuration variables cannot be set this way, or can only be
 118    set if a superuser issues the command.  Only superusers can change a setting
 119    for all roles in all databases.
 120   </para>
 121  </refsect1>
 122
 123  <refsect1>
 124   <title>Parameters</title>
 125
 126     <variablelist>
 127      <varlistentry>
 128       <term><replaceable class="PARAMETER">name</replaceable></term>
 129       <listitem>
 130        <para>
 131         The name of the role whose attributes are to be altered.
 132        </para>
 133       </listitem>
 134      </varlistentry>
 135
 136      <varlistentry>
 137       <term><literal>CURRENT_USER</literal></term>
 138       <listitem>
 139        <para>
 140         Alter the current user instead of an explicitly identified role.
 141        </para>
 142       </listitem>
 143      </varlistentry>
 144
 145      <varlistentry>
 146       <term><literal>SESSION_USER</literal></term>
 147       <listitem>
 148        <para>
 149         Alter the current session user instead of an explicitly identified
 150         role.
 151        </para>
 152       </listitem>
 153      </varlistentry>
 154
 155      <varlistentry>
 156       <term><literal>SUPERUSER</literal></term>
 157       <term><literal>NOSUPERUSER</literal></term>
 158       <term><literal>CREATEDB</></term>
 159       <term><literal>NOCREATEDB</></term>
 160       <term><literal>CREATEROLE</literal></term>
 161       <term><literal>NOCREATEROLE</literal></term>
 162       <term><literal>INHERIT</literal></term>
 163       <term><literal>NOINHERIT</literal></term>
 164       <term><literal>LOGIN</literal></term>
 165       <term><literal>NOLOGIN</literal></term>
 166       <term><literal>REPLICATION</literal></term>
 167       <term><literal>NOREPLICATION</literal></term>
 168       <term><literal>BYPASSRLS</literal></term>
 169       <term><literal>NOBYPASSRLS</literal></term>
 170       <term><literal>CONNECTION LIMIT</literal> <replaceable class="parameter">connlimit</replaceable></term>
 171       <term>[ <literal>ENCRYPTED</> ] <literal>PASSWORD</> <replaceable class="parameter">password</replaceable></term>
 172       <term><literal>VALID UNTIL</literal> '<replaceable class="parameter">timestamp</replaceable>'</term>
 173       <listitem>
 174        <para>
 175         These clauses alter attributes originally set by
 176         <xref linkend="SQL-CREATEROLE">. For more information, see the
 177         <command>CREATE ROLE</command> reference page.
 178        </para>
 179       </listitem>
 180      </varlistentry>
 181
 182      <varlistentry>
 183       <term><replaceable>new_name</replaceable></term>
 184       <listitem>
 185        <para>
 186         The new name of the role.
 187        </para>
 188       </listitem>
 189      </varlistentry>
 190
 191      <varlistentry>
 192        <term><replaceable>database_name</replaceable></term>
 193        <listitem>
 194          <para>
 195            The name of the database the configuration variable should be set in.
 196          </para>
 197        </listitem>
 198      </varlistentry>
 199
 200      <varlistentry>
 201       <term><replaceable>configuration_parameter</replaceable></term>
 202       <term><replaceable>value</replaceable></term>
 203       <listitem>
 204        <para>
 205         Set this role's session default for the specified configuration
 206         parameter to the given value.  If
 207         <replaceable>value</replaceable> is <literal>DEFAULT</literal>
 208         or, equivalently, <literal>RESET</literal> is used, the
 209         role-specific variable setting is removed, so the role will
 210         inherit the system-wide default setting in new sessions.  Use
 211         <literal>RESET ALL</literal> to clear all role-specific settings.
 212         <literal>SET FROM CURRENT</> saves the session's current value of
 213         the parameter as the role-specific value.
 214         If <literal>IN DATABASE</literal> is specified, the configuration
 215         parameter is set or removed for the given role and database only.
 216        </para>
 217
 218        <para>
 219         Role-specific variable settings take effect only at login;
 220         <xref linkend="sql-set-role"> and
 221         <xref linkend="sql-set-session-authorization">
 222         do not process role-specific variable settings.
 223        </para>
 224
 225        <para>
 226         See <xref linkend="sql-set"> and <xref
 227         linkend="runtime-config"> for more information about allowed
 228         parameter names and values.
 229        </para>
 230       </listitem>
 231      </varlistentry>
 232     </variablelist>
 233  </refsect1>
 234
 235  <refsect1>
 236   <title>Notes</title>
 237
 238   <para>
 239    Use <xref linkend="SQL-CREATEROLE">
 240    to add new roles, and <xref linkend="SQL-DROPROLE"> to remove a role.
 241   </para>
 242
 243   <para>
 244    <command>ALTER ROLE</command> cannot change a role's memberships.
 245    Use <xref linkend="SQL-GRANT"> and
 246    <xref linkend="SQL-REVOKE">
 247    to do that.
 248   </para>
 249
 250   <para>
 251    Caution must be exercised when specifying an unencrypted password
 252    with this command.  The password will be transmitted to the server
 253    in cleartext, and it might also be logged in the client's command
 254    history or the server log.  <xref linkend="app-psql">
 255    contains a command
 256    <command>\password</command> that can be used to change a
 257    role's password without exposing the cleartext password.
 258   </para>
 259
 260   <para>
 261    It is also possible to tie a
 262    session default to a specific database rather than to a role; see
 263    <xref linkend="sql-alterdatabase">.
 264    If there is a conflict, database-role-specific settings override role-specific
 265    ones, which in turn override database-specific ones.
 266   </para>
 267  </refsect1>
 268
 269  <refsect1>
 270   <title>Examples</title>
 271
 272   <para>
 273    Change a role's password:
 274
 275 <programlisting>
 276 ALTER ROLE davide WITH PASSWORD 'hu8jmn3';
 277 </programlisting>
 278   </para>
 279
 280   <para>
 281    Remove a role's password:
 282
 283 <programlisting>
 284 ALTER ROLE davide WITH PASSWORD NULL;
 285 </programlisting>
 286   </para>
 287
 288   <para>
 289    Change a password expiration date, specifying that the password
 290    should expire at midday on 4th May 2015 using
 291    the time zone which is one hour ahead of <acronym>UTC</>:
 292 <programlisting>
 293 ALTER ROLE chris VALID UNTIL 'May 4 12:00:00 2015 +1';
 294 </programlisting>
 295   </para>
 296
 297   <para>
 298    Make a password valid forever:
 299 <programlisting>
 300 ALTER ROLE fred VALID UNTIL 'infinity';
 301 </programlisting>
 302   </para>
 303
 304   <para>
 305    Give a role the ability to create other roles and new databases:
 306
 307 <programlisting>
 308 ALTER ROLE miriam CREATEROLE CREATEDB;
 309 </programlisting>
 310   </para>
 311
 312   <para>
 313    Give a role a non-default setting of the
 314    <xref linkend="guc-maintenance-work-mem"> parameter:
 315
 316 <programlisting>
 317 ALTER ROLE worker_bee SET maintenance_work_mem = 100000;
 318 </programlisting>
 319   </para>
 320
 321   <para>
 322    Give a role a non-default, database-specific setting of the
 323    <xref linkend="guc-client-min-messages"> parameter:
 324
 325 <programlisting>
 326 ALTER ROLE fred IN DATABASE devel SET client_min_messages = DEBUG;
 327 </programlisting></para>
 328  </refsect1>
 329
 330  <refsect1>
 331   <title>Compatibility</title>
 332
 333   <para>
 334    The <command>ALTER ROLE</command> statement is a
 335    <productname>PostgreSQL</productname> extension.
 336   </para>
 337  </refsect1>
 338
 339  <refsect1>
 340   <title>See Also</title>
 341
 342   <simplelist type="inline">
 343    <member><xref linkend="sql-createrole"></member>
 344    <member><xref linkend="sql-droprole"></member>
 345    <member><xref linkend="sql-alterdatabase"></member>
 346    <member><xref linkend="sql-set"></member>
 347   </simplelist>
 348  </refsect1>
 349 </refentry>