SQL throttling

Throttling error messages

After you create an SQL throttling rule, the database system returns a specific error message if an application runs an SQL statement that matches the rule's keywords or template.

Scenarios

Throttling modes

Procedure

This topic uses ApsaraDB RDS for MySQL as an example to describe how to use the throttling feature. For related operations for other database types, see Related documentation.

1. Log on to the DAS console.

2. In the navigation pane on the left, click Intelligent O&M Center > Instance Monitoring .

3. Find the target instance and click the instance ID to open the instance details page.

4. In the left-side navigation pane, click Instance Sessions.

5. On the Session Management page, click SQL Throttling.

6. In the dialog box, click Create Throttling Rule.

7. In the Create Throttling Rule dialog box, configure the following parameters based on the database engine.

RDS for MySQL

Parameter	Description
Throttling Mode	Select a throttling mode as needed.
SQL Type	The type of the SQL statement. Valid values: SELECT, UPDATE, DELETE, and INSERT. Note This parameter is required if you set Throttling Mode to Throttle by Keyword. You can throttle INSERT statements only on the following database engines: ApsaraDB RDS for MySQL 8.0 PolarDB for MySQL 5.7 and 8.0 PolarDB-X 2.0 You cannot throttle INSERT...SELECT... statements.
Database	The database where SQL statements will be throttled. Note This parameter is required if you set Throttling Mode to Throttle by SQL Template.
Maximum Concurrency	The maximum number of concurrent SQL statements. The minimum value is 0. Note Throttling begins when the number of concurrent SQL statements matching the rule reaches this value.
Throttling Duration	The duration for which the SQL throttling rule is effective. Important SQL throttling is an emergency measure. We recommend setting the duration based on your business needs and disabling the rule when it is no longer required.
SQL Keywords	Keywords in the SQL statements to be throttled. Note This parameter is required if you set Throttling Mode to Throttle by Keyword. If you specify multiple keywords, the throttling rule is triggered only if an SQL statement contains all of the specified keywords. Separate multiple keywords with tildes (~). The order of the keywords does not matter. For example, if the original statement is SELECT min(id), max(id) FROM task_event WHERE gmt_modified < '2020-06-21' AND begin_time > '2020-07-09' AND source IN (527) AND id >= 15673 AND id <= 8015673 , the corresponding throttling keywords are SELECT~min~id~max~id~FROM~task_event~WHERE~gmt_modified~AND~begin_time~AND~source~IN~AND~id~AND~id. You cannot specify only SELECT, INSERT, UPDATE, DELETE as throttling keywords. Keywords are case-sensitive. However, some earlier instance versions are not case-sensitive.
SQL Sample	An example SQL statement to throttle. Note This parameter is required if you set Throttling Mode to Throttle by SQL Template. For complex SQL statements, DAS transforms the SQL Sample for internal processing, but the final SQL template remains unchanged. The throttling effect is not affected by this transformation. For example, if you enter select name from das where name = `das` and age = 21 limit 20, it is templated to select name from das where name = ? and age = ? limit ? and then rewritten to select name from das where name = `param0` and age = `param1` limit 20.

RDS for PostgreSQL

Parameter	Description
Throttling Mode	ApsaraDB RDS for PostgreSQL supports only Throttle by SQL Template.
Database	The database where SQL statements will be throttled.
Search Path	The search path for SQL throttling. Note Separate multiple paths with commas (,). The default value is information_schema,public.
Maximum Concurrency	The maximum number of concurrent SQL statements. The minimum value is 0. Note Throttling begins when the number of concurrent SQL statements matching the rule reaches this value.
Maximum Waiting Queries	The maximum number of waiting queries.
Throttling Duration	The duration for which the SQL throttling rule is effective. Important SQL throttling is an emergency measure. We recommend setting the duration based on your business needs and disabling the rule when it is no longer required.
SQL Sample	An example SQL statement to throttle. Note This parameter is required if you set Throttling Mode to Throttle by SQL Template. For complex SQL statements, DAS transforms the SQL Sample for internal processing, but the final SQL template remains unchanged. The throttling effect is not affected by this transformation. For example, if you enter select name from das where name = "das" and age = 21 limit 20, it is templated to select name from das where name = ? and age = ? limit ? and then rewritten to select name from das where name = "param0" and age = "param1" limit 20.

