PolarDB:JDBC

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

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

データ型の解析

• Date 型：64 ビット Date 型のサポート。

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

• Interval 型：Oracle モードでの Interval 型入力のサポート。

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

• Number 型：Number 型の GET 動作のサポート。

  java.sql の標準実装には getNumber 関数がありません。getInt などの関数のみがあります。関数パラメーターが Number 型の場合、getInt、setInt、RegisterParam などのインターフェイスを使用して、パラメーターを整数として渡すことができます。

• 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 を使用します。ただし、boolAsInt パラメーターを有効にすることで、Oracle 互換の 1/0 セマンティクスに切り替えることができます。これにより、Oracle と互換性のあるデータベース対話要件に適応します。

  説明

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

  • バージョン 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),                     // Integer
      new BigDecimal("9999.99"),               // java.math.BigDecimal
      Boolean.TRUE,                            // Boolean
      new Date(),                              // java.util.Date
      new Timestamp(System.currentTimeMillis()), // java.sql.Timestamp
      "This is a test string",                 // 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 設定ファイルで 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 (ラージオブジェクト) 型の設定：ネイティブの PostgreSQL は LOB 型をサポートしていません。そのため、PostgresPlusDialect ダイアレクトは CLOB と BLOB の両方の列を oid 型の列にマッピングします。これにより、これらの列に挿入された文字列は oid 番号に変換されます。PolarDB for PostgreSQL (Oracle 互換) 2.0 は、CLOB 型を text 型に、BLOB 型を bytea 型にマッピングします。マッピングを有効にするには、列の型を指定する必要があります。次のいずれかの設定を使用できます。

  • 設定 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 インジェクションの脅威を防ぎます。

   // 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 以降) を使用する場合、追加のコード変更なしで構造体をストアドプロシージャのパラメーターとして直接渡すことができます。次の例は、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 は 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 for PostgreSQL (Oracle 互換) は、オープンソースの PostgreSQL をベースに多くの互換性機能を実装しています。一部の機能はドライバーレベルでの連携が必要なため、PolarDB JDBC ドライバーの使用を推奨します。ドライバーは公式サイトからダウンロードできます。

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

公式サイトによると、JDBC ドライバーを入手する唯一のサポートされている方法は、JAR パッケージをダウンロードすることです。Maven プロジェクトの場合、この JAR パッケージをローカルリポジトリに手動でインストールする必要があります。

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

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

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

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

• このバージョンは、/* /* Comments */ のような 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 型として登録された場合に、データベースがパラメーターの型を正しく推論できない問題が修正されました。