Debian Codegraph @

doc/src/sgml/ref/createuser.sgml

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