Enhance the description of user and database management. Reduce the

number of forward references in the admin guide.

doc/src/sgml/admin.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.37 2002/06/13 05:15:22 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.38 2002/09/25 21:16:10 petere Exp $
 -->
 
 <book id="admin">
@@ -25,10 +25,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.37 2002/06/13 05:15:22
   &installation;
   &installw;
   &runtime;
+  &user-manag;
+  &manage-ag;
   &client-auth;
   &charset;
-  &manage-ag;
-  &user-manag;
   &maintenance;
   &backup;
   &monitoring;

doc/src/sgml/filelist.sgml

-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.22 2002/08/22 03:17:37 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.23 2002/09/25 21:16:10 petere Exp $ -->
 
 <!entity history    SYSTEM "history.sgml">
 <!entity info       SYSTEM "info.sgml">
@@ -29,7 +29,6 @@
 <!entity func       SYSTEM "func.sgml">
 <!entity indices    SYSTEM "indices.sgml">
 <!entity keywords   SYSTEM "keywords.sgml">
-<!entity manage     SYSTEM "manage.sgml">
 <!entity mvcc       SYSTEM "mvcc.sgml">
 <!entity perform    SYSTEM "perform.sgml">
 <!entity queries    SYSTEM "queries.sgml">

doc/src/sgml/manage-ag.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.20 2001/11/28 20:49:10 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.21 2002/09/25 21:16:10 petere Exp $
 -->
 
 <chapter id="managing-databases">
@@ -7,19 +7,47 @@ $Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.20 2001/11/28 20:49:10 p
 
  <indexterm zone="managing-databases"><primary>database</></>
 
+ <para>
+  Every instance of a running PostgreSQL server manages one or more
+  databases.  Databases are therefore the topmost hierarchical level
+  for organizing SQL objects (<quote>database objects</quote>).  This
+  chapter describes the properties of databases, and how to create,
+  manage, and destroy them.
+ </para>
+
+ <sect1>
+  <title>Overview</title>
+
   <para>
    A database is a named collection of SQL objects (<quote>database
-  objects</quote>).  Generally, every database object (tables, functions,
-  etc.) belongs to one and only one database.  (But there are a few system
-  catalogs, for example <literal>pg_database</>, that belong to a whole
-  installation and are accessible from each database within the
-  installation.)
-  An application that connects
-  to the database server specifies in its connection request the
-  name of the database it wants to connect to. It is not possible to
-  access more than one database per connection. (But an application
-  is not restricted in the number of connections it opens to the same
-  or other databases.)
+   objects</quote>).  Generally, every database object (tables,
+   functions, etc.) belongs to one and only one database.  (But there
+   are a few system catalogs, for example <literal>pg_database</>,
+   that belong to a whole installation and are accessible from each
+   database within the installation.)  More accurately, a database is
+   a collection of schemas and the schemas contain the tables,
+   functions, etc.  So the full hierarchy is:
+   server-database-schema-table (or something else instead of a
+   table).
+  </para>
+
+  <para>
+   An application that connects to the database server specifies in
+   its connection request the name of the database it wants to connect
+   to. It is not possible to access more than one database per
+   connection. (But an application is not restricted in the number of
+   connections it opens to the same or other databases.)  It is
+   possible, however, to access more than one schema from the same
+   connection.  Schemas are a purely logical structure and who can
+   access what is managed by the privilege system.  Databases are
+   physically separated and access control is managed at the
+   connection level.  If one PostgreSQL server instance is to house
+   projects or users that should be separate and for the most part
+   unaware of each other, it is therefore recommendable to put them
+   into separate databases.  If the projects or users are interrelated
+   and should be able to use each other's resources they should be put
+   in the same databases but possibly into separate schemas.  More
+   information about managing schemas is in &cite-user;.
   </para>
 
   <note>
@@ -28,16 +56,17 @@ $Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.20 2001/11/28 20:49:10 p
     difference in practice.
    </para>
   </note>
+ </sect1>
+
+ <sect1 id="manage-ag-createdb">
+  <title>Creating a Database</title>
 
   <para>
