JDBC

前提条件

• 支持的PolarDB PostgreSQL版（兼容Oracle）的内核小版本包括：Oracle语法兼容1.0版本和Oracle语法兼容2.0版本。

• 已经在PolarDB集群创建用户，如何创建用户请参见创建数据库账号。

• 已经将需要访问PolarDB集群的主机IP地址添加到白名单，如何添加白名单请参见设置集群白名单。

背景信息

JDBC（Java Database Connectivity）为Java应用程序提供了访问数据库的编程接口。PolarDB PostgreSQL版（兼容Oracle）数据库的JDBC是基于开源的PostgreSQL JDBC开发而来，使用PostgreSQL本地网络协议进行通信，允许Java程序使用标准的、独立于数据库的Java代码连接数据库。

下载驱动

JDBC驱动（42.5.4.0.9.2）

Maven配置

在Maven工程的pom.xml文件中添加如下依赖。

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId><安装的Jar包名></artifactId>
    <version><安装的Jar包版本号></version>
</dependency>

示例：

<dependency>
	<groupId>com.aliyun</groupId>
	<artifactId>polardb-jdbc18</artifactId>
	<version>42.5.4.0.6</version>
</dependency

功能介绍

连接级参数功能

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

版本路由功能

为了同时支持Oracle语法兼容1.0和Oracle语法兼容2.0两个版本，PolarDB提供了带有路由功能的JDBC。即在使用过程中，驱动通过连接数据库的类型自动识别，从而选择对应的驱动。

具体的选择方式如下表所示。

数据类型解析

• 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兼容的数据库交互需求。

PL/SQL适配

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

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

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

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

• 支持匿名块绑定参数。

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

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

示例

加载JDBC驱动

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

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

连接数据库

在JDBC中，一个数据库通常用一个URL来表示，示例如下：

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

查询并处理结果

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

访问数据库存储过程时，如果要使用带有OUT参数的存储过程，需要创建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

相关工具适配

适配Hibernate

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

<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>

Druid连接池

Druid 1.1.24之前的版本，需要显式设置driver name和dbtype参数，如下所示：

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

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

适配WebSphere

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

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

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

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

常见问题

如何选择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:poalardb://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:poalardb://1.2.XX.XX:5432,2.3.XX.XX:5432/postgres?oracleCase=true