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 <link linkend="sql-droprole"><command>DROP ROLE</command></link>.
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
224   <varlistentry>
225    <term><envar>PG_COLOR</envar></term>
226    <listitem>
227     <para>
228      Specifies whether to use color in diagnostic messages. Possible values
229      are <literal>always</literal>, <literal>auto</literal> and
230      <literal>never</literal>.
231     </para>
232    </listitem>
233   </varlistentry>
234  </variablelist>
235
236  <para>
237   This utility, like most other <productname>PostgreSQL</productname> utilities,
238   also uses the environment variables supported by <application>libpq</application>
239   (see <xref linkend="libpq-envars"/>).
240  </para>
241
242 </refsect1>
243
244
245 <refsect1>
246  <title>Diagnostics</title>
247
248  <para>
249   In case of difficulty, see <xref linkend="sql-droprole"/>
250   and <xref linkend="app-psql"/> for
251   discussions of potential problems and error messages.
252   The database server must be running at the
253   targeted host.  Also, any default connection settings and environment
254   variables used by the <application>libpq</application> front-end
255   library will apply.
256  </para>
257
258 </refsect1>
259
260
261 <refsect1>
262  <title>Examples</title>
263
264   <para>
265    To remove user <literal>joe</literal> from the default database
266    server:
267<screen>
268<prompt>$ </prompt><userinput>dropuser joe</userinput>
269</screen>
270   </para>
271
272   <para>
273    To remove user <literal>joe</literal> using the server on host
274    <literal>eden</literal>, port 5000, with verification and a peek at the underlying
275    command:
276<screen>
277<prompt>$ </prompt><userinput>dropuser -p 5000 -h eden -i -e joe</userinput>
278<computeroutput>Role "joe" will be permanently removed.
279Are you sure? (y/n) </computeroutput><userinput>y</userinput>
280<computeroutput>DROP ROLE joe;</computeroutput>
281</screen></para>
282 </refsect1>
283
284
285 <refsect1>
286  <title>See Also</title>
287
288  <simplelist type="inline">
289   <member><xref linkend="app-createuser"/></member>
290   <member><xref linkend="sql-droprole"/></member>
291  </simplelist>
292 </refsect1>
293
294</refentry>
295