Re: pg_dump docs should mention TMPDIR - Mailing list pgsql-docs

Tom Lane wrote:
> Mark Stosberg <mark@summersault.com> writes:
> > A suggested addition to the pg_dump docs:
> > This would be an extension to the documentation for the "tar" format:
>
> > The tar format needs some space to create temporary files. By default
> > "/tmp" is used. On systems with small "/tmp" partitions, set the
> > "TMPDIR" environment variable to a location with more space, such as
> > "/usr/tmp".
>
> There is no reference to TMPDIR in the pg_dump code.  It may be that
> tmpfile() pays attention to such an environment variable on your
> machine, but there's nothing about it in the Single Unix Spec.
>
> > Also, I would like it if the pg_dump docs more assertively recommended
> > one of the "tar" or "custom" formats. They seem very similiar.
>
> Yeah.  I think it should specifically recommend custom format.  The only
> reason for using tar format would be if you want to process the file
> later with something other than pg_restore.

I have applied the attached patch to recommend more clearly custom
pg_dump format over tar, by showing custom format examples first.

--
  Bruce Momjian   http://candle.pha.pa.us
  EnterpriseDB    http://www.enterprisedb.com

  + If your life is a hard drive, Christ can be your backup. +
Index: doc/src/sgml/ref/pg_dump.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v
retrieving revision 1.83
diff -c -c -r1.83 pg_dump.sgml
*** doc/src/sgml/ref/pg_dump.sgml    15 Apr 2006 18:11:16 -0000    1.83
--- doc/src/sgml/ref/pg_dump.sgml    6 May 2006 23:23:23 -0000
***************
*** 244,271 ****
          </varlistentry>

          <varlistentry>
!          <term><literal>t</></term>
!          <term><literal>tar</></term>
           <listitem>
            <para>
!          Output a <command>tar</command> archive suitable for input into
!          <application>pg_restore</application>. Using this archive format
!          allows reordering and/or exclusion of database objects
!          at the time the database is restored. It is also possible to limit
!          which data is reloaded at restore time.
            </para>
           </listitem>
          </varlistentry>

          <varlistentry>
!          <term><literal>c</></term>
!          <term><literal>custom</></term>
           <listitem>
            <para>
!          Output a custom archive suitable for input into
!          <application>pg_restore</application>. This is the most flexible
!          format in that it allows reordering of loading data as well
!          as object definitions. This format is also compressed by default.
            </para>
           </listitem>
          </varlistentry>
--- 244,271 ----
          </varlistentry>

          <varlistentry>
!          <term><literal>c</></term>
!          <term><literal>custom</></term>
           <listitem>
            <para>
!          Output a custom archive suitable for input into
!          <application>pg_restore</application>. This is the most flexible
!          format in that it allows reordering of loading data as well
!          as object definitions. This format is also compressed by default.
            </para>
           </listitem>
          </varlistentry>

          <varlistentry>
!          <term><literal>t</></term>
!          <term><literal>tar</></term>
           <listitem>
            <para>
!          Output a <command>tar</command> archive suitable for input into
!          <application>pg_restore</application>. Using this archive format
!          allows reordering and/or exclusion of database objects
!          at the time the database is restored. It is also possible to limit
!          which data is reloaded at restore time.
            </para>
           </listitem>
          </varlistentry>
***************
*** 665,675 ****
    </para>

    <para>
!    To dump a database called <literal>mydb</> to a <filename>tar</filename>
     file:

  <screen>
! <prompt>$</prompt> <userinput>pg_dump -Ft mydb > db.tar</userinput>
  </screen>
    </para>

--- 665,675 ----
    </para>

    <para>
!    To dump a database called <literal>mydb</> to a file in custom format:
     file:

  <screen>
! <prompt>$</prompt> <userinput>pg_dump -Fc mydb > db.out</userinput>
  </screen>
    </para>

***************
*** 677,683 ****
     To reload this dump into an existing database called <literal>newdb</>:

  <screen>
! <prompt>$</prompt> <userinput>pg_restore -d newdb db.tar</userinput>
  </screen>
    </para>

--- 677,683 ----
     To reload this dump into an existing database called <literal>newdb</>:

  <screen>
! <prompt>$</prompt> <userinput>pg_restore -d newdb db.out</userinput>
  </screen>
    </para>