Re: pg_dumpall reccomendation in release notes

On Tue, Feb 25, 2014 at 05:05:09PM -0800, Josh Berkus wrote:
> On 02/25/2014 04:42 PM, Bruce Momjian wrote:
> > On Tue, Feb 25, 2014 at 06:41:26PM -0500, Tom Lane wrote:
> >> I'm not sure what "many limitations" you think pg_dumpall has that pg_dump
> >> doesn't.
> >>
> >> I do think that it might be time to reword this to recommend pg_upgrade
> >> first, though.  ISTM that the current wording dates from when pg_upgrade
> >> could charitably be described as experimental.
> >
> > Wow, so pg_upgrade takes the lead!  And from Tom too!  :-)
> >
> > I agree with Tom that mentioning pg_dump/restore is going to lead to
> > global object data loss, and throwing the users to a URL with no
> > explanation isn't going to help either.  What we could do is to
> > restructure the existing text and add a link to the upgrade URL for more
> > details.
>
> What I was suggesting was something like:
>
> "Users upgrading from earlier versions will need to go through the
> entire upgrade procedure, as described on our upgrade page: <link>"
>
> The problem is that anything we say about "how to upgrade" in one short
> sentence is going to confuse some people.  BTW, the reason I got that
> question about pg_dump was that 9.2's release notes say "pg_dump" and
> 9.3's say "pg_dumpall", causing users to think there's been some kind of
> change.
>
> Of course, this means I need to fix the upgrade page, and I need to
> write backported versions of that fix for at least 9.1 and 9.2.

I have developed the attached patch to address the issues raised above:

o  non-text output of pg_dump is mentioned
o  mentions of using OID for keys is removed
o  the necessity of pg_dumpall --globals-only is mentioned
o  using pg_dump parallel mode rather than pg_dumpall for upgrades is mentioned
o  pg_upgrade is mentioned more prominently for upgrades
o  replication upgrades are in their own section

I don't think we want to mention pg_upgrade as the _primary_
major-version upgrade method.  While the pg_dump upgrade section is
long, it is mostly about starting/stoping the server, moving
directories, etc, the same things you have to do for pg_upgrade, so I
just mentioned that int the pg_upgrade section.  Other ideas?

I plan to apply this to head and 9.4.


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

  + Everyone has their own god. +