Обсуждение: pg_upgrade docs

Поиск
Список
Период
Сортировка

pg_upgrade docs

От
Stefan Kaltenbrunner
Дата:
While looking at the docs for pg_upgrade I noticed some stuff that the
following patch attempts to at least partly address.
There is quite some confusion going on between using "Postgres" and
PostgreSQL, I changed that to the later because that is how we spell the
productname in all the other parts of the docs, also added some further
markups and crossreferences to other docs.
Stuff that seems to need further work is more or less the "limitations"
section, I don't think there are only issues when upgrade from 8.3 but
also from 8.4 (though not as much iirc) there is also the rather bold
"we will support upgrades from every snapshot and alpha release" which
seems very optimistic...


Stefan

Вложения

Re: pg_upgrade docs

От
Alvaro Herrera
Дата:
Excerpts from Stefan Kaltenbrunner's message of mié may 19 15:53:18 -0400 2010:
> While looking at the docs for pg_upgrade I noticed some stuff that the
> following patch attempts to at least partly address.

Surely this para can be removed?
    <para>     If you are using tablespaces and migrating to 8.4 or earlier, there must
-     be sufficient directory permissions to allow pg_upgrade to rename each
+     be sufficient directory permissions to allow <application>pg_upgrade</> to rename each     tablespace directory
toadd a ".old" suffix.    </para>
 

-- 


Re: pg_upgrade docs

От
Bruce Momjian
Дата:
Stefan Kaltenbrunner wrote:
> While looking at the docs for pg_upgrade I noticed some stuff that the
> following patch attempts to at least partly address.
> There is quite some confusion going on between using "Postgres" and
> PostgreSQL, I changed that to the later because that is how we spell the
> productname in all the other parts of the docs, also added some further
> markups and crossreferences to other docs.

Applied.

> Stuff that seems to need further work is more or less the "limitations"
> section, I don't think there are only issues when upgrade from 8.3 but
> also from 8.4 (though not as much iirc) there is also the rather bold

There are some limitations when migrating from 8.3 to 8.4, but not when
migrating from 8.3 to 9.0, because we added a feature to 9.0.  Can you
give a specific example?

> "we will support upgrades from every snapshot and alpha release" which
> seems very optimistic...

Well, I didn't say "every".

--  Bruce Momjian  <bruce@momjian.us>        http://momjian.us EnterpriseDB
http://enterprisedb.com


Re: pg_upgrade docs

От
Bruce Momjian
Дата:
Alvaro Herrera wrote:
> Excerpts from Stefan Kaltenbrunner's message of mié may 19 15:53:18 -0400 2010:
> > While looking at the docs for pg_upgrade I noticed some stuff that the
> > following patch attempts to at least partly address.
> 
> Surely this para can be removed?
> 
>      <para>
>       If you are using tablespaces and migrating to 8.4 or earlier, there must
> -     be sufficient directory permissions to allow pg_upgrade to rename each
> +     be sufficient directory permissions to allow <application>pg_upgrade</> to rename each
>       tablespace directory to add a ".old" suffix.
>      </para>

Ah, yes, removed.

--  Bruce Momjian  <bruce@momjian.us>        http://momjian.us EnterpriseDB
http://enterprisedb.com


Re: pg_upgrade docs

От
Andres Freund
Дата:
On Wednesday 19 May 2010 22:39:32 Bruce Momjian wrote:
> There are some limitations when migrating from 8.3 to 8.4, but not when
> migrating from 8.3 to 9.0, because we added a feature to 9.0.  Can you
> give a specific example?
Didnt the 'name' alignment change?

Andres 


Re: pg_upgrade docs

От
Bruce Momjian
Дата:
Andres Freund wrote:
> On Wednesday 19 May 2010 22:39:32 Bruce Momjian wrote:
> > There are some limitations when migrating from 8.3 to 8.4, but not when
> > migrating from 8.3 to 9.0, because we added a feature to 9.0.  Can you
> > give a specific example?
> Didnt the 'name' alignment change?

Uh, the heading above that item is:
 <title>Limitations in migrating <emphasis>from</> PostgreSQL 8.3</title>

What is unclear there?  It covers going to 8.4 and 9.0.

--  Bruce Momjian  <bruce@momjian.us>        http://momjian.us EnterpriseDB
http://enterprisedb.com


Re: pg_upgrade docs

