MySQL8 中文参考（八十四）（3）

MySQL8 中文参考（八十四）（2）https://developer.aliyun.com/article/1566018

22.4.5 表中的文档

原文：dev.mysql.com/doc/refman/8.0/en/mysql-shell-tutorial-python-documents-in-tables.html

在 MySQL 中，表可以包含传统关系数据、JSON 值或两者兼有。您可以通过将文档存储在具有本机JSON数据类型的列中，将传统数据与 JSON 文档结合起来。

本节示例使用world_x模式中的城市表。

城市表描述

城市表有五列（或字段）。

+---------------+------------+-------+-------+---------+------------------+
| Field         | Type       | Null  | Key   | Default | Extra            |
+---------------+------------+-------+-------+---------+------------------+
| ID            | int(11)    | NO    | PRI   | null    | auto_increment   |
| Name          | char(35)   | NO    |       |         |                  |
| CountryCode   | char(3)    | NO    |       |         |                  |
| District      | char(20)   | NO    |       |         |                  |
| Info          | json       | YES   |       | null    |                  |
+---------------+------------+-------+-------+---------+------------------+

插入一条记录

要将文档插入表的列中，请按正确顺序将格式良好的 JSON 文档传递给values()方法。在下面的示例中，一个文档作为最终值传递，将插入到 Info 列中。

mysql-py> db.city.insert().values(
None, "San Francisco", "USA", "California", '{"Population":830000}')

选择一条记录

您可以发出带有评估表达式中文档值的搜索条件的查询。

mysql-py> db.city.select(["ID", "Name", "CountryCode", "District", "Info"]).where(
"CountryCode = :country and Info->'$.Population' > 1000000").bind(
'country', 'USA')
+------+----------------+-------------+----------------+-----------------------------+
| ID   | Name           | CountryCode | District       | Info                        |
+------+----------------+-------------+----------------+-----------------------------+
| 3793 | New York       | USA         | New York       | {"Population": 8008278}     |
| 3794 | Los Angeles    | USA         | California     | {"Population": 3694820}     |
| 3795 | Chicago        | USA         | Illinois       | {"Population": 2896016}     |
| 3796 | Houston        | USA         | Texas          | {"Population": 1953631}     |
| 3797 | Philadelphia   | USA         | Pennsylvania   | {"Population": 1517550}     |
| 3798 | Phoenix        | USA         | Arizona        | {"Population": 1321045}     |
| 3799 | San Diego      | USA         | California     | {"Population": 1223400}     |
| 3800 | Dallas         | USA         | Texas          | {"Population": 1188580}     |
| 3801 | San Antonio    | USA         | Texas          | {"Population": 1144646}     |
+------+----------------+-------------+----------------+-----------------------------+
9 rows in set (0.01 sec)

相关信息

• 有关更多信息，请参阅与关系表和文档一起工作。
  
• 详细描述数据类型，请参阅第 13.5 节，“JSON 数据类型”。
  

22.5 X 插件

原文：dev.mysql.com/doc/refman/8.0/en/x-plugin.html

22.5.1 检查 X 插件安装

22.5.2 禁用 X 插件

22.5.3 使用 X 插件进行加密连接

22.5.4 使用 X 插件与缓存 SHA-2 认证插件

22.5.5 使用 X 插件进行连接压缩

22.5.6 X 插件选项和变量

22.5.7 监控 X 插件

本节介绍如何使用、配置和监控 X 插件。

22.5.1 检查 X 插件安装情况

原文：dev.mysql.com/doc/refman/8.0/en/x-plugin-checking-installation.html

MySQL 8 默认启用了 X 插件，因此安装或升级到 MySQL 8 将使插件可用。您可以使用 SHOW plugins 语句查看插件列表来验证 X 插件是否已安装在 MySQL 服务器的实例上。

使用 MySQL Shell 来验证 X 插件是否已安装，请执行：

$> mysqlsh -u *user* --sqlc -P 3306 -e "SHOW plugins"

使用 MySQL Client 来验证 X 插件是否已安装，请执行：

$> mysql -u *user* -p -e "SHOW plugins"

如果 X 插件已安装，则示例结果如下所示：

+----------------------------+----------+--------------------+---------+---------+
| Name                       | Status   | Type               | Library | License |
+----------------------------+----------+--------------------+---------+---------+
...
| mysqlx                     | ACTIVE   | DAEMON             | NULL    | GPL     |
...
+----------------------------+----------+--------------------+---------+---------+

