From 3c4e2bc9be076805dfc2561628aa575f1c8db0cf Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Thu, 15 Oct 1998 05:47:04 +0000
Subject: [PATCH] SGML updates from post 6.3.2 manual changes.  Added
 pg_upgrade man page.

---
 doc/src/sgml/docguide.sgml            |   6 +-
 doc/src/sgml/libpq.sgml               | 650 ++++++++++++++------------
 doc/src/sgml/ref/allfiles.sgml        |   1 +
 doc/src/sgml/ref/create_sequence.sgml |  40 +-
 doc/src/sgml/ref/create_table.sgml    |  20 +-
 doc/src/sgml/ref/explain.sgml         |   3 +-
 doc/src/sgml/ref/load.sgml            |   2 +-
 doc/src/sgml/ref/pg_upgrade.sgml      |  59 +++
 doc/src/sgml/ref/psql-ref.sgml        |   3 +-
 doc/src/sgml/ref/select.sgml          |   2 +-
 10 files changed, 477 insertions(+), 309 deletions(-)
 create mode 100644 doc/src/sgml/ref/pg_upgrade.sgml

diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index e092663790..f5ecbfe950 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -1,9 +1,12 @@
 <!--
-$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>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 3038b4a51e..7caa0ce444 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1513,113 +1513,130 @@ for information on correct values for these environment variables.
 <Para>
 <ProgramListing>
 /*
-* testlibpq.c
-*   Test the C version of LIBPQ,
-+   the <ProductName>Postgres</ProductName> frontend library.
-*
-*
-*/
+ * testlibpq.c Test the C version of Libpq, the Postgres frontend
+ * library.
+ *
+ *
+ */
 #include &lt;stdio.h&gt;
 #include "libpq-fe.h"
 
 void
