Thread

Backup docs

Magnus Hagander <magnus@hagander.net> — 2012-06-05T13:43:57Z

In reference to:
http://www.postgresql.org/docs/devel/static/continuous-archiving.html

I would like to see that page changed to list pg_basebackup as the
"default" way of doing base backups, and then list the "manual way" as
an option if you need more flexibility.

The reason being that for the majority of users that's going to be
flexible enough, and it's easier to use. And it doesn't hurt to show
that setting these things up really doesn't have to be that hard.

But since I'm definitely slightly biased on this, I'm not going to go
changing anything, or even write up suggested changing, until I can
get some agreement that making this change is good in the first place
;) Thus, please...

I'd also like to add "pg_basebackup -x" under standalone hot backups,
again as the main option.


I also wonder if we need a tl;dr; section of that whole page that just
goes through *what to do*, rather than why we do it? Of course not
removing the details, just showing the simplest case in, um, a simpler
way?

-- 
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/

Re: Backup docs

Simon Riggs <simon@2ndquadrant.com> — 2012-06-05T13:50:02Z

On 5 June 2012 14:43, Magnus Hagander <magnus@hagander.net> wrote:
> In reference to:
> http://www.postgresql.org/docs/devel/static/continuous-archiving.html
>
> I would like to see that page changed to list pg_basebackup as the
> "default" way of doing base backups, and then list the "manual way" as
> an option if you need more flexibility.

Agreed, but prefer phrasing old approach as "lower level API" or similar.


> The reason being that for the majority of users that's going to be
> flexible enough, and it's easier to use. And it doesn't hurt to show
> that setting these things up really doesn't have to be that hard.
>
> But since I'm definitely slightly biased on this, I'm not going to go
> changing anything, or even write up suggested changing, until I can
> get some agreement that making this change is good in the first place
> ;) Thus, please...
>
> I'd also like to add "pg_basebackup -x" under standalone hot backups,
> again as the main option.
>
>
> I also wonder if we need a tl;dr; section of that whole page that just
> goes through *what to do*, rather than why we do it? Of course not
> removing the details, just showing the simplest case in, um, a simpler
> way?
>
> --
>  Magnus Hagander
>  Me: http://www.hagander.net/
>  Work: http://www.redpill-linpro.com/
>
> --
> Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-hackers



-- 
 Simon Riggs                   http://www.2ndQuadrant.com/
 PostgreSQL Development, 24x7 Support, Training & Services

Re: Backup docs

Kevin Grittner <kevin.grittner@wicourts.gov> — 2012-06-05T14:48:25Z

Magnus Hagander <magnus@hagander.net> wrote:
> In reference to:
>
http://www.postgresql.org/docs/devel/static/continuous-archiving.html
> 
> I would like to see that page changed to list pg_basebackup as the
> "default" way of doing base backups, and then list the "manual
> way" as an option if you need more flexibility.

That sounds reasonable to me, as long as we don't lose information
on the alternatives.  I agree that we should *emphasize* the easiest
steps to set up and run.  The lower-level alternatives could even be
moved to a separate "tuning" section.  (Speaking of which, if we
have such a section I think it would make sense to describe the
rsync techniques which minimize network traffic in the docs.)

Basically, a simple, straightforward description of the easy way to
get going is desperately needed, with alternatives separated out a
bit, with some hint as to when it might be worth going to the extra
trouble..

-Kevin

Re: Backup docs

Dimitri Fontaine <dimitri@2ndquadrant.fr> — 2012-06-13T19:20:57Z

Magnus Hagander <magnus@hagander.net> writes:
> I would like to see that page changed to list pg_basebackup as the
> "default" way of doing base backups, and then list the "manual way" as
> an option if you need more flexibility.

+1

> I'd also like to add "pg_basebackup -x" under standalone hot backups,
> again as the main option.

+1

> I also wonder if we need a tl;dr; section of that whole page that just
> goes through *what to do*, rather than why we do it? Of course not
> removing the details, just showing the simplest case in, um, a simpler
> way?

+1

Come to think about it, that is the perfect occasion to have the
tutorial open itself up to dealing with admin tasks, right?

Please let's apply that documentation patch to 9.2 too.

Regards,
-- 
Dimitri Fontaine
http://2ndQuadrant.fr     PostgreSQL : Expertise, Formation et Support

Re: Backup docs

Robert Haas <robertmhaas@gmail.com> — 2012-06-14T14:37:08Z

On Wed, Jun 13, 2012 at 3:20 PM, Dimitri Fontaine
<dimitri@2ndquadrant.fr> wrote:
> Please let's apply that documentation patch to 9.2 too.

Agreed.

-- 
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

Re: Backup docs

Magnus Hagander <magnus@hagander.net> — 2012-06-15T09:02:10Z

On Thu, Jun 14, 2012 at 10:37 PM, Robert Haas <robertmhaas@gmail.com> wrote:
> On Wed, Jun 13, 2012 at 3:20 PM, Dimitri Fontaine
> <dimitri@2ndquadrant.fr> wrote:
>> Please let's apply that documentation patch to 9.2 too.
>
> Agreed.

Here's a patch that does the first two things. Does not attempt a
tl;tr section yet. Also adds a subheader for the notes about
compressing archive logs that seems to have been missing for a long
time - that's definitely valid for things that aren't standalone
backups, and is arguably a lot more *useful* in cases that aren't
standalone backups (since standalone backups won't have very much
log).

No removed text, just moved around and added some.

Unless there are objections to this one specifically, I'll go ahead
and commit it soon.

-- 
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/

