Subject: Do we need "Diagnostics" sections of SQL command reference pages?

From: Tom Lane <[email-masked]>
Date: Mon, 25 Aug 2003 17:37:50 -0400

I'm starting to look at updating the docs to match 7.4 error message
spellings.  I find that a large part of the work I'll have to do is in
updating the "Diagnostics" (formerly "Outputs") section of the command
reference pages.  I am wondering if it wouldn't be better to just rip
out these sections entirely.  They seem like nearly content-free fluff
to me --- the listings of possible error messages are always incomplete,
often out of date, and arguably useless.  If there is an error message
that's not clear enough by itself, we'd better fix the error message
instead of putting a gloss on it in the reference page.

Comments?

			regards, tom lane

---

From: Bruno Wolff III <[email-masked]>
Date: Tue, 26 Aug 2003 07:16:46 -0500

On Mon, Aug 25, 2003 at 17:37:50 -0400,
> instead of putting a gloss on it in the reference page.

I think that a listing of possible error messages essentially indexed by
command isn't very useful.

However some of the documentation in that section is useful. In particular
the information for INSERT covers stuff that isn't self explanatory in the
output message.

---

From: "Dan Langille" <[email-masked]>
Date: Tue, 26 Aug 2003 08:26:26 -0400

On 25 Aug 2003 at 17:37, Tom Lane wrote:

> reference pages.

Do you have a URL for that.  I was looking at 
http://developer.postgresql.org/docs/postgres/index.html and didn't 
find it.

> I am wondering if it wouldn't be better to just rip

I have never been a fan of error codes.  I think that the error 
messages should contain enough information to fix the error.  It 
saves the reader time and reduces the load on support mechanisms 
(e.g. the mailing lists).
-- 
Dan Langille : http://www.langille.org/

---

From: Tom Lane <[email-masked]>
Date: Tue, 26 Aug 2003 09:14:41 -0400

> Do you have a URL for that.

Any of the SQL command reference pages, eg
http://developer.postgresql.org/docs/postgres/sql-createdatabase.html

			regards, tom lane

---

From: "Dan Langille" <[email-masked]>
Date: Tue, 26 Aug 2003 09:19:36 -0400

> http://developer.postgresql.org/docs/postgres/sql-createdatabase.html

Thanks.  I was looking for a single section.

The value I see in those message is it gives the reader more 
information about what can go wrong.  The above example shows that 
you cannot use "create database" within a transaction.

Also, the information under "ERROR: Could not initialize database 
directory." is pretty good.
-- 
Dan Langille : http://www.langille.org/

---

From: Tom Lane <[email-masked]>
Date: Tue, 26 Aug 2003 09:37:04 -0400

> you cannot use "create database" within a transaction.

Sure, but that should have been stated in the command description.

> directory." is pretty good.

I chose this example deliberately, because it's one of very few pages
where there's actually nontrivial content in the Diagnostics section.
"could not initialize database directory" seems to me the only one
of these messages that requires more info (the "could not create
database directory" message now includes the kernel error code, so
it's sufficiently improved IMHO).  What I'm inclined to do about it
is add a DETAIL field showing the exact "cp" command that failed, and
perhaps a HINT suggesting that people look in the postmaster's stderr
log to see cp's complaint.  Not sure how to translate that to Windows,
but under Unix it should be sufficient no?

			regards, tom lane

---

From: "Dan Langille" <[email-masked]>
Date: Tue, 26 Aug 2003 09:52:20 -0400

> Sure, but that should have been stated in the command description.

Agreed.  If the command description contains enough information, the 
DIAGNOSTICS section is no longer needed.

> but under Unix it should be sufficient no?

For me, yes.  I do like the idea of a DETAIL field.  The more info 
the better.  The HINT would be nice to have.
-- 
Dan Langille : http://www.langille.org/

---

From: "Chris M" <[email-masked]>
Date: Wed, 27 Aug 2003 20:51:51 +0800

"Tom Lane" <[email-masked]> Write news:[email-masked]...
> log to see cp's complaint.  Not sure how to translate that to Windows,

    Windows port may use "copy", "xcopy" to copy files.  In Windows, "copy"
is not so powerful as "xcopy". But I don't think using OS specific shell
commands
a good idea. If environment variable PATH is not set correctly, using these
commands
may cause a fail.

> ---------------------------(end of broadcast)---------------------------
> TIP 9: the planner will ignore your desire to choose an index scan if your
>       joining column's datatypes do not match
>

---

From: Josh Berkus <[email-masked]>
Date: Wed, 3 Sep 2003 13:06:14 -0700

Tom,

> instead of putting a gloss on it in the reference page.

I agree that we don't need descriptions of the meaning of each error message 
in the command documentation.

However, the listing of potential error messages is *very* useful to 
application coders for doing automated handling of errors.   Since we are now 
supporting SQLSTATE responses, perhaps we could have error code ranges for 
the commands?     Or is that totally unreasonable?

-- 
-Josh Berkus
 Aglio Database Solutions
 San Francisco

---

From: Tom Lane <[email-masked]>
Date: Wed, 03 Sep 2003 17:31:09 -0400

> the commands?     Or is that totally unreasonable?

It seems completely impractical to guarantee that any particular command
can produce only some-small-subset of all the possible errors.  There
are too many layers of code involved in handling any SQL command.

			regards, tom lane

---

From: Peter Eisentraut <[email-masked]>
Date: Thu, 4 Sep 2003 00:12:27 +0200 (CEST)

Tom Lane writes:

> out these sections entirely.

I agree with ripping out the messages part, but it might be useful to show
the completion tag somewhere, especially in cases where it contains
additional information (e.g., UPDATE).

-- 
Peter Eisentraut   [email-masked]

---

From: Tom Lane <[email-masked]>
Date: Wed, 03 Sep 2003 18:25:16 -0400

> additional information (e.g., UPDATE).

I'll make sure the completion tag is documented anywhere it's not simply
the command name.

			regards, tom lane