Thread: Added documentation about caching, reliability

I have added a section to the top of the WAL docs explaining caching and
reliability issues:

    http://candle.pha.pa.us/main/writings/pgsql/sgml/reliability.html

I also renamed the chapter "Reilability" rather than "WAL."

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

On Wed, Sep 28, 2005 at 02:26:24PM -0400, Bruce Momjian wrote:
> I have added a section to the top of the WAL docs explaining caching and
> reliability issues:
>
>     http://candle.pha.pa.us/main/writings/pgsql/sgml/reliability.html
>
> I also renamed the chapter "Reilability" rather than "WAL."

While you are re-titling the docs, maybe the sections on that chapter
could be titled "Benefits of Write-Ahead Log" instead of "Benefits of
WAL", etc.

--
Alvaro Herrera                  http://www.amazon.com/gp/registry/DXLWNGRJD34
"La realidad se compone de muchos sueños, todos ellos diferentes,
pero en cierto aspecto, parecidos..." (Yo, hablando de sueños eróticos)

Alvaro Herrera wrote:
> On Wed, Sep 28, 2005 at 02:26:24PM -0400, Bruce Momjian wrote:
> > I have added a section to the top of the WAL docs explaining caching and
> > reliability issues:
> >
> >     http://candle.pha.pa.us/main/writings/pgsql/sgml/reliability.html
> >
> > I also renamed the chapter "Reilability" rather than "WAL."
>
> While you are re-titling the docs, maybe the sections on that chapter
> could be titled "Benefits of Write-Ahead Log" instead of "Benefits of
> WAL", etc.

The chapter sections are:

    Table of Contents
    26.1. Write-Ahead Logging (WAL)
    26.2. Benefits of WAL
    26.3. WAL Configuration
    26.4. WAL Internals

Are you suggesting we spell out Write-Ahead Logging for all section
titles?

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

On Wed, Sep 28, 2005 at 10:08:02PM -0400, Bruce Momjian wrote:

> The chapter sections are:
>
>     Table of Contents
>     26.1. Write-Ahead Logging (WAL)
>     26.2. Benefits of WAL
>     26.3. WAL Configuration
>     26.4. WAL Internals
>
> Are you suggesting we spell out Write-Ahead Logging for all section
> titles?

Is it considered good style to use acronyms in titles?  I wouldn't do it.

Maybe it could be left as

     26.1. Write-Ahead Logging
     26.2. Benefits of Write-Ahead Logging
     26.3. WAL Configuration
     26.4. WAL Internals

because the former two talk about WAL in a general manner, while the
latter two are about our implementation.  I also wouldn't expand the
acronym in a title.

--
Alvaro Herrera       Valdivia, Chile   ICBM: S 39º 49' 17.7", W 73º 14' 26.8"
Thou shalt study thy libraries and strive not to reinvent them without
cause, that thy code may be short and readable and thy days pleasant
and productive. (7th Commandment for C Programmers)

Alvaro Herrera wrote:
> On Wed, Sep 28, 2005 at 10:08:02PM -0400, Bruce Momjian wrote:
>
> > The chapter sections are:
> >
> >     Table of Contents
> >     26.1. Write-Ahead Logging (WAL)
> >     26.2. Benefits of WAL
> >     26.3. WAL Configuration
> >     26.4. WAL Internals
> >
> > Are you suggesting we spell out Write-Ahead Logging for all section
> > titles?
>
> Is it considered good style to use acronyms in titles?  I wouldn't do it.
>
> Maybe it could be left as
>
>      26.1. Write-Ahead Logging
>      26.2. Benefits of Write-Ahead Logging

I modified 26.2 as you suggested.

>      26.3. WAL Configuration
>      26.4. WAL Internals
>
> because the former two talk about WAL in a general manner, while the
> latter two are about our implementation.  I also wouldn't expand the
> acronym in a title.

I think we do need to show the acronym in the title if use that acronym
in later titles.

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

Am Mittwoch, 28. September 2005 20:26 schrieb Bruce Momjian:
> I also renamed the chapter "Reilability" rather than "WAL."

Considering that the chapter is, in fact, all about WAL, I don't think this is
a good move.  Reliability is a concern that is not only addressed by the WAL
system.  Please change it back.

