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>--no-password</></term>
 134       <listitem>
 135        <para>
 136         Never issue a password prompt.  If the server requires
 137         password authentication and a password is not available by
 138         other means such as a <filename>.pgpass</filename> file, the
 139         connection attempt will fail.  This option can be useful in
 140         batch jobs and scripts where no user is present to enter a
 141         password.
 142        </para>
 143       </listitem>
 144      </varlistentry>
 145
 146      <varlistentry>
 147       <term><option>-W</></term>
 148       <term><option>--password</></term>
 149       <listitem>
 150        <para>
 151         Force <application>dropdb</application> to prompt for a
 152         password before connecting to a database.
 153        </para>
 154
 155        <para>
 156         This option is never essential, since
 157         <application>dropdb</application> will automatically prompt
 158         for a password if the server demands password authentication.
 159         However, <application>dropdb</application> will waste a
 160         connection attempt finding out that the server wants a password.
 161         In some cases it is worth typing <option>-W</> to avoid the extra
 162         connection attempt.
 163        </para>
 164       </listitem>
 165      </varlistentry>
 166    </variablelist>
 167   </para>
 168  </refsect1>
 169
 170
 171  <refsect1>
 172   <title>Environment</title>
 173
 174   <variablelist>
 175    <varlistentry>
 176     <term><envar>PGHOST</envar></term>
 177     <term><envar>PGPORT</envar></term>
 178     <term><envar>PGUSER</envar></term>
 179
 180     <listitem>
 181      <para>
 182       Default connection parameters
 183      </para>
 184     </listitem>
 185    </varlistentry>
 186   </variablelist>
 187
 188   <para>
 189    This utility, like most other <productname>PostgreSQL</> utilities,
 190    also uses the environment variables supported by <application>libpq</>
 191    (see <xref linkend="libpq-envars">).
 192   </para>
 193
 194  </refsect1>
 195
 196
 197  <refsect1>
 198   <title>Diagnostics</title>
 199
 200   <para>
 201    In case of difficulty, see <xref linkend="SQL-DROPDATABASE"
 202    endterm="sql-dropdatabase-title"> and <xref linkend="APP-PSQL"> for
 203    discussions of potential problems and error messages.
 204    The database server must be running at the
 205    targeted host.  Also, any default connection settings and environment
 206    variables used by the <application>libpq</application> front-end
 207    library will apply.
 208   </para>
 209
 210  </refsect1>
 211
 212
 213  <refsect1>
 214   <title>Examples</title>
 215
 216    <para>
 217     To destroy the database <literal>demo</literal> on the default
 218     database server:
 219 <screen>
 220 <prompt>$ </prompt><userinput>dropdb demo</userinput>
 221 </screen>
 222    </para>
 223
 224    <para>
 225     To destroy the database <literal>demo</literal> using the
 226     server on host <literal>eden</literal>, port 5000, with verification and a peek
 227     at the underlying command:
 228 <screen>
 229 <prompt>$ </prompt><userinput>dropdb -p 5000 -h eden -i -e demo</userinput>
 230 <computeroutput>Database "demo" will be permanently deleted.
 231 Are you sure? (y/n) </computeroutput><userinput>y</userinput>
 232 <computeroutput>DROP DATABASE demo;</computeroutput>
 233 </screen>
 234    </para>
 235  </refsect1>
 236
 237
 238  <refsect1>
 239   <title>See Also</title>
 240
 241   <simplelist type="inline">
 242    <member><xref linkend="app-createdb"></member>
 243    <member><xref linkend="sql-dropdatabase" endterm="sql-dropdatabase-title"></member>
 244   </simplelist>
 245  </refsect1>
 246
 247 </refentry>