<!entity vacuum system "vacuum.sgml">

<!-- these are in the "utilities" reference chapter -->

<!entity createdb system "createdb.sgml">

<!entity createuser system "createuser.sgml">

<!entity destroydb system "destroydb.sgml">

<!entity destroyuser system "destroyuser.sgml">

<!entity initdb system "initdb.sgml">

<!entity initlocation system "initlocation.sgml">

<!entity pgDump system "pg_dump.sgml">

<!entity pgDumpall system "pg_dumpall.sgml">

<!entity psqlRef system "psql-ref.sgml">

&set;

&show;

&update;

&vacuum;

</Chapter>

<productname>Postgres</productname> support utilities.

</para>

&createdb;

&createuser;

&destroydb;

&destroyuser;

&initdb;

&initlocation;

&pgDump;

&pgDumpall;

&psqlRef;

</chapter>

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

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

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

<varlistentry>

<term>

-u

</term>

<listitem>

<para>

Use password authentication.

Prompts for

<replaceable class="parameter">username</replaceable>

and <replaceable class="parameter">password</replaceable>.

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

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

</variablelist>

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

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

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

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

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

<listitem>

<para>

You do not have permission to create new databases.

Contact your <productname>Postgres</productname> site administrator.

<varlistentry>

<term>

ERROR: createdb: database '<replaceable class="parameter">dbname</replaceable>' already exists.

createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.

<listitem>

<para>

The database already exists.

<varlistentry>

<term>

createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.

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

</variablelist>

<note>

<para>

<application>createdb</application> internally runs

CREATE DATABASE from <application>psql</application>

while connected to the <literal>template1</literal> database.

</note>

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

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

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

</REFENTRY>