Result Set Packets
Contents
MariaDB Server sends the following packets as part of a result set: A resultset consists of different packets:
- if not (
MARIADB_CLIENT_CACHE_METADATAcapability set) OR (send metadata == 1)- for each column (i.e column_count times)
- if not (
CLIENT_DEPRECATE_EOFcapability set) EOF_Packet - n resultset row
- if error
- else
- if
CLIENT_DEPRECATE_EOFcapability- OK_Packet with a 0xFE header
- else EOF_Packet
- if
It would be unsafe to assume that any packet with a 0xFE header is an OK packet (OK_Packet) or an EOF packet (EOF_Packet), because result-set row packets (ResultsetRow) can also begin with 0xFE when using the text protocol with a field length greater than 0xFFFFFF.
To safely confirm that a packet with a 0xFE header is an OK packet (OK_Packet) or an EOF packet (EOF_Packet), you must also check that the packet length is less than 0xFFFFFF.
Column Count Packet
The column count packet describes the number of columns in the result set. It uses the following format:
- int<lenenc> column count
- if (
MARIADB_CLIENT_CACHE_METADATAcapability set)- int<1> metadata follows (0 / 1)
The metadata indicator byte is only present if both the client and the server declare the MARIADB_CLIENT_CACHE_METADATA capability.
If the metadata byte is set to 1, the normal metadata will follow the column definitions. If the metadata byte is set to 0, the Column Count Packet is immediately followed by the second EOF packet (EOF_Packet) or the resultset rows if the CLIENT_DEPRECATE_EOF capability is set.
Column Definition Packet
A column definition packet describes a column in the result set. It uses the following format:
- string<lenenc> catalog (always 'def')
- string<lenenc> schema
- string<lenenc> table alias
- string<lenenc> table
- string<lenenc> column alias
- string<lenenc> column
- if extended type supported (see
MARIADB_CLIENT_EXTENDED_METADATA) - int<lenenc> length of fixed fields (=0xC)
- int<2> character set number
- int<4> max. column size
- int<1> Field types
- int<2> Field detail flag
- int<1> decimals
- int<2> - unused -
Field types
The column type field in the column definition packet describes the base type of the column. It also indicates how the values are encoded for COM_STMT_EXECUTE parameters and binary resultset rows.
| Value | Protocol Column Type | Encoding |
|---|---|---|
| 0 | MYSQL_TYPE_DECIMAL | byte<lenenc> encoding |
| 1 | MYSQL_TYPE_TINY | TINYINT Binary encoding |
| 2 | MYSQL_TYPE_SHORT | SMALLINT Binary encoding |
| 3 | MYSQL_TYPE_LONG | INTEGER Binary encoding |
| 4 | MYSQL_TYPE_FLOAT | FLOAT Binary encoding |
| 5 | MYSQL_TYPE_DOUBLE | DOUBLE Binary encoding |
| 6 | MYSQL_TYPE_NULL | Not used, nullness is indicated by the NULL-bitmap in the result |
| 7 | MYSQL_TYPE_TIMESTAMP | TIMESTAMP Binary encoding |
| 8 | MYSQL_TYPE_LONGLONG | BIGINT Binary encoding |
| 9 | MYSQL_TYPE_INT24 | INTEGER Binary encoding |
| 10 | MYSQL_TYPE_DATE | TIMESTAMP Binary encoding |
| 11 | MYSQL_TYPE_TIME | TIME Binary encoding |
| 12 | MYSQL_TYPE_DATETIME | TIMESTAMP Binary encoding |
| 13 | MYSQL_TYPE_YEAR | SMALLINT Binary encoding |
| 14 | MYSQL_TYPE_NEWDATE | byte<lenenc> encoding |
| 15 | MYSQL_TYPE_VARCHAR | byte<lenenc> encoding |
| 16 | MYSQL_TYPE_BIT | byte<lenenc> encoding |
| 17 | MYSQL_TYPE_TIMESTAMP2 | Used only in the replication protocol |
| 18 | MYSQL_TYPE_DATETIME2 | Used only in the replication protocol |
| 19 | MYSQL_TYPE_TIME2 | Used only in the replication protocol |
| 245 | MYSQL_TYPE_JSON | byte<lenenc> encoding (only used with MySQL, MariaDB uses MYSQL_TYPE_STRING for JSON) |
| 246 | MYSQL_TYPE_NEWDECIMAL | byte<lenenc> encoding |
| 247 | MYSQL_TYPE_ENUM | byte<lenenc> encoding |
| 248 | MYSQL_TYPE_SET | byte<lenenc> encoding |
| 249 | MYSQL_TYPE_TINY_BLOB | byte<lenenc> encoding |
| 250 | MYSQL_TYPE_MEDIUM_BLOB | byte<lenenc> encoding |
| 251 | MYSQL_TYPE_LONG_BLOB | byte<lenenc> encoding |
| 252 | MYSQL_TYPE_BLOB | byte<lenenc> encoding |
| 253 | MYSQL_TYPE_VAR_STRING | byte<lenenc> encoding |
| 254 | MYSQL_TYPE_STRING | byte<lenenc> encoding |
| 255 | MYSQL_TYPE_GEOMETRY | byte<lenenc> encoding |
Field Details Flag
The column details flag describes certain column attributes and whether certain column options are set.
It is a bitmask with the following flags:
| Flag Value | Flag Name | Flag Description |
|---|---|---|
| 1 | NOT_NULL | field cannot be null |
| 2 | PRIMARY_KEY | field is a primary key |
| 4 | UNIQUE_KEY | field is unique |
| 8 | MULTIPLE_KEY | field is in a multiple key |
| 16 | BLOB | is this field a Blob |
| 32 | UNSIGNED | is this field unsigned |
| 64 | ZEROFILL_FLAG | is this field a zerofill |
| 128 | BINARY_COLLATION | whether this field has a binary collation |
| 256 | ENUM | Field is an enumeration |
| 512 | AUTO_INCREMENT | field auto-increment |
| 1024 | TIMESTAMP | field is a timestamp value |
| 2048 | SET | field is a SET |
| 4096 | NO_DEFAULT_VALUE_FLAG | field doesn't have default value |
| 8192 | ON_UPDATE_NOW_FLAG | field is set to NOW on UPDATE |
| 32768 | NUM_FLAG | field is num |
The BLOB flag cannot be used to determine if a column has binary data, because BINARY and VARBINARY columns are treated as strings, instead of blobs.
The BINARY_COLLATION flag can be used to determine if a string column has binary data.
Extended metadata
This extended column type information can be used to find out more specific details about the column type.
For example:
- For a
POINTcolumn, the column type field will beMYSQL_TYPE_GEOMETRY, but the extended type will indicate 'point'. - For a
JSONcolumn, the column type field will beMYSQL_TYPE_STRING, but the extended type will indicate 'json'.
- while string has data
- int<1> data type: 0x00:type, 0x01: format
- string<lenenc> value
