All Products
Search

This Product

    PolarDB:Configure a blacklist rule

    Document Center

    PolarDB:Configure a blacklist rule

    Last Updated:Aug 27, 2026

    You can create, enable, disable, modify, and delete blacklist rules in the PolarDB console. This topic describes blacklist rules and how to configure them.

    Blacklist rules

    The proxy provides a blocking feature. You can configure blacklist rules to block specific types of SQL statements or individual SQL statements.

    You can configure blacklist rules in the following three modes:

    • fixed rule mode: A common mode for configuring blacklist rules in the console. Each rule can be applied to a specific account and cluster. For a list of supported common rules, see Configure SQL Firewall rules.

    • custom parameterized SQL mode: This mode parameterizes all variables in your SQL statements and saves the generated template to the database. The proxy then blocks any SQL statement that matches this template.

    • custom SQL mode: This mode blocks a specific SQL statement verbatim, without parameterizing any variables. SQL statements that have different parameters are not affected.

    Create a blacklist rule

    1. Log on to the PolarDB console.

    2. In the upper-left corner, select the region where the cluster is deployed.

    3. Find the target cluster and click its ID.

    4. In the left-side navigation pane, choose Settings and Management > Security.

    5. On the SQL Firewall tab, click Add on the left.

    6. In the Create a Rule dialog box, configure the parameters based on your desired blacklist mode.

      • fixed rule mode

        1. If you select fixed rule mode, configure the following parameters.

          Table 1. Parameters for SQL Firewall rules

          Parameter

          Required

          Description

          Basic Information

          Rule Name

          Yes

          The name of the SQL Firewall rule. The name must meet the following requirements:

          • Consist of letters and digits.

          • Be up to 30 characters long.

          Description

          No

          A description for easy identification and management.

          Note

          The description can be up to 64 characters in length.

          Endpoint

          Yes

          The endpoint to which the rule applies.

          Configurations

          Rule Type

          Yes

          Select Blacklist Rule.

          Current Mode

          No

          The mode for the SQL Firewall rule. This is always set to Protection Mode, meaning SQL statements that match a blacklist rule are blocked.

          Database Account Name

          No

          The database accounts to which this rule applies. The following options are available:

          • All Accounts: Applies the rule to all database accounts in the cluster. You do not need to enter anything in the text box.

          • Include: Applies the rule only to the specified database accounts. Enter one or more comma-separated account names.

          • Exclude: Applies the rule to all database accounts in the cluster except for the ones you specify. Enter one or more comma-separated account names.

          Note

          The database account name that you enter must be in one of the following formats:

          • AccountName. Example: user.

          • AccountName@IPAddress. Example: user@10.0.0.0.

          Block SQLs With Asterisks (*)

          No

          Blocks SQL statements that contain an asterisk (*). Valid values:

          • Enable: Blocks SQL statements that contain an asterisk (*).

          • Close: Does not block SQL statements that contain an asterisk (*).

          Block SQLs of Specific Types

          No

          Blocks specific types of SQL statements. Valid values:

          • Enable: Blocks specific types of SQL statements. If you enable Block SQLs of Specific Types, you must select at least one type. Supported types:

            • CREATE

            • DROP

            • ALTER

            • TRUNCATE

            • RENAME

            • INSERT

            • UPDATE

            • SELECT

            • DELETE

          • Close: Does not block specific types of SQL statements.

          Block SQLs Without WHERE

          No

          Blocks SQL statements that do not have a WHERE clause. Valid values:

          • Enable: Blocks specified types of SQL statements that do not have a WHERE clause. If you enable Block SQLs Without WHERE, you must select at least one type. Supported types:

            • UPDATE

            • SELECT

            • DELETE

          • Close: Does not block SQL statements that do not have a WHERE clause.

          Note

          This parameter applies only to SELECT, UPDATE, and DELETE statements that contain at least one table name. The proxy does not block statements such as SELECT 1;.

          Block SQLs With Specific Columns

          No

          Blocks SQL statements that contain specific column names. Valid values:

          • Enable: Blocks SQL statements that contain specific column names. If you enable Block SQLs With Specific Columns, the following options are available:

            • All: Applies the rule to all column names in the cluster. You do not need to enter anything in the text box.

            • Include: Applies the rule only to the specified column names. You must enter one or more column names, separated by commas (,).

            • Exclude: Applies the rule to all column names in the cluster except for the ones you specify. You must enter one or more column names, separated by commas (,).

          • Close: Does not block SQL statements that contain specific column names.

          Block SQLs With Specific Functions

          No

          Blocks SQL statements that use specific functions. Valid values:

          • Enable: Blocks SQL statements that use specific functions. If you enable Block SQLs With Specific Functions, the following options are available:

            • All: Applies the rule to all functions executed in the cluster's databases. You do not need to enter anything in the text box.

            • Include: Applies the rule only to the specified functions. You must enter one or more function names, separated by commas (,).

            • Exclude: Applies the rule to all functions except for the ones you specify. You must enter one or more function names, separated by commas (,).

          • Close: Does not block SQL statements that use specific functions.

          Block SQLs With Specific Columns and Specific Functions

          No

          Blocks SQL statements that contain specific functions and reference specific column names. Valid values:

          • Enable: Blocks SQL statements that contain specific functions and reference specific column names. If you enable Block SQLs With Specific Columns and Specific Functions, you must enter one or more Function Name and Column Name values. Specifically:

            • If Function Name is set to Include and Column Name is also set to Include, the rule applies to SQL statements in the cluster that use a specific function and reference a specific column name.

            • If Function Name is set to Include and Column Name is set to Exclude, the rule applies to statements that use a specified function on any column except the ones specified.

            • If Function Name is set to Exclude and Column Name is set to Include, the rule applies to statements that use any function except the ones specified on a specified column.

            • If you select Exclude for Function Name and also select Exclude for Column Name, this means the rule applies to SQL statements in the cluster that use functions other than the specified ones and reference columns other than the specified ones.

          • Close: Does not block SQL statements that contain specific functions and reference specific column names.

        2. After you configure the rule, click OK.

      • custom parameterized SQL mode

        1. If you select custom parameterized SQL mode, configure the required parameters. For more information, see Parameters for SQL Firewall rules.

          Note

          When you use the custom parameterized SQL mode, you do not need to enable any blocking rules under Configurations.

        2. After you configure the rule, click OK.

        3. Use the Database Account Name from the previous step to connect to the specified database endpoint. To block an SQL statement, add the hint command /* store_to_blacklist */ before the statement. For example, to block the SQL statement select id from sqlblack_test where id = 1;, run the following command:

          /* store_to_blacklist */ select id from sqlblack_test where id = 1;

          The parameterized template is as follows:

          select id from sqlblack_test where id = ?

          In this template, ? represents any value.

          After about 5 seconds, the proxy blocks any SQL statement from this account that matches the template. The following error is returned:

          ERROR 1141 (HY000): This SQL is rejected by SQL Firewall. Access denied for user 'xxx'@'x.x.x.x' to database 'xzh': This SQL is on blacklist bl_test.

          In this message, bl_test is the name of the blacklist rule.

        Note

        • If you use the MySQL command-line client, you must add the -c option. Otherwise, the hint command will not take effect.

        • The rule takes effect after about 5 seconds.

      • custom SQL mode

        1. If you select custom SQL mode, configure the required parameters. For more information, see Parameters for SQL Firewall rules.

          Note

          When you use the custom SQL mode, you do not need to enable any blocking rules under Configurations.

        2. After you configure the rule, click OK.

        3. Use the Database Account Name from the previous step to connect to the specified database endpoint. To block an SQL statement, add the hint command /* orginal_store_to_blacklist */ before the statement. For example, to block the statement update t set k = 2 where id = 2;, run the following command:

          /* orginal_store_to_blacklist */ update t set k = 2 where id = 2;

          After about 5 seconds, when you use this account to execute the exact SQL statement update t set k = 2 where id = 2;, the proxy blocks the statement. Other SQL statements are not affected. The following error is returned:

          ERROR 1141 (HY000): This SQL is rejected by SQL Firewall. Access denied for user 'xxx'@'x.x.x.x' to database 'xzh': This SQL is on blacklist bl_test.

          In this message, bl_test is the name of the blacklist rule.

        Note

        • If you use the MySQL command-line client, you must add the -c option. Otherwise, the hint command will not take effect.

        • The rule takes effect after about 5 seconds.

    Enable or disable a blacklist rule

    1. Log on to the PolarDB console.

    2. In the upper-left corner, select the region where the cluster is deployed.

    3. Find the target cluster and click its ID.

    4. In the left-side navigation pane, choose Settings and Management > Security.

    5. On the SQL Firewall tab, find the rule that you want to enable or disable and click the Enable/Disable switch.

      Note

      You can also select multiple rules in the list and click Enable or Disable at the bottom of the list to enable or disable them in bulk.

    6. In the Enable or Disable dialog box that appears, click OK.

    Modify a blacklist rule

    1. Log on to the PolarDB console.

    2. In the upper-left corner, select the region where the cluster is deployed.

    3. Find the target cluster and click its ID.

    4. In the left-side navigation pane, choose Settings and Management > Security.

    5. On the SQL Firewall tab, find the rule that you want to modify, and click Modify in the Operation column. In the Modify A Rule dialog box, modify the parameters. For details about the parameters, see Parameters for SQL Firewall rules.

      Note

      You cannot modify a rule's Rule Name.

    6. After you modify the rule, click OK.

    Note

    From the console, you cannot modify parameterized SQL statements in rules created using custom parameterized SQL mode, nor can you modify specific SQL statements in rules created using custom SQL mode. To change these statements, you must delete them from the database table and add them again.

    Delete a blacklist rule

    1. Log on to the PolarDB console.

    2. In the upper-left corner, select the region where the cluster is deployed.

    3. Find the target cluster and click its ID.

    4. In the left-side navigation pane, choose Settings and Management > Security.

    5. On the SQL Firewall tab, find the rule that you want to delete and click Delete in the Operation column.

      Note

      You can also select multiple rules in the list and click Delete at the bottom of the list to delete them in bulk.

    6. In the Delete dialog box that appears, click OK.

    Remove rules for custom modes

    • custom parameterized SQL mode blacklist rule

      You can remove a custom parameterized SQL mode blacklist rule in one of the following ways:

      • You can remove a blacklist rule for the custom parameterized SQL mode by enabling or disabling a blacklist rule or deleting a blacklist rule.

        Note

        If you only disable the blacklist rule in the console without deleting the corresponding parameterized SQL statement from the proxy_auditing.sql_list table, the rule takes effect again if you re-enable it for the same account.

      • Connect to the primary node of the endpoint by using a super administrator account, and delete the corresponding SQL statement from the proxy_auditing.sql_list table. After about 5 seconds, the proxy will no longer block the statement.

        Note

        Do not use the DROP command to delete the table.

    • custom SQL mode blacklist rule

      You can remove a custom SQL mode blacklist rule in one of the following ways:

      • To manage a custom SQL mode blacklist rule, you can enable or disable a blacklist rule or delete a blacklist rule.

        Note

        If you only disable the blacklist rule in the console without deleting the corresponding SQL statement from the proxy_auditing.org_sql_list table, the rule takes effect again if you re-enable it for the same account.

      • Connect to the primary node of the endpoint by using a super administrator account, and delete the corresponding SQL statement from the proxy_auditing.org_sql_list table. After about 5 seconds, the proxy will no longer block the statement.

        Note

        Do not use the DROP command to delete the table.