<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h3 class="title">
      <a name="performance-schema-connection-attribute-tables">
      </a>
      29.12.9 Performance Schema Connection Attribute Tables
     </h3>
    </div>
   </div>
  </div>
  <div class="toc">
   <dl class="toc">
    <dt>
     <span class="section">
      <a href="performance-schema-session-account-connect-attrs-table.html">
       29.12.9.1 The session_account_connect_attrs Table
      </a>
     </span>
    </dt>
    <dt>
     <span class="section">
      <a href="performance-schema-session-connect-attrs-table.html">
       29.12.9.2 The session_connect_attrs Table
      </a>
     </span>
    </dt>
   </dl>
  </div>
  <p>
   Connection attributes are key-value pairs that application
        programs can pass to the server at connect time. For
        applications based on the C API implemented by the
   <code class="literal">
    libmysqlclient
   </code>
   client library, the
   <a class="ulink" href="/doc/c-api/8.4/en/mysql-options.html" target="_top">
    <code class="literal">
     mysql_options()
    </code>
   </a>
   and
   <a class="ulink" href="/doc/c-api/8.4/en/mysql-options4.html" target="_top">
    <code class="literal">
     mysql_options4()
    </code>
   </a>
   functions
        define the connection attribute set. Other MySQL Connectors may
        provide their own attribute-definition methods.
  </p>
  <p>
   These Performance Schema tables expose attribute information:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <a class="link" href="performance-schema-session-account-connect-attrs-table.html" title="29.12.9.1 The session_account_connect_attrs Table">
       <code class="literal">
        session_account_connect_attrs
       </code>
      </a>
      :
            Connection attributes for the current session, and other
            sessions associated with the session account
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="link" href="performance-schema-session-connect-attrs-table.html" title="29.12.9.2 The session_connect_attrs Table">
       <code class="literal">
        session_connect_attrs
       </code>
      </a>
      :
            Connection attributes for all sessions
     </p>
    </li>
   </ul>
  </div>
  <p>
   In addition, connect events written to the audit log may include
        connection attributes. See
   <a class="xref" href="audit-log-file-formats.html" title="8.4.5.4 Audit Log File Formats">
    Section 8.4.5.4, “Audit Log File Formats”
   </a>
   .
  </p>
  <p>
   Attribute names that begin with an underscore
        (
   <code class="literal">
    _
   </code>
   ) are reserved for internal use and should
        not be created by application programs. This convention permits
        new attributes to be introduced by MySQL without colliding with
        application attributes, and enables application programs to
        define their own attributes that do not collide with internal
        attributes.
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <a class="xref" href="performance-schema-connection-attribute-tables.html#performance-schema-connection-attributes-available" title="Available Connection Attributes">
       Available Connection Attributes
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="performance-schema-connection-attribute-tables.html#performance-schema-connection-attribute-limits" title="Connection Attribute Limits">
       Connection Attribute Limits
      </a>
     </p>
    </li>
   </ul>
  </div>
  <h4>
   <a name="performance-schema-connection-attributes-available">
   </a>
   Available Connection Attributes
  </h4>
  <p>
   The set of connection attributes visible within a given
        connection varies depending on factors such as your platform,
        MySQL Connector used to establish the connection, or client
        program.
  </p>
  <p>
   The
   <code class="literal">
    libmysqlclient
   </code>
   client library sets these
        attributes:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <code class="literal">
       _client_name
      </code>
      : The client name
            (
      <code class="literal">
       libmysql
      </code>
      for the client library).
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _client_version
      </code>
      : The client library
            version.
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _os
      </code>
      : The operating system (for example,
      <code class="literal">
       Linux
      </code>
      ,
      <code class="literal">
       Win64
      </code>
      ).
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _pid
      </code>
      : The client process ID.
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _platform
      </code>
      : The machine platform (for
            example,
      <code class="literal">
       x86_64
      </code>
      ).
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _thread
      </code>
      : The client thread ID (Windows
            only).
     </p>
    </li>
   </ul>
  </div>
  <p>
   Other MySQL Connectors may define their own connection
        attributes.
  </p>
  <p>
   MySQL Connector/C++ defines these attributes for applications that use
        X DevAPI or X DevAPI for C:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <code class="literal">
       _client_license
      </code>
      : The connector license
            (for example
      <code class="literal">
       GPL-2.0
      </code>
      ).
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _client_name
      </code>
      : The connector name
            (
      <code class="literal">
       mysql-connector-cpp
      </code>
      ).
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _client_version
      </code>
      : The connector version.
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _os
      </code>
      : The operating system (for example,
      <code class="literal">
       Linux
      </code>
      ,
      <code class="literal">
       Win64
      </code>
      ).
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _pid
      </code>
      : The client process ID.
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _platform
      </code>
      : The machine platform (for
            example,
      <code class="literal">
       x86_64
      </code>
      ).
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _source_host
      </code>
      : The host name of the
            machine on which the client is running.
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _thread
      </code>
      : The client thread ID (Windows
            only).
     </p>
    </li>
   </ul>
  </div>
  <p>
   <a name="performance-schema-connection-attributes-cj">
   </a>
   MySQL Connector/J defines these attributes:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <code class="literal">
       _client_name
      </code>
      : The client name
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _client_version
      </code>
      : The client library
            version
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _os
      </code>
      : The operating system (for example,
      <code class="literal">
       Linux
      </code>
      ,
      <code class="literal">
       Win64
      </code>
      )
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _client_license
      </code>
      : The connector license
            type
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _platform
      </code>
      : The machine platform (for
            example,
      <code class="literal">
       x86_64
      </code>
      )
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _runtime_vendor
      </code>
      : The Java runtime
            environment (JRE) vendor
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _runtime_version
      </code>
      : The Java runtime
            environment (JRE) version
     </p>
    </li>
   </ul>
  </div>
  <p>
   MySQL Connector/NET defines these attributes:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <code class="literal">
       _client_version
      </code>
      : The client library
            version.
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _os
      </code>
      : The operating system (for example,
      <code class="literal">
       Linux
      </code>
      ,
      <code class="literal">
       Win64
      </code>
      ).
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _pid
      </code>
      : The client process ID.
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _platform
      </code>
      : The machine platform (for
            example,
      <code class="literal">
       x86_64
      </code>
      ).
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _program_name
      </code>
      : The client name.
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _thread
      </code>
      : The client thread ID (Windows
            only).
     </p>
    </li>
   </ul>
  </div>
  <p>
   The Connector/Python implementation defines these attributes; some values
        and attributes depend on the Connector/Python implementation (pure python
        or c-ext):
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <code class="literal">
       _client_license
      </code>
      : The license type of the
            connector;
      <code class="literal">
       GPL-2.0
      </code>
      or
      <code class="literal">
       Commercial
      </code>
      . (pure python only)
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _client_name
      </code>
      : Set to
      <code class="literal">
       mysql-connector-python
      </code>
      (pure python) or
      <code class="literal">
       libmysql
      </code>
      (c-ext)
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _client_version
      </code>
      : The connector version
            (pure python) or mysqlclient library version (c-ext).
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _os
      </code>
      : The operating system with the
            connector (for example,
      <code class="literal">
       Linux
      </code>
      ,
      <code class="literal">
       Win64
      </code>
      ).
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _pid
      </code>
      : The process identifier on the
            source machine (for example,
      <code class="literal">
       26955
      </code>
      )
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _platform
      </code>
      : The machine platform (for
            example,
      <code class="literal">
       x86_64
      </code>
      ).
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _source_host
      </code>
      : The host name of the
            machine on which the connector is connecting from.
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _connector_version
      </code>
      : The connector version
            (for example,
      <code class="literal">
       8.4.3
      </code>
      ) (c-ext
            only).
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _connector_license
      </code>
      : The license type of
            the connector;
      <code class="literal">
       GPL-2.0
      </code>
      or
      <code class="literal">
       Commercial
      </code>
      (c-ext only).
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       _connector_name
      </code>
      : Always set to
      <code class="literal">
       mysql-connector-python
      </code>
      (c-ext only).
     </p>
    </li>
   </ul>
  </div>
  <p>
   PHP defines attributes that depend on how it was compiled:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      Compiled using
      <code class="literal">
       libmysqlclient
      </code>
      : The
            standard
      <code class="literal">
       libmysqlclient
      </code>
      attributes,
            described previously.
     </p>
    </li>
    <li class="listitem">
     <p>
      Compiled using
      <code class="literal">
       mysqlnd
      </code>
      : Only the
      <code class="literal">
       _client_name
      </code>
      attribute, with a value of
      <code class="literal">
       mysqlnd
      </code>
      .
     </p>
    </li>
   </ul>
  </div>
  <p>
   Many MySQL client programs set a
   <code class="literal">
    program_name
   </code>
   attribute with a value equal to the client name. For example,
   <a class="link" href="mysqladmin.html" title="6.5.2 mysqladmin — A MySQL Server Administration Program">
    <span class="command">
     <strong>
      mysqladmin
     </strong>
    </span>
   </a>
   and
   <a class="link" href="mysqldump.html" title="6.5.4 mysqldump — A Database Backup Program">
    <span class="command">
     <strong>
      mysqldump
     </strong>
    </span>
   </a>
   set
   <code class="literal">
    program_name
   </code>
   to
   <code class="literal">
    mysqladmin
   </code>
   and
   <code class="literal">
    mysqldump
   </code>
   ,
        respectively. MySQL Shell sets
   <code class="literal">
    program_name
   </code>
   to
   <code class="literal">
    mysqlsh
   </code>
   .
  </p>
  <p>
   Some MySQL client programs define additional attributes:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <a class="link" href="mysql.html" title="6.5.1 mysql — The MySQL Command-Line Client">
       <span class="command">
        <strong>
         mysql
        </strong>
       </span>
      </a>
      :
     </p>
     <div class="itemizedlist">
      <ul class="itemizedlist" style="list-style-type: circle; ">
       <li class="listitem">
        <p>
         <code class="literal">
          os_user
         </code>
         : The name of the operating
                system user running the program. Available on Unix and
                Unix-like systems and Windows.
        </p>
       </li>
       <li class="listitem">
        <p>
         <code class="literal">
          os_sudouser
         </code>
         : The value of the
         <code class="literal">
          SUDO_USER
         </code>
         environment variable.
                Available on Unix and Unix-like systems.
        </p>
        <a class="indexterm" name="idm46045071898832">
        </a>
        <a class="indexterm" name="idm46045071897744">
        </a>
       </li>
      </ul>
     </div>
     <p>
      <a class="link" href="mysql.html" title="6.5.1 mysql — The MySQL Command-Line Client">
       <span class="command">
        <strong>
         mysql
        </strong>
       </span>
      </a>
      connection attributes for which the
            value is empty are not sent.
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="link" href="mysqlbinlog.html" title="6.6.9 mysqlbinlog — Utility for Processing Binary Log Files">
       <span class="command">
        <strong>
         mysqlbinlog
        </strong>
       </span>
      </a>
      :
     </p>
     <div class="itemizedlist">
      <ul class="itemizedlist" style="list-style-type: circle; ">
       <li class="listitem">
        <p>
         <code class="literal">
          _client_role
         </code>
         :
         <code class="literal">
          binary_log_listener
         </code>
        </p>
       </li>
      </ul>
     </div>
    </li>
    <li class="listitem">
     <p>
      Replica connections:
     </p>
     <div class="itemizedlist">
      <ul class="itemizedlist" style="list-style-type: circle; ">
       <li class="listitem">
        <p>
         <code class="literal">
          program_name
         </code>
         :
         <code class="literal">
          mysqld
         </code>
        </p>
       </li>
       <li class="listitem">
        <p>
         <code class="literal">
          _client_role
         </code>
         :
         <code class="literal">
          binary_log_listener
         </code>
        </p>
       </li>
       <li class="listitem">
        <p>
         <code class="literal">
          _client_replication_channel_name
         </code>
         : The
                channel name.
        </p>
       </li>
      </ul>
     </div>
    </li>
    <li class="listitem">
     <p>
      <a class="link" href="federated-storage-engine.html" title="18.8 The FEDERATED Storage Engine">
       <code class="literal">
        FEDERATED
       </code>
      </a>
      storage engine
            connections:
     </p>
     <div class="itemizedlist">
      <ul class="itemizedlist" style="list-style-type: circle; ">
       <li class="listitem">
        <p>
         <code class="literal">
          program_name
         </code>
         :
         <code class="literal">
          mysqld
         </code>
        </p>
       </li>
       <li class="listitem">
        <p>
         <code class="literal">
          _client_role
         </code>
         :
         <code class="literal">
          federated_storage
         </code>
        </p>
       </li>
      </ul>
     </div>
    </li>
   </ul>
  </div>
  <h4>
   <a name="performance-schema-connection-attribute-limits">
   </a>
   Connection Attribute Limits
  </h4>
  <p>
   There are limits on the amount of connection attribute data
        transmitted from client to server:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      A fixed limit imposed by the client prior to connect time.
     </p>
    </li>
    <li class="listitem">
     <p>
      A fixed limit imposed by the server at connect time.
     </p>
    </li>
    <li class="listitem">
     <p>
      A configurable limit imposed by the Performance Schema at
            connect time.
     </p>
    </li>
   </ul>
  </div>
  <p>
   For connections initiated using the C API, the
   <code class="literal">
    libmysqlclient
   </code>
   library imposes a limit of
        64KB on the aggregate size of connection attribute data on the
        client side: Calls to
   <a class="ulink" href="/doc/c-api/8.4/en/mysql-options.html" target="_top">
    <code class="literal">
     mysql_options()
    </code>
   </a>
   that cause this
        limit to be exceeded produce a
   <a class="ulink" href="/doc/mysql-errors/8.4/en/client-error-reference.html#error_cr_invalid_parameter_no" target="_top">
    <code class="literal">
     CR_INVALID_PARAMETER_NO
    </code>
   </a>
   error.
        Other MySQL Connectors may impose their own client-side limits
        on how much connection attribute data can be transmitted to the
        server.
  </p>
  <p>
   On the server side, these size checks on connection attribute
        data occur:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      The server imposes a limit of 64KB on the aggregate size of
            connection attribute data it accepts. If a client attempts
            to send more than 64KB of attribute data, the server rejects
            the connection. Otherwise, the server considers the
            attribute buffer valid and tracks the size of the longest
            such buffer in the
      <a class="link" href="performance-schema-status-variables.html#statvar_Performance_schema_session_connect_attrs_longest_seen">
       <code class="literal">
        Performance_schema_session_connect_attrs_longest_seen
       </code>
      </a>
      status variable.
     </p>
    </li>
    <li class="listitem">
     <p>
      For accepted connections, the Performance Schema checks
            aggregate attribute size against the value of the
      <a class="link" href="performance-schema-system-variables.html#sysvar_performance_schema_session_connect_attrs_size">
       <code class="literal">
        performance_schema_session_connect_attrs_size
       </code>
      </a>
      system variable. If attribute size exceeds this value, these
            actions take place:
     </p>
     <div class="itemizedlist">
      <ul class="itemizedlist" style="list-style-type: circle; ">
       <li class="listitem">
        <p>
         The Performance Schema truncates the attribute data and
                increments the
         <a class="link" href="performance-schema-status-variables.html#statvar_Performance_schema_session_connect_attrs_lost">
          <code class="literal">
           Performance_schema_session_connect_attrs_lost
          </code>
         </a>
         status variable, which indicates the number of
                connections for which attribute truncation occurred.
        </p>
       </li>
       <li class="listitem">
        <p>
         The Performance Schema writes a message to the error log
                if the
         <a class="link" href="server-system-variables.html#sysvar_log_error_verbosity">
          <code class="literal">
           log_error_verbosity
          </code>
         </a>
         system variable is greater than 1:
        </p>
        <div class="copytoclipboard-wrapper">
         <pre class="programlisting language-none"><div class="docs-select-all right" id="sa48004860"><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-none">Connection attributes of length <em class="replaceable">N</em> were truncated
(<em class="replaceable">N</em> bytes lost)
for connection <em class="replaceable">N</em>, user <em class="replaceable">user_name</em>@<em class="replaceable">host_name</em>
(as <em class="replaceable">user_name</em>), auth: {yes|no}</code></pre>
        </div>
        <p>
         The information in the warning message is intended to
                help DBAs identify clients for which attribute
                truncation occurred.
        </p>
       </li>
       <li class="listitem">
        <p>
         A
         <code class="literal">
          _truncated
         </code>
         attribute is added to
                the session attributes with a value indicating how many
                bytes were lost, if the attribute buffer has sufficient
                space. This enables the Performance Schema to expose
                per-connection truncation information in the connection
                attribute tables. This information can be examined
                without having to check the error log.
        </p>
       </li>
      </ul>
     </div>
    </li>
   </ul>
  </div>
 </div>
 <br/>
</div>
