Thread: Removal of backward-compatibility docs mentions

The attached patch removes or minimizes some documentation mentions of
backward compatibility for release 7.2 and earlier.  I have not altered
any mentions of release 7.3 or later.  The release notes were not
modified, so the changes are still documented, just not in the main
docs.

--
  Bruce Momjian   http://candle.pha.pa.us
  SRA OSS, Inc.   http://www.sraoss.com

  + If your life is a hard drive, Christ can be your backup. +
Index: doc/src/sgml/array.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/array.sgml,v
retrieving revision 1.48
diff -c -c -r1.48 array.sgml
*** doc/src/sgml/array.sgml    19 Nov 2005 01:50:08 -0000    1.48
--- doc/src/sgml/array.sgml    20 Mar 2006 18:40:41 -0000
***************
*** 559,566 ****
     embedded in element values will be backslash-escaped.  For numeric
     data types it is safe to assume that double quotes will never appear, but
     for textual data types one should be prepared to cope with either presence
!    or absence of quotes.  (This is a change in behavior from pre-7.2
!    <productname>PostgreSQL</productname> releases.)
    </para>

    <para>
--- 559,565 ----
     embedded in element values will be backslash-escaped.  For numeric
     data types it is safe to assume that double quotes will never appear, but
     for textual data types one should be prepared to cope with either presence
!    or absence of quotes.
    </para>

    <para>
Index: doc/src/sgml/backup.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v
retrieving revision 2.79
diff -c -c -r2.79 backup.sgml
*** doc/src/sgml/backup.sgml    10 Mar 2006 19:10:46 -0000    2.79
--- doc/src/sgml/backup.sgml    20 Mar 2006 18:40:42 -0000
***************
*** 1211,1218 ****
     the number after the first dot changes). This does not apply to
     different minor releases under the same major release (where the
     number after the second dot changes); these always have compatible
!    storage formats. For example, releases 7.0.1, 7.1.2, and 7.2 are
!    not compatible, whereas 7.1.1 and 7.1.2 are. When you update
     between compatible versions, you can simply replace the executables
     and reuse the data directory on disk. Otherwise you need to back
     up your data and restore it on the new server.  This has to be done
--- 1211,1218 ----
     the number after the first dot changes). This does not apply to
     different minor releases under the same major release (where the
     number after the second dot changes); these always have compatible
!    storage formats. For example, releases 7.2.1, 7.3.2, and 7.4 are
!    not compatible, whereas 7.2.1 and 7.2.2 are. When you update
     between compatible versions, you can simply replace the executables
     and reuse the data directory on disk. Otherwise you need to back
     up your data and restore it on the new server.  This has to be done
Index: doc/src/sgml/config.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/config.sgml,v
retrieving revision 1.52
diff -c -c -r1.52 config.sgml
*** doc/src/sgml/config.sgml    10 Mar 2006 19:10:47 -0000    1.52
--- doc/src/sgml/config.sgml    20 Mar 2006 18:40:44 -0000
***************
*** 3789,3801 ****
        <listitem>
         <para>
          This controls the inheritance semantics, in particular whether
!         subtables are included by various commands by default. They were
!         not included in versions prior to 7.1. If you need the old
!         behavior you can set this variable to <literal>off</>, but in
!         the long run you are encouraged to change your applications to
!         use the <literal>ONLY</literal> key word to exclude subtables.
!         See <xref linkend="ddl-inherit"> for more information about
!         inheritance.
         </para>
        </listitem>
       </varlistentry>
--- 3789,3796 ----
        <listitem>
         <para>
          This controls the inheritance semantics, in particular whether
!         subtables are included by various commands by default. This was
!         added for compatibility with releases prior to 7.1.
         </para>
        </listitem>
       </varlistentry>
Index: doc/src/sgml/datatype.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v
retrieving revision 1.166
diff -c -c -r1.166 datatype.sgml
*** doc/src/sgml/datatype.sgml    10 Mar 2006 19:10:47 -0000    1.166
--- doc/src/sgml/datatype.sgml    20 Mar 2006 18:40:46 -0000
***************
*** 894,915 ****
      string.
     </para>

!     <para>
!      If one explicitly casts a value to <type>character
!      varying(<replaceable>n</>)</type> or
!      <type>character(<replaceable>n</>)</type>, then an over-length
!      value will be truncated to <replaceable>n</> characters without
!      raising an error. (This too is required by the
!      <acronym>SQL</acronym> standard.)
!     </para>
!
!    <note>
!     <para>
!      Prior to <productname>PostgreSQL</> 7.2, strings that were too long were
!      always truncated without raising an error, in either explicit or
!      implicit casting contexts.
!     </para>
!    </note>

     <para>
      The notations <type>varchar(<replaceable>n</>)</type> and
--- 894,907 ----
      string.
     </para>

!    <para>
!     If one explicitly casts a value to <type>character
!     varying(<replaceable>n</>)</type> or
!     <type>character(<replaceable>n</>)</type>, then an over-length
!     value will be truncated to <replaceable>n</> characters without
!     raising an error. (This too is required by the
!     <acronym>SQL</acronym> standard.)
!    </para>

     <para>
      The notations <type>varchar(<replaceable>n</>)</type> and
***************
*** 2899,2913 ****
      </para>
     </note>

-    <note>
-     <para>
-      Prior to <productname>PostgreSQL</> 7.2, <type>bit</type> data
-      was always silently truncated or zero-padded on the right, with
-      or without an explicit cast. This was changed to comply with the
-      <acronym>SQL</acronym> standard.
-     </para>
-    </note>
-
     <para>
      Refer to <xref
      linkend="sql-syntax-bit-strings"> for information about the syntax
--- 2891,2896 ----
Index: doc/src/sgml/datetime.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/datetime.sgml,v
retrieving revision 2.48
diff -c -c -r2.48 datetime.sgml
*** doc/src/sgml/datetime.sgml    10 Mar 2006 19:10:47 -0000    2.48
--- doc/src/sgml/datetime.sgml    20 Mar 2006 18:40:47 -0000
***************
*** 171,180 ****
        <tip>
         <para>
          Gregorian years AD 1-99 may be entered by using 4 digits with leading
!         zeros (e.g., <literal>0099</> is AD 99). Previous versions of
!         <productname>PostgreSQL</productname> accepted years with three
!         digits and with single digits, but as of version 7.0 the rules have
!         been tightened up to reduce the possibility of ambiguity.
         </para>
        </tip>
       </para>
--- 171,177 ----
        <tip>
         <para>
          Gregorian years AD 1-99 may be entered by using 4 digits with leading
!         zeros (e.g., <literal>0099</> is AD 99).
         </para>
        </tip>
       </para>
Index: doc/src/sgml/ddl.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ddl.sgml,v
retrieving revision 1.55
diff -c -c -r1.55 ddl.sgml
*** doc/src/sgml/ddl.sgml    18 Feb 2006 23:14:45 -0000    1.55
--- doc/src/sgml/ddl.sgml    20 Mar 2006 18:40:52 -0000
***************
*** 2145,2165 ****
    <note>
     <title>Deprecated</title>
     <para>
!      In previous versions of <productname>PostgreSQL</productname>, the
       default behavior was not to include child tables in queries. This was
!      found to be error prone and is also in violation of the SQL
!      standard. Under the old syntax, to include the child tables you append
!      <literal>*</literal> to the table name. For example:
! <programlisting>
! SELECT * from cities*;
! </programlisting>
!      You can still explicitly specify scanning child tables by
!      appending <literal>*</literal>, as well as explicitly specify not
!      scanning child tables by writing <literal>ONLY</literal>.  But
!      beginning in version 7.1, the default behavior for an undecorated
!      table name is to scan its child tables too, whereas before the
!      default was not to do so.  To get the old default behavior,
!      disable the <xref linkend="guc-sql-inheritance"> configuration
       option.
     </para>
    </note>
--- 2145,2155 ----
    <note>
     <title>Deprecated</title>
     <para>
!      In releases of <productname>PostgreSQL</productname> prior to 7.1, the
       default behavior was not to include child tables in queries. This was
!      found to be error prone and also in violation of the SQL
!      standard.  You can get the pre-7.1 behavior by turning off the
!      <xref linkend="guc-sql-inheritance"> configuration
       option.
     </para>
    </note>
Index: doc/src/sgml/func.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/func.sgml,v
retrieving revision 1.313
diff -c -c -r1.313 func.sgml
*** doc/src/sgml/func.sgml    10 Mar 2006 20:15:25 -0000    1.313
--- doc/src/sgml/func.sgml    20 Mar 2006 18:41:01 -0000
***************
*** 6118,6131 ****
       the result is given to the full available precision.
      </para>

-     <note>
-      <para>
-       Prior to <productname>PostgreSQL</productname> 7.2, the precision
-       parameters were unimplemented, and the result was always given
-       in integer seconds.
-      </para>
-     </note>
-
     <para>
      Some examples:
  <screen>
--- 6118,6123 ----
Index: doc/src/sgml/libpq.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v
retrieving revision 1.206
diff -c -c -r1.206 libpq.sgml
*** doc/src/sgml/libpq.sgml    10 Mar 2006 19:10:48 -0000    1.206
--- doc/src/sgml/libpq.sgml    20 Mar 2006 18:41:05 -0000
***************
*** 689,699 ****
  functions described below to get
  at the contents of <structname>PGconn</structname>.  Avoid directly referencing the fields of the
  <structname>PGconn</> structure because they are subject to change in the future.
- (Beginning in <productname>PostgreSQL</productname> release 6.4, the
- definition of the <type>struct</type> behind <structname>PGconn</> is not even provided in
<filename>libpq-fe.h</filename>.
- If you have old code that accesses <structname>PGconn</structname> fields directly, you can keep using it
- by including <filename>libpq-int.h</filename> too, but you are encouraged to fix the code
- soon.)
  </para>
  </tip>

--- 689,694 ----
***************
*** 2972,2978 ****

  typedef struct pgNotify {
      char *relname;              /* notification condition name */
!     int  be_pid;                /* process ID of server process */
      char *extra;                /* notification parameter */
  } PGnotify;
  </synopsis>
--- 2967,2973 ----

  typedef struct pgNotify {
      char *relname;              /* notification condition name */
!     int  be_pid;                /* process ID of notifying server process */
      char *extra;                /* notification parameter */
  } PGnotify;
  </synopsis>
***************
*** 2986,2999 ****
  always point to an empty string.)
  </para>

- <note>
- <para>
-  In <productname>PostgreSQL</productname> 6.4 and later,
-  the <structfield>be_pid</structfield> is that of the notifying server process,
-  whereas in earlier versions it was always the <acronym>PID</acronym> of your own server process.
- </para>
- </note>
-
  <para>
  <xref linkend="libpq-example-2"> gives a sample program that illustrates the use
  of asynchronous notification.
--- 2981,2986 ----
***************
*** 4288,4303 ****
     </itemizedlist>
    </para>

-   <para>
-    <indexterm><primary>libpq-int.h</></>
-    If your codes references the header file
-    <filename>libpq-int.h</filename> and you refuse to fix your code to
-    not use it, starting in <productname>PostgreSQL</> 7.2, this file will be found in
-    <filename><replaceable>includedir</replaceable>/postgresql/internal/libpq-int.h</filename>,
-    so you need to add the appropriate <option>-I</option> option to
-    your compiler command line.
-   </para>
-
   </sect1>


