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

   1 <!--
   2 $PostgreSQL: pgsql/doc/src/sgml/ref/create_user.sgml,v 1.34 2005/01/04 00:39:53 tgl Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-CREATEUSER">
   7  <refmeta>
   8   <refentrytitle id="sql-createuser-title">CREATE USER</refentrytitle>
   9   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  10  </refmeta>
  11
  12  <refnamediv>
  13   <refname>CREATE USER</refname>
  14   <refpurpose>define a new database user account</refpurpose>
  15  </refnamediv>
  16
  17  <indexterm zone="sql-createuser">
  18   <primary>CREATE USER</primary>
  19  </indexterm>
  20
  21  <refsynopsisdiv>
  22 <synopsis>
  23 CREATE USER <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <replaceable class="PARAMETER">option</replaceable> [ ... ] ]
  24
  25 where <replaceable class="PARAMETER">option</replaceable> can be:
  26
  27       SYSID <replaceable class="PARAMETER">uid</replaceable>
  28     | CREATEDB | NOCREATEDB
  29     | CREATEUSER | NOCREATEUSER
  30     | IN GROUP <replaceable class="PARAMETER">groupname</replaceable> [, ...]
  31     | [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
  32     | VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>'
  33 </synopsis>
  34  </refsynopsisdiv>
  35
  36  <refsect1>
  37   <title>Description</title>
  38
  39   <para>
  40    <command>CREATE USER</command> adds a new user to a
  41    <productname>PostgreSQL</productname> database cluster.  Refer to
  42    <xref linkend="user-manag"> and <xref
  43    linkend="client-authentication"> for information about managing
  44    users and authentication.  You must be a database superuser to use
  45    this command.
  46   </para>
  47  </refsect1>
  48
  49  <refsect1>
  50   <title>Parameters</title>
  51
  52     <variablelist>
  53      <varlistentry>
  54       <term><replaceable class="parameter">name</replaceable></term>
  55       <listitem>
  56        <para>
  57         The name of the new user.
  58        </para>
  59       </listitem>
  60      </varlistentry>
  61
  62      <varlistentry>
  63       <term><replaceable class="parameter">uid</replaceable></term>
  64       <listitem>
  65        <para>
  66         The <literal>SYSID</literal> clause can be used to choose the
  67         <productname>PostgreSQL</productname> user ID of the new user.
  68         This is normally not necessary, but may
  69         be useful if you need to recreate the owner of an orphaned
  70         object.
  71        </para>
  72        <para>
  73         If this is not specified, the highest assigned user ID plus one
  74         (with a minimum of 100) will be used as default.
  75        </para>
  76       </listitem>
  77      </varlistentry>
  78
  79      <varlistentry>
  80       <term><literal>CREATEDB</></term>
  81       <term><literal>NOCREATEDB</></term>
  82       <listitem>
  83        <para>
  84         These clauses define a user's ability to create databases.  If
  85         <literal>CREATEDB</literal> is specified, the user being
  86         defined will be allowed to create his own databases. Using
  87         <literal>NOCREATEDB</literal> will deny a user the ability to
  88         create databases. If not specified,
  89         <literal>NOCREATEDB</literal> is the default.
  90        </para>
  91       </listitem>
  92      </varlistentry>
  93
  94      <varlistentry>
  95       <term><literal>CREATEUSER</literal></term>
  96       <term><literal>NOCREATEUSER</literal></term>
  97       <listitem>
  98        <para>
  99         These clauses determine whether a user will be permitted to
 100         create new users himself. <literal>CREATEUSER</literal> will also make
 101         the user a superuser, who can override all access restrictions.
 102         If not specified,
 103         <literal>NOCREATEUSER</literal> is the default.
 104        </para>
 105       </listitem>
 106      </varlistentry>
 107
 108      <varlistentry>
 109       <term><replaceable class="parameter">groupname</replaceable></term>
 110       <listitem>
 111        <para>
 112         A name of an existing group into which to insert the user as a new
 113         member. Multiple group names may be listed.
 114        </para>
 115       </listitem>
 116      </varlistentry>
 117
 118      <varlistentry>
 119       <term><replaceable class="parameter">password</replaceable></term>
 120       <listitem>
 121        <para>
 122         Sets the user's password. If you do not plan to use password
 123         authentication you can omit this option, but then the user
 124         won't be able to connect if you decide to switch to password
 125         authentication.  The password can be set or changed later,
 126         using <xref linkend="SQL-ALTERUSER"
 127         endterm="SQL-ALTERUSER-title">.
 128        </para>
 129       </listitem>
 130      </varlistentry>
 131
 132      <varlistentry>
 133       <term><literal>ENCRYPTED</></term>
 134       <term><literal>UNENCRYPTED</></term>
 135       <listitem>
 136        <para>
 137         These key words control whether the password is stored
 138         encrypted in the system catalogs.  (If neither is specified,
 139         the default behavior is determined by the configuration
 140         parameter <xref linkend="guc-password-encryption">.)  If the
 141         presented password string is already in MD5-encrypted format,
 142         then it is stored encrypted as-is, regardless of whether
 143         <literal>ENCRYPTED</> or <literal>UNENCRYPTED</> is specified
 144         (since the system cannot decrypt the specified encrypted
 145         password string).  This allows reloading of encrypted
 146         passwords during dump/restore.
 147        </para>
 148
 149        <para>
 150         Note that older clients may lack support for the MD5
 151         authentication mechanism that is needed to work with passwords
 152         that are stored encrypted.
 153        </para>
 154       </listitem>
 155      </varlistentry>
 156
 157      <varlistentry>
 158       <term><replaceable class="parameter">abstime</replaceable></term>
 159       <listitem>
 160        <para>
 161         The <literal>VALID UNTIL</literal> clause sets an absolute
 162         time after which the user's password is no longer valid.  If
 163         this clause is omitted the password will be valid for all time.
 164        </para>
 165       </listitem>
 166      </varlistentry>
 167     </variablelist>
 168  </refsect1>
 169
 170  <refsect1>
 171   <title>Notes</title>
 172
 173   <para>
 174    Use <xref linkend="SQL-ALTERUSER" endterm="SQL-ALTERUSER-title"> to
 175    change the attributes of a user, and <xref linkend="SQL-DROPUSER"
 176    endterm="SQL-DROPUSER-title"> to remove a user.  Use <xref
 177    linkend="SQL-ALTERGROUP" endterm="SQL-ALTERGROUP-title"> to add the
 178    user to groups or remove the user from groups.
 179   </para>
 180
 181   <para>
 182    <productname>PostgreSQL</productname> includes a program <xref
 183    linkend="APP-CREATEUSER" endterm="APP-CREATEUSER-title"> that has
 184    the same functionality as <command>CREATE USER</command> (in fact, it calls this
 185    command) but can be run from the command shell.
 186   </para>
 187
 188   <para>
 189    The <literal>VALID UNTIL</> clause defines an expiration time for a
 190    password only, not for the user account <foreignphrase>per se</>.  In
 191    particular, the expiration time is not enforced when logging in using
 192    a non-password-based authentication method.
 193   </para>
 194  </refsect1>
 195
 196  <refsect1>
 197   <title>Examples</title>
 198
 199   <para>
 200    Create a user with no password:
 201 <programlisting>
 202 CREATE USER jonathan;
 203 </programlisting>
 204   </para>
 205
 206   <para>
 207    Create a user with a password:
 208 <programlisting>
 209 CREATE USER davide WITH PASSWORD 'jw8s0F4';
 210 </programlisting>
 211   </para>
 212
 213   <para>
 214    Create a user with a password that is valid until the end of 2004.
 215    After one second has ticked in 2005, the password is no longer
 216    valid.
 217
 218 <programlisting>
 219 CREATE USER miriam WITH PASSWORD 'jw8s0F4' VALID UNTIL '2005-01-01';
 220 </programlisting>
 221   </para>
 222
 223   <para>
 224    Create an account where the user can create databases:
 225 <programlisting>
 226 CREATE USER manuel WITH PASSWORD 'jw8s0F4' CREATEDB;
 227 </programlisting>
 228   </para>
 229  </refsect1>
 230
 231  <refsect1>
 232   <title>Compatibility</title>
 233
 234   <para>
 235    The <command>CREATE USER</command> statement is a
 236    <productname>PostgreSQL</productname> extension.  The SQL standard
 237    leaves the definition of users to the implementation.
 238   </para>
 239  </refsect1>
 240
 241  <refsect1>
 242   <title>See Also</title>
 243
 244   <simplelist type="inline">
 245    <member><xref linkend="sql-alteruser" endterm="sql-alteruser-title"></member>
 246    <member><xref linkend="sql-dropuser" endterm="sql-dropuser-title"></member>
 247    <member><xref linkend="app-createuser"></member>
 248   </simplelist>
 249  </refsect1>
 250 </refentry>
 251
 252 <!-- Keep this comment at the end of the file
 253 Local variables:
 254 mode: sgml
 255 sgml-omittag:nil
 256 sgml-shorttag:t
 257 sgml-minimize-attributes:nil
 258 sgml-always-quote-attributes:t
 259 sgml-indent-step:1
 260 sgml-indent-data:t
 261 sgml-parent-document:nil
 262 sgml-default-dtd-file:"../reference.ced"
 263 sgml-exposed-tags:nil
 264 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 265 sgml-local-ecat-files:nil
 266 End:
 267 -->