22.5.2 禁用 X 插件

原文：dev.mysql.com/doc/refman/8.0/en/x-plugin-disabling.html

X 插件可以在启动时通过在 MySQL 配置文件中设置mysqlx=0，或者在启动 MySQL 服务器时传入--mysqlx=0或--skip-mysqlx来禁用。

或者，可以使用-DWITH_MYSQLX=OFF CMake 选项来编译不包含 X 插件的 MySQL 服务器。

22.5.3 使用 X 插件进行加密连接

原文：dev.mysql.com/doc/refman/8.0/en/x-plugin-encrypted-connections.html

本节解释了如何配置 X 插件以使用加密连接。有关更多背景信息，请参阅 Section 8.3, “Using Encrypted Connections”。

要启用对加密连接的支持进行配置，X 插件具有mysqlx_ssl_*xxx*系统变量，这些变量的值可以与用于 MySQL 服务器的ssl_*xxx*系统变量不同。例如，X  插件可以具有与 MySQL 服务器不同的 SSL 密钥、证书和证书颁发机构文件。这些变量在 Section 22.5.6.2, “X  Plugin Options and System Variables”中有描述。同样，X 插件具有其自己的Mysqlx_ssl_*xxx*状态变量，对应于 MySQL 服务器加密连接的Ssl_*xxx*状态变量。请参阅 Section 22.5.6.3, “X Plugin Status Variables”。

在初始化时，X 插件确定其用于加密连接的 TLS 上下文如下：

• 如果所有mysqlx_ssl_*xxx*系统变量都具有其默认值，则 X 插件使用与 MySQL 服务器主连接接口相同的 TLS 上下文，该接口由ssl_*xxx*系统变量的值确定。
  
• 如果任何mysqlx_ssl_*xxx*变量具有非默认值，则 X 插件使用由其自身系统变量的值定义的 TLS 上下文。（如果任何mysqlx_ssl_*xxx*系统变量设置为与其默认值不同的值，则是这种情况。）
  

这意味着，在启用 X 插件的服务器上，您可以选择通过仅设置ssl_*xxx*变量来共享 MySQL 协议和 X 协议连接的相同加密配置，或者通过分别配置ssl_*xxx*和mysqlx_ssl_*xxx*变量来为 MySQL 协议和 X 协议连接设置不同的加密配置。

要使 MySQL 协议和 X 协议连接使用相同的加密配置，请在my.cnf中仅设置ssl_*xxx*系统变量：

[mysqld]
ssl_ca=ca.pem
ssl_cert=server-cert.pem
ssl_key=server-key.pem

要为 MySQL 协议和 X 协议连接分别配置加密，请在my.cnf中设置ssl_*xxx*和mysqlx_ssl_*xxx*系统变量：

[mysqld]
ssl_ca=ca1.pem
ssl_cert=server-cert1.pem
ssl_key=server-key1.pem
mysqlx_ssl_ca=ca2.pem
mysqlx_ssl_cert=server-cert2.pem
mysqlx_ssl_key=server-key2.pem

有关配置连接加密支持的一般信息，请参阅 Section 8.3.1, “Configuring MySQL to Use Encrypted Connections”。该讨论是针对 MySQL 服务器编写的，但参数名称对于 X 插件是类似的。（X 插件的mysqlx_ssl_*xxx*系统变量名称对应于 MySQL 服务器的ssl_*xxx*系统变量名称。）

tls_version 系统变量确定了 MySQL 协议连接所允许的 TLS 版本，也适用于 X 协议连接。因此，这两种连接类型所允许的 TLS 版本是相同的。

每个连接的加密是可选的，但可以通过在创建用户的 CREATE USER 语句中包含适当的 REQUIRE 子句来要求特定用户在 X 协议和 MySQL 协议连接中使用加密。有关详细信息，请参见 Section 15.7.1.3, “CREATE USER Statement”。或者，要求所有用户在 X 协议和 MySQL 协议连接中使用加密，可以启用 require_secure_transport 系统变量。有关更多信息，请参见 将加密连接配置为强制性。

22.5.4 使用 X 插件与缓存 SHA-2 认证插件

原文：dev.mysql.com/doc/refman/8.0/en/x-plugin-sha2-cache-plugin.html

