云原生数据库 PolarDB：JDBC

连接级参数功能

以下功能都通过一个连接参数配置，支持的参数如下表所示。所有的新增参数的生效范围都控制为连接级别，随Connection的生命周期生效。

数据类型解析

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

  内核支持了64位的Date，数据表示格式与Oracle相同，带有时分秒信息，对应驱动可以以Timestamp的方式去处理该Date。将所有的Date类型（Types.DATE或者DATEOID）映射成Timestamp类型，驱动将Date视为Timestamp进行处理。

• Interval类型：支持Oracle模式的Interval输入。

  PG社区的驱动不支持例如+12 12:03:12.111形式的Interval输入，由于目前Oracle模式下该形式是标准输出，所以PolarDB PostgreSQL版（兼容Oracle）支持这种形式的输出。

• Number类型：支持Number的GET行为。

  Java.sql的标准实现中没有getNumber相关的函数，只有getInt等函数。如果一个函数的参数类型是Number，允许使用getInt、setInt、RegisterParam等接口将参数以Int形式传递。

• Blob类型：Blob处理为Bytea，Clob处理为Text。

  针对Java.sql.Blob和Java.sql.Clob接口的实现。内核已经为Blob、Clob添加了映射，在Java层面也可以按照Bytea、Text的方式去处理。主类实现了getBytes、setBytes、position、getBinaryStream等方法。

• Boolean类型：支持布尔类型转义为1/0。

  为了保证老版本的兼容性，setBoolean 接口方法在设置时默认采用 true/false。然而，用户可以通过激活 boolAsInt 参数来切换至与Oracle兼容的1/0语义，以此适应Oracle兼容的数据库交互需求。

  说明

  针对数字类型转换为Boolean类型，不同版本的驱动包处理规则存在差异，具体区别如下：

  • 42.5.4.0.10及以下版本：1或等同于1的数字视为True，0或等同于0的数字视为False，其他数字值则返回错误。

  • 42.5.4.0.11及以上版本：0或等同于0的数字视为False，其他非0的数字值均视为True，此版本驱动的这一行为与Oracle驱动保持一致。

PL/SQL适配

• 支持不带$$符号的存储过程。

  支持在创建FUNCTION/PROCEDURE等过程时省略$$符号，并支持在语法解析时截断/字符。

• 支持冒号变量名作为参数。

  支持使用:xxx这种方式传递参数，其中xxx为冒号开头的变量名。

• 支持匿名块绑定参数。

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

  防止循环中存储过多的警告信息导致内存超限。

Oracle q-quote字面量语法

自42.5.7.0.14版本起，驱动完整支持Oracle q-quote语法的所有合法 delimiter（包括 ' 作 delimiter 的 q''..'' 特殊形态）。在PreparedStatement中q-quote内部的?和:xxx不会被误判为绑定参数：

-- 标准 q-quote：使用 [ ] 作为定界符
SELECT q'[It's a test]' FROM dual;
-- 结果: It's a test

-- 单引号作 delimiter 的特殊形态
SELECT q''te:s't ? :44'' FROM dual;
-- 结果: te:s't ? :44

// q-quote 内的 ? 和 :param 不会被识别为绑定参数
PreparedStatement ps = conn.prepareStatement(
    "SELECT q'[where id = ? and name = :test]' FROM dual");
ResultSet rs = ps.executeQuery();
rs.next();
System.out.println(rs.getString(1));
// 输出: where id = ? and name = :test

TABLE OF / INDEX BY 集合类型

自42.5.7.0.14版本起，驱动支持通过CallableStatement接收 PolarDB 的 TABLE OF / INDEX BY 集合类型作为 OUT 参数。使用 Types.ARRAY 注册 OUT 参数，通过 getArray() 获取 PgArray 对象，其中保留了关联数组的 key 信息。

典型用法：

// 假设数据库中有如下类型和函数：
// CREATE TYPE str_table IS TABLE OF VARCHAR2(100) INDEX BY BINARY_INTEGER;
// CREATE FUNCTION get_names() RETURN str_table IS ...

CallableStatement cs = conn.prepareCall("{ ? = call get_names() }");
cs.registerOutParameter(1, Types.ARRAY);
cs.execute();

