doc/src/sgml/ref/createuser.sgml

   1 <!--
   2 doc/src/sgml/ref/createuser.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="app-createuser">
   7  <indexterm zone="app-createuser">
   8   <primary>createuser</primary>
   9  </indexterm>
  10
  11  <refmeta>
  12   <refentrytitle><application>createuser</application></refentrytitle>
  13   <manvolnum>1</manvolnum>
  14   <refmiscinfo>Application</refmiscinfo>
  15  </refmeta>
  16
  17  <refnamediv>
  18   <refname>createuser</refname>
  19   <refpurpose>define a new <productname>PostgreSQL</productname> user account</refpurpose>
  20  </refnamediv>
  21
  22  <refsynopsisdiv>
  23   <cmdsynopsis>
  24    <command>createuser</command>
  25    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
  26    <arg rep="repeat"><replaceable>option</replaceable></arg>
  27    <arg choice="opt"><replaceable>username</replaceable></arg>
  28   </cmdsynopsis>
  29  </refsynopsisdiv>
  30
  31
  32  <refsect1>
  33   <title>Description</title>
  34   <para>
  35    <application>createuser</application> creates a
  36    new <productname>PostgreSQL</productname> user (or more precisely, a role).
  37    Only superusers and users with <literal>CREATEROLE</literal> privilege can create
  38    new users, so <application>createuser</application> must be
  39    invoked by someone who can connect as a superuser or a user with
  40    <literal>CREATEROLE</literal> privilege.
  41   </para>
  42
  43   <para>
  44    If you wish to create a role with the <literal>SUPERUSER</literal>,
  45    <literal>REPLICATION</literal>, or <literal>BYPASSRLS</literal> privilege,
  46    you must connect as a superuser, not merely with
  47    <literal>CREATEROLE</literal> privilege.
  48    Being a superuser implies the ability to bypass all access permission
  49    checks within the database, so superuser access should not be granted
  50    lightly. <literal>CREATEROLE</literal> also conveys
  51    <link linkend="role-creation">very extensive privileges</link>.
  52   </para>
  53
  54   <para>
  55    <application>createuser</application> is a wrapper around the
  56    <acronym>SQL</acronym> command <link linkend="sql-createrole"><command>CREATE ROLE</command></link>.
  57    There is no effective difference between creating users via
  58    this utility and via other methods for accessing the server.
  59   </para>
  60
  61  </refsect1>
  62
  63
  64  <refsect1>
  65   <title>Options</title>
  66
  67   <para>
  68    <application>createuser</application> accepts the following command-line arguments:
  69
  70     <variablelist>
  71      <varlistentry>
  72       <term><replaceable class="parameter">username</replaceable></term>
  73       <listitem>
  74        <para>
  75         Specifies the name of the <productname>PostgreSQL</productname> user
  76         to be created.
  77         This name must be different from all existing roles in this
  78         <productname>PostgreSQL</productname> installation.
  79        </para>
  80       </listitem>
  81      </varlistentry>
  82
  83      <varlistentry>
  84       <term><option>-a <replaceable class="parameter">role</replaceable></option></term>
  85       <term><option>--with-admin=<replaceable class="parameter">role</replaceable></option></term>
  86       <listitem>
  87        <para>
  88         Specifies an existing role that will be automatically added as a member of the new
  89         role with admin option, giving it the right to grant membership in the
  90         new role to others.  Multiple existing roles can be specified by
  91         writing multiple <option>-a</option> switches.
  92        </para>
  93       </listitem>
  94      </varlistentry>
  95
  96      <varlistentry>
  97       <term><option>-c <replaceable class="parameter">number</replaceable></option></term>
  98       <term><option>--connection-limit=<replaceable class="parameter">number</replaceable></option></term>
  99       <listitem>
 100        <para>
 101         Set a maximum number of connections for the new user.
 102         The default is to set no limit.
 103        </para>
 104       </listitem>
 105      </varlistentry>
 106
 107      <varlistentry>
 108       <term><option>-d</option></term>
 109       <term><option>--createdb</option></term>
 110       <listitem>
 111        <para>
 112         The new user will be allowed to create databases.
 113        </para>
 114       </listitem>
 115      </varlistentry>
 116
 117      <varlistentry>
 118       <term><option>-D</option></term>
 119       <term><option>--no-createdb</option></term>
 120       <listitem>
 121        <para>
 122         The new user will not be allowed to create databases.  This is the
 123         default.
 124        </para>
 125       </listitem>
 126      </varlistentry>
 127
 128      <varlistentry>
 129       <term><option>-e</option></term>
 130       <term><option>--echo</option></term>
 131       <listitem>
 132        <para>
 133         Echo the commands that <application>createuser</application> generates
 134         and sends to the server.
 135        </para>
 136       </listitem>
 137      </varlistentry>
 138
 139      <varlistentry>
 140       <term><option>-E</option></term>
 141       <term><option>--encrypted</option></term>
 142       <listitem>
 143        <para>
 144         This option is obsolete but still accepted for backward
 145         compatibility.
 146        </para>
 147       </listitem>
 148      </varlistentry>
 149
 150      <varlistentry>
 151       <term><option>-g <replaceable class="parameter">role</replaceable></option></term>
 152       <term><option>--member-of=<replaceable class="parameter">role</replaceable></option></term>
 153       <term><option>--role=<replaceable class="parameter">role</replaceable></option> (deprecated)</term>
 154       <listitem>
 155        <para>
 156         Specifies the new role should be automatically added as a member
 157         of the specified existing role. Multiple existing roles can be
 158         specified by writing multiple <option>-g</option> switches.
 159        </para>
 160       </listitem>
 161      </varlistentry>
 162
 163      <varlistentry>
 164       <term><option>-i</option></term>
 165       <term><option>--inherit</option></term>
 166       <listitem>
 167        <para>
 168         The new role will automatically inherit privileges of roles
 169         it is a member of.
 170         This is the default.
 171        </para>
 172       </listitem>
 173      </varlistentry>
 174
 175      <varlistentry>
 176       <term><option>-I</option></term>
 177       <term><option>--no-inherit</option></term>
 178       <listitem>
 179        <para>
 180         The new role will not automatically inherit privileges of roles
 181         it is a member of.
 182        </para>
 183       </listitem>
 184      </varlistentry>
 185
 186      <varlistentry>
 187       <term><option>--interactive</option></term>
 188       <listitem>
 189        <para>
 190         Prompt for the user name if none is specified on the command line, and
 191         also prompt for whichever of the options
 192         <option>-d</option>/<option>-D</option>,
 193         <option>-r</option>/<option>-R</option>,
 194         <option>-s</option>/<option>-S</option> is not specified on the command
 195         line.  (This was the default behavior up to PostgreSQL 9.1.)
 196        </para>
 197       </listitem>
 198      </varlistentry>
 199
 200      <varlistentry>
 201       <term><option>-l</option></term>
 202       <term><option>--login</option></term>
 203       <listitem>
 204        <para>
 205         The new user will be allowed to log in (that is, the user name
 206         can be used as the initial session user identifier).
 207         This is the default.
 208        </para>
 209       </listitem>
 210      </varlistentry>
 211
 212      <varlistentry>
 213       <term><option>-L</option></term>
 214       <term><option>--no-login</option></term>
 215       <listitem>
 216        <para>
 217         The new user will not be allowed to log in.
 218         (A role without login privilege is still useful as a means of
 219         managing database permissions.)
 220        </para>
 221       </listitem>
 222      </varlistentry>
 223
 224      <varlistentry>
 225       <term><option>-m <replaceable class="parameter">role</replaceable></option></term>
 226       <term><option>--with-member=<replaceable class="parameter">role</replaceable></option></term>
 227       <listitem>
 228        <para>
 229         Specifies an existing role that will be automatically
 230         added as a member of the new role. Multiple existing roles can
 231         be specified by writing multiple <option>-m</option> switches.
 232        </para>
 233       </listitem>
 234      </varlistentry>
 235
 236      <varlistentry>
 237       <term><option>-P</option></term>
 238       <term><option>--pwprompt</option></term>
 239       <listitem>
 240        <para>
 241        If given, <application>createuser</application> will issue a prompt for
 242        the password of the new user. This is not necessary if you do not plan
 243        on using password authentication.
 244        </para>
 245       </listitem>
 246      </varlistentry>
 247
 248      <varlistentry>
 249       <term><option>-r</option></term>
 250       <term><option>--createrole</option></term>
 251       <listitem>
 252        <para>
 253         The new user will be allowed to create, alter, drop, comment on,
 254         change the security label for other roles; that is,
 255         this user will have <literal>CREATEROLE</literal> privilege.
 256         See <xref linkend="role-creation"/> for more details about what
 257         capabilities are conferred by this privilege.
 258        </para>
 259       </listitem>
 260      </varlistentry>
 261
 262      <varlistentry>
 263       <term><option>-R</option></term>
 264       <term><option>--no-createrole</option></term>
 265       <listitem>
 266        <para>
 267         The new user will not be allowed to create new roles.  This is the
 268         default.
 269        </para>
 270       </listitem>
 271      </varlistentry>
 272
 273      <varlistentry>
 274       <term><option>-s</option></term>
 275       <term><option>--superuser</option></term>
 276       <listitem>
 277        <para>
 278         The new user will be a superuser.
 279        </para>
 280       </listitem>
 281      </varlistentry>
 282
 283      <varlistentry>
 284       <term><option>-S</option></term>
 285       <term><option>--no-superuser</option></term>
 286       <listitem>
 287        <para>
 288         The new user will not be a superuser.  This is the default.
 289        </para>
 290       </listitem>
 291      </varlistentry>
 292
 293      <varlistentry>
 294       <term><option>-v <replaceable class="parameter">timestamp</replaceable></option></term>
 295       <term><option>--valid-until=<replaceable class="parameter">timestamp</replaceable></option></term>
 296       <listitem>
 297        <para>
 298         Set a date and time after which the role's password is no longer valid.
 299         The default is to set no password expiry date.
 300        </para>
 301       </listitem>
 302      </varlistentry>
 303
 304      <varlistentry>
 305        <term><option>-V</option></term>
 306        <term><option>--version</option></term>
 307        <listitem>
 308        <para>
 309        Print the <application>createuser</application> version and exit.
 310        </para>
 311        </listitem>
 312      </varlistentry>
 313
 314      <varlistentry>
 315       <term><option>--bypassrls</option></term>
 316       <listitem>
 317        <para>
 318         The new user will bypass every row-level security (RLS) policy.
 319        </para>
 320       </listitem>
 321      </varlistentry>
 322
 323      <varlistentry>
 324       <term><option>--no-bypassrls</option></term>
 325       <listitem>
 326        <para>
 327         The new user will not bypass row-level security (RLS) policies.  This is
 328         the default.
 329        </para>
 330       </listitem>
 331      </varlistentry>
 332
 333      <varlistentry>
 334       <term><option>--replication</option></term>
 335       <listitem>
 336        <para>
 337         The new user will have the <literal>REPLICATION</literal> privilege,
 338         which is described more fully in the documentation for <xref
 339         linkend="sql-createrole"/>.
 340        </para>
 341       </listitem>
 342      </varlistentry>
 343
 344      <varlistentry>
 345       <term><option>--no-replication</option></term>
 346       <listitem>
 347        <para>
 348         The new user will not have the <literal>REPLICATION</literal>
 349         privilege, which is described more fully in the documentation for <xref
 350         linkend="sql-createrole"/>.  This is the default.
 351        </para>
 352       </listitem>
 353      </varlistentry>
 354
 355      <varlistentry>
 356        <term><option>-?</option></term>
 357        <term><option>--help</option></term>
 358        <listitem>
 359        <para>
 360        Show help about <application>createuser</application> command line
 361        arguments, and exit.
 362        </para>
 363        </listitem>
 364      </varlistentry>
 365
 366     </variablelist>
 367   </para>
 368
 369   <para>
 370    <application>createuser</application> also accepts the following
 371    command-line arguments for connection parameters:
 372
 373    <variablelist>
 374      <varlistentry>
 375       <term><option>-h <replaceable class="parameter">host</replaceable></option></term>
 376       <term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
 377       <listitem>
 378        <para>
 379         Specifies the host name of the machine on which the
 380         server
 381         is running.  If the value begins with a slash, it is used
 382         as the directory for the Unix domain socket.
 383        </para>
 384       </listitem>
 385      </varlistentry>
 386
 387      <varlistentry>
 388       <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
 389       <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
 390       <listitem>
 391        <para>
 392         Specifies the TCP port or local Unix domain socket file
 393         extension on which the server
 394         is listening for connections.
 395        </para>
 396       </listitem>
 397      </varlistentry>
 398
 399      <varlistentry>
 400       <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
 401       <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
 402       <listitem>
 403        <para>
 404         User name to connect as (not the user name to create).
 405        </para>
 406       </listitem>
 407      </varlistentry>
 408
 409      <varlistentry>
 410       <term><option>-w</option></term>
 411       <term><option>--no-password</option></term>
 412       <listitem>
 413        <para>
 414         Never issue a password prompt.  If the server requires
 415         password authentication and a password is not available by
 416         other means such as a <filename>.pgpass</filename> file, the
 417         connection attempt will fail.  This option can be useful in
 418         batch jobs and scripts where no user is present to enter a
 419         password.
 420        </para>
 421       </listitem>
 422      </varlistentry>
 423
 424      <varlistentry>
 425       <term><option>-W</option></term>
 426       <term><option>--password</option></term>
 427       <listitem>
 428        <para>
 429         Force <application>createuser</application> to prompt for a
 430         password (for connecting to the server, not for the
 431         password of the new user).
 432        </para>
 433
 434        <para>
 435         This option is never essential, since
 436         <application>createuser</application> will automatically prompt
 437         for a password if the server demands password authentication.
 438         However, <application>createuser</application> will waste a
 439         connection attempt finding out that the server wants a password.
 440         In some cases it is worth typing <option>-W</option> to avoid the extra
 441         connection attempt.
 442        </para>
 443       </listitem>
 444      </varlistentry>
 445    </variablelist>
 446   </para>
 447  </refsect1>
 448
 449
 450  <refsect1>
 451   <title>Environment</title>
 452
 453   <variablelist>
 454    <varlistentry>
 455     <term><envar>PGHOST</envar></term>
 456     <term><envar>PGPORT</envar></term>
 457     <term><envar>PGUSER</envar></term>
 458
 459     <listitem>
 460      <para>
 461       Default connection parameters
 462      </para>
 463     </listitem>
 464    </varlistentry>
 465
 466    <varlistentry>
 467     <term><envar>PG_COLOR</envar></term>
 468     <listitem>
 469      <para>
 470       Specifies whether to use color in diagnostic messages. Possible values
 471       are <literal>always</literal>, <literal>auto</literal> and
 472       <literal>never</literal>.
 473      </para>
 474     </listitem>
 475    </varlistentry>
 476   </variablelist>
 477
 478   <para>
 479    This utility, like most other <productname>PostgreSQL</productname> utilities,
 480    also uses the environment variables supported by <application>libpq</application>
 481    (see <xref linkend="libpq-envars"/>).
 482   </para>
 483
 484  </refsect1>
 485
 486
 487  <refsect1>
 488   <title>Diagnostics</title>
 489
 490   <para>
 491    In case of difficulty, see <xref linkend="sql-createrole"/>
 492    and <xref linkend="app-psql"/> for
 493    discussions of potential problems and error messages.
 494    The database server must be running at the
 495    targeted host.  Also, any default connection settings and environment
 496    variables used by the <application>libpq</application> front-end
 497    library will apply.
 498   </para>
 499
 500  </refsect1>
 501
 502
 503  <refsect1>
 504   <title>Examples</title>
 505
 506    <para>
 507     To create a user <literal>joe</literal> on the default database
 508     server:
 509 <screen>
 510 <prompt>$ </prompt><userinput>createuser joe</userinput>
 511 </screen>
 512    </para>
 513
 514    <para>
 515     To create a user <literal>joe</literal> on the default database
 516     server with prompting for some additional attributes:
 517 <screen>
 518 <prompt>$ </prompt><userinput>createuser --interactive joe</userinput>
 519 <computeroutput>Shall the new role be a superuser? (y/n) </computeroutput><userinput>n</userinput>
 520 <computeroutput>Shall the new role be allowed to create databases? (y/n) </computeroutput><userinput>n</userinput>
 521 <computeroutput>Shall the new role be allowed to create more new roles? (y/n) </computeroutput><userinput>n</userinput>
 522 </screen>
 523    </para>
 524
 525    <para>
 526     To create the same user <literal>joe</literal> using the
 527     server on host <literal>eden</literal>, port 5000, with attributes explicitly specified,
 528     taking a look at the underlying command:
 529 <screen>
 530 <prompt>$ </prompt><userinput>createuser -h eden -p 5000 -S -D -R -e joe</userinput>
 531 <computeroutput>CREATE ROLE joe NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT LOGIN;</computeroutput>
 532 </screen>
 533    </para>
 534
 535    <para>
 536     To create the user <literal>joe</literal> as a superuser,
 537     and assign a password immediately:
 538 <screen>
 539 <prompt>$ </prompt><userinput>createuser -P -s -e joe</userinput>
 540 <computeroutput>Enter password for new role: </computeroutput><userinput>xyzzy</userinput>
 541 <computeroutput>Enter it again: </computeroutput><userinput>xyzzy</userinput>
 542 <computeroutput>CREATE ROLE joe PASSWORD 'md5b5f5ba1a423792b526f799ae4eb3d59e' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;</computeroutput>
 543 </screen>
 544     In the above example, the new password isn't actually echoed when typed,
 545     but we show what was typed for clarity.  As you see, the password is
 546     encrypted before it is sent to the client.
 547    </para>
 548  </refsect1>
 549
 550
 551  <refsect1>
 552   <title>See Also</title>
 553
 554   <simplelist type="inline">
 555    <member><xref linkend="app-dropuser"/></member>
 556    <member><xref linkend="sql-createrole"/></member>
 557    <member><xref linkend="guc-createrole-self-grant"/></member>
 558   </simplelist>
 559  </refsect1>
 560
 561 </refentry>