Skip to content

Add a default value for serial consistency: LocalSerial #291

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 3, 2021

Conversation

psarna
Copy link
Contributor

@psarna psarna commented Sep 17, 2021

This series adds a default serial consistency level for queries - LocalSerial. The decision is based on the fact that LocalSerial is the one that provides acceptable performance. Users interested in strong, cross-dc consistency - which could also cause prohibitive latencies - should override to Serial.

The series also comes with a doc entry which briefly explains LWT queries (they weren't mentioned at all so far), as well as an extra validation layer which would prevent users from setting a wrong consistency level, without introducing any backward incompatible changes.

This series introduces a breaking change - serial consistency is now defined as a separate enum. Fixing the existing aplications is trivial and consists of replacing all occurrences of Consistency::LocalSerial to SerialConsistency::LocalSerial and Consistency::Serial to SerialConsistency::Serial.

Fixes #277

Pre-review checklist

  • I have split my patch into logically separate commits.
  • All commit messages clearly explain what they change and why.
  • I added relevant tests for new features and bug fixes.
  • All commits compile, pass static checks and pass test.
  • PR description sums up the changes and reasons why they should be introduced.
  • I added appropriate Fixes: annotations to PR description.

@psarna psarna requested a review from piodul September 17, 2021 07:40
pub fn validate_serial(cl: &Option<Self>) {
match cl {
None | Some(Consistency::Serial) | Some(Consistency::LocalSerial) => (),
_ => panic!("Serial consistency can only be set to Serial or LocalSerial"),
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

By the way, I wonder if we couldn't split the Consistency type into a regular Consistency + SerialConsistency - there would be no need for runtime validation and less confusion for the users. Does it make sense to set Serial or LocalSerial for regular consistency?

On the other hand other drivers always seem to use the same consistency level type both for regular and serial consistency, maybe there is a good reason for that...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That would indeed be best, but that's also why I mentioned maintaining backward compatibility - existing code could break for some users. That's why I went with a runtime check.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sigh, on the other hand, we're still in 0.x, so we can make breaking changes, and it makes so much sense to split the types... they are absolutely mutually exclusive, as it's also not legal to set a LOCAL_SERIAL level to the regular consistency level. I'll rework this pull request to make this breaking change and send it for review.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's also no point in following other drivers in that matter - if anything, our solution would just be more comprehensible to the users. It's ultimately CQL's fault that these levels were standardized in such a weird manner.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kostja Could you comment on #291 (comment) ? The rust driver has a type which represents the CQL's [consistency], but would like to split it into two - one which has SERIAL and LOCAL_SERIAL consistency levels, and one which has the others. Is there a good reason not to do that? I don't think any other driver which I know does that, but I'm not sure if there is a good reason behind that.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would be wonderful if there are two distinct types.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think go driver went that path

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SERIAL and LOCAL-SERIAL should be part of Consistency data type, but it's best to make SerialConsistency a distinct type to avoid programming bugs.

@@ -53,6 +53,7 @@ impl Batch {
/// Sets the serial consistency to be used when executing this batch.
/// (Ignored unless the batch is an LWT)
pub fn set_serial_consistency(&mut self, sc: Option<Consistency>) {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we decide not to split the Consistency type, it would be nice if the set_serial_consistency functions would have a comment which warns that the function will panic if the consistency level is invalid.

@psarna psarna force-pushed the serial_consistency_default branch from ffd22ab to 787f880 Compare September 17, 2021 10:46
@psarna
Copy link
Contributor Author

psarna commented Sep 17, 2021

v2:

  • instead of runtime checks, split the types so that the compiler can check correctness for us

This breaking change splits the Consistency enum into two:
 - Consistency, used for all queries
 - SerialConsistency, an additional flag used only
   for lightweight transactions

The reason for the split is that these values are mutually exclusive:
 - it's only legal to use serial consistency for LWT, and it's not
possible to use it in any other scope. Respectively, it's not possible
to use any of the regular consistency values for defining serial
consistency.
... to improve user experience. Serial consistency level can be
reset to stronger, cross-DC consistency by calling
set_serial_consistency explicitly.
@psarna psarna force-pushed the serial_consistency_default branch from 787f880 to c1e8293 Compare November 3, 2021 07:51
@psarna
Copy link
Contributor Author

psarna commented Nov 3, 2021

@piodul rebased, review ping

@psarna
Copy link
Contributor Author

psarna commented Nov 3, 2021

There's some clash with a recent bump of docs version, I'll debug. Meanwhile, the code itself is still reviewable

The entry explains that lightweight transaction queries are
almost like regular queries, except they have a serial consistency level
in addition to the regular consistency level.
@psarna psarna force-pushed the serial_consistency_default branch from c1e8293 to 70a4cd1 Compare November 3, 2021 08:01
Copy link
Collaborator

@piodul piodul left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Consider adding a default serial consistency level
3 participants