// 方式一：直接获取 Array 的 Java 数组
Array arr = cs.getArray(1);

String[ ] values = (String[ ]) arr.getArray();

// values = ["alpha", "beta", "gamma"]

// 方式二：通过 ResultSet 遍历，并获取关联数组的 key
ResultSet rs = arr.getResultSet();
while (rs.next()) {
    int key = rs.getInt(1);      // 关联数组的 key（如 1, 2, 3）
    String val = rs.getString(2); // 对应的值
    System.out.println(key + " => " + val);
}
cs.close();

数值类型 OUT 参数自动转换

自42.5.7.0.14版本起，CallableStatement 的 OUT 参数支持全数值族类型自动互转。即使数据库函数返回 BIGINT，用户注册为 Types.NUMERIC 也能正确获取值，反之亦然。支持的类型包括：SMALLINT、INTEGER、BIGINT、NUMERIC、DECIMAL、REAL、FLOAT、DOUBLE。

典型用法（适用于 DBMS_SQL.EXECUTE 等返回 BIGINT 的场景）：

// 数据库函数实际返回 BIGINT，但业务框架按 Oracle 惯例注册为 NUMERIC
CallableStatement cs = conn.prepareCall("{ ? = call dbms_sql.execute(?) }");
cs.registerOutParameter(1, Types.NUMERIC);  // 注册为 NUMERIC
cs.setInt(2, cursorId);
cs.execute();

// 驱动自动完成 BIGINT → NUMERIC 转换
BigDecimal result = cs.getBigDecimal(1);
System.out.println(result); // 正常获取值，无类型不匹配错误
cs.close();

加载JDBC驱动

在应用中执行以下命令加载JDBC驱动：

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

连接数据库

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

jdbc:postgresql://pc-***.o.polardb.rds.aliyuncs.com:1521/postgres?forceDriverType=True

查询并处理结果

访问数据库执行查询时，需要创建一个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));
}

调用函数/存储过程

您可使用JDBC的CallableStatement对象调用函数（Function）和存储过程（Procedure）。

CREATE OR REPLACE PROCEDURE test_in_out_procedure (a IN number, b IN OUT number, c OUT number) IS
BEGIN
    b := a + b;
    c := b + 1;
END;

CallableStatement cstmt = connection.prepareCall("{call test_in_out_procedure(?, ?, ?)}");

// IN 参数 a
cstmt.setInt(1, 1);

// IN OUT 参数 b
cstmt.setInt(2, 2);
cstmt.registerOutParameter(2, Types.INTEGER);

// OUT 参数 c
cstmt.registerOutParameter(3, Types.INTEGER);

cstmt.execute();

int b = cstmt.getInt(2);
int c = cstmt.getInt(3);

CREATE OR REPLACE FUNCTION test_in_out_function (a IN number, b IN OUT number, c OUT number) RETURN number AS
BEGIN
    b := a + b;
    c := b + 1;
    RETURN c + 1;
END;

CREATE OR REPLACE PROCEDURE test_in_out_function_as_procedure_1 (
    a IN number,
    b IN OUT number,
    c OUT number,
    r OUT number
) AS
BEGIN
    r := test_in_out_function(a, b, c);
END;

CallableStatement cstmt = connection.prepareCall("{call test_in_out_function_as_procedure_1(?, ?, ?, ?)}");

cstmt.setInt(1, 1); // a
cstmt.setInt(2, 2); // b
cstmt.registerOutParameter(2, Types.INTEGER);
cstmt.registerOutParameter(3, Types.INTEGER); // c
cstmt.registerOutParameter(4, Types.INTEGER); // r

cstmt.execute();

int b = cstmt.getInt(2);
int c = cstmt.getInt(3);
int r = cstmt.getInt(4);

CREATE OR REPLACE PROCEDURE test_in_out_function_as_procedure_2 (
    a IN number,
    b IN OUT number,
    c OUT number,
    r OUT number
) AS
BEGIN
    SELECT test_in_out_function(a, b, c) INTO r FROM dual;
END;

CallableStatement cstmt = connection.prepareCall("{call test_in_out_function_as_procedure_2(?, ?, ?, ?)}");

