automatically prompt
for a password if the server demands password authentication.
However, <application>createdb</application> will waste a
connection attempt finding out that the server wants a password.
In some cases it is worth typing <option>-W</option> to avoid the extra
connection attempt.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term>
<listitem>
<para>
Specifies the name of the database to connect to when creating the
new database. If not specified, the <literal>postgres</literal>
database will be used; if that does not exist (or if it is the name
of the new database being created), <literal>template1</literal> will
be used.
This can be a <link linkend="libpq-connstring">connection
string</link>. If so, connection string parameters will override any
conflicting command line options.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
<title>Environment</title>
<variablelist>
<varlistentry>
<term><envar>PGDATABASE</envar></term>
<listitem>
<para>
If set, the name of the database to create, unless overridden on
the command line.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>PGHOST</envar></term>
<term><envar>PGPORT</envar></term>
<term><envar>PGUSER</envar></term>
<listitem>
<para>
Default connection parameters. <envar>PGUSER</envar> also
determines the name of the database to create, if it is not
specified on the command line or by <envar>PGDATABASE</envar>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>PG_COLOR</envar></term>
<listitem>
<para>
Specifies whether to use color in diagnostic messages. Possible values
are <literal>always</literal>, <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-createdatabase"/>
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 the database <literal>demo</literal> using the default
database server:
<screen>
<prompt>$ </prompt><userinput>createdb demo</userinput>
</screen>
</para>
<para>
To create the database <literal>demo</literal> using the
server on host <literal>eden</literal>, port 5000, using the
<literal>template0</literal> template database, here is the
command-line command and the underlying SQL command:
<screen>
<prompt>$ </prompt><userinput>createdb -p 5000 -h eden -T template0 -e demo</userinput>
<computeroutput>CREATE DATABASE demo TEMPLATE template0;</computeroutput>
</screen></para>
</refsect1>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="app-dropdb"/></member>
<member><xref linkend="sql-createdatabase"/></member>
</simplelist>
</refsect1>
</refentry>