企业官网建设流程全解析

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

【免费下载链接】starrocksThe world's 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 Blacklist（SQL 黑名单）能力，用于让管理员禁用特定模式的 SQL，以避免某些 SQL 触发集群崩溃或引发非预期的高并发查询。该黑名单从 v3.1 起适用于 SELECT 语句和 INSERT 语句，从 v3.4 起进一步覆盖 CTAS（CREATE 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>

参数说明：

索引号从哪里来？通过 SHOW SQLBLACKLIST 语句获取。SHOW 语句同样需要 SYSTEM 级 BLACKLIST 权限，返回两列：

索引号由 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）：

从源码看，添加规则时 FE 会把用户提交的 SQL 正则先做归一化处理：.trim().toLowerCase().replaceAll(" +", " ").replace("\r", " ").replace("\n", " ").replaceAll("\\s+", " ")，然后调用Pattern.compile(sql)编译为正则对象（见 SqlBlackList.java）。这意味着黑名单匹配是大小写不敏感的（全部小写化后匹配），且语句中的连续空白会被压缩为单个空格。

底层原理：DELETE 的执行链路与持久化

DELETE SQLBLACKLIST并非简单的内存操作，其执行涉及完整的 FE 元数据持久化链路。核心实现位于 SqlBlackList.java，调用关系如下：

1. 语句分发：FE 解析 SQL 后，StmtExecutor识别出DelSqlBlackListStmt类型的语句，调用handleDelSqlBlackListStmt()（见 StmtExecutor.java）。

2. 删除入口：deleteBlackSql(DelSqlBlackListStmt)取出语句中的索引号列表，通过 EditLog 记录删除操作（logDeleteSQLBlackList），并在 WAL 回调中逐条调用delete(id)（见 SqlBlackList.java）。这保证了删除操作会先写入编辑日志，再实际生效，从而在 FE 宕机后可通过日志重放恢复状态。

3. 内存删除：delete(long id)加锁遍历内部的ConcurrentHashMap<String, BlackListSql>，找到 id 匹配的条目后移除，并刷新只读快照ruleSnapshot（见 SqlBlackList.java）。快照按 id 升序排序，供后续 SHOW 和匹配使用。

4. 快照持久化：集群元数据做 checkpoint 时，save(ImageWriter)会把黑名单全量写入 SRMetaBlock（见 SqlBlackList.java）；FE 重启时通过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，观察其是否恢复正常执行。

最佳实践与注意事项

1. 删除前先 SHOW，按索引精准操作：索引号是删除的唯一依据，务必先用SHOW SQLBLACKLIST确认目标规则及编号，避免误删。多条删除可一次性完成（如3, 4），减少操作次数。
2. 注意规则匹配的宽泛性：正则匹配采用find()而非全串匹配，且大小写不敏感、空白被压缩，一条宽泛规则可能拦截大量 SQL。删除前应评估该规则当前覆盖的 SQL 类型。
3. 开启后全量过滤，谨慎启停：enable_sql_blacklist开启后，每条查询都会经过黑名单过滤，会产生额外匹配开销；不必要时保持默认关闭。
4. 权限最小化：BLACKLIST 为 SYSTEM 级权限，只授予需要管理黑名单的管理员账号。
5. 变更可持久：删除操作会写入 EditLog 并最终进入元数据快照，无需担心 FE 重启后规则"复活"；同样，若希望彻底清空黑名单并重置索引号，需要走元数据层面的cleanup()流程，该行为不会由普通 DDL 触发。

相关文档与源码索引

• 黑名单功能总览：Blacklist Management
• 添加规则：ADD SQLBLACKLIST
• 查看规则：SHOW SQLBLACKLIST
• 权限授予：GRANT
• 核心实现：SqlBlackList.java
• 执行入口与匹配触发：StmtExecutor.java
• 开关配置项：Config.java

【免费下载链接】starrocksThe world's 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