From 58d214e51fe50b10b4439da6ec263d54c155afbf Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Tue, 26 Jul 2005 23:24:02 +0000 Subject: [PATCH] Basic documentation for ROLEs. The user-manag chapter still needs to be rewritten, but at least the reference pages are reasonably sane. --- doc/src/sgml/ref/allfiles.sgml | 5 +- doc/src/sgml/ref/alter_group.sgml | 34 +- doc/src/sgml/ref/alter_role.sgml | 272 ++++++++++++++++ doc/src/sgml/ref/alter_user.sgml | 237 +------------- doc/src/sgml/ref/create_group.sgml | 104 ++---- doc/src/sgml/ref/create_role.sgml | 428 +++++++++++++++++++++++++ doc/src/sgml/ref/create_user.sgml | 218 ++----------- doc/src/sgml/ref/drop_group.sgml | 51 +-- doc/src/sgml/ref/drop_role.sgml | 126 ++++++++ doc/src/sgml/ref/drop_user.sgml | 66 +--- doc/src/sgml/ref/grant.sgml | 73 ++++- doc/src/sgml/ref/revoke.sgml | 32 +- doc/src/sgml/ref/set_role.sgml | 46 ++- doc/src/sgml/ref/set_session_auth.sgml | 6 +- doc/src/sgml/reference.sgml | 5 +- 15 files changed, 1061 insertions(+), 642 deletions(-) create mode 100644 doc/src/sgml/ref/alter_role.sgml create mode 100644 doc/src/sgml/ref/create_role.sgml create mode 100644 doc/src/sgml/ref/drop_role.sgml diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml index d993b64ad0..98dfbda111 100644 --- a/doc/src/sgml/ref/allfiles.sgml +++ b/doc/src/sgml/ref/allfiles.sgml @@ -1,5 +1,5 @@ @@ -16,6 +16,7 @@ Complete list of usable sgml source files in this directory. + @@ -44,6 +45,7 @@ Complete list of usable sgml source files in this directory. + @@ -68,6 +70,7 @@ Complete list of usable sgml source files in this directory. + diff --git a/doc/src/sgml/ref/alter_group.sgml b/doc/src/sgml/ref/alter_group.sgml index aa025e684a..884f1e22c0 100644 --- a/doc/src/sgml/ref/alter_group.sgml +++ b/doc/src/sgml/ref/alter_group.sgml @@ -1,5 +1,5 @@ @@ -11,7 +11,7 @@ PostgreSQL documentation ALTER GROUP - change a user group + change role name or membership @@ -32,16 +32,25 @@ ALTER GROUP groupname RENAME TO ALTER GROUP changes the attributes of a user group. + This is an obsolete command, though still accepted for backwards + compatibility, because groups (and users too) have been superseded by the + more general concept of roles. The first two variants add users to a group or remove them from a group. - Only database superusers can use this command. + (Any role can play the part of either a user or a + group for this purpose.) These variants are effectively + equivalent to granting or revoking membership in the role named as the + group; so the preferred way to do this is to use + or + . - The third variant changes the name of the group. Only a database - superuser can rename groups. + The third variant changes the name of the group. This is exactly + equivalent to renaming the role with + . @@ -53,7 +62,7 @@ ALTER GROUP groupname RENAME TO groupname - The name of the group to modify. + The name of the group (role) to modify. @@ -62,9 +71,9 @@ ALTER GROUP groupname RENAME TO username - Users that are to be added to or removed from the group. The users - must already exist; ALTER GROUP does not create or - drop users. + Users (roles) that are to be added to or removed from the group. + The users must already exist; ALTER GROUP does not + create or drop users. @@ -103,7 +112,7 @@ ALTER GROUP workers DROP USER beth; There is no ALTER GROUP statement in the SQL - standard. The concept of roles is similar. + standard. @@ -111,8 +120,9 @@ ALTER GROUP workers DROP USER beth; See Also - - + + + diff --git a/doc/src/sgml/ref/alter_role.sgml b/doc/src/sgml/ref/alter_role.sgml new file mode 100644 index 0000000000..3e87cf0176 --- /dev/null +++ b/doc/src/sgml/ref/alter_role.sgml @@ -0,0 +1,272 @@ + + + + + ALTER ROLE + SQL - Language Statements + + + + ALTER ROLE + change a database role + + + + ALTER ROLE + + + + +ALTER ROLE name [ [ WITH ] option [ ... ] ] + +where option can be: + + SUPERUSER | NOSUPERUSER + | CREATEDB | NOCREATEDB + | CREATEROLE | NOCREATEROLE + | CREATEUSER | NOCREATEUSER + | INHERIT | NOINHERIT + | LOGIN | NOLOGIN + | [ ENCRYPTED | UNENCRYPTED ] PASSWORD 'password' + | VALID UNTIL 'timestamp' + +ALTER ROLE name RENAME TO newname + +ALTER ROLE name SET parameter { TO | = } { value | DEFAULT } +ALTER ROLE name RESET parameter + + + + + Description + + + ALTER ROLE changes the attributes of a + PostgreSQL role. + + + + The first variant of this command listed in the synopsis can change + many of the role attributes that can be specified in + , + which see for details. (All the possible attributes are covered, + except that there are no options for adding or removing memberships; use + and + for that.) + Attributes not mentioned in the command retain their previous settings. + Database superusers can change any of these settings for any role. + Roles having CREATEROLE privilege can change any of these + settings, but only for non-superuser roles. + Ordinary roles can only change their own password. + + + + The second variant changes the name of the role. + Database superusers can rename any role. + Roles having CREATEROLE privilege can rename non-superuser + roles. + The current session user cannot be renamed. + (Connect as a different user if you need to do that.) + Because MD5-encrypted passwords use the role name as + cryptographic salt, renaming a role clears its password if the + password is MD5-encrypted. + + + + The third and the fourth variant change a role's session default for + a specified configuration variable. Whenever the role subsequently + starts a new session, the specified value becomes the session default, + overriding whatever setting is present in postgresql.conf + or has been received from the postmaster command line. + (For a role without LOGIN privilege, session defaults have + no effect.) + Ordinary roles can change their own session defaults. + Superusers can change anyone's session defaults. + Roles having CREATEROLE privilege can change defaults for + non-superuser roles. + Certain variables cannot be set this way, or can only be + set if a superuser issues the command. + + + + + Parameters + + + + name + + + The name of the role whose attributes are to be altered. + + + + + + SUPERUSER + NOSUPERUSER + CREATEDB + NOCREATEDB + CREATEROLE + NOCREATEROLE + CREATEUSER + NOCREATEUSER + INHERIT + NOINHERIT + LOGIN + NOLOGIN + PASSWORD password + ENCRYPTED + UNENCRYPTED + VALID UNTIL 'timestamp' + + + These clauses alter attributes originally set by + , + which see for more information. + + + + + + newname + + + The new name of the role. + + + + + + parameter + value + + + Set this role's session default for the specified configuration + parameter to the given value. If + value is DEFAULT + or, equivalently, RESET is used, the + role-specific variable setting is removed, so the role will + inherit the system-wide default setting in new sessions. Use + RESET ALL to clear all role-specific settings. + + + + See and for more information about allowed + parameter names and values. + + + + + + + + Notes + + + Use + to add new roles, and to remove a role. + + + + ALTER ROLE cannot change a role's memberships. + Use and + + to do that. + + + + It is also possible to tie a + session default to a specific database rather than to a role; see + . + Role-specific settings override database-specific + ones if there is a conflict. + + + + + Examples + + + Change a role's password: + + +ALTER ROLE davide WITH PASSWORD 'hu8jmn3'; + + + + + Change a password expiration date, specifying that the password + should expire at midday on 4th May 2015 using + the time zone which is one hour ahead of UTC: + +ALTER ROLE chris VALID UNTIL 'May 4 12:00:00 2015 +1'; + + + + + Make a password valid forever: + +ALTER ROLE fred VALID UNTIL 'infinity'; + + + + + Give a role the ability to create other roles and new databases: + + +ALTER ROLE miriam CREATEROLE CREATEDB; + + + + + Give a role a non-default setting of the + parameter: + + +ALTER ROLE worker_bee SET maintenance_work_mem = 100000; + + + + + + Compatibility + + + The ALTER ROLE statement is a + PostgreSQL extension. + + + + + See Also + + + + + + + + + + diff --git a/doc/src/sgml/ref/alter_user.sgml b/doc/src/sgml/ref/alter_user.sgml index 960016d2ed..2844a63d08 100644 --- a/doc/src/sgml/ref/alter_user.sgml +++ b/doc/src/sgml/ref/alter_user.sgml @@ -1,5 +1,5 @@ @@ -11,7 +11,7 @@ PostgreSQL documentation ALTER USER - change a database user account + change a database role @@ -23,11 +23,15 @@ PostgreSQL documentation ALTER USER name [ [ WITH ] option [ ... ] ] where option can be: - - CREATEDB | NOCREATEDB - | CREATEUSER | NOCREATEUSER - | [ ENCRYPTED | UNENCRYPTED ] PASSWORD 'password' - | VALID UNTIL 'abstime' + + SUPERUSER | NOSUPERUSER + | CREATEDB | NOCREATEDB + | CREATEROLE | NOCREATEROLE + | CREATEUSER | NOCREATEUSER + | INHERIT | NOINHERIT + | LOGIN | NOLOGIN + | [ ENCRYPTED | UNENCRYPTED ] PASSWORD 'password' + | VALID UNTIL 'timestamp' ALTER USER name RENAME TO newname @@ -40,218 +44,9 @@ ALTER USER name RESET Description - ALTER USER changes the attributes of a - PostgreSQL user account. Attributes not - mentioned in the command retain their previous settings. - - - - The first variant of this command listed in the synopsis changes certain - per-user privileges and authentication settings. (See below for - details.) Database superusers can change any of these settings for any - user. Ordinary users can only change their own password. - - - - The second variant changes the name of the user. Only a database - superuser can rename user accounts. The current session user cannot be - renamed. (Connect as a different user if you need to do that.) - Because MD5-encrypted passwords use the user name as - cryptographic salt, renaming a user clears their MD5 - password. - - - - The third and the fourth variant change a user's session default for - a specified configuration variable. Whenever the user subsequently - starts a new session, the specified value becomes the session default, - overriding whatever setting is present in postgresql.conf - or has been received from the postmaster command line. - Ordinary users can change their own session defaults. - Superusers can change anyone's session defaults. - Certain variables cannot be set this way, or can only be - set by a superuser. - - - - - Parameters - - - - name - - - The name of the user whose attributes are to be altered. - - - - - - CREATEDB - NOCREATEDB - - - These clauses define a user's ability to create databases. If - CREATEDB is specified, the user - will be allowed to create his own databases. Using - NOCREATEDB will deny a user the ability to - create databases. (If the user is also a superuser, then this - setting has no real effect.) - - - - - - CREATEUSER - NOCREATEUSER - - - These clauses determine whether a user will be permitted to - create new users himself. CREATEUSER will also make - the user a superuser, who can override all access restrictions. - - - - - - password - - - The new password to be used for this account. - - - - - - ENCRYPTED - UNENCRYPTED - - - These key words control whether the password is stored - encrypted in pg_shadow. (See - - for more information about this choice.) - - - - - - abstime - - - The date (and, optionally, the time) - at which this user's password is to expire. To set the password - never to expire, use 'infinity'. - - - - - - newname - - - The new name of the user. - - - - - - parameter - value - - - Set this user's session default for the specified configuration - parameter to the given value. If - value is DEFAULT - or, equivalently, RESET is used, the - user-specific variable setting is removed, so the user will - inherit the system-wide default setting in new sessions. Use - RESET ALL to clear all user-specific settings. - - - - See and for more information about allowed - parameter names and values. - - - - - - - - Notes - - - Use - to add new users, and to remove a user. - - - - ALTER USER cannot change a user's group memberships. - Use - to do that. - - - - The VALID UNTIL clause defines an expiration time for a - password only, not for the user account per se. In - particular, the expiration time is not enforced when logging in using - a non-password-based authentication method. - - - - It is also possible to tie a - session default to a specific database rather than to a user; see - . - User-specific settings override database-specific - ones if there is a conflict. - - - - - Examples - - - Change a user's password: - - -ALTER USER davide WITH PASSWORD 'hu8jmn3'; - - - - - Change the expiration date of the user's password: - - -ALTER USER manuel VALID UNTIL 'Jan 31 2030'; - - - - - Change a password expiration date, specifying that the password - should expire at midday on 4th May 2005 using - the time zone which is one hour ahead of UTC: - -ALTER USER chris VALID UNTIL 'May 4 12:00:00 2005 +1'; - - - - - Make a password valid forever: - -ALTER USER fred VALID UNTIL 'infinity'; - - - - - Give a user the ability to create other users and new databases: - - -ALTER USER miriam CREATEUSER CREATEDB; - + ALTER USER is now an alias for + , + which see for more information. @@ -269,9 +64,7 @@ ALTER USER miriam CREATEUSER CREATEDB; See Also - - - + diff --git a/doc/src/sgml/ref/create_group.sgml b/doc/src/sgml/ref/create_group.sgml index 94ce98a757..345d018806 100644 --- a/doc/src/sgml/ref/create_group.sgml +++ b/doc/src/sgml/ref/create_group.sgml @@ -1,5 +1,5 @@ @@ -11,7 +11,7 @@ PostgreSQL documentation CREATE GROUP - define a new user group + define a new database role @@ -23,9 +23,21 @@ PostgreSQL documentation CREATE GROUP name [ [ WITH ] option [ ... ] ] where option can be: - - SYSID gid - | USER username [, ...] + + SUPERUSER | NOSUPERUSER + | CREATEDB | NOCREATEDB + | CREATEROLE | NOCREATEROLE + | CREATEUSER | NOCREATEUSER + | INHERIT | NOINHERIT + | LOGIN | NOLOGIN + | [ ENCRYPTED | UNENCRYPTED ] PASSWORD 'password' + | VALID UNTIL 'timestamp' + | IN ROLE rolename [, ...] + | IN GROUP rolename [, ...] + | ROLE rolename [, ...] + | ADMIN rolename [, ...] + | USER rolename [, ...] + | SYSID uid @@ -33,89 +45,18 @@ where option can be: Description - CREATE GROUP will create a new group of users. - You must be a database superuser to use this command. - - - - Note that both users and groups are defined at the database cluster - level, and so are valid in all databases in the cluster. + CREATE GROUP is now an alias for + , + which see for more information. - - - Use - to change a group's membership, and to remove a group. - - - - Parameters - - - - name - - - The name of the group. - - - - - - gid - - - The SYSID clause can be used to choose - the PostgreSQL group ID of the new - group. - This is normally not necessary, but may - be useful if you need to recreate a group referenced in the - permissions of some object. - - - If this is not specified, the highest assigned group ID plus one - (with a minimum of 100) will be used as default. - - - - - - username - - - A list of users to include in the group. The users must already exist. - - - - - - - - - Examples - - - Create an empty group: - -CREATE GROUP staff; - - - - - Create a group with members: - -CREATE GROUP marketing WITH USER jonathan, david; - - - Compatibility There is no CREATE GROUP statement in the SQL - standard. Roles are similar in concept to groups. + standard. @@ -123,8 +64,7 @@ CREATE GROUP marketing WITH USER jonathan, david; See Also - - + diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml new file mode 100644 index 0000000000..598888528f --- /dev/null +++ b/doc/src/sgml/ref/create_role.sgml @@ -0,0 +1,428 @@ + + + + + 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 + | [ 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 INHERIT privilege 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 + LOGIN privilege 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. + + + + + + PASSWORD password + + + Sets the role's password. (A password is only of use for + roles having LOGIN privilege, 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. + + + + INHERIT privilege 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. + + + + 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. + + + + + 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 + + + + + + + + + + + + + diff --git a/doc/src/sgml/ref/create_user.sgml b/doc/src/sgml/ref/create_user.sgml index ed15c410a6..68d37bbd86 100644 --- a/doc/src/sgml/ref/create_user.sgml +++ b/doc/src/sgml/ref/create_user.sgml @@ -1,5 +1,5 @@ @@ -11,7 +11,7 @@ PostgreSQL documentation CREATE USER - define a new database user account + define a new database role @@ -24,12 +24,20 @@ CREATE USER name [ [ WITH ] option can be: - SYSID uid + SUPERUSER | NOSUPERUSER | CREATEDB | NOCREATEDB + | CREATEROLE | NOCREATEROLE | CREATEUSER | NOCREATEUSER - | IN GROUP groupname [, ...] + | INHERIT | NOINHERIT + | LOGIN | NOLOGIN | [ ENCRYPTED | UNENCRYPTED ] PASSWORD 'password' - | VALID UNTIL 'abstime' + | VALID UNTIL 'timestamp' + | IN ROLE rolename [, ...] + | IN GROUP rolename [, ...] + | ROLE rolename [, ...] + | ADMIN rolename [, ...] + | USER rolename [, ...] + | SYSID uid @@ -37,194 +45,14 @@ where option can be: Description - CREATE USER adds a new user to a - PostgreSQL database cluster. Refer to - and for information about managing - users and authentication. You must be a database superuser to use - this command. - - - - - Parameters - - - - name - - - The name of the new user. - - - - - - uid - - - The SYSID clause can be used to choose the - PostgreSQL user ID of the new user. - This is normally not necessary, but may - be useful if you need to recreate the owner of an orphaned - object. - - - If this is not specified, the highest assigned user ID plus one - (with a minimum of 100) will be used as default. - - - - - - CREATEDB - NOCREATEDB - - - These clauses define a user's ability to create databases. If - CREATEDB is specified, the user being - defined will be allowed to create his own databases. Using - NOCREATEDB will deny a user the ability to - create databases. If not specified, - NOCREATEDB is the default. - - - - - - CREATEUSER - NOCREATEUSER - - - These clauses determine whether a user will be permitted to - create new users himself. CREATEUSER will also make - the user a superuser, who can override all access restrictions. - If not specified, - NOCREATEUSER is the default. - - - - - - groupname - - - A name of an existing group into which to insert the user as a new - member. Multiple group names may be listed. - - - - - - password - - - Sets the user's password. If you do not plan to use password - authentication you can omit this option, but then the user - won't be able to connect if you decide to switch to password - authentication. The password can be set or changed later, - using . - - - - - - 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. - - - - - - abstime - - - The VALID UNTIL clause sets an absolute - time after which the user's password is no longer valid. If - this clause is omitted the password will be valid for all time. - - - - - - - - Notes - - - Use to - change the attributes of a user, and to remove a user. Use to add the - user to groups or remove the user from groups. - - - - PostgreSQL includes a program that has - the same functionality as CREATE USER (in fact, it calls this - command) but can be run from the command shell. - - - - The VALID UNTIL clause defines an expiration time for a - password only, not for the user account per se. In - particular, the expiration time is not enforced when logging in using - a non-password-based authentication method. - - - - - Examples - - - Create a user with no password: - -CREATE USER jonathan; - - - - - Create a user with a password: - -CREATE USER davide WITH PASSWORD 'jw8s0F4'; - - - - - Create a user 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 USER miriam WITH PASSWORD 'jw8s0F4' VALID UNTIL '2005-01-01'; - - - - - Create an account where the user can create databases: - -CREATE USER manuel WITH PASSWORD 'jw8s0F4' CREATEDB; - + CREATE USER is now an alias for + , + which see for more information. + The only difference is that when the command is spelled + CREATE USER, LOGIN is assumed + by default, whereas NOLOGIN is assumed when + the command is spelled + CREATE ROLE. @@ -242,9 +70,7 @@ CREATE USER manuel WITH PASSWORD 'jw8s0F4' CREATEDB; See Also - - - + diff --git a/doc/src/sgml/ref/drop_group.sgml b/doc/src/sgml/ref/drop_group.sgml index 10f513ebbd..1decf950d6 100644 --- a/doc/src/sgml/ref/drop_group.sgml +++ b/doc/src/sgml/ref/drop_group.sgml @@ -1,5 +1,5 @@ @@ -11,7 +11,7 @@ PostgreSQL documentation DROP GROUP - remove a user group + remove a database role @@ -20,7 +20,7 @@ PostgreSQL documentation -DROP GROUP name +DROP GROUP name [, ...] @@ -28,48 +28,12 @@ DROP GROUP name Description - DROP GROUP removes the specified group. The - users in the group are not removed. + DROP GROUP is now an alias for + , + which see for more information. - - - Parameters - - - - name - - - The name of an existing group. - - - - - - - - Notes - - - It is unwise to drop a group that has any - granted permissions on objects. Currently, this is not enforced, - but it is likely that future versions of - PostgreSQL will check for the error. - - - - - Examples - - To drop a group: - -DROP GROUP staff; - - - - Compatibility @@ -82,8 +46,7 @@ DROP GROUP staff; See Also - - + diff --git a/doc/src/sgml/ref/drop_role.sgml b/doc/src/sgml/ref/drop_role.sgml new file mode 100644 index 0000000000..dc8a0896de --- /dev/null +++ b/doc/src/sgml/ref/drop_role.sgml @@ -0,0 +1,126 @@ + + + + + DROP ROLE + SQL - Language Statements + + + + DROP ROLE + remove a database role + + + + DROP ROLE + + + + +DROP ROLE name [, ...] + + + + + Description + + + DROP ROLE removes the specified role(s). + To drop a superuser role, you must be a superuser yourself; + to drop non-superuser roles, you must have CREATEROLE + privilege. + + + + A role cannot be removed if it is still referenced in any database + of the cluster; an error will be raised if so. Before dropping the role, + you must drop all the objects it owns (or reassign their ownership) + and revoke any privileges the role has been granted. + + + + However, it is not necessary to remove role memberships involving + the role; DROP ROLE automatically revokes any memberships + of the target role in other roles, and of other roles in the target role. + The other roles are not dropped nor otherwise affected. + + + + + Parameters + + + + name + + + The name of the role to remove. + + + + + + + + Notes + + + PostgreSQL includes a program that has the + same functionality as this command (in fact, it calls this command) + but can be run from the command shell. + + + + + Examples + + + To drop a role: + +DROP ROLE jonathan; + + + + + + Compatibility + + + The SQL standard defines DROP ROLE, but it allows + only one role to be dropped at a time, and it specifies different + privilege requirements than PostgreSQL uses. + + + + + See Also + + + + + + + + + + + diff --git a/doc/src/sgml/ref/drop_user.sgml b/doc/src/sgml/ref/drop_user.sgml index c02cf12607..419a7eda7c 100644 --- a/doc/src/sgml/ref/drop_user.sgml +++ b/doc/src/sgml/ref/drop_user.sgml @@ -1,5 +1,5 @@ @@ -11,7 +11,7 @@ PostgreSQL documentation DROP USER - remove a database user account + remove a database role @@ -20,7 +20,7 @@ PostgreSQL documentation -DROP USER name +DROP USER name [, ...] @@ -28,64 +28,15 @@ DROP USER name Description - DROP USER removes the specified user. - It does not remove tables, views, or other objects owned by the user. If the - user owns any database, an error is raised. + DROP USER is now an alias for + , + which see for more information. - - Parameters - - - - name - - - The name of the user to remove. - - - - - - - - Notes - - - PostgreSQL includes a program that has the - same functionality as this command (in fact, it calls this command) - but can be run from the command shell. - - - - To drop a user who owns a database, first drop the database or change - its ownership. - - - - It is unwise to drop a user who either owns any database objects or has any - granted permissions on objects. Currently, this is only enforced for - the case of owners of databases, but it is likely that future versions of - PostgreSQL will check other cases. - - - - - Examples - - - To drop a user account: - -DROP USER jonathan; - - - - Compatibility - + The DROP USER statement is a PostgreSQL extension. The SQL standard @@ -97,8 +48,7 @@ DROP USER jonathan; See Also - - + diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml index c1875abb2f..57af287dc9 100644 --- a/doc/src/sgml/ref/grant.sgml +++ b/doc/src/sgml/ref/grant.sgml @@ -1,5 +1,5 @@ @@ -44,6 +44,9 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] } GRANT { CREATE | ALL [ PRIVILEGES ] } ON TABLESPACE tablespacename [, ...] TO { username | GROUP groupname | PUBLIC } [, ...] [ WITH GRANT OPTION ] + +GRANT role [, ...] + TO { username | GROUP groupname | PUBLIC } [, ...] [ WITH ADMIN OPTION ] @@ -51,20 +54,39 @@ GRANT { CREATE | ALL [ PRIVILEGES ] } Description - The GRANT command gives specific privileges on - an object (table, view, sequence, database, function, - procedural language, schema, or tablespace) to - one or more users or groups of users. These privileges are added + The GRANT command has two basic variants: one + that grants privileges on a database object (table, view, sequence, + database, function, procedural language, schema, or tablespace), + and one that grants membership in a role. These variants are + similar in many ways, but they are different enough to be described + separately. + + + + As of PostgreSQL 8.1, the concepts of users and + groups have been unified into a single kind of entity called a role. + It is therefore no longer necessary to use the keyword GROUP + to identify whether a grantee is a user or a group. GROUP + is still allowed in the command, but it is a noise word. + + + + GRANT on Database Objects + + + This variant of the GRANT command gives specific + privileges on a database object to + one or more roles. These privileges are added to those already granted, if any. The key word PUBLIC indicates that the - privileges are to be granted to all users, including those that may + privileges are to be granted to all roles, including those that may be created later. PUBLIC may be thought of as an - implicitly defined group that always includes all users. - Any particular user will have the sum - of privileges granted directly to him, privileges granted to any group he + implicitly defined group that always includes all roles. + Any particular role will have the sum + of privileges granted directly to it, privileges granted to any role it is presently a member of, and privileges granted to PUBLIC. @@ -72,9 +94,8 @@ GRANT { CREATE | ALL [ PRIVILEGES ] } If WITH GRANT OPTION is specified, the recipient of the privilege may in turn grant it to others. Without a grant - option, the recipient cannot do that. At present, grant options can - only be granted to individual users, not to groups or - PUBLIC. + option, the recipient cannot do that. Grant options cannot be granted + to PUBLIC. @@ -258,6 +279,24 @@ GRANT { CREATE | ALL [ PRIVILEGES ] } The privileges required by other commands are listed on the reference page of the respective command. + + + + GRANT on Roles + + + This variant of the GRANT command grants membership + in a role to one or more other roles. Membership in a role is significant + because it conveys the privileges granted to a role to each of its + members. + + + + If WITH ADMIN OPTION is specified, the member may + in turn grant membership in the role to others. Without the admin + option, the recipient cannot do that. + + @@ -296,6 +335,8 @@ GRANT { CREATE | ALL [ PRIVILEGES ] } command, the command is performed as though it were issued by the owner of the affected object. In particular, privileges granted via such a command will appear to have been granted by the object owner. + (For role membership, the membership appears to have been granted + by the containing role itself.) @@ -392,6 +433,14 @@ GRANT ALL PRIVILEGES ON kinds TO manuel; else it will only grant those permissions for which the someone else has grant options. + + + Grant membership in role admins to user joe: + + +GRANT admins TO joe; + + diff --git a/doc/src/sgml/ref/revoke.sgml b/doc/src/sgml/ref/revoke.sgml index b7bd2faa8e..58219c55ce 100644 --- a/doc/src/sgml/ref/revoke.sgml +++ b/doc/src/sgml/ref/revoke.sgml @@ -1,5 +1,5 @@ @@ -56,6 +56,11 @@ REVOKE [ GRANT OPTION FOR ] ON TABLESPACE tablespacename [, ...] FROM { username | GROUP groupname | PUBLIC } [, ...] [ CASCADE | RESTRICT ] + +REVOKE [ ADMIN OPTION FOR ] + role [, ...] + FROM { username | GROUP groupname | PUBLIC } [, ...] + [ CASCADE | RESTRICT ] @@ -64,9 +69,9 @@ REVOKE [ GRANT OPTION FOR ] The REVOKE command revokes previously granted - privileges from one or more users or groups of users. The key word + privileges from one or more roles. The key word PUBLIC refers to the implicitly defined group of - all users. + all roles. @@ -75,13 +80,13 @@ REVOKE [ GRANT OPTION FOR ] - Note that any particular user will have the sum - of privileges granted directly to him, privileges granted to any group he + Note that any particular role will have the sum + of privileges granted directly to it, privileges granted to any role it is presently a member of, and privileges granted to PUBLIC. Thus, for example, revoking SELECT privilege - from PUBLIC does not necessarily mean that all users + from PUBLIC does not necessarily mean that all roles have lost SELECT privilege on the object: those who have it granted - directly or via a group will still have it. + directly or via another role will still have it. @@ -103,6 +108,11 @@ REVOKE [ GRANT OPTION FOR ] Thus, the affected users may effectively keep the privilege if it was also granted through other users. + + + When revoking membership in a role, GRANT OPTION is instead + called ADMIN OPTION, but the behavior is similar. + @@ -173,6 +183,14 @@ REVOKE ALL PRIVILEGES ON kinds FROM manuel; Note that this actually means revoke all privileges that I granted. + + + Revoke membership in role admins from user joe: + + +REVOKE admins FROM joe; + + diff --git a/doc/src/sgml/ref/set_role.sgml b/doc/src/sgml/ref/set_role.sgml index 6fbe40fabf..e4b57743a4 100644 --- a/doc/src/sgml/ref/set_role.sgml +++ b/doc/src/sgml/ref/set_role.sgml @@ -1,4 +1,8 @@ - + + SET ROLE @@ -29,9 +33,10 @@ RESET ROLE This command sets the current user identifier of the current SQL-session context to be rolename. The role name may be - written as either an identifier or a string literal. Using this - command, it is possible to either add privileges or restrict one's - privileges. + written as either an identifier or a string literal. + After SET ROLE, permissions checking for SQL commands + is carried out as though the named role were the one that had logged + in originally. @@ -53,6 +58,39 @@ RESET ROLE + + Notes + + + Using this command, it is possible to either add privileges or restrict + one's privileges. If the session user role has the INHERITS + attribute, then it automatically has all the privileges of every role that + it could SET ROLE to; in this case SET ROLE + effectively drops all the privileges assigned directly to the session user + and to the other roles it is a member of, leaving only the privileges + available to the named role. On the other hand, if the session user role + has the NOINHERITS attribute, SET ROLE drops the + privileges assigned directly to the session user and instead acquires the + privileges available to the named role. + + + + In particular, when a superuser chooses to SET ROLE to a + non-superuser role, she loses her superuser privileges. + + + + SET ROLE has effects comparable to + , but the privilege + checks involved are quite different. Also, + SET SESSION AUTHORIZATION determines which roles are + allowable for later SET ROLE commands, whereas changing + roles with SET ROLE does not change the set of roles + allowed to a later SET ROLE. + + + Examples diff --git a/doc/src/sgml/ref/set_session_auth.sgml b/doc/src/sgml/ref/set_session_auth.sgml index 334847fb00..56642c1535 100644 --- a/doc/src/sgml/ref/set_session_auth.sgml +++ b/doc/src/sgml/ref/set_session_auth.sgml @@ -1,4 +1,4 @@ - + SET SESSION AUTHORIZATION @@ -89,8 +89,8 @@ SELECT SESSION_USER, CURRENT_USER; The SQL standard allows some other expressions to appear in place - of the literal username which are not - important in practice. PostgreSQL + of the literal username, but these options + are not important in practice. PostgreSQL allows identifier syntax ("username"), which SQL does not. SQL does not allow this command during a transaction; PostgreSQL does not make this diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml index 63ecfe1204..5a06288c73 100644 --- a/doc/src/sgml/reference.sgml +++ b/doc/src/sgml/reference.sgml @@ -1,5 +1,5 @@ @@ -48,6 +48,7 @@ PostgreSQL Reference Manual &alterLanguage; &alterOperator; &alterOperatorClass; + &alterRole; &alterSchema; &alterSequence; &alterTable; @@ -76,6 +77,7 @@ PostgreSQL Reference Manual &createLanguage; &createOperator; &createOperatorClass; + &createRole; &createRule; &createSchema; &createSequence; @@ -100,6 +102,7 @@ PostgreSQL Reference Manual &dropLanguage; &dropOperator; &dropOperatorClass; + &dropRole; &dropRule; &dropSchema; &dropSequence; -- GitLab