Topics in this section:

The following list describes some of the terms introduced in this section:

Transport: Transport layer that exchanges data: TCP sockets, Unix Sockets, TLS, and so on.

Connection: A lower-level connection between two Endpoints.

Session: The session maintains the state. User-Variables, Temporary Tables, and so on.

Messages: Messages are exchanged between Endpoints. On a higher level they build a sequence of Messages with a initial and final Message.

Endpoints: A client or a server.

Connection

A default connection supports:

supports connection capability negotiation via Mysqlx::Connection::CapabilitiesGet and Mysqlx::Connection::CapabilitiesSet
must support at least one of the following:
- TLS Extension and PLAIN Authentication or
- MYSQL41 Authentication or another challenge response authentication mechanism or
- SHA256_MEMORY Authentication

Session

A session owns state like:

current schema
current character set
temporary tables
user variables
open transactions

A session is used by the server and the protocol to manage state.

Sessions are:

opened with Mysqlx::Session::AuthenticateStart
reset session state with Mysqlx::Session::Reset
re-authenticate session with Mysqlx::Session::Reset
closed with Mysqlx::Session::Close

Closing a session releases all session related data.

Stages of Session Setup

After a client connects to the server it:

may ask for the servers capabilities with Mysqlx::Connection::CapabilitiesGet
may ask the server to use optional protocol features with Mysqlx::Connection::CapabilitiesSet
MUST authenticate
may send commands

Stages of Session Setup

In the Negotiation step the client checks which features the server supports on the protocol side.

After a successful finish of the Authentication step the previous Session is discarded and a new Session is created.

Further Command Messages run within a Session.

Authentication

Authentication supports several authentication mechanisms that can be discovered with Mysqlx::Connection::CapabilitiesGet.

authentication.mechanisms

Server-side supported SASL mechanism:

before TLS connection established: ["MYSQL41", "SHA256_MEMORY"]
after TLS connection established: ["PLAIN", "SHA256_MEMORY", "MYSQL41"]

Required mechanisms:

PLAIN (over SSL) RFC; RFC 4616 (required)

Other known mechanisms:

MYSQL41 (MySQL 4.1 auth mechanism)
SHA256_MEMORY

Pipelining

The messages may be pipelined:

the client may send the messages without waiting for a reply first
the client should only send messages which safely trigger an Error packet

For the server it is no difference if the messages from client where sent in a bulk or if the client waited. The network and send/receive buffers of the Operation System will act as queue.

Expectations help to control the behavior of following messages if a pipelined message fails.

Tip: For more information, see Implementation Notes.

Extensions

If the result of Mysqlx::Connection::CapabilitiesGet contains a extension key from the table below it supports the feature.

Name	Extension	Read/Write	Version
`tls`	TLS	RW	5.7
`authentication.mechanisms`	Authentication mechanisms	R	5.7
`doc.formats`	Doc formats	R	5.7
`client.interactive`	Client interactive	RW	8.0
`compression`	Compression	RW	8.0.18
`node_type`	Node type	R	5.7
`client.pwd_expire_ok`	Client pwd expire ok	RW	5.7

Note: More extensions can be added in future iterations as long as they are announced in CapabilitiesGet() and documented.

TLS Extension

The client may assume that the server supports a set of features by default and skip the Mysqlx::Connection::CapabilitiesGet step:

if the TLS extension isn't supported, then the Mysqlx::Connection::CapabilitiesSet will fail
if it is supported, then it will succeed

Feature: extensions
  Scenario: connecting with TLS, fast path
    Given a client side X.509 certificate is provided with user name "foo"
    And client certificate is valid
    When connecting with TLS established
    Then handshake should be single-step

TLS extension

Mysqlx::Connection::CapabilitiesGet

0: supported, not in use
1: supported, in use

Mysqlx::Connection::CapabilitiesSet

1: switch to TLS connection after server-side Ok

If the server doesn't support the capability, then it will return an error.

Note: Disabling TLS on a connection may not be supported by the server and should result in an error.

Authentication mechanisms Extension

This capability return a list that informs the client, which authentication mechanism may be used while authentication (AuthenticationStart message).

Note: This list is combination of what server support (has implemented) and current state of the connection. For example, authentication method like PLAIN is going to be visiable after SSL actication or on SECURE channel:

See also: Authentication section for more detail about differen authentication mechanisms

Document formats Extension

This extension informs how document are encoded by the server. Currently documents are in text format, still in future it could be changed to some binary encoding and user might be able to change the format.

Interactive client Extension

This extension changes, which timeout-values are used by the server when its waiting for first byte of a new request. Its enabled by setting client.interactive capability to true, it changes the default of mysqlx_wait_timeout variable, which is going to be initialized from mysqlx_interactive_timeout variable.

Note: Interactive clients, are application which send their requests after user input, for example mysql or mysqlsh. In such case the admin of an server might consider to extend the timeout values, and shorten for scripts that do SQL batch execution.

Compression Extension

This extension informs what compression algorithms are permitted for use on X Protocol connections. Currently, the Deflate, LZ4, and zstd algorithms are supported and permitted by default. To disallow any of the algorithms, the user can set mysqlx_compression_algorithms variable to include only the ones permitted.

Node type Extension

This is rather an information to what network node the client connected. Currently the capability transfers "mysql" value, which points to MySQL Server, still intermediate network elements like MySQL Router might consider changing this value to "router".

Client pasword expire ok Extension

This extension changes, behavior on server side, where authentication fails when expired MySQL Server account is used. Setting client.interactive capability to true waiting for first byte of a new request. Its enabled by setting client.pwd_expire_oke capability to true, makes the authentication pass which allows user to change the password.