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.7 1999/12/07 22:41:41 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>-i, --sysid <replaceable class="parameter">uid</replaceable></term>
 130       <listitem>
 131        <para>
 132        Allows you to pick a non-default user id for the new user. This is not
 133        necessary, but some people like it.
 134        </para>
 135       </listitem>
 136      </varlistentry>
 137
 138      <varlistentry>
 139       <term><replaceable class="parameter">username</replaceable></term>
 140       <listitem>
 141        <para>
 142         Specifies the name of the <productname>PostgreSQL</productname> user to be created.
 143         This name must be unique among all <productname>PostgreSQL</productname> users.
 144        </para>
 145       </listitem>
 146      </varlistentry>
 147     </variablelist>
 148
 149     You will be prompted for a name and other missing information if it is not
 150     specified on the command line.
 151     </para>
 152
 153     <para>
 154     The options <literal>-h</literal>, <literal>-p</literal>, and <literal>-e</literal>,
 155     are passed on literally to <xref linkend="APP-PSQL" endterm="APP-PSQL-title">. The
 156     <application>psql</application> options <literal>-U</literal> and <literal>-W</literal>
 157     are available as well, but their use can be confusing in this context.
 158    </para>
 159   </refsect2>
 160
 161   <refsect2 id="R2-APP-CREATEUSER-2">
 162    <refsect2info>
 163     <date>1999-11-07</date>
 164    </refsect2info>
 165    <title>
 166     Outputs
 167    </title>
 168    <para>
 169     <variablelist>
 170      <varlistentry>
 171       <term><computeroutput>CREATE USER</computeroutput></term>
 172       <listitem>
 173        <para>
 174         All is well.
 175        </para>
 176       </listitem>
 177      </varlistentry>
 178
 179      <varlistentry>
 180       <term><computeroutput>createuser: Creation of user "<replaceable class="parameter">username</replaceable>" failed.</computeroutput></term>
 181       <listitem>
 182        <para>
 183         Something went wrong. The user was not created.
 184        </para>
 185       </listitem>
 186      </varlistentry>
 187
 188     </variablelist>
 189
 190     If there is an error condition, the backend error message will be displayed.
 191     See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
 192     and <xref linkend="APP-PSQL" endterm="APP-PSQL-title"> for possibilities.
 193    </para>
 194   </refsect2>
 195  </refsynopsisdiv>
 196
 197  <refsect1 id="R1-APP-CREATEUSER-1">
 198   <refsect1info>
 199    <date>1998-11-07</date>
 200   </refsect1info>
 201   <title>
 202    Description
 203   </title>
 204   <para>
 205    <application>createuser</application> creates a
 206    new <productname>PostgreSQL</productname> user.
 207    Only users with <literal>usesuper</literal> set in
 208    the <literal>pg_shadow</literal> class can create
 209    new <productname>Postgres</productname> users.
 210   </para>
 211
 212   <para>
 213    <application>createuser</application> is a shell script wrapper around the
 214    <acronym>SQL</acronym> command
 215    <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title"> via
 216    the <productname>PostgreSQL</productname> interactive terminal
 217    <xref linkend="APP-PSQL" endterm="APP-PSQL-title">. Thus, there is nothing
 218    special about creating users via this or other methods. This means
 219    that the <application>psql</application> must be found by the script and that
 220    a database server is running at the targeted host. Also, any default
 221    settings and environment variables available to <application>psql</application>
 222    and the <application>libpq</application> front-end library do apply.
 223   </para>
 224
 225  </refsect1>
 226
 227
 228  <refsect1 id="R1-APP-CREATEUSER-2">
 229   <refsect1info>
 230    <date>1999-11-07</date>
 231   </refsect1info>
 232   <title>
 233    Usage
 234   </title>
 235   <para>
 236    To create a user <literal>joe</literal>
 237    on the default database server:
 238
 239    <programlisting>
 240 $ <userinput>createuser joe</userinput>
 241 Is the new user allowed to create databases? (y/n) <userinput>n</userinput>
 242 Shall the new user be allowed to create more new users? (y/n) <userinput>n</userinput>
 243 CREATE USER
 244    </programlisting>
 245   </para>
 246
 247   <para>
 248    To create the same user <literal>joe</literal>
 249    using the postmaster on host eden, port 5000, avoiding
 250    the prompts and taking a look at the underlying query:
 251
 252    <programlisting>
 253 $ <userinput>createuser -p 5000 -h eden -D -A -e joe</userinput>
 254 CREATE USER "joe" NOCREATEDB NOCREATEUSER
 255 CREATE USER
 256    </programlisting>
 257   </para>
 258  </refsect1>
 259
 260 </refentry>
 261
 262 <!-- Keep this comment at the end of the file
 263 Local variables:
 264 mode: sgml
 265 sgml-omittag:nil
 266 sgml-shorttag:t
 267 sgml-minimize-attributes:nil
 268 sgml-always-quote-attributes:t
 269 sgml-indent-step:1
 270 sgml-indent-data:t
 271 sgml-parent-document:nil
 272 sgml-default-dtd-file:"../reference.ced"
 273 sgml-exposed-tags:nil
 274 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 275 sgml-local-ecat-files:nil
 276 End:
 277 -->