--- 4275,4280 ----
Index: doc/src/sgml/lobj.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v
retrieving revision 1.39
diff -c -c -r1.39 lobj.sgml
*** doc/src/sgml/lobj.sgml    10 Mar 2006 19:10:48 -0000    1.39
--- doc/src/sgml/lobj.sgml    20 Mar 2006 18:41:05 -0000
***************
*** 25,67 ****
      values.  This is not described here.
     </para>

!   <sect1 id="lo-history">
!    <title>History</title>

!    <para>
!     <productname>POSTGRES 4.2</productname>, the indirect predecessor
!     of <productname>PostgreSQL</productname>, supported three standard
!     implementations of large objects: as files external to the
!     <productname>POSTGRES</productname> server, as external files
!     managed by the <productname>POSTGRES</productname> server, and as
!     data stored within the <productname>POSTGRES</productname>
!     database. This caused considerable confusion among users. As a
!     result, only support for large objects as data stored within the
!     database is retained in <productname>PostgreSQL</productname>.
!     Even though this is slower to access, it provides stricter data
!     integrity.  For historical reasons, this storage scheme is
!     referred to as <firstterm>Inversion large
!     objects</firstterm>. (You will see the term Inversion used
!     occasionally to mean the same thing as large object.)  Since
!     <productname>PostgreSQL 7.1</productname>, all large objects are
!     placed in one system table called
!     <classname>pg_largeobject</classname>.
!    </para>

     <para>
!     <indexterm>
!      <primary>TOAST</primary>
!      <secondary>versus large objects</secondary>
!     </indexterm>
!     <productname>PostgreSQL</productname> 7.1 introduced a mechanism
!     (nicknamed <quote><acronym>TOAST</acronym></quote>) that allows
!     data values to be much larger than single pages.  This
!     makes the large object facility partially obsolete.  One
      remaining advantage of the large object facility is that it allows values
      up to 2 GB in size, whereas <acronym>TOAST</acronym>ed fields can be at
!     most 1 GB.  Also, large objects can be manipulated piece-by-piece much more
!     easily than ordinary data fields, so the practical limits are considerably
!     different.
     </para>

    </sect1>
--- 25,50 ----
      values.  This is not described here.
     </para>

!   <sect1 id="lo-intro">
!    <title>Introduction</title>

!    <indexterm>
!     <primary>TOAST</primary>
!     <secondary>versus large objects</secondary>
!    </indexterm>

     <para>
!     All large objects are placed in a single system table called
!     <classname>pg_largeobject</classname>.
!     <productname>PostgreSQL</productname> also supports a storage system called
!     <quote><acronym>TOAST</acronym></quote> that automatically stores values
!     larger than a single database page into a secondary storage area per table.
!     This makes the large object facility partially obsolete.  One
      remaining advantage of the large object facility is that it allows values
      up to 2 GB in size, whereas <acronym>TOAST</acronym>ed fields can be at
!     most 1 GB.  Also, large objects can be randomly modified using a read/write
!     API that is more efficient than performing such operations using
!     <acronym>TOAST</acronym>.
     </para>

    </sect1>
***************
*** 70,77 ****
     <title>Implementation Features</title>

     <para>
!     The large object implementation breaks  large
!     objects  up  into  <quote>chunks</quote>  and  stores  the chunks in
      rows in the database.  A B-tree index guarantees fast
      searches for the correct chunk number when doing random
      access reads and writes.
--- 53,60 ----
     <title>Implementation Features</title>

     <para>
!     The large object implementation breaks large
!     objects up into <quote>chunks</quote> and stores the chunks in
      rows in the database.  A B-tree index guarantees fast
      searches for the correct chunk number when doing random
      access reads and writes.
***************
*** 86,95 ****
      <productname>PostgreSQL</productname> client interface libraries
      provide for accessing large objects.  All large object
      manipulation using these functions <emphasis>must</emphasis> take
!     place within an SQL transaction block.  (This requirement is
!     strictly enforced as of <productname>PostgreSQL 6.5</>, though it
!     has been an implicit requirement in previous versions, resulting
!     in misbehavior if ignored.)
      The  <productname>PostgreSQL</productname>  large  object interface is modeled after
      the <acronym>Unix</acronym>  file-system  interface,  with  analogues  of
      <function>open</function>,  <function>read</function>,
--- 69,75 ----
      <productname>PostgreSQL</productname> client interface libraries
      provide for accessing large objects.  All large object
      manipulation using these functions <emphasis>must</emphasis> take
!     place within an SQL transaction block.
      The  <productname>PostgreSQL</productname>  large  object interface is modeled after
      the <acronym>Unix</acronym>  file-system  interface,  with  analogues  of
      <function>open</function>,  <function>read</function>,
Index: doc/src/sgml/maintenance.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v
retrieving revision 1.54
diff -c -c -r1.54 maintenance.sgml
*** doc/src/sgml/maintenance.sgml    10 Mar 2006 19:10:48 -0000    1.54
--- doc/src/sgml/maintenance.sgml    20 Mar 2006 18:41:05 -0000
***************
*** 82,96 ****
    </para>

    <para>
!    Beginning in <productname>PostgreSQL</productname> 7.2, the standard form
!    of <command>VACUUM</> can run in parallel with normal database operations
!    (selects, inserts, updates, deletes, but not changes to table definitions).
!    Routine vacuuming is therefore not nearly as intrusive as it was in prior
!    releases, and it is not as critical to try to schedule it at low-usage
!    times of day.
!   </para>
!
!   <para>
     Beginning in <productname>PostgreSQL</productname> 8.0, there are
     configuration parameters that can be adjusted to further reduce the
     performance impact of background vacuuming.  See
--- 82,90 ----
    </para>

    <para>
!    The standard form of <command>VACUUM</> can run in parallel with
!    normal database operations (SELECTs, INSERTs, UPDATEs, DELETEs, but not
!    changes to table definitions).
     Beginning in <productname>PostgreSQL</productname> 8.0, there are
     configuration parameters that can be adjusted to further reduce the
     performance impact of background vacuuming.  See
***************
*** 245,256 ****
      It is possible to run <command>ANALYZE</> on specific tables and even
      just specific columns of a table, so the flexibility exists to update some
      statistics more frequently than others if your application requires it.
!     In practice, however, the usefulness of this feature is doubtful.
!     Beginning in <productname>PostgreSQL</productname> 7.2,
!     <command>ANALYZE</> is a fairly fast operation even on large tables,
!     because it uses a statistical random sampling of the rows of a table
!     rather than reading every single row.  So it's probably much simpler
!     to just run it over the whole database every so often.
     </para>

     <tip>
--- 239,247 ----
      It is possible to run <command>ANALYZE</> on specific tables and even
      just specific columns of a table, so the flexibility exists to update some
      statistics more frequently than others if your application requires it.
!     In practice, however, the usefulness of this feature is doubtful because
!     <command>ANALYZE</> is such a fast operation it is often best to just run
!     it on the entire database.
     </para>

     <tip>
***************
*** 295,312 ****
      transactions that were in the past appear to be in the future — which
      means their outputs become invisible.  In short, catastrophic data loss.
      (Actually the data is still there, but that's cold comfort if you can't
!     get at it.)
!    </para>
!
!    <para>
!     Prior to <productname>PostgreSQL</productname> 7.2, the only defense
!     against XID wraparound was to re-<command>initdb</> at least every 4
!     billion transactions. This of course was not very satisfactory for
!     high-traffic sites, so a better solution has been devised. The new
!     approach allows a server to remain up indefinitely, without
!     <command>initdb</> or any sort of restart. The price is this
!     maintenance requirement: <emphasis>every table in the database must
!     be vacuumed at least once every billion transactions</emphasis>.
     </para>

     <para>
--- 286,293 ----
      transactions that were in the past appear to be in the future — which
      means their outputs become invisible.  In short, catastrophic data loss.
      (Actually the data is still there, but that's cold comfort if you can't
!     get at it.)  To avoid this, it is <emphasis>necessary to vacuum every table
!     in every database at least once every billion transactions</emphasis>.
     </para>

     <para>
Index: doc/src/sgml/mvcc.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v
retrieving revision 2.55
diff -c -c -r2.55 mvcc.sgml
*** doc/src/sgml/mvcc.sgml    10 Mar 2006 19:10:48 -0000    2.55
--- doc/src/sgml/mvcc.sgml    20 Mar 2006 18:41:06 -0000
***************
*** 899,908 ****
      TABLE</command> locks the whole table.)  This should be taken into
      account when porting applications to
      <productname>PostgreSQL</productname> from other environments.
-     (Before version 6.5 <productname>PostgreSQL</productname> used
-     read locks, and so this above consideration is also relevant when
-     upgrading from <productname>PostgreSQL</productname> versions
-     prior to 6.5.)
     </para>

     <para>
--- 899,904 ----
Index: doc/src/sgml/rules.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/rules.sgml,v
retrieving revision 1.44
diff -c -c -r1.44 rules.sgml
*** doc/src/sgml/rules.sgml    22 Oct 2005 14:44:35 -0000    1.44
--- doc/src/sgml/rules.sgml    20 Mar 2006 18:41:06 -0000
***************
*** 2043,2052 ****
  <para>
      Another situation is cases on <command>UPDATE</command> where it depends on the
      change of an attribute if an action should be performed or
!     not. In <productname>PostgreSQL</productname> version 6.4, the
!     attribute specification for rule events is disabled (it will have
!     its comeback latest in 6.5, maybe earlier
!     - stay tuned). So for now the only way to
      create a rule as in the shoelace_log example is to do it with
      a rule qualification. That results in an extra query that is
      performed always, even if the attribute of interest cannot
--- 2043,2049 ----
  <para>
      Another situation is cases on <command>UPDATE</command> where it depends on the
      change of an attribute if an action should be performed or
!     not. The only way to
      create a rule as in the shoelace_log example is to do it with
      a rule qualification. That results in an extra query that is
      performed always, even if the attribute of interest cannot
Index: doc/src/sgml/storage.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/storage.sgml,v
retrieving revision 1.9
diff -c -c -r1.9 storage.sgml
*** doc/src/sgml/storage.sgml    10 Mar 2006 19:10:49 -0000    1.9
--- doc/src/sgml/storage.sgml    20 Mar 2006 18:41:07 -0000
***************
*** 188,201 ****

  <para>
  Since <productname>PostgreSQL</productname> uses a fixed page size (commonly
! 8Kb), and does not allow tuples to span multiple pages, it's not possible to
! store very large field values directly.  Before <productname>PostgreSQL</> 7.1
! there was a hard limit of just under one page on the total amount of data that
! could be put into a table row.  In release 7.1 and later, this limit is
! overcome by allowing large field values to be compressed and/or broken up into
! multiple physical rows.  This happens transparently to the user, with only
! small impact on most of the backend code.  The technique is affectionately
! known as <acronym>TOAST</> (or <quote>the best thing since sliced bread</>).
  </para>

  <para>
