This patch improves the "Database Users and Permissions" section of

the Administrator's Guide. This section needs a lot more work, but
this is a start anyway...

Neil Conway

doc/src/sgml/user-manag.sgml

@@ -1,10 +1,14 @@
-<Chapter id="user-manag">
+<!--
+$Header: /cvsroot/pgsql/doc/src/sgml/user-manag.sgml,v 1.14 2002/08/16 04:47:43 momjian Exp $
+-->
+
+<chapter id="user-manag">
  <title>Database Users and Permissions</title>
 
  <para>
   Managing database users and their privileges is in concept similar
-  to managing users of a Unix operating system, but the details are not
+  to managing the users of a Unix operating system, but the details
-  identical.
+  are not identical.
  </para>
 
  <sect1 id="database-users">
@@ -27,8 +31,8 @@ CREATE USER <replaceable>name</replaceable>
   </para>
 
   <para>
-   For convenience, the shell scripts <filename>createuser</filename>
+   For convenience, the shell scripts <application>createuser</application>
-   and <filename>dropuser</filename> are provided as wrappers around these SQL
+   and <application>dropuser</application> are provided as wrappers around these SQL
    commands.
   </para>
 
@@ -36,18 +40,18 @@ CREATE USER <replaceable>name</replaceable>
    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
+   <application>initdb</application>) it will have the same name as
-   operating system user that initialized the area (and is presumably
+   the operating system user that initialized the database
-   being used as the user that runs the server). Customarily, this user
+   cluster. Customarily, this user will be named
-   will be named <systemitem>postgres</systemitem>. In order to create more
+   <systemitem>postgres</systemitem>. In order to create more users
-   users you first have to connect as this initial user.
+   you first have to connect as this initial user.
   </para>
 
   <para>
    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>
+   <application>psql</application> program uses the <option>-U</option>
    command line option to indicate the user to connect as. The set of
    database users a given client connection may connect as is
    determined by the client authentication setup, as explained in
@@ -71,7 +75,7 @@ CREATE USER <replaceable>name</replaceable>
        <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 name
+        superuser, use <literal>CREATE USER <replaceable>name</replaceable>
         CREATEUSER</literal>.
        </para>
       </listitem>
@@ -83,8 +87,8 @@ CREATE USER <replaceable>name</replaceable>
        <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 name
+        checks). To create such a user, use <literal>CREATE USER
-        CREATEDB</literal>.
+        <replaceable>name</replaceable> CREATEDB</literal>.
        </para>
       </listitem>
      </varlistentry>
@@ -93,11 +97,14 @@ CREATE USER <replaceable>name</replaceable>
       <term>password</term>
       <listitem>
        <para>
-        A password is only significant if password authentication is
+        A password is only significant if the client authentication
-        used for client authentication. Database passwords are separate
+        method requires the user to supply a password when connecting
-        from operating system passwords. Specify a password upon
+        to the database. At present, the <option>password</>,
-        user creation with <literal>CREATE USER name PASSWORD
+        <option>md5</>, and <option>crypt</> authentication methods
-        'string'</literal>.
+        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 'string'</literal>. 
        </para>
       </listitem>
      </varlistentry>
@@ -134,26 +141,29 @@ ALTER GROUP <replaceable>name</replaceable> DROP USER <replaceable>uname1</repla
 
   <para>
    When a database object is created, it is assigned an owner. The
-   owner is the user that executed the creation statement. There is
+   owner is the user that executed the creation statement. To change
-   currently no polished interface for changing the owner of a database
+   the owner of a table, index, sequence, or view, use the
-   object (except for tables, for which <command>ALTER TABLE</> can do it).
+   <command>ALTER TABLE</command> command. By default, only an owner
-   By default, only an owner (or a superuser) can do anything
+   (or a superuser) can do anything with the object. In order to allow
-   with the object. In order to allow other users to use it,
+   other users to use it, <firstterm>privileges</firstterm> must be
-   <firstterm>privileges</firstterm> must be granted.
+   granted.
   </para>
 
   <para>
-   There are several different privileges: <literal>SELECT</literal>
+   There are several different privileges: <literal>SELECT</>,
-   (read), <literal>INSERT</literal> (append), <literal>UPDATE</literal>
+   <literal>INSERT</>, <literal>UPDATE</>, <literal>DELETE</>,
-   (write), <literal>DELETE</literal>, <literal>RULE</literal>,
+   <literal>RULE</>, <literal>REFERENCES</>, <literal>TRIGGER</>,
-   <literal>REFERENCES</literal> (foreign key), and
+   <literal>CREATE</>, <literal>TEMPORARY</>, <literal>EXECUTE</>,
-   <literal>TRIGGER</literal>. (See the <command>GRANT</command> manual
+   <literal>USAGE</>, and <literal>ALL PRIVILEGES</>. For more
-   page for more detailed information.) The right to modify or destroy
+   information on the different types of privileges support by
-   an object is always the privilege of the owner only. To assign
+   <productname>PostgreSQL</productname>, refer to the
-   privileges, the <command>GRANT</command> command is used. So, if
+   <command>GRANT</command> reference manual. The right to modify or
-   <literal>joe</literal> is an existing user, and
+   destroy an object is always the privilege of the owner only. To
-   <literal>accounts</literal> is an existing table, write access can be
+   assign privileges, the <command>GRANT</command> command is
-   granted with
+   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>
@@ -210,4 +220,4 @@ REVOKE ALL ON accounts FROM PUBLIC;
 
  </sect1>
 
-</Chapter>
+</chapter>