pg_upgrade docs
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
Attachments:
pgupgrade-sgml.patchtext/x-patch; name=pgupgrade-sgml.patchDownload
Index: doc/src/sgml/pgupgrade.sgml
===================================================================
RCS file: /projects/cvsroot/pgsql/doc/src/sgml/pgupgrade.sgml,v
retrieving revision 1.5
diff -u -r1.5 pgupgrade.sgml
--- doc/src/sgml/pgupgrade.sgml 18 May 2010 15:41:36 -0000 1.5
+++ doc/src/sgml/pgupgrade.sgml 19 May 2010 19:33:07 -0000
@@ -9,10 +9,10 @@
<para>
<application>pg_upgrade</> (formerly called pg_migrator) allows data
- stored in Postgres data files to be migrated to a later Postgres
+ stored in <productname>PostgreSQL</> data files to be migrated to a later <productname>PostgreSQL</>
major version without the data dump/reload typically required for
major version upgrades, e.g. from 8.4.7 to the current major release
- of Postgres. It is not required for minor version upgrades, e.g.
+ of <productname>PostgreSQL</>. It is not required for minor version upgrades, e.g
9.0.1 -> 9.0.4.
</para>
@@ -21,7 +21,7 @@
<para>
pg_upgrade supports upgrades from 8.3.X and later to the current
- major release of Postgres, including snapshot and alpha releases.
+ major release of <productname>PostgreSQL</>, including snapshot and alpha releases.
</para>
@@ -37,17 +37,17 @@
</para>
<para>
- If you are using a version-specific PostgreSQL install directory, e.g.
+ If you are using a version-specific installation directory, e.g.
/opt/PostgreSQL/8.4, you do not need to move the old cluster. The
one-click installers all use version-specific install directories.
</para>
<para>
- If your PostgreSQL install directory is not version-specific, e.g.
- /usr/local/pgsql, it is necessary to move the current Postgres install
- directory so it does not interfere with the new Postgres installation.
- Once the current Postgres server is shut down, it is safe to rename the
- Postgres install directory; assuming the old directory is
+ If your installation directory is not version-specific, e.g.
+ /usr/local/pgsql, it is necessary to move the current PostgreSQL install
+ directory so it does not interfere with the new <productname>PostgreSQL</> installation.
+ Once the current <productname>PostgreSQL</> server is shut down, it is safe to rename the
+ PostgreSQL install directory; assuming the old directory is
/usr/local/pgsql, you can do:
<programlisting>
@@ -58,26 +58,26 @@
<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>
</listitem>
<listitem>
<para>
- For PostgreSQL source installs, build the new PostgreSQL version
+ For source installs, build the new version
</para>
<para>
- Build the new Postgres source with configure flags that are compatible
- with the old cluster. pg_upgrade will check pg_controldata to make
+ Build the new PostgreSQL source with configure flags that are compatible
+ with the old cluster. <application>pg_upgrade</> will check <command>pg_controldata</> to make
sure all settings are compatible before starting the upgrade.
</para>
</listitem>
<listitem>
<para>
- Install the new Postgres binaries
+ Install the new PostgreSQL binaries
</para>
<para>
@@ -109,8 +109,10 @@
</para>
<para>
- Initialize the new cluster using initdb. Again, use compatible initdb
- flags that match the old cluster (pg_upgrade will check that too.) Many
+ Initialize the new cluster <xref
+ linkend="app-initdb">,<indexterm><primary>initdb</></>.
+ Again, use compatible initdb
+ flags that match the old cluster. Many
prebuilt installers do this step automatically. There is no need to
start the new cluster.
</para>
@@ -139,8 +141,8 @@
pg_upgrade will connect to the old and new servers several times,
so you might want to set authentication to <literal>trust</> in
<filename>pg_hba.conf</>, or if using <literal>md5</> authentication,
- use a <filename>pgpass</> file to avoid being prompted repeatedly
- for a password.
+ use a <filename>~/.pgpass</> file (see <xref linkend="libpq-pgpass">)
+ to avoid being prompted repeatedly for a password.
</para>
</listitem>
@@ -167,20 +169,20 @@
or
<programlisting>
-NET STOP pgsql-8.3 (different service name)
+NET STOP pgsql-8.3 (<productname>PostgreSQL</> 8.3 and older used a different service name)
</programlisting>
</para>
</listitem>
<listitem>
<para>
- Run pg_upgrade
+ Run <application>pg_upgrade</>
</para>
<para>
- Always run the pg_upgrade binary in the new server, not the old one.
- pg_upgrade requires the specification of the old and new cluster's
- PGDATA and executable (/bin) directories. You can also specify separate
+ Always run the <application>pg_upgrade</> binary in the new server, not the old one.
+ <application>pg_upgrade</> requires the specification of the old and new cluster's
+ <varname>PGDATA</> and executable (/bin) directories. You can also specify separate
user and port values, and whether you want the data linked instead of
copied (the default). If you use linking, the migration will be much
faster (no data copying), but you will no longer be able to access your
@@ -197,7 +199,7 @@
SET PATH=%PATH%;C:\Program Files\PostgreSQL\9.0\bin;
</programlisting>
- and then run pg_upgrade with quoted directories, e.g.:
+ and then run <application>pg_upgrade</> with quoted directories, e.g.:
<programlisting>
pg_upgrade.exe
@@ -259,25 +261,28 @@
The scripts can be run in any order and can be deleted once they have
been run.
</para>
-
+
+ <caution>
<para>
In general it is unsafe to access tables referenced in rebuild scripts
until the rebuild scripts have run to completion; doing so could yield
incorrect results or poor performance. Tables not referenced in rebuild
scripts can be accessed immediately.
</para>
+ </caution>
</listitem>
<listitem>
<para>
Statistics
</para>
-
+ <caution>
<para>
Because optimizer statistics are not transferred by pg_upgrade, you will
be instructed to run a command to regenerate that information at the end
of the migration.
</para>
+ </caution>
</listitem>
<listitem>
@@ -334,7 +339,7 @@
</sect2>
<sect2>
- <title>Limitations In Migrating <emphasis>from</> PostgreSQL 8.3</title>
+ <title>Limitations in migrating <emphasis>from</> PostgreSQL 8.3</title>
<para>
@@ -387,7 +392,7 @@
<para>
Also, the default datetime storage format changed to integer after
- Postgres 8.3. pg_upgrade will check that the datetime storage format
+ <productname>PostgreSQL</> 8.3. pg_upgrade will check that the datetime storage format
used by the old and new clusters match. Make sure your new cluster is
built with the configure flag <option>--disable-integer-datetimes</>.
</para>
@@ -401,7 +406,7 @@
</para>
<para>
- All failure, rebuild, and reindex cases will be reported by pg_upgrade
+ All failure, rebuild, and reindex cases will be reported by <application>pg_upgrade</>
if they affect your installation; post-migration scripts to rebuild
tables and indexes will be automatically generated.
</para>
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>--
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
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
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
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
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
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 not work 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 type
You must drop any such columns and migrate them manually.
You can see the full documentation here:
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
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
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
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
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
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
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
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
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
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
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
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
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
Attachments:
/rtmp/difftext/x-diffDownload
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>