-exit_nicely(PGconn* conn)
+exit_nicely(PGconn *conn)
 {
-     PQfinish(conn);
-     exit(1);
+    PQfinish(conn);
+    exit(1);
 }
 
 main()
 {
-  char *pghost, *pgport, *pgoptions, *pgtty;
-  char* dbName;
-  int nFields;
-  int i,j;
-
-/*  FILE *debug; */
-
-  PGconn* conn;
-  PGresult* res;
-
-  /* begin, by setting the parameters for a backend connection
-     if the parameters are null, then the system will try to use
-     reasonable defaults by looking up environment variables
-     or, failing that, using hardwired constants */
-  pghost = NULL;  /* host name of the backend server */
-  pgport = NULL;  /* port of the backend server */
-  pgoptions = NULL; /* special options to start up the backend server */
-  pgtty = NULL;     /* debugging tty for the backend server */
-  dbName = "template1";
-
-  /* make a connection to the database */
-  conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
-
-  /* check to see that the backend connection was successfully made */
-  if (PQstatus(conn) == CONNECTION_BAD) {
-    fprintf(stderr,"Connection to database '&percnt;s' failed.\n", dbName);
-    fprintf(stderr,"&percnt;s",PQerrorMessage(conn));
-    exit_nicely(conn);
-  }
-
-  /*  debug = fopen("/tmp/trace.out","w");  */
-  /*   PQtrace(conn, debug);  */
-
-  /* start a transaction block */
-
-  res = PQexec(conn,"BEGIN");
-  if (PQresultStatus(res) != PGRES_COMMAND_OK) {
-    fprintf(stderr,"BEGIN command failed\n");
-    PQclear(res);
-    exit_nicely(conn);
-  }
-  /* should PQclear PGresult when done to avoid memory leaks */
-  PQclear(res);
-
-  /* fetch instances from the pg_database, the system catalog of databases*/
-  res = PQexec(conn,"DECLARE mycursor CURSOR FOR select * from pg_database");
-  if (PQresultStatus(res) != PGRES_COMMAND_OK) {
-    fprintf(stderr,"DECLARE CURSOR command failed\n");
+    char       *pghost,
+               *pgport,
+               *pgoptions,
+               *pgtty;
+    char       *dbName;
+    int         nFields;
+    int         i,
+                j;
+
+    /* FILE *debug; */
+
+    PGconn     *conn;
+    PGresult   *res;
+
+    /*
+     * begin, by setting the parameters for a backend connection if the
+     * parameters are null, then the system will try to use reasonable
+     * defaults by looking up environment variables or, failing that,
+     * using hardwired constants
+     */
+    pghost = NULL;              /* host name of the backend server */
+    pgport = NULL;              /* port of the backend server */
+    pgoptions = NULL;           /* special options to start up the backend
+                                 * server */
+    pgtty = NULL;               /* debugging tty for the backend server */
+    dbName = "template1";
+
+    /* make a connection to the database */
+    conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
+
+    /*
+     * check to see that the backend connection was successfully made
+     */
+    if (PQstatus(conn) == CONNECTION_BAD)
+    {
+        fprintf(stderr, "Connection to database '&percnt;s' failed.\n", dbName);
+        fprintf(stderr, "&percnt;s", PQerrorMessage(conn));
+        exit_nicely(conn);
+    }
+
+    /* debug = fopen("/tmp/trace.out","w"); */
+    /* PQtrace(conn, debug);  */
+
+    /* start a transaction block */
+    res = PQexec(conn, "BEGIN");
+    if (PQresultStatus(res) != PGRES_COMMAND_OK)
+    {
+        fprintf(stderr, "BEGIN command failed\n");
+        PQclear(res);
+        exit_nicely(conn);
+    }
+
+    /*
+     * should PQclear PGresult whenever it is no longer needed to avoid
+     * memory leaks
+     */
     PQclear(res);
-    exit_nicely(conn);
-  }
-  PQclear(res);
 
-  res = PQexec(conn,"FETCH ALL in mycursor");
-  if (PQresultStatus(res) != PGRES_TUPLES_OK) {
-    fprintf(stderr,"FETCH ALL command didn't return tuples properly\n");
+    /*
+     * fetch instances from the pg_database, the system catalog of
+     * databases
+     */
+    res = PQexec(conn, "DECLARE mycursor CURSOR FOR select * from pg_database");
+    if (PQresultStatus(res) != PGRES_COMMAND_OK)
+    {
+        fprintf(stderr, "DECLARE CURSOR command failed\n");
+        PQclear(res);
+        exit_nicely(conn);
+    }
     PQclear(res);
-    exit_nicely(conn);
-  }
-
-  /* first, print out the attribute names */
-  nFields = PQnfields(res);
-  for (i=0; i &lt; nFields; i++) {
-    printf("&percnt;-15s",PQfname(res,i));
-  }
-  printf("\n");
-
-  /* next, print out the instances */
-  for (i=0; i &lt; PQntuples(res); i++) {
-    for (j=0  ; j &lt; nFields; j++) {
-      printf("&percnt;-15s", PQgetvalue(res,i,j));
+
+    res = PQexec(conn, "FETCH ALL in mycursor");
+    if (PQresultStatus(res) != PGRES_TUPLES_OK)
+    {
+        fprintf(stderr, "FETCH ALL command didn't return tuples properly\n");
+        PQclear(res);
+        exit_nicely(conn);
     }
-    printf("\n");
-  }
 
-  PQclear(res);
+    /* first, print out the attribute names */
+    nFields = PQnfields(res);
+    for (i = 0; i &lt; nFields; i++)
+        printf("&percnt;-15s", PQfname(res, i));
+    printf("\n\n");
+
+    /* next, print out the instances */
+    for (i = 0; i &lt; PQntuples(res); i++)
+    {
+        for (j = 0; j &lt; nFields; j++)
+            printf("&percnt;-15s", PQgetvalue(res, i, j));
+        printf("\n");
+    }
 
-  /* close the cursor */
-  res = PQexec(conn, "CLOSE mycursor");
-  PQclear(res);
+    PQclear(res);
 
-  /* end the transaction */
-  res = PQexec(conn, "END");
-  PQclear(res);
+    /* close the cursor */
+    res = PQexec(conn, "CLOSE mycursor");
+    PQclear(res);
+
+    /* commit the transaction */
+    res = PQexec(conn, "COMMIT");
+    PQclear(res);
 
-  /* close the connection to the database and cleanup */
-  PQfinish(conn);
+    /* close the connection to the database and cleanup */
+    PQfinish(conn);
 
-/*   fclose(debug); */
+    /* fclose(debug); */
 }
 </ProgramListing>
 </Para>
@@ -1631,94 +1648,112 @@ main()
 <Para>
 <ProgramListing>
 /*
- * testlibpq2.c
- *   Test of the asynchronous notification interface
+ * testlibpq2.c Test of the asynchronous notification interface
  *
-   populate a database with the following:
-
-   CREATE TABLE TBL1 (i int4);
-
-   CREATE TABLE TBL2 (i int4);
-
-   CREATE RULE r1 AS ON INSERT TO TBL1 
-   DO [INSERT INTO TBL2 values (new.i); NOTIFY TBL2];
-
-* Then start up this program
-* After the program has begun, do
-
-   INSERT INTO TBL1 values (10);
-
-*
-*
-*/
+ * populate a database with the following:
+ *
+ * CREATE TABLE TBL1 (i int4);
+ *
+ * CREATE TABLE TBL2 (i int4);
+ *
+ * CREATE RULE r1 AS ON INSERT TO TBL1 DO [INSERT INTO TBL2 values
+ * (new.i); NOTIFY TBL2];
+ *
+ * Then start up this program After the program has begun, do
+ *
+ * INSERT INTO TBL1 values (10);
+ *
+ *
+ *
+ */
 #include &lt;stdio.h&gt;
 #include "libpq-fe.h"
 
-void exit_nicely(PGconn* conn)
+void
+exit_nicely(PGconn *conn)
 {
-  PQfinish(conn);
-  exit(1);
+    PQfinish(conn);
+    exit(1);
 }
 
 main()
 {
-  char *pghost, *pgport, *pgoptions, *pgtty;
-  char* dbName;
-  int nFields;
-  int i,j;
-
-  PGconn* conn;
-  PGresult* res;
-  PGnotify* notify;
-
-  /* begin, by setting the parameters for a backend connection
-     if the parameters are null, then the system will try to use
-     reasonable defaults by looking up environment variables
-     or, failing that, using hardwired constants */
-  pghost = NULL;  /* host name of the backend server */
-  pgport = NULL;  /* port of the backend server */
-  pgoptions = NULL; /* special options to start up the backend server */
-  pgtty = NULL;     /* debugging tty for the backend server */
-  dbName = getenv("USER"); /* change this to the name of your test database*/
-
-  /* make a connection to the database */
-  conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
-
-  /* check to see that the backend connection was successfully made */
-  if (PQstatus(conn) == CONNECTION_BAD) {
-    fprintf(stderr,"Connection to database '&percnt;s' failed.\n", dbName);
-    fprintf(stderr,"&percnt;s",PQerrorMessage(conn));
-    exit_nicely(conn);
-  }
-
-  res = PQexec(conn, "LISTEN TBL2");
-  if (PQresultStatus(res) != PGRES_COMMAND_OK) {
-    fprintf(stderr,"LISTEN command failed\n");
-    PQclear(res);
-    exit_nicely(conn);
-  }
-  /* should PQclear PGresult whenever it is no longer needed to avoid
-     memory leaks */
-  PQclear(res);
-
-  while (1) {
-    /* wait a little bit between checks;
-     * waiting with select() would be more efficient.
+    char       *pghost,
+               *pgport,
+               *pgoptions,
+               *pgtty;
+    char       *dbName;
+    int         nFields;
+    int         i,
+                j;
+
+    PGconn     *conn;
+    PGresult   *res;
+    PGnotify   *notify;
+
+    /*
+     * begin, by setting the parameters for a backend connection if the
+     * parameters are null, then the system will try to use reasonable
+     * defaults by looking up environment variables or, failing that,
+     * using hardwired constants
+     */
+    pghost = NULL;              /* host name of the backend server */
+    pgport = NULL;              /* port of the backend server */
+    pgoptions = NULL;           /* special options to start up the backend
+                                 * server */
+    pgtty = NULL;               /* debugging tty for the backend server */
+    dbName = getenv("USER");    /* change this to the name of your test
+                                 * database */
+
+    /* make a connection to the database */
+    conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
+
+    /*
+     * check to see that the backend connection was successfully made
+     */
+    if (PQstatus(conn) == CONNECTION_BAD)
+    {
+        fprintf(stderr, "Connection to database '&percnt;s' failed.\n", dbName);
+        fprintf(stderr, "&percnt;s", PQerrorMessage(conn));
+        exit_nicely(conn);
+    }
+
+    res = PQexec(conn, "LISTEN TBL2");
+    if (PQresultStatus(res) != PGRES_COMMAND_OK)
+    {
+        fprintf(stderr, "LISTEN command failed\n");
+        PQclear(res);
+        exit_nicely(conn);
+    }
+
+    /*
+     * should PQclear PGresult whenever it is no longer needed to avoid
+     * memory leaks
      */
-    sleep(1);
-    /* collect any asynchronous backend messages */
-    PQconsumeInput(conn);
-    /* check for asynchronous notify messages */
-    while ((notify = PQnotifies(conn)) != NULL) {
-      fprintf(stderr,
-        "ASYNC NOTIFY of '&percnt;s' from backend pid '&percnt;d' received\n",
-        notify-&gt;relname, notify-&gt;be_pid);
-      free(notify);
+    PQclear(res);
+
+    while (1)
+    {
+
+        /*
+         * wait a little bit between checks; waiting with select()
+         * would be more efficient.
+         */
+        sleep(1);
+        /* collect any asynchronous backend messages */
+        PQconsumeInput(conn);
+        /* check for asynchronous notify messages */
+        while ((notify = PQnotifies(conn)) != NULL)
+        {
+            fprintf(stderr,
+                 "ASYNC NOTIFY of '&percnt;s' from backend pid '&percnt;d' received\n",
+                    notify-&gt;relname, notify-&gt;be_pid);
+            free(notify);
+        }
     }
-  }
 
-  /* close the connection to the database and cleanup */
-  PQfinish(conn);
+    /* close the connection to the database and cleanup */
+    PQfinish(conn);
 
 }
 </ProgramListing>
@@ -1731,155 +1766,176 @@ main()
 <Para>
 <ProgramListing>
 /*
- * testlibpq3.c
- *   Test the C version of LIBPQ,
- +   the <ProductName>Postgres</ProductName> frontend library
- *   tests the binary cursor interface
+ * testlibpq3.c Test the C version of Libpq, the Postgres frontend
+ * library. tests the binary cursor interface
  *
  *
  *
-   populate a database by doing the following:
-
-   CREATE TABLE test1 (i int4, d float4, p polygon);
-
-   INSERT INTO test1 values (1, 3.567, '(3.0, 4.0, 1.0, 2.0)'::polygon);
-
-   INSERT INTO test1 values (2, 89.05, '(4.0, 3.0, 2.0, 1.0)'::polygon);
-
-   the expected output is:
-
-  tuple 0: got
-  i = (4 bytes) 1,
-  d = (4 bytes) 3.567000,
-  p = (4 bytes) 2 points
-         boundbox = (hi=3.000000/4.000000, lo = 1.000000,2.000000)
- tuple 1: got
-  i = (4 bytes) 2,
-  d = (4 bytes) 89.050003,
-  p = (4 bytes) 2 points
-         boundbox = (hi=4.000000/3.000000, lo = 2.000000,1.000000)
+ * populate a database by doing the following:
+ *
+ * CREATE TABLE test1 (i int4, d float4, p polygon);
+ *
+ * INSERT INTO test1 values (1, 3.567, '(3.0, 4.0, 1.0,
+ * 2.0)'::polygon);
+ *
+ * INSERT INTO test1 values (2, 89.05, '(4.0, 3.0, 2.0,
+ * 1.0)'::polygon);
+ *
+ * the expected output is:
+ *
+ * tuple 0: got i = (4 bytes) 1, d = (4 bytes) 3.567000, p = (4
+ * bytes) 2 points   boundbox = (hi=3.000000/4.000000, lo =
+ * 1.000000,2.000000) tuple 1: got i = (4 bytes) 2, d = (4 bytes)
+ * 89.050003, p = (4 bytes) 2 points   boundbox =
+ * (hi=4.000000/3.000000, lo = 2.000000,1.000000)
+ *
  *
  */
 #include &lt;stdio.h&gt;
 #include "libpq-fe.h"
-#include "utils/geo-decls.h" /* for the POLYGON type */
+#include "utils/geo-decls.h"    /* for the POLYGON type */
 
-void exit_nicely(PGconn* conn)
+void
+exit_nicely(PGconn *conn)
 {
-  PQfinish(conn);
-  exit(1);
+    PQfinish(conn);
+    exit(1);
 }
 
 main()
 {
-  char *pghost, *pgport, *pgoptions, *pgtty;
-  char* dbName;
-  int nFields;
-  int i,j;
-  int i_fnum, d_fnum, p_fnum;
-
-  PGconn* conn;
-  PGresult* res;
-
-  /* begin, by setting the parameters for a backend connection
-     if the parameters are null, then the system will try to use
-     reasonable defaults by looking up environment variables
-     or, failing that, using hardwired constants */
-  pghost = NULL;  /* host name of the backend server */
-  pgport = NULL;  /* port of the backend server */
-  pgoptions = NULL; /* special options to start up the backend server */
-  pgtty = NULL;     /* debugging tty for the backend server */
-
-  dbName = getenv("USER");  /* change this to the name of your test database*/
-
-  /* make a connection to the database */
-  conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
-
-  /* check to see that the backend connection was successfully made */
-  if (PQstatus(conn) == CONNECTION_BAD) {
-    fprintf(stderr,"Connection to database '&percnt;s' failed.\n", dbName);
-    fprintf(stderr,"&percnt;s",PQerrorMessage(conn));
-    exit_nicely(conn);
-  }
-
-  /* start a transaction block */
-  res = PQexec(conn,"BEGIN");
-  if (PQresultStatus(res) != PGRES_COMMAND_OK) {
-    fprintf(stderr,"BEGIN command failed\n");
+    char       *pghost,
+               *pgport,
+               *pgoptions,
+               *pgtty;
+    char       *dbName;
+    int         nFields;
+    int         i,
+                j;
+    int         i_fnum,
+                d_fnum,
+                p_fnum;
+    PGconn     *conn;
+    PGresult   *res;
+
+    /*
+     * begin, by setting the parameters for a backend connection if the
+     * parameters are null, then the system will try to use reasonable
+     * defaults by looking up environment variables or, failing that,
+     * using hardwired constants
+     */
+    pghost = NULL;              /* host name of the backend server */
+    pgport = NULL;              /* port of the backend server */
+    pgoptions = NULL;           /* special options to start up the backend
+                                 * server */
+    pgtty = NULL;               /* debugging tty for the backend server */
+
+    dbName = getenv("USER");    /* change this to the name of your test
+                                 * database */
+
+    /* make a connection to the database */
+    conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
+
+    /*
+     * check to see that the backend connection was successfully made
+     */
+    if (PQstatus(conn) == CONNECTION_BAD)
+    {
+        fprintf(stderr, "Connection to database '&percnt;s' failed.\n", dbName);
+        fprintf(stderr, "&percnt;s", PQerrorMessage(conn));
+        exit_nicely(conn);
+    }
+
+    /* start a transaction block */
+    res = PQexec(conn, "BEGIN");
+    if (PQresultStatus(res) != PGRES_COMMAND_OK)
+    {
+        fprintf(stderr, "BEGIN command failed\n");
+        PQclear(res);
+        exit_nicely(conn);
+    }
+
+    /*
+     * should PQclear PGresult whenever it is no longer needed to avoid
+     * memory leaks
+     */
+    PQclear(res);
+
+    /*
+     * fetch instances from the pg_database, the system catalog of
+     * databases
+     */
+    res = PQexec(conn, "DECLARE mycursor BINARY CURSOR FOR select * from test1");
+    if (PQresultStatus(res) != PGRES_COMMAND_OK)
+    {
+        fprintf(stderr, "DECLARE CURSOR command failed\n");
+        PQclear(res);
+        exit_nicely(conn);
+    }
+    PQclear(res);
+
+    res = PQexec(conn, "FETCH ALL in mycursor");
+    if (PQresultStatus(res) != PGRES_TUPLES_OK)
+    {
+        fprintf(stderr, "FETCH ALL command didn't return tuples properly\n");
+        PQclear(res);
+        exit_nicely(conn);
+    }
+
+    i_fnum = PQfnumber(res, "i");
+    d_fnum = PQfnumber(res, "d");
+    p_fnum = PQfnumber(res, "p");
+
+    for (i = 0; i &lt; 3; i++)
+    {
+        printf("type[&percnt;d] = &percnt;d, size[&percnt;d] = &percnt;d\n",
+               i, PQftype(res, i),
+               i, PQfsize(res, i));
+    }
+    for (i = 0; i &lt; PQntuples(res); i++)
+    {
+        int        *ival;
+        float      *dval;
+        int         plen;
+        POLYGON    *pval;
+
+        /* we hard-wire this to the 3 fields we know about */
+        ival = (int *) PQgetvalue(res, i, i_fnum);
+        dval = (float *) PQgetvalue(res, i, d_fnum);
+        plen = PQgetlength(res, i, p_fnum);
+
+        /*
+         * plen doesn't include the length field so need to
+         * increment by VARHDSZ
+         */
+        pval = (POLYGON *) malloc(plen + VARHDRSZ);
+        pval-&gt;size = plen;
+        memmove((char *) &pval-&gt;npts, PQgetvalue(res, i, p_fnum), plen);
+        printf("tuple &percnt;d: got\n", i);
+        printf(" i = (&percnt;d bytes) &percnt;d,\n",
+               PQgetlength(res, i, i_fnum), *ival);
+        printf(" d = (&percnt;d bytes) &percnt;f,\n",
+               PQgetlength(res, i, d_fnum), *dval);
+        printf(" p = (&percnt;d bytes) &percnt;d points \tboundbox = (hi=&percnt;f/&percnt;f, lo = &percnt;f,&percnt;f)\n",
+               PQgetlength(res, i, d_fnum),
+               pval-&gt;npts,
+               pval-&gt;boundbox.xh,
+               pval-&gt;boundbox.yh,
+               pval-&gt;boundbox.xl,
+               pval-&gt;boundbox.yl);
+    }
     PQclear(res);
-    exit_nicely(conn);
-  }
-  /* should PQclear PGresult whenever it is no longer needed to avoid
-     memory leaks */
-  PQclear(res);
-
-  /* fetch instances from the pg_database, the system catalog of databases*/
-  res = PQexec(conn,"DECLARE mycursor BINARY CURSOR FOR select * from test1");
-  if (PQresultStatus(res) != PGRES_COMMAND_OK) {
-    fprintf(stderr,"DECLARE CURSOR command failed\n");
+
+    /* close the cursor */
+    res = PQexec(conn, "CLOSE mycursor");
     PQclear(res);
-    exit_nicely(conn);
-  }
-  PQclear(res);
 
-  res = PQexec(conn,"FETCH ALL in mycursor");
-  if (PQresultStatus(res) != PGRES_TUPLES_OK) {
-    fprintf(stderr,"FETCH ALL command didn't return tuples properly\n");
+    /* commit the transaction */
+    res = PQexec(conn, "COMMIT");
     PQclear(res);
-    exit_nicely(conn);
-  }
-
-  i_fnum = PQfnumber(res,"i");
-  d_fnum = PQfnumber(res,"d");
-  p_fnum = PQfnumber(res,"p");
-
-  for (i=0;i&lt;3;i++) {
-      printf("type[&percnt;d] = &percnt;d, size[&percnt;d] = &percnt;d\n",
- i, PQftype(res,i),
-          i, PQfsize(res,i));
-  }
-  for (i=0; i &lt; PQntuples(res); i++) {
-    int *ival;
-    float *dval;
-    int plen;
-    POLYGON* pval;
-    /*/
-    ival =  (int*)PQgetvalue(res,i,i_fnum);
-    dval =  (float*)PQgetvalue(res,i,d_fnum);
-    plen = PQgetlength(res,i,p_fnum);
-
-    /* plen doesn't include the length field so need to increment by VARHDSZ*/
-    pval = (POLYGON*) malloc(plen + VARHDRSZ);
-    pval-&gt;size = plen;
-    memmove((char*)&amp;pval-&gt;npts, PQgetvalue(res,i,p_fnum), plen);
-    printf("tuple &percnt;d: got\n", i);
-    printf(" i = (&percnt;d bytes) &percnt;d,\n",
-        PQgetlength(res,i,i_fnum), *ival);
-    printf(" d = (&percnt;d bytes) &percnt;f,\n",
-        PQgetlength(res,i,d_fnum), *dval);
-    printf(" p = (&percnt;d bytes) &percnt;d points"
-           " boundbox = (hi=&percnt;f/&percnt;f"
-           ", lo = &percnt;f,&percnt;f)\n",
-        PQgetlength(res,i,d_fnum),
-        pval-&gt;npts,
-        pval-&gt;boundbox.xh,
-        pval-&gt;boundbox.yh,
-        pval-&gt;boundbox.xl,
-        pval-&gt;boundbox.yl);
-  }
-
-  PQclear(res);
-
-  /* close the cursor */
-  res = PQexec(conn, "CLOSE mycursor");
-  PQclear(res);
-
-  /* end the transaction */
-  res = PQexec(conn, "END");
-  PQclear(res);
-
-  /* close the connection to the database and cleanup */
-  PQfinish(conn);
+
+    /* close the connection to the database and cleanup */
+    PQfinish(conn);
 
 }
 </ProgramListing>
diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml
index 5c5c496d88..37d3d54384 100644
--- a/doc/src/sgml/ref/allfiles.sgml
+++ b/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">
diff --git a/doc/src/sgml/ref/create_sequence.sgml b/doc/src/sgml/ref/create_sequence.sgml
index d678bb319c..2ba60a56d4 100644
--- a/doc/src/sgml/ref/create_sequence.sgml
+++ b/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,11 +246,42 @@ 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>
diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index 0081f66726..241d93c95d 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/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>
diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml
index 8173ac0b1f..9b2d989964 100644
--- a/doc/src/sgml/ref/explain.sgml
+++ b/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>
diff --git a/doc/src/sgml/ref/load.sgml b/doc/src/sgml/ref/load.sgml
index ad355e0c20..6614e73245 100644
--- a/doc/src/sgml/ref/load.sgml
+++ b/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>
diff --git a/doc/src/sgml/ref/pg_upgrade.sgml b/doc/src/sgml/ref/pg_upgrade.sgml
new file mode 100644
index 0000000000..7ee84fa0d3
--- /dev/null
+++ b/doc/src/sgml/ref/pg_upgrade.sgml
@@ -0,0 +1,59 @@
+<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>
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 95832a7e4e..a1cf38cb73 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/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.
@@ -865,4 +866,4 @@ Get help information about the slash (<quote>\</quote>) commands.
 
 </variablelist>
 
-</refentry>
\ No newline at end of file
+</refentry>
diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index 9296addfea..491f7a16ae 100644
--- a/doc/src/sgml/ref/select.sgml
+++ b/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> ] [, ...] ]
-- 
2.40.0