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