<!-- doc/src/sgml/user-manag.sgml -->

<chapter id="user-manag">
 <title>Database Roles</title>

 <para>
  <productname>PostgreSQL</productname> manages database access permissions
  using the concept of <firstterm>roles</firstterm>.  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 functions) and can assign privileges on those objects to other roles to
  control who has access to which objects.  Furthermore, it is possible
  to grant <firstterm>membership</firstterm> in a role to another role, thus
  allowing the member role to use privileges assigned to another role.
 </para>

 <para>
  The concept of roles subsumes the concepts of <quote>users</quote> and
  <quote>groups</quote>.  In <productname>PostgreSQL</productname> 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.
 </para>

 <para>
  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 <xref linkend="ddl-priv"/>.
 </para>

 <sect1 id="database-roles">
  <title>Database Roles</title>

  <indexterm zone="database-roles">
   <primary>role</primary>
  </indexterm>

  <indexterm zone="database-roles">
   <primary>user</primary>
  </indexterm>

  <indexterm>
   <primary>CREATE ROLE</primary>
  </indexterm>

  <indexterm>
   <primary>DROP ROLE</primary>
  </indexterm>

  <para>
   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 <link
   linkend="sql-createrole"><command>CREATE ROLE</command></link> SQL command:
<synopsis>
CREATE ROLE <replaceable>name</replaceable>;
</synopsis>
   <replaceable>name</replaceable> 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 <literal>LOGIN</literal>, to the command.  More details appear
   below.)  To remove an existing role, use the analogous
   <link linkend="sql-droprole"><command>DROP ROLE</command></link> command:
<synopsis>
DROP ROLE <replaceable>name</replaceable>;
</synopsis>
  </para>

  <indexterm>
   <primary>createuser</primary>
  </indexterm>

  <indexterm>
   <primary>dropuser</primary>
  </indexterm>

  <para>
   For convenience, the programs <xref linkend="app-createuser"/>
   and <xref linkend="app-dropuser"/> are provided as wrappers
   around these SQL commands that can be called from the shell command
   line:
<synopsis>
createuser <replaceable>name</replaceable>
dropuser <replaceable>name</replaceable>
</synopsis>
  </para>

  <para>
   To determine the set of existing roles, examine the <structname>pg_roles</structname>
   system catalog, for example:
<synopsis>
SELECT rolname FROM pg_roles;
</synopsis>
   or to see just those capable of logging in:
<synopsis>
SELECT rolname FROM pg_roles WHERE rolcanlogin;
</synopsis>
   The <xref linkend="app-psql"/> program's <literal>\du</literal> meta-command
   is also useful for listing the existing roles.
  </para>

  <para>
   In order to bootstrap the database system, a freshly initialized
   system always contains one predefined login-capable role. This role
   is always a <quote>superuser</quote>, and it will have
   the same name as the operating system user that initialized the
   database cluster with <command>initdb</command> unless a different name
   is specified.  This role is often named
   <literal>postgres</literal>. In order to create more roles you
   first have to connect as this initial role.
  </para>

  <para>
   Every connection to the database