<REFENTRY ID="APP-DESTROYDB">
<REFMETA>
<REFENTRYTITLE>
<application>destroydb</application>
</REFENTRYTITLE>
<REFMISCINFO>Application</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
<application>destroydb</application>
</REFNAME>
<REFPURPOSE>
Create a new <productname>Postgres</productname> database
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
destroydb [ <replaceable class="parameter">dbname</replaceable> ]
destroydb [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
    [ -i ] [ <replaceable class="parameter">dbname</replaceable> ]
</SYNOPSIS>

<REFSECT2 ID="R2-APP-DESTROYDB-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>
-i
</term>
<listitem>
<para>
Run in interactive mode.
Prompts for confirmation before destroying a database.

<varlistentry>
<term>
<replaceable class="parameter">dbname</replaceable>
</term>
<listitem>
<para>
Specifies the name of the database to be destroyed.  The database
must be one of the existing <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-DESTROYDB-2">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>destroydb</application> will remove files from the
<filename><envar>PGDATA</envar>/<replaceable class="parameter">dbname</replaceable>/</filename>
data area for the existing 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>'?
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
<application>destroydb</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'
destroydb: database destroy 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
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
You do not have permission to destroy (or create) databases. 
Contact your <productname>Postgres</productname> site administrator.

<varlistentry>
<term>
ERROR:  destroydb: database '<replaceable class="parameter">dbname</replaceable>' does not exist.
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
The database to be removed does not have an entry in the
<literal>pg_database</literal> class.

<varlistentry>
<term>
ERROR:  destroydb: database '<replaceable class="parameter">dbname</replaceable>' is not owned by you.
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
You are not the Database Administrator (DBA) for the specified database.

<varlistentry>
<term>
destroydb: database destroy 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>destroydb</application> internally runs
<command>DESTROY DATABASE</command> from <application>psql</application>
while connected to the <literal>template1</literal> database.
</note>

<REFSECT1 ID="R1-APP-DESTROYDB-1">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>destroydb</application> destroys an existing
<productname>Postgres</productname> database.
The person who executes this command must be
the database administrator, or <acronym>DBA</acronym>,
or must be the <productname>Postgres</productname> super-user.
The program runs silently; no confirmation message will be displayed.
After the database is destroyed, a Unix shell prompt will reappear.

<para>
All references to
the database are removed, including the directory containing this
database and its associated files.

<para>
<application>destroydb</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>destroydb</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-DESTROYDB-2">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To destroy the database <literal>demo</literal>
 using the postmaster on the local host, port 5432:
<programlisting>
destroydb demo
</programlisting>

<para>
To destroy the database <literal>demo</literal>
 using the postmaster on host eden, port 5000:
<programlisting>
destroydb -p 5000 -h eden demo
</programlisting>

</REFENTRY>
