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