cstmt.setInt(1, 1); // a
cstmt.setInt(2, 2); // b
cstmt.registerOutParameter(2, Types.INTEGER);
cstmt.registerOutParameter(3, Types.INTEGER); // c
cstmt.registerOutParameter(4, Types.INTEGER); // r

cstmt.execute();

// 假设 conn 是一个已建立的数据库连接对象
public void testSelectBoolean1() throws Exception {
  // 1. 准备构成结构体的属性数组。
  // 数组元素的顺序和类型必须与数据库中定义的 test_object 类型严格匹配。
  Object[] addressAttributes = new Object[] {
      Integer.valueOf(42),                     // Integer
      new BigDecimal("9999.99"),               // java.math.BigDecimal
      Boolean.TRUE,                            // Boolean
      new Date(),                              // java.util.Date
      new Timestamp(System.currentTimeMillis()), // java.sql.Timestamp
      "这是一个测试字符串",                      // String
      new StringBuilder("可变字符串"),           // StringBuilder
      null,                                    // null
  };
  
  // 2. 使用 conn.createStruct 创建 Struct 对象
  Struct addressStruct = conn.createStruct("test_object", addressAttributes);
  
   // 3. 准备并执行 CallableStatement 来调用函数
  CallableStatement stmt = conn.prepareCall("{? = call test_object_func(?)}");
  stmt.registerOutParameter(1, Types.VARCHAR);
  stmt.setObject(2, addressStruct);
  stmt.execute();
  
  // 4. 获取并打印函数返回值
  System.out.println(stmt.getObject(1).toString());
  
  stmt.close();
}

适配Hibernate

• hibernate.cfg.xml驱动类与方言配置：如果您的工程使用Hibernate连接数据库，请在您的Hibernate配置文件hibernate.cfg.xml中配置PolarDB数据库的驱动类和方言。

  说明

  Hibernate需要为3.6及以上版本才支持PostgresPlusDialect方言。

  <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类型配置：对于表中DATE类型的列，需要在Hibernate的.hbm.xml文件中调整配置type="java.util.Date"以确保Hibernate读写PolarDB的DATE类型数据时保留时分秒精度。如果直接使用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>

• LOB（Large Objects）大对象类型配置：原生PostgreSQL不支持LOB类型，因此PostgresPlusDialect方言将CLOB、BLOB类型的列都映射为oid类型的列，这会导致插入该列的字符串被转为oid数字。PolarDB PostgreSQL版Oracle语法兼容 2.0将CLOB类型映射为text类型，BLOB映射为bytea类型。需要指定列的类型使之生效，以下配置二选一即可。

  • 配置一：Java类定义。

    @Lob
    @Column(name = "col_clob")
    @Type(type = "text")
    private String columnClob;
    
    @Lob
    @Column(name = "col_blob")
    @Type(type = "bytea")
    private String columnBlob;

  • 配置二：在Hibernate的.hbm.xml文件定义。

    <!-- 其他配置信息 -->
    <hibernate-mapping package="com.aliyun.polardb2.demo">
        <class name="TestTableEntity" table="test_table_name">
            <!-- 其他列信息 -->
            <property name="columnClob" column="col_clob" type="text"/>
            <property name="columnBlob" column="col_blob" type="bytea"/>
            <!-- 其他列信息 -->
        </class>
    </hibernate-mapping>

Druid连接池

Druid是一个数据库连接池，您可以通过它来管理应用程序与PolarDB PostgreSQL版（兼容Oracle）之间的连接。当您使用Druid连接时，为确保功能的完整性和稳定性，请注意以下关键配置：

1. Druid是从1.2.26版本开始支持PolarDB的，请确保您项目中引用的版本不低于此版本。以Maven为例：

   <dependency>
       <groupId>com.alibaba</groupId>
       <artifactId>druid</artifactId>
       <version>1.2.26</version>
   </dependency>

2. 在初始化连接池时，必须显式设置驱动类名（driverClassName）和数据库类型（dbType）。

   DruidDataSource dataSource = new DruidDataSource();
   dataSource.setDriverClassName("com.aliyun.polardb2.Driver");
   dataSource.setDbType("polardb2");

