doc/src/sgml/ref/dropdb.sgml

   1 <!--
   2 $PostgreSQL$
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="APP-DROPDB">
   7  <refmeta>
   8   <refentrytitle id="APP-DROPDB-TITLE"><application>dropdb</application></refentrytitle>
   9   <manvolnum>1</manvolnum>
  10   <refmiscinfo>Application</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>dropdb</refname>
  15   <refpurpose>remove a <productname>PostgreSQL</productname> database</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="app-dropdb">
  19   <primary>dropdb</primary>
  20  </indexterm>
  21
  22  <refsynopsisdiv>
  23   <cmdsynopsis>
  24    <command>dropdb</command>
  25    <arg rep="repeat"><replaceable>option</replaceable></arg>
  26    <arg choice="plain"><replaceable>dbname</replaceable></arg>
  27   </cmdsynopsis>
  28  </refsynopsisdiv>
  29
  30
  31  <refsect1>
  32   <title>Description</title>
  33
  34   <para>
  35    <application>dropdb</application> destroys an existing
  36    <productname>PostgreSQL</productname> database.
  37    The user who executes this command must be a database
  38    superuser or the owner of the database.
  39   </para>
  40
  41   <para>
  42    <application>dropdb</application> is a wrapper around the
  43    <acronym>SQL</acronym> command <xref linkend="SQL-DROPDATABASE"
  44    endterm="SQL-DROPDATABASE-title">.
  45    There is no effective difference between dropping databases via
  46    this utility and via other methods for accessing the server.
  47   </para>
  48
  49  </refsect1>
  50
  51
  52  <refsect1>
  53   <title>Options</title>
  54
  55   <para>
  56    <application>dropdb</> accepts the following command-line arguments:
  57
  58     <variablelist>
  59      <varlistentry>
  60       <term><replaceable class="parameter">dbname</replaceable></term>
  61       <listitem>
  62        <para>
  63         Specifies the name of the database to be removed.
  64        </para>
  65       </listitem>
  66      </varlistentry>
  67
  68      <varlistentry>
  69       <term><option>-e</></term>
  70       <term><option>--echo</></term>
  71       <listitem>
  72        <para>
  73         Echo the commands that <application>dropdb</application> generates
  74         and sends to the server.
  75        </para>
  76       </listitem>
  77      </varlistentry>
  78
  79      <varlistentry>
  80       <term><option>-i</></term>
  81       <term><option>--interactive</></term>
  82       <listitem>
  83        <para>
  84        Issues a verification prompt before doing anything destructive.
  85        </para>
  86       </listitem>
  87      </varlistentry>
  88     </variablelist>
  89   </para>
  90
  91   <para>
  92    <application>dropdb</application> also accepts the following
  93    command-line arguments for connection parameters:
  94
  95    <variablelist>
  96      <varlistentry>
  97       <term><option>-h <replaceable class="parameter">host</replaceable></></term>
  98       <term><option>--host <replaceable class="parameter">host</replaceable></></term>
  99       <listitem>
 100        <para>
 101         Specifies the host name of the machine on which the
 102         server
 103         is running.  If the value begins with a slash, it is used
 104         as the directory for the Unix domain socket.
 105        </para>
 106       </listitem>
 107      </varlistentry>
 108
 109      <varlistentry>
 110       <term><option>-p <replaceable class="parameter">port</replaceable></></term>
 111       <term><option>--port <replaceable class="parameter">port</replaceable></></term>
 112       <listitem>
 113        <para>
 114         Specifies the TCP port or local Unix domain socket file
 115         extension on which the server
 116         is listening for connections.
 117        </para>
 118       </listitem>
 119      </varlistentry>
 120
 121      <varlistentry>
 122       <term><option>-U <replaceable class="parameter">username</replaceable></></term>
 123       <term><option>--username <replaceable class="parameter">username</replaceable></></term>
 124       <listitem>
 125        <para>
 126         User name to connect as.
 127        </para>
 128       </listitem>
 129      </varlistentry>
 130
 131      <varlistentry>
 132       <term><option>-W</></term>
 133       <term><option>--password</></term>
 134       <listitem>
 135        <para>
 136         Force <application>dropdb</application> to prompt for a
 137         password before connecting to a database.
 138        </para>
 139
 140        <para>
 141         This option is never essential, since
 142         <application>dropdb</application> will automatically prompt
 143         for a password if the server demands password authentication.
 144         However, <application>dropdb</application> will waste a
 145         connection attempt finding out that the server wants a password.
 146         In some cases it is worth typing <option>-W</> to avoid the extra
 147         connection attempt.
 148        </para>
 149       </listitem>
 150      </varlistentry>
 151    </variablelist>
 152   </para>
 153  </refsect1>
 154
 155
 156  <refsect1>
 157   <title>Environment</title>
 158
 159   <variablelist>
 160    <varlistentry>
 161     <term><envar>PGHOST</envar></term>
 162     <term><envar>PGPORT</envar></term>
 163     <term><envar>PGUSER</envar></term>
 164
 165     <listitem>
 166      <para>
 167       Default connection parameters
 168      </para>
 169     </listitem>
 170    </varlistentry>
 171   </variablelist>
 172
 173   <para>
 174    This utility, like most other <productname>PostgreSQL</> utilities,
 175    also uses the environment variables supported by <application>libpq</>
 176    (see <xref linkend="libpq-envars">).
 177   </para>
 178
 179  </refsect1>
 180
 181
 182  <refsect1>
 183   <title>Diagnostics</title>
 184
 185   <para>
 186    In case of difficulty, see <xref linkend="SQL-DROPDATABASE"
 187    endterm="sql-dropdatabase-title"> and <xref linkend="APP-PSQL"> for
 188    discussions of potential problems and error messages.
 189    The database server must be running at the
 190    targeted host.  Also, any default connection settings and environment
 191    variables used by the <application>libpq</application> front-end
 192    library will apply.
 193   </para>
 194
 195  </refsect1>
 196
 197
 198  <refsect1>
 199   <title>Examples</title>
 200
 201    <para>
 202     To destroy the database <literal>demo</literal> on the default
 203     database server:
 204 <screen>
 205 <prompt>$ </prompt><userinput>dropdb demo</userinput>
 206 </screen>
 207    </para>
 208
 209    <para>
 210     To destroy the database <literal>demo</literal> using the
 211     server on host <literal>eden</literal>, port 5000, with verification and a peek
 212     at the underlying command:
 213 <screen>
 214 <prompt>$ </prompt><userinput>dropdb -p 5000 -h eden -i -e demo</userinput>
 215 <computeroutput>Database "demo" will be permanently deleted.
 216 Are you sure? (y/n) </computeroutput><userinput>y</userinput>
 217 <computeroutput>DROP DATABASE demo;</computeroutput>
 218 </screen>
 219    </para>
 220  </refsect1>
 221
 222
 223  <refsect1>
 224   <title>See Also</title>
 225
 226   <simplelist type="inline">
 227    <member><xref linkend="app-createdb"></member>
 228    <member><xref linkend="sql-dropdatabase" endterm="sql-dropdatabase-title"></member>
 229   </simplelist>
 230  </refsect1>
 231
 232 </refentry>