<!--
doc/src/sgml/ref/createuser.sgml
PostgreSQL documentation
-->

<refentry id="app-createuser">
 <indexterm zone="app-createuser">
  <primary>createuser</primary>
 </indexterm>

 <refmeta>
  <refentrytitle><application>createuser</application></refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>createuser</refname>
  <refpurpose>define a new <productname>PostgreSQL</productname> user account</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>createuser</command>
   <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
   <arg rep="repeat"><replaceable>option</replaceable></arg>
   <arg choice="opt"><replaceable>username</replaceable></arg>
  </cmdsynopsis>
 </refsynopsisdiv>


 <refsect1>
  <title>Description</title>
  <para>
   <application>createuser</application> creates a
   new <productname>PostgreSQL</productname> user (or more precisely, a role).
   Only superusers and users with <literal>CREATEROLE</literal> privilege can create
   new users, so <application>createuser</application> must be
   invoked by someone who can connect as a superuser or a user with
   <literal>CREATEROLE</literal> privilege.
  </para>

  <para>
   If you wish to create a role with the <literal>SUPERUSER</literal>,
   <literal>REPLICATION</literal>, or <literal>BYPASSRLS</literal> privilege,
   you must connect as a superuser, not merely with
   <literal>CREATEROLE</literal> privilege.
   Being a superuser implies the ability to bypass all access permission
   checks within the database, so superuser access should not be granted
   lightly. <literal>CREATEROLE</literal> also conveys
   <link linkend="role-creation">very extensive privileges</link>.
  </para>

  <para>
   <application>createuser</application> is a wrapper around the
   <acronym>SQL</acronym> command <link linkend="sql-createrole"><command>CREATE ROLE</command></link>.
   There is no effective difference between creating users via
   this utility and via other methods for accessing the server.
  </para>

 </refsect1>


 <refsect1>
  <title>Options</title>

  <para>
   <application>createuser</application> accepts the following command-line arguments:

    <variablelist>
     <varlistentry>
      <term><replaceable class="parameter">username</replaceable></term>
      <listitem>
       <para>
        Specifies the name of the <productname>PostgreSQL</productname> user
        to be created.
        This name must be different from all existing roles in this
        <productname>PostgreSQL</productname> installation.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-a <replaceable class="parameter">role</replaceable></option></term>
      <term><option>--with-admin=<replaceable class="parameter">role</replaceable></option></term>
      <listitem>
       <para>
        Specifies an existing role that will be automatically added as a member of the new
        role with admin option, giving it the right to grant membership in the
        new role to others.  Multiple existing roles can be specified by
        writing multiple <option>-a</option> switches.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-c <replaceable class="parameter">number</replaceable></option></term>
      <term><option>--connection-limit=<replaceable class="parameter">number</replaceable></option></term>
      <listitem>
       <para>
        Set a maximum number of connections for the new user.
        The default is to set no limit.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-d</option></term>
      <term><option>--createdb</option></term>
      <listitem>
       <para>
        The new user will be allowed to create databases.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-D</option></term>
      <term><option>--no-createdb</option></term>