--- 188,199 ----

  <para>
  Since <productname>PostgreSQL</productname> uses a fixed page size (commonly
! 8Kb), and does not allow tuples to span multiple pages, so it's not possible to
! store very large field values directly.  To overcome this limitation, large
! field values are compressed and/or broken up into multiple physical rows.
! This happens transparently to the user, with only small impact on most of the
! backend code.  The technique is affectionately known as <acronym>TOAST</>
! (or <quote>the best thing since sliced bread</>).
  </para>

  <para>
Index: doc/src/sgml/xfunc.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v
retrieving revision 1.111
diff -c -c -r1.111 xfunc.sgml
*** doc/src/sgml/xfunc.sgml    10 Mar 2006 19:10:49 -0000    1.111
--- doc/src/sgml/xfunc.sgml    20 Mar 2006 18:41:08 -0000
***************
*** 1192,1206 ****
      command <literal>pg_config --pkglibdir</literal>.
     </para>

-    <para>
-     Before <productname>PostgreSQL</productname> release 7.2, only
-     exact absolute paths to object files could be specified in
-     <command>CREATE FUNCTION</>.  This approach is now deprecated
-     since it makes the function definition unnecessarily unportable.
-     It's best to specify just the shared library name with no path nor
-     extension, and let the search mechanism provide that information
-     instead.
-    </para>
    </sect2>

     <sect2 id="xfunc-c-basetype">
--- 1192,1197 ----
***************
*** 1915,1929 ****
          --includedir-server</literal><indexterm><primary>pg_config</><secondary>with user-defined C functions</></>
          to find out where the <productname>PostgreSQL</> server header
          files are installed on your system (or the system that your
!         users will be running on).  This option is new with
!         <productname>PostgreSQL</> 7.2.  For
!         <productname>PostgreSQL</> 7.1 you should use the option
!         <option>--includedir</option>.  (<command>pg_config</command>
!         will exit with a non-zero status if it encounters an unknown
!         option.)  For releases prior to 7.1 you will have to guess,
!         but since that was before the current calling conventions were
!         introduced, it is unlikely that you want to support those
!         releases.
         </para>
        </listitem>

--- 1906,1912 ----
          --includedir-server</literal><indexterm><primary>pg_config</><secondary>with user-defined C functions</></>
          to find out where the <productname>PostgreSQL</> server header
          files are installed on your system (or the system that your
!         users will be running on).
         </para>
        </listitem>

[ Sorry for the two copies, Bruce: I forgot to CC the list previously ]

On Mon, 2006-03-20 at 13:57 -0500, Bruce Momjian wrote:
> The attached patch removes or minimizes some documentation mentions of
> backward compatibility for release 7.2 and earlier.

I don't think it's a net win to get rid of this text, as it describes
useful alternatives to the GUC variable:

*** doc/src/sgml/config.sgml    10 Mar 2006 19:10:47 -0000      1.52
--- doc/src/sgml/config.sgml    20 Mar 2006 18:40:44 -0000
***************
*** 3789,3801 ****
        <listitem>
         <para>
          This controls the inheritance semantics, in particular whether
!         subtables are included by various commands by default. They
were
!         not included in versions prior to 7.1. If you need the old
!         behavior you can set this variable to <literal>off</>, but in
!         the long run you are encouraged to change your applications to
!         use the <literal>ONLY</literal> key word to exclude subtables.
!         See <xref linkend="ddl-inherit"> for more information about
!         inheritance.
         </para>
        </listitem>
       </varlistentry>
--- 3789,3796 ----
        <listitem>
         <para>
          This controls the inheritance semantics, in particular whether
!         subtables are included by various commands by default. This
was
!         added for compatibility with releases prior to 7.1.
         </para>
        </listitem>
       </varlistentry>

*** doc/src/sgml/libpq.sgml     10 Mar 2006 19:10:48 -0000      1.206
--- doc/src/sgml/libpq.sgml     20 Mar 2006 18:41:05 -0000
***************
*** 689,699 ****
  functions described below to get
  at the contents of <structname>PGconn</structname>.  Avoid directly
referencing the fields of the
  <structname>PGconn</> structure because they are subject to change in
the future.
- (Beginning in <productname>PostgreSQL</productname> release 6.4, the
- definition of the <type>struct</type> behind <structname>PGconn</> is
not even provided in <filename>libpq-fe.h</filename>.
- If you have old code that accesses <structname>PGconn</structname>
fields directly, you can keep using it
- by including <filename>libpq-int.h</filename> too, but you are
encouraged to fix the code
- soon.)
  </para>
  </tip>

Removing the information about libpq-int.h but keeping the suggestion to
"avoid directly referencing fields of the PGconn structure" doesn't seem
consistent: the user *can't* directly reference fields without including
libpq-int.h. So I think this hunk should be kept.

The second hunk modified in maintenance.sgml removes some useful
information (ANALYZE collects rows by random sampling).

From storage.sgml:

!  Since <productname>PostgreSQL</productname> uses a fixed page size
(commonly
! 8Kb), and does not allow tuples to span multiple pages, so it's not
possible to
! store very large field values directly.

That is poorly phrased ("Since ..., so it's not").

-Neil

Neil Conway <neilc@samurai.com> writes:
> I don't think it's a net win to get rid of this text, as it describes
> useful alternatives to the GUC variable:

I was about to object to some other parts of the patch on the same
grounds, in particular the changes to ddl.sgml and maintenance.sgml,
and the first change in xfunc.sgml.  In most of these cases,
currently-useful information is intertwined with the reference to the
old behavior.  If you can't be bothered to rewrite to preserve all of
the information, then don't remove the text.

            regards, tom lane

Tom Lane wrote:
> Neil Conway <neilc@samurai.com> writes:
> > I don't think it's a net win to get rid of this text, as it describes
> > useful alternatives to the GUC variable:
>
> I was about to object to some other parts of the patch on the same
> grounds, in particular the changes to ddl.sgml and maintenance.sgml,
> and the first change in xfunc.sgml.  In most of these cases,
> currently-useful information is intertwined with the reference to the
> old behavior.  If you can't be bothered to rewrite to preserve all of
> the information, then don't remove the text.

I am working on Neils suggestion.  I don't agree we need to preserve all
information about very old releases.

--
  Bruce Momjian   http://candle.pha.pa.us
  SRA OSS, Inc.   http://www.sraoss.com

  + If your life is a hard drive, Christ can be your backup. +

Bruce Momjian <pgman@candle.pha.pa.us> writes:
> Tom Lane wrote:
>> currently-useful information is intertwined with the reference to the
>> old behavior.  If you can't be bothered to rewrite to preserve all of
>> the information, then don't remove the text.

> I am working on Neils suggestion.  I don't agree we need to preserve all
> information about very old releases.

That's not what I complained about.

            regards, tom lane

I have made the modifications you suggested.  Any others?

---------------------------------------------------------------------------

Neil Conway wrote:
> [ Sorry for the two copies, Bruce: I forgot to CC the list previously ]
>
> On Mon, 2006-03-20 at 13:57 -0500, Bruce Momjian wrote:
> > The attached patch removes or minimizes some documentation mentions of
> > backward compatibility for release 7.2 and earlier.
>
> I don't think it's a net win to get rid of this text, as it describes
> useful alternatives to the GUC variable:
>
> *** doc/src/sgml/config.sgml    10 Mar 2006 19:10:47 -0000      1.52
> --- doc/src/sgml/config.sgml    20 Mar 2006 18:40:44 -0000
> ***************
> *** 3789,3801 ****
>         <listitem>
>          <para>
>           This controls the inheritance semantics, in particular whether
> !         subtables are included by various commands by default. They
> were
> !         not included in versions prior to 7.1. If you need the old
> !         behavior you can set this variable to <literal>off</>, but in
> !         the long run you are encouraged to change your applications to
> !         use the <literal>ONLY</literal> key word to exclude subtables.
> !         See <xref linkend="ddl-inherit"> for more information about
> !         inheritance.
>          </para>
>         </listitem>
>        </varlistentry>
> --- 3789,3796 ----
>         <listitem>
>          <para>
>           This controls the inheritance semantics, in particular whether
> !         subtables are included by various commands by default. This
> was
> !         added for compatibility with releases prior to 7.1.
>          </para>
>         </listitem>
>        </varlistentry>
>
> *** doc/src/sgml/libpq.sgml     10 Mar 2006 19:10:48 -0000      1.206
> --- doc/src/sgml/libpq.sgml     20 Mar 2006 18:41:05 -0000
> ***************
> *** 689,699 ****
>   functions described below to get
>   at the contents of <structname>PGconn</structname>.  Avoid directly
> referencing the fields of the
>   <structname>PGconn</> structure because they are subject to change in
> the future.
> - (Beginning in <productname>PostgreSQL</productname> release 6.4, the
> - definition of the <type>struct</type> behind <structname>PGconn</> is
> not even provided in <filename>libpq-fe.h</filename>.
> - If you have old code that accesses <structname>PGconn</structname>
> fields directly, you can keep using it
> - by including <filename>libpq-int.h</filename> too, but you are
> encouraged to fix the code
> - soon.)
>   </para>
>   </tip>
>
> Removing the information about libpq-int.h but keeping the suggestion to
> "avoid directly referencing fields of the PGconn structure" doesn't seem
> consistent: the user *can't* directly reference fields without including
> libpq-int.h. So I think this hunk should be kept.
>
> The second hunk modified in maintenance.sgml removes some useful
> information (ANALYZE collects rows by random sampling).
>
> >From storage.sgml:
>
> !  Since <productname>PostgreSQL</productname> uses a fixed page size
> (commonly
> ! 8Kb), and does not allow tuples to span multiple pages, so it's not
> possible to
> ! store very large field values directly.
>
> That is poorly phrased ("Since ..., so it's not").
>
> -Neil
>
>
>
> ---------------------------(end of broadcast)---------------------------
> TIP 1: if posting/reading through Usenet, please send an appropriate
>        subscribe-nomail command to majordomo@postgresql.org so that your
>        message can get through to the mailing list cleanly
>

--
  Bruce Momjian   http://candle.pha.pa.us
  SRA OSS, Inc.   http://www.sraoss.com

  + If your life is a hard drive, Christ can be your backup. +
Index: doc/src/sgml/array.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/array.sgml,v
retrieving revision 1.48
diff -c -c -r1.48 array.sgml
*** doc/src/sgml/array.sgml    19 Nov 2005 01:50:08 -0000    1.48
--- doc/src/sgml/array.sgml    20 Mar 2006 23:42:29 -0000
***************
*** 559,566 ****
     embedded in element values will be backslash-escaped.  For numeric
     data types it is safe to assume that double quotes will never appear, but
     for textual data types one should be prepared to cope with either presence
!    or absence of quotes.  (This is a change in behavior from pre-7.2
!    <productname>PostgreSQL</productname> releases.)
    </para>

    <para>
--- 559,565 ----
     embedded in element values will be backslash-escaped.  For numeric
     data types it is safe to assume that double quotes will never appear, but
     for textual data types one should be prepared to cope with either presence
!    or absence of quotes.
    </para>

    <para>
Index: doc/src/sgml/backup.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v
retrieving revision 2.79
diff -c -c -r2.79 backup.sgml
*** doc/src/sgml/backup.sgml    10 Mar 2006 19:10:46 -0000    2.79
--- doc/src/sgml/backup.sgml    20 Mar 2006 23:42:31 -0000
***************
*** 1211,1218 ****
     the number after the first dot changes). This does not apply to
     different minor releases under the same major release (where the
     number after the second dot changes); these always have compatible
