diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml
index d993b64ad04..98dfbda111b 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 aa025e684a0..884f1e22c0c 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 00000000000..3e87cf01763
--- /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 960016d2ed1..2844a63d083 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 94ce98a757e..345d018806a 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.
+ CREATE GROUP is now an alias for
+ ,
+ which see for more information.
-
-
- Note that both users and groups are defined at the database cluster
- level, and so are valid in all databases in the cluster.
-
-
-
- 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 00000000000..598888528fb
--- /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 ed15c410a61..68d37bbd86d 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 10f513ebbdc..1decf950d62 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.
-
-
-
-
- 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.
+ DROP GROUP is now an alias for
+ ,
+ which see for more information.
-
- 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 00000000000..dc8a0896de1
--- /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 c02cf12607c..419a7eda7c8 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 c1875abb2fe..57af287dc9c 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 b7bd2faa8ea..58219c55cef 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 6fbe40fabff..e4b57743a4d 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 334847fb00e..56642c15354 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 63ecfe12041..5a06288c735 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;