PolarDB:JDBC

JDBC ドライバーの構成

Java アプリケーションで JDBC ドライバーを使用するには、その JAR ファイルへのパスを CLASSPATH に追加します。例えば、JAR ファイルが /usr/local/polardb/share/java/ ディレクトリに保存されている場合、次のコマンドを実行してそのパスを CLASSPATH に追加します。

export CLASSPATH=$CLASSPATH:/usr/local/polardb/share/java/<jar-file-name.jar>

例：

export CLASSPATH=$CLASSPATH:/usr/local/polardb/share/java/polardb-jdbc18.jar

JDBC ドライバーのバージョンを確認するには、次のコマンドを実行します。

#java -jar <jar-file-name.jar>

例：

#java -jar polardb-jdbc18.jar
POLARDB JDBC Driver 42.2.XX.XX.0

PolarDB への接続

• [例]

  package com.aliyun.polardb;
  
  import java.sql.Connection;
  import java.sql.Driver;
  import java.sql.DriverManager;
  import java.sql.ResultSet;
  import java.sql.SQLException;
  import java.sql.Statement;
  import java.util.Properties;
  
  /**
   * POLARDB JDBC デモ
   * <p>
   * このデモを実行するホストの IP アドレスがクラスターのホワイトリストに含まれていることを確認してください。
   */
  public class PolarDBJdbcDemo {
    /**
     * 以下のプレースホルダー値を置き換えてください。
     */
    private final String host = "***.o.polardb.rds.aliyuncs.com";
    private final String user = "***";
    private final String password = "***";
    private final String port = "1521";
    private final String database = "db_name";
  
    public void run() throws Exception {
      Connection connect = null;
      Statement statement = null;
      ResultSet resultSet = null;
  
      try {
        Class.forName("com.aliyun.polardb.Driver");
  
        Properties props = new Properties();
        props.put("user", user);
        props.put("password", password);
        String url = "jdbc:polardb://" + host + ":" + port + "/" + database;
        connect = DriverManager.getConnection(url, props);
  
        /**
         * create table foo(id int, name varchar(20));
         */
        String sql = "select id, name from foo";
        statement = connect.createStatement();
        resultSet = statement.executeQuery(sql);
        while (resultSet.next()) {
          System.out.println("id:" + resultSet.getInt(1));
          System.out.println("name:" + resultSet.getString(2));
        }
      } catch (Exception e) {
        e.printStackTrace();
        throw e;
      } finally {
        try {
          if (resultSet != null)
            resultSet.close();
          if (statement != null)
            statement.close();
          if (connect != null)
            connect.close();
        } catch (SQLException e) {
          e.printStackTrace();
          throw e;
        }
      }
    }
  
    public static void main(String[] args) throws Exception {
      PolarDBJdbcDemo demo = new PolarDBJdbcDemo();
      demo.run();
    }
  }

• JDBC ドライバーの読み込み

  アプリケーションで次のコマンドを実行して、JDBC ドライバーを読み込みます。

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

• データベースへの接続

  JDBC では、接続 URL がデータベース接続を表します。例：

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

  パラメータ	例	説明
  URL プレフィックス	jdbc:polardb://	PolarDB への接続 URL プレフィックスは常に jdbc:polardb:// です。
  エンドポイント	pc-***.o.polardb.rds.aliyuncs.com	PolarDB クラスターのエンドポイントです。詳細については、「エンドポイントの表示または申請」をご参照ください。
  ポート	1521	PolarDB クラスターのポートです。デフォルトは 1521 です。
  データベース	polardb_test	接続先のデータベース名です。
  ユーザー名	test	PolarDB クラスターのユーザー名です。
  パスワード	Pw123456	PolarDB クラスターのユーザー名に対応するパスワードです。

