Details
-
Improvement
-
Status: Open
-
Normal
-
Resolution: Unresolved
Description
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.
Attachments
Attachments
Issue Links
- is duplicated by
-
-
- Resolved
-