mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-08-18 08:33:22 +02:00
1366 lines
52 KiB
Plaintext
1366 lines
52 KiB
Plaintext
From pgsql-hackers-owner+M16120=candle.pha.pa.us=pgman@postgresql.org Fri Nov 30 12:14:19 2001
|
|
Return-path: <pgsql-hackers-owner+M16120=candle.pha.pa.us=pgman@postgresql.org>
|
|
Received: from rs.postgresql.org (server1.pgsql.org [64.39.15.238] (may be forged))
|
|
by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id fAUIEIR21802
|
|
for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 13:14:18 -0500 (EST)
|
|
Received: from postgresql.org (postgresql.org [64.49.215.8])
|
|
by rs.postgresql.org (8.11.6/8.11.6) with ESMTP id fAUI6ER13094
|
|
for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 12:11:00 -0600 (CST)
|
|
(envelope-from pgsql-hackers-owner+M16120=candle.pha.pa.us=pgman@postgresql.org)
|
|
Received: from moutvdom01.kundenserver.de (moutvdom01.kundenserver.de [195.20.224.200])
|
|
by postgresql.org (8.11.3/8.11.4) with ESMTP id fAUI58m98870
|
|
for <pgsql-hackers@postgresql.org>; Fri, 30 Nov 2001 13:05:08 -0500 (EST)
|
|
(envelope-from peter_e@gmx.net)
|
|
Received: from [195.20.224.208] (helo=mrvdom01.schlund.de)
|
|
by moutvdom01.kundenserver.de with esmtp (Exim 2.12 #2)
|
|
id 169s27-00049P-00
|
|
for pgsql-hackers@postgresql.org; Fri, 30 Nov 2001 19:05:07 +0100
|
|
Received: from p3e9e6fa2.dip0.t-ipconnect.de ([62.158.111.162])
|
|
by mrvdom01.schlund.de with esmtp (Exim 2.12 #2)
|
|
id 169s21-0001UP-00
|
|
for pgsql-hackers@postgresql.org; Fri, 30 Nov 2001 19:05:03 +0100
|
|
Date: Fri, 30 Nov 2001 19:12:16 +0100 (CET)
|
|
From: Peter Eisentraut <peter_e@gmx.net>
|
|
X-Sender: <peter@peter.localdomain>
|
|
To: PostgreSQL Development <pgsql-hackers@postgresql.org>
|
|
Subject: [HACKERS] Backend error message style issues
|
|
Message-ID: <Pine.LNX.4.30.0111292302020.609-100000@peter.localdomain>
|
|
MIME-Version: 1.0
|
|
Content-Type: TEXT/PLAIN; charset=US-ASCII
|
|
Precedence: bulk
|
|
Sender: pgsql-hackers-owner@postgresql.org
|
|
Status: ORr
|
|
|
|
Now that we've gone through nearly one development cycle with national
|
|
language support, I'd like to bring up a number of issues concerning the
|
|
style of the backend error messages that make life difficult, but probably
|
|
not only for the translators but for users as well. Not all of these are
|
|
strictly translation issues, but the message catalogs make for a good
|
|
overview of what's going on.
|
|
|
|
I hope we can work through all of these during the next development
|
|
period.
|
|
|
|
Prefixing messages with command names
|
|
-------------------------------------
|
|
|
|
For instance,
|
|
|
|
| CREATE DATABASE: permission denied
|
|
|
|
This "command: message" style is typical for command-line programs and
|
|
it's pretty useful there if you run many commands in a pipe. The same
|
|
usefulness could probably be derived if you run many SQL commands in a
|
|
function. (Just "permission denied" would be very confusing there!)
|
|
|
|
If we want to use that style we should make it consistent and we should
|
|
automate it. Via the "command tag" mechanism we already know what command
|
|
we're executing, so we can automatically prefix all messages that way. It
|
|
could even be switched off by the user if it's deemed annoying.
|
|
|
|
|
|
Prefixing messages with function names
|
|
--------------------------------------
|
|
|
|
The function names obviously have no meaning to the user. It is claimed
|
|
that they allow a developer to locate the place the error was raised
|
|
faster, but that's only half the truth. Firstly, this whole thing doesn't
|
|
work if the displayed name of the function was actually passed in from
|
|
elsewhere. Then it takes you three times longer to locate the source
|
|
because you *think* you know where it was but it's not there. Secondly,
|
|
a developer doesn't have the need to locate every error. For instance,
|
|
|
|
| ExecAppend: rejected due to CHECK constraint foo
|
|
|
|
There's no need to debug anything there, it's a perfectly normal use
|
|
situation.
|
|
|
|
I think the key here is to distinguish error messages that are perfectly
|
|
normal user-level events from messages which really represent an "assert
|
|
failure, but continue gracefully", such as
|
|
|
|
| initGISTstate: numberOfAttributes %d > %d
|
|
|
|
The latter could better be written something like
|
|
|
|
| BETTER_BE_TRUE(index->rd_att->natts > INDEX_MAX_KEYS);
|
|
|
|
we could lead to an error message in the style of an assert failure,
|
|
including the expression in question and file and line information (and
|
|
bug reporting suggestions). This way the developer doesn't have to write
|
|
any message text at all but still gets much better information to locate
|
|
the source. (E.g., note that the tested variable isn't even called
|
|
"numberOfAttributes".)
|
|
|
|
The exact API could be tuned to include some other information such as an
|
|
informal message, but I think something along these lines needs to be
|
|
worked out.
|
|
|
|
|
|
Quoting
|
|
-------
|
|
|
|
Which is better:
|
|
|
|
function '%s' not found
|
|
function "%s" not found
|
|
function %s not found
|
|
|
|
I think two kinds of quotes is looking messy. Personal suggestion:
|
|
double quotes.
|
|
|
|
|
|
Capitalization and punctuation
|
|
------------------------------
|
|
|
|
Which one?
|
|
|
|
ERROR: Permission denied.
|
|
ERROR: Permission denied
|
|
ERROR: permission denied
|
|
|
|
I have personally used the GNU-recommended way which is the third, mostly
|
|
just because it is *some* standardized way. I don't have a strong feeling
|
|
about the initial capitalization, but I'm against the periods except when
|
|
the message is really a sentence and it contains some other punctuation
|
|
(commas, etc.) or the message consists of more than one sentence.
|
|
|
|
|
|
Grammatical structure and choice of words
|
|
-----------------------------------------
|
|
|
|
There are many others besides the above choices:
|
|
|
|
ERROR: Permission was denied.
|
|
ERROR: You don't have permission to do <task>.
|
|
ERROR: Permission to do <task> was denied.
|
|
ERROR: <task>: Permission denied
|
|
|
|
In other cases there's a sea of possibilities:
|
|
|
|
couldn't find THING
|
|
can't find THING
|
|
THING wasn't found
|
|
unable to locate THING
|
|
lookup of THING failed
|
|
THING doesn't exist
|
|
|
|
Strictly speaking, there are at least four different meanings among those
|
|
six messages, yet they're used mostly randomly.
|
|
|
|
There are a number of things to think about here: active vs passive, can
|
|
vs could, complete sentence vs telegram style, use of colons, addressing
|
|
the user with "you [cannot...]".
|
|
|
|
And please let's not have the program talk in the "I"-form ("I have rolled
|
|
back the current transaction ...").
|
|
|
|
|
|
|
|
More esoteric discussions are also possible, but I'm going to postpone
|
|
those. ;-) However, I think it's worth working on this and perhaps
|
|
putting together a "manual of style" that applies to all parts of
|
|
PostgreSQL. This would significantly improve the overall perceived
|
|
quality. Some projects like KDE, GNU, and GCC have teams that discuss
|
|
these kinds of things and it's definitely showing.
|
|
|
|
--
|
|
Peter Eisentraut peter_e@gmx.net
|
|
|
|
|
|
---------------------------(end of broadcast)---------------------------
|
|
TIP 3: if posting/reading through Usenet, please send an appropriate
|
|
subscribe-nomail command to majordomo@postgresql.org so that your
|
|
message can get through to the mailing list cleanly
|
|
|
|
From pgsql-hackers-owner+M16128=candle.pha.pa.us=pgman@postgresql.org Fri Nov 30 13:39:41 2001
|
|
Return-path: <pgsql-hackers-owner+M16128=candle.pha.pa.us=pgman@postgresql.org>
|
|
Received: from rs.postgresql.org (server1.pgsql.org [64.39.15.238] (may be forged))
|
|
by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id fAUJdfR29066
|
|
for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 14:39:41 -0500 (EST)
|
|
Received: from postgresql.org (postgresql.org [64.49.215.8])
|
|
by rs.postgresql.org (8.11.6/8.11.6) with ESMTP id fAUJXkR15701
|
|
for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 13:36:17 -0600 (CST)
|
|
(envelope-from pgsql-hackers-owner+M16128=candle.pha.pa.us=pgman@postgresql.org)
|
|
Received: from corvette.mascari.com (dhcp065-024-158-068.columbus.rr.com [65.24.158.68])
|
|
by postgresql.org (8.11.3/8.11.4) with ESMTP id fAUJMnm01940
|
|
for <pgsql-hackers@postgresql.org>; Fri, 30 Nov 2001 14:22:49 -0500 (EST)
|
|
(envelope-from mascarm@mascari.com)
|
|
Received: from mascari.com (ferrari.mascari.com [192.168.2.1])
|
|
by corvette.mascari.com (8.9.3/8.9.3) with ESMTP id OAA20637;
|
|
Fri, 30 Nov 2001 14:16:52 -0500
|
|
Message-ID: <3C07DBAD.A9735975@mascari.com>
|
|
Date: Fri, 30 Nov 2001 14:19:09 -0500
|
|
From: Mike Mascari <mascarm@mascari.com>
|
|
Organization: Mascari Development Inc.
|
|
X-Mailer: Mozilla 4.77 [en] (WinNT; U)
|
|
X-Accept-Language: en
|
|
MIME-Version: 1.0
|
|
To: Peter Eisentraut <peter_e@gmx.net>
|
|
cc: PostgreSQL Development <pgsql-hackers@postgresql.org>
|
|
Subject: Re: [HACKERS] Backend error message style issues
|
|
References: <Pine.LNX.4.30.0111292302020.609-100000@peter.localdomain>
|
|
Content-Type: text/plain; charset=us-ascii
|
|
Content-Transfer-Encoding: 7bit
|
|
Precedence: bulk
|
|
Sender: pgsql-hackers-owner@postgresql.org
|
|
Status: OR
|
|
|
|
Peter Eisentraut wrote:
|
|
>
|
|
> Now that we've gone through nearly one development cycle with national
|
|
> language support, I'd like to bring up a number of issues concerning the
|
|
> style of the backend error messages that make life difficult, but probably
|
|
> not only for the translators but for users as well. Not all of these are
|
|
> strictly translation issues, but the message catalogs make for a good
|
|
> overview of what's going on.
|
|
|
|
For what its worth, Oracle 8 ships with an error.txt file which
|
|
dictates the message standards to which their products comply.
|
|
Roughly:
|
|
|
|
Size Of Message:
|
|
---------------
|
|
|
|
Cannot exceed 76 characters, even when embedded format specifiers
|
|
are apart of the message. Only
|
|
start-up and system-dependent messages can exceed 76 characters.
|
|
|
|
Simple Language:
|
|
---------------
|
|
|
|
Use non-cryptic messages and overly technical language.
|
|
|
|
Upper vs. Lowercase:
|
|
-------------------
|
|
|
|
Use uppercase for commands and keywords, lowercase for message
|
|
wording, including the first letter (which agrees with your use,
|
|
Peter).
|
|
|
|
Commands, Keywords, Parameter Values:
|
|
------------------------------------
|
|
|
|
When possible, give the command, keyword and parameters used in the
|
|
message.
|
|
|
|
BAD: The relation could not be created
|
|
GOOD: CREATE TABLE failed for table "foo" because the disk is full
|
|
|
|
Period:
|
|
------
|
|
|
|
Do not end messages with a period (also agrees with your
|
|
conclusion).
|
|
|
|
Numbers:
|
|
-------
|
|
|
|
Don't enclose numbers with special characters. For example:
|
|
|
|
BAD: rows returned by subquery (3) exceeded limit (1)
|
|
GOOD: the subquery returned 3 rows exceeding the 1 row limit
|
|
|
|
Quotes:
|
|
------
|
|
|
|
Don't use single or double quotes to emphasize a text variable or
|
|
command
|
|
|
|
Single Quotes:
|
|
-------------
|
|
|
|
Never use them.
|
|
|
|
Double Quotes:
|
|
-------------
|
|
|
|
Always and only use them to identify database objects.
|
|
|
|
BAD: Unable to drop table employees
|
|
GOOD: DROP TABLE of "employees" failed due to referential integrity
|
|
constraints
|
|
|
|
Ellipses:
|
|
--------
|
|
|
|
Don't use them.
|
|
|
|
BAD: Unable to drop column mascarm.employees.salary
|
|
GOOD: ALTER TABLE was unable to drop the column "salary" table
|
|
"employees" schema "mascarm"
|
|
|
|
Parentheses:
|
|
-----------
|
|
|
|
Always and only use parentheses for constraint names
|
|
|
|
BAD: not null constraint ri_employees violated
|
|
GOOD: not null constraint (ri_employees) violated
|
|
|
|
Brackets:
|
|
--------
|
|
|
|
Always and only used for program arguments
|
|
|
|
Grammar:
|
|
-------
|
|
|
|
Use complete sentences whenever possible without the trailing
|
|
period. Don't use multiple sentences. Use the active voice. Don't
|
|
use an aggressive tone.
|
|
|
|
Style:
|
|
-----
|
|
|
|
Make positive suggestions. Explain what is invalid and what is
|
|
valid.
|
|
|
|
Example:
|
|
|
|
BAD: file name invalid
|
|
BETTER: COPY failed because the file name was too long
|
|
|
|
Routine names:
|
|
-------------
|
|
|
|
Do not use routine names in messages. Again, agrees with you, Peter.
|
|
|
|
FWIW,
|
|
|
|
Mike Mascari
|
|
mascarm@mascari.com
|
|
|
|
---------------------------(end of broadcast)---------------------------
|
|
TIP 1: subscribe and unsubscribe commands go to majordomo@postgresql.org
|
|
|
|
From pgsql-hackers-owner+M16130=candle.pha.pa.us=pgman@postgresql.org Fri Nov 30 14:09:48 2001
|
|
Return-path: <pgsql-hackers-owner+M16130=candle.pha.pa.us=pgman@postgresql.org>
|
|
Received: from rs.postgresql.org (server1.pgsql.org [64.39.15.238] (may be forged))
|
|
by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id fAUK9lR02095
|
|
for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 15:09:48 -0500 (EST)
|
|
Received: from postgresql.org (postgresql.org [64.49.215.8])
|
|
by rs.postgresql.org (8.11.6/8.11.6) with ESMTP id fAUK3MR16820
|
|
for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 14:05:48 -0600 (CST)
|
|
(envelope-from pgsql-hackers-owner+M16130=candle.pha.pa.us=pgman@postgresql.org)
|
|
Received: from sss.pgh.pa.us ([192.204.191.242])
|
|
by postgresql.org (8.11.3/8.11.4) with ESMTP id fAUJnLm02954
|
|
for <pgsql-hackers@postgresql.org>; Fri, 30 Nov 2001 14:49:21 -0500 (EST)
|
|
(envelope-from tgl@sss.pgh.pa.us)
|
|
Received: from sss2.sss.pgh.pa.us (tgl@localhost [127.0.0.1])
|
|
by sss.pgh.pa.us (8.11.4/8.11.4) with ESMTP id fAUJnEi10307;
|
|
Fri, 30 Nov 2001 14:49:14 -0500 (EST)
|
|
To: Peter Eisentraut <peter_e@gmx.net>
|
|
cc: PostgreSQL Development <pgsql-hackers@postgresql.org>
|
|
Subject: Re: [HACKERS] Backend error message style issues
|
|
In-Reply-To: <Pine.LNX.4.30.0111292302020.609-100000@peter.localdomain>
|
|
References: <Pine.LNX.4.30.0111292302020.609-100000@peter.localdomain>
|
|
Comments: In-reply-to Peter Eisentraut <peter_e@gmx.net>
|
|
message dated "Fri, 30 Nov 2001 19:12:16 +0100"
|
|
Date: Fri, 30 Nov 2001 14:49:14 -0500
|
|
Message-ID: <10303.1007149754@sss.pgh.pa.us>
|
|
From: Tom Lane <tgl@sss.pgh.pa.us>
|
|
Precedence: bulk
|
|
Sender: pgsql-hackers-owner@postgresql.org
|
|
Status: OR
|
|
|
|
Peter Eisentraut <peter_e@gmx.net> writes:
|
|
> I hope we can work through all of these during the next development
|
|
> period.
|
|
|
|
Too bad we didn't do it *before* doing a lot of translation work :-(.
|
|
|
|
Yes, I agree that a pass of rationalizing the error messages would be
|
|
useful. Might want to think about that old bugaboo, error codes,
|
|
while we're at it. Also the perennial complaint that "ERROR" and
|
|
"DEBUG" macros tend to conflict with other things. As long as we're
|
|
going to touch many/all of the elog() calls, couldn't we try to clean
|
|
up all these issues?
|
|
|
|
> Which is better:
|
|
|
|
> function '%s' not found
|
|
> function "%s" not found
|
|
> function %s not found
|
|
|
|
Given that 'x' and "x" mean very different things in SQL, I think that
|
|
the first form is just plain wrong when an identifier is involved.
|
|
Unfortunately a lot of older code uses that style. I've tried to use
|
|
double quotes in new messages, but have restrained myself from wholesale
|
|
changes of existing messages.
|
|
|
|
> More esoteric discussions are also possible, but I'm going to postpone
|
|
> those. ;-) However, I think it's worth working on this and perhaps
|
|
> putting together a "manual of style" that applies to all parts of
|
|
> PostgreSQL. This would significantly improve the overall perceived
|
|
> quality.
|
|
|
|
Sounds like a plan to me: put together a style guide first, and then
|
|
make a pass through the code to try to implement it.
|
|
|
|
regards, tom lane
|
|
|
|
---------------------------(end of broadcast)---------------------------
|
|
TIP 1: subscribe and unsubscribe commands go to majordomo@postgresql.org
|
|
|
|
From pgsql-hackers-owner+M25090@postgresql.org Wed Jul 17 14:27:47 2002
|
|
Return-path: <pgsql-hackers-owner+M25090@postgresql.org>
|
|
Received: from postgresql.org (postgresql.org [64.49.215.8])
|
|
by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id g6HIRke20336
|
|
for <pgman@candle.pha.pa.us>; Wed, 17 Jul 2002 14:27:46 -0400 (EDT)
|
|
Received: from postgresql.org (postgresql.org [64.49.215.8])
|
|
by postgresql.org (Postfix) with SMTP
|
|
id A5EC0475931; Wed, 17 Jul 2002 14:27:42 -0400 (EDT)
|
|
Received: from klamath.dyndns.org (CPE002078144ae0.cpe.net.cable.rogers.com [24.102.202.35])
|
|
by postgresql.org (Postfix) with ESMTP id 8C8A74758F5
|
|
for <pgsql-hackers@postgresql.org>; Wed, 17 Jul 2002 14:27:39 -0400 (EDT)
|
|
Received: by klamath.dyndns.org (Postfix, from userid 1000)
|
|
id D98827015; Wed, 17 Jul 2002 14:27:39 -0400 (EDT)
|
|
Date: Wed, 17 Jul 2002 14:27:39 -0400
|
|
To: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
|
|
Subject: [HACKERS] error codes
|
|
Message-ID: <20020717182739.GB5542@klamath.dyndns.org>
|
|
Mail-Followup-To: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
|
|
MIME-Version: 1.0
|
|
Content-Type: text/plain; charset=us-ascii
|
|
Content-Disposition: inline
|
|
User-Agent: Mutt/1.4i
|
|
From: nconway@klamath.dyndns.org (Neil Conway)
|
|
Precedence: bulk
|
|
Sender: pgsql-hackers-owner@postgresql.org
|
|
Status: ORr
|
|
|
|
I'd like to implement error codes. I think they would be pretty useful,
|
|
although there are a few difficulties in the implementation I'd like
|
|
to get some input on.
|
|
|
|
Should every elog() have an error code? I'm not sure -- there are many
|
|
elog() calls that will never been seen by the user, since the error
|
|
they represent will be caught before control reaches the elog (e.g.
|
|
parse errors, internal consistency checks, multiple elog(ERROR)
|
|
for the same user error, etc.) Perhaps for those error messages
|
|
that don't have numbers, we could just give them ERRNO_UNKNOWN or
|
|
a similar constant.
|
|
|
|
How should the backend code signal an error with an error number?
|
|
Perhaps we could report errors with error numbers via a separate
|
|
function, which would take the error number as its only param.
|
|
For example:
|
|
|
|
error(ERRNO_REF_INT_VIOLATION);
|
|
|
|
The problem here is that many errors will require more information
|
|
that that, in order for the client to handle them properly. For
|
|
example, how should a COPY indicate that an RI violation has
|
|
occured? Ideally, we'd like to allow the client application to
|
|
know that in line a, column b, the literal value 'c' was
|
|
not found in the referenced column d of the referenced table d.
|
|
|
|
How should the error number be sent to the client, and would this
|
|
require an FE/BE change? I think we can avoid that: including the
|
|
error number in the error message itself, make PQgetErrorMessage()
|
|
(and similar funcs) smart enough to remove the error number, and
|
|
add a separate function (such as PQgetErrorNumber() ) to report
|
|
the error number, if there is one.
|
|
|
|
On a related note, it would be nice to get a consistent style of
|
|
punctuation for elog() messages -- currently, some of them end
|
|
in a period (e.g. "Database xxx does not exist in the system
|
|
catalog."), while the majority do not. Which is better?
|
|
|
|
Also, I think it was Bruce who mentioned that it would be nice
|
|
to add function names, source files, and/or line numbers to error
|
|
messages, instead of the current inconsistent method of sometimes
|
|
specifying the function name in the elog() message. Would this
|
|
be a good idea? Should all errors include this information?
|
|
|
|
It would be relatively easy to replace elog() with a macro of
|
|
the form:
|
|
|
|
#define elog(...) real_elog(__FILE__, __LINE__, __VA_ARGS__)
|
|
|
|
And then adjust real_elog() to report that information as
|
|
appropriate.
|
|
|
|
Cheers,
|
|
|
|
Neil
|
|
|
|
--
|
|
Neil Conway <neilconway@rogers.com>
|
|
PGP Key ID: DB3C29FC
|
|
|
|
---------------------------(end of broadcast)---------------------------
|
|
TIP 2: you can get off all lists at once with the unregister command
|
|
(send "unregister YourEmailAddressHere" to majordomo@postgresql.org)
|
|
|
|
From pgsql-hackers-owner+M25094@postgresql.org Wed Jul 17 15:58:08 2002
|
|
Return-path: <pgsql-hackers-owner+M25094@postgresql.org>
|
|
Received: from postgresql.org (postgresql.org [64.49.215.8])
|
|
by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id g6HJw7e27032
|
|
for <pgman@candle.pha.pa.us>; Wed, 17 Jul 2002 15:58:07 -0400 (EDT)
|
|
Received: from postgresql.org (postgresql.org [64.49.215.8])
|
|
by postgresql.org (Postfix) with SMTP
|
|
id 73DA3475C3D; Wed, 17 Jul 2002 15:58:00 -0400 (EDT)
|
|
Received: from sss.pgh.pa.us (unknown [192.204.191.242])
|
|
by postgresql.org (Postfix) with ESMTP id BDA71475D6F
|
|
for <pgsql-hackers@postgresql.org>; Wed, 17 Jul 2002 15:57:56 -0400 (EDT)
|
|
Received: from sss2.sss.pgh.pa.us (tgl@localhost [127.0.0.1])
|
|
by sss.pgh.pa.us (8.12.5/8.12.5) with ESMTP id g6HJvuAl016463;
|
|
Wed, 17 Jul 2002 15:57:56 -0400 (EDT)
|
|
To: nconway@klamath.dyndns.org (Neil Conway)
|
|
cc: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
|
|
Subject: Re: [HACKERS] error codes
|
|
In-Reply-To: <20020717182739.GB5542@klamath.dyndns.org>
|
|
References: <20020717182739.GB5542@klamath.dyndns.org>
|
|
Comments: In-reply-to nconway@klamath.dyndns.org (Neil Conway)
|
|
message dated "Wed, 17 Jul 2002 14:27:39 -0400"
|
|
Date: Wed, 17 Jul 2002 15:57:56 -0400
|
|
Message-ID: <16462.1026935876@sss.pgh.pa.us>
|
|
From: Tom Lane <tgl@sss.pgh.pa.us>
|
|
Precedence: bulk
|
|
Sender: pgsql-hackers-owner@postgresql.org
|
|
Status: OR
|
|
|
|
nconway@klamath.dyndns.org (Neil Conway) writes:
|
|
> Should every elog() have an error code?
|
|
|
|
I believe we decided that it'd be okay to use one or two codes defined
|
|
like "internal error", "corrupted data", etc for all the elogs that are
|
|
not-supposed-to-happen conditions. What error codes are really for is
|
|
distinguishing different kinds of user mistakes, and so that's where
|
|
you need specificness.
|
|
|
|
> How should the backend code signal an error with an error number?
|
|
|
|
Please read some of the archived discussions about this. All the points
|
|
you mention have been brought up before.
|
|
|
|
regards, tom lane
|
|
|
|
---------------------------(end of broadcast)---------------------------
|
|
TIP 5: Have you checked our extensive FAQ?
|
|
|
|
http://www.postgresql.org/users-lounge/docs/faq.html
|
|
|
|
From pgsql-hackers-owner+M25095@postgresql.org Wed Jul 17 16:18:08 2002
|
|
Return-path: <pgsql-hackers-owner+M25095@postgresql.org>
|
|
Received: from postgresql.org (postgresql.org [64.49.215.8])
|
|
by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id g6HKI8e28852
|
|
for <pgman@candle.pha.pa.us>; Wed, 17 Jul 2002 16:18:08 -0400 (EDT)
|
|
Received: from postgresql.org (postgresql.org [64.49.215.8])
|
|
by postgresql.org (Postfix) with SMTP
|
|
id 68FAB475C69; Wed, 17 Jul 2002 16:18:05 -0400 (EDT)
|
|
Received: from klamath.dyndns.org (CPE002078144ae0.cpe.net.cable.rogers.com [24.102.202.35])
|
|
by postgresql.org (Postfix) with ESMTP id 7867847585D
|
|
for <pgsql-hackers@postgresql.org>; Wed, 17 Jul 2002 16:17:57 -0400 (EDT)
|
|
Received: by klamath.dyndns.org (Postfix, from userid 1000)
|
|
id A182C7015; Wed, 17 Jul 2002 16:17:58 -0400 (EDT)
|
|
Date: Wed, 17 Jul 2002 16:17:58 -0400
|
|
To: Tom Lane <tgl@sss.pgh.pa.us>
|
|
cc: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
|
|
Subject: Re: [HACKERS] error codes
|
|
Message-ID: <20020717201758.GA6846@klamath.dyndns.org>
|
|
Mail-Followup-To: Tom Lane <tgl@sss.pgh.pa.us>,
|
|
PostgreSQL Hackers <pgsql-hackers@postgresql.org>
|
|
References: <20020717182739.GB5542@klamath.dyndns.org> <16462.1026935876@sss.pgh.pa.us>
|
|
MIME-Version: 1.0
|
|
Content-Type: text/plain; charset=us-ascii
|
|
Content-Disposition: inline
|
|
In-Reply-To: <16462.1026935876@sss.pgh.pa.us>
|
|
User-Agent: Mutt/1.4i
|
|
From: nconway@klamath.dyndns.org (Neil Conway)
|
|
Precedence: bulk
|
|
Sender: pgsql-hackers-owner@postgresql.org
|
|
Status: OR
|
|
|
|
On Wed, Jul 17, 2002 at 03:57:56PM -0400, Tom Lane wrote:
|
|
> nconway@klamath.dyndns.org (Neil Conway) writes:
|
|
> > Should every elog() have an error code?
|
|
>
|
|
> I believe we decided that it'd be okay to use one or two codes defined
|
|
> like "internal error", "corrupted data", etc for all the elogs that are
|
|
> not-supposed-to-happen conditions.
|
|
|
|
Ok, makes sense to me.
|
|
|
|
> > How should the backend code signal an error with an error number?
|
|
>
|
|
> Please read some of the archived discussions about this. All the points
|
|
> you mention have been brought up before.
|
|
|
|
Woops -- I wasn't aware that this had been discussed before, my apologies.
|
|
I'm reading the archives now...
|
|
|
|
Peter: are you planning to implement this?
|
|
|
|
Cheers,
|
|
|
|
Neil
|
|
|
|
--
|
|
Neil Conway <neilconway@rogers.com>
|
|
PGP Key ID: DB3C29FC
|
|
|
|
---------------------------(end of broadcast)---------------------------
|
|
TIP 2: you can get off all lists at once with the unregister command
|
|
(send "unregister YourEmailAddressHere" to majordomo@postgresql.org)
|
|
|
|
From pgsql-hackers-owner+M25097@postgresql.org Wed Jul 17 18:04:36 2002
|
|
Return-path: <pgsql-hackers-owner+M25097@postgresql.org>
|
|
Received: from postgresql.org (postgresql.org [64.49.215.8])
|
|
by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id g6HM4Ze09359
|
|
for <pgman@candle.pha.pa.us>; Wed, 17 Jul 2002 18:04:35 -0400 (EDT)
|
|
Received: from postgresql.org (postgresql.org [64.49.215.8])
|
|
by postgresql.org (Postfix) with SMTP
|
|
id AD154475D78; Wed, 17 Jul 2002 18:04:29 -0400 (EDT)
|
|
Received: from candle.pha.pa.us (216-55-132-35.dsl.san-diego.abac.net [216.55.132.35])
|
|
by postgresql.org (Postfix) with ESMTP id 5541A475C95
|
|
for <pgsql-hackers@postgresql.org>; Wed, 17 Jul 2002 18:04:21 -0400 (EDT)
|
|
Received: (from pgman@localhost)
|
|
by candle.pha.pa.us (8.11.6/8.10.1) id g6HM4Hi09355;
|
|
Wed, 17 Jul 2002 18:04:17 -0400 (EDT)
|
|
From: Bruce Momjian <pgman@candle.pha.pa.us>
|
|
Message-ID: <200207172204.g6HM4Hi09355@candle.pha.pa.us>
|
|
Subject: Re: [HACKERS] error codes
|
|
In-Reply-To: <20020717182739.GB5542@klamath.dyndns.org>
|
|
To: Neil Conway <nconway@klamath.dyndns.org>
|
|
Date: Wed, 17 Jul 2002 18:04:17 -0400 (EDT)
|
|
cc: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
|
|
X-Mailer: ELM [version 2.4ME+ PL99 (25)]
|
|
MIME-Version: 1.0
|
|
Content-Type: multipart/mixed; boundary=ELM1026943457-25421-1_
|
|
Content-Transfer-Encoding: 7bit
|
|
Precedence: bulk
|
|
Sender: pgsql-hackers-owner@postgresql.org
|
|
Status: OR
|
|
|
|
--ELM1026943457-25421-1_
|
|
Content-Transfer-Encoding: 7bit
|
|
Content-Type: text/plain; charset=US-ASCII
|
|
|
|
|
|
Neil, attached are three email messages dealing with error message
|
|
wording.
|
|
|
|
I like Tom's idea of coding only the messages that are common/user
|
|
errors and leaving the others with a catch-all code.
|
|
|
|
We now have more elog levels in 7.3, so it should be easier to classify
|
|
the messages.
|
|
|
|
I can see this job as several parts:
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
Cleanup of error wording, removal of function names. See attached
|
|
emails for possible standard.
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
Reporting of file, line, function reporting using GUC/SET variable. For
|
|
function names I see in the gcc 3.1 docs at
|
|
http://gcc.gnu.org/onlinedocs/gcc-3.1/cpp/Standard-Predefined-Macros.html:
|
|
|
|
C99 introduces __func__, and GCC has provided __FUNCTION__ for a long
|
|
time. Both of these are strings containing the name of the current
|
|
function (there are slight semantic differences; see the GCC manual).
|
|
Neither of them is a macro; the preprocessor does not know the name of
|
|
the current function. They tend to be useful in conjunction with
|
|
__FILE__ and __LINE__, though.
|
|
|
|
My gcc 2.95 (gcc version 2.95.2 19991024) supports both __FUNCTION__ and
|
|
__func__, even though they are not documented in the info manual pages I
|
|
have. I think we will need a configure.in test for this because it
|
|
isn't a macro you can #ifdef.
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
Actual error code numbers/letters. I think the new elog levels will
|
|
help with this. We have to decide if we want error numbers, or some
|
|
pneumonic like NOATTR or CONSTVIOL. I suggest the latter.
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
I think we have plenty of time to get this done for 7.3.
|
|
|
|
--
|
|
Bruce Momjian | http://candle.pha.pa.us
|
|
pgman@candle.pha.pa.us | (610) 853-3000
|
|
+ If your life is a hard drive, | 830 Blythe Avenue
|
|
+ Christ can be your backup. | Drexel Hill, Pennsylvania 19026
|
|
|
|
--ELM1026943457-25421-1_
|
|
Content-Transfer-Encoding: 7bit
|
|
Content-Type: text/plain
|
|
Content-Disposition: inline; filename="/bjm/error"
|
|
|
|
>From pgsql-hackers-owner+M16120=candle.pha.pa.us=pgman@postgresql.org Fri Nov 30 12:14:19 2001
|
|
Return-path: <pgsql-hackers-owner+M16120=candle.pha.pa.us=pgman@postgresql.org>
|
|
Received: from rs.postgresql.org (server1.pgsql.org [64.39.15.238] (may be forged))
|
|
by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id fAUIEIR21802
|
|
for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 13:14:18 -0500 (EST)
|
|
Received: from postgresql.org (postgresql.org [64.49.215.8])
|
|
by rs.postgresql.org (8.11.6/8.11.6) with ESMTP id fAUI6ER13094
|
|
for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 12:11:00 -0600 (CST)
|
|
(envelope-from pgsql-hackers-owner+M16120=candle.pha.pa.us=pgman@postgresql.org)
|
|
Received: from moutvdom01.kundenserver.de (moutvdom01.kundenserver.de [195.20.224.200])
|
|
by postgresql.org (8.11.3/8.11.4) with ESMTP id fAUI58m98870
|
|
for <pgsql-hackers@postgresql.org>; Fri, 30 Nov 2001 13:05:08 -0500 (EST)
|
|
(envelope-from peter_e@gmx.net)
|
|
Received: from [195.20.224.208] (helo=mrvdom01.schlund.de)
|
|
by moutvdom01.kundenserver.de with esmtp (Exim 2.12 #2)
|
|
id 169s27-00049P-00
|
|
for pgsql-hackers@postgresql.org; Fri, 30 Nov 2001 19:05:07 +0100
|
|
Received: from p3e9e6fa2.dip0.t-ipconnect.de ([62.158.111.162])
|
|
by mrvdom01.schlund.de with esmtp (Exim 2.12 #2)
|
|
id 169s21-0001UP-00
|
|
for pgsql-hackers@postgresql.org; Fri, 30 Nov 2001 19:05:03 +0100
|
|
Date: Fri, 30 Nov 2001 19:12:16 +0100 (CET)
|
|
From: Peter Eisentraut <peter_e@gmx.net>
|
|
X-Sender: <peter@peter.localdomain>
|
|
To: PostgreSQL Development <pgsql-hackers@postgresql.org>
|
|
Subject: [HACKERS] Backend error message style issues
|
|
Message-ID: <Pine.LNX.4.30.0111292302020.609-100000@peter.localdomain>
|
|
MIME-Version: 1.0
|
|
Content-Type: TEXT/PLAIN; charset=US-ASCII
|
|
Precedence: bulk
|
|
Sender: pgsql-hackers-owner@postgresql.org
|
|
Status: ORr
|
|
|
|
Now that we've gone through nearly one development cycle with national
|
|
language support, I'd like to bring up a number of issues concerning the
|
|
style of the backend error messages that make life difficult, but probably
|
|
not only for the translators but for users as well. Not all of these are
|
|
strictly translation issues, but the message catalogs make for a good
|
|
overview of what's going on.
|
|
|
|
I hope we can work through all of these during the next development
|
|
period.
|
|
|
|
Prefixing messages with command names
|
|
-------------------------------------
|
|
|
|
For instance,
|
|
|
|
| CREATE DATABASE: permission denied
|
|
|
|
This "command: message" style is typical for command-line programs and
|
|
it's pretty useful there if you run many commands in a pipe. The same
|
|
usefulness could probably be derived if you run many SQL commands in a
|
|
function. (Just "permission denied" would be very confusing there!)
|
|
|
|
If we want to use that style we should make it consistent and we should
|
|
automate it. Via the "command tag" mechanism we already know what command
|
|
we're executing, so we can automatically prefix all messages that way. It
|
|
could even be switched off by the user if it's deemed annoying.
|
|
|
|
|
|
Prefixing messages with function names
|
|
--------------------------------------
|
|
|
|
The function names obviously have no meaning to the user. It is claimed
|
|
that they allow a developer to locate the place the error was raised
|
|
faster, but that's only half the truth. Firstly, this whole thing doesn't
|
|
work if the displayed name of the function was actually passed in from
|
|
elsewhere. Then it takes you three times longer to locate the source
|
|
because you *think* you know where it was but it's not there. Secondly,
|
|
a developer doesn't have the need to locate every error. For instance,
|
|
|
|
| ExecAppend: rejected due to CHECK constraint foo
|
|
|
|
There's no need to debug anything there, it's a perfectly normal use
|
|
situation.
|
|
|
|
I think the key here is to distinguish error messages that are perfectly
|
|
normal user-level events from messages which really represent an "assert
|
|
failure, but continue gracefully", such as
|
|
|
|
| initGISTstate: numberOfAttributes %d > %d
|
|
|
|
The latter could better be written something like
|
|
|
|
| BETTER_BE_TRUE(index->rd_att->natts > INDEX_MAX_KEYS);
|
|
|
|
we could lead to an error message in the style of an assert failure,
|
|
including the expression in question and file and line information (and
|
|
bug reporting suggestions). This way the developer doesn't have to write
|
|
any message text at all but still gets much better information to locate
|
|
the source. (E.g., note that the tested variable isn't even called
|
|
"numberOfAttributes".)
|
|
|
|
The exact API could be tuned to include some other information such as an
|
|
informal message, but I think something along these lines needs to be
|
|
worked out.
|
|
|
|
|
|
Quoting
|
|
-------
|
|
|
|
Which is better:
|
|
|
|
function '%s' not found
|
|
function "%s" not found
|
|
function %s not found
|
|
|
|
I think two kinds of quotes is looking messy. Personal suggestion:
|
|
double quotes.
|
|
|
|
|
|
Capitalization and punctuation
|
|
------------------------------
|
|
|
|
Which one?
|
|
|
|
ERROR: Permission denied.
|
|
ERROR: Permission denied
|
|
ERROR: permission denied
|
|
|
|
I have personally used the GNU-recommended way which is the third, mostly
|
|
just because it is *some* standardized way. I don't have a strong feeling
|
|
about the initial capitalization, but I'm against the periods except when
|
|
the message is really a sentence and it contains some other punctuation
|
|
(commas, etc.) or the message consists of more than one sentence.
|
|
|
|
|
|
Grammatical structure and choice of words
|
|
-----------------------------------------
|
|
|
|
There are many others besides the above choices:
|
|
|
|
ERROR: Permission was denied.
|
|
ERROR: You don't have permission to do <task>.
|
|
ERROR: Permission to do <task> was denied.
|
|
ERROR: <task>: Permission denied
|
|
|
|
In other cases there's a sea of possibilities:
|
|
|
|
couldn't find THING
|
|
can't find THING
|
|
THING wasn't found
|
|
unable to locate THING
|
|
lookup of THING failed
|
|
THING doesn't exist
|
|
|
|
Strictly speaking, there are at least four different meanings among those
|
|
six messages, yet they're used mostly randomly.
|
|
|
|
There are a number of things to think about here: active vs passive, can
|
|
vs could, complete sentence vs telegram style, use of colons, addressing
|
|
the user with "you [cannot...]".
|
|
|
|
And please let's not have the program talk in the "I"-form ("I have rolled
|
|
back the current transaction ...").
|
|
|
|
|
|
|
|
More esoteric discussions are also possible, but I'm going to postpone
|
|
those. ;-) However, I think it's worth working on this and perhaps
|
|
putting together a "manual of style" that applies to all parts of
|
|
PostgreSQL. This would significantly improve the overall perceived
|
|
quality. Some projects like KDE, GNU, and GCC have teams that discuss
|
|
these kinds of things and it's definitely showing.
|
|
|
|
--
|
|
Peter Eisentraut peter_e@gmx.net
|
|
|
|
|
|
---------------------------(end of broadcast)---------------------------
|
|
TIP 3: if posting/reading through Usenet, please send an appropriate
|
|
subscribe-nomail command to majordomo@postgresql.org so that your
|
|
message can get through to the mailing list cleanly
|
|
|
|
>From pgsql-hackers-owner+M16128=candle.pha.pa.us=pgman@postgresql.org Fri Nov 30 13:39:41 2001
|
|
Return-path: <pgsql-hackers-owner+M16128=candle.pha.pa.us=pgman@postgresql.org>
|
|
Received: from rs.postgresql.org (server1.pgsql.org [64.39.15.238] (may be forged))
|
|
by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id fAUJdfR29066
|
|
for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 14:39:41 -0500 (EST)
|
|
Received: from postgresql.org (postgresql.org [64.49.215.8])
|
|
by rs.postgresql.org (8.11.6/8.11.6) with ESMTP id fAUJXkR15701
|
|
for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 13:36:17 -0600 (CST)
|
|
(envelope-from pgsql-hackers-owner+M16128=candle.pha.pa.us=pgman@postgresql.org)
|
|
Received: from corvette.mascari.com (dhcp065-024-158-068.columbus.rr.com [65.24.158.68])
|
|
by postgresql.org (8.11.3/8.11.4) with ESMTP id fAUJMnm01940
|
|
for <pgsql-hackers@postgresql.org>; Fri, 30 Nov 2001 14:22:49 -0500 (EST)
|
|
(envelope-from mascarm@mascari.com)
|
|
Received: from mascari.com (ferrari.mascari.com [192.168.2.1])
|
|
by corvette.mascari.com (8.9.3/8.9.3) with ESMTP id OAA20637;
|
|
Fri, 30 Nov 2001 14:16:52 -0500
|
|
Message-ID: <3C07DBAD.A9735975@mascari.com>
|
|
Date: Fri, 30 Nov 2001 14:19:09 -0500
|
|
From: Mike Mascari <mascarm@mascari.com>
|
|
Organization: Mascari Development Inc.
|
|
X-Mailer: Mozilla 4.77 [en] (WinNT; U)
|
|
X-Accept-Language: en
|
|
MIME-Version: 1.0
|
|
To: Peter Eisentraut <peter_e@gmx.net>
|
|
cc: PostgreSQL Development <pgsql-hackers@postgresql.org>
|
|
Subject: Re: [HACKERS] Backend error message style issues
|
|
References: <Pine.LNX.4.30.0111292302020.609-100000@peter.localdomain>
|
|
Content-Type: text/plain; charset=us-ascii
|
|
Content-Transfer-Encoding: 7bit
|
|
Precedence: bulk
|
|
Sender: pgsql-hackers-owner@postgresql.org
|
|
Status: OR
|
|
|
|
Peter Eisentraut wrote:
|
|
>
|
|
> Now that we've gone through nearly one development cycle with national
|
|
> language support, I'd like to bring up a number of issues concerning the
|
|
> style of the backend error messages that make life difficult, but probably
|
|
> not only for the translators but for users as well. Not all of these are
|
|
> strictly translation issues, but the message catalogs make for a good
|
|
> overview of what's going on.
|
|
|
|
For what its worth, Oracle 8 ships with an error.txt file which
|
|
dictates the message standards to which their products comply.
|
|
Roughly:
|
|
|
|
Size Of Message:
|
|
---------------
|
|
|
|
Cannot exceed 76 characters, even when embedded format specifiers
|
|
are apart of the message. Only
|
|
start-up and system-dependent messages can exceed 76 characters.
|
|
|
|
Simple Language:
|
|
---------------
|
|
|
|
Use non-cryptic messages and overly technical language.
|
|
|
|
Upper vs. Lowercase:
|
|
-------------------
|
|
|
|
Use uppercase for commands and keywords, lowercase for message
|
|
wording, including the first letter (which agrees with your use,
|
|
Peter).
|
|
|
|
Commands, Keywords, Parameter Values:
|
|
------------------------------------
|
|
|
|
When possible, give the command, keyword and parameters used in the
|
|
message.
|
|
|
|
BAD: The relation could not be created
|
|
GOOD: CREATE TABLE failed for table "foo" because the disk is full
|
|
|
|
Period:
|
|
------
|
|
|
|
Do not end messages with a period (also agrees with your
|
|
conclusion).
|
|
|
|
Numbers:
|
|
-------
|
|
|
|
Don't enclose numbers with special characters. For example:
|
|
|
|
BAD: rows returned by subquery (3) exceeded limit (1)
|
|
GOOD: the subquery returned 3 rows exceeding the 1 row limit
|
|
|
|
Quotes:
|
|
------
|
|
|
|
Don't use single or double quotes to emphasize a text variable or
|
|
command
|
|
|
|
Single Quotes:
|
|
-------------
|
|
|
|
Never use them.
|
|
|
|
Double Quotes:
|
|
-------------
|
|
|
|
Always and only use them to identify database objects.
|
|
|
|
BAD: Unable to drop table employees
|
|
GOOD: DROP TABLE of "employees" failed due to referential integrity
|
|
constraints
|
|
|
|
Ellipses:
|
|
--------
|
|
|
|
Don't use them.
|
|
|
|
BAD: Unable to drop column mascarm.employees.salary
|
|
GOOD: ALTER TABLE was unable to drop the column "salary" table
|
|
"employees" schema "mascarm"
|
|
|
|
Parentheses:
|
|
-----------
|
|
|
|
Always and only use parentheses for constraint names
|
|
|
|
BAD: not null constraint ri_employees violated
|
|
GOOD: not null constraint (ri_employees) violated
|
|
|
|
Brackets:
|
|
--------
|
|
|
|
Always and only used for program arguments
|
|
|
|
Grammar:
|
|
-------
|
|
|
|
Use complete sentences whenever possible without the trailing
|
|
period. Don't use multiple sentences. Use the active voice. Don't
|
|
use an aggressive tone.
|
|
|
|
Style:
|
|
-----
|
|
|
|
Make positive suggestions. Explain what is invalid and what is
|
|
valid.
|
|
|
|
Example:
|
|
|
|
BAD: file name invalid
|
|
BETTER: COPY failed because the file name was too long
|
|
|
|
Routine names:
|
|
-------------
|
|
|
|
Do not use routine names in messages. Again, agrees with you, Peter.
|
|
|
|
FWIW,
|
|
|
|
Mike Mascari
|
|
mascarm@mascari.com
|
|
|
|
---------------------------(end of broadcast)---------------------------
|
|
TIP 1: subscribe and unsubscribe commands go to majordomo@postgresql.org
|
|
|
|
>From pgsql-hackers-owner+M16130=candle.pha.pa.us=pgman@postgresql.org Fri Nov 30 14:09:48 2001
|
|
Return-path: <pgsql-hackers-owner+M16130=candle.pha.pa.us=pgman@postgresql.org>
|
|
Received: from rs.postgresql.org (server1.pgsql.org [64.39.15.238] (may be forged))
|
|
by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id fAUK9lR02095
|
|
for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 15:09:48 -0500 (EST)
|
|
Received: from postgresql.org (postgresql.org [64.49.215.8])
|
|
by rs.postgresql.org (8.11.6/8.11.6) with ESMTP id fAUK3MR16820
|
|
for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 14:05:48 -0600 (CST)
|
|
(envelope-from pgsql-hackers-owner+M16130=candle.pha.pa.us=pgman@postgresql.org)
|
|
Received: from sss.pgh.pa.us ([192.204.191.242])
|
|
by postgresql.org (8.11.3/8.11.4) with ESMTP id fAUJnLm02954
|
|
for <pgsql-hackers@postgresql.org>; Fri, 30 Nov 2001 14:49:21 -0500 (EST)
|
|
(envelope-from tgl@sss.pgh.pa.us)
|
|
Received: from sss2.sss.pgh.pa.us (tgl@localhost [127.0.0.1])
|
|
by sss.pgh.pa.us (8.11.4/8.11.4) with ESMTP id fAUJnEi10307;
|
|
Fri, 30 Nov 2001 14:49:14 -0500 (EST)
|
|
To: Peter Eisentraut <peter_e@gmx.net>
|
|
cc: PostgreSQL Development <pgsql-hackers@postgresql.org>
|
|
Subject: Re: [HACKERS] Backend error message style issues
|
|
In-Reply-To: <Pine.LNX.4.30.0111292302020.609-100000@peter.localdomain>
|
|
References: <Pine.LNX.4.30.0111292302020.609-100000@peter.localdomain>
|
|
Comments: In-reply-to Peter Eisentraut <peter_e@gmx.net>
|
|
message dated "Fri, 30 Nov 2001 19:12:16 +0100"
|
|
Date: Fri, 30 Nov 2001 14:49:14 -0500
|
|
Message-ID: <10303.1007149754@sss.pgh.pa.us>
|
|
From: Tom Lane <tgl@sss.pgh.pa.us>
|
|
Precedence: bulk
|
|
Sender: pgsql-hackers-owner@postgresql.org
|
|
Status: OR
|
|
|
|
Peter Eisentraut <peter_e@gmx.net> writes:
|
|
> I hope we can work through all of these during the next development
|
|
> period.
|
|
|
|
Too bad we didn't do it *before* doing a lot of translation work :-(.
|
|
|
|
Yes, I agree that a pass of rationalizing the error messages would be
|
|
useful. Might want to think about that old bugaboo, error codes,
|
|
while we're at it. Also the perennial complaint that "ERROR" and
|
|
"DEBUG" macros tend to conflict with other things. As long as we're
|
|
going to touch many/all of the elog() calls, couldn't we try to clean
|
|
up all these issues?
|
|
|
|
> Which is better:
|
|
|
|
> function '%s' not found
|
|
> function "%s" not found
|
|
> function %s not found
|
|
|
|
Given that 'x' and "x" mean very different things in SQL, I think that
|
|
the first form is just plain wrong when an identifier is involved.
|
|
Unfortunately a lot of older code uses that style. I've tried to use
|
|
double quotes in new messages, but have restrained myself from wholesale
|
|
changes of existing messages.
|
|
|
|
> More esoteric discussions are also possible, but I'm going to postpone
|
|
> those. ;-) However, I think it's worth working on this and perhaps
|
|
> putting together a "manual of style" that applies to all parts of
|
|
> PostgreSQL. This would significantly improve the overall perceived
|
|
> quality.
|
|
|
|
Sounds like a plan to me: put together a style guide first, and then
|
|
make a pass through the code to try to implement it.
|
|
|
|
regards, tom lane
|
|
|
|
---------------------------(end of broadcast)---------------------------
|
|
TIP 1: subscribe and unsubscribe commands go to majordomo@postgresql.org
|
|
|
|
|
|
--ELM1026943457-25421-1_
|
|
Content-Type: text/plain
|
|
Content-Disposition: inline
|
|
Content-Transfer-Encoding: 8bit
|
|
MIME-Version: 1.0
|
|
|
|
|
|
---------------------------(end of broadcast)---------------------------
|
|
TIP 1: subscribe and unsubscribe commands go to majordomo@postgresql.org
|
|
|
|
--ELM1026943457-25421-1_--
|
|
|
|
From pgsql-hackers-owner+M25104@postgresql.org Wed Jul 17 18:30:49 2002
|
|
Return-path: <pgsql-hackers-owner+M25104@postgresql.org>
|
|
Received: from postgresql.org (postgresql.org [64.49.215.8])
|
|
by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id g6HMUme12537
|
|
for <pgman@candle.pha.pa.us>; Wed, 17 Jul 2002 18:30:48 -0400 (EDT)
|
|
Received: from postgresql.org (postgresql.org [64.49.215.8])
|
|
by postgresql.org (Postfix) with SMTP
|
|
id BF5D6475D9D; Wed, 17 Jul 2002 18:30:42 -0400 (EDT)
|
|
Received: from mail.gmx.net (mail.gmx.net [213.165.64.20])
|
|
by postgresql.org (Postfix) with SMTP id 20611475DCB
|
|
for <pgsql-hackers@postgresql.org>; Wed, 17 Jul 2002 18:30:35 -0400 (EDT)
|
|
Received: (qmail 9427 invoked by uid 0); 17 Jul 2002 22:30:37 -0000
|
|
Received: from pd902f0de.dip0.t-ipconnect.de (217.2.240.222)
|
|
by mail.gmx.net (mp007-rz3) with SMTP; 17 Jul 2002 22:30:37 -0000
|
|
Date: Thu, 18 Jul 2002 00:33:22 +0200 (CEST)
|
|
From: Peter Eisentraut <peter_e@gmx.net>
|
|
X-X-Sender: peter@localhost.localdomain
|
|
To: Neil Conway <nconway@klamath.dyndns.org>
|
|
cc: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
|
|
Subject: Re: [HACKERS] error codes
|
|
In-Reply-To: <20020717182739.GB5542@klamath.dyndns.org>
|
|
Message-ID: <Pine.LNX.4.44.0207172108290.9047-100000@localhost.localdomain>
|
|
MIME-Version: 1.0
|
|
Content-Type: TEXT/PLAIN; charset=US-ASCII
|
|
Precedence: bulk
|
|
Sender: pgsql-hackers-owner@postgresql.org
|
|
Status: OR
|
|
|
|
Neil Conway writes:
|
|
|
|
> I'd like to implement error codes. I think they would be pretty useful,
|
|
> although there are a few difficulties in the implementation I'd like
|
|
> to get some input on.
|
|
|
|
OK, allow me to pass on to you the accumulated wisdom on this topic. :-)
|
|
|
|
> Should every elog() have an error code?
|
|
|
|
The set of error codes should primarily be that defined by SQL99 part 2
|
|
clause 22 "Status codes" and PostgreSQL extensions that follow that
|
|
spirit. That means that all those "can't happen" or "all is lost anyway"
|
|
types should be lumped (perhaps in some implicit way) under "internal
|
|
error". That means, yes, an error code should be returned in every case
|
|
of an error, but it doesn't have to be a distinct error code for every
|
|
condition.
|
|
|
|
> How should the backend code signal an error with an error number?
|
|
|
|
> The problem here is that many errors will require more information
|
|
> that that, in order for the client to handle them properly. For
|
|
> example, how should a COPY indicate that an RI violation has
|
|
> occured? Ideally, we'd like to allow the client application to
|
|
> know that in line a, column b, the literal value 'c' was
|
|
> not found in the referenced column d of the referenced table d.
|
|
|
|
Precisely. You will find that SQL99 part 2 clause 19 "Diagnostics
|
|
management" defines all the fields that form part of a diagnostic (i.e.,
|
|
error or notice). This includes for example, fields that contain the name
|
|
and schema of the table that was involved, if appropriate. (Again,
|
|
appropriate PostgreSQL extensions could be made.) It is recommendable
|
|
that this scheme be followed, so PL/pgSQL and ECPG, to name some
|
|
candidates, could implement the GET DIAGNOSTICS statement as in the
|
|
standard. (Notice that, for example, a diagnostic still contains a text
|
|
message in addition to a code.)
|
|
|
|
> How should the error number be sent to the client, and would this
|
|
> require an FE/BE change? I think we can avoid that: including the
|
|
> error number in the error message itself, make PQgetErrorMessage()
|
|
> (and similar funcs) smart enough to remove the error number, and
|
|
> add a separate function (such as PQgetErrorNumber() ) to report
|
|
> the error number, if there is one.
|
|
|
|
I would advise against trying to cram everything into a string. Consider
|
|
the extra fields explained above. Consider being nice to old clients.
|
|
Also, libpq allows that more than one error message might arrive per query
|
|
cycle. Currently, the error messages are concatenated. That won't work
|
|
anymore. You need a new API anyway. You need a new API for notices, too.
|
|
|
|
One possiblity to justify a protocol change is to break something else
|
|
with it, like a new copy protocol.
|
|
|
|
> On a related note, it would be nice to get a consistent style of
|
|
> punctuation for elog() messages -- currently, some of them end
|
|
> in a period (e.g. "Database xxx does not exist in the system
|
|
> catalog."), while the majority do not. Which is better?
|
|
|
|
Yup, we've talked about that some time ago. I have a style guide mostly
|
|
worked out for discussion.
|
|
|
|
> It would be relatively easy to replace elog() with a macro of
|
|
> the form:
|
|
>
|
|
> #define elog(...) real_elog(__FILE__, __LINE__, __VA_ARGS__)
|
|
>
|
|
> And then adjust real_elog() to report that information as
|
|
> appropriate.
|
|
|
|
And it would be relatively easy to break every old compiler that way...
|
|
|
|
--
|
|
Peter Eisentraut peter_e@gmx.net
|
|
|
|
|
|
---------------------------(end of broadcast)---------------------------
|
|
TIP 6: Have you searched our list archives?
|
|
|
|
http://archives.postgresql.org
|
|
|
|
From pgsql-hackers-owner+M25114@postgresql.org Wed Jul 17 21:57:52 2002
|
|
Return-path: <pgsql-hackers-owner+M25114@postgresql.org>
|
|
Received: from postgresql.org (postgresql.org [64.49.215.8])
|
|
by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id g6I1vpe07438
|
|
for <pgman@candle.pha.pa.us>; Wed, 17 Jul 2002 21:57:52 -0400 (EDT)
|
|
Received: from postgresql.org (postgresql.org [64.49.215.8])
|
|
by postgresql.org (Postfix) with SMTP
|
|
id 0E63047593C; Wed, 17 Jul 2002 21:57:47 -0400 (EDT)
|
|
Received: from houston.familyhealth.com.au (i231-006.nv.iinet.net.au [203.59.231.6])
|
|
by postgresql.org (Postfix) with ESMTP id BA91F47585D
|
|
for <pgsql-hackers@postgresql.org>; Wed, 17 Jul 2002 21:57:41 -0400 (EDT)
|
|
Received: (from root@localhost)
|
|
by houston.familyhealth.com.au (8.11.6/8.11.6) id g6I1viW22817
|
|
for pgsql-hackers@postgresql.org; Thu, 18 Jul 2002 09:57:44 +0800 (WST)
|
|
(envelope-from chriskl@familyhealth.com.au)
|
|
Received: from mariner (mariner.internal [192.168.0.101])
|
|
by houston.familyhealth.com.au (8.11.6/8.9.3) with SMTP id g6I1vhV22728;
|
|
Thu, 18 Jul 2002 09:57:43 +0800 (WST)
|
|
From: "Christopher Kings-Lynne" <chriskl@familyhealth.com.au>
|
|
To: "Neil Conway" <nconway@klamath.dyndns.org>,
|
|
"PostgreSQL Hackers" <pgsql-hackers@postgresql.org>
|
|
Subject: Re: [HACKERS] error codes
|
|
Date: Thu, 18 Jul 2002 09:57:56 +0800
|
|
Message-ID: <GNELIHDDFBOCMGBFGEFOOEDECDAA.chriskl@familyhealth.com.au>
|
|
MIME-Version: 1.0
|
|
Content-Type: text/plain;
|
|
charset="us-ascii"
|
|
Content-Transfer-Encoding: 7bit
|
|
X-Priority: 3 (Normal)
|
|
X-MSMail-Priority: Normal
|
|
X-Mailer: Microsoft Outlook IMO, Build 9.0.2416 (9.0.2910.0)
|
|
In-Reply-To: <20020717182739.GB5542@klamath.dyndns.org>
|
|
X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2600.0000
|
|
Importance: Normal
|
|
X-scanner: scanned by Inflex 0.1.5c - (http://www.inflex.co.za/)
|
|
Precedence: bulk
|
|
Sender: pgsql-hackers-owner@postgresql.org
|
|
Status: OR
|
|
|
|
> Should every elog() have an error code? I'm not sure -- there are many
|
|
> elog() calls that will never been seen by the user, since the error
|
|
> they represent will be caught before control reaches the elog (e.g.
|
|
> parse errors, internal consistency checks, multiple elog(ERROR)
|
|
> for the same user error, etc.) Perhaps for those error messages
|
|
> that don't have numbers, we could just give them ERRNO_UNKNOWN or
|
|
> a similar constant.
|
|
|
|
It might be cool to a little command utility "pg_error" or whatever that you
|
|
pass an error code to and it prints out a very detailed description of the
|
|
problem...
|
|
|
|
Chris
|
|
|
|
|
|
---------------------------(end of broadcast)---------------------------
|
|
TIP 6: Have you searched our list archives?
|
|
|
|
http://archives.postgresql.org
|
|
|
|
From pgsql-hackers-owner+M25119@postgresql.org Thu Jul 18 04:01:40 2002
|
|
Return-path: <pgsql-hackers-owner+M25119@postgresql.org>
|
|
Received: from postgresql.org (postgresql.org [64.49.215.8])
|
|
by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id g6I81de14995
|
|
for <pgman@candle.pha.pa.us>; Thu, 18 Jul 2002 04:01:40 -0400 (EDT)
|
|
Received: from postgresql.org (postgresql.org [64.49.215.8])
|
|
by postgresql.org (Postfix) with SMTP
|
|
id 38C49475E0D; Thu, 18 Jul 2002 04:01:33 -0400 (EDT)
|
|
Received: from smxsat1.smxs.net (smxsat1.smxs.net [213.150.10.1])
|
|
by postgresql.org (Postfix) with ESMTP id 82A1B475DB6
|
|
for <pgsql-hackers@postgresql.org>; Thu, 18 Jul 2002 04:01:26 -0400 (EDT)
|
|
Received: from m01x1.s-mxs.net [10.3.55.201]
|
|
by smxsat1.smxs.net
|
|
over TLS secured channel
|
|
with XWall v3.21e ;
|
|
Thu, 18 Jul 2002 10:01:23 +0200
|
|
Received: from m0102.s-mxs.net [10.3.55.2]
|
|
by m01x1.s-mxs.net
|
|
with XWall v3.21b ;
|
|
Thu, 18 Jul 2002 10:01:21 +0200
|
|
Received: from m0114.s-mxs.net ([10.3.55.14]) by m0102.s-mxs.net with Microsoft SMTPSVC(5.0.2195.4453);
|
|
Thu, 18 Jul 2002 10:01:20 +0200
|
|
X-MimeOLE: Produced By Microsoft Exchange V6.0.5762.3
|
|
content-class: urn:content-classes:message
|
|
MIME-Version: 1.0
|
|
Content-Type: text/plain;
|
|
charset="iso-8859-1"
|
|
Subject: Re: [HACKERS] error codes
|
|
Date: Thu, 18 Jul 2002 10:01:20 +0200
|
|
Message-ID: <46C15C39FEB2C44BA555E356FBCD6FA4961E24@m0114.s-mxs.net>
|
|
Thread-Topic: [HACKERS] error codes
|
|
Thread-Index: AcIt3fXLfLUm5ueDTfKp02tm+iyO0AAUPF/Q
|
|
From: "Zeugswetter Andreas SB SD" <ZeugswetterA@spardat.at>
|
|
To: "Bruce Momjian" <pgman@candle.pha.pa.us>,
|
|
"Neil Conway" <nconway@klamath.dyndns.org>
|
|
cc: "PostgreSQL Hackers" <pgsql-hackers@postgresql.org>
|
|
X-OriginalArrivalTime: 18 Jul 2002 08:01:20.0584 (UTC) FILETIME=[4D5A6480:01C22E31]
|
|
Precedence: bulk
|
|
Sender: pgsql-hackers-owner@postgresql.org
|
|
Content-Transfer-Encoding: 8bit
|
|
X-MIME-Autoconverted: from quoted-printable to 8bit by candle.pha.pa.us id g6I81de14995
|
|
Status: ORr
|
|
|
|
|
|
Bruce wrote:
|
|
> Actual error code numbers/letters. I think the new elog levels will
|
|
> help with this. We have to decide if we want error numbers, or some
|
|
> pneumonic like NOATTR or CONSTVIOL. I suggest the latter.
|
|
|
|
Since there is an actual standard for error codes, I would strongly suggest
|
|
to adhere. The standardized codes are SQLSTATE a char(5) (well standardized
|
|
for many classes of db errors). Also common, but not so standardized is SQLCODE
|
|
a long (only a very few are standardized, like 100 = 'no data found').
|
|
And also sqlca. Also look at ecpg for sqlcode and sqlca.
|
|
|
|
A Quote from dec rdb:
|
|
--------------------------------------------------------------------
|
|
o SQLCODE-This is the original SQL error handling mechanism.
|
|
It is an integer value. SQLCODE differentiates among errors
|
|
(negative numbers), warnings (positive numbers), succesful
|
|
completion (0), and a special code of 100, which means no
|
|
data. SQLCODE is a deprecated feature of the ANSI/ISO SQL
|
|
standard.
|
|
|
|
o SQLCA-This is an extension of the SQLCODE error handling
|
|
mechanism. It contains other context information that
|
|
supplements the SQLCODE value. SQLCA is not part of the
|
|
ANSI/ISO SQL standard. However, many foreign databases such
|
|
as DB2 and ORACLE RDBMS have defined proprietary semantics and
|
|
syntax to implement it.
|
|
|
|
o SQLSTATE-This is the error handling mechanism for the ANSI/ISO
|
|
SQL standard. The SQLSTATE value is a character string that is
|
|
associated with diagnostic information. To use the SQLSTATE
|
|
status parameter, you must specify the SQL92 dialect and
|
|
compile your module using DEC Rdb Version 6.0.
|
|
--------------------------------------------------------------------
|
|
|
|
Andreas
|
|
|
|
---------------------------(end of broadcast)---------------------------
|
|
TIP 4: Don't 'kill -9' the postmaster
|
|
|