Skip to content

Clarified the order of watch events for TXN operations #984

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.

Sign up for GitHub

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Clarified the order of watch events for TXN operations #984

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion content/en/docs/v3.4/learning/api_guarantees.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,11 @@ KV Service operations are atomic and occur in a total order, consistent with
real-time order of those operations. Total order is implied through [revision].
Read more about [strict serializability].

For transactions without nested TXNs, the order of execution of operations
is guaranteed to be the same as in its list of operations, which means stable
GET responses within the transaction.
For transactions with nested TXNs, the order of execution is not specified.

Strict serializability implies other weaker guarantees that might be easier to understand:

#### Atomicity
Expand Down Expand Up @@ -87,7 +92,10 @@ removes the performance penalty of linearized accesses' reliance on live consens
Watches make guarantees about events:
* Ordered - events are ordered by revision.
An event will never appear on a watch if it precedes an event in time that
has already been posted.
has already been posted. For transactions without nested TXNs, the order of
generated events is guaranteed to be the same as in its list of operations.
For transactions with nested TXNs, the order of generated events is not
specified.
* Unique - an event will never appear on a watch twice.
* Reliable - a sequence of events will never drop any subsequence of events
within the available history window. If there are events ordered in time as
Expand Down
10 changes: 9 additions & 1 deletion content/en/docs/v3.5/learning/api_guarantees.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,11 @@ KV Service operations are atomic and occur in a total order, consistent with
real-time order of those operations. Total order is implied through [revision].
Read more about [strict serializability].

For transactions without nested TXNs, the order of execution of operations
is guaranteed to be the same as in its list of operations, which means stable
GET responses within the transaction.
For transactions with nested TXNs, the order of execution is not specified.

Strict serializability implies other weaker guarantees that might be easier to understand:

#### Atomicity
Expand Down Expand Up @@ -87,7 +92,10 @@ removes the performance penalty of linearized accesses' reliance on live consens
Watches make guarantees about events:
* Ordered - events are ordered by revision.
An event will never appear on a watch if it precedes an event in time that
has already been posted.
has already been posted. For transactions without nested TXNs, the order of
generated events is guaranteed to be the same as in its list of operations.
For transactions with nested TXNs, the order of generated events is not
specified.
* Unique - an event will never appear on a watch twice.
* Reliable - a sequence of events will never drop any subsequence of events
within the available history window. If there are events ordered in time as
Expand Down
10 changes: 9 additions & 1 deletion content/en/docs/v3.6/learning/api_guarantees.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,11 @@ KV Service operations are atomic and occur in a total order, consistent with
real-time order of those operations. Total order is implied through [revision].
Read more about [strict serializability].

For transactions without nested TXNs, the order of execution of operations
is guaranteed to be the same as in its list of operations, which means stable
GET responses within the transaction.
For transactions with nested TXNs, the order of execution is not specified.

Strict serializability implies other weaker guarantees that might be easier to understand:

#### Atomicity
Expand Down Expand Up @@ -87,7 +92,10 @@ removes the performance penalty of linearized accesses' reliance on live consens
Watches make guarantees about events:
* Ordered - events are ordered by revision.
An event will never appear on a watch if it precedes an event in time that
has already been posted.
has already been posted. For transactions without nested TXNs, the order of
generated events is guaranteed to be the same as in its list of operations.
For transactions with nested TXNs, the order of generated events is not
specified.
* Unique - an event will never appear on a watch twice.
* Reliable - a sequence of events will never drop any subsequence of events
within the available history window. If there are events ordered in time as
Expand Down
10 changes: 9 additions & 1 deletion content/en/docs/v3.7/learning/api_guarantees.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,11 @@ KV Service operations are atomic and occur in a total order, consistent with
real-time order of those operations. Total order is implied through [revision].
Read more about [strict serializability].

For transactions without nested TXNs, the order of execution of operations
is guaranteed to be the same as in its list of operations, which means stable
GET responses within the transaction.
For transactions with nested TXNs, the order of execution is not specified.

Strict serializability implies other weaker guarantees that might be easier to understand:

#### Atomicity
Expand Down Expand Up @@ -87,7 +92,10 @@ removes the performance penalty of linearized accesses' reliance on live consens
Watches make guarantees about events:
* Ordered - events are ordered by revision.
An event will never appear on a watch if it precedes an event in time that
has already been posted.
has already been posted. For transactions without nested TXNs, the order of
generated events is guaranteed to be the same as in its list of operations.
For transactions with nested TXNs, the order of generated events is not
Copy link
Member

@serathius serathius Jul 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Again I'm against about over specifying this. Users should apply single revisions atomically and not depend on order of operations within a TXN.

Copy link
Member

Choose a reason for hiding this comment

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

To be more specific, I don't care about enough to argue. But don't expect me to help maintain a guarantee that is useless and has zero testing and might impede development/optimization of etcd in the future.

Copy link
Member

Choose a reason for hiding this comment

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

that is useless

Why do you think it's useless? Read the 3rd item in #984 (comment). Also FYI in a broader database industry, the order of commands in one transaction is guaranteed by MVCC/visibility check.

has zero testing

I agree it's a gap that we need to resolve.

Copy link
Member

@serathius serathius Jul 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Also FYI in a broader database industry, the order of commands in one transaction is guaranteed by MVCC/visibility check.

We should not compare etcd TXN with database transactions, it's closer to single UPDATE statement with WHERE condition. When I execute a UPDATE request on SQL database I don't know nor care in which order the rows were updated.

This is because in both cases such operation should not touch a single row/key twice.

Copy link
Member

Choose a reason for hiding this comment

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

When I execute a UPDATE request on SQL database I don't know nor care in which order the rows were updated.

This is because in both cases such operation should not touch a single row/key twice.

It seems that we are not talking the same thing. We are discussing the execution order of commands/operations in one transaction, not the the about data/rows the commands are updating.

Copy link
Author

@socketpair socketpair Jul 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

@serathius

We should not compare etcd TXN with database transactions

SQL databases typically don't have modification notifications. It would be nice if Etcd could send ONE BIG event for whole TXN transactions. But it's not so! Instead, it sends a sequence of events. Yes, with revisions, but a sequence (!). That's why I want the order to be clarified.

it's closer to single UPDATE statement with WHERE condition

Yes, but we have GET requests in TXN list of operations.

specified.
* Unique - an event will never appear on a watch twice.
* Reliable - a sequence of events will never drop any subsequence of events
within the available history window. If there are events ordered in time as
Expand Down