INSTALL/install.sgml file

Bruce Momjian <pgman@candle.pha.pa.us> writes:

In looking at the INSTALL/install.sgml files, I see that there are no
instructions for removing the /data directory after the backup, so
initdb will succeed. Should that be suggested after the backup is
performed? If not, initdb will fail. Also, I have to add something to
the initdb step to tell 7.* users they don't need initdb.

What? It says "move the old directories out of the way" at the bottom
of step 6.

Possibly that should be promoted into a whole separate step, rather than
being just an afterthought to killing the postmaster.

This step and step 11 should also mention pg_upgrade as a possible
alternative to doing a full reload. (But encourage people to make
the backup anyway ;-).)

regards, tom lane

Bruce Momjian <pgman@candle.pha.pa.us> writes:

In looking at the INSTALL/install.sgml files, I see that there are no
instructions for removing the /data directory after the backup, so
initdb will succeed. Should that be suggested after the backup is
performed? If not, initdb will fail. Also, I have to add something to
the initdb step to tell 7.* users they don't need initdb.

What? It says "move the old directories out of the way" at the bottom
of step 6.

Oh, I see that now. The trick was that people upgrading from 7.0 or
7.0.1 do not need to do pg_dumpall, nor move the old directory out of
the way, nor do an initdb, nor reload from pg_dumpall.

I put a note about who should run pg_dumpall (6.5.* or earlier), and
then later I mention that "If you did pg_dumpall..." move the old
directory out of the way, do initdb, and reload. Seems it is OK now.
Thanks.

Possibly that should be promoted into a whole separate step, rather than
being just an afterthought to killing the postmaster.

This step and step 11 should also mention pg_upgrade as a possible
alternative to doing a full reload. (But encourage people to make
the backup anyway ;-).)

I got that into step 5:

Rather than using pg_dumpall, pg_upgrade can often be used.

-- 
  Bruce Momjian                        |  http://www.op.net/~candle
  pgman@candle.pha.pa.us               |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

Bruce Momjian writes:

This step and step 11 should also mention pg_upgrade as a possible
alternative to doing a full reload. (But encourage people to make
the backup anyway ;-).)

I got that into step 5:

Rather than using pg_dumpall, pg_upgrade can often be used.

I think the installation instructions should say "If you are upgrading
from an existing installation, read the Administrator's Guide for backing
and restoring your data." The said guide contains a chapter discussing
these issues in detail (or at least it contains a chapter on it and we
should add some detail :). This sort of thing can't be replaced by three
sentences.

Just the other day I griped about the fact that the installation
instructions are in fact a chapter of the administrator's guide, which
breaks the internal and external organization and the flow of information
of both the installation instructions and the administrator's guide.

Can anyone see that concern?

--
Peter Eisentraut Sernanders v�g 10:115
peter_e@gmx.net 75262 Uppsala
http://yi.org/peter-e/ Sweden

I think the installation instructions should say "If you are upgrading
from an existing installation, read the Administrator's Guide for backing
and restoring your data." The said guide contains a chapter discussing
these issues in detail (or at least it contains a chapter on it and we
should add some detail :). This sort of thing can't be replaced by three
sentences.

Just the other day I griped about the fact that the installation
instructions are in fact a chapter of the administrator's guide, which
breaks the internal and external organization and the flow of information
of both the installation instructions and the administrator's guide.

Can we refer people to that section for more information?

-- 
  Bruce Momjian                        |  http://www.op.net/~candle
  pgman@candle.pha.pa.us               |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

Bruce Momjian writes:

Just the other day I griped about the fact that the installation
instructions are in fact a chapter of the administrator's guide, which
breaks the internal and external organization and the flow of information
of both the installation instructions and the administrator's guide.

Can we refer people to that section for more information?

We can refer people, but how? Do you write "please read more about this in
the Administrator's Guide"? Then somebody who's reading the installation
instructions as part of the administrator's guide will think "Well, duh,
thanks a lot". Or you make a proper DocBook hyperlink which comes out
something like "read more about this in `Backing up and Restoring'". Then
somebody who reads the flat text file will say "Gee, and where exactly is
that?". Schizophrenia Bad.

IMHO, there's really a line between:
* Installation Guide: how to get from sources to binaries (roughly)
* Administration Guide: how to get from binaries to running system
* Users (and other) Guide: how to make use of the running system

--
Peter Eisentraut Sernanders v�g 10:115
peter_e@gmx.net 75262 Uppsala
http://yi.org/peter-e/ Sweden

We can refer people, but how? Do you write "please read more about this in
the Administrator's Guide"? Then somebody who's reading the installation
instructions as part of the administrator's guide will think "Well, duh,
thanks a lot". Or you make a proper DocBook hyperlink which comes out
something like "read more about this in `Backing up and Restoring'". Then
somebody who reads the flat text file will say "Gee, and where exactly is
that?". Schizophrenia Bad.

IMHO, there's really a line between:
* Installation Guide: how to get from sources to binaries (roughly)
* Administration Guide: how to get from binaries to running system
* Users (and other) Guide: how to make use of the running system

Good questions. No good answers I can think of.

-- 
  Bruce Momjian                        |  http://www.op.net/~candle
  pgman@candle.pha.pa.us               |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026