All Products
Search

This Product

    Database Autonomy Service:SQL throttling

    Document Center

    Database Autonomy Service:SQL throttling

    Last Updated:Apr 01, 2026

    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:

    1. An SQL statement arrives at the database.

    2. DAS checks whether the statement matches the throttling rule (by keyword, template, template ID, or execution time).

    3. If the statement matches and the concurrency limit is not yet reached, the statement runs normally.

    4. 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

    Important

    SQL throttling is an emergency measure. Set a short throttling duration and disable the rule as soon as the situation is resolved.

    1. Log on to the DAS console.

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

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

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

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

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

    7. 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. INSERT...SELECT... statements cannot be throttled.
    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 SELECT, INSERT, UPDATE, or DELETE as keywords. Example: For the statement 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 keywords are: SELECT~min~id~max~id~FROM~task_event~WHERE~gmt_modified~AND~begin_time~AND~source~IN~AND~id~AND~id.
    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. INSERT...SELECT... statements cannot be throttled.
    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. INSERT...SELECT... statements cannot be throttled.
    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.

    1. 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
    ApsaraDB RDS for MySQL 5.7 (minor version earlier than 20200630) 1317
    PolarDB for MySQL 5.6 1317
    Positive integer ApsaraDB RDS for MySQL 5.7 (minor version 20200630 or later) 5041 Concurrency control waiting count exceed max waiting count
    ApsaraDB RDS for MySQL 8.0 7534
    PolarDB for MySQL 5.7 3277
    PolarDB for MySQL 8.0 7533
    0 ApsaraDB RDS for MySQL 5.7 (minor version 20200630 or later) 5042 Concurrency control refuse to execute query
    ApsaraDB RDS for MySQL 8.0 7535
    PolarDB for MySQL 5.7 3278
    PolarDB for MySQL 8.0 7534

    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

    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.