X 插件支持使用caching_sha2_password认证插件创建的 MySQL 用户账户。有关此插件的更多信息，请参阅 8.4.1.2 节，“缓存 SHA-2 可插拔认证”。您可以使用 X 插件对这些账户进行身份验证，使用非 SSL 连接进行SHA256_MEMORY认证和使用 SSL 连接进行PLAIN认证。

虽然caching_sha2_password认证插件拥有一个认证缓存，但这个缓存不与 X 插件共享，因此 X 插件使用自己的认证缓存进行SHA256_MEMORY认证。X 插件认证缓存存储用户账户密码的哈希值，并且无法通过 SQL 访问。如果用户账户被修改或移除，相关条目将从缓存中移除。X 插件认证缓存由默认启用的mysqlx_cache_cleaner插件维护，没有相关的系统变量或状态变量。

在您可以使用非 SSL X 协议连接对使用caching_sha2_password认证插件的账户进行身份验证之前，该账户必须至少通过 SSL 进行一次 X 协议连接的认证，以向 X 插件认证缓存提供密码。一旦这个初始的 SSL 认证成功，就可以使用非 SSL X 协议连接。

可以通过使用选项--mysqlx_cache_cleaner=0启动 MySQL 服务器来禁用mysqlx_cache_cleaner插件。如果这样做，X 插件认证缓存将被禁用，因此在使用SHA256_MEMORY认证进行身份验证时，必须始终使用 SSL 进行 X 协议连接。

22.5.5 X 插件的连接压缩

原文：dev.mysql.com/doc/refman/8.0/en/x-plugin-connection-compression.html

从 MySQL 8.0.19 开始，X 插件支持在 X  协议连接上发送消息时进行压缩。如果服务器和客户端就一个相互支持的压缩算法达成一致，连接可以进行压缩。启用压缩会减少通过网络发送的字节数，但会增加服务器和客户端进行压缩和解压缩操作的额外  CPU 成本。因此，压缩的好处主要在网络带宽较低、网络传输时间主导压缩和解压缩操作成本、结果集较大时才会发生。

注意

不同的 MySQL 客户端以不同方式实现对连接压缩的支持；请查阅您的客户端文档以获取详细信息。例如，对于经典 MySQL 协议连接，请参阅 6.2.8 节，“连接压缩控制”。

• 配置 X 插件的连接压缩
  
• X 插件的压缩连接特性
  
• 监控 X 插件连接压缩
  

配置 X 插件的连接压缩

默认情况下，X 插件支持 zstd、LZ4 和 Deflate 压缩算法。使用 Deflate 算法进行压缩时，使用 zlib 软件库，因此 X 协议连接的 deflate_stream 压缩算法设置等效于经典 MySQL 协议连接的 zlib 设置。

在服务器端，您可以通过将 mysqlx_compression_algorithms 系统变量设置为仅包含允许的压缩算法来禁止任何压缩算法。算法名称 zstd_stream、lz4_message 和 deflate_stream 可以以任何组合指定，顺序和大小写不重要。如果系统变量值为空字符串，则不允许任何压缩算法，连接将不被压缩。

以下表格比较了不同压缩算法的特性，并显示了它们的分配优先级。默认情况下，服务器选择服务器和客户端共同允许的最高优先级算法；客户端可以按后文所述更改优先级。在指定时，客户端可以使用算法的简短别名。

表 22.1 X 协议压缩算法特性

X 协议允许的压缩算法集（无论是用户指定的还是默认的）与 MySQL 服务器允许经典 MySQL 协议连接的压缩算法集是独立的，后者由protocol_compression_algorithms服务器系统变量指定。如果您没有指定mysqlx_compression_algorithms系统变量，X  插件不会回退到使用经典 MySQL 协议连接的压缩设置。相反，默认情况下，它允许表 22.1，“X 协议压缩算法特性”中显示的所有算法。这与  TLS 上下文的情况不同，如果未设置 X 插件系统变量，则使用 MySQL 服务器设置，如第 22.5.3 节，“使用 X  插件进行加密连接”中所述。有关经典 MySQL 协议连接的压缩信息，请参阅第 6.2.8 节，“连接压缩控制”。

在客户端端，X 协议连接请求可以为压缩控制指定几个参数：

• 压缩模式。
  
• 压缩级别（从 MySQL 8.0.20 开始）。
  
