MySQL 8.4 Reference Manual  /  Language Structure  /  Query Attributes

11.6 查询属性

SQL 语句的最可见部分是语句本身。客户端还可以定义查询属性,以便将其应用于下一个要发送到服务器执行的语句:

  • 属性在发送语句之前定义。

  • 属性存在直到语句执行结束,然后属性集将被清除。

  • 在属性存在期间,可以在服务器端访问它们。

查询属性的示例用法:

  • 一个 Web 应用程序生成页面,该页面生成数据库查询,并且对于每个查询必须跟踪生成该查询的页面 URL。

  • 一个应用程序将额外的处理信息与每个查询一起传递,以便由插件,如审计插件或查询重写插件使用。

MySQL 支持这些功能,无需使用工作-around,如特别格式化的注释在查询字符串中。以下部分描述了如何使用查询属性支持,包括必须满足的先决条件。

定义和访问查询属性

使用 MySQL C API 定义查询属性的应用程序可以通过调用 mysql_bind_param() 函数来定义查询属性。见 mysql_bind_param()。其他 MySQL 连接器可能也提供查询属性支持。见个connectors 的文档。

MySQL 客户端 mysql 有一个 query_attributes 命令,可以定义最多 32 对属性名称和值对。见 Section 6.5.1.2, “mysql Client Commands”

查询属性名称使用由 character_set_client 系统变量 指定的字符集传输。

要在 SQL 语句中访问已定义的查询属性,安装 query_attributes 组件,见 使用查询属性的先决条件。该组件实现了 mysql_query_attribute_string() 可加载函数,该函数以属性名称参数作为输入,并返回属性值作为字符串,或者 NULL 如果属性不存在。见 查询属性可加载函数

以下示例使用mysql客户端query_attributes命令来定义属性名称/值对,并使用mysql_query_attribute_string()函数访问属性值。

这个示例定义了两个属性名为n1n2。第一个SELECT语句展示了如何检索这些属性,并且还演示了检索一个不存在的属性(n3)将返回NULL。第二个SELECT语句展示了属性不跨越语句。

mysql> query_attributes n1 v1 n2 v2;
mysql> SELECT
         mysql_query_attribute_string('n1') AS 'attr 1',
         mysql_query_attribute_string('n2') AS 'attr 2',
         mysql_query_attribute_string('n3') AS 'attr 3';
+--------+--------+--------+
| attr 1 | attr 2 | attr 3 |
+--------+--------+--------+
| v1     | v2     | NULL   |
+--------+--------+--------+

mysql> SELECT
         mysql_query_attribute_string('n1') AS 'attr 1',
         mysql_query_attribute_string('n2') AS 'attr 2';
+--------+--------+
| attr 1 | attr 2 |
+--------+--------+
| NULL   | NULL   |
+--------+--------+

如第二个SELECT语句所示,定义的属性在执行语句后将被清除。要在多个语句中使用属性值,可以将其分配给变量。下面示例展示了如何做到这一点,并且演示了属性值在后续语句中可以通过变量访问,但不能通过调用mysql_query_attribute_string()函数:

mysql> query_attributes n1 v1 n2 v2;
mysql> SET
         @attr1 = mysql_query_attribute_string('n1'),
         @attr2 = mysql_query_attribute_string('n2');

mysql> SELECT
         @attr1, mysql_query_attribute_string('n1') AS 'attr 1',
         @attr2, mysql_query_attribute_string('n2') AS 'attr 2';
+--------+--------+--------+--------+
| @attr1 | attr 1 | @attr2 | attr 2 |
+--------+--------+--------+--------+
| v1     | NULL   | v2     | NULL   |
+--------+--------+--------+--------+

属性也可以通过将其保存到表中来保存以便后续使用:

mysql> CREATE TABLE t1 (c1 CHAR(20), c2 CHAR(20));

mysql> query_attributes n1 v1 n2 v2;
mysql> INSERT INTO t1 (c1, c2) VALUES(
         mysql_query_attribute_string('n1'),
         mysql_query_attribute_string('n2')
       );

mysql> SELECT * FROM t1;
+------+------+
| c1   | c2   |
+------+------+
| v1   | v2   |
+------+------+

查询属性受以下限制和限制:

  • 如果在发送语句到服务器执行前发生多个属性定义操作,最近的定义操作将覆盖早期操作定义的属性。

  • 如果多个属性定义了同名属性,尝试检索属性值将有未定义的结果。

  • 定义了空名称的属性不能通过名称检索。

  • 属性不适用于使用PREPARE语句准备的语句。

  • 不能在DDL语句中使用mysql_query_attribute_string()函数。

  • 属性不复制。调用mysql_query_attribute_string()函数的语句将在所有服务器上获取不同的值。

使用查询属性的先决条件

要在SQL语句中访问查询属性,其中已经定义了属性,需要安装query_attributes组件。使用以下语句安装:

INSTALL COMPONENT "file://component_query_attributes";

组件安装是一次性操作,不需要在每个服务器启动时执行。INSTALL COMPONENT加载组件,并将其注册到mysql.component系统表,以便在后续服务器启动时加载。

查询组件query_attributes访问查询属性以实现mysql_query_attribute_string()函数。请参阅第7.5.4节,“查询属性组件”

要卸载query_attributes组件,请使用以下语句:

UNINSTALL COMPONENT "file://component_query_attributes";

UNINSTALL COMPONENT卸载组件,并从mysql.component系统表中注销它,以便在后续服务器启动时不加载它。

由于安装和卸载query_attributes组件安装和卸载mysql_query_attribute_string()函数,该组件实现的函数,因此不需要使用CREATE FUNCTIONDROP FUNCTION来实现。

  • mysql_query_attribute_string(name)

    应用程序可以定义对下一个发送到服务器的查询的属性。mysql_query_attribute_string()函数将属性值作为字符串返回,给定属性名称。这使查询可以访问和包含属性的值,该值适用于该查询。

    mysql_query_attribute_string()由安装query_attributes组件安装。请参阅第11.6节,“查询属性”,该节还讨论了查询属性的目的是什么和如何使用它们。

    参数:

    • name:属性名称。

    返回值:

    成功时返回属性值作为字符串,否则返回NULL如果属性不存在。

    示例:

    以下示例使用mysql客户端query_attributes命令定义查询属性,可以由mysql_query_attribute_string()检索。SELECT显示检索一个不存在的属性(n3)返回NULL

    mysql> query_attributes n1 v1 n2 v2;
    mysql> SELECT
        ->   mysql_query_attribute_string('n1') AS 'attr 1',
        ->   mysql_query_attribute_string('n2') AS 'attr 2',
        ->   mysql_query_attribute_string('n3') AS 'attr 3';
    +--------+--------+--------+
    | attr 1 | attr 2 | attr 3 |
    +--------+--------+--------+
    | v1     | v2     | NULL   |
    +--------+--------+--------+