云数据库 RDS：SQL限流（rds_ccl）

使用场景

该函数只能在主实例中调用，用于创建一个SQL限流规则。

语法

• 语法一：根据设置的SQL语句进行限流。

  SELECT rds_add_ccl_rule(
  	query_string varchar,
  	node_tag int,
  	max_concurrency int,
  	max_waiting int,
  	is_enabled boolean,
  	comment varchar,		-- 可选
  	search_path varchar		-- 可选
  );

• 语法二：根据设置的query_id进行限流。

  SELECT rds_add_ccl_rule_with_query_id(
    query_id		bigint,
    node_tag		int,
    max_concurrency	int,
    max_waiting		int,
    is_enabled		boolean,
    query_string		varchar,	-- 可选
    comment		varchar,	-- 可选
    search_path           varchar		-- 可选（1.2及之后版本支持）
  );

参数解释

-- 使用$$包裹SQL语句
$$SELECT * FROM my_table;$$

-- SQL语句中已存在$$，使用$ccl$包裹SQL语句
$ccl$SELECT * FROM my_table WHERE my_column = $$hello$$;$ccl$

注意事项

• 在语法一中，comment和search_path如果不配置，可以填写为空字符串（''），如果配置为NULL，则函数不会进行任何操作而直接返回。

• 在语法二中：

  • query_string和comment如果不配置，可以填写为空字符串（''），如果配置为NULL，则函数不会进行任何操作而直接返回。

  • 如果同时配置了query_id和query_string，AliPG内核将以query_id为准进行SQL限流。

• 该函数会返回ccl_id，ccl_id是当前数据库下限流规则的唯一标识。

SQL示例

在主实例的ccl_test数据库中，有数据表ccl_tbl，创建SQL限流规则：

1. 对所有的SELECT * FROM ccl_tbl语句（假设其query_id=1）进行限流。

2. 最多允许3条此类SQL并发执行。

3. 最多允许2个此类SQL等待。

4. 规则创建成功后立即生效。

• 语法一：

  SELECT rds_add_ccl_rule(
    $$SELECT * FROM ccl_tbl;$$,		-- 待限流的SQL语句，使用$$包裹
    1,					-- 仅限制主实例
    3,					-- 最多允许3条此类SQL并发执行
    2,					-- 最多允许2个此类SQL等待
    true,					-- 规则立即生效
    'limit constant select',		-- 规则描述
    ''					-- 使用默认的search_path
  );

• 语法二：

  SELECT rds_add_ccl_rule_with_query_id(
    1,					-- 待限流的SQL语句的query_id
    1,					-- 仅限制主实例
    3,					-- 最多允许3条此类SQL并发执行
    2,					-- 最多允许2个此类SQL等待
    true,					-- 规则立即生效
    ''					-- SQL语句的文本，本示例不填写	
    'limit constant select',		-- 规则描述
    'public'                              -- search_path
  );

使用场景

该命令可以在主实例或只读实例中使用，用于查询已创建的SQL限流规则。

语法

• 查看当前实例中所有库下的SQL限流规则：

  SELECT * FROM rds_enabled_ccl_rule;

  说明

  • 此命令查询结果中，由于显示限制，query_string和comment的信息会被截断，只显示前200个字符，如果需要查看完整信息，请使用SELECT * FROM rds_show_current_db_ccl_rule();命令。

  • 1.2及之后版本rds_ccl的支持返回search_path。

• 查询当前数据库下的所有SQL限流规则：

  SELECT * FROM rds_show_current_db_ccl_rule();

使用场景

该函数只能在主实例中调用，适用于以下场景：

• 如果创建SQL限流规则时，is_enabled参数配置为false，则可以使用此函数使规则生效。

• 使失效的规则再次生效。

语法

SELECT rds_enable_ccl_rule(ccl_id int);

参数解释

注意事项

无

SQL示例

SELECT rds_enable_ccl_rule(1);

使用场景

该函数可以在主实例或只读实例中调用，用于加载SQL限流规则，只有被加载的规则才会发挥SQL限流作用。

适用于以下场景：

• 主实例：

  • 创建SQL限流规则时，如果is_enabled配置为true，则规则会自动加载到主实例，无需手动调用。

  • 创建SQL限流规则时，如果is_enabled配置为false，调用rds_enable_ccl_rule函数使规则生效时，规则会自动加载到主实例，无需手动调用。

  • 如果主实例重启，则需要手动调用此函数，加载规则。

• 只读实例：

  如果需要规则在只读实例发挥作用，则需要在主实例创建规则（node_tag配置为2或3）后，再在只读实例中调用此函数，手动加载规则。

语法

SELECT rds_load_ccl_rule(ccl_id int);

参数解释

注意事项

• 只有在主实例中调用rds_add_ccl_rule函数创建了SQL限流规则，且node_tag配置为2或3时，才能在只读实例中加载规则。

• 失效的规则无法被加载，如果只读实例需要加载某条失效的规则，请先在主实例中使其生效，具体方法，请参见使SQL限流规则生效。

SQL示例

SELECT rds_load_ccl_rule(1);

使用场景