!    storage formats. For example, releases 7.0.1, 7.1.2, and 7.2 are
!    not compatible, whereas 7.1.1 and 7.1.2 are. When you update
     between compatible versions, you can simply replace the executables
     and reuse the data directory on disk. Otherwise you need to back
     up your data and restore it on the new server.  This has to be done
--- 1211,1218 ----
     the number after the first dot changes). This does not apply to
     different minor releases under the same major release (where the
     number after the second dot changes); these always have compatible
!    storage formats. For example, releases 7.2.1, 7.3.2, and 7.4 are
!    not compatible, whereas 7.2.1 and 7.2.2 are. When you update
     between compatible versions, you can simply replace the executables
     and reuse the data directory on disk. Otherwise you need to back
     up your data and restore it on the new server.  This has to be done
Index: doc/src/sgml/config.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/config.sgml,v
retrieving revision 1.52
diff -c -c -r1.52 config.sgml
*** doc/src/sgml/config.sgml    10 Mar 2006 19:10:47 -0000    1.52
--- doc/src/sgml/config.sgml    20 Mar 2006 23:42:34 -0000
***************
*** 3788,3801 ****
        <indexterm><primary>inheritance</></>
        <listitem>
         <para>
!         This controls the inheritance semantics, in particular whether
!         subtables are included by various commands by default. They were
!         not included in versions prior to 7.1. If you need the old
!         behavior you can set this variable to <literal>off</>, but in
!         the long run you are encouraged to change your applications to
!         use the <literal>ONLY</literal> key word to exclude subtables.
!         See <xref linkend="ddl-inherit"> for more information about
!         inheritance.
         </para>
        </listitem>
       </varlistentry>
--- 3788,3798 ----
        <indexterm><primary>inheritance</></>
        <listitem>
         <para>
!         This controls the inheritance semantics.  If turned <literal>off</>,
!         subtables are not included by various commands by default; basically
!         an implied <literal>ONLY</literal> key word.  This was added for
!         compatibility with releases prior to 7.1.  See
!         <xref linkend="ddl-inherit"> for more information.
         </para>
        </listitem>
       </varlistentry>
Index: doc/src/sgml/datatype.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v
retrieving revision 1.166
diff -c -c -r1.166 datatype.sgml
*** doc/src/sgml/datatype.sgml    10 Mar 2006 19:10:47 -0000    1.166
--- doc/src/sgml/datatype.sgml    20 Mar 2006 23:42:41 -0000
***************
*** 894,915 ****
      string.
     </para>

!     <para>
!      If one explicitly casts a value to <type>character
!      varying(<replaceable>n</>)</type> or
!      <type>character(<replaceable>n</>)</type>, then an over-length
!      value will be truncated to <replaceable>n</> characters without
!      raising an error. (This too is required by the
!      <acronym>SQL</acronym> standard.)
!     </para>
!
!    <note>
!     <para>
!      Prior to <productname>PostgreSQL</> 7.2, strings that were too long were
!      always truncated without raising an error, in either explicit or
!      implicit casting contexts.
!     </para>
!    </note>

     <para>
      The notations <type>varchar(<replaceable>n</>)</type> and
--- 894,907 ----
      string.
     </para>

!    <para>
!     If one explicitly casts a value to <type>character
!     varying(<replaceable>n</>)</type> or
!     <type>character(<replaceable>n</>)</type>, then an over-length
!     value will be truncated to <replaceable>n</> characters without
!     raising an error. (This too is required by the
!     <acronym>SQL</acronym> standard.)
!    </para>

     <para>
      The notations <type>varchar(<replaceable>n</>)</type> and
***************
*** 2899,2913 ****
      </para>
     </note>

-    <note>
-     <para>
-      Prior to <productname>PostgreSQL</> 7.2, <type>bit</type> data
-      was always silently truncated or zero-padded on the right, with
-      or without an explicit cast. This was changed to comply with the
-      <acronym>SQL</acronym> standard.
-     </para>
-    </note>
-
     <para>
      Refer to <xref
      linkend="sql-syntax-bit-strings"> for information about the syntax
--- 2891,2896 ----
Index: doc/src/sgml/datetime.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/datetime.sgml,v
retrieving revision 2.48
diff -c -c -r2.48 datetime.sgml
*** doc/src/sgml/datetime.sgml    10 Mar 2006 19:10:47 -0000    2.48
--- doc/src/sgml/datetime.sgml    20 Mar 2006 23:42:42 -0000
***************
*** 171,180 ****
        <tip>
         <para>
          Gregorian years AD 1-99 may be entered by using 4 digits with leading
!         zeros (e.g., <literal>0099</> is AD 99). Previous versions of
!         <productname>PostgreSQL</productname> accepted years with three
!         digits and with single digits, but as of version 7.0 the rules have
!         been tightened up to reduce the possibility of ambiguity.
         </para>
        </tip>
       </para>
--- 171,177 ----
        <tip>
         <para>
          Gregorian years AD 1-99 may be entered by using 4 digits with leading
!         zeros (e.g., <literal>0099</> is AD 99).
         </para>
        </tip>
       </para>
Index: doc/src/sgml/ddl.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ddl.sgml,v
retrieving revision 1.55
diff -c -c -r1.55 ddl.sgml
*** doc/src/sgml/ddl.sgml    18 Feb 2006 23:14:45 -0000    1.55
--- doc/src/sgml/ddl.sgml    20 Mar 2006 23:42:43 -0000
***************
*** 2145,2165 ****
    <note>
     <title>Deprecated</title>
     <para>
!      In previous versions of <productname>PostgreSQL</productname>, the
       default behavior was not to include child tables in queries. This was
!      found to be error prone and is also in violation of the SQL
!      standard. Under the old syntax, to include the child tables you append
!      <literal>*</literal> to the table name. For example:
! <programlisting>
! SELECT * from cities*;
! </programlisting>
!      You can still explicitly specify scanning child tables by
!      appending <literal>*</literal>, as well as explicitly specify not
!      scanning child tables by writing <literal>ONLY</literal>.  But
!      beginning in version 7.1, the default behavior for an undecorated
!      table name is to scan its child tables too, whereas before the
!      default was not to do so.  To get the old default behavior,
!      disable the <xref linkend="guc-sql-inheritance"> configuration
       option.
     </para>
    </note>
--- 2145,2155 ----
    <note>
     <title>Deprecated</title>
     <para>
!      In releases of <productname>PostgreSQL</productname> prior to 7.1, the
       default behavior was not to include child tables in queries. This was
!      found to be error prone and also in violation of the SQL
!      standard.  You can get the pre-7.1 behavior by turning off the
!      <xref linkend="guc-sql-inheritance"> configuration
       option.
     </para>
    </note>
Index: doc/src/sgml/func.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/func.sgml,v
retrieving revision 1.313
diff -c -c -r1.313 func.sgml
*** doc/src/sgml/func.sgml    10 Mar 2006 20:15:25 -0000    1.313
--- doc/src/sgml/func.sgml    20 Mar 2006 23:42:48 -0000
***************
*** 6118,6131 ****
       the result is given to the full available precision.
      </para>

-     <note>
-      <para>
-       Prior to <productname>PostgreSQL</productname> 7.2, the precision
-       parameters were unimplemented, and the result was always given
-       in integer seconds.
-      </para>
-     </note>
-
     <para>
      Some examples:
  <screen>
--- 6118,6123 ----
Index: doc/src/sgml/libpq.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v
retrieving revision 1.206
diff -c -c -r1.206 libpq.sgml
*** doc/src/sgml/libpq.sgml    10 Mar 2006 19:10:48 -0000    1.206
--- doc/src/sgml/libpq.sgml    20 Mar 2006 23:42:50 -0000
***************
*** 686,699 ****
  <indexterm><primary>libpq-int.h</></>
  <application>libpq</application> application programmers should be careful to
  maintain the <structname>PGconn</structname> abstraction.  Use the accessor
! functions described below to get
! at the contents of <structname>PGconn</structname>.  Avoid directly referencing the fields of the
! <structname>PGconn</> structure because they are subject to change in the future.
! (Beginning in <productname>PostgreSQL</productname> release 6.4, the
! definition of the <type>struct</type> behind <structname>PGconn</> is not even provided in
<filename>libpq-fe.h</filename>.
! If you have old code that accesses <structname>PGconn</structname> fields directly, you can keep using it
! by including <filename>libpq-int.h</filename> too, but you are encouraged to fix the code
! soon.)
  </para>
  </tip>

--- 686,695 ----
  <indexterm><primary>libpq-int.h</></>
  <application>libpq</application> application programmers should be careful to
  maintain the <structname>PGconn</structname> abstraction.  Use the accessor
! functions described below to get at the contents of <structname>PGconn</structname>.
! Reference to internal <structname>PGconn</structname> fields using
! <filename>libpq-int.h</> is not recommended because they are subject to change
! in the future.
  </para>
  </tip>

***************
*** 2972,2978 ****

  typedef struct pgNotify {
      char *relname;              /* notification condition name */
!     int  be_pid;                /* process ID of server process */
      char *extra;                /* notification parameter */
  } PGnotify;
  </synopsis>
--- 2968,2974 ----

  typedef struct pgNotify {
      char *relname;              /* notification condition name */
!     int  be_pid;                /* process ID of notifying server process */
      char *extra;                /* notification parameter */
  } PGnotify;
  </synopsis>
***************
*** 2986,2999 ****
  always point to an empty string.)
  </para>

- <note>
- <para>
-  In <productname>PostgreSQL</productname> 6.4 and later,
-  the <structfield>be_pid</structfield> is that of the notifying server process,
-  whereas in earlier versions it was always the <acronym>PID</acronym> of your own server process.
- </para>
- </note>
-
  <para>
  <xref linkend="libpq-example-2"> gives a sample program that illustrates the use
  of asynchronous notification.
--- 2982,2987 ----
***************
*** 4288,4303 ****
     </itemizedlist>
    </para>

-   <para>
-    <indexterm><primary>libpq-int.h</></>
-    If your codes references the header file
-    <filename>libpq-int.h</filename> and you refuse to fix your code to
-    not use it, starting in <productname>PostgreSQL</> 7.2, this file will be found in
-    <filename><replaceable>includedir</replaceable>/postgresql/internal/libpq-int.h</filename>,
-    so you need to add the appropriate <option>-I</option> option to
-    your compiler command line.
-   </para>
-
   </sect1>


--- 4276,4281 ----
Index: doc/src/sgml/lobj.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v
retrieving revision 1.39
diff -c -c -r1.39 lobj.sgml
*** doc/src/sgml/lobj.sgml    10 Mar 2006 19:10:48 -0000    1.39
--- doc/src/sgml/lobj.sgml    20 Mar 2006 23:42:50 -0000
***************
*** 25,67 ****
      values.  This is not described here.
     </para>

!   <sect1 id="lo-history">
!    <title>History</title>

