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

   1 <!--
   2 $PostgreSQL: pgsql/doc/src/sgml/ref/alter_role.sgml,v 1.2 2005/07/31 17:19:17 tgl Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-ALTERROLE">
   7  <refmeta>
   8   <refentrytitle id="sql-alterrole-title">ALTER ROLE</refentrytitle>
   9   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  10  </refmeta>
  11
  12  <refnamediv>
  13   <refname>ALTER ROLE</refname>
  14   <refpurpose>change a database role</refpurpose>
  15  </refnamediv>
  16
  17  <indexterm zone="sql-alterrole">
  18   <primary>ALTER ROLE</primary>
  19  </indexterm>
  20
  21  <refsynopsisdiv>
  22 <synopsis>
  23 ALTER ROLE <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <replaceable class="PARAMETER">option</replaceable> [ ... ] ]
  24
  25 where <replaceable class="PARAMETER">option</replaceable> can be:
  26
  27       SUPERUSER | NOSUPERUSER
  28     | CREATEDB | NOCREATEDB
  29     | CREATEROLE | NOCREATEROLE
  30     | CREATEUSER | NOCREATEUSER
  31     | INHERIT | NOINHERIT
  32     | LOGIN | NOLOGIN
  33     | CONNECTION LIMIT <replaceable class="PARAMETER">connlimit</replaceable>
  34     | [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
  35     | VALID UNTIL '<replaceable class="PARAMETER">timestamp</replaceable>'
  36
  37 ALTER ROLE <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>newname</replaceable>
  38
  39 ALTER ROLE <replaceable class="PARAMETER">name</replaceable> SET <replaceable>parameter</replaceable> { TO | = } { <replaceable>value</replaceable> | DEFAULT }
  40 ALTER ROLE <replaceable class="PARAMETER">name</replaceable> RESET <replaceable>parameter</replaceable>
  41 </synopsis>
  42  </refsynopsisdiv>
  43
  44  <refsect1>
  45   <title>Description</title>
  46
  47   <para>
  48    <command>ALTER ROLE</command> changes the attributes of a
  49    <productname>PostgreSQL</productname> role.
  50   </para>
  51
  52   <para>
  53    The first variant of this command listed in the synopsis can change
  54    many of the role attributes that can be specified in
  55    <xref linkend="sql-createrole" endterm="sql-createrole-title">,
  56    which see for details.  (All the possible attributes are covered,
  57    except that there are no options for adding or removing memberships; use
  58    <xref linkend="SQL-GRANT" endterm="SQL-GRANT-title"> and
  59    <xref linkend="SQL-REVOKE" endterm="SQL-REVOKE-title"> for that.)
  60    Attributes not mentioned in the command retain their previous settings.
  61    Database superusers can change any of these settings for any role.
  62    Roles having <literal>CREATEROLE</> privilege can change any of these
  63    settings, but only for non-superuser roles.
  64    Ordinary roles can only change their own password.
  65   </para>
  66
  67   <para>
  68    The second variant changes the name of the role.
  69    Database superusers can rename any role.
  70    Roles having <literal>CREATEROLE</> privilege can rename non-superuser
  71    roles.
  72    The current session user cannot be renamed.
  73    (Connect as a different user if you need to do that.)
  74    Because <literal>MD5</>-encrypted passwords use the role name as
  75    cryptographic salt, renaming a role clears its password if the
  76    password is <literal>MD5</>-encrypted.
  77   </para>
  78
  79   <para>
  80    The third and the fourth variant change a role's session default for
  81    a specified configuration variable.  Whenever the role subsequently
  82    starts a new session, the specified value becomes the session default,
  83    overriding whatever setting is present in <filename>postgresql.conf</>
  84    or has been received from the <command>postmaster</command> command line.
  85    (For a role without <literal>LOGIN</> privilege, session defaults have
  86    no effect.)
  87    Ordinary roles can change their own session defaults.
  88    Superusers can change anyone's session defaults.
  89    Roles having <literal>CREATEROLE</> privilege can change defaults for
  90    non-superuser roles.
  91    Certain variables cannot be set this way, or can only be
  92    set if a superuser issues the command.
  93   </para>
  94  </refsect1>
  95
  96  <refsect1>
  97   <title>Parameters</title>
  98
  99     <variablelist>
 100      <varlistentry>
 101       <term><replaceable class="PARAMETER">name</replaceable></term>
 102       <listitem>
 103        <para>
 104         The name of the role whose attributes are to be altered.
 105        </para>
 106       </listitem>
 107      </varlistentry>
 108
 109      <varlistentry>
 110       <term><literal>SUPERUSER</literal></term>
 111       <term><literal>NOSUPERUSER</literal></term>
 112       <term><literal>CREATEDB</></term>
 113       <term><literal>NOCREATEDB</></term>
 114       <term><literal>CREATEROLE</literal></term>
 115       <term><literal>NOCREATEROLE</literal></term>
 116       <term><literal>CREATEUSER</literal></term>
 117       <term><literal>NOCREATEUSER</literal></term>
 118       <term><literal>INHERIT</literal></term>
 119       <term><literal>NOINHERIT</literal></term>
 120       <term><literal>LOGIN</literal></term>
 121       <term><literal>NOLOGIN</literal></term>
 122       <term><literal>CONNECTION LIMIT</literal> <replaceable class="parameter">connlimit</replaceable></term>
 123       <term><literal>PASSWORD</> <replaceable class="parameter">password</replaceable></term>
 124       <term><literal>ENCRYPTED</></term>
 125       <term><literal>UNENCRYPTED</></term>
 126       <term><literal>VALID UNTIL</literal> '<replaceable class="parameter">timestamp</replaceable>'</term>
 127       <listitem>
 128        <para>
 129         These clauses alter attributes originally set by
 130         <xref linkend="SQL-CREATEROLE" endterm="SQL-CREATEROLE-title">,
 131         which see for more information.
 132        </para>
 133       </listitem>
 134      </varlistentry>
 135
 136      <varlistentry>
 137       <term><replaceable>newname</replaceable></term>
 138       <listitem>
 139        <para>
 140         The new name of the role.
 141        </para>
 142       </listitem>
 143      </varlistentry>
 144
 145      <varlistentry>
 146       <term><replaceable>parameter</replaceable></term>
 147       <term><replaceable>value</replaceable></term>
 148       <listitem>
 149        <para>
 150         Set this role's session default for the specified configuration
 151         parameter to the given value.  If
 152         <replaceable>value</replaceable> is <literal>DEFAULT</literal>
 153         or, equivalently, <literal>RESET</literal> is used, the
 154         role-specific variable setting is removed, so the role will
 155         inherit the system-wide default setting in new sessions.  Use
 156         <literal>RESET ALL</literal> to clear all role-specific settings.
 157        </para>
 158
 159        <para>
 160         See <xref linkend="sql-set" endterm="sql-set-title"> and <xref
 161         linkend="runtime-config"> for more information about allowed
 162         parameter names and values.
 163        </para>
 164       </listitem>
 165      </varlistentry>
 166     </variablelist>
 167  </refsect1>
 168
 169  <refsect1>
 170   <title>Notes</title>
 171
 172   <para>
 173    Use <xref linkend="SQL-CREATEROLE" endterm="SQL-CREATEROLE-title">
 174    to add new roles, and <xref linkend="SQL-DROPROLE"
 175    endterm="SQL-DROPROLE-title"> to remove a role.
 176   </para>
 177
 178   <para>
 179    <command>ALTER ROLE</command> cannot change a role's memberships.
 180    Use <xref linkend="SQL-GRANT" endterm="SQL-GRANT-title"> and
 181    <xref linkend="SQL-REVOKE" endterm="SQL-REVOKE-title">
 182    to do that.
 183   </para>
 184
 185   <para>
 186    It is also possible to tie a
 187    session default to a specific database rather than to a role; see
 188    <xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title">.
 189    Role-specific settings override database-specific
 190    ones if there is a conflict.
 191   </para>
 192  </refsect1>
 193
 194  <refsect1>
 195   <title>Examples</title>
 196
 197   <para>
 198    Change a role's password:
 199
 200 <programlisting>
 201 ALTER ROLE davide WITH PASSWORD 'hu8jmn3';
 202 </programlisting>
 203   </para>
 204
 205   <para>
 206    Change a password expiration date, specifying that the password
 207    should expire at midday on 4th May 2015 using
 208    the time zone which is one hour ahead of <acronym>UTC</>:
 209 <programlisting>
 210 ALTER ROLE chris VALID UNTIL 'May 4 12:00:00 2015 +1';
 211 </programlisting>
 212   </para>
 213
 214   <para>
 215    Make a password valid forever:
 216 <programlisting>
 217 ALTER ROLE fred VALID UNTIL 'infinity';
 218 </programlisting>
 219   </para>
 220
 221   <para>
 222    Give a role the ability to create other roles and new databases:
 223
 224 <programlisting>
 225 ALTER ROLE miriam CREATEROLE CREATEDB;
 226 </programlisting>
 227   </para>
 228
 229   <para>
 230    Give a role a non-default setting of the
 231    <xref linkend="guc-maintenance-work-mem"> parameter:
 232
 233 <programlisting>
 234 ALTER ROLE worker_bee SET maintenance_work_mem = 100000;
 235 </programlisting>
 236   </para>
 237  </refsect1>
 238
 239  <refsect1>
 240   <title>Compatibility</title>
 241
 242   <para>
 243    The <command>ALTER ROLE</command> statement is a
 244    <productname>PostgreSQL</productname> extension.
 245   </para>
 246  </refsect1>
 247
 248  <refsect1>
 249   <title>See Also</title>
 250
 251   <simplelist type="inline">
 252    <member><xref linkend="sql-createrole" endterm="sql-createrole-title"></member>
 253    <member><xref linkend="sql-droprole" endterm="sql-droprole-title"></member>
 254    <member><xref linkend="sql-set" endterm="sql-set-title"></member>
 255   </simplelist>
 256  </refsect1>
 257 </refentry>
 258
 259 <!-- Keep this comment at the end of the file
 260 Local variables:
 261 mode: sgml
 262 sgml-omittag:nil
 263 sgml-shorttag:t
 264 sgml-minimize-attributes:nil
 265 sgml-always-quote-attributes:t
 266 sgml-indent-step:1
 267 sgml-indent-data:t
 268 sgml-parent-document:nil
 269 sgml-default-dtd-file:"../reference.ced"
 270 sgml-exposed-tags:nil
 271 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 272 sgml-local-ecat-files:nil
 273 End:
 274 -->