SQL限流介紹及樣本 - PolarDB

為應對突發的資料庫請求流量、資源消耗過高的語句訪問以及SQL訪問模型的變化等問題，PolarDB-X提供了節點層級的SQL限流功能來限制造成上述問題的SQL執行，從而保證執行個體的持續穩定運行。本文介紹如何使用SQL限流功能。

版本限制

僅計算節點組件版本為5.4.9-16167266及以上的PolarDB-X企業版執行個體支援SQL限流功能，其中慢SQL限流觸發器則需要執行個體的計算節點組件版本為5.4.11-16251897及以上。

說明

執行個體版本的規則說明，請參見版本說明。
執行個體版本的查看方式，請參見查看執行個體版本。

建立限流規則

文法

CREATE CCL_RULE [ IF NOT EXISTS ] `ccl_rule_name`
ON `database`.`table`
TO '<username>'@'<host>'
FOR { UPDATE | SELECT | INSERT | DELETE }
[ filter_options ]
with_options

filter_options:
    [ FILTER  BY KEYWORD('KEYWORD1', 'KEYWORD2',…) ]
    [ FILTER  BY TEMPLATE('template_id') ]
    
 with_options:
    WITH MAX_CONCURRENCY = value1 [ , WAIT_QUEUE_SIZE = value2 ] [ , WAIT_TIMEOUT = value3 ] [ ,FAST_MATCH = { 0 , 1 }]

參數說明：

參數		是否必選	說明
限流規則匹配參數	`ccl_rule_name`	必選	限流規則的名稱。說明為避免名稱與SQL關鍵字衝突，建議在規則名稱前後各加一個反引號（`）。
	`database`.`table`	必選	資料庫和資料表的名稱，支援使用星號（*）表示任意匹配。說明為避免名稱與SQL關鍵字衝突，建議在庫表名稱前後各加一個反引號（`）。
	`'<username>'@'<host>'`	必選	帳號名稱。其中`host`部分支援用百分比符號（%）來表示任意匹配。
	`UPDATE \| SELECT \| INSERT \| DELETE`	必選	SQL語句類型。當前支援UPDATE、SELECT、INSERT和DELETE類型。說明每條限流規則僅支援傳入一種類型的SQL語句。
	`[ filter_options ]`	可選	過濾條件，支援包括如下兩種條件：關鍵詞（KEYWORD）：查看限流規則時，關鍵詞列表會在查詢結果中被轉化為`["kwd1","kw2","kw3"...]`的字串形式，最多支援512個字元。說明若關鍵字是SQL語句中的參數值，匹配時大小寫敏感。若關鍵字是SQL語句中的其他詞，匹配時大小寫不敏感。模板（TEMPLATE）：模板編號是SQL日誌中的`sql_code`值，該值是參數化後的SQL語句（SQL模板）以16進位表示的雜湊值。您可以通過`SHOW FULL PROCESSLIST`和`EXPLAIN`命令查看模板編號。
限流規則行為控制參數	`with_options`	必選	WITH選項中支援如下4個參數來控制限流規則的行為： MAX_CONCURRENCY：匹配到該限流規則的SQL語句的最大並發度，超過後進入等待隊列。取值範圍：[0~2³¹ - 1]，預設值為0。 WAIT_QUEUE_SIZE：超過並發度後的最大等待隊列長度。當等待隊列長度超過該值後，SQL語句將報錯。在隊列中的語句仍然佔用了線程資源，排隊過多時也可能導致記憶體耗盡。取值範圍：[0~2³¹ - 1]，預設值為0。 WAIT_TIMEOUT：SQL語句在等待隊列中的最長等待時間，超過該等待時間後，SQL語句將報錯。取值範圍：[0~2³¹ - 1]，單位為秒，預設值為600。 FAST_MATCH：是否開啟Cache來加速匹配。開啟後，模板會將模板編號作為Cache key的一部分，匹配結果作為value進行緩衝，來加速匹配速度。取值範圍：0表示關閉，1表示開啟，預設開啟。說明建立限流規則時，需從上述4個行為控制參數中至少選擇一個傳入。當MAX_CONCURRENCY為預設值（0）時，可能會使匹配到的所有SQL返回錯誤。此時，建議您顯式指定該參數為非0的值。 PolarDB-X是分布式雲原生資料庫，計算層由多個節點群組成，因此每個節點的並發度之和是整個執行個體的並發數最大值。在負載不均衡的情況下，整個執行個體的受限制SQL並發數可能無法達到最大並發數。

說明