От
Stefan Kaltenbrunner
Дата:
On 05/19/2010 05:16 PM, Bruce Momjian wrote:
> Andres Freund wrote:
>> On Wednesday 19 May 2010 22:39:32 Bruce Momjian wrote:
>>> There are some limitations when migrating from 8.3 to 8.4, but not when
>>> migrating from 8.3 to 9.0, because we added a feature to 9.0.  Can you
>>> give a specific example?
>> Didnt the 'name' alignment change?
> 
> Uh, the heading above that item is:
> 
>   <title>Limitations in migrating <emphasis>from</> PostgreSQL
>   8.3</title>
> 
> What is unclear there?  It covers going to 8.4 and 9.0.

well the wording makes it kinda unclear on what happens if you go FROM
8.4 to 9.0. If there are no known limits we might want to add a small
note saying so. If there are some we might want to restructure the
paragraph a bit...


Stefan


Re: pg_upgrade docs

От
Bruce Momjian
Дата:
Stefan Kaltenbrunner wrote:
> On 05/19/2010 05:16 PM, Bruce Momjian wrote:
> > Andres Freund wrote:
> >> On Wednesday 19 May 2010 22:39:32 Bruce Momjian wrote:
> >>> There are some limitations when migrating from 8.3 to 8.4, but not when
> >>> migrating from 8.3 to 9.0, because we added a feature to 9.0.  Can you
> >>> give a specific example?
> >> Didnt the 'name' alignment change?
> > 
> > Uh, the heading above that item is:
> > 
> >   <title>Limitations in migrating <emphasis>from</> PostgreSQL
> >   8.3</title>
> > 
> > What is unclear there?  It covers going to 8.4 and 9.0.
> 
> well the wording makes it kinda unclear on what happens if you go FROM
> 8.4 to 9.0. If there are no known limits we might want to add a small
> note saying so. If there are some we might want to restructure the
> paragraph a bit...

Sorry for the delay in replying.  The section you list is titled:
F.31.4. Limitations in migrating from PostgreSQL 8.3
http://developer.postgresql.org/pgdocs/postgres/pgupgrade.html

and the first sentence is:
  pg_upgrade will not work for a migration from 8.3 if a user column

I have updated the paragraph to be:
  Upgrading from PostgreSQL 8.3 has additional restrictions not present  when upgrading from later PostgreSQL releases.
For example,  pg_upgrade will not work for a migration from 8.3 if a user column  is defined as:
 

Can you suggest other wording?

FYI, the items that affect only 8.3 to 8.4 migrations are no longer in
the 9.0 pg_upgrade docs because we don't support 8.4 as a target
anymore;  specifically:
Limitations In Migrating _to_ PostgreSQL 8.4----------------------------------------------------------pg_migrator will
notwork if a user column is defined as:    o  a user-defined composite data type    o  a user-defined array data type
o  a user-defined enum data typeYou must drop any such columns and migrate them manually.
 

You can see the full documentation here:
http://cvs.pgfoundry.org/cgi-bin/cvsweb.cgi/pg-migrator/pg_migrator/README?rev=1.78&content-type=text/x-cvsweb-markup

--  Bruce Momjian  <bruce@momjian.us>        http://momjian.us EnterpriseDB
http://enterprisedb.com


Re: pg_upgrade docs

От
Stefan Kaltenbrunner
Дата:
On 05/24/2010 07:43 PM, Bruce Momjian wrote:
> Stefan Kaltenbrunner wrote:
>> On 05/19/2010 05:16 PM, Bruce Momjian wrote:
>>> Andres Freund wrote:
>>>> On Wednesday 19 May 2010 22:39:32 Bruce Momjian wrote:
>>>>> There are some limitations when migrating from 8.3 to 8.4, but not when
>>>>> migrating from 8.3 to 9.0, because we added a feature to 9.0.  Can you
>>>>> give a specific example?
>>>> Didnt the 'name' alignment change?
>>>
>>> Uh, the heading above that item is:
>>>
>>>    <title>Limitations in migrating<emphasis>from</>  PostgreSQL
>>>    8.3</title>
>>>
>>> What is unclear there?  It covers going to 8.4 and 9.0.
>>
>> well the wording makes it kinda unclear on what happens if you go FROM
>> 8.4 to 9.0. If there are no known limits we might want to add a small
>> note saying so. If there are some we might want to restructure the
>> paragraph a bit...
>
> Sorry for the delay in replying.  The section you list is titled:
>
>     F.31.4. Limitations in migrating from PostgreSQL 8.3
>
>     http://developer.postgresql.org/pgdocs/postgres/pgupgrade.html
>
> and the first sentence is:
>
>     pg_upgrade will not work for a migration from 8.3 if a user column
>
> I have updated the paragraph to be:
>
>     Upgrading from PostgreSQL 8.3 has additional restrictions not present
>     when upgrading from later PostgreSQL releases.  For example,
>     pg_upgrade will not work for a migration from 8.3 if a user column
>     is defined as:
>
> Can you suggest other wording?