• 按优先顺序列出的允许的压缩算法列表（从 MySQL 8.0.22 开始）。
  

注意

一些客户端或连接器可能不支持特定的压缩控制功能。例如，仅 MySQL Shell 支持为 X 协议连接指定压缩级别，而其他 MySQL 客户端或连接器不支持。有关支持的功能及如何使用它们的详细信息，请参阅特定产品的文档。

连接模式具有以下允许的值：

• disabled：连接未经压缩。
  
• preferred：服务器和客户端协商以找到双方都允许的压缩算法。如果没有可用的公共算法，则连接未经压缩。如果未明确指定，则这是默认模式。
  
• required：压缩算法协商与preferred模式相同，但如果没有可用的公共算法，则连接请求将以错误终止。
  

除了为每个连接协商压缩算法外，服务器和客户端还可以就适用于约定算法的数字范围内的压缩级别达成一致。随着算法的压缩级别的增加，数据压缩比例增加，从而减少了发送消息到客户端所需的网络带宽和传输时间。然而，数据压缩所需的工作量也增加，占用了服务器上的时间、CPU  和内存资源。压缩工作量的增加与压缩比例的增加之间没有线性关系。

在 MySQL 8.0.19 中，X Plugin 始终使用每种算法的库默认压缩级别（zstd 为 3，LZ4 为 0，Deflate 为  6），客户端无法协商此设置。从 MySQL 8.0.20 开始，客户端可以在与服务器进行 X 协议连接的能力协商期间请求特定的压缩级别。

MySQL 8.0.20 中 X Plugin  使用的默认压缩级别是通过性能测试选择的，是在压缩时间和网络传输时间之间的良好折衷。这些默认值不一定与每种算法的库默认值相同。如果客户端没有为算法请求压缩级别，则会应用这些默认压缩级别。默认压缩级别最初设置为  zstd 的 3，LZ4 的 2，以及 Deflate 的 3。您可以使用mysqlx_zstd_default_compression_level，mysqlx_lz4_default_compression_level，和mysqlx_deflate_default_compression_level系统变量来调整这些设置。

为防止服务器上的资源消耗过多，X Plugin  为每种算法设置了服务器允许的最大压缩级别。如果客户端请求的压缩级别超过此设置，服务器将使用其允许的最大压缩级别（客户端请求的压缩级别仅由  MySQL Shell 支持）。最大压缩级别最初设置为 zstd 的 11，LZ4 的 8，以及 Deflate 的 5。您可以使用mysqlx_zstd_max_client_compression_level，mysqlx_lz4_max_client_compression_level，和mysqlx_deflate_max_client_compression_level系统变量来调整这些设置。

如果服务器和客户端共同允许多个算法，则在协商期间选择算法的默认优先顺序如表 22.1，“X 协议压缩算法特性”中所示。从 MySQL  8.0.22  开始，对于支持指定压缩算法的客户端，连接请求可以包含客户端允许的算法列表，使用算法名称或其别名指定。列表中这些算法的顺序被服务器视为优先顺序。在这种情况下使用的算法是客户端列表中第一个在服务器端也允许的算法。然而，压缩算法选项取决于压缩模式：

• 如果压缩模式为disabled，则忽略压缩算法选项。
  
• 如果压缩模式为preferred，但客户端端和服务器端上没有允许的算法，则连接未经压缩。
  
• 如果压缩模式为required，但客户端端和服务器端上没有允许的算法，则会发生错误。
  

要监视消息压缩的效果，请使用 X Plugin 监视连接压缩中描述的 X Plugin 状态变量。您可以使用这些状态变量来计算使用当前设置的消息压缩的好处，并使用该信息来调整您的设置。

X Plugin 的压缩连接特性

X 协议连接压缩具有以下行为和边界：

• 算法名称中的_stream和_message后缀指的是两种不同的操作模式：在流模式中，单个连接中的所有  X  协议消息被压缩成连续的流，并且必须以相同的方式解压缩——按照它们被压缩的顺序进行，而且不能跳过任何消息。在消息模式中，每个消息都被单独和独立地压缩，不需要按照它们被压缩的顺序进行解压缩。此外，消息模式不要求所有压缩的消息都必须被解压缩。
  
• 不适用于在身份验证成功之前发送的任何消息的压缩。
  
