PolarDB:Use the always-confidential database feature from a client

Step 1: Download and install the driver

EncJDBC depends on the community PostgreSQL JDBC driver.

Install the JAR to your local Maven repository:

mvn install:install-file \
  -DgroupId=com.alibaba.encdb \
  -DartifactId=encjdbc \
  -Dversion=1.0.6 \
  -Dpackaging=jar \
  -Dfile=<path-to-encjdbc-1.0.6.jar>

Maven 3.9.2 is required. If you use an earlier version, upgrade Maven before running this command.

Step 2: Add Maven dependencies

Add the following to the <dependencies> section of your pom.xml:

<dependency>
  <groupId>com.alibaba.encdb</groupId>
  <artifactId>encjdbc</artifactId>
  <version>1.0.6</version>
</dependency>
<!-- Bouncy Castle crypto provider -->
<dependency>
  <groupId>org.bouncycastle</groupId>
  <artifactId>bcprov-jdk15on</artifactId>
  <version>1.62</version>
</dependency>
<dependency>
  <groupId>org.bouncycastle</groupId>
  <artifactId>bcpkix-jdk15on</artifactId>
  <version>1.62</version>
</dependency>
<dependency>
  <groupId>com.alibaba.fastjson2</groupId>
  <artifactId>fastjson2</artifactId>
  <version>2.0.2</version>
</dependency>
<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
  <version>42.2.23</version>
</dependency>
<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>guava</artifactId>
  <version>24.1.1-jre</version>
</dependency>
<dependency>
  <groupId>com.alibaba</groupId>
  <artifactId>druid</artifactId>
  <version>1.2.4</version>
</dependency>
<!-- jgrapht 1.4.0: versions 1.5.0+ drop Java 1.8 support -->
<dependency>
  <groupId>org.jgrapht</groupId>
  <artifactId>jgrapht-core</artifactId>
  <version>1.4.0</version>
</dependency>

Step 3: Connect and query

The connection URL uses the encjdbc:postgresql:// scheme and carries encryption parameters as query string fields:

String dbUrl = String.format(
    "encjdbc:postgresql://%s:%s/%s?mek=%s&enc_algo=%s",
    hostname, port, dbname, mek, encAlgo
);
Class.forName("com.alibaba.encdb.encjdbc.EncDriver");
Connection dbConnection = DriverManager.getConnection(dbUrl, username, password);

Complete example

// Load credentials from environment variables in production code.
String hostname = "hostname";
String port     = "port";
String dbname   = "db";
String username = "user";
String password = "password";

// Example MEK — use a stronger, randomly generated value in production.
String mek     = "00112233445566778899aabbccddeeff";
String encAlgo = "SM4_128_CBC";

String dbUrl = String.format(
    "encjdbc:postgresql://%s:%s/%s?mek=%s&enc_algo=%s",
    hostname, port, dbname, mek, encAlgo
);
Class.forName("com.alibaba.encdb.encjdbc.EncDriver");
Connection dbConnection = DriverManager.getConnection(dbUrl, username, password);

// Create table
dbConnection.createStatement().executeUpdate("DROP TABLE IF EXISTS example");
dbConnection.createStatement().executeUpdate(
    "CREATE TABLE example " +
    "(id INTEGER, name VARCHAR, price enc_int4, miles enc_float4, secret enc_text, PRIMARY KEY (id))"
);

// Insert encrypted data — EncJDBC encrypts automatically
PreparedStatement stmt = dbConnection.prepareStatement(
    "INSERT INTO example (id, name, price, miles, secret) VALUES(?,?,?,?,?)"
);
int    price  = 1234;
float  miles  = 12.34f;
String secret = "aliyun";
stmt.setInt(1, 1);
stmt.setString(2, "name");
stmt.setInt(3, price);
stmt.setFloat(4, miles);
stmt.setString(5, secret);
stmt.execute();

// Query — EncJDBC decrypts automatically; the result set contains plaintext values
String sqlCmd = "SELECT * FROM example WHERE price > ?";
PreparedStatement query = dbConnection.prepareStatement(sqlCmd);
query.setInt(1, 100);
ResultSet rs = query.executeQuery();
while (rs.next()) {
    int    id     = rs.getInt(1);
    String name   = rs.getString(2);
    int    priceV = rs.getInt(3);
    float  milesV = rs.getFloat(4);
    String secretV = rs.getString(5);
    System.out.println(id + ", " + name + ", " + priceV + ", " + milesV + ", " + secretV);
}

Expected output:

1, name, 1234, 12.34, aliyun

Only the driver class and the URL scheme differ from standard JDBC. All other database operations—inserts, queries, prepared statements—work identically to a plain JDBC program.

Step 1: Download and install the SDK

Install the JAR to your local Maven repository:

mvn install:install-file \
  -DgroupId=com.alibaba.encdb \
  -DartifactId=libencdb \
  -Dversion=1.2.12 \
  -Dpackaging=jar \
  -Dfile=<path-to-libencdb-1.2.12.jar>

Maven 3.9.2 is required. If you use an earlier version, upgrade Maven before running this command.

Step 2: Add Maven dependencies