!    <para>
!     <productname>POSTGRES 4.2</productname>, the indirect predecessor
!     of <productname>PostgreSQL</productname>, supported three standard
!     implementations of large objects: as files external to the
!     <productname>POSTGRES</productname> server, as external files
!     managed by the <productname>POSTGRES</productname> server, and as
!     data stored within the <productname>POSTGRES</productname>
!     database. This caused considerable confusion among users. As a
!     result, only support for large objects as data stored within the
!     database is retained in <productname>PostgreSQL</productname>.
!     Even though this is slower to access, it provides stricter data
!     integrity.  For historical reasons, this storage scheme is
!     referred to as <firstterm>Inversion large
!     objects</firstterm>. (You will see the term Inversion used
!     occasionally to mean the same thing as large object.)  Since
!     <productname>PostgreSQL 7.1</productname>, all large objects are
!     placed in one system table called
!     <classname>pg_largeobject</classname>.
!    </para>

     <para>
!     <indexterm>
!      <primary>TOAST</primary>
!      <secondary>versus large objects</secondary>
!     </indexterm>
!     <productname>PostgreSQL</productname> 7.1 introduced a mechanism
!     (nicknamed <quote><acronym>TOAST</acronym></quote>) that allows
!     data values to be much larger than single pages.  This
!     makes the large object facility partially obsolete.  One
      remaining advantage of the large object facility is that it allows values
      up to 2 GB in size, whereas <acronym>TOAST</acronym>ed fields can be at
!     most 1 GB.  Also, large objects can be manipulated piece-by-piece much more
!     easily than ordinary data fields, so the practical limits are considerably
!     different.
     </para>

    </sect1>
--- 25,50 ----
      values.  This is not described here.
     </para>

!   <sect1 id="lo-intro">
!    <title>Introduction</title>

!    <indexterm>
!     <primary>TOAST</primary>
!     <secondary>versus large objects</secondary>
!    </indexterm>

     <para>
!     All large objects are placed in a single system table called
!     <classname>pg_largeobject</classname>.
!     <productname>PostgreSQL</productname> also supports a storage system called
!     <quote><acronym>TOAST</acronym></quote> that automatically stores values
!     larger than a single database page into a secondary storage area per table.
!     This makes the large object facility partially obsolete.  One
      remaining advantage of the large object facility is that it allows values
      up to 2 GB in size, whereas <acronym>TOAST</acronym>ed fields can be at
!     most 1 GB.  Also, large objects can be randomly modified using a read/write
!     API that is more efficient than performing such operations using
!     <acronym>TOAST</acronym>.
     </para>

    </sect1>
***************
*** 70,77 ****
     <title>Implementation Features</title>

     <para>
!     The large object implementation breaks  large
!     objects  up  into  <quote>chunks</quote>  and  stores  the chunks in
      rows in the database.  A B-tree index guarantees fast
      searches for the correct chunk number when doing random
      access reads and writes.
--- 53,60 ----
     <title>Implementation Features</title>

     <para>
!     The large object implementation breaks large
!     objects up into <quote>chunks</quote> and stores the chunks in
      rows in the database.  A B-tree index guarantees fast
      searches for the correct chunk number when doing random
      access reads and writes.
***************
*** 86,95 ****
      <productname>PostgreSQL</productname> client interface libraries
      provide for accessing large objects.  All large object
      manipulation using these functions <emphasis>must</emphasis> take
!     place within an SQL transaction block.  (This requirement is
!     strictly enforced as of <productname>PostgreSQL 6.5</>, though it
!     has been an implicit requirement in previous versions, resulting
!     in misbehavior if ignored.)
      The  <productname>PostgreSQL</productname>  large  object interface is modeled after
      the <acronym>Unix</acronym>  file-system  interface,  with  analogues  of
      <function>open</function>,  <function>read</function>,
--- 69,75 ----
      <productname>PostgreSQL</productname> client interface libraries
      provide for accessing large objects.  All large object
      manipulation using these functions <emphasis>must</emphasis> take
!     place within an SQL transaction block.
      The  <productname>PostgreSQL</productname>  large  object interface is modeled after
      the <acronym>Unix</acronym>  file-system  interface,  with  analogues  of
      <function>open</function>,  <function>read</function>,
Index: doc/src/sgml/maintenance.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v
retrieving revision 1.54
diff -c -c -r1.54 maintenance.sgml
*** doc/src/sgml/maintenance.sgml    10 Mar 2006 19:10:48 -0000    1.54
--- doc/src/sgml/maintenance.sgml    20 Mar 2006 23:42:50 -0000
***************
*** 82,96 ****
    </para>

    <para>
!    Beginning in <productname>PostgreSQL</productname> 7.2, the standard form
!    of <command>VACUUM</> can run in parallel with normal database operations
!    (selects, inserts, updates, deletes, but not changes to table definitions).
!    Routine vacuuming is therefore not nearly as intrusive as it was in prior
!    releases, and it is not as critical to try to schedule it at low-usage
!    times of day.
!   </para>
!
!   <para>
     Beginning in <productname>PostgreSQL</productname> 8.0, there are
     configuration parameters that can be adjusted to further reduce the
     performance impact of background vacuuming.  See
--- 82,90 ----
    </para>

    <para>
!    The standard form of <command>VACUUM</> can run in parallel with
!    normal database operations (SELECTs, INSERTs, UPDATEs, DELETEs, but not
!    changes to table definitions).
     Beginning in <productname>PostgreSQL</productname> 8.0, there are
     configuration parameters that can be adjusted to further reduce the
     performance impact of background vacuuming.  See
***************
*** 245,256 ****
      It is possible to run <command>ANALYZE</> on specific tables and even
      just specific columns of a table, so the flexibility exists to update some
      statistics more frequently than others if your application requires it.
!     In practice, however, the usefulness of this feature is doubtful.
!     Beginning in <productname>PostgreSQL</productname> 7.2,
!     <command>ANALYZE</> is a fairly fast operation even on large tables,
!     because it uses a statistical random sampling of the rows of a table
!     rather than reading every single row.  So it's probably much simpler
!     to just run it over the whole database every so often.
     </para>

     <tip>
--- 239,247 ----
      It is possible to run <command>ANALYZE</> on specific tables and even
      just specific columns of a table, so the flexibility exists to update some
      statistics more frequently than others if your application requires it.
!     In practice, however, it is usually best to just analyze the entire database
!     because it is a fast operation.  It uses a statistical random sampling of
!     the rows of a table rather than reading every single row.
     </para>

     <tip>
***************
*** 295,312 ****
      transactions that were in the past appear to be in the future — which
      means their outputs become invisible.  In short, catastrophic data loss.
      (Actually the data is still there, but that's cold comfort if you can't
!     get at it.)
!    </para>
!
!    <para>
!     Prior to <productname>PostgreSQL</productname> 7.2, the only defense
!     against XID wraparound was to re-<command>initdb</> at least every 4
!     billion transactions. This of course was not very satisfactory for
!     high-traffic sites, so a better solution has been devised. The new
!     approach allows a server to remain up indefinitely, without
!     <command>initdb</> or any sort of restart. The price is this
!     maintenance requirement: <emphasis>every table in the database must
!     be vacuumed at least once every billion transactions</emphasis>.
     </para>

     <para>
--- 286,293 ----
      transactions that were in the past appear to be in the future — which
      means their outputs become invisible.  In short, catastrophic data loss.
      (Actually the data is still there, but that's cold comfort if you can't
!     get at it.)  To avoid this, it is <emphasis>necessary to vacuum every table
!     in every database at least once every billion transactions</emphasis>.
     </para>

     <para>
Index: doc/src/sgml/mvcc.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v
retrieving revision 2.55
diff -c -c -r2.55 mvcc.sgml
*** doc/src/sgml/mvcc.sgml    10 Mar 2006 19:10:48 -0000    2.55
--- doc/src/sgml/mvcc.sgml    20 Mar 2006 23:42:51 -0000
***************
*** 899,908 ****
      TABLE</command> locks the whole table.)  This should be taken into
      account when porting applications to
      <productname>PostgreSQL</productname> from other environments.
-     (Before version 6.5 <productname>PostgreSQL</productname> used
-     read locks, and so this above consideration is also relevant when
-     upgrading from <productname>PostgreSQL</productname> versions
-     prior to 6.5.)
     </para>

     <para>
--- 899,904 ----
Index: doc/src/sgml/rules.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/rules.sgml,v
retrieving revision 1.44
diff -c -c -r1.44 rules.sgml
*** doc/src/sgml/rules.sgml    22 Oct 2005 14:44:35 -0000    1.44
--- doc/src/sgml/rules.sgml    20 Mar 2006 23:42:51 -0000
***************
*** 2043,2052 ****
  <para>
      Another situation is cases on <command>UPDATE</command> where it depends on the
      change of an attribute if an action should be performed or
!     not. In <productname>PostgreSQL</productname> version 6.4, the
!     attribute specification for rule events is disabled (it will have
!     its comeback latest in 6.5, maybe earlier
!     - stay tuned). So for now the only way to
      create a rule as in the shoelace_log example is to do it with
      a rule qualification. That results in an extra query that is
      performed always, even if the attribute of interest cannot
--- 2043,2049 ----
  <para>
      Another situation is cases on <command>UPDATE</command> where it depends on the
      change of an attribute if an action should be performed or
!     not. The only way to
      create a rule as in the shoelace_log example is to do it with
      a rule qualification. That results in an extra query that is
      performed always, even if the attribute of interest cannot
Index: doc/src/sgml/storage.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/storage.sgml,v
retrieving revision 1.9
diff -c -c -r1.9 storage.sgml
*** doc/src/sgml/storage.sgml    10 Mar 2006 19:10:49 -0000    1.9
--- doc/src/sgml/storage.sgml    20 Mar 2006 23:42:52 -0000
***************
*** 187,201 ****
  </para>

  <para>
! Since <productname>PostgreSQL</productname> uses a fixed page size (commonly
! 8Kb), and does not allow tuples to span multiple pages, it's not possible to
! store very large field values directly.  Before <productname>PostgreSQL</> 7.1
! there was a hard limit of just under one page on the total amount of data that
! could be put into a table row.  In release 7.1 and later, this limit is
! overcome by allowing large field values to be compressed and/or broken up into
! multiple physical rows.  This happens transparently to the user, with only
! small impact on most of the backend code.  The technique is affectionately
! known as <acronym>TOAST</> (or <quote>the best thing since sliced bread</>).
  </para>

  <para>
--- 187,199 ----
  </para>

  <para>
! <productname>PostgreSQL</productname> uses a fixed page size (commonly
! 8Kb), and does not allow tuples to span multiple pages.  Therefore,  it is
! not possible to store very large field values directly.  To overcome
! this limitation, large  field values are compressed and/or broken up into
! multiple physical rows. This happens transparently to the user, with only
! small impact on most of the backend code.  The technique is affectionately
! known as <acronym>TOAST</>  (or <quote>the best thing since sliced bread</>).
  </para>

  <para>
Index: doc/src/sgml/xfunc.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v
retrieving revision 1.111
diff -c -c -r1.111 xfunc.sgml
*** doc/src/sgml/xfunc.sgml    10 Mar 2006 19:10:49 -0000    1.111
--- doc/src/sgml/xfunc.sgml    20 Mar 2006 23:42:53 -0000
***************
*** 1192,1206 ****
      command <literal>pg_config --pkglibdir</literal>.
     </para>