hmm that seems better thanks, however I just noticed that we don't have 
a "general limitations" section. The way the docs are now done suggests 
that there are not limitations at all (except for the two warnings in 
the migration guide). Is pg_upgrade really up to the point where it can 
fully replace pg_dump & pg_restore independent of the loaded (contrib) 
or even third party modules(like postgis or custom datatypes etc)?



Stefan


Re: pg_upgrade docs

От
Bruce Momjian
Дата:
Stefan Kaltenbrunner wrote:
> > I have updated the paragraph to be:
> >
> >     Upgrading from PostgreSQL 8.3 has additional restrictions not present
> >     when upgrading from later PostgreSQL releases.  For example,
> >     pg_upgrade will not work for a migration from 8.3 if a user column
> >     is defined as:
> >
> > Can you suggest other wording?
> 
> hmm that seems better thanks, however I just noticed that we don't have 
> a "general limitations" section. The way the docs are now done suggests 
> that there are not limitations at all (except for the two warnings in 
> the migration guide). Is pg_upgrade really up to the point where it can 
> fully replace pg_dump & pg_restore independent of the loaded (contrib) 
> or even third party modules(like postgis or custom datatypes etc)?

Yea, that's about right.  I can add limiations if you want.  ;-)

The only open pg_upgrade items are the ones on our TODO list:
http://wiki.postgresql.org/wiki/Todo

(I can't give you a URL hash-reference to the section because it doesn't
work on Firefox and no one seems to be able to fix it.)

--  Bruce Momjian  <bruce@momjian.us>        http://momjian.us EnterpriseDB
http://enterprisedb.com


Re: pg_upgrade docs

От
Robert Haas
Дата:
On Mon, May 24, 2010 at 3:11 PM, Bruce Momjian <bruce@momjian.us> wrote:
> Stefan Kaltenbrunner wrote:
>> > I have updated the paragraph to be:
>> >
>> >     Upgrading from PostgreSQL 8.3 has additional restrictions not present
>> >     when upgrading from later PostgreSQL releases.  For example,
>> >     pg_upgrade will not work for a migration from 8.3 if a user column
>> >     is defined as:
>> >
>> > Can you suggest other wording?
>>
>> hmm that seems better thanks, however I just noticed that we don't have
>> a "general limitations" section. The way the docs are now done suggests
>> that there are not limitations at all (except for the two warnings in
>> the migration guide). Is pg_upgrade really up to the point where it can
>> fully replace pg_dump & pg_restore independent of the loaded (contrib)
>> or even third party modules(like postgis or custom datatypes etc)?
>
> Yea, that's about right.  I can add limiations if you want.  ;-)

I don't believe this.  For one thing, I am pretty sure that if there
are ABI differences between loadable modules between the old and new
cluster, hilarity will ensue.

> The only open pg_upgrade items are the ones on our TODO list:
>
>        http://wiki.postgresql.org/wiki/Todo
>
> (I can't give you a URL hash-reference to the section because it doesn't
> work on Firefox and no one seems to be able to fix it.)

It works OK for me.  The link to /contrib/pg_upgrade within the nav
section at the top righthand corner of the page seems to work just
fine.

http://wiki.postgresql.org/wiki/Todo#.2Fcontrib.2Fpg_upgrade

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


Re: pg_upgrade docs

От
Bruce Momjian
Дата:
Robert Haas wrote:
> On Mon, May 24, 2010 at 3:11 PM, Bruce Momjian <bruce@momjian.us> wrote:
> > Stefan Kaltenbrunner wrote:
> >> > I have updated the paragraph to be:
> >> >
> >> > ? ? Upgrading from PostgreSQL 8.3 has additional restrictions not present
> >> > ? ? when upgrading from later PostgreSQL releases. ?For example,
> >> > ? ? pg_upgrade will not work for a migration from 8.3 if a user column
> >> > ? ? is defined as:
> >> >
> >> > Can you suggest other wording?
> >>
> >> hmm that seems better thanks, however I just noticed that we don't have
> >> a "general limitations" section. The way the docs are now done suggests
> >> that there are not limitations at all (except for the two warnings in
> >> the migration guide). Is pg_upgrade really up to the point where it can
> >> fully replace pg_dump & pg_restore independent of the loaded (contrib)
> >> or even third party modules(like postgis or custom datatypes etc)?
> >
> > Yea, that's about right. ?I can add limiations if you want. ?;-)
> 
> I don't believe this.  For one thing, I am pretty sure that if there
> are ABI differences between loadable modules between the old and new
> cluster, hilarity will ensue.

