前提條件

• 支持PolarDB PostgreSQL版（兼容Oracle） 2.0版本。

• 已經(jīng)在PolarDB集群創(chuàng)建用戶，如何創(chuàng)建用戶請參見創(chuàng)建數(shù)據(jù)庫賬號。

• 已經(jīng)將需要訪問PolarDB集群的主機(jī)IP地址添加到白名單，如何添加白名單請參見設(shè)置集群白名單。

背景信息

JDBC（Java Database Connectivity）為Java應(yīng)用程序提供了訪問數(shù)據(jù)庫的編程接口。PolarDB PostgreSQL版（兼容Oracle）數(shù)據(jù)庫的JDBC是基于開源的PostgreSQL JDBC開發(fā)而來，使用PostgreSQL本地網(wǎng)絡(luò)協(xié)議進(jìn)行通信，允許Java程序使用標(biāo)準(zhǔn)的、獨(dú)立于數(shù)據(jù)庫的Java代碼連接數(shù)據(jù)庫。

下載驅(qū)動

Maven配置

目前PolarDB的JDBC驅(qū)動尚未在公開的Maven倉庫中提供，當(dāng)前僅支持通過上傳JAR包的方式進(jìn)行配置。

功能介紹

連接級參數(shù)功能

以下功能都通過一個連接參數(shù)配置，支持的參數(shù)如下表所示。所有的新增參數(shù)的生效范圍都控制為連接級別，隨Connection的生命周期生效。

數(shù)據(jù)類型解析

• Date類型：64位Date類型的支持。

  內(nèi)核支持了64位的Date，數(shù)據(jù)表示格式與Oracle相同，帶有時分秒信息，對應(yīng)驅(qū)動可以以Timestamp的方式去處理該Date。將所有的Date類型（Types.DATE或者DATEOID）映射成Timestamp類型，驅(qū)動將Date視為Timestamp進(jìn)行處理。

• Interval類型：支持Oracle模式的Interval輸入。

  PG社區(qū)的驅(qū)動不支持例如+12 12:03:12.111形式的Interval輸入，由于目前Oracle模式下該形式是標(biāo)準(zhǔn)輸出，所以PolarDB PostgreSQL版（兼容Oracle）支持這種形式的輸出。

• Number類型：支持Number的GET行為。

  Java.sql的標(biāo)準(zhǔn)實現(xiàn)中沒有g(shù)etNumber相關(guān)的函數(shù)，只有g(shù)etInt等函數(shù)。如果一個函數(shù)的參數(shù)類型是Number，允許使用getInt、setInt、RegisterParam等接口將參數(shù)以Int形式傳遞。

• Blob類型：Blob處理為Bytea，Clob處理為Text。

  針對Java.sql.Blob和Java.sql.Clob接口的實現(xiàn)。內(nèi)核已經(jīng)為Blob、Clob添加了映射，在Java層面也可以按照Bytea、Text的方式去處理。主類實現(xiàn)了getBytes、setBytes、position、getBinaryStream等方法。

• Boolean類型：支持布爾類型轉(zhuǎn)義為1/0。

  為了保證老版本的兼容性，setBoolean 接口方法在設(shè)置時默認(rèn)采用 true/false。然而，用戶可以通過激活 boolAsInt 參數(shù)來切換至與Oracle兼容的1/0語義，以此適應(yīng)Oracle兼容的數(shù)據(jù)庫交互需求。

PL/SQL適配

• 支持不帶$$符號的存儲過程。

  支持在創(chuàng)建FUNCTION/PROCEDURE等過程時省略$$符號，并支持在語法解析時截斷/字符。

• 支持冒號變量名作為參數(shù)。

  支持使用:xxx這種方式傳遞參數(shù)，其中xxx為冒號開頭的變量名。

• 支持匿名塊綁定參數(shù)。

• 支持屏蔽PLSQL的警告信息。

  防止循環(huán)中存儲過多的警告信息導(dǎo)致內(nèi)存超限。

