メインコンテンツまでスキップ
バージョン: 3.15
Features and pricing

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_millisSQL セッションファクトリのキャッシュの有効期限 (ミリ秒)。10000

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

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

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

ScalarDB タイプJDBC (Java) タイプ
BOOLEANboolean または Boolean
INTint または Integer
BIGINTlong または Long
FLOATfloat または Float
DOUBLEdouble または Double
TEXTString
BLOBbyte[]
DATEjava.time.LocalDate
TIMEjava.time.LocalTime
TIMESTAMPjava.time.LocalDateTime
TIMESTAMPTZjava.time.Instant

各データ型の 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>");
  
    // Get a DATE value of a column
  LocalDate dateValue = resultSet.getObject("<column name>", LocalDate.class);

  // Get a TIME value of a column
  LocalTime timeValue = resultSet.getObject("<column name>", LocalTime.class);

  // Get a TIMESTAMP value of a column
  LocalDateTime timestampValue = resultSet.getObject("<column name>", LocalDateTime.class);

  // Get a TIMESTAMPTZ value of a column
  Instant timestampTZValue = resultSet.getObject("<column name>", Instant.class);
}

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>);
  //Set a DATE value as parameter
  preparedStatement.setObject(9, <LocalDate value>);

  //Set a TIME value as parameter
  preparedStatement.setObject(10, <LocalTime value>);

  //Set a TIMESTAMP value as parameter
  preparedStatement.setObject(11, <LocalDateTime value>);

  //Set a TIMESTAMPTZ value as parameter
  preparedStatement.setObject(12, <Instant 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 ガイドも参照してください。

参考文献​