1<!--
2doc/src/sgml/ref/dropuser.sgml
3PostgreSQL documentation
4-->
5
6<refentry id="app-dropuser">
7 <indexterm zone="app-dropuser">
8  <primary>dropuser</primary>
9 </indexterm>
10
11 <refmeta>
12  <refentrytitle><application>dropuser</application></refentrytitle>
13  <manvolnum>1</manvolnum>
14  <refmiscinfo>Application</refmiscinfo>
15 </refmeta>
16
17 <refnamediv>
18  <refname>dropuser</refname>
19  <refpurpose>remove a <productname>PostgreSQL</productname> user account</refpurpose>
20 </refnamediv>
21
22 <refsynopsisdiv>
23  <cmdsynopsis>
24   <command>dropuser</command>
25   <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
26   <arg rep="repeat"><replaceable>option</replaceable></arg>
27   <arg choice="opt"><replaceable>username</replaceable></arg>
28  </cmdsynopsis>
29 </refsynopsisdiv>
30
31
32 <refsect1>
33  <title>Description</title>
34
35  <para>
36   <application>dropuser</application> removes an existing
37   <productname>PostgreSQL</productname> user.
38   Only superusers and users with the <literal>CREATEROLE</literal> privilege can
39   remove <productname>PostgreSQL</productname> users.  (To remove a
40   superuser, you must yourself be a superuser.)
41  </para>
42
43  <para>
44   <application>dropuser</application> is a wrapper around the
45   <acronym>SQL</acronym> command <xref linkend="sql-droprole"/>.
46   There is no effective difference between dropping users via
47   this utility and via other methods for accessing the server.
48  </para>
49
50 </refsect1>
51
52
53 <refsect1>
54  <title>Options</title>
55
56  <para>
57   <application>dropuser</application> accepts the following command-line arguments:
58
59    <variablelist>
60     <varlistentry>
61      <term><replaceable class="parameter">username</replaceable></term>
62      <listitem>
63       <para>
64        Specifies the name of the <productname>PostgreSQL</productname> user to be removed.
65        You will be prompted for a name if none is specified on the command
66        line and the <option>-i</option>/<option>--interactive</option> option
67        is used.
68       </para>
69      </listitem>
70     </varlistentry>
71
72     <varlistentry>
73      <term><option>-e</option></term>
74      <term><option>--echo</option></term>
75      <listitem>
76       <para>
77        Echo the commands that <application>dropuser</application> generates
78        and sends to the server.
79       </para>
80      </listitem>
81     </varlistentry>
82
83     <varlistentry>
84      <term><option>-i</option></term>
85      <term><option>--interactive</option></term>
86      <listitem>
87       <para>
88        Prompt for confirmation before actually removing the user, and prompt
89        for the user name if none is specified on the command line.
90       </para>
91      </listitem>
92     </varlistentry>
93
94     <varlistentry>
95       <term><option>-V</option></term>
96       <term><option>--version</option></term>
97       <listitem>
98       <para>
99       Print the <application>dropuser</application> version and exit.
100       </para>
101       </listitem>
102     </varlistentry>
103
104     <varlistentry>
105      <term><option>--if-exists</option></term>
106      <listitem>
107       <para>
108        Do not throw an error if the user does not exist. A notice is
109        issued in this case.
110       </para>
111      </listitem>
112     </varlistentry>
113
114     <varlistentry>
115       <term><option>-?</option></term>
116       <term><option>--help</option></term>
117       <listitem>
118       <para>
119       Show help about <application>dropuser</application> command line
120       arguments, and exit.
121       </para>
122       </listitem>
123     </varlistentry>
124
125    </variablelist>
126  </para>
127
128  <para>
129   <application>dropuser</application> also accepts the following
130   command-line arguments for connection parameters:
131
132   <variablelist>
133     <varlistentry>
134      <term><option>-h <replaceable class="parameter">host</replaceable></option></term>
135      <term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
136      <listitem>
137       <para>
138        Specifies the host name of the machine on which the
139        server
140        is running.  If the value begins with a slash, it is used
141        as the directory for the Unix domain socket.
142       </para>
143      </listitem>
144     </varlistentry>
145
146     <varlistentry>
147      <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
148      <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
149      <listitem>
150       <para>
151        Specifies the TCP port or local Unix domain socket file
152        extension on which the server
153        is listening for connections.
154       </para>
155      </listitem>
156     </varlistentry>
157
158     <varlistentry>
159      <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
160      <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
161      <listitem>
162       <para>
163        User name to connect as (not the user name to drop).
164       </para>
165      </listitem>
166     </varlistentry>
167
168     <varlistentry>
169      <term><option>-w</option></term>
170      <term><option>--no-password</option></term>
171      <listitem>
172       <para>
173        Never issue a password prompt.  If the server requires
174        password authentication and a password is not available by
175        other means such as a <filename>.pgpass</filename> file, the
176        connection attempt will fail.  This option can be useful in
177        batch jobs and scripts where no user is present to enter a
178        password.
179       </para>
180      </listitem>
181     </varlistentry>
182
183     <varlistentry>
184      <term><option>-W</option></term>
185      <term><option>--password</option></term>
186      <listitem>
187       <para>
188        Force <application>dropuser</application> to prompt for a
189        password before connecting to a database.
190       </para>
191
192       <para>
193        This option is never essential, since
194        <application>dropuser</application> will automatically prompt
195        for a password if the server demands password authentication.
196        However, <application>dropuser</application> will waste a
197        connection attempt finding out that the server wants a password.
198        In some cases it is worth typing <option>-W</option> to avoid the extra
199        connection attempt.
200       </para>
201      </listitem>
202     </varlistentry>
203   </variablelist>
204  </para>
205 </refsect1>
206
207
208 <refsect1>
209  <title>Environment</title>
210
211  <variablelist>
212   <varlistentry>
213    <term><envar>PGHOST</envar></term>
214    <term><envar>PGPORT</envar></term>
215    <term><envar>PGUSER</envar></term>
216
217    <listitem>
218     <para>
219      Default connection parameters
220     </para>
221    </listitem>
222   </varlistentry>
223  </variablelist>
224
225  <para>
226   This utility, like most other <productname>PostgreSQL</productname> utilities,
227   also uses the environment variables supported by <application>libpq</application>
228   (see <xref linkend="libpq-envars"/>).
229  </para>
230
231 </refsect1>
232
233
234 <refsect1>
235  <title>Diagnostics</title>
236
237  <para>
238   In case of difficulty, see <xref linkend="sql-droprole"/>
239   and <xref linkend="app-psql"/> for
240   discussions of potential problems and error messages.
241   The database server must be running at the
242   targeted host.  Also, any default connection settings and environment
243   variables used by the <application>libpq</application> front-end
244   library will apply.
245  </para>
246
247 </refsect1>
248
249
250 <refsect1>
251  <title>Examples</title>
252
253   <para>
254    To remove user <literal>joe</literal> from the default database
255    server:
256<screen>
257<prompt>$ </prompt><userinput>dropuser joe</userinput>
258</screen>
259   </para>
260
261   <para>
262    To remove user <literal>joe</literal> using the server on host
263    <literal>eden</literal>, port 5000, with verification and a peek at the underlying
264    command:
265<screen>
266<prompt>$ </prompt><userinput>dropuser -p 5000 -h eden -i -e joe</userinput>
267<computeroutput>Role "joe" will be permanently removed.
268Are you sure? (y/n) </computeroutput><userinput>y</userinput>
269<computeroutput>DROP ROLE joe;</computeroutput>
270</screen></para>
271 </refsect1>
272
273
274 <refsect1>
275  <title>See Also</title>
276
277  <simplelist type="inline">
278   <member><xref linkend="app-createuser"/></member>
279   <member><xref linkend="sql-droprole"/></member>
280  </simplelist>
281 </refsect1>
282
283</refentry>
284