<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.26 2002/04/21 19:02:39 thomas Exp $
PostgreSQL documentation
-->
<refentry id="APP-CREATEDB">
<refmeta>
<refentrytitle id="APP-CREATEDB-TITLE"><application>createdb</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>createdb</refname>
<refpurpose>create a new <productname>PostgreSQL</productname> database</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>createdb</command>
<arg rep="repeat"><replaceable>options</replaceable></arg>
<arg><replaceable>dbname</replaceable></arg>
<arg><replaceable>description</replaceable></arg>
</cmdsynopsis>
<refsect2 id="R2-APP-CREATEDB-1">
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term>-h, --host <replaceable class="parameter">host</replaceable></term>
<listitem>
<para>
Specifies the host name of the machine on which the
server is running. If host begins with a slash, it is used
as the directory for the Unix domain socket.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-p, --port <replaceable class="parameter">port</replaceable></term>
<listitem>
<para>
Specifies the Internet TCP/IP port or the local Unix domain socket file
extension on which the server is listening for connections.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-U, --username <replaceable class="parameter">username</replaceable></term>
<listitem>
<para>
User name to connect as
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-W, --password</term>
<listitem>
<para>
Force password prompt.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-e, --echo</term>
<listitem>
<para>
Echo the queries that <application>createdb</application> generates
and sends to the server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-q, --quiet</term>
<listitem>
<para>
Do not display a response.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-O, --owner <replaceable class="parameter">owner</replaceable></term>
<listitem>
<para>
Specifies the database user who will own the new database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-D, --location <replaceable class="parameter">datadir</replaceable></term>
<listitem>
<para>
Specifies the alternative location for the database. See also <xref
linkend="app-initlocation">.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-T, --template <replaceable class="parameter">template</replaceable></term>
<listitem>
<para>
Specifies the template database from which to build this database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-E, --encoding <replaceable class="parameter">encoding</replaceable></term>
<listitem>
<para>
Specifies the character encoding scheme to be used in this database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">dbname</replaceable></term>
<listitem>
<para>
Specifies the name of the database to be created. The name must be
unique among all <productname>PostgreSQL</productname> databases in this installation.
The default is to create a database with the same name as the
current system user.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">description</replaceable></term>
<listitem>
<para>
This optionally specifies a comment to be associated with the newly created
database.
</para>
</listitem>
</varlistentry>
</variablelist>
The options <option>-h</option>, <option>-p</option>, <option>-U</option>,
<option>-W</option>, and <option>-e</option> are passed on literally to
<xref linkend="app-psql">.
The options <option>-O</option>, <option>-D</option>,
<option>-T</option>, and
<option>-E</option> are converted into options for the underlying
SQL command <xref linkend="SQL-CREATEDATABASE"
endterm="SQL-CREATEDATABASE-title">; see there for more information
about them.
</para>
</refsect2>
<refsect2 id="R2-APP-CREATEDB-2">
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>CREATE DATABASE</computeroutput></term>
<listitem>
<para>The database was successfully created.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>createdb: Database creation failed.</computeroutput></term>
<listitem>
<para>(Says it all.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>createdb: Comment creation failed. (Database was created.)</computeroutput></term>
<listitem>
<para>
The comment/description for the database could not be created.
The database itself will have been created already. You can use the
<acronym>SQL</acronym> command <command>COMMENT ON DATABASE</command> to
create the comment later on.
</para>
</listitem>
</varlistentry>
</variablelist>
If there is an error condition, the backend error message will be displayed.
See <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-TITLE">
and <xref linkend="APP-PSQL"> for possibilities.
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-APP-CREATEDB-1">
<title>
Description
</title>
<para>
<application>createdb</application> creates a new <productname>PostgreSQL</productname>
database.
</para>
<para>
Normally, the database user who executes this command becomes the owner of
the new database.
However a different owner can be specified via the <option>-O</option>
option, if the executing user has appropriate privileges.
</para>
<para>
<application>createdb</application> is a shell script wrapper around the
<acronym>SQL</acronym> command
<xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-title"> via
the <productname>PostgreSQL</productname> interactive terminal
<xref linkend="APP-PSQL">. Thus, there is nothing
special about creating databases via this or other methods. This means
that the <application>psql</application> program must be found by the script and that
a database server must be running at the targeted port. Also, any default
settings and environment variables available to <application>psql</application>
and the <application>libpq</application> front-end library will apply.
</para>
</refsect1>
<refsect1 id="R1-APP-CREATEDB-2">
<title>Usage</title>
<informalexample>
<para>
To create the database <literal>demo</literal> using the default
database server:
<screen>
<prompt>$ </prompt><userinput>createdb demo</userinput>
<computeroutput>CREATE DATABASE</computeroutput>
</screen>
The response is the same as you would have gotten from running the
<command>CREATE DATABASE</command> <acronym>SQL</acronym> command.
</para>
</informalexample>
<informalexample>
<para>
To create the database <literal>demo</literal> using the
server on host <literal>eden</>, port 5000, using the
<literal>LATIN1</literal> encoding scheme with a look at the
underlying query:
<screen>
<prompt>$ </prompt><userinput>createdb -p 5000 -h eden -E LATIN1 -e demo</userinput>
<computeroutput>CREATE DATABASE "demo" WITH ENCODING = 'LATIN1'</computeroutput>
<computeroutput>CREATE DATABASE</computeroutput>
</screen>
</para>
</informalexample>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->