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

   1 <!--
   2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.6 1999/12/04 04:53:15 momjian Exp $
   3 Postgres documentation
   4 -->
   5
   6 <refentry id="APP-CREATEUSER">
   7  <refmeta>
   8   <refentrytitle id="APP-CREATEUSER-TITLE">
   9    <application>createuser</application>
  10   </refentrytitle>
  11   <refmiscinfo>Application</refmiscinfo>
  12  </refmeta>
  13  <refnamediv>
  14   <refname>
  15    <application>createuser</application>
  16   </refname>
  17   <refpurpose>
  18    Create a new <productname>PostgreSQL</productname> user
  19   </refpurpose>
  20  </refnamediv>
  21  <refsynopsisdiv>
  22   <refsynopsisdivinfo>
  23    <date>1999-11-07</date>
  24   </refsynopsisdivinfo>
  25
  26   <synopsis>
  27 createuser [ <replaceable class="parameter">options</replaceable> ] [ <replaceable class="parameter">username</replaceable> ]
  28   </synopsis>
  29
  30   <refsect2 id="R2-APP-CREATEUSER-1">
  31    <refsect2info>
  32     <date>1999-11-07</date>
  33    </refsect2info>
  34    <title>
  35     Inputs
  36    </title>
  37    <para>
  38
  39     <variablelist>
  40      <varlistentry>
  41       <term>-h, --host <replaceable class="parameter">host</replaceable></term>
  42       <listitem>
  43        <para>
  44         Specifies the hostname of the machine on which the
  45         <application>postmaster</application>
  46         is running.
  47        </para>
  48       </listitem>
  49      </varlistentry>
  50
  51      <varlistentry>
  52       <term>-p, --port <replaceable class="parameter">port</replaceable></term>
  53       <listitem>
  54        <para>
  55         Specifies the Internet TCP/IP port or local Unix domain socket file
  56         extension on which the <application>postmaster</application>
  57         is listening for connections.
  58        </para>
  59       </listitem>
  60      </varlistentry>
  61
  62      <varlistentry>
  63       <term>-e, --echo</term>
  64       <listitem>
  65        <para>
  66         Echo the queries that <application>createdb</application> generates
  67         and sends to the backend.
  68        </para>
  69       </listitem>
  70      </varlistentry>
  71
  72      <varlistentry>
  73       <term>-q, --quiet</term>
  74       <listitem>
  75        <para>
  76         Do not display a response.
  77        </para>
  78       </listitem>
  79      </varlistentry>
  80
  81      <varlistentry>
  82       <term>-d, --createdb</term>
  83       <listitem>
  84        <para>
  85         Allows the new user to create databases.
  86        </para>
  87       </listitem>
  88      </varlistentry>
  89
  90      <varlistentry>
  91       <term>-D, --no-createdb</term>
  92       <listitem>
  93        <para>
  94         Forbids the new user to create databases.
  95        </para>
  96       </listitem>
  97      </varlistentry>
  98
  99      <varlistentry>
 100       <term>-a, --adduser</term>
 101       <listitem>
 102        <para>
 103         Allows the new user to create other users.
 104        </para>
 105       </listitem>
 106      </varlistentry>
 107
 108      <varlistentry>
 109       <term>-A, --no-adduser</term>
 110       <listitem>
 111        <para>
 112         Forbids the new user to create other users.
 113        </para>
 114       </listitem>
 115      </varlistentry>
 116
 117      <varlistentry>
 118       <term>-P, --pwprompt</term>
 119       <listitem>
 120        <para>
 121        If given, <application>createuser</application> will issue a prompt for
 122        the password of the new user. This is not necessary if you do not plan
 123        on using password authentication.
 124        </para>
 125       </listitem>
 126      </varlistentry>
 127
 128      <varlistentry>
 129       <term><replaceable class="parameter">username</replaceable></term>
 130       <listitem>
 131        <para>
 132         Specifies the name of the <productname>PostgreSQL</productname> user to be created.
 133         This name must be unique among all <productname>PostgreSQL</productname> users.
 134        </para>
 135       </listitem>
 136      </varlistentry>
 137     </variablelist>
 138
 139     You will be prompted for a name and other missing information if it is not
 140     specified on the command line.
 141     </para>
 142
 143     <para>
 144     The options <literal>-h</literal>, <literal>-p</literal>, and <literal>-e</literal>,
 145     are passed on literally to <xref linkend="APP-PSQL" endterm="APP-PSQL-title">. If you
 146     need the <application>psql</application> options <literal>-U</literal> and
 147     <literal>-W</literal> as well, you can uncomment the
 148     respective lines in the source. They are disabled by default because of the potential
 149     conceptual confusion between existing and new users.
 150    </para>
 151   </refsect2>
 152
 153   <refsect2 id="R2-APP-CREATEUSER-2">
 154    <refsect2info>
 155     <date>1999-11-07</date>
 156    </refsect2info>
 157    <title>
 158     Outputs
 159    </title>
 160    <para>
 161     <variablelist>
 162      <varlistentry>
 163       <term><computeroutput>CREATE USER</computeroutput></term>
 164       <listitem>
 165        <para>
 166         All is well.
 167        </para>
 168       </listitem>
 169      </varlistentry>
 170
 171      <varlistentry>
 172       <term><computeroutput>createuser: Creation of user "<replaceable class="parameter">username</replaceable>" failed.</computeroutput></term>
 173       <listitem>
 174        <para>
 175         Something went wrong. The user was not created.
 176        </para>
 177       </listitem>
 178      </varlistentry>
 179
 180     </variablelist>
 181
 182     If there is an error condition, the backend error message will be displayed.
 183     See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
 184     and <xref linkend="APP-PSQL" endterm="APP-PSQL-title"> for possibilities.
 185    </para>
 186   </refsect2>
 187  </refsynopsisdiv>
 188
 189  <refsect1 id="R1-APP-CREATEUSER-1">
 190   <refsect1info>
 191    <date>1998-11-07</date>
 192   </refsect1info>
 193   <title>
 194    Description
 195   </title>
 196   <para>
 197    <application>createuser</application> creates a
 198    new <productname>PostgreSQL</productname> user.
 199    Only users with <literal>usesuper</literal> set in
 200    the <literal>pg_shadow</literal> class can create
 201    new <productname>Postgres</productname> users.
 202   </para>
 203
 204   <para>
 205    <application>createuser</application> is a shell script wrapper around the
 206    <acronym>SQL</acronym> command
 207    <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title"> via
 208    the <productname>PostgreSQL</productname> interactive terminal
 209    <xref linkend="APP-PSQL" endterm="APP-PSQL-title">. Thus, there is nothing
 210    special about creating users via this or other methods. This means
 211    that the <application>psql</application> must be found by the script and that
 212    a database server is running at the targeted host. Also, any default
 213    settings and environment variables available to <application>psql</application>
 214    and the <application>libpq</application> front-end library do apply.
 215   </para>
 216
 217  </refsect1>
 218
 219
 220  <refsect1 id="R1-APP-CREATEUSER-2">
 221   <refsect1info>
 222    <date>1999-11-07</date>
 223   </refsect1info>
 224   <title>
 225    Usage
 226   </title>
 227   <para>
 228    To create a user <literal>joe</literal>
 229    on the default database server:
 230
 231    <programlisting>
 232 $ <userinput>createuser joe</userinput>
 233 Is the new user allowed to create databases? (y/n) <userinput>n</userinput>
 234 Shall the new user be allowed to create more new users? (y/n) <userinput>n</userinput>
 235 CREATE USER
 236    </programlisting>
 237   </para>
 238
 239   <para>
 240    To create the same user <literal>joe</literal>
 241    using the postmaster on host eden, port 5000, avoiding
 242    the prompts and taking a look at the underlying query:
 243
 244    <programlisting>
 245 $ <userinput>createuser -p 5000 -h eden -D -A -e joe</userinput>
 246 QUERY: CREATE USER "joe" NOCREATEDB NOCREATEUSER
 247 CREATE USER
 248    </programlisting>
 249   </para>
 250  </refsect1>
 251
 252 </refentry>
 253
 254 <!-- Keep this comment at the end of the file
 255 Local variables:
 256 mode: sgml
 257 sgml-omittag:nil
 258 sgml-shorttag:t
 259 sgml-minimize-attributes:nil
 260 sgml-always-quote-attributes:t
 261 sgml-indent-step:1
 262 sgml-indent-data:t
 263 sgml-parent-document:nil
 264 sgml-default-dtd-file:"../reference.ced"
 265 sgml-exposed-tags:nil
 266 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 267 sgml-local-ecat-files:nil
 268 End:
 269 -->