Debian Codegraph @

doc/src/sgml/ref/dropuser.sgml

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