<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h3 class="title">
      <a name="x-plugin-connection-compression">
      </a>
      22.5.5 Connection Compression with X Plugin
     </h3>
    </div>
   </div>
  </div>
  <a class="indexterm" name="idm46045126647216">
  </a>
  <a class="indexterm" name="idm46045126645728">
  </a>
  <p>
   X Plugin supports compression of messages sent over X Protocol
      connections. Connections can be compressed if the server and the
      client agree on a mutually supported compression algorithm.
      Enabling compression reduces the number of bytes sent over the
      network, but adds to the server and client an additional CPU cost
      for compression and decompression operations. The benefits of
      compression therefore occur primarily when there is low network
      bandwidth, network transfer time dominates the cost of compression
      and decompression operations, and result sets are large.
  </p>
  <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
   <div class="admon-title">
    Note
   </div>
   <p>
    Different MySQL clients implement support for connection
        compression differently; consult your client documentation for
        details. For example, for classic MySQL protocol connections, see
    <a class="xref" href="connection-compression-control.html" title="6.2.8 Connection Compression Control">
     Section 6.2.8, “Connection Compression Control”
    </a>
    .
   </p>
  </div>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <a class="xref" href="x-plugin-connection-compression.html#x-plugin-connection-compression-configuration" title="Configuring Connection Compression for X Plugin">
       Configuring Connection Compression for X Plugin
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="x-plugin-connection-compression.html#x-plugin-connection-compression-characteristics" title="Compressed Connection Characteristics for X Plugin">
       Compressed Connection Characteristics for X Plugin
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="x-plugin-connection-compression.html#x-plugin-connection-compression-monitoring" title="Monitoring Connection Compression for X Plugin">
       Monitoring Connection Compression for X Plugin
      </a>
     </p>
    </li>
   </ul>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h4 class="title">
       <a name="x-plugin-connection-compression-configuration">
       </a>
       Configuring Connection Compression for X Plugin
      </h4>
     </div>
    </div>
   </div>
   <p>
    By default, X Plugin supports the zstd, LZ4, and Deflate
        compression algorithms. Compression with the Deflate algorithm
        is carried out using the zlib software library, so the
    <code class="literal">
     deflate_stream
    </code>
    compression algorithm setting
        for X Protocol connections is equivalent to the
    <code class="literal">
     zlib
    </code>
    setting for classic MySQL protocol
        connections.
   </p>
   <p>
    On the server side, you can disallow any of the compression
        algorithms by setting the
    <a class="link" href="x-plugin-options-system-variables.html#sysvar_mysqlx_compression_algorithms">
     <code class="literal">
      mysqlx_compression_algorithms
     </code>
    </a>
    system variable to include only those permitted. The algorithm
        names
    <code class="literal">
     zstd_stream
    </code>
    ,
    <code class="literal">
     lz4_message
    </code>
    , and
    <code class="literal">
     deflate_stream
    </code>
    can be specified in any
        combination, and the order and lettercase are not important. If
        the system variable value is the empty string, no compression
        algorithms are permitted and connections are uncompressed.
   </p>
   <p>
    The following table compares the characteristics of the
        different compression algorithms and shows their assigned
        priorities. By default, the server chooses the highest-priority
        algorithm permitted in common by the server and the client;
        clients may change the priorities as described later. The short
        form alias for the algorithms can be used by clients when
        specifying them.
   </p>
   <div class="table">
    <a name="x-plugin-connection-compression-algorithms">
    </a>
    <p class="title">
     <b>
      Table 22.1 X Protocol Compression Algorithm Characteristics
     </b>
    </p>
    <div class="table-contents">
     <table frame="void">
      <colgroup>
       <col align="center" style="width: 18%"/>
       <col align="center" style="width: 14%"/>
       <col align="center" style="width: 18%"/>
       <col align="center" style="width: 17%"/>
       <col align="center" style="width: 16%"/>
       <col align="center" style="width: 16%"/>
      </colgroup>
      <thead>
       <tr>
        <th scope="col">
         Algorithm
        </th>
        <th scope="col">
         Alias
        </th>
        <th scope="col">
         Compression Ratio
        </th>
        <th scope="col">
         Throughput
        </th>
        <th scope="col">
         CPU Cost
        </th>
        <th scope="col">
         Default Priority
        </th>
       </tr>
      </thead>
      <tbody>
       <tr>
        <th scope="row">
         <code class="literal">
          zsth_stream
         </code>
        </th>
        <td>
         <code class="literal">
          zstd
         </code>
        </td>
        <td>
         High
        </td>
        <td>
         High
        </td>
        <td>
         Medium
        </td>
        <td>
         First
        </td>
       </tr>
       <tr>
        <th scope="row">
         <code class="literal">
          lz4_message
         </code>
        </th>
        <td>
         <code class="literal">
          lz4
         </code>
        </td>
        <td>
         Low
        </td>
        <td>
         High
        </td>
        <td>
         Lowest
        </td>
        <td>
         Second
        </td>
       </tr>
       <tr>
        <th scope="row">
         <code class="literal">
          deflate_stream
         </code>
        </th>
        <td>
         <code class="literal">
          deflate
         </code>
        </td>
        <td>
         High
        </td>
        <td>
         Low
        </td>
        <td>
         Highest
        </td>
        <td>
         Third
        </td>
       </tr>
      </tbody>
     </table>
    </div>
   </div>
   <br class="table-break"/>
   <p>
    The X Protocol set of permitted compression algorithms (whether
        user-specified or default) is independent of the set of
        compression algorithms permitted by MySQL Server for
        classic MySQL protocol connections, which is specified by the
    <a class="link" href="server-system-variables.html#sysvar_protocol_compression_algorithms">
     <code class="literal">
      protocol_compression_algorithms
     </code>
    </a>
    server system variable. If you do not specify the
    <a class="link" href="x-plugin-options-system-variables.html#sysvar_mysqlx_compression_algorithms">
     <code class="literal">
      mysqlx_compression_algorithms
     </code>
    </a>
    system variable, X Plugin does not fall back to using
        compression settings for classic MySQL protocol connections. Instead,
        its default is to permit all algorithms shown in
    <a class="xref" href="x-plugin-connection-compression.html#x-plugin-connection-compression-algorithms" title="Table 22.1 X Protocol Compression Algorithm Characteristics">
     Table 22.1, “X Protocol Compression Algorithm Characteristics”
    </a>
    .
        This is unlike the situation for the TLS context, where MySQL
        Server settings are used if the X Plugin system variables are
        not set, as described in
    <a class="xref" href="x-plugin-encrypted-connections.html" title="22.5.3 Using Encrypted Connections with X Plugin">
     Section 22.5.3, “Using Encrypted Connections with X Plugin”
    </a>
    . For
        information about compression for classic MySQL protocol connections,
        see
    <a class="xref" href="connection-compression-control.html" title="6.2.8 Connection Compression Control">
     Section 6.2.8, “Connection Compression Control”
    </a>
    .
   </p>
   <p>
    On the client side, an X Protocol connection request can
        specify several parameters for compression control:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       The compression mode.
      </p>
     </li>
     <li class="listitem">
      <p>
       The compression level.
      </p>
     </li>
     <li class="listitem">
      <p>
       The list of permitted compression algorithms in priority
            order.
      </p>
     </li>
    </ul>
   </div>
   <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Note
    </div>
    <p>
     Some clients or Connectors might not support a given
          compression-control feature. For example, specifying
          compression level for X Protocol connections is supported
          only by MySQL Shell, not by other MySQL clients or
          Connectors. See the documentation for specific products for
          details about supported features and how to use them.
    </p>
   </div>
   <p>
    The connection mode has these permitted values:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       <code class="literal">
        disabled
       </code>
       : The connection is uncompressed.
      </p>
     </li>
     <li class="listitem">
      <p>
       <code class="literal">
        preferred
       </code>
       : The server and client
            negotiate to find a compression algorithm they both permit.
            If no common algorithm is available, the connection is
            uncompressed. This is the default mode if not specified
            explicitly.
      </p>
     </li>
     <li class="listitem">
      <p>
       <code class="literal">
        required
       </code>
       : Compression algorithm
            negotiation occurs as for
       <code class="literal">
        preferred
       </code>
       mode,
            but if no common algorithm is available, the connection
            request terminates with an error.
      </p>
     </li>
    </ul>
   </div>
   <p>
    In addition to agreeing on a compression algorithm for each
        connection, the server and client can agree on a compression
        level from the numeric range that applies to the agreed
        algorithm. As the compression level for an algorithm increases,
        the data compression ratio increases, which reduces the network
        bandwidth and transfer time needed to send the message to the
        client. However, the effort required for data compression also
        increases, taking up time and CPU and memory resources on the
        server. Increases in the compression effort do not have a linear
        relationship to increases in the compression ratio.
   </p>
   <p>
    The client can request a specific compression level during
        capability negotiations with the server for an X Protocol
        connection.
   </p>
   <p>
    The default compression levels used by X Plugin in MySQL
        8.4 have been selected through performance testing
        as being a good trade-off between compression time and network
        transit time. These defaults are not necessarily the same as the
        library default for each algorithm. They apply if the client
        does not request a compression level for the algorithm. The
        default compression levels are initially set to 3 for zstd, 2
        for LZ4, and 3 for Deflate. You can adjust these settings using
        the
    <a class="link" href="x-plugin-options-system-variables.html#sysvar_mysqlx_zstd_default_compression_level">
     <code class="literal">
      mysqlx_zstd_default_compression_level
     </code>
    </a>
    ,
    <a class="link" href="x-plugin-options-system-variables.html#sysvar_mysqlx_lz4_default_compression_level">
     <code class="literal">
      mysqlx_lz4_default_compression_level
     </code>
    </a>
    ,
        and
    <a class="link" href="x-plugin-options-system-variables.html#sysvar_mysqlx_deflate_default_compression_level">
     <code class="literal">
      mysqlx_deflate_default_compression_level
     </code>
    </a>
    system variables.
   </p>
   <p>
    To prevent excessive resource consumption on the server,
        X Plugin sets a maximum compression level that the server
        permits for each algorithm. If a client requests a compression
        level that exceeds this setting, the server uses its maximum
        permitted compression level (compression level requests by a
        client are supported only by MySQL Shell). The maximum
        compression levels are initially set to 11 for zstd, 8 for LZ4,
        and 5 for Deflate. You can adjust these settings using the
    <a class="link" href="x-plugin-options-system-variables.html#sysvar_mysqlx_zstd_max_client_compression_level">
     <code class="literal">
      mysqlx_zstd_max_client_compression_level
     </code>
    </a>
    ,
    <a class="link" href="x-plugin-options-system-variables.html#sysvar_mysqlx_lz4_max_client_compression_level">
     <code class="literal">
      mysqlx_lz4_max_client_compression_level
     </code>
    </a>
    ,
        and
    <a class="link" href="x-plugin-options-system-variables.html#sysvar_mysqlx_deflate_max_client_compression_level">
     <code class="literal">
      mysqlx_deflate_max_client_compression_level
     </code>
    </a>
    system variables.
   </p>
   <p>
    If the server and client permit more than one algorithm in
        common, the default priority order for choosing an algorithm
        during negotiation is shown in
    <a class="xref" href="x-plugin-connection-compression.html#x-plugin-connection-compression-algorithms" title="Table 22.1 X Protocol Compression Algorithm Characteristics">
     Table 22.1, “X Protocol Compression Algorithm Characteristics”
    </a>
    .
        For clients that support specifying compression algorithms, the
        connection request can include a list of algorithms permitted by
        the client, specified using the algorithm name or its alias. The
        order of these algorithms in the list is taken as a priority
        order by the server. The algorithm used in this case is the
        first of those in the client list that is also permitted on the
        server side. However, the option for compression algorithms is
        subject to the compression mode:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       If the compression mode is
       <code class="literal">
        disabled
       </code>
       , the
            compression algorithms option is ignored.
      </p>
     </li>
     <li class="listitem">
      <p>
       If the compression mode is
       <code class="literal">
        preferred
       </code>
       but
            no algorithm permitted on the client side is permitted on
            the server side, the connection is uncompressed.
      </p>
     </li>
     <li class="listitem">
      <p>
       If the compression mode is
       <code class="literal">
        required
       </code>
       but
            no algorithm permitted on the client side is permitted on
            the server side, an error occurs.
      </p>
     </li>
    </ul>
   </div>
   <p>
    To monitor the effects of message compression, use the X Plugin
        status variables described in
    <a class="xref" href="x-plugin-connection-compression.html#x-plugin-connection-compression-monitoring" title="Monitoring Connection Compression for X Plugin">
     Monitoring Connection Compression for X Plugin
    </a>
    .
        You can use these status variables to calculate the benefit of
        message compression with your current settings, and use that
        information to tune your settings.
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h4 class="title">
       <a name="x-plugin-connection-compression-characteristics">
       </a>
       Compressed Connection Characteristics for X Plugin
      </h4>
     </div>
    </div>
   </div>
   <p>
    X Protocol connection compression operates with the following
        behaviors and boundaries:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       The
       <code class="literal">
        _stream
       </code>
       and
       <code class="literal">
        _message
       </code>
       suffixes in algorithm names
            refer to two different operational modes: In stream mode,
            all X Protocol messages in a single connection are
            compressed into a continuous stream and must be decompressed
            in the same manner—following the order they were
            compressed and without skipping any messages. In message
            mode, each message is compressed individually and
            independently, and need not be decompressed in the order in
            which they were compressed. Also, message mode does not
            require all compressed messages to be decompressed.
      </p>
     </li>
     <li class="listitem">
      <p>
       Compression is not applied to any messages that are sent
            before authentication succeeds.
      </p>
     </li>
     <li class="listitem">
      <p>
       Compression is not applied to control flow messages such as
       <code class="literal">
        Mysqlx.Ok
       </code>
       ,
       <code class="literal">
        Mysqlx.Error
       </code>
       , and
       <code class="literal">
        Mysqlx.Sql.StmtExecuteOk
       </code>
       messages.
      </p>
     </li>
     <li class="listitem">
      <p>
       All other X Protocol messages can be compressed if the
            server and client agree on a mutually permitted compression
            algorithm during capability negotiation. If the client does
            not request compression at that stage, neither the client
            nor the server applies compression to messages.
      </p>
     </li>
     <li class="listitem">
      <p>
       When messages sent over X Protocol connections are
            compressed, the limit specified by the
       <a class="link" href="x-plugin-options-system-variables.html#sysvar_mysqlx_max_allowed_packet">
        <code class="literal">
         mysqlx_max_allowed_packet
        </code>
       </a>
       system variable still applies. The network packet must be
            smaller than this limit after the message payload has been
            decompressed. If the limit is exceeded, X Plugin returns a
            decompression error and closes the connection.
      </p>
     </li>
     <li class="listitem">
      <p>
       The following points pertain to compression level requests
            by clients, which is supported only by MySQL Shell:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: circle; ">
        <li class="listitem">
         <p>
          Compression levels must be specified by the client as an
                integer. If any other type of value is supplied, the
                connection closes with an error.
         </p>
        </li>
        <li class="listitem">
         <p>
          If a client specifies an algorithm but not a compression
                level, the server uses its default compression level for
                the algorithm.
         </p>
        </li>
        <li class="listitem">
         <p>
          If a client requests an algorithm compression level that
                exceeds the server maximum permitted level, the server
                uses the maximum permitted level.
         </p>
        </li>
        <li class="listitem">
         <p>
          If a client requests an algorithm compression level that
                is less than the server minimum permitted level, the
                server uses the minimum permitted level.
         </p>
        </li>
       </ul>
      </div>
     </li>
    </ul>
   </div>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h4 class="title">
       <a name="x-plugin-connection-compression-monitoring">
       </a>
       Monitoring Connection Compression for X Plugin
      </h4>
     </div>
    </div>
   </div>
   <p>
    You can monitor the effects of message compression using the
        X Plugin status variables. When message compression is in use,
        the session
    <a class="link" href="x-plugin-status-variables.html#statvar_Mysqlx_compression_algorithm">
     <code class="literal">
      Mysqlx_compression_algorithm
     </code>
    </a>
    status variable shows which compression algorithm is in use for
        the current X Protocol connection, and
    <a class="link" href="x-plugin-status-variables.html#statvar_Mysqlx_compression_level">
     <code class="literal">
      Mysqlx_compression_level
     </code>
    </a>
    shows
        the compression level that was selected.
   </p>
   <p>
    X Plugin status variables can be used to calculate the
        efficiency of the compression algorithms that are selected (the
        data compression ratio), and the overall effect of using message
        compression. Use the session value of the status variables in
        the following calculations to see what the benefit of message
        compression was for a specific session with a known compression
        algorithm. Or use the global value of the status variables to
        check the overall benefit of message compression for your server
        across all sessions using X Protocol connections, including all
        the compression algorithms that have been used for those
        sessions, and all sessions that did not use message compression.
        You can then tune message compression by adjusting the permitted
        compression algorithms, maximum compression level, and default
        compression level, as described in
    <a class="xref" href="x-plugin-connection-compression.html#x-plugin-connection-compression-configuration" title="Configuring Connection Compression for X Plugin">
     Configuring Connection Compression for X Plugin
    </a>
    .
   </p>
   <p>
    When message compression is in use, the
    <a class="link" href="x-plugin-status-variables.html#statvar_Mysqlx_bytes_sent">
     <code class="literal">
      Mysqlx_bytes_sent
     </code>
    </a>
    status
        variable shows the total number of bytes sent out from the
        server, including compressed message payloads measured after
        compression, any items in compressed messages that were not
        compressed such as X Protocol headers, and any uncompressed
        messages. The
    <a class="link" href="x-plugin-status-variables.html#statvar_Mysqlx_bytes_sent_compressed_payload">
     <code class="literal">
      Mysqlx_bytes_sent_compressed_payload
     </code>
    </a>
    status variable shows the total number of bytes sent as
        compressed message payloads, measured after compression, and the
    <a class="link" href="x-plugin-status-variables.html#statvar_Mysqlx_bytes_sent_uncompressed_frame">
     <code class="literal">
      Mysqlx_bytes_sent_uncompressed_frame
     </code>
    </a>
    status variable shows the total number of bytes for those same
        message payloads but measured before compression. The
        compression ratio, which shows the efficiency of the compression
        algorithm, can therefore be calculated using the following
        expression:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting one-line language-simple"><div class="docs-select-all right" id="sa73312766"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-simple">mysqlx_bytes_sent_uncompressed_frame <span class="token operator">/</span> mysqlx_bytes_sent_compressed_payload</code></pre>
   </div>
   <p>
    The effectiveness of compression for X Protocol messages sent
        by the server can be calculated using the following expression:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting one-line language-simple"><div class="docs-select-all right" id="sa71069708"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-simple"><span class="token punctuation">(</span>mysqlx_bytes_sent <span class="token operator">-</span> mysqlx_bytes_sent_compressed_payload <span class="token operator">+</span> mysqlx_bytes_sent_uncompressed_frame<span class="token punctuation">)</span> <span class="token operator">/</span> mysqlx_bytes_sent</code></pre>
   </div>
   <p>
    For messages received by the server from clients, the
    <a class="link" href="x-plugin-status-variables.html#statvar_Mysqlx_bytes_received_compressed_payload">
     <code class="literal">
      Mysqlx_bytes_received_compressed_payload
     </code>
    </a>
    status variable shows the total number of bytes received as
        compressed message payloads, measured before decompression, and
        the
    <a class="link" href="x-plugin-status-variables.html#statvar_Mysqlx_bytes_received_uncompressed_frame">
     <code class="literal">
      Mysqlx_bytes_received_uncompressed_frame
     </code>
    </a>
    status variable shows the total number of bytes for those same
        message payloads but measured after decompression. The
    <a class="link" href="x-plugin-status-variables.html#statvar_Mysqlx_bytes_received">
     <code class="literal">
      Mysqlx_bytes_received
     </code>
    </a>
    status
        variable includes compressed message payloads measured before
        decompression, any uncompressed items in compressed messages,
        and any uncompressed messages.
   </p>
  </div>
 </div>
 <br/>
</div>