示例

加載JDBC驅(qū)動

在應(yīng)用中執(zhí)行以下命令加載JDBC驅(qū)動：

Class.forName("com.aliyun.polardb2.Driver");

連接數(shù)據(jù)庫

在JDBC中，一個數(shù)據(jù)庫通常用一個URL來表示，示例如下：

jdbc:polardb://pc-***.o.polardb.rds.aliyuncs.com:1521/polardb_test?user=test&password=Pw123456

查詢并處理結(jié)果

訪問數(shù)據(jù)庫執(zhí)行查詢時，需要創(chuàng)建一個Statement、PreparedStatment或者CallableStatement對象。

使用PreparedStatment示例如下：

PreparedStatement st = conn.prepareStatement("select id, name from foo where id > ?");
st.setInt(1, 10);
resultSet = st.executeQuery();
while (resultSet.next()) {
    System.out.println("id:" + resultSet.getInt(1));
    System.out.println("name:" + resultSet.getString(2));
}

使用OUT參數(shù)

訪問數(shù)據(jù)庫存儲過程時，如果要使用帶有OUT參數(shù)的存儲過程，需要創(chuàng)建CallableStatement對象。并使用

registerOutParameter，使用示例如下：

String sql = "CREATE or replace PROCEDURE test_in_out_procedure(a IN integer, b INOUT integer, c OUT integer)\n" +
                    "AS $$\n" +
                    "BEGIN\n" +
                    "    c = a + b;\n" +
                    "    b = a;\n" +
                    "return;\n" +
                    "END;\n" +
                    "$$;";
conn.createStatement().execute(sql);
CallableStatement stmt = conn.prepareCall("{call test_in_out_procedure(?,?,?)}");
stmt.setInt(1, 1);
stmt.setInt(2, 2);
stmt.registerOutParameter(2, Types.INTEGER);
stmt.registerOutParameter(3, Types.INTEGER);

stmt.execute();

System.out.println("get $2 = " + stmt.getInt(2));
System.out.println("get $3 = " + stmt.getInt(3));

// OUTPUT:
// get $2 = 1
// get $3 = 3

相關(guān)工具適配

適配Hibernate

如果您的工程使用Hibernate連接數(shù)據(jù)庫，請在您的Hibernate配置文件hibernate.cfg.xml中配置PolarDB數(shù)據(jù)庫的驅(qū)動類和方言。

<property name="connection.driver_class">com.aliyun.polardb2.Driver</property>
<property name="connection.url">jdbc:polardb://pc-***.o.polardb.rds.aliyuncs.com:1521/polardb_test</property>
<property name="dialect">org.hibernate.dialect.PostgresPlusDialect</property>

對于表中date類型的列，需要在Hibernate的.hbm.xml文件中調(diào)整配置type="java.util.Date"以確保Hibernate讀寫PolarDB的date類型數(shù)據(jù)時保留時分秒精度。如果直接使用type="date"，則可能造成date精度丟失。示例配置如下：

<!-- 其他配置信息 -->
<hibernate-mapping package="com.aliyun.polardb2.demo">
    <class name="TestTableEntity" table="test_table_name">
        <!-- 其他列信息 -->
        <property name="currentDate" column="curr_date" type="java.util.Date"/> <!-- 指定java.util.Date類型以保留date精度 -->
        <!-- 其他列信息 -->
    </class>
</hibernate-mapping>

Druid連接池

Druid 1.1.24之前的版本，需要顯式設(shè)置driver name和dbtype參數(shù)，如下所示：

dataSource.setDriverClassName("com.aliyun.polardb2.Driver");
dataSource.setDbType("postgresql");

如果您需要在Druid連接池中對數(shù)據(jù)庫密碼進(jìn)行加密，請參見數(shù)據(jù)庫密碼加密。

適配WebSphere

使用WebSphere時，配置PolarDB的JDBC作為數(shù)據(jù)源，步驟如下所示：

