2 doc/src/sgml/ref/createuser.sgml
3 PostgreSQL documentation
6 <refentry id="APP-CREATEUSER">
8 <refentrytitle><application>createuser</application></refentrytitle>
9 <manvolnum>1</manvolnum>
10 <refmiscinfo>Application</refmiscinfo>
14 <refname>createuser</refname>
15 <refpurpose>define a new <productname>PostgreSQL</productname> user account</refpurpose>
18 <indexterm zone="app-createuser">
19 <primary>createuser</primary>
24 <command>createuser</command>
25 <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
26 <arg rep="repeat"><replaceable>option</replaceable></arg>
27 <arg><replaceable>username</replaceable></arg>
33 <title>Description</title>
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</> 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</> privilege.
44 If you wish to create a new superuser, you must connect as a
45 superuser, not merely with <literal>CREATEROLE</> privilege.
46 Being a superuser implies the ability to bypass all access permission
47 checks within the database, so superuserdom should not be granted lightly.
51 <application>createuser</application> is a wrapper around the
52 <acronym>SQL</acronym> command <xref linkend="SQL-CREATEROLE">.
53 There is no effective difference between creating users via
54 this utility and via other methods for accessing the server.
61 <title>Options</title>
64 <application>createuser</> accepts the following command-line arguments:
68 <term><replaceable class="parameter">username</replaceable></term>
71 Specifies the name of the <productname>PostgreSQL</productname> user
73 This name must be different from all existing roles in this
74 <productname>PostgreSQL</productname> installation.
80 <term><option>-c <replaceable class="parameter">number</replaceable></></term>
81 <term><option>--connection-limit=<replaceable class="parameter">number</replaceable></></term>
84 Set a maximum number of connections for the new user.
85 The default is to set no limit.
91 <term><option>-d</></term>
92 <term><option>--createdb</></term>
95 The new user will be allowed to create databases.
101 <term><option>-D</></term>
102 <term><option>--no-createdb</></term>
105 The new user will not be allowed to create databases.
111 <term><option>-e</></term>
112 <term><option>--echo</></term>
115 Echo the commands that <application>createuser</application> generates
116 and sends to the server.
122 <term><option>-E</></term>
123 <term><option>--encrypted</></term>
126 Encrypts the user's password stored in the database. If not
127 specified, the default password behavior is used.
133 <term><option>-i</></term>
134 <term><option>--inherit</></term>
137 The new role will automatically inherit privileges of roles
145 <term><option>-I</></term>
146 <term><option>--no-inherit</></term>
149 The new role will not automatically inherit privileges of roles
156 <term><option>-l</></term>
157 <term><option>--login</></term>
160 The new user will be allowed to log in (that is, the user name
161 can be used as the initial session user identifier).
168 <term><option>-L</></term>
169 <term><option>--no-login</></term>
172 The new user will not be allowed to log in.
173 (A role without login privilege is still useful as a means of
174 managing database permissions.)
180 <term><option>-N</></term>
181 <term><option>--unencrypted</></term>
184 Does not encrypt the user's password stored in the database. If
185 not specified, the default password behavior is used.
191 <term><option>-P</></term>
192 <term><option>--pwprompt</></term>
195 If given, <application>createuser</application> will issue a prompt for
196 the password of the new user. This is not necessary if you do not plan
197 on using password authentication.
203 <term><option>-r</></term>
204 <term><option>--createrole</></term>
207 The new user will be allowed to create new roles (that is,
208 this user will have <literal>CREATEROLE</> privilege).
214 <term><option>-R</></term>
215 <term><option>--no-createrole</></term>
218 The new user will not be allowed to create new roles.
224 <term><option>-s</></term>
225 <term><option>--superuser</></term>
228 The new user will be a superuser.
234 <term><option>-S</></term>
235 <term><option>--no-superuser</></term>
238 The new user will not be a superuser.
244 <term><option>--replication</></term>
247 The new user will have the REPLICATION privilege, which is
248 described more fully in the documentation for
249 <xref linkend="sql-createrole">.
255 <term><option>--no-replication</></term>
258 The new user will not have the REPLICATION privilege, which is
259 described more fully in the documentation for
260 <xref linkend="sql-createrole">.
266 <term><option>-V</></term>
267 <term><option>--version</></term>
270 Print the <application>createuser</application> version and exit.
276 <term><option>-?</></term>
277 <term><option>--help</></term>
280 Show help about <application>createuser</application> command line
290 You will be prompted for a name and other missing information if it
291 is not specified on the command line.
295 <application>createuser</application> also accepts the following
296 command-line arguments for connection parameters:
300 <term><option>-h <replaceable class="parameter">host</replaceable></></term>
301 <term><option>--host=<replaceable class="parameter">host</replaceable></></term>
304 Specifies the host name of the machine on which the
306 is running. If the value begins with a slash, it is used
307 as the directory for the Unix domain socket.
313 <term><option>-p <replaceable class="parameter">port</replaceable></></term>
314 <term><option>--port=<replaceable class="parameter">port</replaceable></></term>
317 Specifies the TCP port or local Unix domain socket file
318 extension on which the server
319 is listening for connections.
325 <term><option>-U <replaceable class="parameter">username</replaceable></></term>
326 <term><option>--username=<replaceable class="parameter">username</replaceable></></term>
329 User name to connect as (not the user name to create).
335 <term><option>-w</></term>
336 <term><option>--no-password</></term>
339 Never issue a password prompt. If the server requires
340 password authentication and a password is not available by
341 other means such as a <filename>.pgpass</filename> file, the
342 connection attempt will fail. This option can be useful in
343 batch jobs and scripts where no user is present to enter a
350 <term><option>-W</></term>
351 <term><option>--password</></term>
354 Force <application>createuser</application> to prompt for a
355 password (for connecting to the server, not for the
356 password of the new user).
360 This option is never essential, since
361 <application>createuser</application> will automatically prompt
362 for a password if the server demands password authentication.
363 However, <application>createuser</application> will waste a
364 connection attempt finding out that the server wants a password.
365 In some cases it is worth typing <option>-W</> to avoid the extra
376 <title>Environment</title>
380 <term><envar>PGHOST</envar></term>
381 <term><envar>PGPORT</envar></term>
382 <term><envar>PGUSER</envar></term>
386 Default connection parameters
393 This utility, like most other <productname>PostgreSQL</> utilities,
394 also uses the environment variables supported by <application>libpq</>
395 (see <xref linkend="libpq-envars">).
402 <title>Diagnostics</title>
405 In case of difficulty, see <xref linkend="SQL-CREATEROLE">
406 and <xref linkend="APP-PSQL"> for
407 discussions of potential problems and error messages.
408 The database server must be running at the
409 targeted host. Also, any default connection settings and environment
410 variables used by the <application>libpq</application> front-end
418 <title>Examples</title>
421 To create a user <literal>joe</literal> on the default database
424 <prompt>$ </prompt><userinput>createuser joe</userinput>
425 <computeroutput>Shall the new role be a superuser? (y/n) </computeroutput><userinput>n</userinput>
426 <computeroutput>Shall the new role be allowed to create databases? (y/n) </computeroutput><userinput>n</userinput>
427 <computeroutput>Shall the new role be allowed to create more new roles? (y/n) </computeroutput><userinput>n</userinput>
432 To create the same user <literal>joe</literal> using the
433 server on host <literal>eden</>, port 5000, avoiding the prompts and
434 taking a look at the underlying command:
436 <prompt>$ </prompt><userinput>createuser -h eden -p 5000 -S -D -R -e joe</userinput>
437 <computeroutput>CREATE ROLE joe NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT LOGIN;</computeroutput>
442 To create the user <literal>joe</literal> as a superuser,
443 and assign a password immediately:
445 <prompt>$ </prompt><userinput>createuser -P -s -e joe</userinput>
446 <computeroutput>Enter password for new role: </computeroutput><userinput>xyzzy</userinput>
447 <computeroutput>Enter it again: </computeroutput><userinput>xyzzy</userinput>
448 <computeroutput>CREATE ROLE joe PASSWORD 'md5b5f5ba1a423792b526f799ae4eb3d59e' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;</computeroutput>
450 In the above example, the new password isn't actually echoed when typed,
451 but we show what was typed for clarity. As you see, the password is
452 encrypted before it is sent to the client. If the option <option>--unencrypted</option>
453 is used, the password <emphasis>will</> appear in the echoed command
454 (and possibly also in the server log and elsewhere),
455 so you don't want to use <option>-e</> in that case, if
456 anyone else can see your screen.
462 <title>See Also</title>
464 <simplelist type="inline">
465 <member><xref linkend="app-dropuser"></member>
466 <member><xref linkend="sql-createrole"></member>