-  In order to create or drop databases, the <productname>PostgreSQL</>
-  <application>postmaster</> must be up and running (see <xref
+   In order to create a databases, the <productname>PostgreSQL</>
+   server must be up and running (see <xref
    linkend="postmaster-start">).
   </para>
 
- <sect1 id="manage-ag-createdb">
-  <title>Creating a Database</title>
-
   <para>
    Databases are created with the query language command
    <command>CREATE DATABASE</command>:
@@ -56,8 +85,6 @@ CREATE DATABASE <replaceable>name</>
    linkend="user-attributes"> for how to grant permission.
   </para>
 
-  <formalpara>
-   <title>Bootstrapping:</title>
   <para>
    Since you need to be connected to the database server in order to
    execute the <command>CREATE DATABASE</command> command, the
@@ -65,11 +92,10 @@ CREATE DATABASE <replaceable>name</>
    site can be created. The first database is always created by the
    <command>initdb</> command when the data storage area is
    initialized. (See <xref linkend="creating-cluster">.) By convention
-    this database is called <literal>template1</>. So
-    to create the first <quote>real</> database you can connect to
+   this database is called <literal>template1</>. So to create the
+   first <quote>real</> database you can connect to
    <literal>template1</>.
   </para>
-  </formalpara>
 
   <para>
    The name <quote>template1</quote> is no accident: When a new
@@ -77,14 +103,14 @@ CREATE DATABASE <replaceable>name</>
    This means that any changes you make in <literal>template1</> are
    propagated to all subsequently created databases. This implies that
    you should not use the template database for real work, but when
-   used judiciously this feature can be convenient.  More details appear
-   below.
+   used judiciously this feature can be convenient.  More details
+   appear in <xref linkend="manage-ag-templatedbs">.
   </para>
 
   <para>
    As an extra convenience, there is also a program that you can
    execute from the shell to create new databases,
-   <filename>createdb</>.
+   <command>createdb</>.
 
 <synopsis>
 createdb <replaceable class="parameter">dbname</replaceable>
@@ -99,7 +125,31 @@ createdb <replaceable class="parameter">dbname</replaceable>
    you want.
   </para>
 
-  <sect2 id="manage-ag-templatedbs">
+  <note>
+   <para>
+    <xref linkend="client-authentication"> contains information about
+    how to restrict who can connect to a given database.
+   </para>
+  </note>
+
+  <para>
+   Sometimes you want to create a database for someone else.  That
+   user 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:
+<programlisting>
+CREATE DATABASE <replaceable>dbname</> OWNER <replaceable>username</>;
+</programlisting>
+   from the SQL environment, or
+<programlisting>
+createdb -O <replaceable>username</> <replaceable>dbname</>
+</programlisting>
+   You must be a superuser to be allowed to create a database for
+   someone else.
+  </para>
+ </sect1>
+
+ <sect1 id="manage-ag-templatedbs">
   <title>Template Databases</title>
 
   <para>
@@ -111,7 +161,7 @@ createdb <replaceable class="parameter">dbname</replaceable>
    will be copied into subsequently created user databases.  This
    behavior allows site-local modifications to the standard set of
    objects in databases.  For example, if you install the procedural
-   language <literal>plpgsql</> in <literal>template1</>, it will
+   language <application>PL/pgSQL</> in <literal>template1</>, it will
    automatically be available in user databases without any extra action
    being taken when those databases are made.
   </para>
@@ -132,12 +182,24 @@ createdb <replaceable class="parameter">dbname</replaceable>
    additions that may now be present in <literal>template1</>.
   </para>
 
+  <para>
+   To create a database by copying <literal>template0</literal>, use
+<programlisting>
+CREATE DATABASE <replaceable>dbname</> TEMPLATE template0;
+</programlisting>
+   from the SQL environment, or
+<programlisting>
+createdb -T template0 <replaceable>dbname</>
+</programlisting>
+   from the shell.
+  </para>
+
   <para>
    It is possible to create additional template databases, and indeed
    one might copy any database in an installation by specifying its name
    as the template for <command>CREATE DATABASE</>.  It is important to
    understand, however, that this is not (yet) intended as
-   a general-purpose <quote>COPY DATABASE</quote> facility.  In particular, it is
+   a general-purpose <quote><command>COPY DATABASE</command></quote> facility.  In particular, it is
    essential that the source database be idle (no data-altering transactions
    in progress)
    for the duration of the copying operation.  <command>CREATE DATABASE</>
@@ -151,7 +213,7 @@ createdb <replaceable class="parameter">dbname</replaceable>
 
   <para>
    Two useful flags exist in <literal>pg_database</literal> for each
-   database: <literal>datistemplate</literal> and
+   database: the columns <literal>datistemplate</literal> and
    <literal>datallowconn</literal>.  <literal>datistemplate</literal>
    may be set to indicate that a database is intended as a template for
    <command>CREATE DATABASE</>.  If this flag is set, the database may be
@@ -187,17 +249,46 @@ createdb <replaceable class="parameter">dbname</replaceable>
     <literal>template1</> and <literal>template0</> do not have any special
     status beyond the fact that the name <literal>template1</> is the default
     source database name for <command>CREATE DATABASE</> and the default
-    database-to-connect-to for various scripts such as <literal>createdb</>.
+    database-to-connect-to for various programs such as <command>createdb</>.
     For example, one could drop <literal>template1</> and recreate it from
     <literal>template0</> without any ill effects.  This course of action
     might be advisable if one has carelessly added a bunch of junk in
     <literal>template1</>.
    </para>
   </note>
+ </sect1>
+
+ <sect1 id="manage-ag-config">
+  <title>Database Configuration</title>
 
-  </sect2>
+  <para>
+   Recall from <xref linkend="runtime-config"> that the PostgreSQL
+   server provides a large number of run-time configuration variables.
+   You can set database-specific default values for many of these
+   settings.
+  </para>
 
-  <sect2 id="manage-ag-alternate-locs">
+  <para>
+   For example, if for some reason you want to disable the
+   <acronym>GEQO</acronym> optimizer for a given database, you'd
+   ordinarily have to either disable it for all databases or make sure
+   that every connecting client is careful to issue <literal>SET geqo
+   TO off;</literal>.  To make this setting the default you can
+   execute the command
+<programlisting>
+ALTER DATABASE mydb SET geqo TO off;
+</programlisting>
+   This will save the setting (but not set it immediately) and in
+   subsequent connections it will appear as though <literal>SET geqo
+   TO off;</literal> had been called right before the session started.
+   Note that users can still alter this setting during the session; it
+   will only be the default.  To undo any such setting, use
+   <literal>ALTER DATABASE <replaceable>dbname</> RESET
+   <replaceable>varname</>;</literal>.
+  </para>
+ </sect1>
+
+ <sect1 id="manage-ag-alternate-locs">
   <title>Alternative Locations</title>
 
    <para>
@@ -227,18 +318,14 @@ createdb <replaceable class="parameter">dbname</replaceable>
     initialize the data area, and finally restart the server. (See
     <xref linkend="postmaster-shutdown"> and <xref
     linkend="postmaster-start">.) To set an environment variable, type
-    <informalexample>
 <programlisting>
 PGDATA2=/home/postgres/data
 export PGDATA2
 </programlisting>
-    </informalexample>
     in Bourne shells, or
-    <informalexample>
 <programlisting>
 setenv PGDATA2 /home/postgres/data
 </programlisting>
-    </informalexample>
     in <application>csh</> or <application>tcsh</>. You have to make sure that this environment
     variable is always defined in the server environment, otherwise
     you won't be able to access that database. Therefore you probably
@@ -253,12 +340,11 @@ setenv PGDATA2 /home/postgres/data
     already exists and is writable
     by the user account that runs the server (see <xref
     linkend="postgres-user">). Then from the command line, type
-    <informalexample>
 <programlisting>
 initlocation PGDATA2
 </programlisting>
-    </informalexample>
-    Then you can restart the server.
+    (<emphasis>not</emphasis> <literal>initlocation
+    $PGDATA2</literal>).  Then you can restart the server.
    </para>
 
    <para>
@@ -290,8 +376,6 @@ gmake CPPFLAGS=-DALLOW_ABSOLUTE_DBPATHS all
 </programlisting>
     </para>
    </note>
-
-  </sect2>
  </sect1>
 
  <sect1 id="manage-ag-dropdb">

doc/src/sgml/manage.sgml

-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/manage.sgml,v 1.23 2002/08/13 20:40:43 momjian Exp $
--->
-
- <Chapter Id="manage">
-  <Title>Managing a Database</Title>
-
-  <comment>
-   This section is currently a thinly disguised copy of the
-   Tutorial. Needs to be augmented.
-    - thomas 1998-01-12
-  </comment>
-
-  <Para>
-   Although the <FirstTerm>site administrator</FirstTerm> is responsible for overall management 
-   of the <ProductName>PostgreSQL</ProductName> installation, some databases within the
-   installation may be managed by another person, 
-   designated the <FirstTerm>database administrator</FirstTerm>.
-   This assignment of responsibilities occurs when a database is created. 
-   A user may be assigned explicit privileges to create databases and/or to create new users. 
-   A user assigned both privileges can perform most administrative tasks
-   within <ProductName>PostgreSQL</ProductName>, but will
-   not by default have the same operating system privileges as the site administrator.
-  </Para>
-
-  <Para>
-   The <citetitle>Administrator's Guide</> covers these topics in
-   more detail.
-  </Para>
-
-  <Sect1 id="db-creation">
-   <Title>Database Creation</Title>
-
-   <Para>
-    Databases are created by the <Command>CREATE DATABASE</Command>
-    command issued from within
-    <ProductName>PostgreSQL</ProductName>. <Application>createdb</Application>
-    is a shell script provided to give the same functionality from the
-    Unix command line.
-   </Para>
-
-   <Para>
-    The <ProductName>PostgreSQL</ProductName> backend must be running for either method
-    to succeed, and the user issuing the command must be the <ProductName>PostgreSQL</ProductName>
-    <FirstTerm>superuser</FirstTerm> or have been assigned database creation privileges by the
-    superuser.
-   </Para>
-
-   <Para>
-    To create a new database named <literal>mydb</literal> from the command line, type
-<ProgramListing>
-% createdb mydb
-</ProgramListing>
-
-    and to do the same from within <Application>psql</Application> type
-<ProgramListing>
-=> CREATE DATABASE mydb;
-</ProgramListing>
-   </Para>
-
-   <Para>
-    If you do not have the privileges required to create a database, you will see
-    the following:
-<ProgramListing>
-ERROR:  CREATE DATABASE: Permission denied.
-</ProgramListing>
-   </Para>
-
-   <Para>
-    You  automatically  become  the
-    database  administrator  of  the database you just created.  
-    Database names must  have  an  alphabetic  first
-    character and are limited to 63 characters in length.
-    <ProductName>PostgreSQL</ProductName>  allows  you to create any number of
-    databases at a  given  site.  
-   </Para>
-
-  <Para>
-   The <citetitle>Administrator's Guide</> discusses database creation
-   in more detail, including advanced options of the <command>CREATE
-   DATABASE</> command.
-  </Para>
-
-  </Sect1>
-
-<Sect1 id="db-accessing">
-<Title>Accessing a Database</Title>
-
-<Para>
-     Once you have constructed a database, you can access it
-     by:
-
-    <itemizedlist spacing="compact" mark="bullet">
-     <listitem>
-      <para>
-       Running the <productname>PostgreSQL</productname> interactive
-       terminal program, called <application>psql</application>, which allows you
-       to interactively enter, edit, and execute
-       <acronym>SQL</acronym> commands.
-      </para>
-     </listitem>
-
-     <listitem>
-      <para>
-       Using an existing graphical frontend tool like
-       <application>PgAccess</application> or
-       <application>ApplixWare</application> (via
-       <acronym>ODBC</acronym>) to create and manipulate a database.
-       These possibilities are not covered in this tutorial.
-      </para>
-     </listitem>
-
-     <listitem>
-      <para>
-       Writing a custom application, using one of the several
-       available language bindings.  These possibilities are discussed
-       further in <citetitle>The PostgreSQL Programmer's
-       Guide</citetitle>.
-      </para>
-     </listitem>
-    </itemizedlist>
-
-You probably want to start up <Application>psql</Application>, 
-to try out the examples in this manual.
- It can be activated for the <Database>mydb</Database>
-     database by typing the command:
-<ProgramListing>
-% psql mydb
-</ProgramListing>
-
-     You will be greeted with the following message:
-<ProgramListing>
-Welcome to psql &version;, the PostgreSQL interactive terminal.
- 
-Type:  \copyright for distribution terms
-       \h for help with SQL commands
-       \? for help on internal slash commands
-       \g or terminate with semicolon to execute query
-       \q to quit
-
-mydb=>
-</ProgramListing>
-</Para>
-
-<Para>
-This prompt indicates that <command>psql</command> is listening
-  to you and that you can type <Acronym>SQL</Acronym> queries into a
-     work space maintained by the terminal monitor.
-The <Application>psql</Application> program itself responds to special
-commands  that  begin
-     with  the  backslash  character, <literal>\</literal>.  For example, you
-     can get help on the syntax of various
- <ProductName>PostgreSQL</ProductName> <Acronym>SQL</Acronym> commands by typing:
-<ProgramListing>
-mydb=> \h
-</ProgramListing>
-
-     Once  you  have finished entering your queries into the
-     work space, you can pass the contents of  the  work space
-     to the <ProductName>PostgreSQL</ProductName> server by typing:
-<ProgramListing>
-mydb=> \g
-</ProgramListing>
-
-     This  tells  the  server  to process the query.  If you
-     terminate your query with a semicolon, the  <literal>\g</literal> is  not
-     necessary.   
-<Application>psql</Application> will automatically process semicolon terminated queries.
-     To read queries from a file,  say  <filename>myFile</filename>,  instead  of
-     entering them interactively, type:
-<ProgramListing>
-mydb=> \i myFile
-</ProgramListing>
-
-     To get out of <Application>psql</Application> and return to Unix, type
-<ProgramListing>
-mydb=> \q
-</ProgramListing>
-
-     and  <Application>psql</Application>  will  quit  and  return  you to your command
-     shell. (For more escape codes, type <Command>\?</Command> at  the  <command>psql</command>
-     prompt.)
-     White  space  (i.e.,  spaces, tabs and newlines) may be
-     used freely in <Acronym>SQL</Acronym> queries.  Single-line comments  are  denoted  by
-     <literal>--</literal>.   Everything  after the dashes up to the end of the
-     line is ignored. Multiple-line comments, and comments within a line,
-     are denoted by <literal>/* ... */</literal>.
-</Para>
-
-</Sect1>
-     
-<Sect1 id="db-destroy">
-<Title>Destroying a Database</Title>
-
-<Para>
-     If you are the owner of the  database
-     <Database>mydb</Database>,  you can destroy it using the SQL command
-<ProgramListing>
-=> DROP DATABASE mydb;
-</ProgramListing>
-     or the Unix shell script
-<ProgramListing>
-% dropdb mydb
-</ProgramListing>
-     This action physically removes all of the Unix files
-     associated  with  the database and cannot be undone, so
-     this should only be done with a great deal of forethought.
-</Para>
-</Sect1>
-
-</Chapter>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode:sgml
-sgml-omittag:nil
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:"./reference.ced"
-sgml-exposed-tags:nil
-sgml-local-catalogs:("/usr/lib/sgml/catalog")
-sgml-local-ecat-files:nil
-End:
--->

doc/src/sgml/runtime.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.138 2002/09/21 18:32:53 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.139 2002/09/25 21:16:10 petere Exp $
 -->
 
 <Chapter Id="runtime">
@@ -57,7 +57,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.138 2002/09/21 18:32:53 pe
    database cluster will contain a database named
    <literal>template1</literal>. As the name suggests, this will be used
    as a template for subsequently created databases; it should not be
-   used for actual work.
+   used for actual work.  (See <xref linkend="managing-databases"> for information
+   about creating databases.)
   </para>
 
   <para>
@@ -120,18 +121,17 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput>
 
   <para>
    However, while the directory contents are secure, the default
-   <filename>pg_hba.conf</filename> authentication method of
-   <literal>trust</literal> allows any local user to connect to the
+   client authentication setup allows any local user to connect to the
    database and even become the database superuser. If you don't trust
    other local users, we recommend you use <command>initdb</command>'s
    <option>-W</option> or <option>--pwprompt</option> option to assign a
    password to the database superuser. After <command>initdb</command>,
-   modify <filename>pg_hba.conf</filename> to use <literal>md5</> or
+   modify the <filename>pg_hba.conf</filename> file to use <literal>md5</> or
    <literal>password</> instead of <literal>trust</> authentication
    <emphasis>before</> you start the server for the first time. (Other,
    approaches include using <literal>ident</literal> authentication or
    file system permissions to restrict connections. See <xref
-   linkend="client-authentication"> for more information.
+   linkend="client-authentication"> for more information.)
   </para>
 
   <para>

doc/src/sgml/user-manag.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/user-manag.sgml,v 1.15 2002/09/12 22:05:36 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/user-manag.sgml,v 1.16 2002/09/25 21:16:10 petere Exp $
 -->
 
 <chapter id="user-manag">
- <title>Database Users and Permissions</title>
+ <title>Database Users and Privileges</title>
 
  <para>
-  Managing database users and their privileges is in concept similar
-  to managing the users of a Unix operating system, but the details
-  are not identical.
+  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
+  &cite-user;.
  </para>
 
  <sect1 id="database-users">
@@ -27,19 +36,27 @@ CREATE USER <replaceable>name</replaceable>
    <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
-   <command>DROP USER</command> command.
+   <command>DROP USER</command> command:
+<synopsis>
+DROP USER <replaceable>name</replaceable>
+</synopsis>
   </para>
 
   <para>
-   For convenience, the shell scripts <application>createuser</application>
-   and <application>dropuser</application> are provided as wrappers around these SQL
-   commands.
+   For convenience, the programs <application>createuser</application>
+   and <application>dropuser</application> 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>
    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
+   fixed ID 1, and by default (unless altered when running
    <application>initdb</application>) it will have the same name as
    the operating system user that initialized the database
    cluster. Customarily, this user will be named
@@ -48,21 +65,34 @@ CREATE USER <replaceable>name</replaceable>
   </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
-   <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
+   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 <application>psql</application> 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
+   <application>createuser</> and <application>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, in the same way a person is not
-   constrained in its login name by her real name.)
+   constrained in its login name by 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>
 
