企业官网建设流程全解析

• 数据库
• OLAP
• 数据仓库
• 大数据
• 湖仓一体
• 数据分析

StarRocks 提供的REFRESH CONNECTIONS命令用于将SET GLOBAL修改后的全局变量立即下发到集群中所有活跃连接，解决连接池等长生命周期连接无法感知运行时参数调整的问题。本文将结合官方文档与 FE 端源码实现，完整讲解该命令的语法、参数、执行语义、权限要求、底层实现原理与实测用例，帮助你安全高效地在生产集群中批量刷新会话变量。

为什么需要 REFRESH CONNECTIONS

在 StarRocks 中，SET GLOBAL修改的是全局默认值，默认情况下它只对新建连接生效。已经建立的会话会在本地缓存一份会话变量的副本，除非该连接主动断开重连或显式执行SET SESSION，否则不会感知全局变量发生变化。这一行为与 MySQL 一致，但在生产环境中会带来一个实际问题：

• 应用程序通常通过连接池维护长连接，连接很少断开重建；
• 当 DBA 调整query_timeout、exec_mem_limit等运行时参数时，存量连接依然沿用旧值，参数调整无法真正"落地"；
• 逐一SET SESSION或重启应用都不现实。

REFRESH CONNECTIONS正是为解决这一问题而设计的：管理员执行一次命令，即可让集群内所有活跃连接刷新为最新的全局变量值，无需连接重连。

语法与参数

REFRESH CONNECTIONS [FORCE];

从语法层面看，该命令的 ANTLR 文法规则定义在 StarRocks.g4：

refreshConnectionsStatement : REFRESH CONNECTIONS (FORCE)? ;

FORCE为可选关键字。解析后生成对应的 AST 节点 RefreshConnectionsStmt，其中用一个boolean force字段记录是否强制执行，并向外暴露isForce()方法供执行器读取。

执行行为详解

选择性刷新（默认行为）

默认情况下（不指定FORCE），命令只刷新未被会话自身修改过的变量。判断依据是连接上下文（ConnectContext）中维护的"已修改会话变量表"（modifiedSessionVariablesMap）。也就是说：

• 连接 A 从未执行过SET SESSION，则其所有可全局设置的变量都会被刷新为最新全局值；
• 连接 B 执行过SET SESSION query_timeout = 500，则其query_timeout保持 500，不被覆盖，其余未修改的变量照常刷新。

强制刷新（FORCE）

指定FORCE后，所有变量无条件刷新为全局值，包括被SET SESSION覆盖过的变量。同时：

• 被强制重置的变量会从会话的"已修改变量表"中移除，修改标记被清除；
• 这意味着后续再执行不带FORCE的REFRESH CONNECTIONS时，这些变量会被正常刷新，而不会再被当作"会话自定义值"跳过。

立即生效但不打断正在执行的语句

正在运行中的语句不受影响，刷新操作会在下一条命令执行前生效。这保证了刷新过程不会中断正在进行的查询。

集群级广播

命令执行后会通过 RPC 自动分发到集群中的所有 FE 节点，确保整个集群的存量连接都被刷新，实现全局一致性。

权限要求

只有具备 SYSTEM 对象上OPERATE权限的用户才能执行该命令。典型授权语句：

GRANT OPERATE ON SYSTEM TO 'admin_user';

源码级实现剖析

执行入口

REFRESH CONNECTIONS在 StmtExecutor 中被处理：

private void handleRefreshConnectionsStmt() { try { RefreshConnectionsStmt stmt = (RefreshConnectionsStmt) parsedStmt; GlobalStateMgr.getCurrentState().getVariableMgr().refreshConnections(stmt.isForce()); } catch (Exception e) { context.getState().setError(e.getMessage()); return; } context.getState().setOk(); }

语句解析后直接调用VariableMgr.refreshConnections(force)完成刷新。权限校验则发生在分析阶段，由 AuthorizerStmtVisitor 调用Authorizer.checkSystemAction(context, PrivilegeType.OPERATE)完成。

核心刷新逻辑

VariableMgr.refreshConnections(boolean force) 分两步执行：

