<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>
  </refnamediv>
<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..
	      </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>
	      -i
	    </term>
	    <listitem>
	      <para>
		Run in interactive mode.
		Prompts for confirmation before destroying a database.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <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.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	</variablelist>
      </para>
    </refsect2>

    <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>.
	    </term>
	    <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.
	      </para>
	    </listitem>
	  </varlistentry>

	  <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>.
	    </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
	      destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
	    </term>
	    <listitem>
	      <para>
		You do not have permission to destroy (or create) databases. 
		Contact your <productname>Postgres</productname> site administrator.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      ERROR:  destroydb: database '<replaceable class="parameter">dbname</replaceable>' does not exist.
	      destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
	    </term>
	    <listitem>
	      <para>
		The database to be removed does not have an entry in the
		<literal>pg_database</literal> class.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <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>.
	    </term>
	    <listitem>
	      <para>
		You are not the Database Administrator (DBA) for the specified database.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      destroydb: database destroy 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>destroydb</application> internally runs
	  <command>DESTROY DATABASE</command> from <application>psql</application>
	  while connected to the <literal>template1</literal> database.
	</para>
      </note>
    </refsect2>
  </refsynopsisdiv>

  <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>
    <para>
      All references to
      the database are removed, including the directory containing this
      database and its associated files.
    </para>
    <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">.
    </para>
  </refsect1>

  <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>
    <para>
      To destroy the database <literal>demo</literal>
      using the postmaster on host eden, port 5000:
      <programlisting>
	destroydb -p 5000 -h eden demo
      </programlisting>
    </para>
  </refsect1>
</REFENTRY>
