<REFENTRY ID="APP-DESTROYUSER">
<REFMETA>
<REFENTRYTITLE>
<application>destroyuser</application>
</REFENTRYTITLE>
<REFMISCINFO>Application</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
<application>destroyuser</application>
</REFNAME>
<REFPURPOSE>
Destroy a <productname>Postgres</productname> user and associated databases
</REFPURPOSE>
  </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
destroyuser [ <replaceable class="parameter">username</replaceable> ]
destroyuser [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
    [ <replaceable class="parameter">username</replaceable> ]
</SYNOPSIS>

    <REFSECT2 ID="R2-APP-DESTROYUSER-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>
	      <replaceable class="parameter">username</replaceable>
	    </term>
	    <listitem>
	      <para>
		Specifies the name of the <productname>Postgres</productname> user to be removed. 
		This name must exist in the <productname>Postgres</productname> installation.
		You will be prompted for a name if none is specified on the command line.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	</variablelist>
      </para>
    </refsect2>
    
    <REFSECT2 ID="R2-APP-DESTROYUSER-2">
      <REFSECT2INFO>
	<DATE>1998-10-02</DATE>
      </REFSECT2INFO>
      <TITLE>
	Outputs
      </TITLE>
      <PARA>
	<application>destroyuser</application> will remove an entry in the
	<literal>pg_user</literal> or <literal>pg_shadow</literal> system table,
	and will remove all databases for which that user is the administrator
	(<acronym>DBA</acronym>).

	<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>'?
	      destroyuser: database access failed.
	    </term>
	    <listitem>
	      <para>
		<application>destroyuser</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'
	      destroyuser: database access failed.
	    </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>
	      destroyuser: <replaceable class="parameter">username</replaceable> cannot delete users.
	    </term>
	    <listitem>
	      <para>
		You do not have permission to delete users; contact your
		<productname>Postgres</productname> site administrator.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>
	      destroyuser: user "<replaceable class="parameter">username</replaceable>" already exists
	    </term>
	    <listitem>
	      <para>
		The user to be added already has an entry in the <literal>pg_shadow</literal>
		class.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      database access failed
	    </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>

	  <varlistentry>
	    <term>
	      destroydb on <replaceable class="parameter">dbname</replaceable> failed - exiting
	    </term>
	    <listitem>
	      <para>
		An internal error occurred in <application>psql</application>
		or in the backend server. There was possibly a Unix permissions problem with the
		specified database.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>
	      delete of user <replaceable class="parameter">username</replaceable> was UNSUCCESSFUL
	    </term>
	    <listitem>
	      <para>
		An internal error occurred in <application>psql</application>
		or in the backend server.
	      </para>
	    </listitem>
	  </varlistentry>

	</variablelist>
      </para>

      <note>
	<para>
	  <application>destroyuser</application> internally runs
	  DROP USER from <application>psql</application>
	  while connected to the <literal>template1</literal> database.
	</para>
      </note>
    </refsect2>
  </refsynopsisdiv>
  
  <REFSECT1 ID="R1-APP-DESTROYUSER-1">
    <REFSECT1INFO>
      <DATE>1998-10-02</DATE>
    </REFSECT1INFO>
    <TITLE>
      Description
    </TITLE>
    <PARA>
      <application>destroyuser</application> removes an existing
      <productname>Postgres</productname> user
      and the databases for which that user
      is database administrator.
      Only users with <literal>usesuper</literal> set in
      the <literal>pg_shadow</literal> class can destroy 
      <productname>Postgres</productname> users.  As shipped,
      the user <literal>postgres</literal> can remove users.
    </para>
    <para>
      <application>destroyuser</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>destroyuser</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>
    <para>
      Once invoked, <application>destroyuser</application>
      will warn you about the databases that will be destroyed in the
      process and permit you to abort the removal of the user if desired.
    </para>
  </refsect1>
</REFENTRY>
