+ linkend="client-authentication"> 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
+ endterm="SQL-DROPROLE-title"> 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
+ linkend="APP-CREATEUSER" endterm="APP-CREATEUSER-title"> 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
+
+
+ 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
+
+
+
+
+
+
+
+
+
+
+
+
+
CREATE USER
- define a new database user account
+ define a new database role
where 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
Description
- CREATE USER adds a new user to a
-
PostgreSQL database cluster. Refer to
-
and
- linkend="client-authentication"> 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
- endterm="SQL-ALTERUSER-title">.
-
-
-
-
-
- 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
- endterm="SQL-DROPUSER-title"> to remove a user. Use
- linkend="SQL-ALTERGROUP" endterm="SQL-ALTERGROUP-title"> to add the
- user to groups or remove the user from groups.
-
-
-
PostgreSQL includes a program
- linkend="APP-CREATEUSER" endterm="APP-CREATEUSER-title"> 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.
See Also
-
-
-
+
DROP GROUP
- remove a user group
+ remove a database role
-DROP GROUP name
+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
See Also
-
-
+
--- /dev/null
+
+
+
+
+ DROP ROLE
+ SQL - Language Statements
+
+
+
+ DROP ROLE
+ remove a database 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
+ linkend="APP-DROPUSER" endterm="APP-DROPUSER-title"> 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
+
+
+
+
+
+
+
+
+
+
+
DROP USER
- remove a database user account
+ remove a database role
-DROP USER name
+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
- linkend="APP-DROPUSER" endterm="APP-DROPUSER-title"> 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
See Also
-
-
+
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 ]
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.
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.
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.
+
+
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.)
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;
+
+
ON TABLESPACE tablespacename [, ...]
FROM { username | GROUP groupname | PUBLIC } [, ...]
[ CASCADE | RESTRICT ]
+
+REVOKE [ ADMIN OPTION FOR ]
+ role [, ...]
+ FROM { username | GROUP groupname | PUBLIC } [, ...]
+ [ CASCADE | RESTRICT ]
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.
- 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.
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.
+
Note that this actually means revoke all privileges that I
granted.
+
+ Revoke membership in role admins from user joe:
+
+REVOKE admins FROM joe;
+
+
-
+
+
SET ROLE
This command sets the current user
identifier of the current SQL-session context to be
class="parameter">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.
+
+
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
+
+ endterm="sql-set-session-authorization-title">, 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
-
+
SET SESSION AUTHORIZATION
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
&alterLanguage;
&alterOperator;
&alterOperatorClass;
+ &alterRole;
&alterSchema;
&alterSequence;
&alterTable;
&createLanguage;
&createOperator;
&createOperatorClass;
+ &createRole;
&createRule;
&createSchema;
&createSequence;
&dropLanguage;
&dropOperator;
&dropOperatorClass;
+ &dropRole;
&dropRule;
&dropSchema;
&dropSequence;
projects / postgresql.git / commitdiff