1. 數(shù)據(jù)庫類型選擇用戶自定義的。

2. 實現(xiàn)類名為：com.aliyun.polardb2.ds.PGConnectionPoolDataSource。

3. 類路徑選擇JDBC jar包所在路徑。

常見問題

如何選擇JDBC驅(qū)動，是否可以使用開源社區(qū)驅(qū)動？

PolarDB PostgreSQL版（兼容Oracle）兼容版在開源PostgreSQL的基礎(chǔ)上實現(xiàn)了眾多兼容性相關(guān)的特性，有些特性需要驅(qū)動層配合實現(xiàn)，因此，推薦使用PolarDB的JDBC驅(qū)動。相關(guān)驅(qū)動可以在官網(wǎng)驅(qū)動下載頁面下載。

公共Maven倉庫是否有PolarDB JDBC驅(qū)動？

按照官網(wǎng)描述，JDBC驅(qū)動需要在官網(wǎng)下載jar包，對于Maven工程需要手動安裝該jar包至本地倉庫使用，目前僅支持官網(wǎng)下載JDBC驅(qū)動包一種方式。

如何查看版本號？

通過運(yùn)行java -jar 驅(qū)動名來查看版本號。

是否支持在URL中配置多個IP和端口？

PolarDB PostgreSQL版（兼容Oracle）的JDBC驅(qū)動支持在URL中配置多個IP和端口，示例如下：

jdbc:polardb://1.2.XX.XX:5432,2.3.XX.XX:5432/postgres

游標(biāo)類型如何選擇？

如果是java 1.8之前的JDK，使用Types.REF；如果是java 1.8及其之后的版本，可以使用Types.REF_CURSOR。

是否支持默認(rèn)返回大寫的列名？

可以在JDBC連接串中添加參數(shù)oracleCase=true，該參數(shù)會將返回的列名默認(rèn)轉(zhuǎn)換為大寫，示例如下：

jdbc:polardb://1.2.XX.XX:5432,2.3.XX.XX:5432/postgres?oracleCase=true

版本更新日志

版本45.4.0.10.6（2024-12-04）

• 支持高版本JDBC的Channel Binding功能。

• 升級escapeSyntaxCallMode參數(shù)默認(rèn)值為callIfNoReturn，適配Oracle的參數(shù)綁定行為。

• 修復(fù)attidentity識別錯誤可能導(dǎo)致的列類型獲取不正確缺陷。

版本45.4.0.10.5（2024-10-24）

• 優(yōu)化resetNlsFormat參數(shù)的設(shè)置，確保連接時的正確配置。同時，避免在審計日志中留下非預(yù)期的執(zhí)行記錄。

• 修復(fù)邏輯復(fù)制測試中因無法識別java.nio.Buffer類型接口而導(dǎo)致的錯誤。

• 修復(fù)存儲過程中CASE WHEN...END識別結(jié)束解析不正確的問題。

版本45.4.0.10.4（2024-09-02）

• 修復(fù)了PL塊中綁定不正確的問題。針對此問題對性能的影響，默認(rèn)已關(guān)閉該功能。

• 支持在同一類型內(nèi)部進(jìn)行隱式轉(zhuǎn)換，允許字符類型（如VARCHAR、CHAR）和數(shù)字類型（如NUMERIC、INTEGER、DOUBLE）作為INOUT參數(shù)相互轉(zhuǎn)換。

• 驅(qū)動中元信息的 getDatabaseProductName()函數(shù)返回值現(xiàn)為：“POLARDB2 Database Compatible with Oracle”。

版本45.4.0.10.2（2024-07-19）

• 修復(fù)了在Mybatis中，當(dāng)對象實體注冊類型為Timestamp時，數(shù)據(jù)庫無法正確推斷參數(shù)類型的問題。

專家面對面

關(guān)于JDBC，如果您在使用過程中有任何問題，請進(jìn)釘釘群咨詢。釘釘群號：71365019522。