Thread: 14.4 If You Are Upgrading - Suggested Improvements
I've done a number of upgrades of postgres from one minor release to another, and unless I'm missing something, there's nothing anywhere in section 14 that provides documentation on how to do this.
Generally, it's as simple as:
configure
make
make install
pg_ctl stop [or equivalent, if stop scripts exist]
pg_ctl start -D <data directory> [or equivalent, if start scripts exist]
But it seems like it would be helpful for administrators to break down 14.4 into two sections:
14.4.1 - If You Are Upgrading a Minor Release
14.4.2 - If You Are Upgrading a Major Release (or a Release Requiring an initdb)
Just a suggestion. If this strikes others as a good idea, I'd be happy to draft something.
--
Thomas F. O'Connell
optimizing modern web applications
: for search engines, for usability, and for performance :
On Sat, 2007-01-20 at 16:48 -0600, Thomas F. O'Connell wrote: > I've done a number of upgrades of postgres from one minor release to > another, and unless I'm missing something, there's nothing anywhere in > section 14 that provides documentation on how to do this. > Just a suggestion. If this strikes others as a good idea, I'd be happy > to draft something. Makes sense to me. Would you mind submitting a patch against the SGML docs? -Neil
I'll see what I can do... :) -- Thomas F. O'Connell optimizing modern web applications : for search engines, for usability, and for performance : http://o.ptimized.com/ 615-260-0005 On Jan 26, 2007, at 11:42 AM, Neil Conway wrote: > On Sat, 2007-01-20 at 16:48 -0600, Thomas F. O'Connell wrote: >> I've done a number of upgrades of postgres from one minor release to >> another, and unless I'm missing something, there's nothing >> anywhere in >> section 14 that provides documentation on how to do this. > >> Just a suggestion. If this strikes others as a good idea, I'd be >> happy >> to draft something. > > Makes sense to me. Would you mind submitting a patch against the SGML > docs? > > -Neil
Neil Conway wrote: > On Sat, 2007-01-20 at 16:48 -0600, Thomas F. O'Connell wrote: > > I've done a number of upgrades of postgres from one minor release to > > another, and unless I'm missing something, there's nothing anywhere in > > section 14 that provides documentation on how to do this. > > > Just a suggestion. If this strikes others as a good idea, I'd be happy > > to draft something. > > Makes sense to me. Would you mind submitting a patch against the SGML > docs? I am already working on this and will commit in one hour. -- Bruce Momjian bruce@momjian.us EnterpriseDB http://www.enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
On Jan 26, 2007, at 4:05 PM, Bruce Momjian wrote: > Neil Conway wrote: >> On Sat, 2007-01-20 at 16:48 -0600, Thomas F. O'Connell wrote: >>> I've done a number of upgrades of postgres from one minor release to >>> another, and unless I'm missing something, there's nothing >>> anywhere in >>> section 14 that provides documentation on how to do this. >> >>> Just a suggestion. If this strikes others as a good idea, I'd be >>> happy >>> to draft something. >> >> Makes sense to me. Would you mind submitting a patch against the SGML >> docs? > > I am already working on this and will commit in one hour. Great. I'll just wait to see what Bruce does. My job just got easier... ;) -- Thomas F. O'Connell optimizing modern web applications : for search engines, for usability, and for performance : http://o.ptimized.com/ 615-260-0005
I have updated the installation documentation to clarify major vs. minor
releases; patch attached and applied. I always suspected we were
unclear on this. Comments welcome. I am not inclined to backpatch this
to 8.2.X because it might be too significant a change. URL of new text:
http://momjian.us/main/writings/pgsql/sgml/install-upgrading.html
---------------------------------------------------------------------------
Thomas F. O'Connell wrote:
> I've done a number of upgrades of postgres from one minor release to
> another, and unless I'm missing something, there's nothing anywhere
> in section 14 that provides documentation on how to do this.
>
> Generally, it's as simple as:
>
> configure
> make
> make install
> pg_ctl stop [or equivalent, if stop scripts exist]
> pg_ctl start -D <data directory> [or equivalent, if start scripts exist]
>
> But it seems like it would be helpful for administrators to break
> down 14.4 into two sections:
>
> 14.4.1 - If You Are Upgrading a Minor Release
> 14.4.2 - If You Are Upgrading a Major Release (or a Release Requiring
> an initdb)
>
> Just a suggestion. If this strikes others as a good idea, I'd be
> happy to draft something.
>
> --
> Thomas F. O'Connell
>
> optimizing modern web applications
> : for search engines, for usability, and for performance :
>
> http://o.ptimized.com/
> 615-260-0005
>
--
Bruce Momjian bruce@momjian.us
EnterpriseDB http://www.enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +
Index: doc/src/sgml/installation.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v
retrieving revision 1.275
diff -c -c -r1.275 installation.sgml
*** doc/src/sgml/installation.sgml 25 Jan 2007 23:34:28 -0000 1.275
--- doc/src/sgml/installation.sgml 26 Jan 2007 22:51:23 -0000
***************
*** 367,402 ****
]]>
<sect1 id="install-upgrading">
! <title>If You Are Upgrading</title>
<indexterm zone="install-upgrading">
<primary>upgrading</primary>
</indexterm>
<para>
! The internal data storage format changes with new releases of
! <productname>PostgreSQL</>. Therefore, if you are upgrading an
! existing installation that does not have a version number
<quote>&majorversion;.x</quote>, you must back up and restore your
! data as shown here. These instructions assume that your existing
! installation is under the <filename>/usr/local/pgsql</> directory,
! and that the data area is in <filename>/usr/local/pgsql/data</>.
! Substitute your paths appropriately.
</para>
<procedure>
<step>
<para>
! Make sure that your database is not updated during or after the
! backup. This does not affect the integrity of the backup, but the
! changed data would of course not be included. If necessary, edit
! the permissions in the file
! <filename>/usr/local/pgsql/data/pg_hba.conf</> (or equivalent) to
! disallow access from everyone except you.
</para>
- </step>
- <step>
<para>
<indexterm>
<primary>pg_dumpall</primary>
--- 367,405 ----
]]>
<sect1 id="install-upgrading">
! <title>Upgrading</title>
<indexterm zone="install-upgrading">
<primary>upgrading</primary>
</indexterm>
<para>
! These instructions assume that your existing installation is under the
! <filename>/usr/local/pgsql</> directory, and that the data area is in
! <filename>/usr/local/pgsql/data</>. Substitute your paths
! appropriately.
! </para>
!
! <para>
! The internal data storage format typically changes in every major
! release of <productname>PostgreSQL</>. Therefore, if you are upgrading
! an existing installation that does not have a version number of
<quote>&majorversion;.x</quote>, you must back up and restore your
! data. If you are upgrading from the same major version, the new version
! can use your current data files, so a backup and restore is optional.
! If you wish to avoid the backup/restore, merely skip those steps below.
</para>
<procedure>
<step>
<para>
! If making a backup, make sure that your database is being updated.
! This does not affect the integrity of the backup, but the changed
! data would of course not be included. If necessary, edit the
! permissions in the file <filename>/usr/local/pgsql/data/pg_hba.conf</>
! (or equivalent) to disallow access from everyone except you.
</para>
<para>
<indexterm>
<primary>pg_dumpall</primary>
***************
*** 429,437 ****
<step>
<para>
! If you are installing the new version at the same location as the
! old one then shut down the old server, at the latest before you
! install the new files:
<screen>
<userinput>pg_ctl stop</>
</screen>
--- 432,438 ----
<step>
<para>
! Shut down the old server:
<screen>
<userinput>pg_ctl stop</>
</screen>
***************
*** 448,485 ****
<step>
<para>
! If you are installing in the same place as the old version then
! it is also a good idea to move the old installation out of the
! way, in case you have trouble and need to revert to it.
! Use a command like this:
! <screen>
<userinput>mv /usr/local/pgsql /usr/local/pgsql.old</>
</screen>
</para>
</step>
- </procedure>
! <para>
! After you have installed <productname>PostgreSQL</> &version;, create a new database
! directory and start the new server. Remember that you must execute
! these commands while logged in to the special database user account
! (which you already have if you are upgrading).
<programlisting>
<userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</>
<userinput>/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data</>
</programlisting>
! Finally, restore your data with
<screen>
<userinput>/usr/local/pgsql/bin/psql -d postgres -f <replaceable>outputfile</></userinput>
</screen>
! using the <emphasis>new</> <application>psql</>.
! </para>
<para>
Further discussion appears in
<![%standalone-include[the documentation,]]>
<![%standalone-ignore[<xref linkend="migration">,]]>
! which you are encouraged to read in any case.
</para>
</sect1>
--- 449,511 ----
<step>
<para>
! If restoring from backup, rename or delete the old installation
! directory. It is a good idea to rename the directory, rather than
! delete it, in case you have trouble and need to revert to it. Keep
! in mind the directory might consume significant disk space. To rename
! the directory, use a command like this:
! <screen>
<userinput>mv /usr/local/pgsql /usr/local/pgsql.old</>
</screen>
</para>
</step>
! <step>
! <para>
! Install the new version of <productname>PostgreSQL</productname> as
! outlined in <![%standalone-include[the next section.]]>
! <![%standalone-ignore[<xref linkend="install-procedure">.]]>
! </para>
! </step>
!
! <step>
! <para>
! Create a new database cluster if needed. Remember that you must
! execute these commands while logged in to the special database user
! account (which you already have if you are upgrading).
<programlisting>
<userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</>
+ </programlisting>
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Start the database server, again from the special database user
+ account:
+ <programlisting>
<userinput>/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data</>
</programlisting>
! </para>
! </step>
!
! <step>
! <para>
! Finally, restore your data from backup with
<screen>
<userinput>/usr/local/pgsql/bin/psql -d postgres -f <replaceable>outputfile</></userinput>
</screen>
! using the <emphasis>new</> <application>psql</>.
! </para>
! </step>
! </procedure>
<para>
Further discussion appears in
<![%standalone-include[the documentation,]]>
<![%standalone-ignore[<xref linkend="migration">,]]>
! including instructions on how the previous installation can continue
! running while the new installation is installed.
</para>
</sect1>
Bruce Momjian wrote: > I have updated the installation documentation to clarify major vs. > minor releases; patch attached and applied. I always suspected we > were unclear on this. Comments welcome. I am not inclined to > backpatch this to 8.2.X because it might be too significant a change. > URL of new text: I think this is too weak: """ If you are upgrading from the same major version, the new version can use your current data files, so a backup and restore is optional. If you wish to avoid the backup/restore, merely skip those steps below. """ You write the backup/restore for minor versions is "optional", but when would you make use of this option and why would users "wish" or not wish to skip the steps? The fact is, the backup and restore is not optional, it is just unnecessary, and there is no question about whether to skip the rest or not. -- Peter Eisentraut http://developer.postgresql.org/~petere/
Peter Eisentraut wrote: > Bruce Momjian wrote: > > I have updated the installation documentation to clarify major vs. > > minor releases; patch attached and applied. I always suspected we > > were unclear on this. Comments welcome. I am not inclined to > > backpatch this to 8.2.X because it might be too significant a change. > > URL of new text: > > I think this is too weak: > > """ > If you are upgrading from the same major version, the new version can > use your current data files, so a backup and restore is optional. If > you wish to avoid the backup/restore, merely skip those steps below. > """ > > You write the backup/restore for minor versions is "optional", but when > would you make use of this option and why would users "wish" or not > wish to skip the steps? The fact is, the backup and restore is not > optional, it is just unnecessary, and there is no question about > whether to skip the rest or not. OK, I was unsure if we wanted to encourage minor release folks to still do a backup in case there is a problem. Updated text: The internal data storage format typically changes in every major release of <productname>PostgreSQL</>. Therefore, if you are upgrading an existing installation that does not have a version number of <quote>&majorversion;.x</quote>, you must back up and restore your data. If you are upgrading from the same major version, the new version can use your current data files so you should skip the backup and restore steps below because they are unnecessary. Thanks. -- Bruce Momjian bruce@momjian.us EnterpriseDB http://www.enterprisedb.com + If your life is a hard drive, Christ can be your backup. + Index: doc/src/sgml/installation.sgml =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v retrieving revision 1.276 diff -c -c -r1.276 installation.sgml *** doc/src/sgml/installation.sgml 26 Jan 2007 22:52:50 -0000 1.276 --- doc/src/sgml/installation.sgml 27 Jan 2007 01:23:43 -0000 *************** *** 386,393 **** an existing installation that does not have a version number of <quote>&majorversion;.x</quote>, you must back up and restore your data. If you are upgrading from the same major version, the new version ! can use your current data files, so a backup and restore is optional. ! If you wish to avoid the backup/restore, merely skip those steps below. </para> <procedure> --- 386,393 ---- an existing installation that does not have a version number of <quote>&majorversion;.x</quote>, you must back up and restore your data. If you are upgrading from the same major version, the new version ! can use your current data files so you should skip the backup and ! restore steps below. </para> <procedure>
Bruce Momjian wrote: > Updated text: > > The internal data storage format typically changes in every major > release of <productname>PostgreSQL</>. Therefore, if you are upgrading > an existing installation that does not have a version number of > <quote>&majorversion;.x</quote>, you must back up and restore your > data. If you are upgrading from the same major version, the new version > can use your current data files so you should skip the backup and > restore steps below because they are unnecessary. That's better, but I'd suggest using &majorversion;.x in the last sentence as well, instead of "the same major version", because some people does not yet grasp that we refer to "major" as the first two digits, instead thinking that all "7" versions are compatible, and all "8", etc. -- Alvaro Herrera http://www.CommandPrompt.com/ The PostgreSQL Company - Command Prompt, Inc.
Done, patch attached. --------------------------------------------------------------------------- Alvaro Herrera wrote: > Bruce Momjian wrote: > > > Updated text: > > > > The internal data storage format typically changes in every major > > release of <productname>PostgreSQL</>. Therefore, if you are upgrading > > an existing installation that does not have a version number of > > <quote>&majorversion;.x</quote>, you must back up and restore your > > data. If you are upgrading from the same major version, the new version > > can use your current data files so you should skip the backup and > > restore steps below because they are unnecessary. > > That's better, but I'd suggest using &majorversion;.x in the last > sentence as well, instead of "the same major version", because some > people does not yet grasp that we refer to "major" as the first two > digits, instead thinking that all "7" versions are compatible, and all > "8", etc. > > -- > Alvaro Herrera http://www.CommandPrompt.com/ > The PostgreSQL Company - Command Prompt, Inc. -- Bruce Momjian bruce@momjian.us EnterpriseDB http://www.enterprisedb.com + If your life is a hard drive, Christ can be your backup. + Index: doc/src/sgml/installation.sgml =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v retrieving revision 1.277 diff -c -c -r1.277 installation.sgml *** doc/src/sgml/installation.sgml 27 Jan 2007 01:27:36 -0000 1.277 --- doc/src/sgml/installation.sgml 29 Jan 2007 21:48:05 -0000 *************** *** 385,393 **** release of <productname>PostgreSQL</>. Therefore, if you are upgrading an existing installation that does not have a version number of <quote>&majorversion;.x</quote>, you must back up and restore your ! data. If you are upgrading from the same major version, the new version ! can use your current data files so you should skip the backup and ! restore steps below because they are unnecessary. </para> <procedure> --- 385,394 ---- release of <productname>PostgreSQL</>. Therefore, if you are upgrading an existing installation that does not have a version number of <quote>&majorversion;.x</quote>, you must back up and restore your ! data. If you are upgrading from <productname>PostgreSQL</> ! <quote>&majorversion;.x</quote>, the new version can use your current ! data files so you should skip the backup and restore steps below because ! they are unnecessary. </para> <procedure>