3. 使用SQL防火墙（WallFilter）严格检查业务SQL是否符合Oracle语法规范，防止SQL注入风险。

   // 1. 配置 WallConfig
   WallConfig wallConfig = new WallConfig();
   
   // 1.1 是否进行严格的语法检查，必填
   wallConfig.setStrictSyntaxCheck(true);
   
   // 1.2 更精细的语法控制，仅列举部分，可选
   wallConfig.setMultiStatementAllow(false);    // 是否允许一次执行多条语句
   wallConfig.setCommentAllow(true);            // 允许注释
   wallConfig.setSelectIntoAllow(true);         // 允许SELECT INTO
   wallConfig.setDeleteWhereNoneCheck(true);    // 检查DELETE语句是否无条件
   
   // 2. 使用 WallConfig 配置 WallFilter
   WallFilter wallFilter = new WallFilter();
   wallFilter.setConfig(wallConfig);
   
   // 3. 使用 WallFilter 配置连接池
   DruidDataSource dataSource = new DruidDataSource();
   dataSource.getProxyFilters().add(wallFilter);

4. 如果需要在Druid连接池中对数据库密码进行加密，请参见数据库密码加密。

适配WebSphere

使用WebSphere时，配置PolarDB的JDBC作为数据源，步骤如下所示：

1. 数据库类型选择用户自定义的。

2. 实现类名为：com.aliyun.polardb2.ds.PGConnectionPoolDataSource。

3. 类路径选择JDBC jar包所在路径。

适配Spring框架

在Spring框架中使用新版本JDBC（版本号≥ 42.5.4.0.11）时，可以直接将结构体类型（Struct）作为存储过程参数传入，无需额外的代码改造。以下示例演示了如何通过GetUserProcedure方法调用存储过程get_user_info，其中参数c为复合类型com，通过构建相应的结构体对象实现复合类型的参数传递。

public class GetUserProcedure extends StoredProcedure {
    private static final String PROCEDURE_NAME = "get_user_info";

    public GetUserProcedure(DataSource dataSource) {
        super(dataSource, PROCEDURE_NAME);
        init();
    }

    private void init() {
        // 声明输入参数
        declareParameter(new SqlParameter("p_user_id", Types.NUMERIC));
        declareParameter(new SqlParameter("c", Types.STRUCT, "com"));

        compile(); // 必须调用 compile()
    }

    public Map<String, Object> getUserInfo(Integer userId) {
        Map<String, Object> inputs = new HashMap<>();
        inputs.put("p_user_id", userId);
        Calendar cal = Calendar.getInstance();
        cal.set(2023, Calendar.OCTOBER, 1, 12, 30, 45); // 注意：Calendar 的月份从 0 开始
        cal.set(Calendar.MILLISECOND, 0);

        Rec rec = new Rec();
        rec.t1 = 1;
        rec.t2 = "some text";
        rec.t3 = new Date(cal.getTime().getTime());
        rec.t4 = true;
        rec.t5 = null;
        inputs.put("c", rec);

        return execute(inputs); // 执行存储过程
    }
}

适配Apache ShardingSphere

您可以通过Apache ShardingSphere连接并管理PolarDB PostgreSQL版（兼容Oracle）集群，以实现数据分片、读写分离等高级功能。由于PolarDB完全兼容PostgreSQL协议，而ShardingSphere原生支持该协议，因此两者可以无缝集成。

dataSources:
  ds0:
    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
    driverClassName: com.aliyun.polardb2.Driver
    jdbcUrl: jdbc:postgresql://pc-***.o.polardb.rds.aliyuncs.com:1521/postgres?forceDriverType=True
    username: ******
    password: ******
    maxPoolSize: 2
    minPoolSize: 2
  ds1:
    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
    driverClassName: com.aliyun.polardb2.Driver
    jdbcUrl: jdbc:postgresql://pc-***.o.polardb.rds.aliyuncs.com:1521/postgres?forceDriverType=True
    username: ******
    password: ******
    maxPoolSize: 2
    minPoolSize: 2

如何选择JDBC驱动，是否可以使用开源社区驱动？

PolarDB PostgreSQL版（兼容Oracle）兼容版在开源PostgreSQL的基础上实现了众多兼容性相关的特性，有些特性需要驱动层配合实现，因此，推荐使用PolarDB的JDBC驱动。相关驱动可以在官网驱动下载页面下载。

