Thread: pg_dump docs should mention TMPDIR
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".
Also, I would like it if the pg_dump docs more assertively recommended
one of the "tar" or "custom" formats. They seem very similiar.
It woud also be nice to document that the full names "custom" and "tar" are
supported. Longer names can be nice for clarity.
( Unfortunately, wrong formats like "txx" also work instead of throwing
an error. )
Mark
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.
regards, tom lane
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>
On 2006-05-03, Tom Lane <tgl@sss.pgh.pa.us> 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.
Yes, on FreeBSD "man tmpfile()" documents the use of TMPDIR.
If TMPDIR isn't being respected globally, perhaps there /should/ be
logic in the code to make that so. Even on fairly modern FreeBSD
installs, sometimes "/tmp" only has 256 MB of room. There really should
be a reliable way to specify a different temporary directory.
>> 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.
Thanks for the recommendation.
Is that any concern that over time newer pg_restore's won't read old
"custom" formats? That would be my only worry-- that the data would be
locked in a binary format which becomes unsupported.
Mark
Mark Stosberg wrote: > >> 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. > > Thanks for the recommendation. > > Is that any concern that over time newer pg_restore's won't read old > "custom" formats? That would be my only worry-- that the data would be > locked in a binary format which becomes unsupported. No, we wouldn't do that. -- Bruce Momjian http://candle.pha.pa.us EnterpriseDB http://www.enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
Bruce Momjian <pgman@candle.pha.pa.us> writes:
> Mark Stosberg wrote:
>> Is that any concern that over time newer pg_restore's won't read old
>> "custom" formats? That would be my only worry-- that the data would be
>> locked in a binary format which becomes unsupported.
> No, we wouldn't do that.
Right, I can't imagine that we'd abandon support for pg_dump custom
format without many versions' warning. AFAIK we still read pg_dump
output from 7.0 if not earlier ...
regards, tom lane