cli: promote the 5-character error codes in the error outputs #42779
Conversation
|
This change is |
|
cc @rmloveland this is what we discussed last week over your schema change PR. |
knz
force-pushed
the
20191126-cli-errs
branch
2 times, most recently
from
cff16b4
to
0666e5d
Compare
tldr: This patch opens a new era in the relationship between CockroachDB and its users by acknowledging the existence of SQLSTATE in the error outputs produced by CLI commands. Before: ``` root@127.0.0.1:61772/movr> select * from u; pq: relation "u" does not exist ``` After: ``` root@127.0.0.1:61772/movr> select * from u; ERROR: relation "u" does not exist SQLSTATE: 42P01 ``` Background: The SQL standard specifies that servers should signal errors to clients with both an explanatory text and a 5-character "SQLSTATE" code. Certain of these codes are even standardized. The purpose of these codes is to facilitate both troubleshooting by end-users and easier searching for resources about what to do under certain errors. PostgreSQL makes consistent use of these 5-digit codes; they are always communicated to clients as a special payload in the postgres wire protocol. In fact, CockroachDB has started ever since version 2.0 to imitate PostgreSQL and try an produce similar codes in similar circumstances. Unfortunately, CockroachDB's own SQL shell does not show SQLSTATE codes to the user and this fails to teach users about their existence. Moreover, users who build automation without knowing about SQLSTATE codes get tempted to rely on the text of the error message instead. This is undesirable because we wish to be able to improve error messages (to clarify them over time) and only promise more stability guarantees on the SQLSTATE. This patch improve supon this situation by promoting SQLSTATE in the default output of CLI commands. Additional reading resources: - https://www.postgresql.org/docs/12/errcodes-appendix.html - https://en.wikipedia.org/wiki/SQLSTATE Additionally, in order to prepare for the upcoming `pgx` migration, the `pq: ` prefix to error generated by `lib/pq` is stripped out. It is replaced by the "Severity" field of the pgwire error packet, if available. Release note (cli change): the various CLI commands that use SQL now display errors using a new display format that emphasizes the 5-digit SQLSTATE code. Users are encouraged to combine these codes together with the error message when seeking help or troubleshooting.
knz
force-pushed
the
20191126-cli-errs
branch
from
0666e5d
to
0917dcc
Compare
|
I question whether this is the right thing by default. As you know, in I already find our output more verbose then necessary (timings on by default) - do we want this on by default as well? I suppose it's just for errors, so why not? |
Yeah I'm on the fence about this. OTOH I really want users to start googling SQLSTATE codes more than the error texts, that will make their life easier. Not so easy if it's not printed by default. As another data point, the
For timings this was a feature ask, which did receive positive feedback. Do you think we could tweak it? I recall the need was to display how two "perceptually fast" things are not equally fast, and invite the user to think about indexes early. Do you think we can achieve this in a different way?
Yeah that's what I'm thinking about as well. |
|
Okay, I take it back - I think since it's on error only, I'm okay with it. Maybe we need to dress it up a little bit though. SQLSTATE is meaningless to most people, right? |
It's meaningless to many engineers on our team but that's really a blindspot particular to CRL. The amount and quality of help you get on internet search engines when you use "SQLSTATE" and a code in your query is amazing. SQL users probably know a great deal more about it than we do. |
|
FWIW I love this change - at least on macOS, I can quickly:
|
|
TFYR! bors r+ |
42779: cli: promote the 5-character error codes in the error outputs r=knz a=knz tldr: This patch opens a new era in the relationship between CockroachDB and its users by acknowledging the existence of SQLSTATE in the error outputs produced by CLI commands. Before: ``` root@127.0.0.1:61772/movr> select * from u; pq: relation "u" does not exist ``` After: ``` root@127.0.0.1:61772/movr> select * from u; ERROR: relation "u" does not exist SQLSTATE: 42P01 ``` Background: The SQL standard specifies that servers should signal errors to clients with both an explanatory text and a 5-character "SQLSTATE" code. Certain of these codes are even standardized. The purpose of these codes is to facilitate both troubleshooting by end-users and easier searching for resources about what to do under certain errors. PostgreSQL makes consistent use of these 5-digit codes; they are always communicated to clients as a special payload in the postgres wire protocol. In fact, CockroachDB has started ever since version 2.0 to imitate PostgreSQL and try an produce similar codes in similar circumstances. Unfortunately, CockroachDB's own SQL shell does not show SQLSTATE codes to the user and this fails to teach users about their existence. Moreover, users who build automation without knowing about SQLSTATE codes get tempted to rely on the text of the error message instead. This is undesirable because we wish to be able to improve error messages (to clarify them over time) and only promise more stability guarantees on the SQLSTATE. This patch improve supon this situation by promoting SQLSTATE in the default output of CLI commands. Additional reading resources: - https://www.postgresql.org/docs/12/errcodes-appendix.html - https://en.wikipedia.org/wiki/SQLSTATE Additionally, in order to prepare for the upcoming `pgx` migration, the `pq: ` prefix to error generated by `lib/pq` is stripped out. It is replaced by the "Severity" field of the pgwire error packet, if available. Release note (cli change): the various CLI commands that use SQL now display errors using a new display format that emphasizes the 5-digit SQLSTATE code. Users are encouraged to combine these codes together with the error message when seeking help or troubleshooting. Co-authored-by: Raphael 'kena' Poss <knz@thaumogen.net>
Build succeeded |
tldr: This patch opens a new era in the relationship between
CockroachDB and its users by acknowledging the existence of SQLSTATE
in the error outputs produced by CLI commands.
Before:
After:
Background:
The SQL standard specifies that servers should signal errors to
clients with both an explanatory text and a 5-character "SQLSTATE"
code. Certain of these codes are even standardized. The purpose of
these codes is to facilitate both troubleshooting by end-users and
easier searching for resources about what to do under certain
errors.
PostgreSQL makes consistent use of these 5-digit codes; they are
always communicated to clients as a special payload in the postgres
wire protocol. In fact, CockroachDB has started ever since version 2.0
to imitate PostgreSQL and try an produce similar codes in similar
circumstances.
Unfortunately, CockroachDB's own SQL shell does not show SQLSTATE
codes to the user and this fails to teach users about their existence.
Moreover, users who build automation without knowing about SQLSTATE
codes get tempted to rely on the text of the error message
instead. This is undesirable because we wish to be able to improve
error messages (to clarify them over time) and only promise more
stability guarantees on the SQLSTATE.
This patch improve supon this situation by promoting SQLSTATE
in the default output of CLI commands.
Additional reading resources:
Additionally, in order to prepare for the upcoming
pgxmigration,the
pq:prefix to error generated bylib/pqis stripped out. Itis replaced by the "Severity" field of the pgwire error packet, if
available.
Release note (cli change): the various CLI commands that use SQL now
display errors using a new display format that emphasizes the 5-digit
SQLSTATE code. Users are encouraged to combine these codes together
with the error message when seeking help or troubleshooting.