From: Bruce Momjian Date: Fri, 3 Mar 2006 03:06:17 +0000 (+0000) Subject: Appended is a small documentation patch that adds a note to the CREATE X-Git-Url: http://git.postgresql.org/gitweb/static/gitweb.js?a=commitdiff_plain;h=95b7010509afdeb3303bc987d8370a827c189aba;p=users%2Fbernd%2Fpostgres.git Appended is a small documentation patch that adds a note to the CREATE ROLE page, based on what Tom Lane told me here: http://archives.postgresql.org/pgsql-general/2005-11/msg00998.php Joachim Wieland --- diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml new file mode 100644 index 0000000000..42248cb2f7 --- /dev/null +++ b/doc/src/sgml/ref/create_role.sgml @@ -0,0 +1,471 @@ + + + + + CREATE ROLE + SQL - Language Statements + + + + CREATE ROLE + define a new database role + + + + CREATE ROLE + + + + +CREATE ROLE name [ [ WITH ] option [ ... ] ] + +where option can be: + + SUPERUSER | NOSUPERUSER + | CREATEDB | NOCREATEDB + | CREATEROLE | NOCREATEROLE + | CREATEUSER | NOCREATEUSER + | INHERIT | NOINHERIT + | LOGIN | NOLOGIN + | CONNECTION LIMIT connlimit + | [ ENCRYPTED | UNENCRYPTED ] PASSWORD 'password' + | VALID UNTIL 'timestamp' + | IN ROLE rolename [, ...] + | IN GROUP rolename [, ...] + | ROLE rolename [, ...] + | ADMIN rolename [, ...] + | USER rolename [, ...] + | SYSID uid + + + + + Description + + + CREATE ROLE adds a new role to a + PostgreSQL database cluster. A role is + an entity that can own database objects and have database privileges; + a role can be considered a user, a group, or both + depending on how it is used. Refer to + and for information about managing + users and authentication. You must have CREATEROLE + privilege or be a database superuser to use this command. + + + + Note that roles are defined at the database cluster + level, and so are valid in all databases in the cluster. + + + + + Parameters + + + + name + + + The name of the new role. + + + + + + SUPERUSER + NOSUPERUSER + + + These clauses determine whether the new role is a superuser, + who can override all access restrictions within the database. + Superuser status is dangerous and should be used only when really + needed. You must yourself be a superuser to create a new superuser. + If not specified, + NOSUPERUSER is the default. + + + + + + CREATEDB + NOCREATEDB + + + These clauses define a role's ability to create databases. If + CREATEDB is specified, the role being + defined will be allowed to create new databases. Specifying + NOCREATEDB will deny a role the ability to + create databases. If not specified, + NOCREATEDB is the default. + + + + + + CREATEROLE + NOCREATEROLE + + + These clauses determine whether a role will be permitted to + create new roles (that is, execute CREATE ROLE). + A role with CREATEROLE privilege can also alter + and drop other roles. + If not specified, + NOCREATEROLE is the default. + + + + + + CREATEUSER + NOCREATEUSER + + + These clauses are an obsolete, but still accepted, spelling of + SUPERUSER and NOSUPERUSER. + Note that they are not equivalent to + CREATEROLE as one might naively expect! + + + + + + INHERIT + NOINHERIT + + + These clauses determine whether a role inherits the + privileges of roles it is a member of. + A role with the INHERIT attribute can automatically + use whatever database privileges have been granted to all roles + it is directly or indirectly a member of. + Without INHERIT, membership in another role + only grants the ability to SET ROLE to that other role; + the privileges of the other role are only available after having + done so. + If not specified, + INHERIT is the default. + + + + + + LOGIN + NOLOGIN + + + These clauses determine whether a role is allowed to log in; + that is, whether the role can be given as the initial session + authorization name during client connection. A role having + the LOGIN attribute can be thought of as a user. + Roles without this attribute are useful for managing database + privileges, but are not users in the usual sense of the word. + If not specified, + NOLOGIN is the default, except when + CREATE ROLE is invoked through its alternate spelling + CREATE USER. + + + + + + CONNECTION LIMIT connlimit + + + If role can log in, this specifies how many concurrent connections + the role can make. -1 (the default) means no limit. + + + + + + PASSWORD password + + + Sets the role's password. (A password is only of use for + roles having the LOGIN attribute, but you can + nonetheless define one for roles without it.) + If you do not plan to use password + authentication you can omit this option. + + + + + + ENCRYPTED + UNENCRYPTED + + + These key words control whether the password is stored + encrypted in the system catalogs. (If neither is specified, + the default behavior is determined by the configuration + parameter .) If the + presented password string is already in MD5-encrypted format, + then it is stored encrypted as-is, regardless of whether + ENCRYPTED or UNENCRYPTED is specified + (since the system cannot decrypt the specified encrypted + password string). This allows reloading of encrypted + passwords during dump/restore. + + + + Note that older clients may lack support for the MD5 + authentication mechanism that is needed to work with passwords + that are stored encrypted. + + + + + + VALID UNTIL 'timestamp' + + + The VALID UNTIL clause sets a date and + time after which the role's password is no longer valid. If + this clause is omitted the password will be valid for all time. + + + + + + IN ROLE rolename + + + The IN ROLE clause lists one or more existing + roles to which the new role will be immediately added as a new + member. (Note that there is no option to add the new role as an + administrator; use a separate GRANT command to do that.) + + + + + + IN GROUP rolename + + + IN GROUP is an obsolete spelling of + IN ROLE. + + + + + + ROLE rolename + + + The ROLE clause lists one or more existing + roles which are automatically added as members of the new role. + (This in effect makes the new role a group.) + + + + + + ADMIN rolename + + + The ADMIN clause is like ROLE, + but the named roles are added to the new role WITH ADMIN + OPTION, giving them the right to grant membership in this role + to others. + + + + + + USER rolename + + + The USER clause is an obsolete spelling of + the ROLE clause. + + + + + + SYSID uid + + + The SYSID clause is ignored, but is accepted + for backwards compatibility. + + + + + + + + Notes + + + Use to + change the attributes of a role, and to remove a role. All the attributes + specified by CREATE ROLE can be modified by later + ALTER ROLE commands. + + + + The preferred way to add and remove members of roles that are being + used as groups is to use + and + . + + + + The VALID UNTIL clause defines an expiration time for a + password only, not for the role per se. In + particular, the expiration time is not enforced when logging in using + a non-password-based authentication method. + + + + The INHERIT attribute governs inheritance of grantable + privileges (that is, access privileges for database objects and role + memberships). It does not apply to the special role attributes set by + CREATE ROLE and ALTER ROLE. For example, being + a member of a role with CREATEDB privilege does not immediately + grant the ability to create databases, even if INHERIT is set; + it would be necessary to become that role via + before + creating a database. + + + + The INHERIT attribute is the default for reasons of backwards + compatibility: in prior releases of PostgreSQL, + users always had access to all privileges of groups they were members of. + However, NOINHERIT provides a closer match to the semantics + specified in the SQL standard. + + + + Be careful with the CREATEROLE privilege. There is no concept of + inheritance for the privileges of a CREATEROLE-role. That + means that even if a role does not have a certain privilege but is allowed + to create other roles, it can easily create another role with different + privileges than its own (except for creating roles with superuser + privileges). For example, if the role user has the + CREATEROLE privilege but not the CREATEDB privilege, + nonetheless it can create a new role with the CREATEDB + privilege. Therefore, regard roles that have the CREATEROLE + privilege as almost-superuser-roles. + + + + PostgreSQL includes a program that has + the same functionality as CREATE ROLE (in fact, + it calls this command) but can be run from the command shell. + + + + The CONNECTION LIMIT option is only enforced approximately; + if two new sessions start at about the same time when just one + connection slot remains for the role, it is possible that + both will fail. Also, the limit is never enforced for superusers. + + + + + Examples + + + Create a role that can log in, but don't give it a password: + +CREATE ROLE jonathan LOGIN; + + + + + Create a role with a password: + +CREATE USER davide WITH PASSWORD 'jw8s0F4'; + + (CREATE USER is the same as CREATE ROLE except + that it implies LOGIN.) + + + + Create a role with a password that is valid until the end of 2004. + After one second has ticked in 2005, the password is no longer + valid. + + +CREATE ROLE miriam WITH LOGIN PASSWORD 'jw8s0F4' VALID UNTIL '2005-01-01'; + + + + + Create a role that can create databases and manage roles: + +CREATE ROLE admin WITH CREATEDB CREATEROLE; + + + + + + Compatibility + + + The CREATE ROLE statement is in the SQL standard, + but the standard only requires the syntax + +CREATE ROLE name [ WITH ADMIN rolename ] + + Multiple initial administrators, and all the other options of + CREATE ROLE, are + PostgreSQL extensions. + + + + The SQL standard defines the concepts of users and roles, but it + regards them as distinct concepts and leaves all commands defining + users to be specified by each database implementation. In + PostgreSQL we have chosen to unify + users and roles into a single kind of entity. Roles therefore + have many more optional attributes than they do in the standard. + + + + The behavior specified by the SQL standard is most closely approximated + by giving users the NOINHERIT attribute, while roles are + given the INHERIT attribute. + + + + + See Also + + + + + + + + + + + + +