Hologres:JDBC

手順 1：ドライバーの依存関係の追加

多くの SQL クライアントツールには PostgreSQL ドライバーが組み込まれています。利用できる場合は、それを使用してください。Java アプリケーションの場合は、Maven プロジェクトに PostgreSQL JDBC Driver を追加します。jdbc.postgresql.org/download からダウンロードし、バージョン 42.3.2 以降 (最新の安定版を推奨) を使用してください。

Hologres は標準の PostgreSQL JDBC Driver を使用します。Hologres 専用のドライバーを別途インストールする必要はありません。

次の依存関係を pom.xml に追加します：

<dependencies>
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <!-- 42.3.2 以降を使用します。最新の安定版を推奨します。 -->
        <version>42.7.13</version>
    </dependency>
</dependencies>

手順 2：接続文字列の作成

接続文字列の形式は次のとおりです：

jdbc:postgresql://<ENDPOINT>:<PORT>/<DBNAME>?user=<ACCESS_ID>&password=<ACCESS_KEY>

必須パラメーター

オプションパラメーター

必要に応じて、これらを接続文字列に追加します。複数のパラメーターは & で区切ります。

preferQueryMode について

拡張プロトコルでは、PreparedStatement のパラメーターが明示的な型とともに送信され、ドライバーは暗黙の型変換を行いません。そのため、整数列を varchar パラメーターと比較すると、ERROR: operator does not exist: integer = character varying のようなエラーで失敗する場合があります。この型不一致エラーが発生した場合は、接続文字列に preferQueryMode=simple を追加してください。これにより、ドライバーは SQL をプレーンテキストとして送信し、サーバーがコンテキストからパラメーター型を推論します。

推奨オプションを有効化した接続文字列の例：

jdbc:postgresql://<ENDPOINT>:<PORT>/<DBNAME>?user=<ACCESS_ID>&password=<ACCESS_KEY>&ApplicationName=myApp&reWriteBatchedInserts=true

PreparedStatement クエリが、クエリパラメーターと列の型不一致により ERROR: operator does not exist: integer = character varying のようなエラーで失敗する場合は、接続文字列に preferQueryMode=simple を追加してください：

jdbc:postgresql://<ENDPOINT>:<PORT>/<DBNAME>?user=<ACCESS_ID>&password=<ACCESS_KEY>&preferQueryMode=simple

手順 3：環境変数への認証情報の格納

接続文字列に認証情報をハードコーディングすると、セキュリティリスクになります。代わりに環境変数に格納してください。Linux の場合は、次の内容を ~/.bash_profile に追加します：

export ALIBABA_CLOUD_USER=<ACCESS_ID>
export ALIBABA_CLOUD_PASSWORD=<ACCESS_KEY>

手順 4：接続してクエリを実行

次の例では、環境変数から認証情報を読み取り、タイムアウトプロパティを設定し、Hologres に接続して、標準の Statement を使用して基本的な SELECT クエリを実行します：

import org.postgresql.PGProperty;

import java.sql.*;
import java.util.Properties;

public class HologresTest {

    private void jdbcExample() throws SQLException {
        String user = System.getenv("ALIBABA_CLOUD_USER");
        String password = System.getenv("ALIBABA_CLOUD_PASSWORD");
        String url = String.format(
            "jdbc:postgresql://<ENDPOINT>:<PORT>/<DBNAME>?currentSchema=<SCHEMA_NAME>&user=%s&password=%s",
            user, password
        );
        Properties props = new Properties();
        // 実際のクエリ実行時間に基づいて SOCKET_TIMEOUT を設定し、
        // クエリ完了前にタイムアウトしないようにします。
        PGProperty.SOCKET_TIMEOUT.set(props, 3600);
        PGProperty.LOGIN_TIMEOUT.set(props, 60);
        PGProperty.TCP_KEEP_ALIVE.set(props, true);
        try (Connection conn = DriverManager.getConnection(url, props)) {
            try (Statement st = conn.createStatement()) {
                String sql = "SELECT pk, f1 FROM test_tb WHERE pk > 0 LIMIT 100";
                try (ResultSet rs = st.executeQuery(sql)) {
                    while (rs.next()) {
                        // 1 列目の値を読み取ります
                        String c1 = rs.getString(1);
                    }
                }
            }
        }
    }
}

データの書き込み

JDBC では、Statement またはプリペアドステートメントモードを使用してデータを書き込めます。書き込み操作にはプリペアドステートメントモードを使用してください。このモードでは、サーバーが SQL コンパイル結果をキャッシュするため、書き込みレイテンシが低減し、スループットが向上します。バッチサイズは 256 の倍数に設定してください。推奨される最小バッチサイズは 256 です。

このセクションの例では、次のテーブルを使用します。あらかじめデータベースに作成してください。

