When a client application connects to the database server, it
- specifies which
PostgreSQL user name it
+ specifies which
PostgreSQL database user name it
wants to connect as, much the same way one logs into a Unix computer
as a particular user. Within the SQL environment the active database
user name determines access privileges to database objects — see
essential to restrict which database users can connect.
+
+ As explained in ,
+
PostgreSQL actually does privilege
+ management in terms of roles. In this chapter, we
+ consistently use database user to mean role with the
+ LOGIN privilege.
+
+
+
Authentication is the process by which the
database server establishes the identity of the client, and by
extension determines whether the client application (or the user
who runs the client application) is permitted to connect with the
- user name that was requested.
+ database user name that was requested.
-
PostgreSQL user names are logically
+
PostgreSQL database user names are logically
separate from user names of the operating system in which the server
runs. If all the users of a particular server also have accounts on
the server's machine, it makes sense to assign database user names
A record may have one of the seven formats
-local database user authentication-method authentication-option
-host database user CIDR-address authentication-method authentication-option
-hostssl database user CIDR-address authentication-method authentication-option
-hostnossl database user CIDR-address authentication-method authentication-option
-host database user IP-address IP-mask authentication-method authentication-option
-hostssl database user IP-address IP-mask authentication-method authentication-option
-hostnossl database user IP-address IP-mask authentication-method authentication-option
+local database user auth-method auth-option
+host database user CIDR-address auth-method auth-option
+hostssl database user CIDR-address auth-method auth-option
+hostnossl database user CIDR-address auth-method auth-option
+host database user IP-address IP-mask auth-method auth-option
+hostssl database user IP-address IP-mask auth-method auth-option
+hostnossl database user IP-address IP-mask auth-method auth-option
The meaning of the fields is as follows:
database
- Specifies which databases this record matches. The value
+ Specifies which database names this record matches. The value
all specifies that it matches all databases.
The value sameuser specifies that the record
matches if the requested database has the same name as the
- requested user. The value samegroup specifies that
- the requested user must be a member of the group with the same
- name as the requested database. Otherwise, this is the name of
+ requested user. The value samerole specifies that
+ the requested user must be a member of the role with the same
+ name as the requested database. (samegroup is an
+ obsolete but still accepted spelling of samerole.)
+ Otherwise, this is the name of
a specific
PostgreSQL database.
Multiple database names can be supplied by separating them with
- commas. A file containing database names can be specified by
+ commas. A separate file containing database names can be specified by
preceding the file name with @.
user
- Specifies which
PostgreSQL users this record
+ Specifies which database user names this record
matches. The value all specifies that it
- matches all users. Otherwise, this is the name of a specific
-
PostgreSQL user. Multiple user names
- can be supplied by separating them with commas. Group names can
- be specified by preceding the group name with +. A
- file containing user names can be specified by preceding the
+ matches all users. Otherwise, this is either the name of a specific
+ database user, or a group name preceded by +.
+ (Recall that there is no real distinction between users and groups
+ in
PostgreSQL; a + mark really means+ match any of the roles that are directly or indirectly members
+ of this role, while a name without a + mark matches
+ only that specific role.)
+ Multiple user names can be supplied by separating them with commas.
+ A separate file containing user names can be specified by preceding the
file name with @.
- authentication-method
+ auth-method
Specifies the authentication method to use when connecting via
- authentication-option
+ auth-option
The meaning of this optional field depends on the chosen
Example <filename>pg_hba.conf</filename> entries
# Allow any user on the local system to connect to any database under
-# any user name using Unix-domain sockets (the default for local
+# any database user name using Unix-domain sockets (the default for local
# connections).
#
# TYPE DATABASE USER CIDR-ADDRESS METHOD
# the connection (typically the Unix user name).
#
# TYPE DATABASE USER CIDR-ADDRESS METHOD
-host postgres all 192.168.93.0/24 ident sameuser
+host postgres all 192.168.93.0/24 ident sameuser
# Allow a user from host 192.168.12.10 to connect to database
# "postgres" if the user's password is correctly supplied.
# If these are the only three lines for local connections, they will
# allow local users to connect only to their own databases (databases
-# with the same name as their user name) except for administrators and
-# members of group "support" who may connect to all databases. The file
-# $PGDATA/admins contains a list of user names. Passwords are required in
-# all cases.
+# with the same name as their database user name) except for administrators
+# and members of role "support", who may connect to all databases. The file
+# $PGDATA/admins contains a list of names of administrators. Passwords
+# are required in all cases.
#
# TYPE DATABASE USER CIDR-ADDRESS METHOD
local sameuser all md5
# The last two lines above can be combined into a single line:
local all @admins,+support md5
-# The database column can also use lists and file names, but not groups:
+# The database column can also use lists and file names:
local db1,db2,@demodbs all md5
When trust authentication is specified,
PostgreSQL assumes that anyone who can
connect to the server is authorized to access the database with
- whatever database user they specify (including the database superuser).
+ whatever database user name they specify (including superusers).
Of course, restrictions made in the database and
user columns still apply.
This method should only be used when there is adequate
The password-based authentication methods are md5,
crypt, and password. These methods operate
similarly except for the way that the password is sent across the
- connection. However, crypt does not allow encrypted
- passwords to be stored in pg_shadow.
+ connection: respectively, MD5-hashed, crypt-encrypted, and clear-text.
+ A limitation is that the crypt method does not work with
+ passwords that have been encrypted in pg_authid.
sniffing attacks then md5 is preferred, with
crypt a second choice if you must support pre-7.2
clients. Plain password should especially be avoided for
- connections over the open Internet (unless you use
SSL, SSH, or
- other communications security wrappers around the connection).
+ connections over the open Internet (unless you use
SSL,
+ communications security wrapper around the connection).
PostgreSQL database passwords are
separate from operating system user passwords. The password for
- each database user is stored in the pg_shadow system
- catalog table. Passwords can be managed with the SQL commands
+ each database user is stored in the pg_authid system
+ catalog. Passwords can be managed with the SQL commands
and
,
e.g., CREATE USER foo WITH PASSWORD 'secret';.
- can be a good starting point for exploration.
+ can be good starting points for exploration.
Several sources for
Kerberos distributions exist.
-
PostgreSQL supports Kerberos version 5, and it has- to be enabled at build time. See
- for more information.
+
PostgreSQL supports Kerberos version 5. Kerberos+ support has to be enabled when
PostgreSQL is built;+ see for more information.
PostgreSQL operates like a normal Kerberos service.
The name of the service principal is
servicename/hostname@realm.
-
+
+
servicename can be set on the server side using the
configuration parameter, and on the
- client side using the krbsrvname connection parameter. (See also .). The installation default can be changed from the default
- postgres at build time using
- ./configure --with-krb-srvnam=whatever). In most environments,
- this parameter never needs to be changed. However, to support multiple
-
PostgreSQL installations on the same host it is necessary.- Some Kerberos implementations may also require a different service name,
- such as Microsoft Active Directory which requires the service name
- to be in uppercase (POSTGRES).
-
+ client side using the krbsrvname connection parameter. (See
+ also .) The installation default can be
+ changed from the default postgres at build time using
+ ./configure --with-krb-srvnam=whatever. In most environments,
+ this parameter never needs to be changed. However, to support multiple
+
PostgreSQL installations on the same host it is necessary.+ Some Kerberos implementations may also require a different service name,
+ such as Microsoft Active Directory which requires the service name
+ to be in uppercase (POSTGRES).
+
+
hostname is the fully qualified host name of the
server machine. The service principal's realm is the preferred realm
of the server machine.
- Client principals must have their
PostgreSQL user+ Client principals must have their
PostgreSQL database user name as their first component, for example
pgusername/otherstuff@realm. At present the realm of
the client is not checked by
PostgreSQL; so if you
- The keytab file is generated in the Kerberos system, see the
- Kerberos documentation for details. The following example is
- for MIT-compatible Kerberos 5 implementations:
+ The keytab file is generated by the Kerberos software; see the
+ Kerberos documentation for details. The following example is
+ for MIT-compatible Kerberos 5 implementations:
kadmin% ank -randkey postgres/server.my.domain.org
kadmin% ktadd -k krb5.keytab postgres/server.my.domain.org
When connecting to the database make sure you have a ticket for a
- principal matching the requested database user name. An example: For
+ principal matching the requested database user name. For example, for
database user name fred, both principal
authenticate to the database server.
This is what you are most likely to get if you succeed in contacting
the server, but it does not want to talk to you. As the message
suggests, the server refused the connection request because it found
- no authorizing entry in its pg_hba.conf
+ no matching entry in its pg_hba.conf
configuration file.
CREATE DATABASE name;
where name follows the usual rules for
-
SQL identifiers. The current
user automatically
+
SQL identifiers. The current
role automatically
becomes the owner of the new database. It is the privilege of the
owner of a database to remove it later on (which also removes all
the objects in it, even if they have a different owner).
The creation of databases is a restricted operation. See
- linkend="user-attributes"> for how to grant permission.
+ linkend="role-attributes"> for how to grant permission.
Sometimes you want to create a database for someone else. That
- user should become the owner of the new database, so he can
+ role should become the owner of the new database, so he can
configure and manage it himself. To achieve that, use one of the
following commands:
-CREATE DATABASE dbname OWNER username;
+CREATE DATABASE dbname OWNER rolename;
from the SQL environment, or
-createdb -O username dbname
+createdb -O rolename dbname
You must be a superuser to be allowed to create a database for
- someone else.
+ someone else (that is, for a role you are not a member of).
DROP DATABASE name;
- Only the owner of the database (i.e., the user that created it), or
+ Only the owner of the database, or
a superuser, can drop a database. Dropping a database removes all objects
that were
contained within the database. The destruction of a database cannot
These clauses determine whether a role inherits the
privileges of roles it is a member of.
- A role with INHERIT privilege can automatically
+ A role with the INHERIT attribute can automatically
use whatever database privileges have been granted to all roles
it is directly or indirectly a member of.
Without INHERIT, membership in another role
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.
+ the LOGIN attribute can be thought of as a user.
Roles without this attribute are useful for managing database
privileges, but are not users in the usual sense of the word.
If not specified,
Sets the role's password. (A password is only of use for
- roles having LOGIN privilege, but you can
+ roles having the LOGIN attribute, but you can
nonetheless define one for roles without it.)
If you do not plan to use password
authentication you can omit this option.
- INHERIT privilege is the default for reasons of backwards
+ The INHERIT attribute governs inheritance of grantable
+ privileges (that is, access privileges for database objects and role
+ memberships). It does not apply to the special role attributes set by
+ CREATE ROLE and ALTER ROLE. For example, being
+ a member of a role with CREATEDB privilege does not immediately
+ grant the ability to create databases, even if INHERIT is set;
+ it would be necessary to become that role via
+ before
+ creating a database.
+
+
+ The INHERIT attribute is the default for reasons of backwards
compatibility: in prior releases of
PostgreSQL,
users always had access to all privileges of groups they were members of.
However, NOINHERIT provides a closer match to the semantics
-
Database <span class="marked">User</span>s and Privileges
+
Database <span class="marked">Role</span>s and Privileges
- Every database cluster contains a set of database users. Those
- users are separate from the users managed by the operating system on
- which the server runs. Users own database objects (for example,
- tables) and can assign privileges on those objects to other users to
- control who has access to which object.
+
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 use of privileges assigned to the role it is
+ a member of.
- This chapter describes how to create and manage users and introduces
+ 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 and introduces
the privilege system. More information about the various types of
- database objects and the effects of privileges can be found in .
+ database objects and the effects of privileges can be found in
+ .
- users">
-
Database <span class="marked">User</span>s
+ roles">
+
Database <span class="marked">Role</span>s
-
+
+
+
+
- Database users are conceptually completely separate from
+ 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 user
- names are global across a database cluster installation (and not
- per individual database). To create a
user use the
- linkend="sql-createuser" endterm="sql-createuser-title"> SQL command:
+ 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
+ linkend="sql-createrole" endterm="sql-createrole-title"> SQL command:
-CREATE USER name;
+CREATE ROLE name;
name follows the rules for SQL
identifiers: either unadorned without special characters, or
- double-quoted. To remove an existing user, use the analogous
- command:
+ 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
+ command:
-DROP USER name;
+DROP ROLE name;
- To determine the set of existing users, examine the pg_user
+ To determine the set of existing roles, examine the pg_roles
system catalog, for example
-SELECT usename FROM pg_user;
+SELECT rolname FROM pg_roles;
The program's \du meta-command
- is also useful for listing the existing users.
+ is also useful for listing the existing roles.
In order to bootstrap the database system, a freshly initialized
- system always contains one predefined user. This user will have the
- fixed ID 1, and by default (unless altered when running
+ 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 user will be named
- postgres. In order to create more users you
- first have to connect as this initial user.
+ cluster. Customarily, this role will be named
+ postgres. In order to create more roles you
+ first have to connect as this initial role.
- Exactly one user identity is active for a connection to the
- database server. The user name to use for a particular database
+ Every connection to the database server is made in the name of some
+ particular role, and this role determines the initial access privileges for
+ commands issued on 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
- command line option to indicate the user to
+ 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 convenient to maintain a naming correspondence between the two
- user sets.
+ is often convenient to maintain a naming correspondence between
+ roles and operating system users.
- The set of database users a given client connection may connect as
+ The set of database roles a given client connection may connect as
is determined by the client authentication setup, as explained in
. (Thus, a client is not
- necessarily limited to connect as the user with the same name as
+ necessarily limited to connect as the role with the same name as
its operating system user, just as a person's login name
- need not match her real name.) Since the user
+ 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 this when setting up
a multiuser environment.
- user-attributes">
-
<span class="marked">User</span> Attributes
+ role-attributes">
+
<span class="marked">Role</span> Attributes
- A database user may have a number of attributes that define its
+ A database role may have a number of attributes that define its
privileges and interact with the client authentication system.
+
login privilegelogin privilege+
+ Only roles that have the LOGIN attribute can be used
+ as the initial role name for a database connection. A role with
+ the LOGIN attribute can be considered the same thing
+ as a database user. To create a role with login privilege,
+ use either
+CREATE ROLE name LOGIN;
+CREATE USER name;
+
+ (CREATE USER is equivalent to CREATE ROLE
+ except that CREATE USER assumes LOGIN by
+ default, while CREATE ROLE does not.)
+
+
+
+
+
+
superuser statussuperuser
- A database superuser bypasses all permission checks. Also,
- only a superuser can create new users. To create a database
- superuser, use CREATE USER name
- CREATEUSER.
+ A database superuser bypasses all permission checks. This is a
+ dangerous privilege and should not be used carelessly; it is best
+ to do most of your work as a role that is not a superuser.
+ To create a new database superuser, use CREATE ROLE
+ name SUPERUSER. You must do
+ this as a role that is already a superuser.
database creationdatabaseprivilege to create
- A user must be explicitly given permission to create databases
+ A role must be explicitly given permission to create databases
(except for superusers, since those bypass all permission
- checks). To create such a user, use CREATE USER
+ checks). To create such a role, use CREATE ROLE
name CREATEDB.
+
+
role creationroleprivilege to create+
+ A role must be explicitly given permission to create more roles
+ (except for superusers, since those bypass all permission
+ checks). To create such a role, use CREATE ROLE
+ name CREATEROLE.
+ A role with CREATEROLE privilege can alter and drop
+ other roles, too. However, to alter or drop a superuser role,
+ superuser status is required; CREATEROLE is not sufficient
+ for that.
+
+
+
+
to the database. The
make use of passwords. Database passwords are separate from
- operating system passwords. Specify a password upon user
- creation with CREATE USER
+ operating system passwords. Specify a password upon role
+ creation with CREATE ROLE
name PASSWORD 'string'.
- A user's attributes can be modified after creation with
- See the reference pages for the user"
- endterm="sql-createuser-title"> and "
- endterm="sql-alteruser-title"> commands for details.
+ A role's attributes can be modified after creation with
+ See the reference pages for the role"
+ endterm="sql-createrole-title"> and "
+ endterm="sql-alterrole-title"> commands for details.
- A user can also set personal defaults for many of the run-time
+ A role can also have role-specific defaults for many of the run-time
configuration settings described in
linkend="runtime-config">. For example, if for some reason you
want to disable index scans (hint: not a good idea) anytime you
connect, you can use
-ALTER USER myname SET enable_indexscan TO off;
+ALTER ROLE myname SET enable_indexscan TO off;
This will save the setting (but not set it immediately). In
- subsequent connections by this user it will appear as though
+ subsequent connections by this role it will appear as though
SET enable_indexscan TO off; had been executed
just before the session started.
You can still alter this setting during the session; it will only
- be the default. To undo any such setting, use ALTER USER
- username RESET varname;.
+ be the default. To remove a role-specific default setting, use
+ ALTER ROLE rolename RESET varname;.
+ Note that role-specific defaults attached to roles without
+ LOGIN privilege are fairly useless, since they will never
+ be invoked.
- groups">
-
<span class="marked">Groups</span>
+ role-membership">
+
<span class="marked">Role Membership</span>
- groups">
+ role-membership">
- As in Unix, groups are a way of logically grouping users to ease
- management of privileges: privileges can be granted to, or revoked
- from, a group as a whole. To create a group, use the
- linkend="sql-creategroup" endterm="sql-creategroup-title"> SQL command:
-
-CREATE GROUP name;
->
+ It is frequently convenient to group users together to ease
+ management of privileges: that way, privileges can be granted to, or
+ revoked from, a group as a whole. In
PostgreSQL+ this is done by creating a role that represents the group, and then
+ granting membership in the group role to individual user
+ roles.
+ >
- To add users to or remove users from an existing group, use
- linkend="sql-altergroup" endterm="sql-altergroup-title">:
+ To set up a group role, first create the role:
-ALTER GROUP name ADD USER uname1, ... ;
-ALTER GROUP name DROP USER uname1, ... ;
+CREATE ROLE name;
+ Typically a role being used as a group would not have the LOGIN
+ attribute, though you can set it if you wish.
+
- To destroy a group, use
- linkend="sql-dropgroup" endterm="sql-dropgroup-title">:
+ Once the group role exists, you can add and remove members using the
+ and
+ commands:
-DROP GROUP name;
+GRANT group_role TO role1, ... ;
+REVOKE group_role FROM role1, ... ;
- This only drops the group, not its member users.
+ You can grant membership to other group roles, too (since there isn't
+ really any distinction between group roles and non-group roles). The
+ only restriction is that you can't set up circular membership loops.
- To determine the set of existing groups, examine the pg_group
- system catalog, for example
+ The members of a role can use the privileges of the group role in two
+ ways. First, every member of a group can explicitly do
+ to
+ temporarily become the group role. In this state, the
+ database session has access to the privileges of the group role rather
+ than the original login role, and any database objects created are
+ considered owned by the group role not the login role. Second, member
+ roles that have the INHERIT attribute automatically have use of
+ privileges of roles they are members of. As an example, suppose we have
+ done
+CREATE ROLE joe LOGIN INHERIT;
+CREATE ROLE admin NOINHERIT;
+CREATE ROLE wheel NOINHERIT;
+GRANT admin TO joe;
+GRANT wheel TO admin;
+
+ Immediately after connecting as role joe, a database
+ session will have use of privileges granted directly to joe
+ plus any privileges granted to admin, because joe
+ inherits admin's privileges. However, privileges
+ granted to wheel are not available, because even though
+ joe is indirectly a member of wheel, the
+ membership is via admin which has the NOINHERIT
+ attribute. After
+SET ROLE admin;
+
+ the session would have use of only those privileges granted to
+ admin, and not those granted to joe. After
+SET ROLE wheel;
+
+ the session would have use of only those privileges granted to
+ wheel, and not those granted to either joe
+ or admin. The original privilege state can be restored
+ with any of
+SET ROLE joe;
+SET ROLE NONE;
+RESET ROLE;
+
+
+
+
+ The SET ROLE command always allows selecting any role
+ that the original login role is directly or indirectly a member of.
+ Thus, in the above example, it is not necessary to become
+ admin before becoming wheel.
+
+
+
+
+ In the SQL standard, there is a clear distinction between users and roles,
+ and users do not automatically inherit privileges while roles do. This
+ behavior can be obtained in
PostgreSQL by giving
+ roles being used as SQL roles the INHERIT attribute, while
+ giving roles being used as SQL users the NOINHERIT attribute.
+ However,
PostgreSQL defaults to giving all roles
+ the INHERIT attribute, for backwards compatibility with pre-8.1
+ releases in which users always had use of permissions granted to groups
+ they were members of.
+
+
+
+ To destroy a group role, use
+ linkend="sql-droprole" endterm="sql-droprole-title">:
-SELECT groname FROM pg_group;
+DROP ROLE name;
- The program's \dg meta-command
- is also useful for listing the existing groups.
+ Any memberships in the group role are automatically revoked (but the
+ member roles are not otherwise affected). Note however that any objects
+ owned by the group role must first be dropped or reassigned to other
+ owners; and any permissions granted to the group role must be revoked.
- Being moved to the DDL chapter. Will eventually disappear here.
-
When an object is created, it is assigned an owner. The
- owner is normally the user that executed the creation statement.
+ owner is normally the role that executed the creation statement.
For most kinds of objects, the initial state is that only the owner
(or a superuser) can do anything with the object. To allow
- other users to use it, privileges must be
+ other roles to use it, privileges must be
granted.
There are several different kinds of privilege: SELECT,
INSERT, UPDATE, DELETE,
To assign privileges, the GRANT command is
- used. So, if joe is an existing user, and
+ used. So, if joe is an existing role, and
accounts is an existing table, the privilege to
update the table can be granted with
GRANT UPDATE ON accounts TO joe;
-
- To grant a privilege to a group, use
-GRANT SELECT ON accounts TO GROUP staff;
The special name PUBLIC can
- be used to grant a privilege to every user on the system. Writing
+ be used to grant a privilege to every role on the system. Writing
ALL in place of a specific privilege specifies that all
privileges that apply to the object will be granted.
To revoke a privilege, use the fittingly named
- <command>REVOKE> command:
+ <xref linkend="sql-revoke" endterm="sql-revoke-title"> command:
REVOKE ALL ON accounts FROM PUBLIC;
An object can be assigned to a new owner with an ALTER
- command of the appropriate kind for the object. Only superusers can do
- this.
+ command of the appropriate kind for the object. Superusers can always do
+ this; ordinary roles can only do it if they are both the current owner
+ of the object (or a member of the owning role) and a member of the new
+ owning role.
projects / postgresql.git / commitdiff