• データのクエリと結果の処理

  クエリを実行するには、Statement、PreparedStatement、または CallableStatement オブジェクトを作成します。

  前述の例では Statement オブジェクトを使用しています。次の例では、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));
  }

  CallableStatement は、ストアドプロシージャの呼び出しに使用されます。次に例を示します。

  String sql = "{?=call getName (?, ?, ?)}";
  CallableStatement stmt = conn.prepareCall(sql);
  stmt.registerOutParameter(1, java.sql.Types.INTEGER);
  
  // 最初に IN パラメータをバインドし、次に OUT パラメータをバインドします
  int id = 100;
  stmt.setInt(2, id); // これにより ID が 100 に設定されます
  stmt.registerOutParameter(3, java.sql.Types.VARCHAR);
  stmt.registerOutParameter(4, java.sql.Types.INTEGER);
  
  // execute メソッドを使用してストアドプロシージャを実行します
  stmt.execute();
  
  // getXXX メソッドで名前を取得します
  String name = stmt.getString(3);
  Integer msgId = stmt.getInt(4);
  Integer result = stmt.getInt(1);
  System.out.println("Name with ID:" + id + " is " + name + ", and messageID is " + msgId + ", and return is " + result);

  前述のコードで使用されている getName ストアドプロシージャは、次のように定義されています。

  CREATE OR REPLACE FUNCTION getName(
      id        In      Integer,
      name      Out     Varchar2,
      result    Out     Integer
    ) Return Integer
  Is
    ret     Int;
  Begin
    ret := 0;
    name := 'Test';
    result := 1;
    Return(ret);
  End;

  説明

  カーソルを返すストアドプロシージャの場合、カーソルタイプは Java バージョンによって異なります。

  • Java 8 以降の場合は、Types.REF_CURSOR を使用します。

  • Java 8 より前のバージョンの場合は、Types.REF を使用します。

• フェッチサイズの設定

  デフォルトでは、ドライバーはデータベースからすべてのクエリ結果を一度に取得します。結果セットが大きい場合、これによりクライアント側で大量のメモリが消費され、Out of Memory (OOM) エラーが発生する可能性があります。これを防ぐために、JDBC はカーソルベースの ResultSet を提供しており、データをバッチで取得できます。この機能を使用するには、次の操作を行う必要があります。

  • FetchSize を設定します。FetchSize のデフォルト値は 0 で、すべてのデータが一度にフェッチされることを意味します。

  • 接続の autoCommit プロパティを false に設定します。

  // autocommit がオフになっていることを確認します
  conn.setAutoCommit(false);
  Statement st = conn.createStatement();
  
  // カーソルを使用するために fetchSize を設定します
  st.setFetchSize(50);
  ResultSet rs = st.executeQuery("SELECT * FROM mytable");
  while (rs.next())
  {
      System.out.print("a row was returned.");
  }
  rs.close();
  
  // カーソルをオフにするために fetchSize をリセットします
  st.setFetchSize(0);
  rs = st.executeQuery("SELECT * FROM mytable");
  while (rs.next())
  {
      System.out.print("many rows were returned.");
  }
  rs.close();
  
  // ステートメントを閉じます
  st.close();

Maven 統合

Java プロジェクトが Maven でビルドされている場合、次のコマンドを実行して PolarDB JDBC ドライバーパッケージをローカルリポジトリにインストールします。

mvn install:install-file -DgroupId=com.aliyun -DartifactId=<jar-file-name> -Dversion=1.1.2 -Dpackaging=jar -Dfile=/usr/local/polardb/share/java/<jar-file-name.jar>

例：

mvn install:install-file -DgroupId=com.aliyun -DartifactId=polardb-jdbc18 -Dversion=1.1.2 -Dpackaging=jar -Dfile=/usr/local/polardb/share/java/polardb-jdbc18.jar

Maven プロジェクトの pom.xml ファイルに次の依存関係を追加します。

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId><jar-file-name></artifactId>
    <version>1.1.2</version>
</dependency>

例：

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

Hibernate 統合

プロジェクトで Hibernate を使用している場合、PolarDB 用のドライバークラスと dialect を hibernate.cfg.xml ファイルで設定します。

<property name="connection.driver_class">com.aliyun.polardb.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 以降のバージョンは PolarDB ドライバーをサポートしています。driverClassName および dbtype パラメータを設定する必要はありません。

• Druid 1.1.24 より前のバージョンの場合、driverClassName および dbtype パラメータを明示的に設定する必要があります。

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

  説明

  Druid 1.1.24 より前のバージョンは PolarDB をネイティブにサポートしていないため、dbtype パラメータを postgresql に設定する必要があります。

Druid コネクションプールでデータベースパスワードを暗号化する必要がある場合は、「データベースパスワードの暗号化」をご参照ください。

Activiti 統合

アプリケーションでビジネスプロセス管理に Activiti フレームワークを使用している場合、PolarDB データソースを初期化する際に次のエラーが発生する可能性があります。

couldn't deduct database type from database product name 'POLARDB Database Compatible with Oracle'