僅當一個SQL語句滿足所有的匹配參數條件時，才會根據該規則的WITH選項進行限流。

樣本

假設需要建立一條名為selectrule的規則，用於限制帳號為'ccltest'@'%'使用者發起的，包含cclmatched關鍵字的，且對任意表執行SELECT操作的SQL語句，同時將最大並發度設定為10。

規則建立語句如下：

CREATE CCL_RULE IF NOT EXISTS `selectrule` ON *.* TO 'ccltest'@'%'
FOR SELECT
FILTER BY KEYWORD('cclmatched')
WITH MAX_CONCURRENCY=10;

說明

帳號ccltest從任何IP發起的查詢（SELECT語句），且含有cclmatched關鍵字，這一類查詢語句的最高並發為10。

限流結果

某條SQL匹配到該規則後，根據限流規則中WITH選項裡配置的參數，會出現如下幾種結果：

RUN（可運行）
若並發度還未達到最大並發度（即MAX_CONCURRENCY參數值沒有達到最大值），該SQL正常執行不會被限流。

WAIT（等待中）

若並發度已經達到最大並發度，但等待隊列長度還未達到最大長度（即WAIT_QUEUE_SIZE參數值沒有達到最大值），該SQL進入等待狀態，直到進入可運行（RUN）狀態，或者等待逾時（WAIT_TIMEOUT）狀態。您可以通過如下命令查看由於匹配到限流規則而等待的SQL語句：

SHOW FULL PROCESSLIST;

結果如下：

+----+---------------+-----------------+----------+-------------------------------+------+-------+-----------------------+-----------------+
| ID | USER          | HOST            | DB       | COMMAND                       | TIME | STATE | INFO                  | SQL_TEMPLATE_ID |
+----+---------------+-----------------+----------+-------------------------------+------+-------+-----------------------+-----------------+
|  2 | polardbx_root | ***.*.*.*:62787 | polardbx | Query                         |    0 |       | show full processlist | NULL            |
|  1 | polardbx_root | ***.*.*.*:62775 | polardbx | Query(Waiting-selectrulereal) |   12 |       | select 1              | 9037e5e2        |
+----+---------------+-----------------+----------+-------------------------------+------+-------+-----------------------+-----------------+
2 rows in set (0.08 sec)

說明

SQL語句select 1由於限流規則selectrulereal而處於等待（Waiting）狀態。

WAIT_TIMEOUT（等待逾時）
SQL語句進入等待狀態後，當等待時間超過最長等待時間（WAIT_TIMEOUT）時，該語句將會執行失敗並返回錯誤資訊。例如：設定了一條最長等待時間為10秒的限流規則，執行SELECT sleep(11)語句時會因為等待逾時而報錯，樣本如下：
```
ERROR 3009 (HY000): [11a07e23fd800000][30.225.XXX.XX:8527][polardbx]Exceeding the max concurrency 0 of ccl rule selectrulereal after waiting for 10060 ms
```
KILL（結束）
並發度和等待隊列長度均已經達到最大值，用戶端將收到超過最大並發度的報錯，報錯資訊中會包含匹配上的限流規則的名稱。例如：在並發度和等待隊列長度均已經達到最大值後執行SELECT 1;命令，會出現如下報錯：
```
ERROR 3009 (HY000): [11a07c4425c00000][**.***.***.**:8527][polardbx]Exceeding the max concurrency 0 of ccl rule selectrulereal
```
說明
該SQL語句SELECT 1;由於超出了限流規則selectrulereal設定的最大並發度而執行失敗。

查看限流規則

查看指定限流規則

指定規則名稱進行查看，多個名稱用,分隔。

文法：

SHOW CCL_RULE `ccl_rule_name1` [, `ccl_rule_name2` ]

樣本：

SHOW CCL_RULE `selectrulereal`

結果如下：

                     NO.: 1
               RULE_NAME: selectrulereal
                 RUNNING: 2
                 WAITING: 29
                  KILLED: 0
         MATCH_HIT_CACHE: 21374
             TOTAL_MATCH: 21406
       ACTIVE_NODE_COUNT: 2
MAX_CONCURRENCY_PER_NODE: 1
WAIT_QUEUE_SIZE_PER_NODE: 100
            WAIT_TIMEOUT: 600
              FAST_MATCH: 1
                SQL_TYPE: SELECT
                    USER: ccltest@%
                   TABLE: *.*
                KEYWORDS: ["SELECT"]
              TEMPLATEID: NULL
            CREATED_TIME: 2020-11-26 17:04:08

欄位說明：

