Re: pg_upgrade docs

On Mon, May 24, 2010 at 11:35 PM, Bruce Momjian <bruce(at)momjian(dot)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.

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.

--

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

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise Postgres Company