MySQL 8.0.31
Source Code Documentation
Life Cycle

Topics in this section:

The following list describes some of the terms introduced in this section:

Transport layer that exchanges data: TCP sockets, Unix Sockets, TLS, and so on.
A lower-level connection between two Endpoints.
The session maintains the state. User-Variables, Temporary Tables, and so on.
Messages are exchanged between Endpoints. On a higher level they build a sequence of Messages with a initial and final Message.
A client or a server.


A default connection supports:


A session owns state like:

  • current schema
  • current character set
  • temporary tables
  • user variables
  • open transactions

A session is used by the server and the protocol to manage state.

Sessions are:

Closing a session releases all session related data.

Stages of Session Setup

After a client connects to the server it:

Stages of Session Setup

In the Negotiation step the client checks which features the server supports on the protocol side.

After a successful finish of the Authentication step the previous Session is discarded and a new Session is created.

Further Command Messages run within a Session.


Authentication supports several authentication mechanisms that can be discovered with Mysqlx::Connection::CapabilitiesGet.


Server-side supported SASL mechanism:

  • before TLS connection established: ["MYSQL41", "SHA256_MEMORY"]
  • after TLS connection established: ["PLAIN", "SHA256_MEMORY", "MYSQL41"]

Required mechanisms:

  • PLAIN (over SSL) RFC; RFC 4616 (required)

Other known mechanisms:

  • MYSQL41 (MySQL 4.1 auth mechanism)


The messages may be pipelined:

  • the client may send the messages without waiting for a reply first
  • the client should only send messages which safely trigger an Error packet

For the server it is no difference if the messages from client where sent in a bulk or if the client waited. The network and send/receive buffers of the Operation System will act as queue.

Expectations help to control the behavior of following messages if a pipelined message fails.

For more information, see Implementation Notes.


If the result of Mysqlx::Connection::CapabilitiesGet contains a extension key from the table below it supports the feature.

Name Extension Read/Write Version
tls TLS RW 5.7
authentication.mechanisms Authentication mechanisms R 5.7
doc.formats Doc formats R 5.7
client.interactive Client interactive RW 8.0
compression Compression RW 8.0.18
node_type Node type R 5.7
client.pwd_expire_ok Client pwd expire ok RW 5.7
More extensions can be added in future iterations as long as they are announced in CapabilitiesGet() and documented.

TLS Extension

The client may assume that the server supports a set of features by default and skip the Mysqlx::Connection::CapabilitiesGet step:

Feature: extensions
Scenario: connecting with TLS, fast path
Given a client side X.509 certificate is provided with user name "foo"
And client certificate is valid
When connecting with TLS established
Then handshake should be single-step
TLS extension


  • 0: supported, not in use
  • 1: supported, in use


  • 1: switch to TLS connection after server-side Ok

If the server doesn't support the capability, then it will return an error.

Disabling TLS on a connection may not be supported by the server and should result in an error.

Authentication mechanisms Extension

This capability return a list that informs the client, which authentication mechanism may be used while authentication (AuthenticationStart message).

This list is combination of what server support (has implemented) and current state of the connection. For example, authentication method like PLAIN is going to be visiable after SSL actication or on SECURE channel:
See also
Authentication section for more detail about differen authentication mechanisms

Document formats Extension

This extension informs how document are encoded by the server. Currently documents are in text format, still in future it could be changed to some binary encoding and user might be able to change the format.

Interactive client Extension

This extension changes, which timeout-values are used by the server when its waiting for first byte of a new request. Its enabled by setting client.interactive capability to true, it changes the default of mysqlx_wait_timeout variable, which is going to be initialized from mysqlx_interactive_timeout variable.

Interactive clients, are application which send their requests after user input, for example mysql or mysqlsh. In such case the admin of an server might consider to extend the timeout values, and shorten for scripts that do SQL batch execution.

Compression Extension

This extension informs what compression algorithms are permitted for use on X Protocol connections. Currently, the Deflate, LZ4, and zstd algorithms are supported and permitted by default. To disallow any of the algorithms, the user can set mysqlx_compression_algorithms variable to include only the ones permitted.

Node type Extension

This is rather an information to what network node the client connected. Currently the capability transfers "mysql" value, which points to MySQL Server, still intermediate network elements like MySQL Router might consider changing this value to "router".

Client pasword expire ok Extension

This extension changes, behavior on server side, where authentication fails when expired MySQL Server account is used. Setting client.interactive capability to true waiting for first byte of a new request. Its enabled by setting client.pwd_expire_oke capability to true, makes the authentication pass which allows user to change the password.