MySQL  8.0.20
Source Code Documentation
Life Cycle

Topics in this section:

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

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

Connection

A default connection supports:

Session

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:

  • may ask for the servers capabilities with CapabilitiesGet
  • may ask the server to use optional protocol features with CapabilitiesSet
  • MUST authenticate
  • may send commands
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

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

authentication.mechanisms

Server-side supported SASL mechanism:

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

Required mechanisms:

Other known mechanisms:

  • MYSQL41 (MySQL 4.1 auth mechanism)

Pipelining

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.

Tip
For more information, see Implementation Notes.

Max Message Length

If the server receives a message that is larger than the current Max Message Length, then it MUST close the connection.

message.maxSendLength

CapabilitiesGet

  • 1048576: current max message length 1Mbyte

CapabilitiesSet

  • 2097152: asks to increase the max message length to 2Mbyte

message.maxReceiveLength

CapabilitiesGet

  • 1048576: current max receiving message length 1Mbyte

CapabilitiesSet

  • 2097152: asks to increase the max receiving message length to 2Mbyte
Note
As clients and servers may have to buffer the entire message before it can be processed these limits allow protect against excessive resource usage.

Extensions

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

Name Extension
tls TLS Extension
Note
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 CapabilitiesGet step:

  • if the TLS extension isn't supported, then the CapabilitiesSet will fail
  • if it is supported, then it will succeed
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

CapabilitiesGet

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

CapabilitiesSet

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

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

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