PolarDB for MySQL

Parameter	Description
Throttling Mode	Select a throttling mode as needed.
SQL Type	The type of the SQL statement. Valid values: SELECT, UPDATE, DELETE, and INSERT. Note You can throttle INSERT statements only on the following database engines: ApsaraDB RDS for MySQL 8.0 PolarDB for MySQL 5.7 and 8.0 PolarDB-X 2.0 You cannot throttle INSERT...SELECT... statements.
Maximum Concurrency	The maximum number of concurrent SQL statements. The minimum value is 0. Note Throttling begins when the number of concurrent SQL statements matching the rule reaches this value.
Database	The database where SQL statements will be throttled. Note This parameter is required if you set Throttling Mode to Throttle by SQL Template.
Throttling Duration	The duration for which the SQL throttling rule is effective. Important SQL throttling is an emergency measure. We recommend setting the duration based on your business needs and disabling the rule when it is no longer required.
SQL Keywords	Keywords in the SQL statements to be throttled. Note This parameter is required if you set Throttling Mode to Throttle by Keyword. If you specify multiple keywords, the throttling rule is triggered only if an SQL statement contains all of the specified keywords. Separate multiple keywords with tildes (~). The order of the keywords does not matter. For example, if the original statement is SELECT min(id), max(id) FROM task_event WHERE gmt_modified < '2020-06-21' AND begin_time > '2020-07-09' AND source IN (527) AND id >= 15673 AND id <= 8015673 , the corresponding throttling keywords are SELECT~min~id~max~id~FROM~task_event~WHERE~gmt_modified~AND~begin_time~AND~source~IN~AND~id~AND~id. You cannot specify only SELECT, INSERT, UPDATE, or DELETE as throttling keywords. Keywords are case-sensitive. However, some earlier instance versions are not case-sensitive.
SQL Sample	An example SQL statement to throttle. Note This parameter is required if you set Throttling Mode to Throttle by SQL Template. For complex SQL statements, DAS transforms the SQL Sample for internal processing, but the final SQL template remains unchanged. The throttling effect is not affected by this transformation. For example, if you enter select name from das where name = "das" and age = 21 limit 20, it is templated to select name from das where name = ? and age = ? limit ? and then rewritten to select name from das where name = "param0" and age = "param1" limit 20.

PolarDB-X 2.0

Parameter	Description
Throttling Mode	Select a throttling mode as needed.
SQL Type	The type of the SQL statement. Valid values: SELECT, UPDATE, DELETE, and INSERT. Note You can throttle INSERT statements only on the following database engines: ApsaraDB RDS for MySQL 8.0 PolarDB for MySQL 5.7 and 8.0 PolarDB-X 2.0 You cannot throttle INSERT...SELECT... statements.
Maximum Concurrency	The maximum number of concurrent SQL statements. The minimum value is 0. Note Throttling begins when the number of concurrent SQL statements matching the rule reaches this value.
Throttling Duration	The duration for which the SQL throttling rule is effective. Important SQL throttling is an emergency measure. We recommend setting the duration based on your business needs and disabling the rule when it is no longer required.
SQL Keywords	Keywords in the SQL statements to be throttled. Note This parameter is required if you set Throttling Mode to Throttle by Keyword. If you specify multiple keywords, the throttling rule is triggered only if an SQL statement contains all of the specified keywords. Separate multiple keywords with tildes (~). The order of the keywords does not matter. For example, if the original statement is SELECT min(id), max(id) FROM task_event WHERE gmt_modified < '2020-06-21' AND begin_time > '2020-07-09' AND source IN (527) AND id >= 15673 AND id <= 8015673 , the corresponding throttling keywords are SELECT~min~id~max~id~FROM~task_event~WHERE~gmt_modified~AND~begin_time~AND~source~IN~AND~id~AND~id. You cannot specify only SELECT, INSERT, UPDATE, or DELETE as throttling keywords. Keywords are case-sensitive. However, some earlier instance versions are not case-sensitive.
SQL Template ID	The ID of the SQL template to throttle. An ID is an 8-character hexadecimal string. Separate multiple SQL template IDs with commas (,). Note This parameter is required for PolarDB-X Throttling Mode instances when Throttling Mode is set to Throttle by SQL Template.
Minimum SQL Execution Duration	The threshold for the SQL execution time. If the execution time of an SQL statement exceeds the specified threshold, the system adds the SQL statement's template ID to the throttling rule. Note This parameter is required for PolarDB-X Throttling Mode instances when Throttling Mode is set to Throttle by Execution Duration.
Maximum Number of Throttled Queries	The maximum number of SQL template IDs that can be throttled based on execution time. After this limit is reached, the system no longer creates throttling rules for other SQL statements whose execution time exceeds the specified threshold. Note This parameter is required for PolarDB-X Throttling Mode instances when Throttling Mode is set to Throttle by Execution Duration.
Database Account with Throttled Queries	The database account associated with the throttled SQL statement. Note This parameter is required if you set Throttling Mode to Throttle by Keyword or Throttle by SQL Template.