public void refreshConnections(boolean force) { // Refresh on current node refreshConnectionsInternal(force); // Notify other FE nodes via RPC if (GlobalStateMgr.getCurrentState().isLeader()) { notifyOtherFEsToRefreshConnections(force); } }

1. 本节点刷新：refreshConnectionsInternal(force)从ConnectScheduler的连接表中取出全部活跃连接，逐个刷新；
2. 跨 FE 广播：若当前节点是 Leader，则遍历节点管理器中除自身外的所有 FE，通过 Thrift RPC 调用client.refreshConnections(request)通知其执行同样的刷新（见 notifyOtherFEsToRefreshConnections），RPC 超时与重试次数分别由Config.thrift_rpc_timeout_ms和Config.thrift_rpc_retry_times控制。单个 FE 刷新失败仅记录 WARN 日志，不会中断整体流程。

单连接的变量筛选规则

对每个连接，refreshConnectionVariables通过反射遍历SessionVariable类上带@VarAttr注解的所有字段，并按以下规则逐一判断（见 VariableMgr.refreshConnectionVariables）：

1. 会话已修改：非FORCE模式下，若变量出现在modifiedSessionVariablesMap中则跳过；
2. 仅会话可见：带有SESSION_ONLY标志的变量（无法通过SET GLOBAL设置）跳过，这正是文档中"会话级专属变量不受影响"的实现依据；
3. 不回传 Leader：带有DISABLE_FORWARD_TO_LEADER标志的变量跳过，因为它们不受全局变更影响；
4. 值未变化：仅当全局默认值与当前会话值不同（!Objects.equals(defaultValue, currentValue)）时才真正写入新值并计数；FORCE模式下即使值相同，也会清除该变量的"已修改"标记，为后续非强制刷新铺路。

值得注意的是，刷新逻辑会跳过带有DISABLE_FORWARD_TO_LEADER标志的变量——这与SET GLOBAL在该类变量上的转发限制保持一致，是文档 Notes 部分对应底层行为的具体体现。

空连接表的容错

若ConnectScheduler尚未初始化或连接表为空，refreshConnectionsInternal直接返回（仅记录 WARN 日志），不会抛错。这一点也有对应单元测试覆盖（见下文）。

实操示例

示例 1：修改单个全局变量后刷新

mysql> SET GLOBAL query_timeout = 600; Query OK, 0 rows affected (0.00 sec) mysql> REFRESH CONNECTIONS; Query OK, 0 rows affected (0.00 sec)

执行后，所有活跃连接（除了那些在会话中自行修改过query_timeout的连接）的query_timeout都会更新为 600。

示例 2：修改多个全局变量后刷新

mysql> SET GLOBAL query_timeout = 600; Query OK, 0 rows affected (0.00 sec) mysql> SET GLOBAL exec_mem_limit = 2147483648; Query OK, 0 rows affected (0.00 sec) mysql> REFRESH CONNECTIONS; Query OK, 0 rows affected (0.00 sec)

一次刷新同时应用多个全局变量的最新值，未被子会话覆盖的变量都会更新。

示例 3：强制刷新所有连接

mysql> SET GLOBAL query_timeout = 600; Query OK, 0 rows affected (0.00 sec) mysql> REFRESH CONNECTIONS FORCE; Query OK, 0 rows affected (0.00 sec)

执行后，所有活跃连接的query_timeout都会更新为 600，即使某个连接此前执行过SET SESSION query_timeout = 500。

注意事项

• 会话自定义值默认被保留：例如某连接执行过SET SESSION query_timeout = 500，即使执行REFRESH CONNECTIONS，该连接的query_timeout仍为 500；只有使用REFRESH CONNECTIONS FORCE才会强制覆盖。
• FORCE 会清除修改标记：FORCE刷新后，被强制重置的变量会从会话修改记录中移除，后续非强制刷新可以正常更新它们。
• 影响范围：命令作用于集群所有 FE 节点上的全部活跃连接。
• 不受影响的变量：会话级专属变量（不能全局设置）不受影响；带有DISABLE_FORWARD_TO_LEADER标志的变量不会被刷新。
• 权限：需要 SYSTEM 对象的 OPERATE 权限，普通用户执行会返回权限拒绝错误。

单元测试印证

仓库中的 RefreshConnectionsStmtTest 对上述行为做了系统验证，可作为理解语义的参考：

• testParseRefreshConnections/testParseRreshConnectionsForce：验证FORCE标志的解析；
• testRefreshConnectionsWithOperatePrivilege/testRefreshConnectionsWithoutOperatePrivilege：验证 OPERATE 权限的授予与拒绝（无权限时抛出AccessDeniedException）；
• testRefreshConnectionsExecution：会话修改过的query_timeout保持 500 不被刷新；清空修改记录后再次刷新，成功更新为全局值 900；
• testRefreshConnectionsOnlyUnmodifiedVariables：同时验证会话修改过的变量（query_timeout保持 600）与未修改变量（exec_mem_limit刷新为 1000000000）的差异行为；
• testRefreshConnectionsForce：FORCE强制将会话值 500 覆盖为全局值 1000；
• testForceRefreshClearsModifiedVariables：FORCE后修改标记被清除，随后非强制刷新可正常更新；
• testRefreshConnectionsInternalWithNullScheduler、testNotifyOtherFEsWithRPCException、testNotifyOtherFEsWithErrorResponse：验证调度器未初始化、RPC 异常、远端返回错误等场景下命令均不会抛出异常（容错降级）。

关联语句

• SET：设置系统变量或用户自定义变量（SET GLOBAL与REFRESH CONNECTIONS配合使用）；
• SHOW VARIABLES：查看系统变量当前取值，可用于核对刷新结果。

• 数据库
• OLAP
• 数据仓库
• 大数据
• 湖仓一体
• 数据分析