Debian Codegraph @

doc/src/sgml/ref/dropdb.sgml

raw
1 <!--
2 doc/src/sgml/ref/dropdb.sgml
3 PostgreSQL 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 <link linkend="sql-dropdatabase"><command>DROP DATABASE</command></link>.
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.
302 Are 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>