SQL throttling lets you cap the number of concurrent SQL statements running against a database, so a sudden surge in one query type cannot starve other requests or bring the database down.
How it works
When you create a throttling rule, Database Autonomy Service (DAS) monitors all incoming SQL statements and checks each one against the rule's matching criteria — keywords or a SQL template. When the number of matching statements running simultaneously reaches the configured maximum concurrency, additional matching statements either wait in a queue or are rejected immediately, depending on the instance version and configuration.
Request flow:
An SQL statement arrives at the database.
DAS checks whether the statement matches the throttling rule (by keyword, template, template ID, or execution time).
If the statement matches and the concurrency limit is not yet reached, the statement runs normally.
If the concurrency limit is reached:
Maximum concurrency = positive integer: The statement enters a wait queue. If the queue length exceeds
ccl_max_waiting_count, the database returns an error.Maximum concurrency = 0: The statement is rejected immediately and the database returns an error.
Use cases
| Scenario | Example |
|---|---|
| Concurrency spike on a specific query type | Cache penetration or abnormal application calls cause a sudden spike in SQL concurrency |
| Queries that cause data skew | Frequently querying hot data during a sales promotion causes the overall system to become overloaded |
| Full-table scans due to missing indexes | A high volume of SQL calls on tables without indexes causes the overall system to become slow |
Supported databases
| Database engine | Supported versions |
|---|---|
| ApsaraDB RDS for MySQL | 5.6, 5.7, 8.0 |
| ApsaraDB RDS for PostgreSQL | 13 (minor engine version 20250430 or later), 14 (minor version 20230330 or later), 15 (minor version 20230330 or later), later than 15 (no minor version requirement) |
| PolarDB for MySQL | 5.6, 5.7, 8.0 |
| PolarDB-X 2.0 | — |
Throttling modes
Choose the mode that matches how you want to identify the SQL statements to throttle.
| Mode | Description | Applicable databases |
|---|---|---|
| Throttle by keyword | Throttles SQL statements containing all specified keywords. Note: this mode cannot target a single specific statement — it matches any statement that contains all listed keywords. | ApsaraDB RDS for MySQL, PolarDB for MySQL, PolarDB-X 2.0 |
| Throttle by SQL template | Enter a sample SQL statement. DAS converts it into a template and throttles all statements that match the template. | ApsaraDB RDS for MySQL 8.0 (minor engine version 20230630 or later); ApsaraDB RDS for PostgreSQL 13 (minor version 20250430 or later), 14/15 (minor version 20230330 or later), and later than 15; PolarDB for MySQL 8.0.1 (minor version 8.0.1.1.31 or later) and 8.0.2 (minor version 8.0.2.2.12 or later) |
| Throttle by SQL template ID | Enter an SQL template ID directly. Get the ID from SQL logs, sessions, or EXPLAIN results. A template ID is an 8-character hexadecimal string. | PolarDB-X 2.0 Enterprise Edition |
| Throttle by execution time | Set a running time threshold. DAS automatically adds the template IDs of statements that exceed the threshold to the throttling rule and applies the configured concurrency limit. | PolarDB-X 2.0 Enterprise Edition |
Create a throttling rule
SQL throttling is an emergency measure. Set a short throttling duration and disable the rule as soon as the situation is resolved.
Log on to the DAS console.
In the left navigation pane, click Intelligent O&M Center > Instance Monitoring.
Find the target instance, and click the instance ID to go to the instance details page.
In the left navigation pane, click Instance Sessions.
On the Session Management page, click SQL Throttling.
In the dialog box that appears, click Create Throttling Rule.
In the Create Throttling Rule dialog box, configure the parameters for your database engine.
ApsaraDB RDS for MySQL
| Parameter | Description |
|---|---|
| Throttling mode | Select a throttling mode. |
| SQL type | Select the SQL statement type to throttle: SELECT, UPDATE, DELETE, or INSERT. Required when Throttling mode is set to Throttle by keyword. Note INSERT statements can only be throttled on ApsaraDB RDS for MySQL 8.0, PolarDB for MySQL 5.7 and 8.0, and PolarDB-X 2.0. |
| Database | The database in which to apply the throttling rule. Required when Throttling mode is set to Throttle by SQL template. |
| Maximum concurrency | The maximum number of SQL statements that can run concurrently. Minimum value: 0. Throttling is triggered when concurrent matching statements reach this number. |
| Throttling duration | How long the throttling rule stays active. Disable the rule manually if the situation resolves before the duration expires. |
| SQL keyword | Required when Throttling mode is set to Throttle by keyword. Enter the keywords that identify the statements to throttle. Separate multiple keywords with a tilde (~). A statement is throttled only if it contains all the specified keywords — order does not matter. Note Keywords are case-sensitive on most versions. You cannot use only |
| SQL sample | Required when Throttling mode is set to Throttle by SQL template. Enter a representative SQL statement. DAS converts it to a template by replacing literal values with placeholders. For example, select name from das where name = \das\ and age = 21 limit 20 becomes the template select name from das where name = ? and age = ? limit ?. The throttling effect is not affected by how DAS normalizes the sample. |
ApsaraDB RDS for PostgreSQL
ApsaraDB RDS for PostgreSQL supports only Throttle by SQL template mode.
| Parameter | Description |
|---|---|
| Database | The database in which to apply the throttling rule. |
| Search path | The schema search path for the throttling rule. Separate multiple paths with commas (,). Default: information_schema,public. |
| Maximum concurrency | The maximum number of SQL statements that can run concurrently. Minimum value: 0. Throttling is triggered when concurrent matching statements reach this number. |
| Maximum waiting queries | The maximum number of statements allowed to wait in the queue. |
| Throttling duration | How long the throttling rule stays active. Disable the rule manually if the situation resolves before the duration expires. |
| SQL sample | Enter a representative SQL statement. DAS converts it to a template by replacing literal values with placeholders. For example, select name from das where name = "das" and age = 21 limit 20 becomes select name from das where name = ? and age = ? limit ?. |
PolarDB for MySQL
| Parameter | Description |
|---|---|
| Throttling mode | Select a throttling mode. |
| SQL type | Select the SQL statement type to throttle: SELECT, UPDATE, DELETE, or INSERT. Note INSERT statements can only be throttled on ApsaraDB RDS for MySQL 8.0, PolarDB for MySQL 5.7 and 8.0, and PolarDB-X 2.0. |
| Maximum concurrency | The maximum number of SQL statements that can run concurrently. Minimum value: 0. |
| Database | The database in which to apply the throttling rule. Required when Throttling mode is set to Throttle by SQL template. |
| Throttling duration | How long the throttling rule stays active. |
| SQL keyword | Required when Throttling mode is set to Throttle by keyword. Same rules apply as for ApsaraDB RDS for MySQL. Separate multiple keywords with ~. A statement must contain all specified keywords to be throttled. |
| SQL sample | Required when Throttling mode is set to Throttle by SQL template. DAS converts the sample to a template by replacing literal values with placeholders. |
PolarDB-X 2.0
| Parameter | Description |
|---|---|
| Throttling mode | Select a throttling mode. |
| SQL type | Select the SQL statement type to throttle: SELECT, UPDATE, DELETE, or INSERT. Note INSERT statements can only be throttled on ApsaraDB RDS for MySQL 8.0, PolarDB for MySQL 5.7 and 8.0, and PolarDB-X 2.0. |
| Maximum concurrency | The maximum number of SQL statements that can run concurrently. Minimum value: 0. |
| Throttling duration | How long the throttling rule stays active. |
| SQL keyword | Required when Throttling mode is set to Throttle by keyword. Separate multiple keywords with ~. A statement must contain all specified keywords to be throttled. |
| SQL template ID | Required for PolarDB-X 2.0 Enterprise Edition when Throttling mode is set to Throttle by SQL template. Enter one or more 8-character hexadecimal template IDs, separated by commas (,). Get template IDs from SQL logs, sessions, or EXPLAIN results. |
| Minimum SQL execution duration | Required for PolarDB-X 2.0 Enterprise Edition when Throttling mode is set to Throttle by execution time. The running time threshold. When a statement exceeds this threshold, DAS automatically adds its template ID to the throttling rule. |
| Maximum throttled SQL IDs | Required for PolarDB-X 2.0 Enterprise Edition when Throttling mode is set to Throttle by execution time. The maximum number of SQL template IDs that can be throttled. After this limit is reached, DAS stops adding new template IDs even if more statements exceed the threshold. |
| Database account with throttled queries | Required when Throttling mode is set to Throttle by keyword or Throttle by SQL template. The database account whose SQL statements are subject to throttling. |
Click Submit to create the rule.
Throttling behavior and error codes
When a throttling rule is triggered, the database returns an error to the application. The exact error code depends on the instance version and the configured maximum concurrency.
| Maximum concurrency | Instance | Error code | Error message |
|---|---|---|---|
| 0 or positive integer | ApsaraDB RDS for MySQL 5.6 | 1317 | query execution was interrupted |
| 0 or positive integer | ApsaraDB RDS for MySQL 5.7 (minor version earlier than 20200630) | 1317 | query execution was interrupted |
| 0 or positive integer | PolarDB for MySQL 5.6 | 1317 | query execution was interrupted |
| Positive integer | ApsaraDB RDS for MySQL 5.7 (minor version 20200630 or later) | 5041 | Concurrency control waiting count exceed max waiting count |
| Positive integer | ApsaraDB RDS for MySQL 8.0 | 7534 | Concurrency control waiting count exceed max waiting count |
| Positive integer | PolarDB for MySQL 5.7 | 3277 | Concurrency control waiting count exceed max waiting count |
| Positive integer | PolarDB for MySQL 8.0 | 7533 | Concurrency control waiting count exceed max waiting count |
| 0 | ApsaraDB RDS for MySQL 5.7 (minor version 20200630 or later) | 5042 | Concurrency control refuse to execute query |
| 0 | ApsaraDB RDS for MySQL 8.0 | 7535 | Concurrency control refuse to execute query |
| 0 | PolarDB for MySQL 5.7 | 3278 | Concurrency control refuse to execute query |
| 0 | PolarDB for MySQL 8.0 | 7534 | Concurrency control refuse to execute query |
Additional parameters for supported instances:
`ccl_max_waiting_count` (ApsaraDB RDS for MySQL 5.7 minor version 20200630 or later, ApsaraDB RDS for MySQL 8.0): Sets the maximum queue length. If set to 0, DAS uses the default value of 10.
`ccl_wait_timeout` (ApsaraDB RDS for MySQL 5.7 minor version 20200630 or later, ApsaraDB RDS for MySQL 8.0): Sets a timeout for waiting statements, if it is supported by the instance version. Statements that exceed this timeout continue to run and are no longer subject to throttling.
`ccl_mode` (PolarDB for MySQL 8.0): Controls the behavior when the concurrency limit is exceeded. This parameter is available only on supported instance versions.
WAIT(default): Statements wait in a queue.REFUSE: Statements are rejected immediately without waiting.
View and manage throttling rules
After you create a rule, it appears on the Running tab with the following details.
The columns displayed vary depending on the database engine and throttling mode.
| Column | Description |
|---|---|
| Throttling mode | The mode selected when creating the rule. |
| Throttling rule | The rule configuration: keywords (keyword mode), template ID (template mode), or running time threshold and throttled statement count (execution time mode). |
| Maximum concurrency | The configured concurrency limit. |
| Maximum waiting queries | The maximum queue length. Displayed for ApsaraDB RDS for PostgreSQL with SQL template mode. |
| Throttling duration (min) | The configured active duration. |
| Start time | The time the rule took effect. |
| Remaining time (s) | The time remaining before the rule expires. |
| Sample SQL | The SQL sample used to generate the template. Displayed for SQL template mode. |
| Throttling template ID | The template ID corresponding to the throttled SQL sample. Displayed for SQL template mode. |
| Status | A running rule shows Enabled. |
| Database | The database where the rule applies. Displayed for SQL template mode. |
| Search path | The schema search path. Displayed for ApsaraDB RDS for PostgreSQL with SQL template mode. |
| Matched SQL query | The number of SQL statements matched by the rule. Displayed for SQL template mode. |
| Waiting SQL query | The number of SQL statements currently waiting in the queue. Displayed for SQL template mode. |
| Actions | Disable or Modify the rule. |
What's next
Automatic SQL throttling — let DAS detect and apply throttling rules automatically.
API reference
| API | Description |
|---|---|
| EnableSqlConcurrencyControl | Enables SQL throttling. |
| DisableSqlConcurrencyControl | Disables a specified throttling rule. |
| DisableAllSqlConcurrencyControlRules | Disables all running throttling rules. |
| GetRunningSqlConcurrencyControlRules | Gets the running throttling rules. |
| GetSqlConcurrencyControlRulesHistory | Gets throttling rules that are running or have been triggered. |
| GetSqlConcurrencyControlKeywordsFromSqlText | Generates throttling keywords from an SQL statement. |