begriffs open source - ai-pg/blob - full-docs/txt/app-createuser.txt

   1
   2 createuser
   3
   4    createuser — define a new PostgreSQL user account
   5
   6 Synopsis
   7
   8    createuser [connection-option...] [option...] [username]
   9
  10 Description
  11
  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 role with the SUPERUSER, REPLICATION, or
  18    BYPASSRLS privilege, you must connect as a superuser, not merely with
  19    CREATEROLE privilege. Being a superuser implies the ability to bypass
  20    all access permission checks within the database, so superuser access
  21    should not be granted lightly. CREATEROLE also conveys very extensive
  22    privileges.
  23
  24    createuser is a wrapper around the SQL command CREATE ROLE. There is no
  25    effective difference between creating users via this utility and via
  26    other methods for accessing the server.
  27
  28 Options
  29
  30    createuser accepts the following command-line arguments:
  31
  32    username
  33           Specifies the name of the PostgreSQL user to be created. This
  34           name must be different from all existing roles in this
  35           PostgreSQL installation.
  36
  37    -a role
  38           --with-admin=role
  39           Specifies an existing role that will be automatically added as a
  40           member of the new role with admin option, giving it the right to
  41           grant membership in the new role to others. Multiple existing
  42           roles can be specified by writing multiple -a switches.
  43
  44    -c number
  45           --connection-limit=number
  46           Set a maximum number of connections for the new user. The
  47           default is to set no limit.
  48
  49    -d
  50           --createdb
  51           The new user will be allowed to create databases.
  52
  53    -D
  54           --no-createdb
  55           The new user will not be allowed to create databases. This is
  56           the default.
  57
  58    -e
  59           --echo
  60           Echo the commands that createuser generates and sends to the
  61           server.
  62
  63    -E
  64           --encrypted
  65           This option is obsolete but still accepted for backward
  66           compatibility.
  67
  68    -g role
  69           --member-of=role
  70           --role=role (deprecated)
  71           Specifies the new role should be automatically added as a member
  72           of the specified existing role. Multiple existing roles can be
  73           specified by writing multiple -g switches.
  74
  75    -i
  76           --inherit
  77           The new role will automatically inherit privileges of roles it
  78           is a member of. This is the default.
  79
  80    -I
  81           --no-inherit
  82           The new role will not automatically inherit privileges of roles
  83           it is a member of.
  84
  85    --interactive
  86           Prompt for the user name if none is specified on the command
  87           line, and also prompt for whichever of the options -d/-D, -r/-R,
  88           -s/-S is not specified on the command line. (This was the
  89           default behavior up to PostgreSQL 9.1.)
  90
  91    -l
  92           --login
  93           The new user will be allowed to log in (that is, the user name
  94           can be used as the initial session user identifier). This is the
  95           default.
  96
  97    -L
  98           --no-login
  99           The new user will not be allowed to log in. (A role without
 100           login privilege is still useful as a means of managing database
 101           permissions.)
 102
 103    -m role
 104           --with-member=role
 105           Specifies an existing role that will be automatically added as a
 106           member of the new role. Multiple existing roles can be specified
 107           by writing multiple -m switches.
 108
 109    -P
 110           --pwprompt
 111           If given, createuser will issue a prompt for the password of the
 112           new user. This is not necessary if you do not plan on using
 113           password authentication.
 114
 115    -r
 116           --createrole
 117           The new user will be allowed to create, alter, drop, comment on,
 118           change the security label for other roles; that is, this user
 119           will have CREATEROLE privilege. See role creation for more
 120           details about what capabilities are conferred by this privilege.
 121
 122    -R
 123           --no-createrole
 124           The new user will not be allowed to create new roles. This is
 125           the default.
 126
 127    -s
 128           --superuser
 129           The new user will be a superuser.
 130
 131    -S
 132           --no-superuser
 133           The new user will not be a superuser. This is the default.
 134
 135    -v timestamp
 136           --valid-until=timestamp
 137           Set a date and time after which the role's password is no longer
 138           valid. The default is to set no password expiry date.
 139
 140    -V
 141           --version
 142           Print the createuser version and exit.
 143
 144    --bypassrls
 145           The new user will bypass every row-level security (RLS) policy.
 146
 147    --no-bypassrls
 148           The new user will not bypass row-level security (RLS) policies.
 149           This is the default.
 150
 151    --replication
 152           The new user will have the REPLICATION privilege, which is
 153           described more fully in the documentation for CREATE ROLE.
 154
 155    --no-replication
 156           The new user will not have the REPLICATION privilege, which is
 157           described more fully in the documentation for CREATE ROLE. This
 158           is the default.
 159
 160    -?
 161           --help
 162           Show help about createuser command line arguments, and exit.
 163
 164    createuser also accepts the following command-line arguments for
 165    connection parameters:
 166
 167    -h host
 168           --host=host
 169           Specifies the host name of the machine on which the server is
 170           running. If the value begins with a slash, it is used as the
 171           directory for the Unix domain socket.
 172
 173    -p port
 174           --port=port
 175           Specifies the TCP port or local Unix domain socket file
 176           extension on which the server is listening for connections.
 177
 178    -U username
 179           --username=username
 180           User name to connect as (not the user name to create).
 181
 182    -w
 183           --no-password
 184           Never issue a password prompt. If the server requires password
 185           authentication and a password is not available by other means
 186           such as a .pgpass file, the connection attempt will fail. This
 187           option can be useful in batch jobs and scripts where no user is
 188           present to enter a password.
 189
 190    -W
 191           --password
 192           Force createuser to prompt for a password (for connecting to the
 193           server, not for the password of the new user).
 194
 195           This option is never essential, since createuser will
 196           automatically prompt for a password if the server demands
 197           password authentication. However, createuser will waste a
 198           connection attempt finding out that the server wants a password.
 199           In some cases it is worth typing -W to avoid the extra
 200           connection attempt.
 201
 202 Environment
 203
 204    PGHOST
 205           PGPORT
 206           PGUSER
 207           Default connection parameters
 208
 209    PG_COLOR
 210           Specifies whether to use color in diagnostic messages. Possible
 211           values are always, auto and never.
 212
 213    This utility, like most other PostgreSQL utilities, also uses the
 214    environment variables supported by libpq (see Section 32.15).
 215
 216 Diagnostics
 217
 218    In case of difficulty, see CREATE ROLE and psql for discussions of
 219    potential problems and error messages. The database server must be
 220    running at the targeted host. Also, any default connection settings and
 221    environment variables used by the libpq front-end library will apply.
 222
 223 Examples
 224
 225    To create a user joe on the default database server:
 226 $ createuser joe
 227
 228    To create a user joe on the default database server with prompting for
 229    some additional attributes:
 230 $ createuser --interactive joe
 231 Shall the new role be a superuser? (y/n) n
 232 Shall the new role be allowed to create databases? (y/n) n
 233 Shall the new role be allowed to create more new roles? (y/n) n
 234
 235    To create the same user joe using the server on host eden, port 5000,
 236    with attributes explicitly specified, taking a look at the underlying
 237    command:
 238 $ createuser -h eden -p 5000 -S -D -R -e joe
 239 CREATE ROLE joe NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT LOGIN;
 240
 241    To create the user joe as a superuser, and assign a password
 242    immediately:
 243 $ createuser -P -s -e joe
 244 Enter password for new role: xyzzy
 245 Enter it again: xyzzy
 246 CREATE ROLE joe PASSWORD 'md5b5f5ba1a423792b526f799ae4eb3d59e' SUPERUSER CREATED
 247 B CREATEROLE INHERIT LOGIN;
 248
 249    In the above example, the new password isn't actually echoed when
 250    typed, but we show what was typed for clarity. As you see, the password
 251    is encrypted before it is sent to the client.
 252
 253 See Also
 254
 255    dropuser, CREATE ROLE, createrole_self_grant