用查询属性把页面或请求来源传给当前 SQL 并在服务器端读取

如果一个页面请求触发了多条 SQL，排查慢查询时经常还想知道“这条 SQL 是哪个页面或接口发出的”。MySQL 8.4 的查询属性可以把这类上下文附着到下一条语句，再由服务器端的 mysql_query_attribute_string() 读取，不必把来源拼进 SQL 注释里。

官方地址：https://dev.mysql.com/doc/refman/8.4/en/query-attributes.html

核心记忆点：客户端先定义属性，服务器端只在对应的下一条语句执行期间可见；语句结束后属性集合会被清空。

先判断请求标签应该停留在哪条 SQL 上

先从生命周期判断问题。查询属性不是普通的会话变量，也不是写进 SQL 文本的注释。它在发送语句前定义，服务端执行结束后立即清除。因此它适合表达“这一次查询来自哪里”，例如页面 URL、接口路由或一次查询需要的额外处理信息。

这也解释了一个常见现象：如果页面请求先定义了 page_url，然后发送一条 SELECT，服务端能读到它；下一条独立的 SELECT 再读取同名属性时，得到的就是 NULL。属性的作用域是单条语句，而不是连接的整个生命周期。

安装组件后让 SQL 读取来源属性

服务器端要读取属性，先安装一次 query_attributes 组件。它会注册 mysql_query_attribute_string() 函数，安装记录也会在后续服务器启动时继续生效。

-- 中文注释：组件只需安装一次，用于注册查询属性读取函数
INSTALL COMPONENT "file://component_query_attributes";

-- 中文注释：不再需要时卸载组件，同时取消后续启动加载
-- UNINSTALL COMPONENT "file://component_query_attributes";

组件准备好后，可以用 mysql 客户端的 query_attributes 命令模拟应用侧传值。下面把页面地址和请求标签附着到紧随其后的查询上：

# 中文注释：query_attributes 是 mysql 客户端命令，不是服务端 SQL
query_attributes page_url https://example.test/orders request_tag order-list;

-- 中文注释：当前 SELECT 读取本次查询携带的两个属性
SELECT
  mysql_query_attribute_string('page_url') AS page_url,
  mysql_query_attribute_string('request_tag') AS request_tag,
  mysql_query_attribute_string('missing_key') AS missing_value;

结果中，page_url 和 request_tag 会返回传入的字符串，missing_key 会得到 NULL。客户端程序若使用 C API，可以通过 mysql_bind_param() 定义属性；其他连接器是否支持，则要以对应连接器文档为准。

为什么下一条查询又读不到了

排查时不要只盯着连接是否还在。属性是在语句执行结束时清空的，所以以下写法即使复用同一个客户端连接，也不能让第二条查询继续读取第一条的属性：

# 中文注释：属性只绑定紧随其后的第一条语句
query_attributes page_url https://example.test/orders;
SELECT mysql_query_attribute_string('page_url') AS first_read;

-- 中文注释：第一条语句结束后，属性集合已被清空
SELECT mysql_query_attribute_string('page_url') AS second_read;

还有三个容易混淆的点。第一，多次定义操作发生在发送语句前时，最后一次定义会替换前面的属性集合。第二，同名属性重复定义后的读取结果没有定义保证，应用侧应该保证名称唯一。第三，属性名使用 character_set_client 指定的字符集传输，命名时应保持稳定、简短并避免空名称。

把读取结果落到变量或表里

如果业务确实需要让来源标签跨过当前语句继续使用，就在属性还可见时把它保存下来。保存到用户变量后，后续语句读取的是变量，不再依赖已经清空的查询属性：

# 中文注释：先在属性生命周期内复制到用户变量
query_attributes page_url https://example.test/orders;
SET @page_url = mysql_query_attribute_string('page_url');

-- 中文注释：后续语句读取用户变量，查询属性本身此时已经不可见
SELECT @page_url AS page_url_for_followup_query;

如果需要形成可审计的业务记录，也可以在同一条带属性的语句中写入表。下面的表结构只是示例，真实系统还应根据字段长度、隐私和保留周期做设计：

-- 中文注释：示例表保存一次查询携带的来源标签
CREATE TABLE request_query_source (
  request_id BIGINT PRIMARY KEY,
  page_url VARCHAR(512) NOT NULL
);

# 中文注释：属性值在 INSERT 执行期间仍然可读
query_attributes page_url https://example.test/orders;
INSERT INTO request_query_source (request_id, page_url)
VALUES (1001, mysql_query_attribute_string('page_url'));

这几个边界要提前排除

• 预处理语句：查询属性不适用于通过 PREPARE 准备的语句，不能把它当成所有执行入口都支持的通用参数通道。
• DDL：mysql_query_attribute_string() 不能用于 DDL 语句；需要记录来源时，应在允许读取的语句中先落地。
• 复制：查询属性不会被复制，调用该函数的语句在不同服务器上不会自动得到相同属性值。
• 缺失值：读取不存在的属性会返回 NULL，写入 NOT NULL 列前要明确兜底策略。
• 数量与命名：mysql 客户端一次最多定义 32 对属性；空名称不能按名称检索，同名重复定义的结果也没有定义保证。

总结：把属性当成一次查询的短生命周期上下文

这类需求的排查顺序很固定：先确认客户端在发送 SQL 前定义了属性，再确认服务器已安装组件，接着在当前语句中读取并处理 NULL。如果要跨语句使用，就立即复制到用户变量或业务表。只要记住“下一条语句可见、执行结束清空”，就不会把查询属性误当成连接级状态。

相关问题

查询属性能代替 SQL 注释做审计吗？它可以把额外信息交给服务器端函数或插件使用，但本文范围只讨论传递和读取；审计字段、权限和保留周期仍要由完整的审计方案决定。

为什么函数读出来是 NULL？优先检查属性是否确实定义在当前语句之前、名称是否完全一致，以及 query_attributes 组件是否已经安装；如果这是第二条独立语句，还要考虑上一条执行后属性已经被清除。