SGML updates from post 6.3.2 manual changes. Added pg_upgrade man page.

doc/src/sgml/docguide.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.8 1998/08/17 16:17:07 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.9 1998/10/15 05:46:54 momjian Exp $
 Documentation Guide
 Thomas Lockhart
 
 $Log: docguide.sgml,v $
+Revision 1.9  1998/10/15 05:46:54  momjian
+SGML updates from post 6.3.2 manual changes.  Added pg_upgrade man page.
+
 Revision 1.8  1998/08/17 16:17:07  thomas
 Bring document list closer to up to day.
 Add a note on sgml-tools that they are now working with jade and so
@@ -464,6 +467,7 @@ Status
 <row><entry> ./src/man/page.5	</entry><entry>	Removed. Converted to page.sgml for Dev Guide	</entry></row>
 <row><entry> ./src/man/pg_dump.1	</entry><entry>	Assimilate into Admin Guide	</entry></row>
 <row><entry> ./src/man/pg_dumpall.1	</entry><entry>	Assimilate into Admin Guide	</entry></row>
+<row><entry> ./src/man/pg_upgrade.1	</entry><entry>	Assimilate into Admin Guide	</entry></row>
 <row><entry> ./src/man/pg_hba.conf.5	</entry><entry>	Assimilate into Admin Guide	</entry></row>
 <row><entry> ./src/man/pg_passwd.1	</entry><entry>	Assimilate into Admin Guide	</entry></row>
 <row><entry> ./src/man/pgbuiltin.3	</entry><entry>	Obsolete. Superceded by datatype.sgml	</entry></row>

doc/src/sgml/ref/allfiles.sgml

@@ -119,4 +119,5 @@
 <!entity initlocation       system "initlocation.sgml">
 <!entity pgDump            system "pg_dump.sgml">
 <!entity pgDumpall         system "pg_dumpall.sgml">
+<!entity pgUpgrade          system "pg_upgrade.sgml">
 <!entity psqlRef            system "psql-ref.sgml">

doc/src/sgml/ref/create_sequence.sgml

@@ -68,7 +68,7 @@ CREATE SEQUENCE <replaceable class="parameter">seqname</replaceable>
 	   The optional clause <option>MINVALUE
 	   <replaceable class="parameter">minvalue</replaceable></option>
 	   determines the minimum value
-	   a sequence can be. The defaults are 1 and -2147483647 for
+	   a sequence can generate. The defaults are 1 and -2147483647 for
 	   ascending and descending sequences, respectively.
 	  </PARA>
 	 </LISTITEM>
@@ -113,7 +113,8 @@ CREATE SEQUENCE <replaceable class="parameter">seqname</replaceable>
 	   The <option>CACHE <replaceable class="parameter">cache</replaceable></option> option
 	   enables sequence numbers to be preallocated
 	   and stored in memory for faster access. The  minimum
-	   value is 1 (no cache) and this is also the default.
+	   value is 1 (only one value can be generated at a time, i.e. no cache)
+	   and this is also the default.
 	  </PARA>
 	 </LISTITEM>
 	</VARLISTENTRY>
@@ -223,12 +224,12 @@ CREATE SEQUENCE <replaceable class="parameter">seqname</replaceable>
   <PARA>
    CREATE SEQUENCE will enter a new sequence number generator
    into the current data base. This involves creating and initialising a
-   new single block
+   new single-row
    table with the name <replaceable class="parameter">seqname</replaceable>.
    The generator will be "owned" by the user issuing the command.
   </PARA>
   <para>
-   After the sequence is created, you may use the function
+   After a sequence is created, you may use the function
 <function>nextval(<replaceable class="parameter">seqname</replaceable>)</function>
 to get a new number from the sequence.
 The function
@@ -245,12 +246,43 @@ The function
 SELECT * FROM sequence_name;
    </programlisting>
    to get the parameters of a sequence.
