Re: pg_upgrade docs

Robert Haas wrote:
> 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.

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(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com