1CREATEUSER(1)            PostgreSQL 14.3 Documentation           CREATEUSER(1)
2
3
4

NAME

6       createuser - define a new PostgreSQL user account
7

SYNOPSIS

9       createuser [connection-option...] [option...] [username]
10

DESCRIPTION

12       createuser creates a new PostgreSQL user (or more precisely, a role).
13       Only superusers and users with CREATEROLE privilege can create new
14       users, so createuser must be invoked by someone who can connect as a
15       superuser or a user with CREATEROLE privilege.
16
17       If you wish to create a new superuser, you must connect as a superuser,
18       not merely with CREATEROLE privilege. Being a superuser implies the
19       ability to bypass all access permission checks within the database, so
20       superuser access should not be granted lightly.
21
22       createuser is a wrapper around the SQL command CREATE ROLE. There is no
23       effective difference between creating users via this utility and via
24       other methods for accessing the server.
25

OPTIONS

27       createuser accepts the following command-line arguments:
28
29       username
30           Specifies the name of the PostgreSQL user to be created. This name
31           must be different from all existing roles in this PostgreSQL
32           installation.
33
34       -c number
35       --connection-limit=number
36           Set a maximum number of connections for the new user. The default
37           is to set no limit.
38
39       -d
40       --createdb
41           The new user will be allowed to create databases.
42
43       -D
44       --no-createdb
45           The new user will not be allowed to create databases. This is the
46           default.
47
48       -e
49       --echo
50           Echo the commands that createuser generates and sends to the
51           server.
52
53       -E
54       --encrypted
55           This option is obsolete but still accepted for backward
56           compatibility.
57
58       -g role
59       --role=role
60           Indicates role to which this role will be added immediately as a
61           new member. Multiple roles to which this role will be added as a
62           member can be specified by writing multiple -g switches.
63
64       -i
65       --inherit
66           The new role will automatically inherit privileges of roles it is a
67           member of. This is the default.
68
69       -I
70       --no-inherit
71           The new role will not automatically inherit privileges of roles it
72           is a member of.
73
74       --interactive
75           Prompt for the user name if none is specified on the command line,
76           and also prompt for whichever of the options -d/-D, -r/-R, -s/-S is
77           not specified on the command line. (This was the default behavior
78           up to PostgreSQL 9.1.)
79
80       -l
81       --login
82           The new user will be allowed to log in (that is, the user name can
83           be used as the initial session user identifier). This is the
84           default.
85
86       -L
87       --no-login
88           The new user will not be allowed to log in. (A role without login
89           privilege is still useful as a means of managing database
90           permissions.)
91
92       -P
93       --pwprompt
94           If given, createuser will issue a prompt for the password of the
95           new user. This is not necessary if you do not plan on using
96           password authentication.
97
98       -r
99       --createrole
100           The new user will be allowed to create new roles (that is, this
101           user will have CREATEROLE privilege).
102
103       -R
104       --no-createrole
105           The new user will not be allowed to create new roles. This is the
106           default.
107
108       -s
109       --superuser
110           The new user will be a superuser.
111
112       -S
113       --no-superuser
114           The new user will not be a superuser. This is the default.
115
116       -V
117       --version
118           Print the createuser version and exit.
119
120       --replication
121           The new user will have the REPLICATION privilege, which is
122           described more fully in the documentation for CREATE ROLE
123           (CREATE_ROLE(7)).
124
125       --no-replication
126           The new user will not have the REPLICATION privilege, which is
127           described more fully in the documentation for CREATE ROLE
128           (CREATE_ROLE(7)).
129
130       -?
131       --help
132           Show help about createuser command line arguments, and exit.
133
134       createuser also accepts the following command-line arguments for
135       connection parameters:
136
137       -h host
138       --host=host
139           Specifies the host name of the machine on which the server is
140           running. If the value begins with a slash, it is used as the
141           directory for the Unix domain socket.
142
143       -p port
144       --port=port
145           Specifies the TCP port or local Unix domain socket file extension
146           on which the server is listening for connections.
147
148       -U username
149       --username=username
150           User name to connect as (not the user name to create).
151
152       -w
153       --no-password
154           Never issue a password prompt. If the server requires password
155           authentication and a password is not available by other means such
156           as a .pgpass file, the connection attempt will fail. This option
157           can be useful in batch jobs and scripts where no user is present to
158           enter a password.
159
160       -W
161       --password
162           Force createuser to prompt for a password (for connecting to the
163           server, not for the password of the new user).
164
165           This option is never essential, since createuser will automatically
166           prompt for a password if the server demands password
167           authentication. However, createuser will waste a connection attempt
168           finding out that the server wants a password. In some cases it is
169           worth typing -W to avoid the extra connection attempt.
170

ENVIRONMENT

172       PGHOST
173       PGPORT
174       PGUSER
175           Default connection parameters
176
177       PG_COLOR
178           Specifies whether to use color in diagnostic messages. Possible
179           values are always, auto and never.
180
181       This utility, like most other PostgreSQL utilities, also uses the
182       environment variables supported by libpq (see Section 34.15).
183

DIAGNOSTICS

185       In case of difficulty, see CREATE ROLE (CREATE_ROLE(7)) and psql(1) for
186       discussions of potential problems and error messages. The database
187       server must be running at the targeted host. Also, any default
188       connection settings and environment variables used by the libpq
189       front-end library will apply.
190

EXAMPLES

192       To create a user joe on the default database server:
193
194           $ createuser joe
195
196       To create a user joe on the default database server with prompting for
197       some additional attributes:
198
199           $ createuser --interactive joe
200           Shall the new role be a superuser? (y/n) n
201           Shall the new role be allowed to create databases? (y/n) n
202           Shall the new role be allowed to create more new roles? (y/n) n
203
204       To create the same user joe using the server on host eden, port 5000,
205       with attributes explicitly specified, taking a look at the underlying
206       command:
207
208           $ createuser -h eden -p 5000 -S -D -R -e joe
209           CREATE ROLE joe NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT LOGIN;
210
211       To create the user joe as a superuser, and assign a password
212       immediately:
213
214           $ createuser -P -s -e joe
215           Enter password for new role: xyzzy
216           Enter it again: xyzzy
217           CREATE ROLE joe PASSWORD 'md5b5f5ba1a423792b526f799ae4eb3d59e' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;
218
219       In the above example, the new password isn't actually echoed when
220       typed, but we show what was typed for clarity. As you see, the password
221       is encrypted before it is sent to the client.
222

SEE ALSO

224       dropuser(1), CREATE ROLE (CREATE_ROLE(7))
225
226
227
228PostgreSQL 14.3                      2022                        CREATEUSER(1)
Impressum