ARTICLE DETAIL

建站实战干货

来自一线的建站与推广经验沉淀，每一条都经过真实交付验证。

首页 / 资讯中心 / 正文

StarRocks DELETE SQLBLACKLIST 实战指南：从黑名单中精准移除禁止的 SQL 正则

2026/9/19 20:59:26 拓冰建站 浏览量
StarRocks DELETE SQLBLACKLIST 实战指南：从黑名单中精准移除禁止的 SQL 正则 StarRocks DELETE SQLBLACKLIST 实战指南从黑名单中精准移除禁止的 SQL 正则【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks本文以 StarRocks 官方文档 DELETE SQLBLACKLIST 为核心系统讲解如何通过DELETE SQLBLACKLIST语句按索引号删除 SQL 黑名单中的正则表达式并结合 FE 源码解析删除命令的底层执行链路与持久化机制。读完本文你将掌握黑名单的增、查、删完整操作闭环以及如何安全地解除误加的 SQL 拦截规则。SQL Blacklist 功能与 DELETE 的定位StarRocks 提供 SQL BlacklistSQL 黑名单能力用于让管理员禁用特定模式的 SQL以避免某些 SQL 触发集群崩溃或引发非预期的高并发查询。该黑名单从 v3.1 起适用于 SELECT 语句和 INSERT 语句从 v3.4 起进一步覆盖 CTASCREATE TABLE AS SELECT语句。黑名单的管理由三条语句构成完整闭环ADD SQLBLACKLIST sql_reg_expr添加一条 SQL 正则到黑名单SHOW SQLBLACKLIST查看黑名单中已有的正则及其索引号DELETE SQLBLACKLIST sql_index_number按索引号删除黑名单中的正则。其中DELETE SQLBLACKLIST 是唯一用于解除拦截的语句。当管理员误加了过于宽泛的规则、或某类 SQL 已被修复不再需要拦截时都需要通过它精确移除对应的正则。使用前提开关与权限在执行DELETE SQLBLACKLIST之前需要满足两个前提条件。第一黑名单功能开关必须已启用。该开关为 FE 配置项enable_sql_blacklist默认值为false关闭定义于 Config.java。可通过以下命令动态开启admin set frontend config (enable_sql_blacklist true);第二必须具备 SYSTEM 级别的 BLACKLIST 权限。删除操作与添加、查看操作一样都要求该权限可通过 GRANT 语句授予。具体授权方式请参阅该文档。语法与参数说明DELETE SQLBLACKLIST的语法非常简洁DELETE SQLBLACKLIST sql_index_number参数说明参数说明sql_index_number黑名单中 SQL 正则表达式的索引号Index。多个索引号之间用逗号,加空格分隔例如3, 4。索引号从哪里来通过 SHOW SQLBLACKLIST 语句获取。SHOW 语句同样需要 SYSTEM 级 BLACKLIST 权限返回两列返回列说明Index已加入黑名单的 SQL 正则表达式的索引号Forbidden SQL已加入黑名单的 SQL 正则表达式索引号由 FE 内部的自增计数器AtomicLong ids见 SqlBlackList.java分配添加新规则时按序递增。可以推断索引号在集群生命周期内只增不减删除某条规则后其索引号不会被复用因此后续 SHOW 出的 Index 可能并非连续整数。实战示例删除两条黑名单规则假设当前黑名单中已有 4 条规则查看结果如下mysql SHOW SQLBLACKLIST; --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | Index | Forbidden SQL | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 1 | select count\(\*\) from . | | 2 | select id_int \* 4, id_tinyint, id_varchar from test_all_type_nullable except select id_int, id_tinyint, id_varchar from test_basic except select \(id_int \* 9 \- 8\) \/ 2, id_tinyint, id_varchar from test_all_type_nullable2 except select id_int, id_tinyint, id_varchar from test_basic_nullable | | 3 | select id_int from test_all_type_select1 order by id_int limit [1-7], [5-7] | | 4 | select count\(distinct .\) from . | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------现在希望移除索引号为 3 和 4 的两条规则例如不再需要拦截count(distinct ...)类的查询执行mysql DELETE SQLBLACKLIST 3, 4;语句执行成功后再次查看黑名单可以看到 3、4 号规则已被删除剩余 1、2 号规则mysql SHOW SQLBLACKLIST; --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | Index | Forbidden SQL | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 1 | select count\(\*\) from . | | 2 | select id_int \* 4, id_tinyint, id_varchar from test_all_type_nullable except select id_int, id_tinyint, id_varchar from test_basic except select \(id_int \* 9 \- 8\) \/ 2, id_tinyint, id_varchar from test_all_type_nullable2 except select id_int, id_tinyint, id_varchar from test_basic_nullable | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------注意SHOW 输出中Forbidden SQL一列展示的是对所有 SQL 语义字符进行了转义后的正则例如count\(\*\)。这与 ADD 时提交的原始正则存在转义差异是正常现象不要误以为黑名单内容被改写。理解 Forbidden SQL 的转义规则要准确判断删哪条、留哪条需要理解黑名单正则的书写规则。由于 SQL 本身包含(,),*,.等与正则表达式语义容易混淆的字符StarRocks 的处理原则是(和)在 SQL 中出现过于频繁无需转义StarRocks 可直接识别其他特殊字符需要用转义符\作前缀加以区分。几个典型示例完整示例见 Blacklist Management拦截目标添加语句禁止count(*)ADD SQLBLACKLIST select count(\\*) from .;禁止count(distinct ...)ADD SQLBLACKLIST select count(distinct .) from .;禁止特定order by ... limit x, y区间ADD SQLBLACKLIST select id_int from test_all_type_select1 order by id_int limit [1-7], [5-7];禁止所有 INSERT INTO 语句ADD SQLBLACKLIST (?i)^insert\\sinto\\s.*;禁止所有 INSERT INTO ... VALUES 语句ADD SQLBLACKLIST (?i)^insert\\sinto\\s.*values\\s*\\(;从源码看添加规则时 FE 会把用户提交的 SQL 正则先做归一化处理.trim().toLowerCase().replaceAll( , ).replace(\r, ).replace(\n, ).replaceAll(\\s, )然后调用Pattern.compile(sql)编译为正则对象见 SqlBlackList.java。这意味着黑名单匹配是大小写不敏感的全部小写化后匹配且语句中的连续空白会被压缩为单个空格。底层原理DELETE 的执行链路与持久化DELETE SQLBLACKLIST并非简单的内存操作其执行涉及完整的 FE 元数据持久化链路。核心实现位于 SqlBlackList.java调用关系如下语句分发FE 解析 SQL 后StmtExecutor识别出DelSqlBlackListStmt类型的语句调用handleDelSqlBlackListStmt()见 StmtExecutor.java。删除入口deleteBlackSql(DelSqlBlackListStmt)取出语句中的索引号列表通过 EditLog 记录删除操作logDeleteSQLBlackList并在 WAL 回调中逐条调用delete(id)见 SqlBlackList.java。这保证了删除操作会先写入编辑日志再实际生效从而在 FE 宕机后可通过日志重放恢复状态。内存删除delete(long id)加锁遍历内部的ConcurrentHashMapString, BlackListSql找到 id 匹配的条目后移除并刷新只读快照ruleSnapshot见 SqlBlackList.java。快照按 id 升序排序供后续 SHOW 和匹配使用。快照持久化集群元数据做 checkpoint 时save(ImageWriter)会把黑名单全量写入 SRMetaBlock见 SqlBlackList.javaFE 重启时通过load(SRMetaBlockReader)恢复。因此删除操作在集群内是持久且可恢复的。删除后的效果黑名单匹配机制删除规则后对应的 SQL 不再被拦截。理解匹配机制有助于确认删除是否生效在每次执行 SQL 前StmtExecutor会检查语句类型QueryStatement/InsertStmt/CreateTableAsSelectStmt当Config.enable_sql_blacklist为 true、且语句不是 EXPLAIN、不是代理转发的 SQL、不属于统计信息连接或统计任务时会调用SqlBlackList.verifying(originSql)对原始 SQL 做匹配见 StmtExecutor.java。匹配逻辑位于verifying()将 SQL 的换行替换为空格、压缩连续空白后依次与快照中的每条正则执行Matcher.find()一旦命中即递增指标COUNTER_SQL_BLOCK_HIT_COUNT并抛出错误ERR_SQL_IN_BLACKLIST_ERROR见 SqlBlackList.java。被拦截的客户端会看到类似如下报错ERROR 1064 (HY000): Access denied; sql select count (*) from test_all_type_select_2556 is in blacklist因此验证删除是否生效最直接的方式是执行DELETE SQLBLACKLIST后用SHOW SQLBLACKLIST确认目标索引已消失再重跑一条此前会被拦截的 SQL观察其是否恢复正常执行。最佳实践与注意事项删除前先 SHOW按索引精准操作索引号是删除的唯一依据务必先用SHOW SQLBLACKLIST确认目标规则及编号避免误删。多条删除可一次性完成如3, 4减少操作次数。注意规则匹配的宽泛性正则匹配采用find()而非全串匹配且大小写不敏感、空白被压缩一条宽泛规则可能拦截大量 SQL。删除前应评估该规则当前覆盖的 SQL 类型。开启后全量过滤谨慎启停enable_sql_blacklist开启后每条查询都会经过黑名单过滤会产生额外匹配开销不必要时保持默认关闭。权限最小化BLACKLIST 为 SYSTEM 级权限只授予需要管理黑名单的管理员账号。变更可持久删除操作会写入 EditLog 并最终进入元数据快照无需担心 FE 重启后规则复活同样若希望彻底清空黑名单并重置索引号需要走元数据层面的cleanup()流程该行为不会由普通 DDL 触发。相关文档与源码索引黑名单功能总览Blacklist Management添加规则ADD SQLBLACKLIST查看规则SHOW SQLBLACKLIST权限授予GRANT核心实现SqlBlackList.java执行入口与匹配触发StmtExecutor.java开关配置项Config.java【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考