postgresql/doc/src/sgml/ref/createdb.sgml

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.34 2003/08/31 17:32:22 petere 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>

 <indexterm zone="app-createdb">
  <primary>createdb</primary>
 </indexterm>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>createdb</command>
   <arg rep="repeat"><replaceable>option</replaceable></arg>
   <arg><replaceable>dbname</replaceable></arg>
   <arg><replaceable>description</replaceable></arg>
  </cmdsynopsis>
 </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 wrapper around the
   <acronym>SQL</acronym> command <xref linkend="SQL-CREATEDATABASE"
   endterm="SQL-CREATEDATABASE-title">.  The database server must be 
   running on the targeted host. There is nothing special about creating 
   databases via this or other methods.  Also, any default settings and 
   environment variables used by the <application>libpq</application> 
   front-end library will apply.
  </para>
 </refsect1>


 <refsect1>
  <title>Options</title>

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

    <variablelist>
     <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 cluster.
        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>

     <varlistentry>
      <term><option>-D <replaceable class="parameter">location</replaceable></></term>
      <term><option>--location <replaceable class="parameter">location</replaceable></></term>
      <listitem>
       <para>
	Specifies the alternative location for the database.  See also <xref
	linkend="app-initlocation">.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-e</></term>
      <term><option>--echo</></term>
      <listitem>
       <para>
        Echo the commands that <application>createdb</application> generates
	and sends to the server.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-E <replaceable class="parameter">encoding</replaceable></></term>
      <term><option>--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><option>-O <replaceable class="parameter">owner</replaceable></></term>
      <term><option>--owner <replaceable class="parameter">owner</replaceable></></term>
      <listitem>
       <para>
	Specifies the database user who will own the new database.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-q</></term>
      <term><option>--quiet</></term>
      <listitem>
       <para>
        Do not display a response.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-T <replaceable class="parameter">template</replaceable></></term>
      <term><option>--template <replaceable class="parameter">template</replaceable></></term>
      <listitem>
       <para>
        Specifies the template database from which to build this database.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <para>
    The options <option>-D</option>, <option>-E</option>,
    <option>-O</option>, and
    <option>-T</option> correspond to options of the underlying
    SQL command <xref linkend="SQL-CREATEDATABASE"
    endterm="SQL-CREATEDATABASE-title">; see there for more information
    about them.
   </para>

   <para>
    <application>createdb</application> also accepts the following
    command-line arguments for connection parameters:

    <variablelist>
     <varlistentry>
      <term><option>-h <replaceable class="parameter">host</replaceable></></term>
      <term><option>--host <replaceable class="parameter">host</replaceable></></term>
      <listitem>
       <para>
	Specifies the host name of the machine on which the 
	server is running.  If the value begins with a slash, it is used 
	as the directory for the Unix domain socket.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-p <replaceable class="parameter">port</replaceable></></term>
      <term><option>--port <replaceable class="parameter">port</replaceable></></term>
      <listitem>
       <para>
	Specifies the TCP port or the local Unix domain socket file 
	extension on which the server is listening for connections.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-U <replaceable class="parameter">username</replaceable></></term>
      <term><option>--username <replaceable class="parameter">username</replaceable></></term>
      <listitem>
       <para>
        User name to connect as
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-W</></term>
      <term><option>--password</></term>
      <listitem>
       <para>
        Force password prompt.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

 </refsect1>


 <refsect1>
  <title>Diagnostics</title>

    <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>

   <para>
    If there is an error condition, the backend error message will be displayed.
    See <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-TITLE">
    for possibilities.
   </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>
  </variablelist>
 </refsect1>


 <refsect1 id="R1-APP-CREATEDB-2">
  <title>Examples</title>

   <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>

   <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 command:
<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>
 </refsect1>


 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member><xref linkend="app-dropdb"></member>
   <member><xref linkend="sql-createdatabase" endterm="sql-createdatabase-title"></member>
  </simplelist>
 </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:
-->