doc/src/sgml/ref/dropuser.sgml

   1 <!--
   2 $PostgreSQL$
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="APP-DROPUSER">
   7  <refmeta>
   8   <refentrytitle id="APP-DROPUSER-TITLE"><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>option</replaceable></arg>
  26    <arg><replaceable>username</replaceable></arg>
  27   </cmdsynopsis>
  28  </refsynopsisdiv>
  29
  30
  31  <refsect1>
  32   <title>Description</title>
  33
  34   <para>
  35    <application>dropuser</application> removes an existing
  36    <productname>PostgreSQL</productname> user.
  37    Only superusers and users with the <literal>CREATEROLE</> privilege can
  38    remove <productname>PostgreSQL</productname> users.  (To remove a
  39    superuser, you must yourself be a superuser.)
  40   </para>
  41
  42   <para>
  43    <application>dropuser</application> is a wrapper around the
  44    <acronym>SQL</acronym> command <xref linkend="SQL-DROPROLE"
  45    endterm="SQL-DROPROLE-title">.
  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     </variablelist>
  91   </para>
  92
  93   <para>
  94    <application>dropuser</application> also accepts the following
  95    command-line arguments for connection parameters:
  96
  97    <variablelist>
  98      <varlistentry>
  99       <term><option>-h <replaceable class="parameter">host</replaceable></></term>
 100       <term><option>--host <replaceable class="parameter">host</replaceable></></term>
 101       <listitem>
 102        <para>
 103         Specifies the host name of the machine on which the
 104         server
 105         is running.  If the value begins with a slash, it is used
 106         as the directory for the Unix domain socket.
 107        </para>
 108       </listitem>
 109      </varlistentry>
 110
 111      <varlistentry>
 112       <term><option>-p <replaceable class="parameter">port</replaceable></></term>
 113       <term><option>--port <replaceable class="parameter">port</replaceable></></term>
 114       <listitem>
 115        <para>
 116         Specifies the TCP port or local Unix domain socket file
 117         extension on which the server
 118         is listening for connections.
 119        </para>
 120       </listitem>
 121      </varlistentry>
 122
 123      <varlistentry>
 124       <term><option>-U <replaceable class="parameter">username</replaceable></></term>
 125       <term><option>--username <replaceable class="parameter">username</replaceable></></term>
 126       <listitem>
 127        <para>
 128         User name to connect as (not the user name to drop).
 129        </para>
 130       </listitem>
 131      </varlistentry>
 132
 133      <varlistentry>
 134       <term><option>-w</></term>
 135       <term><option>--no-password</></term>
 136       <listitem>
 137        <para>
 138         Never issue a password prompt.  If the server requires
 139         password authentication and a password is not available by
 140         other means such as a <filename>.pgpass</filename> file, the
 141         connection attempt will fail.  This option can be useful in
 142         batch jobs and scripts where no user is present to enter a
 143         password.
 144        </para>
 145       </listitem>
 146      </varlistentry>
 147
 148      <varlistentry>
 149       <term><option>-W</></term>
 150       <term><option>--password</></term>
 151       <listitem>
 152        <para>
 153         Force <application>dropuser</application> to prompt for a
 154         password before connecting to a database.
 155        </para>
 156
 157        <para>
 158         This option is never essential, since
 159         <application>dropuser</application> will automatically prompt
 160         for a password if the server demands password authentication.
 161         However, <application>dropuser</application> will waste a
 162         connection attempt finding out that the server wants a password.
 163         In some cases it is worth typing <option>-W</> to avoid the extra
 164         connection attempt.
 165        </para>
 166       </listitem>
 167      </varlistentry>
 168    </variablelist>
 169   </para>
 170  </refsect1>
 171
 172
 173  <refsect1>
 174   <title>Environment</title>
 175
 176   <variablelist>
 177    <varlistentry>
 178     <term><envar>PGHOST</envar></term>
 179     <term><envar>PGPORT</envar></term>
 180     <term><envar>PGUSER</envar></term>
 181
 182     <listitem>
 183      <para>
 184       Default connection parameters
 185      </para>
 186     </listitem>
 187    </varlistentry>
 188   </variablelist>
 189
 190   <para>
 191    This utility, like most other <productname>PostgreSQL</> utilities,
 192    also uses the environment variables supported by <application>libpq</>
 193    (see <xref linkend="libpq-envars">).
 194   </para>
 195
 196  </refsect1>
 197
 198
 199  <refsect1>
 200   <title>Diagnostics</title>
 201
 202   <para>
 203    In case of difficulty, see <xref linkend="SQL-DROPROLE"
 204    endterm="sql-droprole-title"> and <xref linkend="APP-PSQL"> for
 205    discussions of potential problems and error messages.
 206    The database server must be running at the
 207    targeted host.  Also, any default connection settings and environment
 208    variables used by the <application>libpq</application> front-end
 209    library will apply.
 210   </para>
 211
 212  </refsect1>
 213
 214
 215  <refsect1>
 216   <title>Examples</title>
 217
 218    <para>
 219     To remove user <literal>joe</literal> from the default database
 220     server:
 221 <screen>
 222 <prompt>$ </prompt><userinput>dropuser joe</userinput>
 223 </screen>
 224    </para>
 225
 226    <para>
 227     To remove user <literal>joe</literal> using the server on host
 228     <literal>eden</literal>, port 5000, with verification and a peek at the underlying
 229     command:
 230 <screen>
 231 <prompt>$ </prompt><userinput>dropuser -p 5000 -h eden -i -e joe</userinput>
 232 <computeroutput>Role "joe" will be permanently removed.
 233 Are you sure? (y/n) </computeroutput><userinput>y</userinput>
 234 <computeroutput>DROP ROLE joe;</computeroutput>
 235 </screen>
 236    </para>
 237  </refsect1>
 238
 239
 240  <refsect1>
 241   <title>See Also</title>
 242
 243   <simplelist type="inline">
 244    <member><xref linkend="app-createuser"></member>
 245    <member><xref linkend="sql-droprole" endterm="sql-droprole-title"></member>
 246   </simplelist>
 247  </refsect1>
 248
 249 </refentry>