begriffs open source - ai-pg/blob - full-docs/src/sgml/man1/createuser.1

   1 '\" t
   2 .\"     Title: createuser
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "CREATEUSER" "1" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 createuser \- define a new PostgreSQL user account
  32 .SH "SYNOPSIS"
  33 .HP \w'\fBcreateuser\fR\ 'u
  34 \fBcreateuser\fR [\fIconnection\-option\fR...] [\fIoption\fR...] [\fIusername\fR]
  35 .SH "DESCRIPTION"
  36 .PP
  37 createuser
  38 creates a new
  39 PostgreSQL
  40 user (or more precisely, a role)\&. Only superusers and users with
  41 CREATEROLE
  42 privilege can create new users, so
  43 createuser
  44 must be invoked by someone who can connect as a superuser or a user with
  45 CREATEROLE
  46 privilege\&.
  47 .PP
  48 If you wish to create a role with the
  49 SUPERUSER,
  50 REPLICATION, or
  51 BYPASSRLS
  52 privilege, you must connect as a superuser, not merely with
  53 CREATEROLE
  54 privilege\&. Being a superuser implies the ability to bypass all access permission checks within the database, so superuser access should not be granted lightly\&.
  55 CREATEROLE
  56 also conveys
  57 very extensive privileges\&.
  58 .PP
  59 createuser
  60 is a wrapper around the
  61 SQL
  62 command
  63 \fBCREATE ROLE\fR\&. There is no effective difference between creating users via this utility and via other methods for accessing the server\&.
  64 .SH "OPTIONS"
  65 .PP
  66 createuser
  67 accepts the following command\-line arguments:
  68 .PP
  69 \fIusername\fR
  70 .RS 4
  71 Specifies the name of the
  72 PostgreSQL
  73 user to be created\&. This name must be different from all existing roles in this
  74 PostgreSQL
  75 installation\&.
  76 .RE
  77 .PP
  78 \fB\-a \fR\fB\fIrole\fR\fR
  79 .br
  80 \fB\-\-with\-admin=\fR\fB\fIrole\fR\fR
  81 .RS 4
  82 Specifies an existing role that will be automatically added as a member of the new role with admin option, giving it the right to grant membership in the new role to others\&. Multiple existing roles can be specified by writing multiple
  83 \fB\-a\fR
  84 switches\&.
  85 .RE
  86 .PP
  87 \fB\-c \fR\fB\fInumber\fR\fR
  88 .br
  89 \fB\-\-connection\-limit=\fR\fB\fInumber\fR\fR
  90 .RS 4
  91 Set a maximum number of connections for the new user\&. The default is to set no limit\&.
  92 .RE
  93 .PP
  94 \fB\-d\fR
  95 .br
  96 \fB\-\-createdb\fR
  97 .RS 4
  98 The new user will be allowed to create databases\&.
  99 .RE
 100 .PP
 101 \fB\-D\fR
 102 .br
 103 \fB\-\-no\-createdb\fR
 104 .RS 4
 105 The new user will not be allowed to create databases\&. This is the default\&.
 106 .RE
 107 .PP
 108 \fB\-e\fR
 109 .br
 110 \fB\-\-echo\fR
 111 .RS 4
 112 Echo the commands that
 113 createuser
 114 generates and sends to the server\&.
 115 .RE
 116 .PP
 117 \fB\-E\fR
 118 .br
 119 \fB\-\-encrypted\fR
 120 .RS 4
 121 This option is obsolete but still accepted for backward compatibility\&.
 122 .RE
 123 .PP
 124 \fB\-g \fR\fB\fIrole\fR\fR
 125 .br
 126 \fB\-\-member\-of=\fR\fB\fIrole\fR\fR
 127 .br
 128 \fB\-\-role=\fR\fB\fIrole\fR\fR (deprecated)
 129 .RS 4
 130 Specifies the new role should be automatically added as a member of the specified existing role\&. Multiple existing roles can be specified by writing multiple
 131 \fB\-g\fR
 132 switches\&.
 133 .RE
 134 .PP
 135 \fB\-i\fR
 136 .br
 137 \fB\-\-inherit\fR
 138 .RS 4
 139 The new role will automatically inherit privileges of roles it is a member of\&. This is the default\&.
 140 .RE
 141 .PP
 142 \fB\-I\fR
 143 .br
 144 \fB\-\-no\-inherit\fR
 145 .RS 4
 146 The new role will not automatically inherit privileges of roles it is a member of\&.
 147 .RE
 148 .PP
 149 \fB\-\-interactive\fR
 150 .RS 4
 151 Prompt for the user name if none is specified on the command line, and also prompt for whichever of the options
 152 \fB\-d\fR/\fB\-D\fR,
 153 \fB\-r\fR/\fB\-R\fR,
 154 \fB\-s\fR/\fB\-S\fR
 155 is not specified on the command line\&. (This was the default behavior up to PostgreSQL 9\&.1\&.)
 156 .RE
 157 .PP
 158 \fB\-l\fR
 159 .br
 160 \fB\-\-login\fR
 161 .RS 4
 162 The new user will be allowed to log in (that is, the user name can be used as the initial session user identifier)\&. This is the default\&.
 163 .RE
 164 .PP
 165 \fB\-L\fR
 166 .br
 167 \fB\-\-no\-login\fR
 168 .RS 4
 169 The new user will not be allowed to log in\&. (A role without login privilege is still useful as a means of managing database permissions\&.)
 170 .RE
 171 .PP
 172 \fB\-m \fR\fB\fIrole\fR\fR
 173 .br
 174 \fB\-\-with\-member=\fR\fB\fIrole\fR\fR
 175 .RS 4
 176 Specifies an existing role that will be automatically added as a member of the new role\&. Multiple existing roles can be specified by writing multiple
 177 \fB\-m\fR
 178 switches\&.
 179 .RE
 180 .PP
 181 \fB\-P\fR
 182 .br
 183 \fB\-\-pwprompt\fR
 184 .RS 4
 185 If given,
 186 createuser
 187 will issue a prompt for the password of the new user\&. This is not necessary if you do not plan on using password authentication\&.
 188 .RE
 189 .PP
 190 \fB\-r\fR
 191 .br
 192 \fB\-\-createrole\fR
 193 .RS 4
 194 The new user will be allowed to create, alter, drop, comment on, change the security label for other roles; that is, this user will have
 195 CREATEROLE
 196 privilege\&. See
 197 role creation
 198 for more details about what capabilities are conferred by this privilege\&.
 199 .RE
 200 .PP
 201 \fB\-R\fR
 202 .br
 203 \fB\-\-no\-createrole\fR
 204 .RS 4
 205 The new user will not be allowed to create new roles\&. This is the default\&.
 206 .RE
 207 .PP
 208 \fB\-s\fR
 209 .br
 210 \fB\-\-superuser\fR
 211 .RS 4
 212 The new user will be a superuser\&.
 213 .RE
 214 .PP
 215 \fB\-S\fR
 216 .br
 217 \fB\-\-no\-superuser\fR
 218 .RS 4
 219 The new user will not be a superuser\&. This is the default\&.
 220 .RE
 221 .PP
 222 \fB\-v \fR\fB\fItimestamp\fR\fR
 223 .br
 224 \fB\-\-valid\-until=\fR\fB\fItimestamp\fR\fR
 225 .RS 4
 226 Set a date and time after which the role\*(Aqs password is no longer valid\&. The default is to set no password expiry date\&.
 227 .RE
 228 .PP
 229 \fB\-V\fR
 230 .br
 231 \fB\-\-version\fR
 232 .RS 4
 233 Print the
 234 createuser
 235 version and exit\&.
 236 .RE
 237 .PP
 238 \fB\-\-bypassrls\fR
 239 .RS 4
 240 The new user will bypass every row\-level security (RLS) policy\&.
 241 .RE
 242 .PP
 243 \fB\-\-no\-bypassrls\fR
 244 .RS 4
 245 The new user will not bypass row\-level security (RLS) policies\&. This is the default\&.
 246 .RE
 247 .PP
 248 \fB\-\-replication\fR
 249 .RS 4
 250 The new user will have the
 251 REPLICATION
 252 privilege, which is described more fully in the documentation for
 253 CREATE ROLE (\fBCREATE_ROLE\fR(7))\&.
 254 .RE
 255 .PP
 256 \fB\-\-no\-replication\fR
 257 .RS 4
 258 The new user will not have the
 259 REPLICATION
 260 privilege, which is described more fully in the documentation for
 261 CREATE ROLE (\fBCREATE_ROLE\fR(7))\&. This is the default\&.
 262 .RE
 263 .PP
 264 \fB\-?\fR
 265 .br
 266 \fB\-\-help\fR
 267 .RS 4
 268 Show help about
 269 createuser
 270 command line arguments, and exit\&.
 271 .RE
 272 .PP
 273 createuser
 274 also accepts the following command\-line arguments for connection parameters:
 275 .PP
 276 \fB\-h \fR\fB\fIhost\fR\fR
 277 .br
 278 \fB\-\-host=\fR\fB\fIhost\fR\fR
 279 .RS 4
 280 Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix domain socket\&.
 281 .RE
 282 .PP
 283 \fB\-p \fR\fB\fIport\fR\fR
 284 .br
 285 \fB\-\-port=\fR\fB\fIport\fR\fR
 286 .RS 4
 287 Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&.
 288 .RE
 289 .PP
 290 \fB\-U \fR\fB\fIusername\fR\fR
 291 .br
 292 \fB\-\-username=\fR\fB\fIusername\fR\fR
 293 .RS 4
 294 User name to connect as (not the user name to create)\&.
 295 .RE
 296 .PP
 297 \fB\-w\fR
 298 .br
 299 \fB\-\-no\-password\fR
 300 .RS 4
 301 Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a
 302 \&.pgpass
 303 file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&.
 304 .RE
 305 .PP
 306 \fB\-W\fR
 307 .br
 308 \fB\-\-password\fR
 309 .RS 4
 310 Force
 311 createuser
 312 to prompt for a password (for connecting to the server, not for the password of the new user)\&.
 313 .sp
 314 This option is never essential, since
 315 createuser
 316 will automatically prompt for a password if the server demands password authentication\&. However,
 317 createuser
 318 will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing
 319 \fB\-W\fR
 320 to avoid the extra connection attempt\&.
 321 .RE
 322 .SH "ENVIRONMENT"
 323 .PP
 324 \fBPGHOST\fR
 325 .br
 326 \fBPGPORT\fR
 327 .br
 328 \fBPGUSER\fR
 329 .RS 4
 330 Default connection parameters
 331 .RE
 332 .PP
 333 \fBPG_COLOR\fR
 334 .RS 4
 335 Specifies whether to use color in diagnostic messages\&. Possible values are
 336 always,
 337 auto
 338 and
 339 never\&.
 340 .RE
 341 .PP
 342 This utility, like most other
 343 PostgreSQL
 344 utilities, also uses the environment variables supported by
 345 libpq
 346 (see
 347 Section\ \&32.15)\&.
 348 .SH "DIAGNOSTICS"
 349 .PP
 350 In case of difficulty, see
 351 CREATE ROLE (\fBCREATE_ROLE\fR(7))
 352 and
 353 \fBpsql\fR(1)
 354 for discussions of potential problems and error messages\&. The database server must be running at the targeted host\&. Also, any default connection settings and environment variables used by the
 355 libpq
 356 front\-end library will apply\&.
 357 .SH "EXAMPLES"
 358 .PP
 359 To create a user
 360 joe
 361 on the default database server:
 362 .sp
 363 .if n \{\
 364 .RS 4
 365 .\}
 366 .nf
 367 $ \fBcreateuser joe\fR
 368 .fi
 369 .if n \{\
 370 .RE
 371 .\}
 372 .PP
 373 To create a user
 374 joe
 375 on the default database server with prompting for some additional attributes:
 376 .sp
 377 .if n \{\
 378 .RS 4
 379 .\}
 380 .nf
 381 $ \fBcreateuser \-\-interactive joe\fR
 382 Shall the new role be a superuser? (y/n) \fBn\fR
 383 Shall the new role be allowed to create databases? (y/n) \fBn\fR
 384 Shall the new role be allowed to create more new roles? (y/n) \fBn\fR
 385 .fi
 386 .if n \{\
 387 .RE
 388 .\}
 389 .PP
 390 To create the same user
 391 joe
 392 using the server on host
 393 eden, port 5000, with attributes explicitly specified, taking a look at the underlying command:
 394 .sp
 395 .if n \{\
 396 .RS 4
 397 .\}
 398 .nf
 399 $ \fBcreateuser \-h eden \-p 5000 \-S \-D \-R \-e joe\fR
 400 CREATE ROLE joe NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT LOGIN;
 401 .fi
 402 .if n \{\
 403 .RE
 404 .\}
 405 .PP
 406 To create the user
 407 joe
 408 as a superuser, and assign a password immediately:
 409 .sp
 410 .if n \{\
 411 .RS 4
 412 .\}
 413 .nf
 414 $ \fBcreateuser \-P \-s \-e joe\fR
 415 Enter password for new role: \fBxyzzy\fR
 416 Enter it again: \fBxyzzy\fR
 417 CREATE ROLE joe PASSWORD \*(Aqmd5b5f5ba1a423792b526f799ae4eb3d59e\*(Aq SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;
 418 .fi
 419 .if n \{\
 420 .RE
 421 .\}
 422 .sp
 423 In the above example, the new password isn\*(Aqt actually echoed when typed, but we show what was typed for clarity\&. As you see, the password is encrypted before it is sent to the client\&.
 424 .SH "SEE ALSO"
 425 \fBdropuser\fR(1), CREATE ROLE (\fBCREATE_ROLE\fR(7)), createrole_self_grant