MongoDB

Parameter	Description
Operation type	Select the operation types to throttle. You can select multiple types. Valid values: find, insert, update, and delete.
Operation concurrency	Specify the maximum number of concurrent operations allowed for the selected operation types. Requests that exceed this threshold are throttled.
Throttling duration	Set the active duration for the throttling rule. After the rule expires, the system automatically disables it and moves it to the Ended tab.
Kill Statement	(Optional) If you enable this option, when the throttling rule takes effect, the system automatically terminates (kills) any active operations that match the rule, such as long-running find or update operations. The system performs this action only once to immediately release occupied connections and computing resources. New requests that arrive after the rule is active are throttled and are not terminated. This feature is ideal for emergency situations where a sudden workload surge has caused a large number of long-running transactions to accumulate, requiring an immediate release of resources.
Throttling scope	This option is available only for ApsaraDB for MongoDB sharded cluster instances. You can apply the rule to All Shards or Partial Shards.
Throttled collections	Specify the collections that the rule applies to. Use the databaseName.collectionName format.

8. Click Submit.

   After the SQL throttling rule is created, you can view its details on the Running tab. The following table describes the parameters.

   Note

   The parameters in the list vary slightly depending on the database engine and throttling mode.

   Parameter	Description
   Throttling Mode	The mode that you selected.
   Throttling Rule	Throttle by Keyword: The configured throttling keywords. Throttle by SQL Template: The template ID corresponding to the SQL Sample. Throttle by Execution Duration: The configured execution time threshold and the number of throttled SQL templates.
   Maximum Concurrency	The maximum number of concurrent SQL statements.
   Maximum Waiting Queries	The maximum number of waiting queries configured in the throttling rule. Note This parameter is displayed for ApsaraDB RDS for PostgreSQL instances when Throttling Mode is set to Throttle by SQL Template.
   Throttling Duration (min)	The duration for which the SQL throttling rule is effective.
   Start Time	The time when the throttling rule was configured and took effect.
   Remaining time	The remaining time before the throttling rule expires.
   SQL Sample	An example SQL statement to throttle. Note This parameter is displayed if you set Throttling Mode to Throttle by SQL Template.
   Throttling Template ID	The template ID corresponding to the SQL Sample. Note This parameter is displayed if you set Throttling Mode to Throttle by SQL Template.
   Status	Indicates that the rule is active.
   Database	The database where SQL statements will be throttled. Note This parameter is displayed if you set Throttling Mode to Throttle by SQL Template.
   Search Path	The search path that corresponds to the throttled SQL statement. Note This parameter is displayed for ApsaraDB RDS for PostgreSQL instances when Throttling Mode is set to Throttle by SQL Template.
   Matched SQL Query	The number of SQL queries that match the throttling rule. Note This parameter is displayed if you set Throttling Mode to Throttle by SQL Template.
   Waiting SQL Query	The number of SQL queries that are waiting due to the throttling rule. Note This parameter is displayed if you set Throttling Mode to Throttle by SQL Template.
   Actions	Allows you to Disable or Modify the rule.

Related topics

• Automatic SQL throttling

• Concurrency control for PolarDB for MySQL

• Concurrency control for ApsaraDB RDS for MySQL.

• SQL throttling for MongoDB

Related APIs