The Confidential Database feature protects sensitive columns—such as email addresses and transaction amounts—from being read in plaintext by privileged internal users like database administrators (DBAs) and developers. It encrypts query results in real time at the database proxy layer, so only authorized applications using a specific encryption driver can decrypt the data. Your physical data on disk is not changed; only the results returned to unauthorized clients are encrypted.
How it works
When an SQL query matches a configured encryption policy, the database proxy intercepts the result and encrypts the specified fields before returning them to the client.
Data storage: The feature does not alter how data is physically stored. Data remains in plaintext in operating system (OS) files and on cloud disks.
User roles and what they see:
| Role | Query results | Can decrypt? |
|---|---|---|
| Super administrator | Always plaintext | N/A—no encryption applied |
| Regular user | Ciphertext | Yes, using a supported encryption driver and the correct key |
| Other users | Ciphertext | No, even with the key |
Limitations and considerations
Query-result encryption only: This feature encrypts results at the proxy layer. Data at rest (OS files, cloud disks) remains in plaintext.
No filtering on encrypted columns from external clients: Standard MySQL clients querying encrypted fields receive ciphertext, which is not human-readable.
Key loss is unrecoverable: If a self-managed key is lost, all data encrypted under that key cannot be decrypted.
Super administrator bypasses all policies: Any account designated as a super administrator always receives plaintext regardless of encryption policies. Limit this role carefully.
Prerequisites
Before you begin, make sure you have:
A PolarDB for MySQL cluster with database proxy version 2.9.12 or later
Configure on-the-fly encryption
Configuring on-the-fly encryption involves three steps: setting up a key, defining role permissions, and creating an encryption policy.
Open the encryption settings
Log on to the PolarDB console. In the left navigation pane, click Clusters. Select the region where your cluster is located, and then click the cluster ID to open the cluster details page.
In the left navigation pane, click Settings and Management > Security, and then click the Encryption tab.
Step 1: Configure a key
On the Encryption page, turn on the Key Management switch.
Use a KMS key (recommended)
Alibaba Cloud Key Management Service (KMS) hosts your keys, supports automatic key rotation, and limits the blast radius of a leaked AccessKey (AK)—you can disable the AK or tighten the access policy without the key itself being compromised.
To configure a KMS CMK:
Return to the PolarDB console, select the CMK you created, and click OK.
Use a self-managed key
If you do not configure KMS, the system uses a self-managed key by default. You are responsible for generating, distributing, and storing the key yourself.
Self-managed keys are at risk of loss or leakage, and key updates are not currently supported. If a key is lost, the corresponding encrypted data cannot be decrypted. Establish strict security procedures before choosing this option.
Step 2: Define role permissions
On the Encryption page, click the Customer Role Permission Settings tab. Role permissions determine whether a database account receives query results in plaintext or ciphertext.
Click Create Role Permission Policy.
In the Role Permission Settings dialog box, configure the following:
Policy Name: A unique name for the policy, up to 64 characters long.
Super administrator: Select the database accounts that always receive plaintext results. These accounts bypass all encryption policies and are intended for management or audit use only. > Note: Add only the accounts that strictly require plaintext access, and strictly limit their use.
Regular user: Select the database accounts that receive ciphertext results. These accounts can decrypt the data using a supported encryption driver and the correct key. > Note: Any database account not listed as a super administrator or regular user is treated as Other users. These accounts receive ciphertext and cannot decrypt it, even with the key.
Click OK.
Step 3: Create an encryption policy
On the Encryption page, click the Encryption Policy Settings tab.
Click Create Encryption Policy.
Configure the policy parameters:
Note Always specify the database, table, and field names when creating a policy. Avoid targeting all databases or all tables to prevent unintended impact on unrelated services.Parameter Required Description Rule Name Yes A unique identifier for the policy, such as encrypt-user-email. Up to 64 characters long.Rule Description No A human-readable description, such as Encrypt the email field in the user table of the customer database. Up to 64 characters long.Enable/Disable Rule — The policy is enabled by default on creation. You cannot change this during creation; modify it after creation if needed. Associated Permission Policy Yes The role permission policy defined in Step 2. Database No The database to which the policy applies. Select All databases (default) or Specify databases. When specifying multiple databases, separate names with a comma ( ,).Table Name No The table to which the policy applies. Select All tables (default) or Specify tables. When specifying multiple tables, separate names with a comma ( ,).Field Name Yes The fields to encrypt. Separate multiple field names with a comma ( ,).Encryption Algorithm Yes The algorithm used for encryption. Supported options: SM4-128-CBC, SM4-128-ECB, SM4-128-GCM, SM4-128-GTR; AES-128-CBC, AES-128-ECB, AES-128-GCM, AES-128-GTR; AES-256-CBC, AES-256-ECB, AES-256-GCM, AES-256-GTR. Click OK.
Manage encryption policies
On the Encryption page, click the Encryption Policy Settings tab to manage existing policies:
Modify a policy: Find the target rule and click Modify in the Actions column.
Delete a policy: Find the target rule, click Delete in the Actions column, and click OK to confirm.
Enable or disable a policy: Find the target rule and click the switch in the Enable/Disable Rule column.
Harden access with RAM
To prevent DBAs or developers with console permissions from modifying or deleting encryption policies, use Resource Access Management (RAM) to explicitly deny those actions.
How it works: Create a RAM deny policy scoped to the two write actions on encryption rules (polardb:ModifyMaskingRules and polardb:DeleteMaskingRules), then attach it to the relevant RAM users. A deny policy takes precedence over any allow policies the user holds.
Step 1: Create a deny policy
Log on to the RAM console. In the left navigation pane, choose Permission Management > Access Policies, and then click Create Policy.
On the visual editor tab, set the following:
Effect: Deny
Service: PolarDB
Action: Select Specify Action. In the Write section, select
polardb:ModifyMaskingRulesandpolardb:DeleteMaskingRules.Resource and Condition: Specify the scope and conditions for the policy. For details, see Basic elements of an access policy.
Click OK, then set the Policy Name and Note in the Create Policy dialog box.
Step 2: Attach the policy to RAM users
In the RAM console, choose Identity Management > Users. Find the target RAM user and click Add Permissions in the Actions column.
In the Access Policies section, select the deny policy you created, and click OK.
Result: When the restricted RAM user attempts to modify or delete an encryption policy, an insufficient-permissions error is returned.
FAQ
I configured an encryption policy, but my database client still shows plaintext. Why?
Check which account you used to connect. If the account is listed as a super administrator, it always receives plaintext results by design. To verify that encryption is working, connect using a regular user account—or any account not in the super administrator list—and query the encrypted field. If the value appears as ciphertext, the proxy layer is encrypting results correctly.
How do I verify that encryption is working?
Connect to the database using a standard MySQL client (such as the command line or Navicat) with an account that is not in the super administrator list. Query the encrypted field. If you see ciphertext, this verifies that the query results are being encrypted in real time at the database proxy layer.
What are the risks of the super administrator role?
The super administrator role reads plaintext data and completely bypasses encryption protection. Reserve it for specific, time-limited tasks such as data correction, migration, or auditing. Remove the account from the role immediately after the task is complete, and maintain a full audit trail of all operations performed under this role.
What's next
After configuring encryption policies, update your application to use an encryption driver that can decrypt the ciphertext results. PolarDB for MySQL supports the EncJDBC driver for Java applications and the GoLang driver for Go applications.