Connection Lifecycle for MariaDB Enterprise Server 10.6

Posted on February 18, 2022 by

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:

  1. Enterprise Server receives the connection request on its TCP port
  2. Enterprise Server assigns a thread for the connection
  3. Enterprise Server performs the initial handshake
  4. Enterprise Server allocates the session state
  5. Enterprise Server receives queries and commands over the active connection
  6. 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 PacketDescription
COM_CHANGE_USERThe client re-authenticates as a new user
COM_PINGThe client checks that the server is still available
COM_QUERYThe client executes a SQL statement
COM_QUITThe client disconnects from the server
COM_RESET_CONNECTIONThe client resets the connection without re-authenticating
COM_STMT_BULK_EXECUTEThe client uses a prepared statement to execute a bulk insert
COM_STMT_CLOSEThe client closes a prepared statement
COM_STMT_EXECUTEThe client executes a prepared statement
COM_STMT_FETCHThe client fetches rows from the result of a prepared statement
COM_STMT_PREPAREThe client prepares a statement
COM_STMT_RESETThe client resets a prepared statement
COM_STMT_SEND_LONG_DATAThe 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.