1 of 17

2 - Text Protocol

Understand the text protocol in the Server's client/server communication. This section details how SQL commands and results are exchanged as plain text, including command types and packet structures.

COM_CHANGE_USER

This command allows a connected client to re-authenticate as a different user without closing and reopening the connection.

COM_CHANGE_USER resets the connection and re-authenticates with the given credentials. The packet is identical to the authentication packet in the connection handshake.

Fields

int<1> 0x11 : COM_CHANGE_USER header.
username.
If (server_capabilities & CLIENT_SECURE_CONNECTION):
- length of authentication response.
- string authentication response.
Else:
- authentication response.
default schema name.
client character collation.
If (server_capabilities & CLIENT_PLUGIN_AUTH):
- authentication plugin name.
If (server_capabilities & CLIENT_CONNECT_ATTRS):
- size of connection attributes.
- Loop:

Response

Server response is like :

An OK packet in case of success .
An error packet in case of error .
Authentication switch:
- If the client or server doesn't have PLUGIN_AUTH

If the authentication fails more than three times, all future COM_CHANGE_USER commands on the connection will return the #08S01 Unknown command error. This is an anti-brute-force mechanism designed to prevent rapid guessing of passwords.

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

COM_CREATE_DB

This command creates a new database on the server, functionally equivalent to the SQL statement CREATE DATABASE.

This command is deprecated and not used by MariaDB connectors any more. Use the SQL statements CREATE SCHEMA or CREATE DATABASE instead.

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

COM_DEBUG

This command forces the server to dump debug information to the standard output or log, requiring the SUPER privilege.

The COM_DEBUG command forces the server to dump debug information to stdout. It requires the privilege.

Fields

0xOD : COM_DEBUG

COM_DROP_DB

This command drops an existing database from the server, functionally equivalent to the SQL statement DROP DATABASE.

This command is deprecated and not used by MariaDB connectors any more. Use the SQL statements DROP SCHEMA or DROP DATABASE instead.

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

COM_FIELD_LIST

This command retrieves a list of fields (columns) for a specified table, similar to the SHOW COLUMNS SQL statement.

This command is deprecated and not used by MariaDB connectors any more. Use the SQL statements SHOW COLUMNS or SELECT FROM INFORMATION_SCHEMA.COLUMNS instead.

Fields

0x04 : COM_FIELD_LIST header.
Table name.
Optional field list.

Response

zero or more .
.

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

COM_INIT_DB

This command selects the default database for the current connection, functionally equivalent to the USE statement.

COM_INIT_DB is used to specify the default schema for the connection.

Fields

0x02 : COM_INIT_DB

COM_PING

This command checks if the server is alive and reachable, the server responds with an OK packet if it is running.

COM_PING permits sending a packet containing one byte to check that the connection is active.

Fields

0x0e : COM_PING header.

COM_PROCESS_KILL

This command asks the server to terminate a specific connection thread, functionally equivalent to the KILL statement.

Forces the server to terminate a specified connection.

Fields

int<1> 0xC COM_PROCESS_KILL.
process ID.

Response

or .

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

COM_PROCESSLIST

This command retrieves a list of active threads and their current status, similar to the SHOW PROCESSLIST statement.

This command is deprecated and not used by MariaDB connectors any more. Use the SQL statement instead.

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

COM_QUERY

This command sends an SQL statement to the server for execution immediately, without the prepare/execute steps.

With the COM_QUERY command, the client sends the server an SQL statement to be executed immediately.

Fields

int<1> 0x03 : COM_QUERY header.
SQL statement.

The SQL statement should be properly escaped. The escape character is usually a backslash '' = 0x5c. However, if the status flag returned by the last had the NO_BACKSLASH_ESCAPES bit set, the escape character is a single quote (' = 0x60).

If the escape character is a backslash, the following characters are escaped:

Single quote (' = 0x60).
Backslash (\ = 0x5c).
Double quote (" = 0x22

If the escape character is a single quote, only the single quote (' = 0x60) can be escaped.

Response

The server can answer with 4 different responses that can be differentiated by the first byte (packet header):

0xFF - if any error occurs.
0x00 - when query execution works without result set.
0xFB - if the query was LOCAL INFILE ....

Example

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

COM_QUIT

This command instructs the server to close the connection and release associated resources.

Using the COM_QUIT command, the client tells the server that the connection should be terminated.

Fields

int<1> 0x01 : COM_QUIT header.

Response

Server terminates connection.

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

COM_RESET_CONNECTION

This command resets the session state (variables, tables, etc.) to its initial values without closing the connection.

COM_RESET_CONNECTION resets a connection without reauthentication.

The command does this:

Roll back any open transactions.
Reset transaction isolation level.

COM_SET_OPTION

This command configures client-specific options for the current connection, such as enabling or disabling multi-statements.

Enables or disables server option.

Fields

0x1B COM_SET_OPTION .

COM_SHUTDOWN

This command requests the server to shut down, it requires the SHUTDOWN privilege to be executed successfully.

Shuts down the server. To execute this command, the SHUTDOWN privilege is required.

Fields

int<1> 0x0A COM_SHUTDOWN
option

Options

Response

or .

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

COM_SLEEP

This is an internal command used to represent a sleeping connection that is waiting for a new command from the client.

This command is used inside the server only.

Direction

Used inside server only.

COM_STATISTICS

This command retrieves a human-readable string containing internal server statistics like uptime and thread counts.

Get internal server statistics.

Fields

int<1> 0x09 : COM_STATISTICS header.

Response

human-readable string.

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

COM_CHANGE_USER

This command allows a connected client to re-authenticate as a different user without closing and reopening the connection.

COM_CHANGE_USER resets the connection and re-authenticates with the given credentials. The packet is identical to the authentication packet in the connection handshake.

Fields

int<1> 0x11 : COM_CHANGE_USER header.
username.
If (server_capabilities & CLIENT_SECURE_CONNECTION):
- length of authentication response.
- string authentication response.
Else:
- authentication response.
default schema name.
client character collation.
If (server_capabilities & CLIENT_PLUGIN_AUTH):
- authentication plugin name.
If (server_capabilities & CLIENT_CONNECT_ATTRS):
- size of connection attributes.
- Loop:

Response

Server response is like :

An OK packet in case of success .
An error packet in case of error .
Authentication switch:
- If the client or server doesn't have PLUGIN_AUTH

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

COM_QUERY

This command sends an SQL statement to the server for execution immediately, without the prepare/execute steps.

With the COM_QUERY command, the client sends the server an SQL statement to be executed immediately.

Fields

int<1> 0x03 : COM_QUERY header.
SQL statement.

If the escape character is a backslash, the following characters are escaped:

Single quote (' = 0x60).
Backslash (\ = 0x5c).
Double quote (" = 0x22

If the escape character is a single quote, only the single quote (' = 0x60) can be escaped.

Response

The server can answer with 4 different responses that can be differentiated by the first byte (packet header):

0xFF - if any error occurs.
0x00 - when query execution works without result set.
0xFB - if the query was LOCAL INFILE ....

Example

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