<dependency>
  <groupId>com.alibaba.encdb</groupId>
  <artifactId>libencdb</artifactId>
  <version>1.2.12</version>
</dependency>
<dependency>
  <groupId>org.bouncycastle</groupId>
  <artifactId>bcprov-jdk15on</artifactId>
  <version>1.70</version>
</dependency>
<dependency>
  <groupId>org.bouncycastle</groupId>
  <artifactId>bcpkix-jdk15on</artifactId>
  <version>1.70</version>
</dependency>
<dependency>
  <groupId>com.google.code.gson</groupId>
  <artifactId>gson</artifactId>
  <version>2.10.1</version>
</dependency>
<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
  <version>42.2.23</version>
</dependency>
<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>guava</artifactId>
  <version>31.1-jre</version>
</dependency>

Step 3: Initialize the SDK and query data

EncDB SDK uses a standard PostgreSQL JDBC connection with binaryTransfer=true. After connecting, initialize an EncdbSDK object with your MEK and encryption algorithm. In most cases, the only required settings are setMek and setEncAlgo; use the defaults for everything else.

The MEK and other security parameters are set on the client side and transmitted to the server using envelope encryption, keeping the MEK value confidential in transit.

Complete example

// Load credentials from environment variables in production code.
String hostname = "hostname";
String port     = "port";
String dbname   = "db";
String username = "user";
String password = "password";

// Standard JDBC connection with binary transfer enabled for encrypted column types
String dbUrl = String.format(
    "jdbc:postgresql://%s:%s/%s?binaryTransfer=true",
    hostname, port, dbname
);
Class.forName("org.postgresql.Driver");
Connection dbConnection = DriverManager.getConnection(dbUrl, username, password);

// Initialize the SDK with your MEK and encryption algorithm
// Example MEK — use a stronger, randomly generated value in production.
String mek = "00112233445566778899aabbccddeeff";
Constants.EncAlgo encAlgo = Constants.EncAlgo.SM4_128_CBC;

EncdbSDK sdk = EncdbSDKBuilder.newInstance()
        .setDbConnection(dbConnection)
        .setMek(mek)
        .setEncAlgo(encAlgo)
        .build();
Cryptor cryptor = sdk.getCryptor();

// Create table
dbConnection.createStatement().executeUpdate("DROP TABLE IF EXISTS example");
dbConnection.createStatement().executeUpdate(
    "CREATE TABLE example " +
    "(id INTEGER, name VARCHAR, price enc_int4, miles enc_float4, secret enc_text, PRIMARY KEY (id))"
);

// Insert — encrypt each sensitive value explicitly before binding
PreparedStatement stmt = dbConnection.prepareStatement(
    "INSERT INTO example (id, name, price, miles, secret) VALUES(?,?,?,?,?)"
);
int    price  = 1234;
float  miles  = 12.34f;
String secret = "aliyun";
stmt.setInt(1, 1);
stmt.setString(2, "name");
stmt.setBytes(3, cryptor.encrypt("example", "price",  price));   // table name + column name
stmt.setBytes(4, cryptor.encrypt("example", "miles",  miles));
stmt.setBytes(5, cryptor.encrypt("example", "secret", secret));
stmt.execute();

// Query — decrypt each sensitive column explicitly after reading the raw bytes
String sqlCmd = "SELECT * FROM example WHERE price > ?";
PreparedStatement query = dbConnection.prepareStatement(sqlCmd);
query.setBytes(1, cryptor.encrypt("example", "price", 100));
ResultSet rs = query.executeQuery();
while (rs.next()) {
    int    id      = rs.getInt(1);
    String name    = rs.getString(2);
    int    priceV  = cryptor.decryptInt(rs.getBytes(3));
    float  milesV  = cryptor.decryptFloat(rs.getBytes(4));
    String secretV = cryptor.decryptString(rs.getBytes(5));
    System.out.println(id + ", " + name + ", " + priceV + ", " + milesV + ", " + secretV);
}

Expected output:

1, name, 1234, 12.34, aliyun

Pass the correct table name and column name to cryptor.encrypt(). If the names do not match the column definition, the SDK cannot look up the correct data encryption key (DEK) and the operation will fail.

SDK API reference

EncdbSDKBuilder newInstance();
EncdbSDKBuilder setDbConnection(java.sql.Connection dbConnection); // Required
EncdbSDKBuilder setKeyMgmtType(KeyMgmtType kmType);               // Required; use MYSQL_PROXY for confidential MySQL databases
EncdbSDKBuilder setMek(byte[] mek);                               // Required (16-byte byte[])
EncdbSDKBuilder setMek(String mekStr);                            // Required (32-char hex string)
EncdbSDKBuilder setEncAlgo(EncAlgo encAlgo);                      // Optional; default SM4_128_CBC
EncdbSDK        build();

Cryptor getCryptor();

int         decryptInt(byte[] val);
long        decryptLong(byte[] val);
float       decryptFloat(byte[] val);
double      decryptDouble(byte[] val);
String      decryptString(byte[] val);
BigDecimal  decryptDecimal(byte[] val);
Timestamp   decryptTimestamp(byte[] val);