Re: Backup docs

Dimitri Fontaine <dimitri@2ndquadrant.fr> — 2012-06-15T20:39:23Z

Magnus Hagander <magnus@hagander.net> writes:
> -    The procedure for making a base backup is relatively simple:
> +    The easiest way to perform a base backup is to use the
> +    <xref linkend="app-pgbasebackup"> tool. It can create
> +    a base backup either as regular files or as a tar archive. If more
> +    flexibility than <xref linkend="app-pgbasebackup"> can provide is
> +    required, you can also make a base backup using the low level API
> +    (see <xref linkend="backup-lowlevel-base-backup">).
> +   </para>

Good start.

> +   <para>
> +    It is not necessary to be concerned about the amount of time it takes
> +    to make a base backup. However, if you normally run the

Why not?

> +    file, and can ordinarily be ignored.) Once you have safely archived
> +    the file system backup and the WAL segment files used during the
> +    backup (as specified in the backup history file), all archived WAL
> +    segments with names numerically less are no longer needed to recover
> +    the file system backup and can be deleted. However, you should
> +    consider keeping several backup sets to be absolutely certain that
> +    you can recover your data.
> +   </para>

You're frighting off users when not detailing, I think. How to be
certain I can recover my data, is there a way that I can't when a backup
has been successfully made? How can I check?

Also I don't see mention of basebackup+wal files all in one with the -x
option, which I though would have to be addressed here?

Regards,
-- 
Dimitri Fontaine
http://2ndQuadrant.fr     PostgreSQL : Expertise, Formation et Support

Re: Backup docs

Magnus Hagander <magnus@hagander.net> — 2012-06-16T03:18:54Z

On Sat, Jun 16, 2012 at 4:39 AM, Dimitri Fontaine
<dimitri@2ndquadrant.fr> wrote:
> Magnus Hagander <magnus@hagander.net> writes:
>> -    The procedure for making a base backup is relatively simple:
>> +    The easiest way to perform a base backup is to use the
>> +    <xref linkend="app-pgbasebackup"> tool. It can create
>> +    a base backup either as regular files or as a tar archive. If more
>> +    flexibility than <xref linkend="app-pgbasebackup"> can provide is
>> +    required, you can also make a base backup using the low level API
>> +    (see <xref linkend="backup-lowlevel-base-backup">).
>> +   </para>
>
> Good start.
>
>> +   <para>
>> +    It is not necessary to be concerned about the amount of time it takes
>> +    to make a base backup. However, if you normally run the
>
> Why not?

This is copied from the old documentation. It used to say "It is not
necessary to be concerned about the amount of time elapsed between
pg_start_backup and the start of the actual backup, nor between the
end of the backup and pg_stop_backup".

And the whole idea was to simplify the text at the beginning ;)


>> +    file, and can ordinarily be ignored.) Once you have safely archived
>> +    the file system backup and the WAL segment files used during the
>> +    backup (as specified in the backup history file), all archived WAL
>> +    segments with names numerically less are no longer needed to recover
>> +    the file system backup and can be deleted. However, you should
>> +    consider keeping several backup sets to be absolutely certain that
>> +    you can recover your data.
>> +   </para>
>
> You're frighting off users when not detailing, I think. How to be

This is copied exactly from what it is today. I'm sure it can be
approved, but it's not the goal of this patch. Let's not let
perfection get in the way of improvement...

> Also I don't see mention of basebackup+wal files all in one with the -x
> option, which I though would have to be addressed here?

It does, it's under "standalone hot backups". The second to last part
of the patch.

-- 
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/

Re: Backup docs

Dimitri Fontaine <dimitri@2ndquadrant.fr> — 2012-06-16T16:13:37Z

Magnus Hagander <magnus@hagander.net> writes:
> This is copied from the old documentation. It used to say "It is not
> necessary to be concerned about the amount of time elapsed between
> pg_start_backup and the start of the actual backup, nor between the
> end of the backup and pg_stop_backup".
>
> And the whole idea was to simplify the text at the beginning ;)

Oh I see, not your patch to fix then. I just quick read the diff, as you
can see.

> This is copied exactly from what it is today. I'm sure it can be
> approved, but it's not the goal of this patch. Let's not let
> perfection get in the way of improvement...

Same.

> It does, it's under "standalone hot backups". The second to last part
> of the patch.

Perfect then.

Sorry for the noise, regards,
-- 
Dimitri Fontaine
http://2ndQuadrant.fr     PostgreSQL : Expertise, Formation et Support

Re: Backup docs

Magnus Hagander <magnus@hagander.net> — 2012-06-17T13:23:38Z

On Sun, Jun 17, 2012 at 12:13 AM, Dimitri Fontaine
<dimitri@2ndquadrant.fr> wrote:
> Magnus Hagander <magnus@hagander.net> writes:
>> This is copied from the old documentation. It used to say "It is not
>> necessary to be concerned about the amount of time elapsed between
>> pg_start_backup and the start of the actual backup, nor between the
>> end of the backup and pg_stop_backup".
>>
>> And the whole idea was to simplify the text at the beginning ;)
>
> Oh I see, not your patch to fix then. I just quick read the diff, as you
> can see.
>
>> This is copied exactly from what it is today. I'm sure it can be
>> approved, but it's not the goal of this patch. Let's not let
>> perfection get in the way of improvement...
>
> Same.
>
>> It does, it's under "standalone hot backups". The second to last part
>> of the patch.
>
> Perfect then.
>
> Sorry for the noise, regards,

np, thanks for checking. Applied.

-- 
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/