+   Aside from fetching the original
+   parameters, you can use
+   <programlisting>
+SELECT last_value FROM sequence_name;
+   </programlisting>
+   to obtain the last value allocated by any backend.
+   parameters, you can use
   </para>
   <para>
    Low-level locking is used to enable multiple simultaneous
    calls to a generator.
   </para>
 
+  <para>
+  <TITLE>
+  NOTE:
+  </TITLE>
+  Unexpected results may be obtained if a cache setting greater than one
+  is used for a sequence object that will be used concurrently by multiple
+  backends.  Each backend will allocate "cache" successive sequence values
+  during one access to the sequence object and increase the sequence
+  object's last_value accordingly.  Then, the next cache-1 uses of nextval
+  within that backend simply return the preallocated values without touching
+  the shared object.  So, numbers allocated but not used in the current session
+  will be lost.  Furthermore, although multiple backends are guaranteed to
+  allocate distinct sequence values, the values may be generated out of
+  sequence when all the backends are considered.  (For example, with a cache
+  setting of 10, backend A might reserve values 1..10 and return nextval=1, then
+  backend B might reserve values 11..20 and return nextval=11 before backend
+  A has generated nextval=2.)  Thus, with a cache setting of one it is safe
+  to assume that nextval values are generated sequentially; with a cache
+  setting greater than one you should only assume that the nextval values
+  are all distinct, not that they are generated purely sequentially.
+  Also, last_value will reflect the latest value reserved by any backend,
+  whether or not it has yet been returned by nextval.
+  </para>
+  
   <REFSECT2 ID="R2-SQL-CREATESEQUENCE-3">
    <REFSECT2INFO>
     <DATE>1998-09-11</DATE>

doc/src/sgml/ref/create_table.sgml

@@ -19,9 +19,13 @@
   </REFSYNOPSISDIVINFO>
   <SYNOPSIS>
 CREATE TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> (
-    <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">type</REPLACEABLE> [ DEFAULT <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE> | <REPLACEABLE>column_constraint_clause</REPLACEABLE> | PRIMARY KEY } [ ... ] ]
+    <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">type</REPLACEABLE>
+    [ DEFAULT <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE>]
+    [, NOT NULL ] [ ,UNIQUE ]
+    [<REPLACEABLE>column_constraint_clause</REPLACEABLE> | PRIMARY KEY } [ ... ] ]
     [, ... ]
     [, PRIMARY KEY ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) ]
+    [, CHECK ( <REPLACEABLE CLASS="PARAMETER">condition</REPLACEABLE> ) ]
     [, <REPLACEABLE>table_constraint_clause</REPLACEABLE> ]
     ) [ INHERITS ( <REPLACEABLE>inherited_table</REPLACEABLE> [, ...] ) ]
   </SYNOPSIS>