公共Maven仓库是否有PolarDB JDBC驱动？

按照官网描述，JDBC驱动需要在官网下载jar包，对于Maven工程需要手动安装该jar包至本地仓库使用，目前仅支持官网下载JDBC驱动包一种方式。

如何查看版本号？

通过运行java -jar 驱动名来查看版本号。

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

PolarDB PostgreSQL版（兼容Oracle）的JDBC驱动支持在URL中配置多个IP和端口，示例如下：

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

游标类型如何选择？

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

是否支持默认返回大写的列名？

可以在JDBC连接串中添加参数oracleCase=true，该参数会将返回的列名默认转换为大写，示例如下：

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

42.5.7.0.14 (2026-05-28)

42.5.7.0.13 (2025-12-24)

• 核心组件升级：将JDBC驱动版本同步至社区42.5.x系列的最新稳定版（42.5.7），引入了最新的安全补丁与性能优化。

• 连接稳定性增强：深度修复了在特定连接池场景下可能出现的连接泄漏隐患，提升了长连接环境下的资源管理可靠性。

• 第三方生态兼容性优化：确保第三方框架（如MyBatis、Hibernate等）能够准确识别驱动类型，避免因识别偏差导致的兼容性异常。

  • 调整getDatabaseProductName返回值为PostgreSQL。

  • 调整DRIVER_NAME返回值为PolarDB-2.0 JDBC Driver。

• 驱动冲突规避：移除了对jdbc:oracle:thin:连接协议的支持。此举旨在消除在多驱动并存的项目中与原生Oracle驱动的潜在冲突，确保驱动加载逻辑的唯一性与准确性。

• Oracle迁移适配增强：优化了getTables接口的检索逻辑，支持通过大写表名查找表。该特性适配了从Oracle迁移至PolarDB的Java业务代码逻辑，降低了应用迁移的改造成本。

42.5.4.0.12（2025-08-13）

• 支持使用结构体（Struct）作为参数。

• 支持使用jdbc:postgresql协议连接集群。

42.5.4.0.10.11（2025-07-10）

• 支持通过CallableStatement接口读写函数以及存储过程，支持各种类型的IN&OUT&INOUT参数。

• 支持SQLCODE错误码字段，与数据库内核的错误处理机制兼容。

• 支持Spring框架中使用Types.STRUCT结构体。

• 优化数字类型到布尔值的转换规则。

• 增强类型绑定支持。

42.5.4.0.10.9（2025-03-19）

• 支持Oracle风格的函数绑定参数功能。

• 修复一个END会导致解析失败的缺陷。

42.5.4.0.10.7（2025-01-06）

• 支持兼容Oracle方式的注释功能（即支持/* /* Comments */功能）。

• 修复Mybatis调用Clob接口时，使用空值导致的Misuse of castNonNull问题。

42.5.4.0.10.6（2024-12-04）

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

• 升级escapeSyntaxCallMode参数默认值为callIfNoReturn，适配Oracle的参数绑定行为。

• 修复attidentity识别错误可能导致的列类型获取不正确缺陷。

42.5.4.0.10.5（2024-10-24）

• 优化resetNlsFormat参数的设置，确保连接时的正确配置。同时，避免在审计日志中留下非预期的执行记录。

• 修复逻辑复制测试中因无法识别java.nio.Buffer类型接口而导致的错误。

• 修复存储过程中CASE WHEN...END识别结束解析不正确的问题。

42.5.4.0.10.4（2024-09-02）

• 修复了PL块中绑定不正确的问题。针对此问题对性能的影响，默认已关闭该功能。

• 支持在同一类型内部进行隐式转换，允许字符类型（如VARCHAR、CHAR）和数字类型（如NUMERIC、INTEGER、DOUBLE）作为INOUT参数相互转换。

• 驱动中元信息的 getDatabaseProductName()函数返回值现为：“POLARDB2 Database Compatible with Oracle”。

42.5.4.0.10.2（2024-07-19）

• 修复了在Mybatis中，当对象实体注册类型为Timestamp时，数据库无法正确推断参数类型的问题。