0 - Packet

Client/server exchanges are done using the following format:

Standard packet

The standard MySQL/MariaDB packet has a 4-byte header and a packet body:

• int<3> packet length;

• sequence number;

• packet body.

Packet length is the length of the packet body. Packet length size cannot be more than 3 bytes length value. The actual length of the packet is calculated as from the 3 bytes as length:

The maximum size of a packet (with all 3 bytes 0xff) is 16777215 , or 2^24-1 or 0xffffff, or 16MB-1 byte.

The sequence number indicates the exchange number when an exchange demands different exchanges. Whenever the client sends a query, the sequence number is set to 0 initially, and is incremented if clients need to split packets.

In more complex situations, when the client and server exchange several packets, for instance, authentication handshake, the rule of thumb for clients is to set sequence number = (last seq.number from received server packet + 1).

Example: Sending a packet COM_PING body has only one byte (0x10):

The server will then return an response with a sequence number of 1.

Packet Splitting

The packet length is 3 bytes, making a maximum size of (2^24 -1) bytes or 16Mbytes-1 byte. But the protocol allows sending and receiving larger data. For those cases, the client can send many packets for the same data, incrementing the sequence number for each packet.

The principle is to split data by chunks of 16M bytes. When the server receives a packet with 0xffffff length, it will continue to read the next packet. In case of a length of exactly 16M bytes, an empty packet must terminate the sequence.

Example: max_allowed_packet is set to a value > to 40M bytes. Sending a 40M bytes packet body: \

First packet:

Second packet:

Third packet:

The client must be aware of the variable value. The server has a buffer to store the body with a maximum size corresponding to this max_allowed_packet value. If the client sends more data than max_allowed_packet size, the socket will be closed.

Compressed Packet

For slow connections, the packet can be compressed. This is activated after the when the client indicates [[1-connecting-connecting#capabilities|COMPRESS] capability with the server having this functionality, too.

When activated, packets are composed of 7 bytes, a compress header and data. The compression algorithm used is ZLIB, widely available and supported by many languages and runtimes.

• compressed packet length;

• compression protocol sequence number;

• uncompress body length;

• compressed body;

Since compress body can contain many "standard packets", compress sequence number is incremented separately from sequence number. If the length of the uncompressed payload exceeds 0xffffff bytes, the uncompressed payload must be sent in several compressed protocol packets.

For small packets, using compression won't be efficient, so the client can choose to send uncompressed data. That is done by setting the compressed packet length to the real length and the uncompressed packet length to 0. (Data must then be uncompressed).

Example: Sending a packet COM_PING body when COMPRESS is enabled. This is 1 byte of data that has then no reason to be compressed, so:

The server returns an response with a compress sequence number of 1, and a sequence number of 1.

Compression Packet Splitting

The server uncompresses data, and then must have the same packet as if there was no compression. If data size needs splitting, it's better to separate compress packet.

_{This page is licensed: CC BY-SA / Gnu FDL}