1<!--
2doc/src/sgml/ref/dropdb.sgml
3PostgreSQL documentation
4-->
5
6<refentry id="app-dropdb">
7 <indexterm zone="app-dropdb">
8  <primary>dropdb</primary>
9 </indexterm>
10
11 <refmeta>
12  <refentrytitle><application>dropdb</application></refentrytitle>
13  <manvolnum>1</manvolnum>
14  <refmiscinfo>Application</refmiscinfo>
15 </refmeta>
16
17 <refnamediv>
18  <refname>dropdb</refname>
19  <refpurpose>remove a <productname>PostgreSQL</productname> database</refpurpose>
20 </refnamediv>
21
22 <refsynopsisdiv>
23  <cmdsynopsis>
24   <command>dropdb</command>
25   <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
26   <arg rep="repeat"><replaceable>option</replaceable></arg>
27   <arg choice="plain"><replaceable>dbname</replaceable></arg>
28  </cmdsynopsis>
29 </refsynopsisdiv>
30
31
32 <refsect1>
33  <title>Description</title>
34
35  <para>
36   <application>dropdb</application> destroys an existing
37   <productname>PostgreSQL</productname> database.
38   The user who executes this command must be a database
39   superuser or the owner of the database.
40  </para>
41
42  <para>
43   <application>dropdb</application> is a wrapper around the
44   <acronym>SQL</acronym> command <xref linkend="sql-dropdatabase"/>.
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</application> 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</option></term>
70      <term><option>--echo</option></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>-f</option></term>
81      <term><option>--force</option></term>
82      <listitem>
83       <para>
84        Attempt to terminate all existing connections to the target database
85        before dropping it.   See <xref linkend="sql-dropdatabase"/> for more
86        information on this option.
87       </para>
88      </listitem>
89     </varlistentry>
90
91     <varlistentry>
92      <term><option>-i</option></term>
93      <term><option>--interactive</option></term>
94      <listitem>
95       <para>
96       Issues a verification prompt before doing anything destructive.
97       </para>
98      </listitem>
99     </varlistentry>
100
101     <varlistentry>
102       <term><option>-V</option></term>
103       <term><option>--version</option></term>
104       <listitem>
105       <para>
106       Print the <application>dropdb</application> version and exit.
107       </para>
108       </listitem>
109     </varlistentry>
110
111     <varlistentry>
112      <term><option>--if-exists</option></term>
113      <listitem>
114       <para>
115       Do not throw an error if the database does not exist. A notice is issued
116       in this case.
117       </para>
118      </listitem>
119     </varlistentry>
120
121     <varlistentry>
122       <term><option>-?</option></term>
123       <term><option>--help</option></term>
124       <listitem>
125       <para>
126       Show help about <application>dropdb</application> command line
127       arguments, and exit.
128       </para>
129       </listitem>
130     </varlistentry>
131
132    </variablelist>
133
134  </para>
135
136  <para>
137   <application>dropdb</application> also accepts the following
138   command-line arguments for connection parameters:
139
140   <variablelist>
141     <varlistentry>
142      <term><option>-h <replaceable class="parameter">host</replaceable></option></term>
143      <term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
144      <listitem>
145       <para>
146        Specifies the host name of the machine on which the
147        server
148        is running.  If the value begins with a slash, it is used
149        as the directory for the Unix domain socket.
150       </para>
151      </listitem>
152     </varlistentry>
153
154     <varlistentry>
155      <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
156      <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
157      <listitem>
158       <para>
159        Specifies the TCP port or local Unix domain socket file
160        extension on which the server
161        is listening for connections.
162       </para>
163      </listitem>
164     </varlistentry>
165
166     <varlistentry>
167      <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
168      <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
169      <listitem>
170       <para>
171        User name to connect as.
172       </para>
173      </listitem>
174     </varlistentry>
175
176     <varlistentry>
177      <term><option>-w</option></term>
178      <term><option>--no-password</option></term>
179      <listitem>
180       <para>
181        Never issue a password prompt.  If the server requires
182        password authentication and a password is not available by
183        other means such as a <filename>.pgpass</filename> file, the
184        connection attempt will fail.  This option can be useful in
185        batch jobs and scripts where no user is present to enter a
186        password.
187       </para>
188      </listitem>
189     </varlistentry>
190
191     <varlistentry>
192      <term><option>-W</option></term>
193      <term><option>--password</option></term>
194      <listitem>
195       <para>
196        Force <application>dropdb</application> to prompt for a
197        password before connecting to a database.
198       </para>
199
200       <para>
201        This option is never essential, since
202        <application>dropdb</application> will automatically prompt
203        for a password if the server demands password authentication.
204        However, <application>dropdb</application> will waste a
205        connection attempt finding out that the server wants a password.
206        In some cases it is worth typing <option>-W</option> to avoid the extra
207        connection attempt.
208       </para>
209      </listitem>
210     </varlistentry>
211
212     <varlistentry>
213      <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term>
214      <listitem>
215       <para>
216         Specifies the name of the database to connect to in order to drop the
217         target database. If not specified, the <literal>postgres</literal>
218         database will be used; if that does not exist (or is the database
219         being dropped), <literal>template1</literal> will be used.
220         This can be a <link linkend="libpq-connstring">connection
221         string</link>.  If so, connection string parameters will override any
222         conflicting command line options.
223       </para>
224      </listitem>
225     </varlistentry>
226   </variablelist>
227  </para>
228 </refsect1>
229
230
231 <refsect1>
232  <title>Environment</title>
233
234  <variablelist>
235   <varlistentry>
236    <term><envar>PGHOST</envar></term>
237    <term><envar>PGPORT</envar></term>
238    <term><envar>PGUSER</envar></term>
239
240    <listitem>
241     <para>
242      Default connection parameters
243     </para>
244    </listitem>
245   </varlistentry>
246
247   <varlistentry>
248    <term><envar>PG_COLOR</envar></term>
249    <listitem>
250     <para>
251      Specifies whether to use color in diagnostic messages. Possible values
252      are <literal>always</literal>, <literal>auto</literal> and
253      <literal>never</literal>.
254     </para>
255    </listitem>
256   </varlistentry>
257  </variablelist>
258
259  <para>
260   This utility, like most other <productname>PostgreSQL</productname> utilities,
261   also uses the environment variables supported by <application>libpq</application>
262   (see <xref linkend="libpq-envars"/>).
263  </para>
264
265 </refsect1>
266
267
268 <refsect1>
269  <title>Diagnostics</title>
270
271  <para>
272   In case of difficulty, see <xref linkend="sql-dropdatabase"/>
273   and <xref linkend="app-psql"/> for
274   discussions of potential problems and error messages.
275   The database server must be running at the
276   targeted host.  Also, any default connection settings and environment
277   variables used by the <application>libpq</application> front-end
278   library will apply.
279  </para>
280
281 </refsect1>
282
283
284 <refsect1>
285  <title>Examples</title>
286
287   <para>
288    To destroy the database <literal>demo</literal> on the default
289    database server:
290<screen>
291<prompt>$ </prompt><userinput>dropdb demo</userinput>
292</screen>
293   </para>
294
295   <para>
296    To destroy the database <literal>demo</literal> using the
297    server on host <literal>eden</literal>, port 5000, with verification and a peek
298    at the underlying command:
299<screen>
300<prompt>$ </prompt><userinput>dropdb -p 5000 -h eden -i -e demo</userinput>
301<computeroutput>Database "demo" will be permanently deleted.
302Are you sure? (y/n) </computeroutput><userinput>y</userinput>
303<computeroutput>DROP DATABASE demo;</computeroutput>
304</screen></para>
305 </refsect1>
306
307
308 <refsect1>
309  <title>See Also</title>
310
311  <simplelist type="inline">
312   <member><xref linkend="app-createdb"/></member>
313   <member><xref linkend="sql-dropdatabase"/></member>
314  </simplelist>
315 </refsect1>
316
317</refentry>
318