欄位	說明
NO.	匹配優先順序，數字越小，優先順序越高。
RULE_NAME	限流規則名稱。
RUNNING	匹配到該限流規則且正常執行的SQL語句數量。
WAITING	匹配到該限流規則且正在等待隊列裡的查詢數量。
KILLED	匹配到該限流規則且被KILL的SQL語句數量。
MATCH_HIT_CACHE	匹配到該限流規則且命中Cache的SQL語句數量。
TOTAL_MATCH	匹配到該限流規則命中的總次數。
ACTIVE_NODE_COUNT	計算層中啟用了SQL限流的節點數。
MAX_CONCURRENCY_PER_NODE	每個計算節點的並發度。
WAIT_QUEUE_SIZE_PER_NODE	每個計算節點上等待隊列的最大長度。
WAIT_TIMEOUT	SQL語句在等待隊列的最大等待時間。
FAST_MATCH	是否啟動緩衝加速匹配速度。
SQL_TYPE	SQL語句類型。
USER	使用者名稱。
TABLE	資料庫表。
KEYWORDS	關鍵詞列表。
TEMPLATEID	SQL模板的編號。
CREATED_TIME	建立時間（本地時間），格式為`yyyy-MM-dd HH:mm:ss`。

查看所有限流規則

SHOW CCL_RULES;

刪除限流規則

說明

被刪除的限流規則會立即失效，此時該規則下等待隊列中的SQL語句全部會被正常執行。

刪除指定限流規則。

指定規則名稱進行刪除，多個名稱用,分隔。

文法：

DROP CCL_RULE [ IF EXISTS ] `ccl_rule_name1` [, `ccl_rule_name2`, ...]

樣本：

DROP CCL_RULE IF EXISTS `selectrulereal`;

刪除所有限流規則：
```
CLEAR CCL_RULES;
```

慢SQL限流觸發器

開啟慢SQL限流觸發器

當SQL的執行時間超過某一閾值時，系統可以自動為該SQL建立一個限流規則。

文法：

SLOW_SQL_CCL GO ['SQL_TYPE'[MAX_CONCURRENCY] [SLOW_SQL_TIME] [MAX_CCL_RULE]]

樣本：

SLOW_SQL_CCL GO 'SELECT' 2 5 2;

說明

參數說明：
- SQL_TYPE：取值為ALL，SELECT，UPDATE，INSERT，預設值為SELECT。相同語句類型的命令，有更新作用。
- MAX_CONCURRENCY：自動建立的限流規則的最高並發數，預設值為CPU核心數的一半。
- SLOW_SQL_TIME：慢SQL的執行時間，SQL執行時間超過此值時會執行該觸發器，預設值為系統參數SLOW_SQL_TIME的值，單位為毫秒（ms）。
- MAX_CCL_RULE：可建立限流規則的個數，預設值為1000。
執行過程：
1. 遍曆整個執行個體的Session，識別出該語句類型慢SQL的TemlateId。
2. 建立針對慢SQL的限流觸發器，名稱為：_SYSTEM_SLOW_SQL_CCL_TRIGGER_{SQL_TYPE}_。
3. 傳遞慢SQL的TemplateId給限流觸發器，由限流觸發器建立限流規則。
4. KILL（結束）所有超過MAX_CONCURRENCY的該語句類型的慢TemplateId查詢。

查看慢SQL限流觸發器

SLOW_SQL_CCL SHOW;

結果如下：

欄位名	值
NO.	1
SCHEMA	__cdc__
TEMPLATE_ID	1394f5db
SQL	SELECT * FROM test
RULE_NAME	AUTO__SYSTEM_SLOW_SQL_CCL_TRIGGER_SELECT____cdc___1394f5db_9e1c7f6d
RUNNING	0
WAITING	0
KILLED	0
TOTAL_MATCH	0
ACTIVE_NODE_COUNT	4
MAX_CONCURRENCY_PER_NODE	2
CREATED_TIME	2025-04-23 00:00:00

調整慢SQL的閾值

調整慢SQL的閾值有三種方式，按優先順序降序排序如下：

在SLOW_SQL_CCL GO語句中設定SLOW_SQL_TIME參數的值。
在一鍵開啟SQL限流之前，設定使用者變數SLOW_SQL_TIME。
樣本：
```
SET @slow_sql_time=2000;
SLOW_SQL_CCL GO;
```
在控制台上設定系統參數SLOW_SQL_TIME。

關閉慢SQL限流觸發器

關閉由SLOW_SQL_CCL GO建立的限流觸發器，會同時刪除由限流觸發器建立的限流規則。

SLOW_SQL_CCL BACK;