The always-confidential database feature for PolarDB-X encrypts sensitive data columns so that stored data is always ciphertext. Authorized users decrypt it transparently through a local key, without changing application logic. Configure and manage the feature in Data Security Center (DSC)—not in the PolarDB-X console—for centralized data security administration across your cloud assets.
Prerequisites
Before you begin, make sure you have:
-
A PolarDB-X instance running version
polardb-2.5.0_5.4.20-20250714_xcluster8.4.20-20250703or later. For version naming rules, see Release notes. To check your version, see View and update the version of an instance. -
An instance deployed in a supported region:
Region type Supported regions The Chinese mainland China (Qingdao), China (Beijing), China (Zhangjiakou), China (Hohhot), China (Hangzhou), China (Shanghai), China (Shenzhen), China (Guangzhou), China (Chengdu) Outside the Chinese mainland China (Hong Kong), Singapore (Singapore), Malaysia (Kuala Lumpur), Indonesia (Jakarta), Germany (Frankfurt) -
A database account with Plaintext Permissions to use as the DSC connection credential. This account must be able to read plaintext data so that DSC can detect and classify sensitive data after connection.
Billing
The always-confidential database feature itself is free. However, it relies on DSC for encryption configuration and management. Purchase DSC and make sure the column encryption quota meets your requirements. For DSC pricing, see Billing overview.
How encryption works
The always-confidential database feature corresponds to Column Encryption in DSC. PolarDB-X supports two encryption algorithms with local keys:
-
AES-128-GCM -
SM4-128-GCM
After column encryption is configured, data is stored as ciphertext. Access to that data depends on the database account's permission type.
Permission model
Each database account in a PolarDB-X cluster is assigned one of two permission types:
| Permission type | How it works |
|---|---|
| Plaintext Permissions | The account reads plaintext directly. No additional client is needed. |
| Ciphertext Permission (JDBC Decryption) | The account reads ciphertext. Use the column encryption driver (JDBC) to decrypt and return plaintext transparently to the application. This is the default for all accounts unless explicitly granted Plaintext Permissions. |
Decide which accounts need Plaintext Permissions before you configure encryption, because this affects your DSC connection credential requirement and your application access strategy.
The DSC connection credential—the database account used to connect DSC to the PolarDB-X cluster—must have Plaintext Permissions. Without plaintext access, DSC cannot classify the latest sensitive data in the database.
Set up DSC and connect your database
Complete the following steps before enabling column encryption:
Activate or upgrade DSC
Column encryption is available in the DSC Free Edition, Enterprise Edition, and Value-added Service Only Edition. Each edition includes a free quota of 1 encrypted column. Purchase additional quota if your use case requires encrypting more columns.
If you have not used DSC:
-
Go to the Data Security Center buy page.
-
Select an edition and enable column encryption.
-
Click Buy Now and complete the payment.
After activation, view your feature specifications on the DSC Overview page.
If you already use DSC:
-
Log on to the Data Security Center console. On the Overview page, verify:
-
Your edition supports column encryption (Free Edition, Enterprise Edition, or Value-added Service Only).
-
Your column encryption quota is sufficient for your requirements.
-
-
If your quota is insufficient, click Upgrade on the Overview page to increase the number of encrypted columns supported in your current edition.
You can only upgrade within the same edition (for example, increase the encrypted column count). To switch to a different edition: - Free Edition: Purchase Enterprise Edition or Value-added Service Only while keeping your Free Edition resources. - Enterprise Edition or Value-added Service Only: Request a refund first, then purchase a different edition. The instance and data of the original edition will be released. Subscription duration cannot be changed during an upgrade.
-
Click Buy Now and complete the payment. The updated specifications appear on the Overview page.
Grant DSC permissions to access cloud resources
-
Log on to the Data Security Center console.
-
In the RAM Authorization dialog box, click Authorize Now.
If the RAM Authorization dialog box does not appear, DSC already has permission to access cloud resources.
Grant permissions to database assets
-
Log on to the Data Security Center console. In the left navigation pane, choose Asset Center.
-
On the Authorization Management tab, click Asset Authorization Management.
-
In the product navigation pane, select the target data type, then click Asset synchronization.
When you first log on after purchasing DSC, an asset sync runs automatically. DSC scans for new assets daily at midnight. If you are an existing user, go to Asset Center > Authorization Management > Asset Authorization Management and click Asset synchronization manually.
-
In the Actions column of the target asset, click Authorization.
To authorize multiple assets at once, select them and click Batch Authorize.
Connect to the database and run a sensitive data detection task
Choose one of the following connection methods:
One-click connection
-
In the left navigation pane, choose Asset Center.
-
On the Authorization Management tab, click Connect in the Actions column of the target asset.
-
In the dialog box, select Scan assets and identify sensitive data now., then click OK.
Important- Selecting Scan assets and identify sensitive data now. triggers a default system detection task that reads data from the database. To minimize performance impact, run this during off-peak hours. - If you skip the scan, go to Classification and Grading > Tasks > Identification Tasks > Default Tasks, find the task, and click Rescan to run it manually.
-
Click the
icon to the left of the database instance to view the connection status and feature status.
Credential-based connection
Use a dedicated database account and follow the principle of least privilege.
-
In the left navigation pane, choose Asset Center.
-
On the Authorization Management tab, click Account Logon in the Operation column for the target asset instance.
-
In the Account Logon panel, click Add Credential in the Operation column for the target database.
-
In the Add Credential dialog box, select a credential, configure the scan option, and click OK. If no credential exists, click the Create Credential tab. Enter the Credential Name, Username, Password, and Credential Type, then click OK.
Important- Selecting Scan assets and identify sensitive data now. triggers a default detection task that reads data and consumes read performance. Run this during off-peak hours. - If you skip the scan, go to Classification and Grading > Tasks > Identification Tasks > Default Tasks, find the task, and click Rescan.
-
Click the
icon to the left of the database instance to view the connection status and feature status.
Enable column encryption
-
Log on to the Data Security Center console. In the left navigation pane, choose Risk Governance > Column Encryption.
ImportantColumn encryption can only be configured for databases whose Encryption Check column shows Passed. If it shows Failed, the instance version may not support column encryption. See the FAQ section for troubleshooting steps.
-
Click Rapid Encryption above the instance list to configure encryption for all unencrypted columns across all instances. To target a specific instance, click Rapid Encryption in the Actions column of that instance.
-
In the Encryption Configuration panel, configure the following settings and click OK:
-
Asset Type, Instance name, and Plaintext Permission Accounts: Select the instance and specify which accounts get Plaintext Permissions.
-
Databases, Table, and Column: Select the scope of columns to encrypt.
Note the following:
-
PolarDB-X supports only
AES-128-GCMandSM4-128-GCMwith local encryption. -
All database accounts not in the Plaintext Permission Accounts list default to Ciphertext Permission (JDBC Decryption). These accounts access ciphertext and must use the column encryption driver (JDBC) to decrypt it.
-
Accounts added to Plaintext Permission Accounts can read encrypted column data as plaintext directly.
-
Modify the column encryption configuration
Modify the scope of encrypted columns
After enabling column encryption, expand or reduce the set of encrypted columns for a specific database instance.
-
Log on to the Data Security Center console. In the left navigation pane, choose Risk Governance > Column Encryption.
-
In the instance list, expand the target instance. Find the target Databases, Table, and Column, then click Enable Encryption or Disable Encryption.
Modify database account permissions
Change an account's permission between Plaintext Permissions and Ciphertext Permission (JDBC Decryption) based on your access requirements.
-
Log on to the Data Security Center console.
-
On the Risk Governance > Column Encryption page, click Permission Settings in the Accounts area. Alternatively, click Edit in the Actions column of the target instance, then click Configure for Account Permissions in the Edit panel.
-
In the Permission Settings panel, search for the target instance and account.
If a newly added database account is not listed, run Asset synchronization and check again.
-
In the Actions column, click Modify Permissions. To change permissions for multiple accounts at once, select them and click Batch Modify Permissions.
-
In the Modify Permission dialog box, select the target permission and click OK.
Verify column encryption
You can verify data access for encrypted columns based on the configured column encryption and database account permissions.
Column encryption is not fully compatible with third-party clients. For example, viewing encrypted data through Data Management (DMS) may cause exceptions. Use the column encryption driver (JDBC) to access encrypted data.
The following example uses a test PolarDB-X cluster where the birth_date column in the students01 table is encrypted. One account has Plaintext Permissions and another has Ciphertext Permission (JDBC Decryption).
-
Connect with the account that has Ciphertext Permission (JDBC Decryption) and run:
SELECT * FROM students01;The query returns ciphertext for the
birth_datecolumn. -
Connect with the account that has Plaintext Permissions and run:
SELECT * FROM students01;The query returns plaintext for the
birth_datecolumn.
Client usage
For accounts with Ciphertext Permission (JDBC Decryption), use the column encryption driver (JDBC) to connect to the database. The driver decrypts ciphertext automatically and returns plaintext to your Java application—transparent to application code. For setup instructions, see Column encryption driver (JDBC).
FAQ
What do I do if the encryption check fails for a PolarDB-X cluster?
First, confirm the cluster is in the Running state. Column encryption cannot be configured for clusters that are not running.
If the cluster is running but Encryption Check still shows Failed, the instance version is earlier than polardb-2.5.0_5.4.20-20250714_xcluster8.4.20-20250703. Upgrade the minor engine version:
-
On the instance details page, upgrade the minor engine version. For detailed steps, see View and upgrade the instance version.
-
After the upgrade, sync assets in DSC to get the latest database information:
-
Log on to the Data Security Center console. In the left navigation pane, choose Asset Center > Authorization Management > Asset Authorization Management.
-
In the product navigation pane, click the target cluster type.
-
Click Sync Assets.
-
What's next
-
For background on how column encryption works and its design principles, see Column encryption overview.
-
If sensitive data in an encrypted column changes after authorization, rescan it. See Scan for sensitive data using a detection task.