Well, the point is that our existing code doesn't have any
incompatibilites that I know of.  We could certainly add some in 9.1.

> > The only open pg_upgrade items are the ones on our TODO list:
> >
> > ? ? ? ?http://wiki.postgresql.org/wiki/Todo
> >
> > (I can't give you a URL hash-reference to the section because it doesn't
> > work on Firefox and no one seems to be able to fix it.)
> 
> It works OK for me.  The link to /contrib/pg_upgrade within the nav
> section at the top righthand corner of the page seems to work just
> fine.
> 
> http://wiki.postgresql.org/wiki/Todo#.2Fcontrib.2Fpg_upgrade

The problem is that the "Contents" menu on the top right of the page
doesn't allow a clickable link to that section, and many others.

--  Bruce Momjian  <bruce@momjian.us>        http://momjian.us EnterpriseDB
http://enterprisedb.com


Re: pg_upgrade docs

От
Robert Haas
Дата:
On Mon, May 24, 2010 at 3:41 PM, Bruce Momjian <bruce@momjian.us> wrote:
> Robert Haas wrote:
>> On Mon, May 24, 2010 at 3:11 PM, Bruce Momjian <bruce@momjian.us> wrote:
>> > Stefan Kaltenbrunner wrote:
>> >> > I have updated the paragraph to be:
>> >> >
>> >> > ? ? Upgrading from PostgreSQL 8.3 has additional restrictions not present
>> >> > ? ? when upgrading from later PostgreSQL releases. ?For example,
>> >> > ? ? pg_upgrade will not work for a migration from 8.3 if a user column
>> >> > ? ? is defined as:
>> >> >
>> >> > Can you suggest other wording?
>> >>
>> >> hmm that seems better thanks, however I just noticed that we don't have
>> >> a "general limitations" section. The way the docs are now done suggests
>> >> that there are not limitations at all (except for the two warnings in
>> >> the migration guide). Is pg_upgrade really up to the point where it can
>> >> fully replace pg_dump & pg_restore independent of the loaded (contrib)
>> >> or even third party modules(like postgis or custom datatypes etc)?
>> >
>> > Yea, that's about right. ?I can add limiations if you want. ?;-)
>>
>> I don't believe this.  For one thing, I am pretty sure that if there
>> are ABI differences between loadable modules between the old and new
>> cluster, hilarity will ensue.
>
> Well, the point is that our existing code doesn't have any
> incompatibilites that I know of.  We could certainly add some in 9.1.

Yes, or third-party vendors could add some for us.  We can't guarantee
this in general.

>> > The only open pg_upgrade items are the ones on our TODO list:
>> >
>> > ? ? ? ?http://wiki.postgresql.org/wiki/Todo
>> >
>> > (I can't give you a URL hash-reference to the section because it doesn't
>> > work on Firefox and no one seems to be able to fix it.)
>>
>> It works OK for me.  The link to /contrib/pg_upgrade within the nav
>> section at the top righthand corner of the page seems to work just
>> fine.
>>
>> http://wiki.postgresql.org/wiki/Todo#.2Fcontrib.2Fpg_upgrade
>
> The problem is that the "Contents" menu on the top right of the page
> doesn't allow a clickable link to that section, and many others.

It does for me...

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


Re: pg_upgrade docs

От
Dave Page
Дата:
On Mon, May 24, 2010 at 5:20 PM, Robert Haas <robertmhaas@gmail.com> wrote:

>>> It works OK for me.  The link to /contrib/pg_upgrade within the nav
>>> section at the top righthand corner of the page seems to work just
>>> fine.
>>>
>>> http://wiki.postgresql.org/wiki/Todo#.2Fcontrib.2Fpg_upgrade
>>
>> The problem is that the "Contents" menu on the top right of the page
>> doesn't allow a clickable link to that section, and many others.
>
> It does for me...

Doesn't here. FYI, neither do others such as 2.6, 2.7, 6.1 & 6.11


--
Dave Page
EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise Postgres Company


Re: pg_upgrade docs

