MySQL 8.0.31
Source Code Documentation
Expectations

Topics in this section:

With the use of pipelining in the X Protocol (sending messages without waiting for successful response) only so many messages can be pipelined without causing havoc if one of the pipelined, dependent messages fails:

Mysqlx.Crud::PrepareFind(stmt_id=1, ...) // may fail
Mysqlx.PreparedStmt::Execute(stmt_id=1, ...) // would fail implicitly as stmt_id=1 doesn't exist
Mysqlx.PreparedStmt::Close(stmt_id=1) // would fail implicitly as stmt_id=1 doesn't exist

While implicitly failing is one thing, there are situations where it isn't that obvious what will happen:

Mysqlx.Crud::PrepareInsert(stmt_id=1, ...) // ok
Mysqlx.PreparedStmt::Execute(stmt_id=1, ...) // ok
Mysqlx.PreparedStmt::Execute(stmt_id=1, ...) // duplicate key error
Mysqlx.PreparedStmt::Execute(stmt_id=1, ...) // what now? abort the insert? ignore?
Mysqlx.PreparedStmt::Close(stmt_id=1) // close the stmt_id

Setting Expectations

Expectations let statements fail reliably until the end of the block.

Assume the PrepareFind fails:

  • don't execute the Execute
  • don't try to close the stmt
Mysqlx.Expect::Open([+no_error])
Mysqlx.Crud::PrepareFind(stmt_id=1, ...) // may fail
Mysqlx.PreparedStmt::Execute(stmt_id=1, ...) // expectation(no_error) failed
Mysqlx.PreparedStmt::Close(stmt_id=1) // expectation(no_error) failed
Mysqlx.Expect::Close()

But this would also skip the close if execute fails. Not what we want. Adding another expect-block handles it:

Mysqlx.Expect::Open([+no_error])
Mysqlx.Crud::PrepareFind(stmt_id=1, ...) // may fail
Mysqlx.Expect::Open([+no_error])
Mysqlx.PreparedStmt::Execute(stmt_id=1, ...) // expectation(no_error) failed
Mysqlx.Expect::Close()
Mysqlx.PreparedStmt::Close(stmt_id=1) // expectation(no_error) failed
Mysqlx.Expect::Close()

With these expectations pipelined, the server will handle errors in a consistent, reliable way.

It also allows to express how a streaming insert would behave if one of the inserts fails (for example: duplicate key error, disk full, and so on):

Either fail at first error:

Mysqlx.Expect::Open([+no_error])
Mysqlx.Crud::PrepareInsert(stmt_id=1, ...) // ok
Mysqlx.Expect::Open([+no_error])
Mysqlx.PreparedStmt::Execute(stmt_id=1, ...) // ok
Mysqlx.PreparedStmt::Execute(stmt_id=1, ...) // duplicate_key error
Mysqlx.PreparedStmt::Execute(stmt_id=1, ...) // expectation(no_error) failed
Mysqlx.PreparedStmt::Execute(stmt_id=1, ...) // expectation(no_error) failed
Mysqlx.Expect::Close()
Mysqlx.PreparedStmt::Close(stmt_id=1) // ok
Mysqlx.Expect::Close()

Or ignore error and continue:

Mysqlx.Expect::Open([+no_error])
Mysqlx.Crud::PrepareInsert(stmt_id=1, ...) // ok
Mysqlx.Expect::Open([-no_error])
Mysqlx.PreparedStmt::Execute(stmt_id=1, ...) // ok
Mysqlx.PreparedStmt::Execute(stmt_id=1, ...) // duplicate_key error
Mysqlx.PreparedStmt::Execute(stmt_id=1, ...) // ok
Mysqlx.PreparedStmt::Execute(stmt_id=1, ...) // ok
Mysqlx.Expect::Close()
Mysqlx.PreparedStmt::Close(stmt_id=1) // expectation(no_error) failed
Mysqlx.Expect::Close()

Behavior

An Expectation Block:

  • encloses client messages
  • has a Condition Set
  • has a parent Expectation Block
  • can inherit a Condition Set from the parent Expectation Block or start with a empty Condition Set
  • fails if one of the Conditions fails while the Block is started or active
  • fails if one of the Conditions isn't recognized or not valid

A Condition Set:

  • has a set of Conditions
  • allows to set/unset Conditions

A Condition:

  • has a key and value
  • key is integer
  • value format depends on the key

If a Expectation Block fails, all following messages of the Expectation block are failing with:

  • error-msg: Expectation failed: %s
  • error-code: ...

Conditions

Warning
The layout of conditions are subject to change:
  • not all may be implemented yet
  • more conditions may be added
Condition Key
no_error 1
schema_version 2
gtid_executed_contains 3
gtid_wait_less_than_ms 4

no_error

Fail all messages of the block after the first message returning an error.

Example:

Mysqlx.Expect::Open([+no_error])
Mysqlx.Expect::Close()

schema_version

Fail all messages of the block if the schema version for the collection doesn't match. (not implemented)

Note
This is a used by the JSON schema support of the server to ensure client and server are in agreement of what schema version is current* as it is currently planned to enforce the checks on the client-side.

Example:

Mysqlx.Expect::Open([+schema_version::`schema`.`collection` = 1])
Mysqlx.Expect::Close()

gtid_executed_contains

Fail all messages until the end of the block if the @@gtid_executed doesn't contain the set GTID. (not implemented)

Note
Used by the read-your-writes to ensure another node is already up to date.

Example:

Mysqlx.Expect::Open([+gtid_executed_contains = "..."])
Mysqlx.Expect::Close()

gtid_wait_less_than_ms

Used in combination with gtid_executed_contains to wait that the node caught up. (not implemented)

Example:

Mysqlx.Expect::Open([+gtid_wait_less_than_ms = 1000])
Mysqlx.Expect::Close()

sql_stateless

Fail any message that executes stateful statements like:

  • temporary tables
  • user variables
  • session variables
  • stateful functions (INSERT_ID(), GET_LOCK())
  • stateful language features (SQL_CALC_FOUND_ROWS)
Note
Depending on the implementation stored procedures may be not allowed as they may through levels of indirection use stateful SQL features.