<REFENTRY ID="APP-CREATEDB">
  <REFMETA>
    <REFENTRYTITLE>
      <application>createdb</application>
    </REFENTRYTITLE>
    <REFMISCINFO>Application</REFMISCINFO>
  </REFMETA>
  <REFNAMEDIV>
    <REFNAME>
      <application>createdb</application>
    </REFNAME>
    <REFPURPOSE>
      Create a new <productname>Postgres</productname> database
    </REFPURPOSE>
  </refnamediv>
  <REFSYNOPSISDIV>
    <REFSYNOPSISDIVINFO>
      <DATE>1998-10-02</DATE>
    </REFSYNOPSISDIVINFO>
    <SYNOPSIS>
      createdb [ <replaceable class="parameter">dbname</replaceable> ]
      createdb [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
      [ -D <replaceable class="parameter">datadir</replaceable> ]
      [ -u ] [ <replaceable class="parameter">dbname</replaceable> ]
    </SYNOPSIS>
    
    <REFSECT2 ID="R2-APP-CREATEDB-1">
      <REFSECT2INFO>
	<DATE>1998-10-02</DATE>
      </REFSECT2INFO>
      <TITLE>
	Inputs
      </TITLE>
      <PARA>
	
	<variablelist>
	  <varlistentry>
	    <term>
	      -h <replaceable class="parameter">host</replaceable>
	    </term>
	    <listitem>
	      <para>
		Specifies the hostname of the machine on which the 
		<application>postmaster</application>
		is running.  Defaults to using a local Unix domain socket
		rather than an IP connection..
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      -p <replaceable class="parameter">port</replaceable>
	    </term>
	    <listitem>
	      <para>
		Specifies the Internet TCP/IP port or local Unix domain socket file 
		extension on which the <application>postmaster</application>
		is listening for connections.  The port number defaults to 5432,
		or the value of the <envar>PGPORT</envar>
		environment variable (if set).
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      -u
	    </term>
	    <listitem>
	      <para>
		Use password authentication. 
		Prompts for
		<replaceable class="parameter">username</replaceable>
		and <replaceable class="parameter">password</replaceable>.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      -D <replaceable class="parameter">datadir</replaceable>
	    </term>
	    <listitem>
	      <para>
		Specifies the alternate database location for this database installation.
		This is the location of the installation system tables, not the location
		of this specific database, which may be different.
	      </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>Postgres</productname> databases in this installation.
		<replaceable class="parameter">dbname</replaceable>
		defaults to the value of the
		<envar>USER</envar>
		environment variable.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	</variablelist>
      </para>
    </refsect2>

    <REFSECT2 ID="R2-APP-CREATEDB-2">
      <REFSECT2INFO>
	<DATE>1998-10-02</DATE>
      </REFSECT2INFO>
      <TITLE>
	Outputs
      </TITLE>
      <PARA>
	<application>createdb</application> will create files in the
	<filename><envar>PGDATA</envar>/<replaceable class="parameter">dbname</replaceable>/</filename>
	data area for the new database.
	
	<variablelist>
	  <varlistentry>
	    <term>
	      Connection to database 'template1' failed.
	      connectDB() failed: Is the postmaster running and accepting connections
	      at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
	      createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
	    </term>
	    <listitem>
	      <para>
		<application>createdb</application> could not attach to the 
		<application>postmaster</application> 
		process on the specified host and port.  If you see this message,
		ensure that the <application>postmaster</application> 
		is running on the proper host and that you have specified the proper
		port.  If your site uses an authentication system, ensure that you
		have obtained the required authentication credentials.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      Connection to database 'template1' failed.
	      FATAL 1:  SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
	      createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
	    </term>
	    <listitem>
	      <para>
		You do not have a valid entry in the relation <literal>pg_shadow</literal>
		and and will not be allowed to access <productname>Postgres</productname>. 
		Contact your <productname>Postgres</productname> administrator.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      ERROR:  user '<replaceable class="parameter">username</replaceable>' is not allowed to create/destroy databases
	      createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
	    </term>
	    <listitem>
	      <para>
		You do not have permission to create new databases.
		Contact your <productname>Postgres</productname> site administrator.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      ERROR:  createdb: database '<replaceable class="parameter">dbname</replaceable>' already exists.
	      createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
	    </term>
	    <listitem>
	      <para>
		The database already exists.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
	    </term>
	    <listitem>
	      <para>
		An internal error occurred in <application>psql</application>
		or in the backend server.  Ensure that your site administrator has
		properly installed <productname>Postgres</productname>and initialized the site with 
		<application>initdb</application>.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	</variablelist>
      </para>
      <note>
	<para>
	  <application>createdb</application> internally runs
	  CREATE DATABASE from <application>psql</application>
	  while connected to the <literal>template1</literal> database.
	</para>
      </note>
    </refsect2>
  </refsynopsisdiv>
  
  <REFSECT1 ID="R1-APP-CREATEDB-1">
    <REFSECT1INFO>
      <DATE>1998-10-02</DATE>
    </REFSECT1INFO>
    <TITLE>
      Description
    </TITLE>
    <PARA>
      <application>createdb</application> creates a new 
      <productname>Postgres</productname> database.
      The person who executes this command becomes
      the database administrator, or <acronym>DBA</acronym>,
      for this database and is the only
      person, other than the <productname>Postgres</productname> super-user,
      who can destroy it.
    </para>
    <para>
      <application>createdb</application> is a shell script that invokes
      <application>psql</application>.
      Hence, a <application>postmaster</application>
      process must be running on the database server host before
      <application>createdb</application>
      is executed. The 
      <envar>PGOPTION</envar>
      and
      <envar>PGREALM</envar>
      environment variables will be passed on to
      <application>psql</application>
      and processed as described in <xref linkend="app-psql" endterm="psql-ref">.
    </para>
  </refsect1>
  
  <REFSECT1 ID="R1-APP-CREATEDB-2">
    <REFSECT1INFO>
      <DATE>1998-10-02</DATE>
    </REFSECT1INFO>
    <TITLE>
      Usage
    </TITLE>
    <PARA>
      To create the database <literal>demo</literal>
      using the postmaster on the local host, port 5432:
      
      <programlisting>
	createdb demo
      </programlisting>
      
      To create the database <literal>demo</literal>
      using the postmaster on host eden, port 5000:
      
      <programlisting>
	createdb -p 5000 -h eden demo
      </programlisting>
    </para>
  </refsect1>
</REFENTRY>
