PostgreSQL™ manages database access permissions using the concept of roles. A role can be thought of as either a database user, or a group of database users, depending on how the role is set up. Roles can own database objects (for example, tables) and can assign privileges on those objects to other roles to control who has access to which objects. Furthermore, it is possible to grant membership in a role to another role, thus allowing the member role to use privileges assigned to another role.
The concept of roles subsumes the concepts of “users” and “groups”. In PostgreSQL™ versions before 8.1, users and groups were distinct kinds of entities, but now there are only roles. Any role can act as a user, a group, or both.
This chapter describes how to create and manage roles. More information about the effects of role privileges on various database objects can be found in the section called “Privileges”.
Database roles are conceptually completely separate from operating system users. In practice it might be convenient to maintain a correspondence, but this is not required. Database roles are global across a database cluster installation (and not per individual database). To create a role use the CREATE ROLE(7) SQL command:
CREATE ROLE name
;
name
follows the rules for SQL
identifiers: either unadorned without special characters, or
double-quoted. (In practice, you will usually want to add additional
options, such as LOGIN
, to the command. More details appear
below.) To remove an existing role, use the analogous
DROP ROLE(7) command:
DROP ROLE name
;
For convenience, the programs createuser(1) and dropuser(1) are provided as wrappers around these SQL commands that can be called from the shell command line:
createusername
dropusername
To determine the set of existing roles, examine the pg_roles system catalog, for example
SELECT rolname FROM pg_roles;
The psql(1) program's \du
meta-command
is also useful for listing the existing roles.
In order to bootstrap the database system, a freshly initialized
system always contains one predefined role. This role is always
a “superuser”, and by default (unless altered when running
initdb) it will have the same name as the
operating system user that initialized the database
cluster. Customarily, this role will be named
postgres
. In order to create more roles you
first have to connect as this initial role.
Every connection to the database server is made using the name of some
particular role, and this role determines the initial access privileges for
commands issued in that connection.
The role name to use for a particular database
connection is indicated by the client that is initiating the
connection request in an application-specific fashion. For example,
the psql program uses the
-U
command line option to indicate the role to
connect as. Many applications assume the name of the current
operating system user by default (including
createuser and psql). Therefore it
is often convenient to maintain a naming correspondence between
roles and operating system users.
The set of database roles a given client connection can connect as is determined by the client authentication setup, as explained in Chapter 19, Client Authentication. (Thus, a client is not limited to connect as the role matching its operating system user, just as a person's login name need not match her real name.) Since the role identity determines the set of privileges available to a connected client, it is important to carefully configure privileges when setting up a multiuser environment.