Subject: suggestion for improving TMPDIR and "--format" docs for pg_dump

From: Mark Stosberg <[email-masked]>
Date: Thu, 08 Mar 2007 21:30:22 -0500

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

---

From: Peter Eisentraut <[email-masked]>
Date: Fri, 9 Mar 2007 11:21:00 +0100

> "TMPDIR" environment variable to a location with more space, such as

That is really standard operating system behavior.  We don't need to duplicate 
that information.

> supported. Longer names can be nice for clarity.

They are.  You must be looking at an older version.

> ( Unfortunately, wrong formats like "txx" also work instead of throwing

Send a patch.

-- 
Peter Eisentraut
http://developer.postgresql.org/~petere/

---

From: Mark Stosberg <[email-masked]>
Date: Fri, 09 Mar 2007 09:31:27 -0500

> That is really standard operating system behavior.  We don't need to duplicate 

So is

 ./configure
 make
 make install

These are all external, standard programs, but they are common and
useful to document with applications. I think a small amount of
redundancy is documentation is a good thing.

When I wanted to use a different tmp dir, I searched the PostgreSQL docs
for how to do that, because I was using a PostgreSQL tool. I had no why
of knowing whether PostgreSQL was even using standard conventions of
tmpdir handling, of if it did it's own thing. Also, after several years
of being professional involved with Unix system maintenance, I was not
aware that this was a standard feature. Surely then, less advanced users
would benefit from the documentation.

> They are.  You must be looking at an older version.

You are correct. Sorry about that.

>> ( Unfortunately, wrong formats like "txx" also work instead of throwing

I appreciate the sentiment, by my C skills are weak.

       Mark

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 19 Mar 2007 13:43:28 -0400 (EDT)

> ( Unfortunately, wrong formats like "txx" also work instead of throwing

I don't see that with current CVS:

	$ pg_dump --format=x test
	pg_dump: invalid output format "x" specified

-- 
  Bruce Momjian  <[email-masked]>          http://momjian.us
  EnterpriseDB                               http://www.enterprisedb.com

  + If your life is a hard drive, Christ can be your backup. +

---

From: Mark Stosberg <[email-masked]>
Date: Mon, 19 Mar 2007 13:47:20 -0400

> 	pg_dump: invalid output format "x" specified

Bruce,

I think the specific test case would have to start with a valid letter,
like "t", and then include invalid characters. Try this instead:

 pg_dump --format=tx test

     Mark

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 22 Mar 2007 15:43:24 -0400 (EDT)

> like "t", and then include invalid characters. Try this instead:

Thanks for the report.  I have corrected this and the fix will be in
PostgreSQL 8.3.  Interestingly, we support non-documented option
"append" and "file" too.

Patch attached and applied.

  + If your life is a hard drive, Christ can be your backup. +
Index: src/bin/pg_dump/pg_dump.c
===================================================================
RCS file: /cvsroot/pgsql/src/bin/pg_dump/pg_dump.c,v
retrieving revision 1.461
diff -c -c -r1.461 pg_dump.c
*** src/bin/pg_dump/pg_dump.c	19 Mar 2007 23:38:30 -0000	1.461
--- src/bin/pg_dump/pg_dump.c	22 Mar 2007 18:39:53 -0000
***************
*** 476,513 ****
  	}
  
  	/* open the output file */
! 	switch (format[0])
  	{
! 		case 'a':
! 		case 'A':
! 			plainText = 1;
! 			g_fout = CreateArchive(filename, archNull, 0, archModeAppend);
! 			break;
! 			
! 		case 'c':
! 		case 'C':
! 			g_fout = CreateArchive(filename, archCustom, compressLevel, archModeWrite);
! 			break;
! 
! 		case 'f':
! 		case 'F':
! 			g_fout = CreateArchive(filename, archFiles, compressLevel, archModeWrite);
! 			break;
! 
! 		case 'p':
! 		case 'P':
! 			plainText = 1;
! 			g_fout = CreateArchive(filename, archNull, 0, archModeWrite);
! 			break;
! 
! 		case 't':
! 		case 'T':
! 			g_fout = CreateArchive(filename, archTar, compressLevel, archModeWrite);
! 			break;
! 
! 		default:
! 			write_msg(NULL, "invalid output format \"%s\" specified\n", format);
! 			exit(1);
  	}
  
  	if (g_fout == NULL)
--- 476,508 ----
  	}
  
  	/* open the output file */
! 	if (strcasecmp(format, "a") == 0 || strcasecmp(format, "append") == 0)
  	{
! 		/* not documented */
! 		plainText = 1;
! 		g_fout = CreateArchive(filename, archNull, 0, archModeAppend);
! 	}
! 	else if (strcasecmp(format, "c") == 0 || strcasecmp(format, "custom") == 0)
! 		g_fout = CreateArchive(filename, archCustom, compressLevel, archModeWrite);
! 	else if (strcasecmp(format, "f") == 0 || strcasecmp(format, "file") == 0)
! 	{
! 		/*
! 		 *	Dump files into the current directory; for demonstration only, not
! 		 *	documented.
! 		 */
! 		g_fout = CreateArchive(filename, archFiles, compressLevel, archModeWrite);
! 	}
! 	else if (strcasecmp(format, "p") == 0 || strcasecmp(format, "plain") == 0)
! 	{
! 		plainText = 1;
! 		g_fout = CreateArchive(filename, archNull, 0, archModeWrite);
! 	}
! 	else if (strcasecmp(format, "t") == 0 || strcasecmp(format, "tar") == 0)
! 		g_fout = CreateArchive(filename, archTar, compressLevel, archModeWrite);
! 	else
! 	{
! 		write_msg(NULL, "invalid output format \"%s\" specified\n", format);
! 		exit(1);
  	}
  
  	if (g_fout == NULL)

---

From: Tom Lane <[email-masked]>
Date: Thu, 22 Mar 2007 16:17:42 -0400

> PostgreSQL 8.3.  Interestingly, we support non-documented option

Surely these should all be pg_strcasecmp?

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 22 Mar 2007 16:18:52 -0400 (EDT)

> Surely these should all be pg_strcasecmp?

Yep, fixed.

---

From: Dave Page <[email-masked]>
Date: Thu, 22 Mar 2007 20:41:42 +0000

> PostgreSQL 8.3.  Interestingly, we support non-documented option

Append is undocumented as it's intended to be used by pg_dumpall, not
directly by users.

Regards, Dave.

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 22 Mar 2007 16:44:34 -0400 (EDT)

> Append is undocumented as it's intended to be used by pg_dumpall, not

Ah, OK, but there should be a clear comment somewhere about that.  I
will add it.

---

From: Dave Page <[email-masked]>
Date: Thu, 22 Mar 2007 20:47:38 +0000

> Ah, OK, but there should be a clear comment somewhere about that.  I

Thanks.

Regards Dave