granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/dropuser.sgml

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