ScalarDB JDBC ガイド

ScalarDB JDBC の使用方法は、基本的に Java JDBC API に従います。 このガイドでは、ScalarDB JDBC に固有の重要なトピックをいくつか説明します。

プロジェクトに ScalarDB JDBC ドライバーを追加する

Gradle を使用して ScalarDB JDBC ドライバーの依存関係を追加するには、次を使用します。<VERSION> は、使用している ScalarDB JDBC ドライバーと関連ライブラリのバージョンに置き換えます。

dependencies {
    implementation 'com.scalar-labs:scalardb-sql-jdbc:<VERSION>'
    implementation 'com.scalar-labs:scalardb-cluster-java-client-sdk:<VERSION>'
}

Maven を使用して依存関係を追加するには、次のコマンドを使用します。... は、使用している ScalarDB JDBC ドライバーのバージョンに置き換えます。

<dependencies>
    <dependency>
        <groupId>com.scalar-labs</groupId>
        <artifactId>scalardb-sql-jdbc</artifactId>
        <version>...</version>
    </dependency>
    <dependency>
        <groupId>com.scalar-labs</groupId>
        <artifactId>scalardb-cluster-java-client-sdk</artifactId>
        <version>...</version>
    </dependency>
</dependencies>

JDBC 接続 URL

ScalarDB JDBC の JDBC 接続 URL 形式は次のとおりです。

jdbc:scalardb:<configuration file path>?<property name>=<property value>&<property name>=<property value>&...

例:

設定ファイルのパスのみを指定します:

jdbc:scalardb:/path/to/database.properties

プロパティのみを指定します:

jdbc:scalardb:?scalar.db.contact_points=localhost&scalar.db.username=cassandra&scalar.db.password=cassandra&scalar.db.storage=cassandra

設定ファイルのパスとプロパティを指定します。

jdbc:scalardb:/path/to/database.properties?scalar.db.metadata.cache_expiration_time_secs=0

ScalarDB JDBC の設定

設定の詳細については、ScalarDB Cluster SQL クライアント設定を参照してください。

さらに、ScalarDB JDBC 固有の設定は次のとおりです。

名前	説明	デフォルト
scalar.db.sql.jdbc.default_auto_commit	デフォルトの接続の自動コミットモード。	true
scalar.db.sql.jdbc.sql_session_factory_cache.expiration_time_millis	SQL セッションファクトリのキャッシュの有効期限 (ミリ秒)。	10000

ScalarDB と JDBC 間のデータ型マッピング

ScalarDB は JDBC で定義されているすべてのデータ型をサポートしているわけではないため、以下では ScalarDB と JDBC 間のデータ型マッピングについて説明します。

ScalarDB と JDBC 間のデータ型マッピングは次のとおりです。

ScalarDB タイプ	JDBC (Java) タイプ
BOOLEAN	boolean または Boolean
INT	int または Integer
BIGINT	long または Long
FLOAT	float または Float
DOUBLE	double または Double
TEXT	String
BLOB	byte[]

各データ型の java.sql.ResultSet オブジェクトからデータを取得する方法は次のとおりです。

try (ResultSet resultSet = ...) {
  resultSet.next();

  // Get a BOOLEAN value of a column
  boolean booleanValue = resultSet.getBoolean("<column name>");

  // Get an INT value of a column
  int intValue = resultSet.getInt("<column name>");

  // Get a BIGINT value of a column
  long bigIntValue = resultSet.getLong("<column name>");

  // Get a FLOAT value of a column
  float floatValue = resultSet.getFloat("<column name>");

  // Get a DOUBLE value of a column
  double doubleValue = resultSet.getDouble("<column name>");

  // Get a TEXT value of a column
  String textValue = resultSet.getString("<column name>");

  // Get a BLOB value of a column
  byte[] blobValue = resultSet.getBytes("<column name>");
}

java.sql.PreparedStatement オブジェクトの各データ型のパラメータとしてデータを設定する方法は次のとおりです。

try (PreparedStatement preparedStatement = ...) {
  // Set a BOOLEAN value as parameter
  preparedStatement.setBoolean(1, <BOOLEAN value>);

  // Set an INT value as parameter
  preparedStatement.setInt(2, <INT value>);

  // Set a BIGINT value as parameter
  preparedStatement.setLong(3, <BIGINT value>);

  // Set a FLOAT value as parameter
  preparedStatement.setFloat(4, <FLOAT value>);

  // Set a DOUBLE value as parameter
  preparedStatement.setDouble(5, <DOUBLE value>);

  // Set a TEXT value as parameter
  preparedStatement.setString(7, "<TEXT value>");

  // Set a BLOB value as parameter
  preparedStatement.setBytes(8, <BLOB value>);

  preparedStatement.execute();
}

SQLException の処理

例外処理は基本的に ScalarDB SQL API と同じです。

// If you execute multiple statements in a transaction, you need to set auto-commit to false.
connection.setAutoCommit(false);

try {
  // Execute statements (SELECT/INSERT/UPDATE/DELETE) in the transaction
  ...

  // Commit the transaction
  connection.commit();
} catch (SQLException e) {
  if (e.getErrorCode() == 301) {
    // The error code 301 indicates that you catch `UnknownTransactionStatusException`.
    // If you catch `UnknownTransactionStatusException`, it indicates that the status of the 
    // transaction, whether it has succeeded or not, is unknown. In such a case, you need to check
    // if the transaction is committed successfully or not and retry it if it failed. How to 
    // identify a transaction status is delegated to users
  } else {
    // For other cases, you can try retrying the transaction

    // Rollback the transaction
    connection.rollback();

    // The cause of the exception can be `TransactionRetryableException` or the other
    // exceptions. For `TransactionRetryableException`, you can basically retry the transaction.
    // However, for the other exceptions, the transaction may still fail if the cause of the
    // exception is nontransient. For such a case, you need to limit the number of retries and
    // give up retrying
  }
}

例外処理の詳細については、ScalarDB SQL API ガイドも参照してください。

参考文献

• Java JDBC API
• ScalarDB SQL API ガイド
• Javadoc for ScalarDB JDBC