Hologres supports Secure Sockets Layer (SSL) encryption in transit to protect data exchanged between clients and Hologres instances. SSL uses digital certificates and encryption algorithms, including Transport Layer Security (TLS), to establish encrypted connections that safeguard confidentiality and integrity during transmission.
SSL provides transport-layer encryption for network connections. This enhances security and integrity but increases network connection response time.
When to use SSL encryption
Remote database access: Encrypt connections from clients that access a Hologres database over a public or untrusted network.
Security and compliance: Meet industry standards and regulatory requirements that mandate encryption for data in transit.
SSL modes
Hologres supports the following SSL modes. The mode determines the level of verification performed during the SSL handshake.
SSL mode | Description | Certificate required | Minimum version |
| Encrypts the data link. Does not verify server identity. | No | V1.1 |
| Encrypts the data link and uses a CA certificate to authenticate the Hologres server. | Yes | V2.1 |
| Encrypts the data link, uses a CA certificate to authenticate the Hologres server, and compares the CN (Common Name) or DNS in the certificate with the Hologres endpoint configured for the connection. | Yes | V2.1 |
| Does not use encryption in transit. | No | N/A |
Version requirements
Version | SSL capability |
V1.1 and later | Encryption in transit |
V1.2 and later | TLS |
V2.1 and later | Encryption in transit with CA certificates and self-service enablement in the management console |
If your instance is earlier than V1.1, submit your feedback using Common upgrade preparation failure errors or by joining the Hologres DingTalk group. For more information, see How do I get more online support?.
Prerequisites
Before you begin, make sure that you have:
A Hologres instance. For more information, see Purchase a Hologres instance
The PSQL client or Java Database Connectivity (JDBC) installed. For more information, see PSQL client or JDBC
Enable encryption in transit
Log on to the Hologres management console and select a region in the upper-left corner.
In the left-side navigation pane, click Instances, and then click the ID of the target instance.
On the instance page, click Data Security.
On the SSL tab, turn on the SSL Encryption switch.
In the Enable SSL Encryption dialog box, click Enable SSL Encryption.
Download the CA certificate
Hologres provides an instance CA certificate to verify the authenticity of the server when connecting remotely. The CA certificate is required for verify-ca and verify-full modes.
Log on to the Hologres management console and select a region in the upper-left corner.
In the left-side navigation pane, click Instances, and then click the ID of the target instance.
On the instance page, click Data Security.
On the SSL tab, click Download Certificate.
Connect with SSL encryption
After you enable SSL encryption, connect to Hologres using the PSQL client or JDBC. Configure SSL parameters to control the encryption mode. If you use verify-ca or verify-full mode, download the CA certificate first.
Connect by using PSQL
Run the following command to connect:
PG_USER=<AccessKey ID>
PG_PASSWORD=<AccessKey secret>
PG_SSLMODE=<SSL Mode>
PG_SSLROOTCERT=<certificate folder>
PGSSLMODE=$PG_SSLMODE PGSSLROOTCERT=$PG_SSLROOTCERT PGUSER=$PG_USER PGPASSWORD=$PG_PASSWORD psql -p <Port> -h <Endpoint> -d <Database>The following table describes the parameters.
Parameter | Description |
AccessKey ID | The AccessKey ID of your Alibaba Cloud account. Go to AccessKey Management to obtain the AccessKey ID. Store credentials in environment variables to reduce the risk of leaks. |
AccessKey secret | The AccessKey secret of your Alibaba Cloud account. Go to AccessKey Management to obtain the AccessKey secret. Store credentials in environment variables to reduce the risk of leaks. |
SSL Mode | The SSL mode for the connection. Valid values: |
certificate folder | The path to the CA certificate file. Required when SSL Mode is set to |
Port | The public port of the Hologres instance. Example: |
Endpoint | The public endpoint of the Hologres instance. Example: |
Database | The name of the Hologres database. A default postgres database is created automatically, but it is allocated limited resources. Create a dedicated database for production workloads. For more information, see Create a database. Example: |
Verify the connection
If you set PGSSLMODE to require, the following output indicates that an SSL-encrypted connection is active:

Connect by using JDBC
Set the ssl and sslmode connection properties to control SSL behavior. The connection result depends on the combination of these properties and the server-side SSL setting, as shown in the following table.
Instance SSL enabled |
|
| Result |
Yes |
|
| Connected. Encryption in transit is used. |
Yes |
|
| Connected. Encryption in transit is not used. |
No |
|
| Connection fails with an error. |
No |
|
| Connected. Encryption in transit is not used. |
Example code
// Set the endpoint of the Hologres instance.
String hostname = "hgxxxxxxx-cn-hangzhou-vpc.hologres.aliyuncs.com";
// Set the port of the Hologres instance.
String port = "80";
// Set the name of the database to connect to.
String dbname = "postgres";
String jdbcUrl = "jdbc:postgresql://" + hostname + ":" + port + "/" + dbname + "?binaryTransfer=true";
Properties properties = new Properties();
// Set the username for the database connection.
// Use environment variables to reduce the risk of credential leaks.
properties.setProperty("user", System.getenv("ALIBABA_CLOUD_USER"));
// Set the password for the database connection.
// Use environment variables to reduce the risk of credential leaks.
properties.setProperty("password", System.getenv("ALIBABA_CLOUD_PASSWORD"));
// Enable SSL.
properties.setProperty("ssl", "true");
// Set the path to the CA root certificate.
properties.setProperty("sslrootcert", path + "/" + "hologres_certificate.crt");
// Set the SSL mode. Valid values: require, verify-ca, verify-full.
properties.setProperty("sslmode", "verify-full");
try {
Class.forName("org.postgresql.Driver");
Connection connection = DriverManager.getConnection(jdbcUrl, properties);
// In this example, assume that a table named example exists in the postgres database.
// The following code queries data from the example table.
PreparedStatement preparedStatement = connection.prepareStatement("select * from " +
"example");
ResultSet resultSet = preparedStatement.executeQuery();
while (resultSet.next()) {
ResultSetMetaData rsmd = resultSet.getMetaData();
int columnCount = rsmd.getColumnCount();
Map map = new HashMap();
for (int i = 0; i < columnCount; i++) {
map.put(rsmd.getColumnName(i + 1).toLowerCase(), resultSet.getObject(i + 1));
}
System.out.println(map);
}
} catch (Exception exception) {
exception.printStackTrace();
}Important considerations
Instance restart and downtime
Enabling or disabling SSL encryption requires an instance restart. Renewing the SSL certificate also requires a restart. Each restart takes approximately 3 minutes. Perform these operations during off-peak hours.
SSL connection behavior
Scenario | Behavior |
SSL disabled (default) | Only non-SSL connections are supported. |
SSL enabled | Clients can connect with or without SSL, but must specify the connection mode explicitly. |
SSL disabled after being enabled | Only non-SSL connections are supported. |
Configuration changed | Existing connections must be disconnected and reconnected for the change to take effect. |
Performance impact
Enabling SSL encryption increases CPU utilization and read/write latency.
Certificate validity
The SSL certificate is valid for one year. Manually renew the certificate before it expires. If the certificate expires, SSL-encrypted connections to the instance fail.
