PolarDB:JDBC

JDBC ドライバーの設定

Java アプリケーションで JDBC ドライバーを使用する前に、JDBC ドライバーパッケージのパスを CLASSPATH に追加する必要があります。たとえば、JDBC ドライバーが /usr/local/polardb/share/java/ パスにある場合、次のコマンドを実行してドライバーパスを CLASSPATH に追加できます。

export CLASSPATH=$CLASSPATH:/usr/local/polardb/share/java/<jar_package_name.jar>

例：

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

次のコマンドを実行して、現在の JDBC バージョンを表示します。

#java -jar <jar_package_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 が 102 に設定されます
  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 messegeID 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 タイプを使用します。

• FetchSize の設定

  デフォルトでは、ドライバーはデータベースからすべてのデータを一度にフェッチします。大量のデータを含むクエリの場合、これによりクライアントのメモリが大量に消費され、メモリ不足 (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_package_name> -Dversion=1.1.2 -Dpackaging=jar -Dfile=/usr/local/polardb/share/java/<jar_package_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_package_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 を使用してデータベースに接続する場合は、hibernate.cfg.xml 構成ファイルで PolarDB データベースのドライバークラスとダイアレクトを設定します。

<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 ドライバーをネイティブにサポートしているため、driver name または dbtype パラメーターを設定する必要はありません。

• 1.1.24 より前のバージョンの Druid の場合は、次のように driver name と dbtype パラメーターを明示的に設定する必要があります。

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

  説明

  1.1.24 より前のバージョンの Druid は PolarDB をネイティブにサポートしていません。そのため、db-type を postgresql に設定する必要があります。

Druid 接続プールでデータベースのパスワードを暗号化する方法については、「データベースパスワードの暗号化」をご参照ください。

Activiti への対応

アプリケーションで Activiti ビジネスプロセス管理 (BPM) フレームワークを使用している場合、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 に対応するデータベースでのみ SQL 文が実行されるようになります。MyBatis が XML マッピングファイルをロードするとき、現在のデータベースと一致する databaseId を持つ SQL 文のみをロードします。databaseId 属性を持たない SQL 文は常にロードされます。

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

よくある質問

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

  A：PolarDB for PostgreSQL (Oracle 互換) はオープンソースの PostgreSQL をベースにしており、互換性のための多くの特徴が含まれています。これらの特徴の一部はドライバーレベルのサポートを必要とします。したがって、公式サイトからダウンロードできる公式の PolarDB JDBC ドライバーを使用することを推奨します。

• Q：PolarDB JDBC ドライバーはパブリック Maven リポジトリで利用できますか？

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

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

  A：java -jar driver_name コマンドを実行してバージョン番号を確認します。

• Q：URL に複数の IP アドレスとポートを設定できますか？

  A：はい、PolarDB for PostgreSQL (Oracle 互換) の JDBC ドライバーは、URL に複数の IP アドレスとポートを設定することをサポートしています。以下に例を示します。

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

  説明

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

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

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

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

  A：はい、できます。JDBC 接続文字列に oracleCase=true パラメーターを追加します。このパラメーターは、返される列名をデフォルトで大文字に変換します。以下に例を示します。

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