-  <sect2 id="user-attributes">
-   <title>User attributes</title>
+ <sect1 id="user-attributes">
+  <title>User Attributes</title>
 
    <para>
     A database user may have a number of attributes that define its
@@ -115,7 +145,23 @@ CREATE USER <replaceable>name</replaceable>
     See the reference pages for <command>CREATE USER</command> and
     <command>ALTER USER</command> for details.
    </para>
-  </sect2>
+
+  <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) and in
+   subsequent connections it will appear as though <literal>SET geqo
+   TO off;</literal> had been called right 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">
@@ -123,7 +169,7 @@ CREATE USER <replaceable>name</replaceable>
 
   <para>
    As in Unix, groups are a way of logically grouping users to ease
-   management of permissions: permissions can be granted to, or revoked
+   management of privileges: privileges can be granted to, or revoked
    from, a group as a whole.  To create a group, use
 <synopsis>
 CREATE GROUP <replaceable>name</replaceable>
@@ -203,11 +249,7 @@ REVOKE ALL ON accounts FROM PUBLIC;
    server that other users may execute without knowing it. Hence, both
    mechanisms permit users to <firstterm>Trojan horse</firstterm>
    others with relative impunity. The only real protection is tight
-   control over who can define functions (e.g., write to relations
-   with SQL fields) and triggers. Audit trails and alerters on the
-   system catalogs <literal>pg_class</literal>,
-   <literal>pg_shadow</literal> and <literal>pg_group</literal> are also
-   possible.
+   control over who can define functions.
   </para>
 
   <para>
@@ -219,7 +261,6 @@ REVOKE ALL ON accounts FROM PUBLIC;
    system access controls. This is an inherent problem with
    user-defined C functions.
   </para>
-
  </sect1>
 
 </chapter>

doc/src/sgml/user.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.31 2002/08/05 19:43:31 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.32 2002/09/25 21:16:10 petere Exp $
 -->
 
 <book id="user">
@@ -24,7 +24,6 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.31 2002/08/05 19:43:31
  &typeconv;
  &indices;
  &mvcc;
- &manage;
  &perform;
 
  <!-- appendices -->