Connection Lifecycle for MariaDB Enterprise Server 10.6

Posted on February 18, 2022 by Max Mether

In this blog, we take a look at the connection lifecycle when connecting from a client to MariaDB Enterprise Server 10.6 over TCP/IP. We additionally explain error handling behavior.

MariaDB Enterprise Server is an enhanced, hardened and secured version of MariaDB Community Server built to meet the most challenging reliability, stability, security and scalability requirements of business-critical, mission-critical applications.

This connection lifecycle can be divided into six distinct stages:

Enterprise Server receives the connection request on its TCP port
Enterprise Server assigns a thread for the connection
Enterprise Server performs the initial handshake
Enterprise Server allocates the session state
Enterprise Server receives queries and commands over the active connection
The connection disconnects

In this blog, we use the term “Enterprise Server node” or “ES node” to describe a running instance of MariaDB Enterprise Server 10.6. This blog describes behavior when the ES node is configured to receive connections on a TCP port.

Stage 1: Connection Request

In stage 1 of the connection lifecycle, the ES node receives the connection request via its TCP port:

If the ES node’s max_connections has been exceeded, the node rejects the connection.

Stage 2: Thread Assignment

In stage 2 of the connection lifecycle, the ES node assigns a thread for the connection:

The thread is pulled from the thread cache, if available. If a cached thread is not available, a new thread is created.

Stage 3: Initial Handshake

In stage 3 of the connection lifecycle, the ES node performs a handshake with the client:

If TLS is enabled, Enterprise Server performs a TLS handshake. If the connection does not use TLS, but Enterprise Server is configured to require TLS, the connection is rejected.
Enterprise Server performs authentication with the client. If authentication fails, the connection is rejected.

Stage 4: Session State

In stage 4 of the connection lifecycle, the ES node allocates the session state:

Enterprise Server allocates buffers used by the connection.
Enterprise Server initializes the connection’s session variables from the global variables.

Stage 5: Active Connection

In stage 5 of the connection lifecycle, the ES node waits for command packets over the connection.

The MariaDB protocol defines specific types of command packets. Some of the most common command packets are:

Command Packet	Description
`COM_CHANGE_USER`	The client re-authenticates as a new user
`COM_PING`	The client checks that the server is still available
`COM_QUERY`	The client executes a SQL statement
`COM_QUIT`	The client disconnects from the server
`COM_RESET_CONNECTION`	The client resets the connection without re-authenticating
`COM_STMT_BULK_EXECUTE`	The client uses a prepared statement to execute a bulk insert
`COM_STMT_CLOSE`	The client closes a prepared statement
`COM_STMT_EXECUTE`	The client executes a prepared statement
`COM_STMT_FETCH`	The client fetches rows from the result of a prepared statement
`COM_STMT_PREPARE`	The client prepares a statement
`COM_STMT_RESET`	The client resets a prepared statement
`COM_STMT_SEND_LONG_DATA`	The client requests data for a column that is too long to fit in normal result packets

Stage 6: Disconnection

In stage 6 of the connection lifecycle, the client disconnects from the ES node:

The client can send an explicit COM_QUIT request to disconnect.
The server will force disconnection if the transaction is idle for longer than wait_timeout.

Error Handling

When a connection encounters an error, Enterprise Server sometimes reports an error to the client:

The client receives an error code, and SQL state, and an error message. The error message does not contain sensitive information.
Sometimes an error message is written to the MariaDB error log. The MariaDB error log can contain sensitive information, including full SQL statements, so the log should be protected at the file system level.