--
Peter Eisentraut
http://developer.postgresql.org/~petere/

Peter Eisentraut wrote:
> Am Mittwoch, 28. September 2005 20:26 schrieb Bruce Momjian:
> > I also renamed the chapter "Reilability" rather than "WAL."
>
> Considering that the chapter is, in fact, all about WAL, I don't think this is
> a good move.  Reliability is a concern that is not only addressed by the WAL
> system.  Please change it back.

Well, now the chapter is about WAL and reliability, so I thought
reliability hit both topics.  Also, maybe we should consider moving this
FAQ item into the docs:

    <H3><A name="3.7">3.7</A>) What computer hardware should I use?</H3>

    <P>Because PC hardware is mostly compatible, people tend to believe that
    all PC hardware is of equal quality.  It is not.  ECC RAM, SCSI, and
    quality motherboards are more reliable and have better performance than
    less expensive hardware.  PostgreSQL will run on almost any hardware,
    but if reliability and performance are important it is wise to
    research your hardware options thoroughly.  Our email lists can be used
    to discuss hardware options and tradeoffs.</P>

Anyway, I thought the previous chapter title, WAL, was weird because it
was hard to know why an administrator would care about WAL --- there was
no lead-in to the term.  This way, it is all under reliability, and can
add to it.

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

Bruce Momjian wrote:
> Well, now the chapter is about WAL and reliability, so I thought
> reliability hit both topics. Also, maybe we should consider moving
> this FAQ item into the docs:
>
>     <H3><A name="3.7">3.7</A>) What computer hardware should I
> use?</H3>

Hardware choice and configuration are important topics, but neither of
these are strongly tied to either WAL or Reliability.  Reliability is
the property (not a "feature") of a system to do what you meant for it
to do.  Certainly WAL contributes to that by increasing tolerance
against hardware failures, but it still seems to be a rather
far-fetched connection to pair these two.

I could see hardware issues being discussed in chapter 16, since we
already have operating system and kernel configuration there, and it's
the chapter a user will read when setting up a server system.

I was never all that happy with the WAL chapter, since, as you say, it
doesn't seem to be a first-class user-level feature.  I'd be happy to
integrate it into another chapter, but I'm not sure where.

--
Peter Eisentraut
http://developer.postgresql.org/~petere/

Peter Eisentraut wrote:
> Bruce Momjian wrote:
> > Well, now the chapter is about WAL and reliability, so I thought
> > reliability hit both topics. Also, maybe we should consider moving
> > this FAQ item into the docs:
> >
> >     <H3><A name="3.7">3.7</A>) What computer hardware should I
> > use?</H3>
>
> Hardware choice and configuration are important topics, but neither of
> these are strongly tied to either WAL or Reliability.  Reliability is
> the property (not a "feature") of a system to do what you meant for it
> to do.  Certainly WAL contributes to that by increasing tolerance
> against hardware failures, but it still seems to be a rather
> far-fetched connection to pair these two.
>
> I could see hardware issues being discussed in chapter 16, since we
> already have operating system and kernel configuration there, and it's
> the chapter a user will read when setting up a server system.
>
> I was never all that happy with the WAL chapter, since, as you say, it
> doesn't seem to be a first-class user-level feature.  I'd be happy to
> integrate it into another chapter, but I'm not sure where.

Sure, I am looking for suggestions.  My relabeling at least fixes that,
but feel free to move things around and relabel them.

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

Hey Bruce,

One grammar issue... otherwise great work.

they can be moved to another computer with similar hardware and all committed transaction will remain intact.

should be

they can be moved to another computer with similar hardware and all committed transactions will remain intact.




--
Respectfully,

Jonah H. Harris, Database Internals Architect
EnterpriseDB Corporation
http://www.enterprisedb.com/

IMHO, spelling out each one is redundant... the first one "Write-Ahead Logging (WAL)" seems to define WAL for use later in the text.





--
Respectfully,

Jonah H. Harris, Database Internals Architect
EnterpriseDB Corporation
http://www.enterprisedb.com/