该函数只能在主实例中调用，用于变更SQL限流规则中的最大并发数和最大等待数。

语法

SELECT rds_update_ccl_rule(
	ccl_id int,
	new_max_concurrency int,
	new_max_waiting int
);

参数解释

注意事项

• 更新SQL限流规则后，规则立即生效。

• 当前仅支持变更SQL限流规则中的最大并发数和最大等待数。

SQL示例

SELECT rds_update_ccl_rule(
 2,     -- ccl_id
 4,     -- 新的最大并发数为4
 5      -- 新的最大等待数为5
);

使用场景

该函数只能在主实例中调用，用于使某条SQL限流规则失效，该规则不再发挥SQL限流作用。

语法

• 使指定SQL限流规则失效：

  SELECT rds_disable_ccl_rule(ccl_id int);

• 使当前库下的所有SQL限流规则失效：

  SELECT rds_disable_all();

参数解释

注意事项

• 失效的规则无法被加载，如果只读实例需要加载某条失效的规则，请先在主实例中使其生效，具体方法，请参见使SQL限流规则生效。

• 使SQL限流规则失效时，会自动将规则从主实例卸载，该规则不再发挥SQL限流作用。

SQL示例

SELECT rds_disable_ccl_rule(1);

使用场景

该函数可以在主实例或只读实例中调用，用于卸载SQL限流规则，被卸载的规则不会再发挥SQL限流作用。

适用于以下场景：

• 主实例：

  • 如果在主实例中调用了rds_disable_ccl_rule或rds_disable_all函数使规则失效，规则将自动从主实例卸载，无需手动调用。

  • 如果在主实例调用了rds_del_ccl_rule函数删除规则，规则将自动从主实例卸载，无需手动调用。

  • 您也可以手动调用此函数，将规则从主实例卸载。

• 只读实例：

  如果不希望某条规则在只读实例发挥限流作用，可以在只读实例中手动调用此函数。

语法

SELECT rds_unload_ccl_rule(ccl_id int, db_name varchar default '');

参数解释

注意事项

规则卸载后，不再发挥SQL限流作用，如需再次使用，需要重新加载，更多信息，请参见加载SQL限流规则。

SQL示例

SELECT rds_unload_ccl_rule(1,'');

使用场景

该函数只能在主实例中调用，用于删除某条SQL限流规则。规则删除时，自动从主实例卸载。

语法

SELECT rds_del_ccl_rule(ccl_id int);

参数解释

注意事项

无。

SQL示例

SELECT rds_del_ccl_rule(1);

返回结果：

   rds_del_ccl_rule   
----------------------
 -7851264404688445170
(1 row)

• query_id是PostgreSQL中SQL的特殊标识，同类SQL的query_id相同。

  例如：

  -- 以下两个sql的query_id相同
  SELECT * FROM tbl WHERE a = 1;
  SELECT * FROM tbl WHERE a = 2;

• query_id包含有SQL中对象的信息（即oid信息），不同数据库下的同名表不是同一个对象，不同schema下的同名表也不是同一个对象。所以相同的SQL，如果其包含的查询对象不同，那么query_id就不相同。

• 如果是SQL中的访问对象的是全局表，或是全局函数，query_id相同。

  • 示例1：pg_database为全局表，在不同数据库中查询query_id相同。

    • ccl_test数据库中执行如下语句：

      SELECT rds_get_query_id($$SELECT * FROM pg_database;$$);

      返回结果：

         rds_get_query_id   
      ----------------------
       -8733244708994363681
      (1 row)

    • ccl_test2数据库中执行如下语句：

      SELECT rds_get_query_id($$SELECT * FROM pg_database;$$);

      返回结果：

         rds_get_query_id   
      ----------------------
       -8733244708994363681
      (1 row)

  • 示例2：pg_sleep为全局函数，在不同数据库中查询query_id相同。

    • ccl_test数据库中执行如下语句：

      SELECT rds_get_query_id($$SELECT pg_sleep(1);$$);

      返回结果：

        rds_get_query_id  
      --------------------
       440101247839410938
      (1 row)

    • ccl_test2数据库中执行如下语句：

      SELECT rds_get_query_id($$SELECT pg_sleep(1);$$);

      返回结果：

        rds_get_query_id  
      --------------------
       440101247839410938
      (1 row)

• 调用函数场景下，当参数类型变化或是有无FROM子句时，query_id会发生变化。

  例如，同样调用pg_sleep函数，不同情况下返回query_id结果不同。

  • 无FROM子句：

    SELECT rds_get_query_id($$SELECT pg_sleep(1);$$);

    返回结果：

      rds_get_query_id  
    --------------------
     440101247839410938
    (1 row)

  • 有FROM子句：

    SELECT rds_get_query_id($$SELECT * FROM pg_sleep(1);$$);

    返回结果：

       rds_get_query_id   
    ----------------------
     -3404018605099167039
    (1 row)

  • 参数类型变化：

    select rds_get_query_id($$SELECT * FROM pg_sleep(1.0);$$);

    返回结果：

      rds_get_query_id   
    ---------------------
     3073869725037049158
    (1 row)