От
Bruce Momjian
Дата:
Robert Haas wrote:
> On Mon, May 24, 2010 at 3:41 PM, Bruce Momjian <bruce@momjian.us> wrote:
> > Robert Haas wrote:
> >> On Mon, May 24, 2010 at 3:11 PM, Bruce Momjian <bruce@momjian.us> wrote:
> >> > Stefan Kaltenbrunner wrote:
> >> >> > I have updated the paragraph to be:
> >> >> >
> >> >> > ? ? Upgrading from PostgreSQL 8.3 has additional restrictions not present
> >> >> > ? ? when upgrading from later PostgreSQL releases. ?For example,
> >> >> > ? ? pg_upgrade will not work for a migration from 8.3 if a user column
> >> >> > ? ? is defined as:
> >> >> >
> >> >> > Can you suggest other wording?
> >> >>
> >> >> hmm that seems better thanks, however I just noticed that we don't have
> >> >> a "general limitations" section. The way the docs are now done suggests
> >> >> that there are not limitations at all (except for the two warnings in
> >> >> the migration guide). Is pg_upgrade really up to the point where it can
> >> >> fully replace pg_dump & pg_restore independent of the loaded (contrib)
> >> >> or even third party modules(like postgis or custom datatypes etc)?
> >> >
> >> > Yea, that's about right. ?I can add limiations if you want. ?;-)
> >>
> >> I don't believe this. ?For one thing, I am pretty sure that if there
> >> are ABI differences between loadable modules between the old and new
> >> cluster, hilarity will ensue.
> >
> > Well, the point is that our existing code doesn't have any
> > incompatibilites that I know of. ?We could certainly add some in 9.1.
> 
> Yes, or third-party vendors could add some for us.  We can't guarantee
> this in general.

What is your point?

--  Bruce Momjian  <bruce@momjian.us>        http://momjian.us EnterpriseDB
http://enterprisedb.com


Re: pg_upgrade docs

От
Robert Haas
Дата:
On Mon, May 24, 2010 at 5:38 PM, Dave Page <dpage@pgadmin.org> wrote:
> On Mon, May 24, 2010 at 5:20 PM, Robert Haas <robertmhaas@gmail.com> wrote:
>
>>>> It works OK for me.  The link to /contrib/pg_upgrade within the nav
>>>> section at the top righthand corner of the page seems to work just
>>>> fine.
>>>>
>>>> http://wiki.postgresql.org/wiki/Todo#.2Fcontrib.2Fpg_upgrade
>>>
>>> The problem is that the "Contents" menu on the top right of the page
>>> doesn't allow a clickable link to that section, and many others.
>>
>> It does for me...
>
> Doesn't here. FYI, neither do others such as 2.6, 2.7, 6.1 & 6.11

Oh, interesting.  2.6 and 2.7 don't work for me, but 6.1 and 6.11 do.
That is really odd.

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


Re: pg_upgrade docs

От
Robert Haas
Дата:
On Mon, May 24, 2010 at 5:50 PM, Bruce Momjian <bruce@momjian.us> wrote:
> What is your point?

My point is that I think Stefan has a good point when he says this:

>> >> >> hmm that seems better thanks, however I just noticed that we don't have
>> >> >> a "general limitations" section. The way the docs are now done suggests
>> >> >> that there are not limitations at all (except for the two warnings in
>> >> >> the migration guide). Is pg_upgrade really up to the point where it can
>> >> >> fully replace pg_dump & pg_restore independent of the loaded (contrib)
>> >> >> or even third party modules(like postgis or custom datatypes etc)?

I think he is quite right to be concerned about these issues and if
the limitations in this area are not well-documented so that users can
easily be aware of them, then IMHO that is something we should
correct.

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


Re: pg_upgrade docs

От
Bruce Momjian
Дата:
Robert Haas wrote:
> On Mon, May 24, 2010 at 5:50 PM, Bruce Momjian <bruce@momjian.us> wrote:
> > What is your point?
> 
> My point is that I think Stefan has a good point when he says this:
> 
> >> >> >> hmm that seems better thanks, however I just noticed that we don't have
> >> >> >> a "general limitations" section. The way the docs are now done suggests
> >> >> >> that there are not limitations at all (except for the two warnings in
> >> >> >> the migration guide). Is pg_upgrade really up to the point where it can
> >> >> >> fully replace pg_dump & pg_restore independent of the loaded (contrib)
> >> >> >> or even third party modules(like postgis or custom datatypes etc)?
> 
> I think he is quite right to be concerned about these issues and if
> the limitations in this area are not well-documented so that users can
> easily be aware of them, then IMHO that is something we should
> correct.

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.

--  Bruce Momjian  <bruce@momjian.us>        http://momjian.us EnterpriseDB
http://enterprisedb.com


Re: pg_upgrade docs

От
Robert Haas
Дата:
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.

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


Re: pg_upgrade docs

От
Bruce Momjian
Дата:
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>