Bruce wrote:
> > I was never all that happy with the WAL chapter, since, as you say,
it
> > doesn't seem to be a first-class user-level feature.  I'd be happy
to
> > integrate it into another chapter, but I'm not sure where.
>
> Sure, I am looking for suggestions.  My relabeling at least fixes
that,
> but feel free to move things around and relabel them.

FWIW, I agree with Peter.  We are supposed to be talking about Server
Administration, not architectural properties of the database
(reliability, performance, etc.).  The proposed move takes things more
off-topic.  In fact, IMO chapter 26 is already too fat and could provide
links to the 'benefits' and 'implementation details' portions (maybe
move to VII Internals?).

Merlin

Merlin Moncure wrote:
> Bruce wrote:
> > > I was never all that happy with the WAL chapter, since, as you say,
> it
> > > doesn't seem to be a first-class user-level feature.  I'd be happy
> to
> > > integrate it into another chapter, but I'm not sure where.
> >
> > Sure, I am looking for suggestions.  My relabeling at least fixes
> that,
> > but feel free to move things around and relabel them.
>
> FWIW, I agree with Peter.  We are supposed to be talking about Server
> Administration, not architectural properties of the database
> (reliability, performance, etc.).  The proposed move takes things more
> off-topic.  In fact, IMO chapter 26 is already too fat and could provide
> links to the 'benefits' and 'implementation details' portions (maybe
> move to VII Internals?).

I have no problem moving the WAL sections out of administration to
somewhere else, and linking to it from the Reliability section.  In
fact, my new added section is probably the only part of that chapter
that _does_ belong in the administration guide.

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

On Wed, 2005-09-28 at 14:26 -0400, Bruce Momjian wrote:
> I have added a section to the top of the WAL docs explaining caching and
> reliability issues:
>
>     http://candle.pha.pa.us/main/writings/pgsql/sgml/reliability.html
>
> I also renamed the chapter "Reilability" rather than "WAL."
>

I submitted a patch last week that builds further on Bruce's changes.
[Docs for PITR and full_page_writes interaction, 2 Oct]

The patch includes:

1. Minor rewording of the case that Bruce refers to "recovery" and I
have differentiated the cases of crash recovery and PITR. The
corresponding section of the backup chapter has also been changed to
include a short discussion on full_page_writes and WAL compression, with
a link back to the WAL section.

2. Merged the 1st and 2nd sects of Reliability into a single section.
The 1st section was only a single paragraph and so that improves
readability. I've freshened that section, since it has not been updated
since 7.1 and currently still reads as if WAL has just been released.

3. I've updated the section on WAL configuration with further WAL
related comments and clarifications. These relate to full_page_writes
and appropriate settings of wal_buffers to match.

Best Regards, Simon Riggs

Applied.  Thanks.

---------------------------------------------------------------------------

Simon Riggs wrote:
> On Wed, 2005-09-28 at 14:26 -0400, Bruce Momjian wrote:
> > I have added a section to the top of the WAL docs explaining caching and
> > reliability issues:
> >
> >     http://candle.pha.pa.us/main/writings/pgsql/sgml/reliability.html
> >
> > I also renamed the chapter "Reilability" rather than "WAL."
> >
>
> I submitted a patch last week that builds further on Bruce's changes.
> [Docs for PITR and full_page_writes interaction, 2 Oct]
>
> The patch includes:
>
> 1. Minor rewording of the case that Bruce refers to "recovery" and I
> have differentiated the cases of crash recovery and PITR. The
> corresponding section of the backup chapter has also been changed to
> include a short discussion on full_page_writes and WAL compression, with
> a link back to the WAL section.
>
> 2. Merged the 1st and 2nd sects of Reliability into a single section.
> The 1st section was only a single paragraph and so that improves
> readability. I've freshened that section, since it has not been updated
> since 7.1 and currently still reads as if WAL has just been released.
>
> 3. I've updated the section on WAL configuration with further WAL
> related comments and clarifications. These relate to full_page_writes
> and appropriate settings of wal_buffers to match.
>
> Best Regards, Simon Riggs
>
>
> ---------------------------(end of broadcast)---------------------------
> TIP 4: Have you searched our list archives?
>
>                http://archives.postgresql.org
>

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073