@@ -89,8 +93,8 @@ CREATE TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> (
      </TERM>
      <LISTITEM>
       <PARA>
-       The optional column constraint clause specifies a list of integrity 
-       constraints which new or updated entries must satisfy for
+       The optional column constraint clauses specify a list of integrity 
+       constraints or tests which new or updated entries must satisfy for
        an insert or update operation to succeed. Each constraint
        must evaluate to a boolean expression. Although <acronym>SQL92</acronym>
 requires the <REPLACEABLE CLASS="PARAMETER">column_constraint_clause</REPLACEABLE>
@@ -113,6 +117,16 @@ requires the <REPLACEABLE CLASS="PARAMETER">column_constraint_clause</REPLACEABL
        an insert or update operation to succeed. Each constraint
        must evaluate to a boolean expression. Multiple columns
        may be referenced within a single constraint.
+       The use of
+       <TERM>
+       PRIMARY KEY <REPLACEABLE>column</REPLACEABLE>
+       </TERM>
+       as a table constraint
+       is mutually incompatible with
+       <TERM>
+       PRIMARY KEY
+       </TERM>
+       used as a column constraint.
        See the table constraint clause for more information.
       </PARA>
      </LISTITEM>

doc/src/sgml/ref/explain.sgml

@@ -101,7 +101,8 @@ Description
 <PARA>
    This command outputs details about the supplied query.
    The default output is the computed query cost. 
-   VERBOSE displays the full query plan and cost.
+   VERBOSE displays the full query plan and cost to your screen,
+   and pretty-prints the plan to the postmaster log file.   
 
 <REFSECT2 ID="R2-SQL-EXPLAIN-3">
 <REFSECT2INFO>

doc/src/sgml/ref/load.sgml

@@ -154,7 +154,7 @@ Usage
 <ProgramListing>
 --Load the file /usr/postgres/demo/circle.o
 --
-LOAD "/usr/postgres/demo/circle.o"
+LOAD '/usr/postgres/demo/circle.o'
 </ProgramListing>
         
 </REFSECT1>

doc/src/sgml/ref/pg_upgrade.sgml

+<REFENTRY ID="APP-PG-UPGRADE">
+<REFMETA>
+<REFENTRYTITLE>
+<application>pg_upgrade</application>
+</REFENTRYTITLE>
+<REFMISCINFO>Application</REFMISCINFO>
+</REFMETA>
+<REFNAMEDIV>
+<REFNAME>
+<application>pg_upgrade</application>
+</REFNAME>
+<REFPURPOSE>
+Allows upgrade from a previous release without reloading data
+</REFPURPOSE>
+<REFSYNOPSISDIV>
+<REFSYNOPSISDIVINFO>
+<DATE>1998-10-04</DATE>
+</REFSYNOPSISDIVINFO>
+<SYNOPSIS>
+pg_upgrade
+pg_upgrade [-f <replaceable class="parameter">input_file</replaceable>] <replaceable class="parameter">old_data_dir</replaceable>
+</SYNOPSIS>
+
+<REFSECT1 ID="R1-APP-PG-UPGRADE-1">
+<REFSECT1INFO>
+<DATE>1998-10-04</DATE>
+</REFSECT1INFO>
+<TITLE>
+Description
+</TITLE>
+<PARA>
+<application>pg_upgrade</application>
+ is a utility for upgrading from a previous
+ PostgreSQL release without reloading all the data.  First,
+ to be safe, back up your data directory.  Then, use:
+<programlisting>
+% pg_dumpall -s >db.out
+</programlisting>
+to dump out your old  database definitions without any
+data.  Stop the postmaster and all backends.
+</para>
+
+<para>
+Then  rename  (using mv) your old pgsql /data directory to
+/data.old and do a make install to install the new binaries.
+Run initdb to create a new template1 database containing the system
+tables for the new release.  Start the new postmaster, cd to the 
+pgsql main directory, and type:
+<programlisting>
+% pg_upgrade -f db.out data.old
+</programlisting>
+The  system  will do some checking to make sure everything
+is properly configured, and run your db.out script to create
+all the  databases and  tables you had, but with no
+data.  It will then move the  data  files  from /data.old
+into  the  proper /data directory.  You can then check out
+the data.  You can delete the /data.old directory when you
+are finished.
+</REFENTRY>

doc/src/sgml/ref/psql-ref.sgml

@@ -165,6 +165,7 @@ Outputs
 <application>psql</application>
 returns 0 to the shell on successful completion of all queries,
 1 for errors, 2 for abrupt disconnection from the backend.
+The default TAB delimiter is used.
 <application>psql</application>
 will also return 1 if the connection to a database could not be made for
 any reason.

doc/src/sgml/ref/select.sgml

@@ -17,7 +17,7 @@
    <date>1998-09-24</date>
   </refsynopsisdivinfo>
   <synopsis>
-SELECT [ALL|DISTINCT]
+SELECT [ALL|DISTINCT [ON <replaceable class="PARAMETER">column</replaceable>] ]
     <replaceable class="PARAMETER">expression</replaceable> [ AS <replaceable class="PARAMETER">name</replaceable> ] [, ...]
     [ INTO [TABLE] <replaceable class="PARAMETER">new_table</replaceable> ]
     [ FROM <replaceable class="PARAMETER">table</replaceable> [<replaceable class="PARAMETER">alias</replaceable> ] [, ...] ]