PolarDB:JDBC

接続レベルのパラメーター機能

以下の機能は、接続パラメーターを使用して設定されます。サポートされているパラメーターを次の表に示します。すべての新しいパラメーターは接続レベルで有効であり、接続のライフサイクルに従います。

データ型の解析

• Date 型: 64 ビットの Date 型をサポートします。

  カーネルは、Oracle と同じデータ形式の 64 ビット Date 型をサポートしており、これには時、分、秒の情報が含まれます。ドライバーはこの Date 型を Timestamp として処理できます。すべての Date 型 (Types.DATE または DATEOID) を Timestamp 型にマッピングし、それに応じて処理します。

• Interval 型: Oracle モードでの Interval 入力をサポートします。

  コミュニティの PostgreSQL ドライバーは、+12 12:03:12.111 のような Interval 入力をサポートしていません。PolarDB for PostgreSQL (Oracle 互換) は、Oracle モードでの標準出力であるため、この出力形式をサポートしています。

• Number 型: Number 型の値の取得をサポートします。

  標準の 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 型: Boolean 型を 1/0 に変換することをサポートします。

  下位互換性のために、setBoolean インターフェイスメソッドはデフォルトで true/false を使用します。ただし、Oracle 互換のデータベース対話の要件を満たすために、boolAsInt パラメーターを有効にすることで、Oracle 互換の 1/0 セマンティクスに切り替えることができます。

  説明

  数値型をブール型に変換するルールは、ドライバーパッケージのバージョンによって異なります。

  • バージョン 42.5.4.0.10 以前: 数値 1 は True として扱われます。数値 0 は False として扱われます。その他の数値はエラーを返します。

  • バージョン 42.5.4.0.11 以降: 数値 0 は False として扱われます。その他すべてのゼロ以外の数値は True として扱われます。この動作は Oracle ドライバーと一致します。

PL/SQL の適応

• $$ 記号なしのストアドプロシージャをサポートします。

  この機能は、FUNCTION や PROCEDURE などのプロシージャを作成する際に $$ 記号を省略することをサポートし、構文解析中に / 文字を切り捨てます。

• コロンで始まる変数名をパラメーターとしてサポートします。

  パラメーターを :xxx 形式で渡すことをサポートします。ここで、xxx はコロンで始まる変数名です。

• 匿名ブロックでのパラメーターバインディングをサポートします。

• PL/SQL の警告メッセージの抑制をサポートします。

  この機能は、過剰な警告情報がループ内に保存され、メモリが超過するのを防ぎます。

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、PreparedStatement、または CallableStatement オブジェクトを作成する必要があります。

PreparedStatement の例を次に示します。

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 オブジェクトを使用して、関数やプロシージャを呼び出すことができます。

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),                     // 整数
      new BigDecimal("9999.99"),               // java.math.BigDecimal
      Boolean.TRUE,                            // ブール値
      new Date(),                              // java.util.Date
      new Timestamp(System.currentTimeMillis()), // java.sql.Timestamp
      "This is a test string",                 // 文字列
      new StringBuilder("mutable string"),     // 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.cfg.xml Hibernate 設定ファイルで PolarDB データベースのドライバークラスとダイアレクトを設定する必要があります。

  説明

  PostgresPlusDialect ダイアレクトをサポートするには、Hibernate のバージョンが 3.6 以降である必要があります。

  <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 型を指定します -->
          <!-- その他の列情報 -->
      </class>
  </hibernate-mapping>

• LOB (Large Object) 型の設定: ネイティブの PostgreSQL は LOB 型をサポートしていません。そのため、PostgresPlusDialect ダイアレクトは CLOB と BLOB の両方の型列を oid 型列にマッピングします。これにより、これらの列に挿入された文字列が oid 番号に変換されます。PolarDB for PostgreSQL (Oracle 互換) 2.0 は、CLOB 型を text 型に、BLOB 型を bytea 型にマッピングします。これを有効にするには、列の型を指定する必要があります。以下の 2 つの設定のいずれかを選択できます。

  • 設定 1: Java クラス定義。

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

  • 設定 2: 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 for 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 インジェクションの脅威を防ぐことができます。まず、WallConfig を設定し、setStrictSyntaxCheck(true) を設定します。また、複数ステートメントの不許可、コメントの許可、SELECT INTO の許可、条件なしの DELETE ステートメントのチェックなど、オプションの設定も構成できます。次に、WallConfig オブジェクトを使用して WallFilter を設定します。最後に、WallFilter を DruidDataSource のプロキシフィルターに追加します。

   // 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);    // WHERE 句のない 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 以降) を使用する場合、追加のコード変更なしで構造体型をストアドプロシージャのパラメーターとして直接渡すことができます。次の例は、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 for PostgreSQL (Oracle 互換) クラスターに接続し、管理することで、データシャーディングや読み書き分離などの高度な機能を実現できます。PolarDB は ShardingSphere がネイティブでサポートする PostgreSQL プロトコルと完全に互換性があるため、両者はシームレスに統合できます。

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 for PostgreSQL (Oracle 互換) は、オープンソースの PostgreSQL の上に多くの互換性関連機能を実装しています。一部の機能は、正しく機能するためにドライバーレベルの協力が必要です。そのため、PolarDB JDBC ドライバーを使用することをお勧めします。ドライバーは公式のドライバーダウンロードページからダウンロードできます。

PolarDB JDBC ドライバーは公開 Maven リポジトリで利用できますか。

公式サイトで説明されているように、JDBC ドライバーの JAR パッケージはウェブサイトからダウンロードする必要があります。Maven プロジェクトの場合、JAR パッケージをローカルリポジトリに手動でインストールする必要があります。現在、公式サイトから JDBC ドライバーパッケージをダウンロードする方法のみがサポートされています。

バージョン番号の確認方法

java -jar driver_name を実行してバージョン番号を確認できます。

URL に複数の IP アドレスとポートを設定することはサポートされていますか。

はい、PolarDB for 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.4.0.12 (2025-08-13)

• 構造体をパラメーターとして使用することをサポートします。

• 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 互換のコメント機能をサポートします。

• Mybatis で Clob インターフェイスを呼び出す際に null 値を使用することが原因で発生する 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 の場合にデータベースがパラメーター型を正しく推論できない問題を修正しました。