• 压缩不适用于诸如Mysqlx.Ok、Mysqlx.Error和Mysqlx.Sql.StmtExecuteOk等控制流消息。
  
• 如果服务器和客户端在能力协商期间就共同允许的压缩算法达成一致，那么所有其他 X 协议消息都可以进行压缩。如果客户端在该阶段不请求压缩，则客户端和服务器都不会对消息应用压缩。
  
• 当通过 X 协议连接发送的消息被压缩时，mysqlx_max_allowed_packet系统变量指定的限制仍然适用。消息负载解压缩后的网络数据包必须小于此限制。如果超过限制，X 插件将返回解压缩错误并关闭连接。
  
• 客户端的压缩级别请求仅由 MySQL Shell 支持，以下是相关要点：

• 客户端必须将压缩级别指定为整数。如果提供了其他类型的值，则连接将以错误关闭。
  
• 如果客户端指定算法但未指定压缩级别，则服务器将使用该算法的默认压缩级别。
  
• 如果客户端请求的算法压缩级别超过服务器允许的最大级别，则服务器使用最大允许级别。
  
• 如果客户端请求的算法压缩级别低于服务器允许的最小级别，则服务器使用最小允许级别。
  

监控 X 插件的连接压缩效果

您可以使用 X 插件状态变量监视消息压缩的效果。当使用消息压缩时，会话Mysqlx_compression_algorithm状态变量显示当前 X 协议连接中使用的压缩算法，Mysqlx_compression_level显示所选的压缩级别。这些会话状态变量从 MySQL 8.0.20 开始可用。

从 MySQL 8.0.19 开始，X  插件状态变量可用于计算所选的压缩算法的效率（数据压缩比），以及使用消息压缩的整体效果。在以下计算中使用状态变量的会话值，以查看已知压缩算法的特定会话的消息压缩带来的好处。或者使用状态变量的全局值，检查使用  X  协议连接的服务器的整体消息压缩效益，包括为这些会话使用的所有压缩算法，以及未使用消息压缩的所有会话。然后，可以通过调整允许的压缩算法、最大压缩级别和默认压缩级别来调整消息压缩，如为  X 插件配置连接压缩中所述。

当消息压缩被使用时，Mysqlx_bytes_sent 状态变量显示从服务器发送的总字节数，包括压缩后测量的压缩消息有效载荷、未压缩的压缩消息中未压缩的项目（如 X 协议头）以及任何未压缩的消息。Mysqlx_bytes_sent_compressed_payload 状态变量显示作为压缩消息有效载荷发送的总字节数，压缩后测量，而 Mysqlx_bytes_sent_uncompressed_frame 状态变量显示相同消息有效载荷的总字节数，但在压缩之前测量。因此，压缩算法的效率可以通过以下表达式计算：

mysqlx_bytes_sent_uncompressed_frame / mysqlx_bytes_sent_compressed_payload

服务器发送的 X 协议消息的压缩效果可以通过以下表达式计算：

(mysqlx_bytes_sent - mysqlx_bytes_sent_compressed_payload + mysqlx_bytes_sent_uncompressed_frame) / mysqlx_bytes_sent

对于服务器从客户端接收的消息，Mysqlx_bytes_received_compressed_payload 状态变量显示作为压缩消息有效载荷接收的总字节数，解压缩前测量，而 Mysqlx_bytes_received_uncompressed_frame 状态变量显示相同消息有效载荷的总字节数，但在解压缩后测量。Mysqlx_bytes_received 状态变量包括解压缩前测量的压缩消息有效载荷、压缩消息中的任何未压缩项目以及任何未压缩消息。

22.5.6 X 插件选项和变量

原文：dev.mysql.com/doc/refman/8.0/en/x-plugin-options-variables.html

22.5.6.1 X 插件选项和变量参考

22.5.6.2 X 插件选项和系统变量

22.5.6.3 X 插件状态变量

本节描述了配置 X 插件的命令选项和系统变量，以及用于监控目的的状态变量。如果在启动时指定的配置值不正确，X 插件可能无法正确初始化，服务器也无法加载它。在这种情况下，服务器还可能因为无法识别其他 X 插件设置而产生错误消息。

原文：dev.mysql.com/doc/refman/8.0/en/x-plugin-option-variable-reference.html

MySQL8 中文参考（八十四）（4）https://developer.aliyun.com/article/1566021