-    <para>
-     Before <productname>PostgreSQL</productname> release 7.2, only
-     exact absolute paths to object files could be specified in
-     <command>CREATE FUNCTION</>.  This approach is now deprecated
-     since it makes the function definition unnecessarily unportable.
-     It's best to specify just the shared library name with no path nor
-     extension, and let the search mechanism provide that information
-     instead.
-    </para>
    </sect2>

     <sect2 id="xfunc-c-basetype">
--- 1192,1197 ----
***************
*** 1915,1929 ****
          --includedir-server</literal><indexterm><primary>pg_config</><secondary>with user-defined C functions</></>
          to find out where the <productname>PostgreSQL</> server header
          files are installed on your system (or the system that your
!         users will be running on).  This option is new with
!         <productname>PostgreSQL</> 7.2.  For
!         <productname>PostgreSQL</> 7.1 you should use the option
!         <option>--includedir</option>.  (<command>pg_config</command>
!         will exit with a non-zero status if it encounters an unknown
!         option.)  For releases prior to 7.1 you will have to guess,
!         but since that was before the current calling conventions were
!         introduced, it is unlikely that you want to support those
!         releases.
         </para>
        </listitem>

--- 1906,1912 ----
          --includedir-server</literal><indexterm><primary>pg_config</><secondary>with user-defined C functions</></>
          to find out where the <productname>PostgreSQL</> server header
          files are installed on your system (or the system that your
!         users will be running on).
         </para>
        </listitem>

> The attached patch removes or minimizes some documentation mentions of
> backward compatibility for release 7.2 and earlier.  I have not altered
> any mentions of release 7.3 or later.  The release notes were not
> modified, so the changes are still documented, just not in the main
> docs.

Patch applied.

---------------------------------------------------------------------------


Bruce Momjian wrote:
>
> I have made the modifications you suggested.  Any others?
>
> ---------------------------------------------------------------------------
>
> Neil Conway wrote:
> > [ Sorry for the two copies, Bruce: I forgot to CC the list previously ]
> >
> > On Mon, 2006-03-20 at 13:57 -0500, Bruce Momjian wrote:
> > > The attached patch removes or minimizes some documentation mentions of
> > > backward compatibility for release 7.2 and earlier.
> >
> > I don't think it's a net win to get rid of this text, as it describes
> > useful alternatives to the GUC variable:
> >
> > *** doc/src/sgml/config.sgml    10 Mar 2006 19:10:47 -0000      1.52
> > --- doc/src/sgml/config.sgml    20 Mar 2006 18:40:44 -0000
> > ***************
> > *** 3789,3801 ****
> >         <listitem>
> >          <para>
> >           This controls the inheritance semantics, in particular whether
> > !         subtables are included by various commands by default. They
> > were
> > !         not included in versions prior to 7.1. If you need the old
> > !         behavior you can set this variable to <literal>off</>, but in
> > !         the long run you are encouraged to change your applications to
> > !         use the <literal>ONLY</literal> key word to exclude subtables.
> > !         See <xref linkend="ddl-inherit"> for more information about
> > !         inheritance.
> >          </para>
> >         </listitem>
> >        </varlistentry>
> > --- 3789,3796 ----
> >         <listitem>
> >          <para>
> >           This controls the inheritance semantics, in particular whether
> > !         subtables are included by various commands by default. This
> > was
> > !         added for compatibility with releases prior to 7.1.
> >          </para>
> >         </listitem>
> >        </varlistentry>
> >
> > *** doc/src/sgml/libpq.sgml     10 Mar 2006 19:10:48 -0000      1.206
> > --- doc/src/sgml/libpq.sgml     20 Mar 2006 18:41:05 -0000
> > ***************
> > *** 689,699 ****
> >   functions described below to get
> >   at the contents of <structname>PGconn</structname>.  Avoid directly
> > referencing the fields of the
> >   <structname>PGconn</> structure because they are subject to change in
> > the future.
> > - (Beginning in <productname>PostgreSQL</productname> release 6.4, the
> > - definition of the <type>struct</type> behind <structname>PGconn</> is
> > not even provided in <filename>libpq-fe.h</filename>.
> > - If you have old code that accesses <structname>PGconn</structname>
> > fields directly, you can keep using it
> > - by including <filename>libpq-int.h</filename> too, but you are
> > encouraged to fix the code
> > - soon.)
> >   </para>
> >   </tip>
> >
> > Removing the information about libpq-int.h but keeping the suggestion to
> > "avoid directly referencing fields of the PGconn structure" doesn't seem
> > consistent: the user *can't* directly reference fields without including
> > libpq-int.h. So I think this hunk should be kept.
> >
> > The second hunk modified in maintenance.sgml removes some useful
> > information (ANALYZE collects rows by random sampling).
> >
> > >From storage.sgml:
> >
> > !  Since <productname>PostgreSQL</productname> uses a fixed page size
> > (commonly
> > ! 8Kb), and does not allow tuples to span multiple pages, so it's not
> > possible to
> > ! store very large field values directly.
> >
> > That is poorly phrased ("Since ..., so it's not").
> >
> > -Neil
> >
> >
> >
> > ---------------------------(end of broadcast)---------------------------
> > TIP 1: if posting/reading through Usenet, please send an appropriate
> >        subscribe-nomail command to majordomo@postgresql.org so that your
> >        message can get through to the mailing list cleanly
> >
>
> --
>   Bruce Momjian   http://candle.pha.pa.us
>   SRA OSS, Inc.   http://www.sraoss.com
>
>   + If your life is a hard drive, Christ can be your backup. +

