1CREATEUSER(1) PostgreSQL 14.3 Documentation CREATEUSER(1)
2
6 createuser - define a new PostgreSQL user account
7
9 createuser [connection-option...] [option...] [username]
10
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 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 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
27 createuser accepts the following command-line arguments:
28 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 -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 -d
40 --createdb
41 The new user will be allowed to create databases.
42 -D
44 --no-createdb
45 The new user will not be allowed to create databases. This is the
46 default.
47 -e
49 --echo
50 Echo the commands that createuser generates and sends to the
51 server.
52 -E
54 --encrypted
55 This option is obsolete but still accepted for backward
56 compatibility.
57 -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 -i
65 --inherit
66 The new role will automatically inherit privileges of roles it is a
67 member of. This is the default.
68 -I
70 --no-inherit
71 The new role will not automatically inherit privileges of roles it
72 is a member of.
73 --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 -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 -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 -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 -r
99 --createrole
100 The new user will be allowed to create new roles (that is, this
101 user will have CREATEROLE privilege).
102 -R
104 --no-createrole
105 The new user will not be allowed to create new roles. This is the
106 default.
107 -s
109 --superuser
110 The new user will be a superuser.
111 -S
113 --no-superuser
114 The new user will not be a superuser. This is the default.
115 -V
117 --version
118 Print the createuser version and exit.
119 --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 --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 -?
131 --help
132 Show help about createuser command line arguments, and exit.
133 createuser also accepts the following command-line arguments for
135 connection parameters:
136 -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 -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 -U username
149 --username=username
150 User name to connect as (not the user name to create).
151 -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 -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 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
172 PGHOST
173 PGPORT
174 PGUSER
175 Default connection parameters
176 PG_COLOR
178 Specifies whether to use color in diagnostic messages. Possible
179 values are always, auto and never.
180 This utility, like most other PostgreSQL utilities, also uses the
182 environment variables supported by libpq (see Section 34.15).
183
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
192 To create a user joe on the default database server:
193 $ createuser joe
195 To create a user joe on the default database server with prompting for
197 some additional attributes:
198 $ 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 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 $ createuser -h eden -p 5000 -S -D -R -e joe
209 CREATE ROLE joe NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT LOGIN;
210 To create the user joe as a superuser, and assign a password
212 immediately:
213 $ 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 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
224 dropuser(1), CREATE ROLE (CREATE_ROLE(7))
225PostgreSQL 14.3 2022 CREATEUSER(1)