PolarDB:Configure a whitelist rule

How it works

PolarProxy operates in one of three modes per whitelist rule:

When PolarProxy collects SQL statements in Training mode, it saves a parameterized form of each statement — not the literal text. For example:

The ? represents any value. This means one trained statement covers all structurally identical queries, regardless of the specific values used. You do not need to train every possible parameter combination.

Configure multiple whitelist rules to separate concerns. Use a dedicated database account to train each rule, then specify which accounts each rule applies to when you switch to Detection mode or Protection mode.

Prerequisites

Before you begin, ensure that you have:

• A PolarDB for MySQL cluster

• Access to the PolarDB console

• At least one database account to associate with the rule

Create a whitelist rule

1. Log on to the PolarDB console.

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

3. Find the cluster and click the cluster ID.

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

5. In the upper-left corner of the SQL Firewall tab, click Add.

6. In the Create a Rule dialog box, configure the following parameters: Database account name options: Account names must follow one of these formats:

   • username — for example, user

   • username@IP address — for example, user@10.0.0.0

   Basic information

   Parameter	Required	Description
   Rule name	Yes	A name for the rule. Can contain digits and letters. Maximum 30 characters.
   Description	No	A description of the rule. Maximum 64 characters.
   Endpoint	Yes	The endpoint this rule applies to.

   Configurations

   Parameter	Required	Description
   Rule type	Yes	Select Whitelist Rule.
   Current mode	No	The operating mode: Training mode, Detection mode, or Protection mode.
   Database account name	No	Which database accounts the rule applies to. See the options below.

   Option	Behavior
   All accounts	Applies to all database accounts. Leave the field on the right blank.
   Include	Applies only to the accounts you specify. Enter at least one account name, separated by commas (,).
   Exclude	Applies to all accounts except those you specify. Enter at least one account name, separated by commas (,).

7. Click OK.

8. Perform follow-up steps based on the mode you selected:

   • Training mode: Connect to the specified endpoint using the database account defined in the rule. Run the business-related SQL statements you want to whitelist. PolarProxy parameterizes each statement and saves it to the rule.

     To manually add a statement to the whitelist without running it, prefix the statement with the following hint:

     hint(/* store_to_whitelist */)

     Important: Each time you update your business, retrain all new SQL statements. In Protection mode, PolarProxy blocks any statement that was not trained.

     When training is complete, switch the rule to Detection mode or Protection mode to start enforcing the whitelist.

   • Detection mode: Connect to the specified endpoint using the defined database account. Run your business SQL statements normally. PolarProxy records any statement not in the whitelist and allows it through. For a statement not in the whitelist, the result looks like:

      Query OK, 0 rows affected (0.03 sec) Rows matched:1 Changed: 0 Warnings:0 

   • Protection mode: Connect to the specified endpoint using the defined database account. Run your business SQL statements. PolarProxy records and blocks any statement not in the whitelist. For a blocked statement, the error looks like:

      ERROR 1141 (HY000): This SQL is rejected by SQL Firewall. Access denied for user 'xzh'@'x.x.x.x' to database 'xzh': This SQL is not in whitelist wl_test. 

Enable or disable a whitelist rule

1. Log on to the PolarDB console.

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

3. Find the cluster and click the cluster ID.

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

5. On the SQL Firewall tab, find the rule and toggle Enable/Disable.

6. In the confirmation message, click OK.

To enable or disable multiple rules at once, select them in the rule table and click Enable or Disable.

Modify a whitelist rule

1. Log on to the PolarDB console.

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

3. Find the cluster and click the cluster ID.

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

5. On the SQL Firewall tab, find the rule and click Modify in the Actions column.

6. In the Modify a Rule dialog box, update the parameters and click OK.

The rule name cannot be changed after the rule is created.

You cannot modify the parameterized SQL statements in a rule in the PolarDB console. To update a parameterized SQL statement, remove it from the proxy_auditing.sql_list table and retrain it.

Delete a whitelist rule

1. Log on to the PolarDB console.

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

3. Find the cluster and click the cluster ID.

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

5. On the SQL Firewall tab, find the rule and click Delete in the Actions column.

6. In the Delete message, click OK.

To delete multiple rules at once, select them in the rule list and click Delete.