> Index: doc/src/sgml/array.sgml
> ===================================================================
> RCS file: /cvsroot/pgsql/doc/src/sgml/array.sgml,v
> retrieving revision 1.48
> diff -c -c -r1.48 array.sgml
> *** doc/src/sgml/array.sgml    19 Nov 2005 01:50:08 -0000    1.48
> --- doc/src/sgml/array.sgml    20 Mar 2006 23:42:29 -0000
> ***************
> *** 559,566 ****
>      embedded in element values will be backslash-escaped.  For numeric
>      data types it is safe to assume that double quotes will never appear, but
>      for textual data types one should be prepared to cope with either presence
> !    or absence of quotes.  (This is a change in behavior from pre-7.2
> !    <productname>PostgreSQL</productname> releases.)
>     </para>
>
>     <para>
> --- 559,565 ----
>      embedded in element values will be backslash-escaped.  For numeric
>      data types it is safe to assume that double quotes will never appear, but
>      for textual data types one should be prepared to cope with either presence
> !    or absence of quotes.
>     </para>
>
>     <para>
> Index: doc/src/sgml/backup.sgml
> ===================================================================
> RCS file: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v
> retrieving revision 2.79
> diff -c -c -r2.79 backup.sgml
> *** doc/src/sgml/backup.sgml    10 Mar 2006 19:10:46 -0000    2.79
> --- doc/src/sgml/backup.sgml    20 Mar 2006 23:42:31 -0000
> ***************
> *** 1211,1218 ****
>      the number after the first dot changes). This does not apply to
>      different minor releases under the same major release (where the
>      number after the second dot changes); these always have compatible
> !    storage formats. For example, releases 7.0.1, 7.1.2, and 7.2 are
> !    not compatible, whereas 7.1.1 and 7.1.2 are. When you update
>      between compatible versions, you can simply replace the executables
>      and reuse the data directory on disk. Otherwise you need to back
>      up your data and restore it on the new server.  This has to be done
> --- 1211,1218 ----
>      the number after the first dot changes). This does not apply to
>      different minor releases under the same major release (where the
>      number after the second dot changes); these always have compatible
> !    storage formats. For example, releases 7.2.1, 7.3.2, and 7.4 are
> !    not compatible, whereas 7.2.1 and 7.2.2 are. When you update
>      between compatible versions, you can simply replace the executables
>      and reuse the data directory on disk. Otherwise you need to back
>      up your data and restore it on the new server.  This has to be done
> Index: doc/src/sgml/config.sgml
> ===================================================================
> RCS file: /cvsroot/pgsql/doc/src/sgml/config.sgml,v
> retrieving revision 1.52
> diff -c -c -r1.52 config.sgml
> *** doc/src/sgml/config.sgml    10 Mar 2006 19:10:47 -0000    1.52
> --- doc/src/sgml/config.sgml    20 Mar 2006 23:42:34 -0000
> ***************
> *** 3788,3801 ****
>         <indexterm><primary>inheritance</></>
>         <listitem>
>          <para>
> !         This controls the inheritance semantics, in particular whether
> !         subtables are included by various commands by default. They were
> !         not included in versions prior to 7.1. If you need the old
> !         behavior you can set this variable to <literal>off</>, but in
> !         the long run you are encouraged to change your applications to
> !         use the <literal>ONLY</literal> key word to exclude subtables.
> !         See <xref linkend="ddl-inherit"> for more information about
> !         inheritance.
>          </para>
>         </listitem>
>        </varlistentry>
> --- 3788,3798 ----
>         <indexterm><primary>inheritance</></>
>         <listitem>
>          <para>
> !         This controls the inheritance semantics.  If turned <literal>off</>,
> !         subtables are not included by various commands by default; basically
> !         an implied <literal>ONLY</literal> key word.  This was added for
> !         compatibility with releases prior to 7.1.  See
> !         <xref linkend="ddl-inherit"> for more information.
>          </para>
>         </listitem>
>        </varlistentry>
> Index: doc/src/sgml/datatype.sgml
> ===================================================================
> RCS file: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v
> retrieving revision 1.166
> diff -c -c -r1.166 datatype.sgml
> *** doc/src/sgml/datatype.sgml    10 Mar 2006 19:10:47 -0000    1.166
> --- doc/src/sgml/datatype.sgml    20 Mar 2006 23:42:41 -0000
> ***************
> *** 894,915 ****
>       string.
>      </para>
>
> !     <para>
> !      If one explicitly casts a value to <type>character
> !      varying(<replaceable>n</>)</type> or
> !      <type>character(<replaceable>n</>)</type>, then an over-length
> !      value will be truncated to <replaceable>n</> characters without
> !      raising an error. (This too is required by the
> !      <acronym>SQL</acronym> standard.)
> !     </para>
> !
> !    <note>
> !     <para>
> !      Prior to <productname>PostgreSQL</> 7.2, strings that were too long were
> !      always truncated without raising an error, in either explicit or
> !      implicit casting contexts.
> !     </para>
> !    </note>
>
>      <para>
>       The notations <type>varchar(<replaceable>n</>)</type> and
> --- 894,907 ----
>       string.
>      </para>
>
> !    <para>
> !     If one explicitly casts a value to <type>character
> !     varying(<replaceable>n</>)</type> or
> !     <type>character(<replaceable>n</>)</type>, then an over-length
> !     value will be truncated to <replaceable>n</> characters without
> !     raising an error. (This too is required by the
> !     <acronym>SQL</acronym> standard.)
> !    </para>
>
>      <para>
>       The notations <type>varchar(<replaceable>n</>)</type> and
> ***************
> *** 2899,2913 ****
>       </para>
>      </note>
>
> -    <note>
> -     <para>
> -      Prior to <productname>PostgreSQL</> 7.2, <type>bit</type> data
> -      was always silently truncated or zero-padded on the right, with
> -      or without an explicit cast. This was changed to comply with the
> -      <acronym>SQL</acronym> standard.
> -     </para>
> -    </note>
> -
>      <para>
>       Refer to <xref
>       linkend="sql-syntax-bit-strings"> for information about the syntax
> --- 2891,2896 ----
> Index: doc/src/sgml/datetime.sgml
> ===================================================================
> RCS file: /cvsroot/pgsql/doc/src/sgml/datetime.sgml,v
> retrieving revision 2.48
> diff -c -c -r2.48 datetime.sgml
> *** doc/src/sgml/datetime.sgml    10 Mar 2006 19:10:47 -0000    2.48
> --- doc/src/sgml/datetime.sgml    20 Mar 2006 23:42:42 -0000
> ***************
> *** 171,180 ****
>         <tip>
>          <para>
>           Gregorian years AD 1-99 may be entered by using 4 digits with leading
> !         zeros (e.g., <literal>0099</> is AD 99). Previous versions of
> !         <productname>PostgreSQL</productname> accepted years with three
> !         digits and with single digits, but as of version 7.0 the rules have
> !         been tightened up to reduce the possibility of ambiguity.
>          </para>
>         </tip>
>        </para>
> --- 171,177 ----
>         <tip>
>          <para>
>           Gregorian years AD 1-99 may be entered by using 4 digits with leading
> !         zeros (e.g., <literal>0099</> is AD 99).
>          </para>
>         </tip>
>        </para>
> Index: doc/src/sgml/ddl.sgml
> ===================================================================
> RCS file: /cvsroot/pgsql/doc/src/sgml/ddl.sgml,v
> retrieving revision 1.55
> diff -c -c -r1.55 ddl.sgml
> *** doc/src/sgml/ddl.sgml    18 Feb 2006 23:14:45 -0000    1.55
> --- doc/src/sgml/ddl.sgml    20 Mar 2006 23:42:43 -0000
> ***************
> *** 2145,2165 ****
>     <note>
>      <title>Deprecated</title>
>      <para>
> !      In previous versions of <productname>PostgreSQL</productname>, the
>        default behavior was not to include child tables in queries. This was
> !      found to be error prone and is also in violation of the SQL
> !      standard. Under the old syntax, to include the child tables you append
> !      <literal>*</literal> to the table name. For example:
> ! <programlisting>
> ! SELECT * from cities*;
> ! </programlisting>
> !      You can still explicitly specify scanning child tables by
> !      appending <literal>*</literal>, as well as explicitly specify not
> !      scanning child tables by writing <literal>ONLY</literal>.  But
> !      beginning in version 7.1, the default behavior for an undecorated
> !      table name is to scan its child tables too, whereas before the
> !      default was not to do so.  To get the old default behavior,
> !      disable the <xref linkend="guc-sql-inheritance"> configuration
>        option.
>      </para>
>     </note>
> --- 2145,2155 ----
>     <note>
>      <title>Deprecated</title>
>      <para>
> !      In releases of <productname>PostgreSQL</productname> prior to 7.1, the
>        default behavior was not to include child tables in queries. This was
> !      found to be error prone and also in violation of the SQL
> !      standard.  You can get the pre-7.1 behavior by turning off the
> !      <xref linkend="guc-sql-inheritance"> configuration
>        option.
>      </para>
>     </note>
> Index: doc/src/sgml/func.sgml
> ===================================================================
> RCS file: /cvsroot/pgsql/doc/src/sgml/func.sgml,v
> retrieving revision 1.313
> diff -c -c -r1.313 func.sgml
> *** doc/src/sgml/func.sgml    10 Mar 2006 20:15:25 -0000    1.313
> --- doc/src/sgml/func.sgml    20 Mar 2006 23:42:48 -0000
> ***************
> *** 6118,6131 ****
>        the result is given to the full available precision.
>       </para>
>
> -     <note>
> -      <para>
> -       Prior to <productname>PostgreSQL</productname> 7.2, the precision
> -       parameters were unimplemented, and the result was always given
> -       in integer seconds.
> -      </para>
> -     </note>
> -
>      <para>
>       Some examples:
>   <screen>
> --- 6118,6123 ----
> Index: doc/src/sgml/libpq.sgml
> ===================================================================
> RCS file: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v
> retrieving revision 1.206
> diff -c -c -r1.206 libpq.sgml
> *** doc/src/sgml/libpq.sgml    10 Mar 2006 19:10:48 -0000    1.206
> --- doc/src/sgml/libpq.sgml    20 Mar 2006 23:42:50 -0000
> ***************
> *** 686,699 ****
>   <indexterm><primary>libpq-int.h</></>
>   <application>libpq</application> application programmers should be careful to
>   maintain the <structname>PGconn</structname> abstraction.  Use the accessor
> ! functions described below to get
> ! at the contents of <structname>PGconn</structname>.  Avoid directly referencing the fields of the
> ! <structname>PGconn</> structure because they are subject to change in the future.
> ! (Beginning in <productname>PostgreSQL</productname> release 6.4, the
> ! definition of the <type>struct</type> behind <structname>PGconn</> is not even provided in
<filename>libpq-fe.h</filename>.
> ! If you have old code that accesses <structname>PGconn</structname> fields directly, you can keep using it
> ! by including <filename>libpq-int.h</filename> too, but you are encouraged to fix the code
> ! soon.)
>   </para>
>   </tip>
>
> --- 686,695 ----
>   <indexterm><primary>libpq-int.h</></>
>   <application>libpq</application> application programmers should be careful to
>   maintain the <structname>PGconn</structname> abstraction.  Use the accessor
> ! functions described below to get at the contents of <structname>PGconn</structname>.
> ! Reference to internal <structname>PGconn</structname> fields using
> ! <filename>libpq-int.h</> is not recommended because they are subject to change
> ! in the future.
>   </para>
>   </tip>
>
> ***************
> *** 2972,2978 ****
>
>   typedef struct pgNotify {
>       char *relname;              /* notification condition name */
> !     int  be_pid;                /* process ID of server process */
>       char *extra;                /* notification parameter */
>   } PGnotify;
>   </synopsis>
> --- 2968,2974 ----
>
>   typedef struct pgNotify {
>       char *relname;              /* notification condition name */
> !     int  be_pid;                /* process ID of notifying server process */
>       char *extra;                /* notification parameter */
>   } PGnotify;
>   </synopsis>
> ***************
> *** 2986,2999 ****
>   always point to an empty string.)
>   </para>
>
> - <note>
> - <para>
> -  In <productname>PostgreSQL</productname> 6.4 and later,
> -  the <structfield>be_pid</structfield> is that of the notifying server process,
> -  whereas in earlier versions it was always the <acronym>PID</acronym> of your own server process.
> - </para>
> - </note>
> -
>   <para>
>   <xref linkend="libpq-example-2"> gives a sample program that illustrates the use
>   of asynchronous notification.
> --- 2982,2987 ----
> ***************
> *** 4288,4303 ****
>      </itemizedlist>
>     </para>
>
> -   <para>
> -    <indexterm><primary>libpq-int.h</></>
> -    If your codes references the header file
> -    <filename>libpq-int.h</filename> and you refuse to fix your code to
> -    not use it, starting in <productname>PostgreSQL</> 7.2, this file will be found in
> -    <filename><replaceable>includedir</replaceable>/postgresql/internal/libpq-int.h</filename>,
> -    so you need to add the appropriate <option>-I</option> option to
> -    your compiler command line.
> -   </para>
> -
>    </sect1>
>
>
> --- 4276,4281 ----
> Index: doc/src/sgml/lobj.sgml
> ===================================================================
> RCS file: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v
> retrieving revision 1.39
> diff -c -c -r1.39 lobj.sgml
> *** doc/src/sgml/lobj.sgml    10 Mar 2006 19:10:48 -0000    1.39
> --- doc/src/sgml/lobj.sgml    20 Mar 2006 23:42:50 -0000
> ***************
> *** 25,67 ****
>       values.  This is not described here.
>      </para>
>
> !   <sect1 id="lo-history">
> !    <title>History</title>
>
> !    <para>
> !     <productname>POSTGRES 4.2</productname>, the indirect predecessor
> !     of <productname>PostgreSQL</productname>, supported three standard
> !     implementations of large objects: as files external to the
> !     <productname>POSTGRES</productname> server, as external files
> !     managed by the <productname>POSTGRES</productname> server, and as
> !     data stored within the <productname>POSTGRES</productname>
> !     database. This caused considerable confusion among users. As a
> !     result, only support for large objects as data stored within the
> !     database is retained in <productname>PostgreSQL</productname>.
> !     Even though this is slower to access, it provides stricter data
> !     integrity.  For historical reasons, this storage scheme is
> !     referred to as <firstterm>Inversion large
> !     objects</firstterm>. (You will see the term Inversion used
> !     occasionally to mean the same thing as large object.)  Since
> !     <productname>PostgreSQL 7.1</productname>, all large objects are
> !     placed in one system table called
> !     <classname>pg_largeobject</classname>.
> !    </para>
>
>      <para>
> !     <indexterm>
> !      <primary>TOAST</primary>
> !      <secondary>versus large objects</secondary>
> !     </indexterm>
> !     <productname>PostgreSQL</productname> 7.1 introduced a mechanism
> !     (nicknamed <quote><acronym>TOAST</acronym></quote>) that allows
> !     data values to be much larger than single pages.  This
> !     makes the large object facility partially obsolete.  One
>       remaining advantage of the large object facility is that it allows values
>       up to 2 GB in size, whereas <acronym>TOAST</acronym>ed fields can be at
> !     most 1 GB.  Also, large objects can be manipulated piece-by-piece much more
> !     easily than ordinary data fields, so the practical limits are considerably
> !     different.
>      </para>
>
>     </sect1>
> --- 25,50 ----
>       values.  This is not described here.
>      </para>
>
> !   <sect1 id="lo-intro">
> !    <title>Introduction</title>
>
> !    <indexterm>
> !     <primary>TOAST</primary>
> !     <secondary>versus large objects</secondary>
> !    </indexterm>
>
>      <para>
> !     All large objects are placed in a single system table called
> !     <classname>pg_largeobject</classname>.
> !     <productname>PostgreSQL</productname> also supports a storage system called
> !     <quote><acronym>TOAST</acronym></quote> that automatically stores values
> !     larger than a single database page into a secondary storage area per table.
> !     This makes the large object facility partially obsolete.  One
>       remaining advantage of the large object facility is that it allows values
>       up to 2 GB in size, whereas <acronym>TOAST</acronym>ed fields can be at
> !     most 1 GB.  Also, large objects can be randomly modified using a read/write
> !     API that is more efficient than performing such operations using
> !     <acronym>TOAST</acronym>.
>      </para>
>
>     </sect1>
> ***************
> *** 70,77 ****
>      <title>Implementation Features</title>
>
>      <para>
> !     The large object implementation breaks  large
> !     objects  up  into  <quote>chunks</quote>  and  stores  the chunks in
>       rows in the database.  A B-tree index guarantees fast
>       searches for the correct chunk number when doing random
>       access reads and writes.
> --- 53,60 ----
>      <title>Implementation Features</title>
>
>      <para>
> !     The large object implementation breaks large
> !     objects up into <quote>chunks</quote> and stores the chunks in
>       rows in the database.  A B-tree index guarantees fast
>       searches for the correct chunk number when doing random
>       access reads and writes.
> ***************
> *** 86,95 ****
>       <productname>PostgreSQL</productname> client interface libraries
>       provide for accessing large objects.  All large object
>       manipulation using these functions <emphasis>must</emphasis> take
> !     place within an SQL transaction block.  (This requirement is
> !     strictly enforced as of <productname>PostgreSQL 6.5</>, though it
> !     has been an implicit requirement in previous versions, resulting
> !     in misbehavior if ignored.)
>       The  <productname>PostgreSQL</productname>  large  object interface is modeled after
>       the <acronym>Unix</acronym>  file-system  interface,  with  analogues  of
>       <function>open</function>,  <function>read</function>,
> --- 69,75 ----
>       <productname>PostgreSQL</productname> client interface libraries
>       provide for accessing large objects.  All large object
>       manipulation using these functions <emphasis>must</emphasis> take
> !     place within an SQL transaction block.
>       The  <productname>PostgreSQL</productname>  large  object interface is modeled after
>       the <acronym>Unix</acronym>  file-system  interface,  with  analogues  of
>       <function>open</function>,  <function>read</function>,
> Index: doc/src/sgml/maintenance.sgml
> ===================================================================
> RCS file: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v
> retrieving revision 1.54
> diff -c -c -r1.54 maintenance.sgml
> *** doc/src/sgml/maintenance.sgml    10 Mar 2006 19:10:48 -0000    1.54
> --- doc/src/sgml/maintenance.sgml    20 Mar 2006 23:42:50 -0000
> ***************
> *** 82,96 ****
>     </para>
>
>     <para>
> !    Beginning in <productname>PostgreSQL</productname> 7.2, the standard form
> !    of <command>VACUUM</> can run in parallel with normal database operations
> !    (selects, inserts, updates, deletes, but not changes to table definitions).
> !    Routine vacuuming is therefore not nearly as intrusive as it was in prior
> !    releases, and it is not as critical to try to schedule it at low-usage
> !    times of day.
> !   </para>
> !
> !   <para>
>      Beginning in <productname>PostgreSQL</productname> 8.0, there are
>      configuration parameters that can be adjusted to further reduce the
>      performance impact of background vacuuming.  See
> --- 82,90 ----
>     </para>
>
>     <para>
> !    The standard form of <command>VACUUM</> can run in parallel with
> !    normal database operations (SELECTs, INSERTs, UPDATEs, DELETEs, but not
> !    changes to table definitions).
>      Beginning in <productname>PostgreSQL</productname> 8.0, there are
>      configuration parameters that can be adjusted to further reduce the
>      performance impact of background vacuuming.  See
> ***************
> *** 245,256 ****
>       It is possible to run <command>ANALYZE</> on specific tables and even
>       just specific columns of a table, so the flexibility exists to update some
>       statistics more frequently than others if your application requires it.
> !     In practice, however, the usefulness of this feature is doubtful.
> !     Beginning in <productname>PostgreSQL</productname> 7.2,
> !     <command>ANALYZE</> is a fairly fast operation even on large tables,
> !     because it uses a statistical random sampling of the rows of a table
> !     rather than reading every single row.  So it's probably much simpler
> !     to just run it over the whole database every so often.
>      </para>
>
>      <tip>
> --- 239,247 ----
>       It is possible to run <command>ANALYZE</> on specific tables and even
>       just specific columns of a table, so the flexibility exists to update some
>       statistics more frequently than others if your application requires it.
> !     In practice, however, it is usually best to just analyze the entire database
> !     because it is a fast operation.  It uses a statistical random sampling of
> !     the rows of a table rather than reading every single row.
>      </para>
>
>      <tip>
> ***************
> *** 295,312 ****
>       transactions that were in the past appear to be in the future — which
>       means their outputs become invisible.  In short, catastrophic data loss.
>       (Actually the data is still there, but that's cold comfort if you can't
> !     get at it.)
> !    </para>
> !
> !    <para>
> !     Prior to <productname>PostgreSQL</productname> 7.2, the only defense
> !     against XID wraparound was to re-<command>initdb</> at least every 4
> !     billion transactions. This of course was not very satisfactory for
> !     high-traffic sites, so a better solution has been devised. The new
> !     approach allows a server to remain up indefinitely, without
> !     <command>initdb</> or any sort of restart. The price is this
> !     maintenance requirement: <emphasis>every table in the database must
> !     be vacuumed at least once every billion transactions</emphasis>.
>      </para>
>
>      <para>
> --- 286,293 ----
>       transactions that were in the past appear to be in the future — which
>       means their outputs become invisible.  In short, catastrophic data loss.
>       (Actually the data is still there, but that's cold comfort if you can't
> !     get at it.)  To avoid this, it is <emphasis>necessary to vacuum every table
> !     in every database at least once every billion transactions</emphasis>.
>      </para>
>
>      <para>
> Index: doc/src/sgml/mvcc.sgml
> ===================================================================
> RCS file: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v
> retrieving revision 2.55
> diff -c -c -r2.55 mvcc.sgml
> *** doc/src/sgml/mvcc.sgml    10 Mar 2006 19:10:48 -0000    2.55
> --- doc/src/sgml/mvcc.sgml    20 Mar 2006 23:42:51 -0000
> ***************
> *** 899,908 ****
>       TABLE</command> locks the whole table.)  This should be taken into
>       account when porting applications to
>       <productname>PostgreSQL</productname> from other environments.
> -     (Before version 6.5 <productname>PostgreSQL</productname> used
> -     read locks, and so this above consideration is also relevant when
> -     upgrading from <productname>PostgreSQL</productname> versions
> -     prior to 6.5.)
>      </para>
>
>      <para>
> --- 899,904 ----
> Index: doc/src/sgml/rules.sgml
> ===================================================================
> RCS file: /cvsroot/pgsql/doc/src/sgml/rules.sgml,v
> retrieving revision 1.44
> diff -c -c -r1.44 rules.sgml
> *** doc/src/sgml/rules.sgml    22 Oct 2005 14:44:35 -0000    1.44
> --- doc/src/sgml/rules.sgml    20 Mar 2006 23:42:51 -0000
> ***************
> *** 2043,2052 ****
>   <para>
>       Another situation is cases on <command>UPDATE</command> where it depends on the
>       change of an attribute if an action should be performed or
> !     not. In <productname>PostgreSQL</productname> version 6.4, the
> !     attribute specification for rule events is disabled (it will have
> !     its comeback latest in 6.5, maybe earlier
> !     - stay tuned). So for now the only way to
>       create a rule as in the shoelace_log example is to do it with
>       a rule qualification. That results in an extra query that is
>       performed always, even if the attribute of interest cannot
> --- 2043,2049 ----
>   <para>
>       Another situation is cases on <command>UPDATE</command> where it depends on the
>       change of an attribute if an action should be performed or
> !     not. The only way to
>       create a rule as in the shoelace_log example is to do it with
>       a rule qualification. That results in an extra query that is
>       performed always, even if the attribute of interest cannot
> Index: doc/src/sgml/storage.sgml
> ===================================================================
> RCS file: /cvsroot/pgsql/doc/src/sgml/storage.sgml,v
> retrieving revision 1.9
> diff -c -c -r1.9 storage.sgml
> *** doc/src/sgml/storage.sgml    10 Mar 2006 19:10:49 -0000    1.9
> --- doc/src/sgml/storage.sgml    20 Mar 2006 23:42:52 -0000
> ***************
> *** 187,201 ****
>   </para>
>
>   <para>
> ! Since <productname>PostgreSQL</productname> uses a fixed page size (commonly
> ! 8Kb), and does not allow tuples to span multiple pages, it's not possible to
> ! store very large field values directly.  Before <productname>PostgreSQL</> 7.1
> ! there was a hard limit of just under one page on the total amount of data that
> ! could be put into a table row.  In release 7.1 and later, this limit is
> ! overcome by allowing large field values to be compressed and/or broken up into
> ! multiple physical rows.  This happens transparently to the user, with only
> ! small impact on most of the backend code.  The technique is affectionately
> ! known as <acronym>TOAST</> (or <quote>the best thing since sliced bread</>).
>   </para>
>
>   <para>
> --- 187,199 ----
>   </para>
>
>   <para>
> ! <productname>PostgreSQL</productname> uses a fixed page size (commonly
> ! 8Kb), and does not allow tuples to span multiple pages.  Therefore,  it is
> ! not possible to store very large field values directly.  To overcome
> ! this limitation, large  field values are compressed and/or broken up into
> ! multiple physical rows. This happens transparently to the user, with only
> ! small impact on most of the backend code.  The technique is affectionately
> ! known as <acronym>TOAST</>  (or <quote>the best thing since sliced bread</>).
>   </para>
>
>   <para>
> Index: doc/src/sgml/xfunc.sgml
> ===================================================================
> RCS file: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v
> retrieving revision 1.111
> diff -c -c -r1.111 xfunc.sgml
> *** doc/src/sgml/xfunc.sgml    10 Mar 2006 19:10:49 -0000    1.111
> --- doc/src/sgml/xfunc.sgml    20 Mar 2006 23:42:53 -0000
> ***************
> *** 1192,1206 ****
>       command <literal>pg_config --pkglibdir</literal>.
>      </para>
>
> -    <para>
> -     Before <productname>PostgreSQL</productname> release 7.2, only
> -     exact absolute paths to object files could be specified in
> -     <command>CREATE FUNCTION</>.  This approach is now deprecated
> -     since it makes the function definition unnecessarily unportable.
> -     It's best to specify just the shared library name with no path nor
> -     extension, and let the search mechanism provide that information
> -     instead.
> -    </para>
>     </sect2>
>
>      <sect2 id="xfunc-c-basetype">
> --- 1192,1197 ----
> ***************
> *** 1915,1929 ****
>           --includedir-server</literal><indexterm><primary>pg_config</><secondary>with user-defined C functions</></>
>           to find out where the <productname>PostgreSQL</> server header
>           files are installed on your system (or the system that your
> !         users will be running on).  This option is new with
> !         <productname>PostgreSQL</> 7.2.  For
> !         <productname>PostgreSQL</> 7.1 you should use the option
> !         <option>--includedir</option>.  (<command>pg_config</command>
> !         will exit with a non-zero status if it encounters an unknown
> !         option.)  For releases prior to 7.1 you will have to guess,
> !         but since that was before the current calling conventions were
> !         introduced, it is unlikely that you want to support those
> !         releases.
>          </para>
>         </listitem>
>
> --- 1906,1912 ----
>           --includedir-server</literal><indexterm><primary>pg_config</><secondary>with user-defined C functions</></>
>           to find out where the <productname>PostgreSQL</> server header
>           files are installed on your system (or the system that your
> !         users will be running on).
>          </para>
>         </listitem>
>

>
> ---------------------------(end of broadcast)---------------------------
> TIP 9: In versions below 8.0, the planner will ignore your desire to
>        choose an index scan if your joining column's datatypes do not
>        match

--
  Bruce Momjian   http://candle.pha.pa.us
  EnterpriseDB    http://www.enterprisedb.com

  + If your life is a hard drive, Christ can be your backup. +