postgresql/doc/src/sgml/user-manag.sgml

<!--
$PostgreSQL: pgsql/doc/src/sgml/user-manag.sgml,v 1.29 2005/03/25 16:38:58 tgl Exp $
-->

<chapter id="user-manag">
 <title>Database Users and Privileges</title>

 <para>
  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.
 </para>

 <para>
  This chapter describes how to create and manage users and introduces
  the privilege system.  More information about the various types of
  database objects and the effects of privileges can be found in <xref linkend="ddl">.
 </para>

 <sect1 id="database-users">
  <title>Database Users</title>

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

  <indexterm>
   <primary>CREATE USER</primary>
  </indexterm>

  <indexterm>
   <primary>DROP USER</primary>
  </indexterm>

  <para>
   Database users 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 <xref
   linkend="sql-createuser" endterm="sql-createuser-title"> SQL command:
<synopsis>
CREATE USER <replaceable>name</replaceable>;
</synopsis>
   <replaceable>name</replaceable> follows the rules for SQL
   identifiers: either unadorned without special characters, or
   double-quoted. To remove an existing user, use the analogous
   <xref linkend="sql-dropuser" endterm="sql-dropuser-title"> command:
<synopsis>
DROP USER <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 users, examine the <structname>pg_user</>
   system catalog, for example
