[
https://issues.apache.org/jira/browse/CASSANDRA-9202?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Sylvain Lebresne updated CASSANDRA-9202:
----------------------------------------
Assignee: (was: Benjamin Lerer)
> Introduce CQL Error Codes
> -------------------------
>
> Key: CASSANDRA-9202
> URL: https://issues.apache.org/jira/browse/CASSANDRA-9202
> Project: Cassandra
> Issue Type: Improvement
> Reporter: Michaël Figuière
> Fix For: 3.x
>
>
> As features have been added or modified over the past years, the constraints
> applied on the CQL language itself have evolved rapidly, making it
> challenging for users, but also for documentation writers, testers and
> developers tools developers to keep up with what's possible or not, but also
> to understand the meaning of each error message and the rule behind it.
> Besides it, as error messages for any single error may change over time to
> fix a typo or to rephrase it, they cannot be used as a stable reference of
> errors.
> It feels like the right time to make error handling more formal in Cassandra,
> by introducing a very classic mechanism in the database world: error codes.
> The purpose of this ticket is to introduce these codes, but *does not* cover
> the way they should then be exposed. Bellow is my proposition along with the
> strategy I used:
> *Gathering Cassandra errors*
> I've walked through the source of all the past releases of Cassandra its git
> repo using a script in order to capture all the CQL related
> {{InvalidRequestException}} that are thrown. Considering it represents most
> of the CQL errors that may be returned by Cassandra.
> Bellow is the list of all errors that have been introduced and modified
> between Cassandra 1.2.0 and the current trunk:
> https://gist.github.com/mfiguiere/3036c2a54af016bbeb58
> The complete list of CQL errors declared in each Cassandra source file, along
> with the range of versions in which they appeared is as follow:
> https://gist.github.com/mfiguiere/42166586647c34b1a41c
> That's a lot of them... Clearly we can only focus on Cassandra 3.0+ here,
> that is on the current trunk.
> *Categorizing errors*
> It's common for database to categorize errors in order to make it simpler for
> the user to understand its nature or to walk through a list of them:
> * PostgreSQL
> (http://www.postgresql.org/docs/9.4/static/errcodes-appendix.html)
> * MySQL (http://dev.mysql.com/doc/refman/5.6/en/error-messages-server.html)
> * Oracle (http://docs.oracle.com/cd/B28359_01/server.111/b28278/toc.htm)
> One issue that can be observed in these 3 examples is that the codes they use
> are fairly cryptic and not really readable.
> It felt to me that a categorization by feature would be helpful for
> Cassandra. And rather than building hexadecimal prefixes, let's use readable
> string ones. We then end up with the following list of CQL error codes:
> https://gist.github.com/mfiguiere/7a19f8368b3ab4fbef3a
> That's about 260 errors overall for the current trunk, but broken into
> categories it feels to me that it remains very easy to browse and review.
> *Native Protocol Error Codes vs. CQL Error Codes*
> We actually already introduced the concept of error codes into the Native
> Protocol specification. These codes represent execution exceptions and are
> used by the clients to understand the kind of problem that occurred.
> I propose to rename these error codes to "Execution Error Codes" and to
> introduce with this ticket "CQL Error Codes", as they address two different
> kind of issues and audiences.
> *Introducing CQL Error Codes*
> Once an agreement will be reached on the list of error the strategy to
> introduce them into the codebase would be as follow:
> 1. We have to wait until CASSANDRA-8099 is merged, as it'll significantly
> change the way Exceptions are manipulated in the CQL codebase.
> 2. We introduce a {{cql_errors.spec}} file that defines the list of all CQL
> errors that may be thrown by Cassandra.
> 3. We modify the sources to introduce the appropriate cqlErrorCode along with
> any error that is declared.
> 4. Once merged, any subsequent addition or modification of an error in the
> sources in the future should lead to the appropriate mutation of the
> {{cql_errors.spec}} file in order to keep it in sync.
> *Benefits*
> I see several benefits in this approach:
> * Provides an immediate, comprehensive documentation of the CQL Errors (and
> thus the corresponding rules and constraints).
> * Easy to maintain. Easy to repair in case of missed update through some
> greps in the codebase.
> * Being guaranteed to be maintained, it can serve as a solid reference for
> any of the more detailed documentation that are produced (CQL spec, Cassandra
> doc,...).
> * Provides a clear summary of the errors thrown by each features of
> Cassandra, making it simple to catch inconsistencies, lack of normalization,
> and duplicates.
> * Will enable easier implementation of sophisticated features in monitoring
> and developer tools such as counters of error codes, help for errors sent by
> Cassandra, external CQL validation, ...
> * SEO / StackOverflow friendly.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