CREATE TABLE test_tb (
    pk int PRIMARY KEY,
    f1 text,
    f2 timestamptz,
    f3 double precision
);

バッチ挿入

import java.sql.Connection;
import java.sql.PreparedStatement;
import java.text.SimpleDateFormat;

/*
 * プリペアドステートメントモードでデータをバッチ書き込みします。
 * バッチサイズ：256 行（推奨される最小値）。
 */
private static void writeBatchWithPreparedStatement(Connection conn) throws Exception {
    try (PreparedStatement stmt = conn.prepareStatement("insert into test_tb values (?,?,?,?)")) {
        int batchSize = 256;
        for (int i = 0; i < batchSize; ++i) {
            stmt.setInt(1, 1000 + i);
            stmt.setString(2, "1");
            SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd hh:mm:ss");
            java.util.Date parsedDate = dateFormat.parse("1990-11-11 00:00:00");
            stmt.setTimestamp(3, new java.sql.Timestamp(parsedDate.getTime()));
            stmt.setDouble(4, 0.1);
            stmt.addBatch();
        }
        stmt.executeBatch();
    }
}

INSERT ON CONFLICT を使用した Upsert

競合時に既存行を更新するには、PostgreSQL の INSERT ON CONFLICT 構文を使用します。宛先テーブルにはプライマリキーが必要です。

import java.sql.Connection;
import java.sql.PreparedStatement;
import java.text.SimpleDateFormat;

private static void insertOverwrite(Connection conn) throws Exception {
    try (PreparedStatement stmt = conn.prepareStatement(
        "insert into test_tb values (?,?,?,?), (?,?,?,?), (?,?,?,?), (?,?,?,?), (?,?,?,?), (?,?,?,?) " +
        "on conflict(pk) do update set f1 = excluded.f1, f2 = excluded.f2, f3 = excluded.f3"
    )) {
        int batchSize = 6;
        for (int i = 0; i < batchSize; ++i) {
            stmt.setInt(i * 4 + 1, i);
            stmt.setString(i * 4 + 2, "1");
            SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd hh:mm:ss");
            java.util.Date parsedDate = dateFormat.parse("1990-11-11 00:00:00");
            stmt.setTimestamp(i * 4 + 3, new java.sql.Timestamp(parsedDate.getTime()));
            stmt.setDouble(i * 4 + 4, 0.1);
        }
        int affectedRows = stmt.executeUpdate();
        System.out.println("affected rows => " + affectedRows);
    }
}

次の例では、書き込み操作にプリペアドステートメントモードを使用し、繰り返しの INSERT でのスループットを向上させます：

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.SQLException;
import java.util.UUID;

private void jdbcPreparedStmtExample() throws SQLException {
    String user = System.getenv("ALIBABA_CLOUD_USER");
    String password = System.getenv("ALIBABA_CLOUD_PASSWORD");
    String url = String.format(
        "jdbc:postgresql://<ENDPOINT>:<PORT>/<DBNAME>?currentSchema=<SCHEMA_NAME>&user=%s&password=%s",
        user, password
    );
    try (Connection conn = DriverManager.getConnection(url)) {
        // 10行を1回の複数値INSERT文で挿入します。
        String sql = "insert into test_tb (pk, f1) values " +
                "(?, ?), (?, ?), (?, ?), (?, ?), (?, ?), " +
                "(?, ?), (?, ?), (?, ?), (?, ?), (?, ?)";
        try (PreparedStatement st = conn.prepareStatement(sql)) {
            for (int j = 0; j < 10; ++j) {
                // 一意のプライマリキーとランダムな文字列を設定します
                st.setInt(j * 2 + 1, 4000 + j);
                st.setString(j * 2 + 2, UUID.randomUUID().toString());
            }
            System.out.println("affected row => " + st.executeUpdate());
        }
    }
}

データのクエリ

Hologres のテーブルからデータをクエリするには、標準の SQL SELECT ステートメントを使用します。手順 4 の基本的な SELECT の例が、このパターンを示しています。

パラメーター化されたクエリには、プリペアドステートメントモードを使用し、列の型に一致する setter でパラメーターを渡してください：

import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;

private static void queryWithPreparedStatement(Connection conn) throws Exception {
    String sql = "select pk, f1, f2, f3 from test_tb where pk = ?";
    try (PreparedStatement stmt = conn.prepareStatement(sql)) {
        // pk は INT 列のため setInt を使用します。setString で String を渡すと
        // 拡張プロトコルでは次のエラーで失敗します：
        // ERROR: operator does not exist: integer = character varying
        stmt.setInt(1, 1000);
        try (ResultSet rs = stmt.executeQuery()) {
            while (rs.next()) {
                System.out.println(rs.getInt("pk") + ", " + rs.getString("f1"));
            }
        }
    }
}