begriffs open source - ai-pg/blob - full-docs/txt/sql-createrole.txt

   1
   2 CREATE ROLE
   3
   4    CREATE ROLE — define a new database role
   5
   6 Synopsis
   7
   8 CREATE ROLE name [ [ WITH ] option [ ... ] ]
   9
  10 where option can be:
  11
  12       SUPERUSER | NOSUPERUSER
  13     | CREATEDB | NOCREATEDB
  14     | CREATEROLE | NOCREATEROLE
  15     | INHERIT | NOINHERIT
  16     | LOGIN | NOLOGIN
  17     | REPLICATION | NOREPLICATION
  18     | BYPASSRLS | NOBYPASSRLS
  19     | CONNECTION LIMIT connlimit
  20     | [ ENCRYPTED ] PASSWORD 'password' | PASSWORD NULL
  21     | VALID UNTIL 'timestamp'
  22     | IN ROLE role_name [, ...]
  23     | ROLE role_name [, ...]
  24     | ADMIN role_name [, ...]
  25     | SYSID uid
  26
  27 Description
  28
  29    CREATE ROLE adds a new role to a PostgreSQL database cluster. A role is
  30    an entity that can own database objects and have database privileges; a
  31    role can be considered a “user”, a “group”, or both depending on how it
  32    is used. Refer to Chapter 21 and Chapter 20 for information about
  33    managing users and authentication. You must have CREATEROLE privilege
  34    or be a database superuser to use this command.
  35
  36    Note that roles are defined at the database cluster level, and so are
  37    valid in all databases in the cluster.
  38
  39    During role creation it is possible to immediately assign the newly
  40    created role to be a member of an existing role, and also assign
  41    existing roles to be members of the newly created role. The rules for
  42    which initial role membership options are enabled are described below
  43    in the IN ROLE, ROLE, and ADMIN clauses. The GRANT command has
  44    fine-grained option control during membership creation, and the ability
  45    to modify these options after the new role is created.
  46
  47 Parameters
  48
  49    name
  50           The name of the new role.
  51
  52    SUPERUSER
  53           NOSUPERUSER
  54           These clauses determine whether the new role is a “superuser”,
  55           who can override all access restrictions within the database.
  56           Superuser status is dangerous and should be used only when
  57           really needed. You must yourself be a superuser to create a new
  58           superuser. If not specified, NOSUPERUSER is the default.
  59
  60    CREATEDB
  61           NOCREATEDB
  62           These clauses define a role's ability to create databases. If
  63           CREATEDB is specified, the role being defined will be allowed to
  64           create new databases. Specifying NOCREATEDB will deny a role the
  65           ability to create databases. If not specified, NOCREATEDB is the
  66           default. Only superuser roles or roles with CREATEDB can specify
  67           CREATEDB.
  68
  69    CREATEROLE
  70           NOCREATEROLE
  71           These clauses determine whether a role will be permitted to
  72           create, alter, drop, comment on, and change the security label
  73           for other roles. See role creation for more details about what
  74           capabilities are conferred by this privilege. If not specified,
  75           NOCREATEROLE is the default.
  76
  77    INHERIT
  78           NOINHERIT
  79           This affects the membership inheritance status when this role is
  80           added as a member of another role, both in this and future
  81           commands. Specifically, it controls the inheritance status of
  82           memberships added with this command using the IN ROLE clause,
  83           and in later commands using the ROLE clause. It is also used as
  84           the default inheritance status when adding this role as a member
  85           using the GRANT command. If not specified, INHERIT is the
  86           default.
  87
  88           In PostgreSQL versions before 16, inheritance was a role-level
  89           attribute that controlled all runtime membership checks for that
  90           role.
  91
  92    LOGIN
  93           NOLOGIN
  94           These clauses determine whether a role is allowed to log in;
  95           that is, whether the role can be given as the initial session
  96           authorization name during client connection. A role having the
  97           LOGIN attribute can be thought of as a user. Roles without this
  98           attribute are useful for managing database privileges, but are
  99           not users in the usual sense of the word. If not specified,
 100           NOLOGIN is the default, except when CREATE ROLE is invoked
 101           through its alternative spelling CREATE USER.
 102
 103    REPLICATION
 104           NOREPLICATION
 105           These clauses determine whether a role is a replication role. A
 106           role must have this attribute (or be a superuser) in order to be
 107           able to connect to the server in replication mode (physical or
 108           logical replication) and in order to be able to create or drop
 109           replication slots. A role having the REPLICATION attribute is a
 110           very highly privileged role, and should only be used on roles
 111           actually used for replication. If not specified, NOREPLICATION
 112           is the default. Only superuser roles or roles with REPLICATION
 113           can specify REPLICATION.
 114
 115    BYPASSRLS
 116           NOBYPASSRLS
 117           These clauses determine whether a role bypasses every row-level
 118           security (RLS) policy. NOBYPASSRLS is the default. Only
 119           superuser roles or roles with BYPASSRLS can specify BYPASSRLS.
 120
 121           Note that pg_dump will set row_security to OFF by default, to
 122           ensure all contents of a table are dumped out. If the user
 123           running pg_dump does not have appropriate permissions, an error
 124           will be returned. However, superusers and the owner of the table
 125           being dumped always bypass RLS.
 126
 127    CONNECTION LIMIT connlimit
 128           If role can log in, this specifies how many concurrent
 129           connections the role can make. -1 (the default) means no limit.
 130           Note that only normal connections are counted towards this
 131           limit. Neither prepared transactions nor background worker
 132           connections are counted towards this limit.
 133
 134    [ ENCRYPTED ] PASSWORD 'password'
 135           PASSWORD NULL
 136           Sets the role's password. (A password is only of use for roles
 137           having the LOGIN attribute, but you can nonetheless define one
 138           for roles without it.) If you do not plan to use password
 139           authentication you can omit this option. If no password is
 140           specified, the password will be set to null and password
 141           authentication will always fail for that user. A null password
 142           can optionally be written explicitly as PASSWORD NULL.
 143
 144 Note
 145
 146           Specifying an empty string will also set the password to null,
 147           but that was not the case before PostgreSQL version 10. In
 148           earlier versions, an empty string could be used, or not,
 149           depending on the authentication method and the exact version,
 150           and libpq would refuse to use it in any case. To avoid the
 151           ambiguity, specifying an empty string should be avoided.
 152
 153           The password is always stored encrypted in the system catalogs.
 154           The ENCRYPTED keyword has no effect, but is accepted for
 155           backwards compatibility. The method of encryption is determined
 156           by the configuration parameter password_encryption. If the
 157           presented password string is already in MD5-encrypted or
 158           SCRAM-encrypted format, then it is stored as-is regardless of
 159           password_encryption (since the system cannot decrypt the
 160           specified encrypted password string, to encrypt it in a
 161           different format). This allows reloading of encrypted passwords
 162           during dump/restore.
 163
 164 Warning
 165
 166           Support for MD5-encrypted passwords is deprecated and will be
 167           removed in a future release of PostgreSQL. Refer to Section 20.5
 168           for details about migrating to another password type.
 169
 170    VALID UNTIL 'timestamp'
 171           The VALID UNTIL clause sets a date and time after which the
 172           role's password is no longer valid. If this clause is omitted
 173           the password will be valid for all time.
 174
 175    IN ROLE role_name
 176           The IN ROLE clause causes the new role to be automatically added
 177           as a member of the specified existing roles. The new membership
 178           will have the SET option enabled and the ADMIN option disabled.
 179           The INHERIT option will be enabled unless the NOINHERIT option
 180           is specified.
 181
 182    ROLE role_name
 183           The ROLE clause causes one or more specified existing roles to
 184           be automatically added as members, with the SET option enabled.
 185           This in effect makes the new role a “group”. Roles named in this
 186           clause with the role-level INHERIT attribute will have the
 187           INHERIT option enabled in the new membership. New memberships
 188           will have the ADMIN option disabled.
 189
 190    ADMIN role_name
 191           The ADMIN clause has the same effect as ROLE, but the named
 192           roles are added as members of the new role with ADMIN enabled,
 193           giving them the right to grant membership in the new role to
 194           others.
 195
 196    SYSID uid
 197           The SYSID clause is ignored, but is accepted for backwards
 198           compatibility.
 199
 200 Notes
 201
 202    Use ALTER ROLE to change the attributes of a role, and DROP ROLE to
 203    remove a role. All the attributes specified by CREATE ROLE can be
 204    modified by later ALTER ROLE commands.
 205
 206    The preferred way to add and remove members of roles that are being
 207    used as groups is to use GRANT and REVOKE.
 208
 209    The VALID UNTIL clause defines an expiration time for a password only,
 210    not for the role per se. In particular, the expiration time is not
 211    enforced when logging in using a non-password-based authentication
 212    method.
 213
 214    The role attributes defined here are non-inheritable, i.e., being a
 215    member of a role with, e.g., CREATEDB will not allow the member to
 216    create new databases even if the membership grant has the INHERIT
 217    option. Of course, if the membership grant has the SET option the
 218    member role would be able to SET ROLE to the createdb role and then
 219    create a new database.
 220
 221    The membership grants created by the IN ROLE, ROLE, and ADMIN clauses
 222    have the role executing this command as the grantor.
 223
 224    The INHERIT attribute is the default for reasons of backwards
 225    compatibility: in prior releases of PostgreSQL, users always had access
 226    to all privileges of groups they were members of. However, NOINHERIT
 227    provides a closer match to the semantics specified in the SQL standard.
 228
 229    PostgreSQL includes a program createuser that has the same
 230    functionality as CREATE ROLE (in fact, it calls this command) but can
 231    be run from the command shell.
 232
 233    The CONNECTION LIMIT option is only enforced approximately; if two new
 234    sessions start at about the same time when just one connection “slot”
 235    remains for the role, it is possible that both will fail. Also, the
 236    limit is never enforced for superusers.
 237
 238    Caution must be exercised when specifying an unencrypted password with
 239    this command. The password will be transmitted to the server in
 240    cleartext, and it might also be logged in the client's command history
 241    or the server log. The command createuser, however, transmits the
 242    password encrypted. Also, psql contains a command \password that can be
 243    used to safely change the password later.
 244
 245 Examples
 246
 247    Create a role that can log in, but don't give it a password:
 248 CREATE ROLE jonathan LOGIN;
 249
 250    Create a role with a password:
 251 CREATE USER davide WITH PASSWORD 'jw8s0F4';
 252
 253    (CREATE USER is the same as CREATE ROLE except that it implies LOGIN.)
 254
 255    Create a role with a password that is valid until the end of 2004.
 256    After one second has ticked in 2005, the password is no longer valid.
 257 CREATE ROLE miriam WITH LOGIN PASSWORD 'jw8s0F4' VALID UNTIL '2005-01-01';
 258
 259    Create a role that can create databases and manage roles:
 260 CREATE ROLE admin WITH CREATEDB CREATEROLE;
 261
 262 Compatibility
 263
 264    The CREATE ROLE statement is in the SQL standard, but the standard only
 265    requires the syntax
 266 CREATE ROLE name [ WITH ADMIN role_name ]
 267
 268    Multiple initial administrators, and all the other options of CREATE
 269    ROLE, are PostgreSQL extensions.
 270
 271    The SQL standard defines the concepts of users and roles, but it
 272    regards them as distinct concepts and leaves all commands defining
 273    users to be specified by each database implementation. In PostgreSQL we
 274    have chosen to unify users and roles into a single kind of entity.
 275    Roles therefore have many more optional attributes than they do in the
 276    standard.
 277
 278    The behavior specified by the SQL standard is most closely approximated
 279    creating SQL-standard users as PostgreSQL roles with the NOINHERIT
 280    option, and SQL-standard roles as PostgreSQL roles with the INHERIT
 281    option.
 282
 283    The USER clause has the same behavior as ROLE but has been deprecated:
 284 USER role_name [, ...]
 285
 286    The IN GROUP clause has the same behavior as IN ROLE but has been
 287    deprecated:
 288 IN GROUP role_name [, ...]
 289
 290 See Also
 291
 292    SET ROLE, ALTER ROLE, DROP ROLE, GRANT, REVOKE, createuser,
 293    createrole_self_grant