DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=beta;
	h=received:message-id:date:from:to:subject:cc:in-reply-to:mime-version:content-type:content-transfer-encoding:content-disposition:references;
	b=cV35wY1NXSm2E5q4Ou+gmyoC5GitJww4gGXeYkI+KC4653LTnSzncuUSdxvBeGO/4EEzUCsmsO3pXn1Kq5nZIWt31bXjLI/Zx2Tgky5ZQ9cGCIIGM64ptK58WlO3WtMeQu7sxXEjE/8cBafpDJOSjclpVFVdqyP2MmLGOVd6cB0=
Message-ID: <dcc563d10709130729oc290afbi89b31aa4c206679f@mail.gmail.com>
Date: Thu, 13 Sep 2007 09:29:34 -0500
From: "Scott Marlowe" <scott.marlowe@gmail.com>
To: "Greg Smith" <gsmith@gregsmith.com>
Subject: Re: [Again] Postgres performance problem
Cc: pgsql-performance@postgresql.org
In-Reply-To: <Pine.GSO.4.64.0709130130390.8547@westnet.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
Content-Disposition: inline
References: <46E636CB.8080008@rentalia.com>
	<43393.192.121.104.48.1189495883.squirrel@zigo.dhs.org>
	<46E64891.9080005@rentalia.com> <20070911225242.GG38801@decibel.org>
	<46E79865.906@rentalia.com>
	<dcc563d10709121128o1e5883a9n96b1f9ed74901be9@mail.gmail.com>
	<Pine.GSO.4.64.0709130130390.8547@westnet.com>

On 9/13/07, Greg Smith <gsmith@gregsmith.com> wrote:
> On Wed, 12 Sep 2007, Scott Marlowe wrote:
>
> > I'm getting more and more motivated to rewrite the vacuum docs.  I think
> > a rewrite from the ground up might be best...  I keep seeing people
> > doing vacuum full on this list and I'm thinking it's as much because of
> > the way the docs represent vacuum full as anything.
>
> I agree you shouldn't start thinking in terms of how to fix the existing
> documentation.  I'd suggest instead writing a tutorial leading someone
> through what they need to know about their tables first and then going
> into how vacuum works based on that data.

I think both things are needed actually.  The current docs were
started back when pg 7.2 roamed the land, and they've been updated a
bit at a time.  The technical definitions of vacuum,  vacuum full,
analyze etc all show a bit too much history from back in the day, and
are confusing.  so, I think that 1: vacuum and analyze should have
their own sections.  analyze used to be a subcommand of vacuum but it
no longer is, but the docs still pretty much tie them together.  2:
The definition for vacuum full needs to include a caveat that vacuum
full should be considered more of a recovery operation than a way to
simply get back some space on your hard drives.

Which leads me to thinking that we then need a simple tutorial on
vacuuming to include the free space map, vacuum, vacuum analyze,
vacuum full, and the autovacuum daemon.  We can throw analyze in there
somewhere too, I just don't want it to seem like it's still married to
vacuum.

> As an example, people throw around terms like "index bloat" and "dead
> tuples" when talking about vacuuming.  The tutorial I'd like to see
> somebody write would start by explaining those terms and showing how to
> measure them--preferably with a good and bad example to contrast.

I agree.  I might rearrange it a bit but that's the way I'm looking at it too.

> The way
> these terms are thrown around right now, I don't expect newcomers to
> understand either the documentation or the advice people are giving them;
> I think it's shooting over their heads and what's needed are some
> walkthroughs.  Another example I'd like to see thrown in there is what it
> looks like when you don't have enough FSM slots.

OK.  Got something to start with.  I'm thinking I might work on a
vacuum tutorial first, then the tech docs...