<literal>auto</literal> and
<literal>never</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
This utility, like most other <productname>PostgreSQL</productname> utilities,
also uses the environment variables supported by <application>libpq</application>
(see <xref linkend="libpq-envars"/>).
</para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<para>
In case of difficulty, see <xref linkend="sql-createrole"/>
and <xref linkend="app-psql"/> for
discussions of potential problems and error messages.
The database server must be running at the
targeted host. Also, any default connection settings and environment
variables used by the <application>libpq</application> front-end
library will apply.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
To create a user <literal>joe</literal> on the default database
server:
<screen>
<prompt>$ </prompt><userinput>createuser joe</userinput>
</screen>
</para>
<para>
To create a user <literal>joe</literal> on the default database
server with prompting for some additional attributes:
<screen>
<prompt>$ </prompt><userinput>createuser --interactive joe</userinput>
<computeroutput>Shall the new role be a superuser? (y/n) </computeroutput><userinput>n</userinput>
<computeroutput>Shall the new role be allowed to create databases? (y/n) </computeroutput><userinput>n</userinput>
<computeroutput>Shall the new role be allowed to create more new roles? (y/n) </computeroutput><userinput>n</userinput>
</screen>
</para>
<para>
To create the same user <literal>joe</literal> using the
server on host <literal>eden</literal>, port 5000, with attributes explicitly specified,
taking a look at the underlying command:
<screen>
<prompt>$ </prompt><userinput>createuser -h eden -p 5000 -S -D -R -e joe</userinput>
<computeroutput>CREATE ROLE joe NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT LOGIN;</computeroutput>
</screen>
</para>
<para>
To create the user <literal>joe</literal> as a superuser,
and assign a password immediately:
<screen>
<prompt>$ </prompt><userinput>createuser -P -s -e joe</userinput>
<computeroutput>Enter password for new role: </computeroutput><userinput>xyzzy</userinput>
<computeroutput>Enter it again: </computeroutput><userinput>xyzzy</userinput>
<computeroutput>CREATE ROLE joe PASSWORD 'md5b5f5ba1a423792b526f799ae4eb3d59e' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;</computeroutput>
</screen>
In the above example, the new password isn't actually echoed when typed,
but we show what was typed for clarity. As you see, the password is
encrypted before it is sent to the client.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="app-dropuser"/></member>
<member><xref linkend="sql-createrole"/></member>
<member><xref linkend="guc-createrole-self-grant"/></member>
</simplelist>
</refsect1>
</refentry>