<synopsis>
SELECT usename FROM pg_user;
</synopsis>
   The <xref linkend="app-psql"> program's <literal>\du</> meta-command
   is also useful for listing the existing users.
  </para>

  <para>
   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
   <command>initdb</command>) it will have the same name as the
   operating system user that initialized the database
   cluster. Customarily, this user will be named
   <literal>postgres</literal>. In order to create more users you
   first have to connect as this initial user.
  </para>

  <para>
   Exactly one user identity is active for a connection to the
   database server.  The user 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 <command>psql</command> program uses the
   <option>-U</option> command line option to indicate the user to
   connect as.  Many applications assume the name of the current
   operating system user by default (including
   <command>createuser</> and <command>psql</>).  Therefore it
   is convenient to maintain a naming correspondence between the two
   user sets.
  </para>

  <para>
   The set of database users a given client connection may connect as
   is determined by the client authentication setup, as explained in
   <xref linkend="client-authentication">. (Thus, a client is not
   necessarily limited to connect as the user 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
   identity determines the set of privileges available to a connected
   client, it is important to carefully configure this when setting up
   a multiuser environment.
  </para>
 </sect1>

 <sect1 id="user-attributes">
  <title>User Attributes</title>

   <para>
    A database user may have a number of attributes that define its
    privileges and interact with the client authentication system.

    <variablelist>
     <varlistentry>
      <term>superuser<indexterm><primary>superuser</></></term>
      <listitem>
       <para>
        A database superuser bypasses all permission checks. Also,
        only a superuser can create new users. To create a database
        superuser, use <literal>CREATE USER <replaceable>name</replaceable>
        CREATEUSER</literal>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>database creation<indexterm><primary>database</><secondary>privilege to create</></></term>
      <listitem>
       <para>
        A user must be explicitly given permission to create databases
        (except for superusers, since those bypass all permission
        checks). To create such a user, use <literal>CREATE USER
        <replaceable>name</replaceable> CREATEDB</literal>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>password<indexterm><primary>password</></></term>
      <listitem>
       <para>
        A password is only significant if the client authentication
        method requires the user to supply a password when connecting
        to the database. The <option>password</>,
        <option>md5</>, and <option>crypt</> authentication methods
        make use of passwords. Database passwords are separate from
        operating system passwords. Specify a password upon user
        creation with <literal>CREATE USER
        <replaceable>name</replaceable> PASSWORD '<replaceable>string</>'</literal>. 
       </para>
      </listitem>
     </varlistentry>
    </variablelist>

    A user's attributes can be modified after creation with
    <command>ALTER USER</command>.<indexterm><primary>ALTER USER</></>
    See the reference pages for the <xref linkend="sql-createuser"
    endterm="sql-createuser-title"> and <xref linkend="sql-alteruser"
    endterm="sql-alteruser-title"> commands for details.
   </para>

  <para>
   A user can also set personal defaults for many of the run-time
   configuration settings described in <xref
   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
<programlisting>
ALTER USER myname SET enable_indexscan TO off;
</programlisting>
   This will save the setting (but not set it immediately).  In
   subsequent connections by this user it will appear as though
   <literal>SET enable_indexscan TO off;</literal> 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 <literal>ALTER USER
   <replaceable>username</> RESET <replaceable>varname</>;</literal>.
  </para>
 </sect1>

 <sect1 id="groups">
  <title>Groups</title>

  <indexterm zone="groups">
   <primary>group</primary>
  </indexterm>

  <para>
   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 <xref
   linkend="sql-creategroup" endterm="sql-creategroup-title"> SQL command:
<synopsis>
CREATE GROUP <replaceable>name</replaceable>;
</synopsis>

   To add users to or remove users from an existing group, use <xref
   linkend="sql-altergroup" endterm="sql-altergroup-title">:
<synopsis>
ALTER GROUP <replaceable>name</replaceable> ADD USER <replaceable>uname1</replaceable>, ... ;
ALTER GROUP <replaceable>name</replaceable> DROP USER <replaceable>uname1</replaceable>, ... ;
</synopsis>

   To destroy a group, use <xref
   linkend="sql-dropgroup" endterm="sql-dropgroup-title">:
<synopsis>
DROP GROUP <replaceable>name</replaceable>;
</synopsis>
   This only drops the group, not its member users.
  </para>

  <para>
   To determine the set of existing groups, examine the <structname>pg_group</>
   system catalog, for example
<synopsis>
SELECT groname FROM pg_group;
</synopsis>
   The <xref linkend="app-psql"> program's <literal>\dg</> meta-command
   is also useful for listing the existing groups.
  </para>
 </sect1>

 <sect1 id="privileges">
  <title>Privileges</title>

  <indexterm zone="privileges">
   <primary>privilege</primary>
  </indexterm>

  <indexterm zone="privileges">
   <primary>owner</primary>
  </indexterm>

  <indexterm zone="privileges">
   <primary>GRANT</primary>
  </indexterm>

  <indexterm zone="privileges">
   <primary>REVOKE</primary>
  </indexterm>

  <remark>Being moved to the DDL chapter.  Will eventually disappear here.</remark>

  <para>
   When an object is created, it is assigned an owner. The
   owner is normally the user 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, <firstterm>privileges</firstterm> must be
   granted.
   There are several different kinds of privilege: <literal>SELECT</>,
   <literal>INSERT</>, <literal>UPDATE</>, <literal>DELETE</>,
   <literal>RULE</>, <literal>REFERENCES</>, <literal>TRIGGER</>,
   <literal>CREATE</>, <literal>TEMPORARY</>, <literal>EXECUTE</>,
   and <literal>USAGE</>. For more
   information on the different types of privileges supported by
   <productname>PostgreSQL</productname>, see the
   <xref linkend="sql-grant" endterm="sql-grant-title"> reference page.
  </para>

  <para>
   To assign privileges, the <command>GRANT</command> command is
   used. So, if <literal>joe</literal> is an existing user, and
   <literal>accounts</literal> is an existing table, the privilege to
   update the table can be granted with
<programlisting>
GRANT UPDATE ON accounts TO joe;
</programlisting>
   To grant a privilege to a group, use
<programlisting>
GRANT SELECT ON accounts TO GROUP staff;
</programlisting>
   The special name <literal>PUBLIC</literal> can
   be used to grant a privilege to every user on the system. Writing
   <literal>ALL</literal> in place of a specific privilege specifies that all
   privileges that apply to the object will be granted.
  </para>

  <para>
   To revoke a privilege, use the fittingly named
   <command>REVOKE</command> command:
<programlisting>
REVOKE ALL ON accounts FROM PUBLIC;
</programlisting>
  </para>

  <para>
   The special privileges of an object's owner (i.e., the right to modify
   or destroy the object) are always implicit in being the owner,
   and cannot be granted or revoked.  But the owner can choose
   to revoke his own ordinary privileges, for example to make a
   table read-only for himself as well as others.
  </para>

  <para>
   An object can be assigned to a new owner with an <command>ALTER</command>
   command of the appropriate kind for the object.  Only superusers can do
   this.
  </para>
 </sect1>

 <sect1 id="perm-functions">
  <title>Functions and Triggers</title>

  <para>
   Functions and triggers allow users to insert code into the backend
   server that other users may execute without knowing it. Hence, both
   mechanisms permit users to <quote>Trojan horse</quote>
   others with relative ease. The only real protection is tight
   control over who can define functions.
  </para>

  <para>
   Functions run inside the backend
   server process with the operating system permissions of the
   database server daemon.  If the programmming language
   used for the function allows unchecked memory accesses, it is
   possible to change the server's internal data structures.
   Hence, among many other things, such functions can circumvent any
   system access controls.  Function languages that allow such access
   are considered <quote>untrusted</>, and
   <productname>PostgreSQL</productname> allows only superusers to
   create functions written in those languages.
  </para>
 </sect1>

</chapter>