Re: pg_upgrade docs - Mailing list pgsql-hackers

Robert Haas wrote:
> On Mon, May 24, 2010 at 11:35 PM, Bruce Momjian <bruce@momjian.us> wrote:
> > Have you read the docs? ?It does mention the issue with /contrib and
> > stuff. ?How do I document a limitation I don't know about? ?This is all
> > very vague. ?Please suggest some wording.
>
> OK, here's an attempt.  Please fact-check.
>
> --
>
> General Limitations
>
> pg_upgrade relies on binary compatibility between the old and new
> on-disk formats, including the on-disk formats of individual data
> types.  pg_upgrade attempts to detect cases in which the on-disk
> format has changed; for example, it verifies that the old and new
> clusters have the same value for --enable-integer-datetimes.  However,
> there is no systematic way for pg_upgrade to detect problems of this
> type; it has hard-coded knowledge of the specific cases known to exist
> in core PostgreSQL, including /contrib.  If third-party or
> user-defined data types or access methods are used, it is the user's
> responsibility to verify that the versions loaded into the old and new
> clusters use compatible on-disk formats.  If they do not, pg_upgrade
> may appear to work but subsequently crash or silently corrupt data.

OK, I have added a mention of the issues above, in a more abbreviated
format.

> pg_upgrade also relies on ABI compatibility between modules loaded
> into the old and new clusters.  For example, if an SQL function in the
> old cluster is defined to call a particular C function, pg_upgrade
> will recreate SQL function in the new cluster and will configure it to
> call the same C function.  If no such C function can be found by the
> new cluster, pg_upgrade will simply fail.  However, if a C function of
> the same name exists in the new cluster, but expects a different
> number of arguments or different types of arguments, then it is likely
> to crash the system when called.  In the worst case, data corruption
> could result.

These issues are not unique to pg_upgrade, and could happen even in a
pg_dump restore.

> Also, the following sentence appears not to fit with our "only to 9.0"
> policy: "For Windows users, note that due to different integer
> datetimes settings used by the one-click installer and the MSI
> installer, it is only possible to upgrade from version 8.3 of the
> one-click distribution to version 8.4 of the one-click distribution.
> It is not possible to upgrade from the MSI installer to the one-click
> installer."

Agreed.  I added a "8.4 or later" mention.  It is not worth calling it
"9.0 or later" because then I would have to update this mention for
every major release.

Applied patch attached.

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com
Index: doc/src/sgml/pgupgrade.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/pgupgrade.sgml,v
retrieving revision 1.10
diff -c -c -r1.10 pgupgrade.sgml
*** doc/src/sgml/pgupgrade.sgml    24 May 2010 17:43:39 -0000    1.10
--- doc/src/sgml/pgupgrade.sgml    25 May 2010 14:50:36 -0000
***************
*** 16,21 ****
--- 16,31 ----
    9.0.1 -> 9.0.4.
   </para>

+  <para>
+   <application>pg_upgrade</> works because, though new features are
+   regularly added to Postgres major releases, the internal data storage
+   format rarely changes.  <application>pg_upgrade</> does its best to
+   make sure the old and new clusters are binary-compatible, e.g.  by
+   checking for compatible compile-time settings.  It is important that
+   any external modules are also binary compatibile, though this cannot
+   be checked by <application>pg_upgrade</>.
+  </para>
+
   <sect2>
    <title>Supported Versions</title>

***************
*** 440,446 ****
    <sect2>
    <title>Limitations in migrating <emphasis>from</> PostgreSQL 8.3</title>

-
    <para>
     Upgrading from PostgreSQL 8.3 has additional restrictions not present
     when upgrading from later PostgreSQL releases.  For example,
--- 450,455 ----
***************
*** 502,509 ****
     For Windows users, note that due to different integer datetimes settings
     used by the one-click installer and the MSI installer, it is only
     possible to upgrade from version 8.3 of the one-click distribution to
!    version 8.4 of the one-click distribution. It is not possible to upgrade
!    from the MSI installer to the one-click installer.
    </para>

    <para>
--- 511,518 ----
     For Windows users, note that due to different integer datetimes settings
     used by the one-click installer and the MSI installer, it is only
     possible to upgrade from version 8.3 of the one-click distribution to
!    version 8.4 or later of the one-click distribution. It is not
!    possible to upgrade from the MSI installer to the one-click installer.
    </para>

    <para>