このエラーは、Activiti に組み込まれているデータベース製品名からデータベースタイプへのマッピングに PolarDB のエントリが含まれていないために発生します。これを解決するには、SpringProcessEngineConfiguration のサブクラスを作成し、buildProcessEngine メソッドをオーバーライドしてデータベースタイプを明示的に指定します。次のコードに例を示します。

package com.aliyun.polardb;

import org.activiti.engine.ProcessEngine;
import org.activiti.spring.SpringProcessEngineConfiguration;

public class PolarDBSpringProcessEngineConfiguration extends SpringProcessEngineConfiguration {

    public PolarDBSpringProcessEngineConfiguration() {
        super();
    }

    @Override
    public ProcessEngine buildProcessEngine() {
        setDatabaseType(DATABASE_TYPE_POSTGRES);
        return super.buildProcessEngine();
    }
}

SpringProcessEngineConfiguration サブクラスをプロジェクトに配置します。次に、構成ファイルで、初期化時にこのクラスから構成を読み込むようにエンジンを設定します。次のコードに例を示します。

<bean id="processEngineConfiguration" class="com.aliyun.polardb.PolarDBSpringProcessEngineConfiguration">
      <property name="dataSource" ref="dataSource"/>
      <property name="transactionManager" ref="transactionManager"/>
      <property name="databaseSchemaUpdate" value="true"/>
      <!-- その他の構成はここでは省略されています。 -->
</bean>

Quartz 統合

org.quartz.jobStore.driverDelegateClass = org.quartz.impl.jdbcjobstore.PostgreSQLDelegate

WebSphere 統合

MyBatis 統合

MyBatis を使用する場合、databaseIdProvider を設定する必要がある場合があります。次のコードは、デフォルトの構成を示しています。

<databaseIdProvider type="DB_VENDOR">
  <property name="SQL Server" value="sqlserver"/>
  <property name="DB2" value="db2"/>
  <property name="Oracle" value="oracle" />
</databaseIdProvider>

databaseIdProvider は、[データベース製品名] から特定のエイリアスである databaseId へのマッピングを提供します。これにより、データベースのバージョン間で製品名が変更された場合でも、データベース製品名が同じエイリアスにマッピングされることが保証されます。

MyBatis XML マッピングファイルでは、SQL ステートメントに databaseId 属性を追加できます。これにより、そのステートメントは、その databaseId に一致するデータベースでのみ実行されます。MyBatis がマッピングファイルを読み込む際、一致する databaseId を持つステートメントと、databaseId 属性を持たないすべてのステートメントのみが読み込まれます。

  <property name="POLARDB" value="polardb" />

よくある質問

• Q：JDBC ドライバーを選択するにはどうすればよいですか。オープンソースコミュニティのドライバーを使用できますか。

  A：PolarDB はオープンソースの PostgreSQL をベースにしていますが、一部の機能にはドライバーレベルのサポートが必要です。したがって、公式の PolarDB JDBC ドライバーを使用することを推奨します。公式ドライバーのダウンロードページからダウンロードできます。

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

  A：いいえ。このドライバーは Maven 公開リポジトリでは利用できません。公式ウェブサイトから JAR ファイルをダウンロードし、Maven プロジェクトの場合は手動でローカルリポジトリにインストールする必要があります。

• Q：ドライバーのバージョン番号を確認するにはどうすればよいですか。

  A：java -jar <driver-name> コマンドを実行してバージョン番号を確認できます。

• Q：接続 URL は複数の IP アドレスとポートをサポートしていますか。

  A：はい、PolarDB JDBC ドライバーでは、次の例に示すように、接続 URL で複数のホストとポートのペアを指定できます。

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

  説明

  複数の IP アドレスを設定した場合、ドライバーは順番に接続を試みます。いずれの IP アドレスでも接続を確立できない場合、接続試行は失敗します。各試行のデフォルトの接続タイムアウトは 10 秒 (connectTimeout) です。タイムアウト期間を変更するには、接続文字列に connectTimeout パラメータを追加することで変更できます。

• Q：カーソルタイプを選択するにはどうすればよいですか。

  A：Java 1.8 より前の JDK バージョンの場合は Types.REF を使用します。Java 1.8 以降の場合は Types.REF_CURSOR を使用できます。

• Q：列名をデフォルトで大文字で返すことはできますか。

  A：はい。JDBC 接続文字列に oracleCase=true パラメータを追加すると、返されるすべての列名が大文字に変換されます。次に例を示します。

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