Обсуждение: backup.sgml WIP (patch included)

Hey,

I originally sent this to -hackers but Bruce kindly pointed me this way.
Attached is my rework of the backup.sgml. I have only worked on the SQL
DUMP and related sections. I left archiving etc... alone. I also didn't
do much with pg_dumpall. I focused on adding up to date information and
removing conversational tone.

The rest is pretty obvious. I am interested feedback before I continue.

Yes, I added -C to the basic pg_dump command. Without it, a newbie will
get an error on restore. I also removed all redirection etc... I know it
is the unix/linux way but flags are what the normies are going to
understand.

Thanks!

JD
--
Command Prompt, Inc. - http://www.commandprompt.com/  503-667-4564
PostgreSQL Centered full stack support, consulting and development.
Announcing "I'm offended" is basically telling the world you can't
control your own emotions, so everyone else should do it for you.

Hello,

Here is an updated patch with current work:

1. Merged multiple note tags into paragraphs per PeterE's feedback on
the man page.

2. Added text explaining the examples

3. Added example of the single transaction/on error stop

A change I did not make per Craig Ringer (and plenty of other people
through the years):

"Instead we should be advising people to use pg_dump -Fc and pg_restore
as their default and primary method of dumping a database. It is rarely
desirable to use text dumps and if pg_dump was being written now, it'd
surely default to -Fc ."

I think we really need to think about this. I have argued for this
change many times in the past and if I am honest, too many people that
have nothing to do with PostgreSQL in the real world keep telling me and
others we are wrong.

The plain text format should be available of course but it should not be
what we suggest or even talk about as the first option.

As before this only touches the SQL DUMP portion of the docs.

Sincerely,

JD


--
Command Prompt, Inc. - http://www.commandprompt.com/  503-667-4564
PostgreSQL Centered full stack support, consulting and development.
Announcing "I'm offended" is basically telling the world you can't
control your own emotions, so everyone else should do it for you.

Joshua D. Drake wrote:

> A change I did not make per Craig Ringer (and plenty of other people through
> the years):
>
> "Instead we should be advising people to use pg_dump -Fc and pg_restore as
> their default and primary method of dumping a database. It is rarely
> desirable to use text dumps and if pg_dump was being written now, it'd
> surely default to -Fc ."
>
> I think we really need to think about this.

Yeah, this makes sense, except that if you want parallel dump (and many
people do) you need -Fd.

--
Álvaro Herrera                http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

On 06/02/2015 01:04 PM, Alvaro Herrera wrote:
>
> Joshua D. Drake wrote:
>
>> A change I did not make per Craig Ringer (and plenty of other people through
>> the years):
>>
>> "Instead we should be advising people to use pg_dump -Fc and pg_restore as
>> their default and primary method of dumping a database. It is rarely
>> desirable to use text dumps and if pg_dump was being written now, it'd
>> surely default to -Fc ."
>>
>> I think we really need to think about this.
>
> Yeah, this makes sense, except that if you want parallel dump (and many
> people do) you need -Fd.
>

Oh agreed there. I do say in the current patch:

The pg_dump application provides other formats. The most notable are the
use of -F c or -F d. The use of the custom format (-F c) is an excellent
option for smaller databases when you need fine grained control of the
objects you chose to restore. The use of the directory format (-F d)
allows for parallel connection based backups. If you are performing a
backup with many objects and using pg_dump then the directory format
will be the most efficient. This option also allows for fine grained
control of the objects you chose to restore. Further, the use of the
custom or directory pg_dump formats requires the use of pg_restore and
will not work with psql. There is more information on using pg_restore
in section Section 24.1.3.

JD

--
Command Prompt, Inc. - http://www.commandprompt.com/  503-667-4564
PostgreSQL Centered full stack support, consulting and development.
Announcing "I'm offended" is basically telling the world you can't
control your own emotions, so everyone else should do it for you.