1<!--
2doc/src/sgml/ref/createuser.sgml
3PostgreSQL documentation
4-->
5
6<refentry id="app-createuser">
7 <indexterm zone="app-createuser">
8  <primary>createuser</primary>
9 </indexterm>
10
11 <refmeta>
12  <refentrytitle><application>createuser</application></refentrytitle>
13  <manvolnum>1</manvolnum>
14  <refmiscinfo>Application</refmiscinfo>
15 </refmeta>
16
17 <refnamediv>
18  <refname>createuser</refname>
19  <refpurpose>define a new <productname>PostgreSQL</productname> user account</refpurpose>
20 </refnamediv>
21
22 <refsynopsisdiv>
23  <cmdsynopsis>
24   <command>createuser</command>
25   <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
26   <arg rep="repeat"><replaceable>option</replaceable></arg>
27   <arg choice="opt"><replaceable>username</replaceable></arg>
28  </cmdsynopsis>
29 </refsynopsisdiv>
30
31
32 <refsect1>
33  <title>Description</title>
34  <para>
35   <application>createuser</application> creates a
36   new <productname>PostgreSQL</productname> user (or more precisely, a role).
37   Only superusers and users with <literal>CREATEROLE</literal> privilege can create
38   new users, so <application>createuser</application> must be
39   invoked by someone who can connect as a superuser or a user with
40   <literal>CREATEROLE</literal> privilege.
41  </para>
42
43  <para>
44   If you wish to create a new superuser, you must connect as a
45   superuser, not merely with <literal>CREATEROLE</literal> privilege.
46   Being a superuser implies the ability to bypass all access permission
47   checks within the database, so superuser access should not be granted lightly.
48  </para>
49
50  <para>
51   <application>createuser</application> is a wrapper around the
52   <acronym>SQL</acronym> command <link linkend="sql-createrole"><command>CREATE ROLE</command></link>.
53   There is no effective difference between creating users via
54   this utility and via other methods for accessing the server.
55  </para>
56
57 </refsect1>
58
59
60 <refsect1>
61  <title>Options</title>
62
63  <para>
64   <application>createuser</application> accepts the following command-line arguments:
65
66    <variablelist>
67     <varlistentry>
68      <term><replaceable class="parameter">username</replaceable></term>
69      <listitem>
70       <para>
71        Specifies the name of the <productname>PostgreSQL</productname> user
72        to be created.
73        This name must be different from all existing roles in this
74        <productname>PostgreSQL</productname> installation.
75       </para>
76      </listitem>
77     </varlistentry>
78
79     <varlistentry>
80      <term><option>-c <replaceable class="parameter">number</replaceable></option></term>
81      <term><option>--connection-limit=<replaceable class="parameter">number</replaceable></option></term>
82      <listitem>
83       <para>
84        Set a maximum number of connections for the new user.
85        The default is to set no limit.
86       </para>
87      </listitem>
88     </varlistentry>
89
90     <varlistentry>
91      <term><option>-d</option></term>
92      <term><option>--createdb</option></term>
93      <listitem>
94       <para>
95        The new user will be allowed to create databases.
96       </para>
97      </listitem>
98     </varlistentry>
99
100     <varlistentry>
101      <term><option>-D</option></term>
102      <term><option>--no-createdb</option></term>
103      <listitem>
104       <para>
105        The new user will not be allowed to create databases.  This is the
106        default.
107       </para>
108      </listitem>
109     </varlistentry>
110
111     <varlistentry>
112      <term><option>-e</option></term>
113      <term><option>--echo</option></term>
114      <listitem>
115       <para>
116        Echo the commands that <application>createuser</application> generates
117        and sends to the server.
118       </para>
119      </listitem>
120     </varlistentry>
121
122     <varlistentry>
123      <term><option>-E</option></term>
124      <term><option>--encrypted</option></term>
125      <listitem>
126       <para>
127        This option is obsolete but still accepted for backward
128        compatibility.
129       </para>
130      </listitem>
131     </varlistentry>
132
133     <varlistentry>
134      <term><option>-g <replaceable class="parameter">role</replaceable></option></term>
135      <term><option>--role=<replaceable class="parameter">role</replaceable></option></term>
136      <listitem>
137       <para>
138         Indicates role to which this role will be added immediately as a new
139         member. Multiple roles to which this role will be added as a member
140         can be specified by writing multiple
141         <option>-g</option> switches.
142         </para>
143      </listitem>
144     </varlistentry>
145
146     <varlistentry>
147      <term><option>-i</option></term>
148      <term><option>--inherit</option></term>
149      <listitem>
150       <para>
151        The new role will automatically inherit privileges of roles
152        it is a member of.
153        This is the default.
154       </para>
155      </listitem>
156     </varlistentry>
157
158     <varlistentry>
159      <term><option>-I</option></term>
160      <term><option>--no-inherit</option></term>
161      <listitem>
162       <para>
163        The new role will not automatically inherit privileges of roles
164        it is a member of.
165       </para>
166      </listitem>
167     </varlistentry>
168
169     <varlistentry>
170      <term><option>--interactive</option></term>
171      <listitem>
172       <para>
173        Prompt for the user name if none is specified on the command line, and
174        also prompt for whichever of the options
175        <option>-d</option>/<option>-D</option>,
176        <option>-r</option>/<option>-R</option>,
177        <option>-s</option>/<option>-S</option> is not specified on the command
178        line.  (This was the default behavior up to PostgreSQL 9.1.)
179       </para>
180      </listitem>
181     </varlistentry>
182
183     <varlistentry>
184      <term><option>-l</option></term>
185      <term><option>--login</option></term>
186      <listitem>
187       <para>
188        The new user will be allowed to log in (that is, the user name
189        can be used as the initial session user identifier).
190        This is the default.
191       </para>
192      </listitem>
193     </varlistentry>
194
195     <varlistentry>
196      <term><option>-L</option></term>
197      <term><option>--no-login</option></term>
198      <listitem>
199       <para>
200        The new user will not be allowed to log in.
201        (A role without login privilege is still useful as a means of
202        managing database permissions.)
203       </para>
204      </listitem>
205     </varlistentry>
206
207     <varlistentry>
208      <term><option>-P</option></term>
209      <term><option>--pwprompt</option></term>
210      <listitem>
211       <para>
212       If given, <application>createuser</application> will issue a prompt for
213       the password of the new user. This is not necessary if you do not plan
214       on using password authentication.
215       </para>
216      </listitem>
217     </varlistentry>
218
219     <varlistentry>
220      <term><option>-r</option></term>
221      <term><option>--createrole</option></term>
222      <listitem>
223       <para>
224        The new user will be allowed to create new roles (that is,
225        this user will have <literal>CREATEROLE</literal> privilege).
226       </para>
227      </listitem>
228     </varlistentry>
229
230     <varlistentry>
231      <term><option>-R</option></term>
232      <term><option>--no-createrole</option></term>
233      <listitem>
234       <para>
235        The new user will not be allowed to create new roles.  This is the
236        default.
237       </para>
238      </listitem>
239     </varlistentry>
240
241     <varlistentry>
242      <term><option>-s</option></term>
243      <term><option>--superuser</option></term>
244      <listitem>
245       <para>
246        The new user will be a superuser.
247       </para>
248      </listitem>
249     </varlistentry>
250
251     <varlistentry>
252      <term><option>-S</option></term>
253      <term><option>--no-superuser</option></term>
254      <listitem>
255       <para>
256        The new user will not be a superuser.  This is the default.
257       </para>
258      </listitem>
259     </varlistentry>
260
261     <varlistentry>
262       <term><option>-V</option></term>
263       <term><option>--version</option></term>
264       <listitem>
265       <para>
266       Print the <application>createuser</application> version and exit.
267       </para>
268       </listitem>
269     </varlistentry>
270
271     <varlistentry>
272      <term><option>--replication</option></term>
273      <listitem>
274       <para>
275        The new user will have the <literal>REPLICATION</literal> privilege,
276        which is described more fully in the documentation for <xref
277        linkend="sql-createrole"/>.
278       </para>
279      </listitem>
280     </varlistentry>
281
282     <varlistentry>
283      <term><option>--no-replication</option></term>
284      <listitem>
285       <para>
286        The new user will not have the <literal>REPLICATION</literal>
287        privilege, which is described more fully in the documentation for <xref
288        linkend="sql-createrole"/>.
289       </para>
290      </listitem>
291     </varlistentry>
292
293     <varlistentry>
294       <term><option>-?</option></term>
295       <term><option>--help</option></term>
296       <listitem>
297       <para>
298       Show help about <application>createuser</application> command line
299       arguments, and exit.
300       </para>
301       </listitem>
302     </varlistentry>
303
304    </variablelist>
305  </para>
306
307  <para>
308   <application>createuser</application> also accepts the following
309   command-line arguments for connection parameters:
310
311   <variablelist>
312     <varlistentry>
313      <term><option>-h <replaceable class="parameter">host</replaceable></option></term>
314      <term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
315      <listitem>
316       <para>
317        Specifies the host name of the machine on which the
318        server
319        is running.  If the value begins with a slash, it is used
320        as the directory for the Unix domain socket.
321       </para>
322      </listitem>
323     </varlistentry>
324
325     <varlistentry>
326      <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
327      <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
328      <listitem>
329       <para>
330        Specifies the TCP port or local Unix domain socket file
331        extension on which the server
332        is listening for connections.
333       </para>
334      </listitem>
335     </varlistentry>
336
337     <varlistentry>
338      <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
339      <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
340      <listitem>
341       <para>
342        User name to connect as (not the user name to create).
343       </para>
344      </listitem>
345     </varlistentry>
346
347     <varlistentry>
348      <term><option>-w</option></term>
349      <term><option>--no-password</option></term>
350      <listitem>
351       <para>
352        Never issue a password prompt.  If the server requires
353        password authentication and a password is not available by
354        other means such as a <filename>.pgpass</filename> file, the
355        connection attempt will fail.  This option can be useful in
356        batch jobs and scripts where no user is present to enter a
357        password.
358       </para>
359      </listitem>
360     </varlistentry>
361
362     <varlistentry>
363      <term><option>-W</option></term>
364      <term><option>--password</option></term>
365      <listitem>
366       <para>
367        Force <application>createuser</application> to prompt for a
368        password (for connecting to the server, not for the
369        password of the new user).
370       </para>
371
372       <para>
373        This option is never essential, since
374        <application>createuser</application> will automatically prompt
375        for a password if the server demands password authentication.
376        However, <application>createuser</application> will waste a
377        connection attempt finding out that the server wants a password.
378        In some cases it is worth typing <option>-W</option> to avoid the extra
379        connection attempt.
380       </para>
381      </listitem>
382     </varlistentry>
383   </variablelist>
384  </para>
385 </refsect1>
386
387
388 <refsect1>
389  <title>Environment</title>
390
391  <variablelist>
392   <varlistentry>
393    <term><envar>PGHOST</envar></term>
394    <term><envar>PGPORT</envar></term>
395    <term><envar>PGUSER</envar></term>
396
397    <listitem>
398     <para>
399      Default connection parameters
400     </para>
401    </listitem>
402   </varlistentry>
403
404   <varlistentry>
405    <term><envar>PG_COLOR</envar></term>
406    <listitem>
407     <para>
408      Specifies whether to use color in diagnostic messages. Possible values
409      are <literal>always</literal>, <literal>auto</literal> and
410      <literal>never</literal>.
411     </para>
412    </listitem>
413   </varlistentry>
414  </variablelist>
415
416  <para>
417   This utility, like most other <productname>PostgreSQL</productname> utilities,
418   also uses the environment variables supported by <application>libpq</application>
419   (see <xref linkend="libpq-envars"/>).
420  </para>
421
422 </refsect1>
423
424
425 <refsect1>
426  <title>Diagnostics</title>
427
428  <para>
429   In case of difficulty, see <xref linkend="sql-createrole"/>
430   and <xref linkend="app-psql"/> for
431   discussions of potential problems and error messages.
432   The database server must be running at the
433   targeted host.  Also, any default connection settings and environment
434   variables used by the <application>libpq</application> front-end
435   library will apply.
436  </para>
437
438 </refsect1>
439
440
441 <refsect1>
442  <title>Examples</title>
443
444   <para>
445    To create a user <literal>joe</literal> on the default database
446    server:
447<screen>
448<prompt>$ </prompt><userinput>createuser joe</userinput>
449</screen>
450   </para>
451
452   <para>
453    To create a user <literal>joe</literal> on the default database
454    server with prompting for some additional attributes:
455<screen>
456<prompt>$ </prompt><userinput>createuser --interactive joe</userinput>
457<computeroutput>Shall the new role be a superuser? (y/n) </computeroutput><userinput>n</userinput>
458<computeroutput>Shall the new role be allowed to create databases? (y/n) </computeroutput><userinput>n</userinput>
459<computeroutput>Shall the new role be allowed to create more new roles? (y/n) </computeroutput><userinput>n</userinput>
460</screen>
461   </para>
462
463   <para>
464    To create the same user <literal>joe</literal> using the
465    server on host <literal>eden</literal>, port 5000, with attributes explicitly specified,
466    taking a look at the underlying command:
467<screen>
468<prompt>$ </prompt><userinput>createuser -h eden -p 5000 -S -D -R -e joe</userinput>
469<computeroutput>CREATE ROLE joe NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT LOGIN;</computeroutput>
470</screen>
471   </para>
472
473   <para>
474    To create the user <literal>joe</literal> as a superuser,
475    and assign a password immediately:
476<screen>
477<prompt>$ </prompt><userinput>createuser -P -s -e joe</userinput>
478<computeroutput>Enter password for new role: </computeroutput><userinput>xyzzy</userinput>
479<computeroutput>Enter it again: </computeroutput><userinput>xyzzy</userinput>
480<computeroutput>CREATE ROLE joe PASSWORD 'md5b5f5ba1a423792b526f799ae4eb3d59e' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;</computeroutput>
481</screen>
482    In the above example, the new password isn't actually echoed when typed,
483    but we show what was typed for clarity.  As you see, the password is
484    encrypted before it is sent to the client.
485   </para>
486 </refsect1>
487
488
489 <refsect1>
490  <title>See Also</title>
491
492  <simplelist type="inline">
493   <member><xref linkend="app-dropuser"/></member>
494   <member><xref linkend="sql-createrole"/></member>
495  </simplelist>
496 </refsect1>
497
498</refentry>
499