Java API を使用した ScalarDB Cluster の開発者ガイド
このページは英語版のページが機械翻訳されたものです。英語版との間に矛盾または不一致がある場合は、英語版を正としてください。
ScalarDB Cluster は、アプリケーションを開発するための Java API を提供します。このドキュメントでは、Java API の使用方法を説明します。
ビルドに ScalarDB Cluster Java Client SDK を追加する
ScalarDB Cluster Java Client SDK は、Maven Central Repository で入手できます。
Gradle を使用して ScalarDB Cluster Java Client SDK への依存関係を追加するには、以下を使用します。<X.Y.Z> は使用したい ScalarDB Cluster Java Client SDK のバージョンに置き換えてください。
dependencies {
implementation 'com.scalar-labs:scalardb-cluster-java-client-sdk:<X.Y.Z>'
}
Maven を使用して依存関係を追加するには、以下を使用します。<X.Y.Z> は使用したい ScalarDB Cluster Java Client SDK のバージョンに置き換えてください。
<dependency>
<groupId>com.scalar-labs</groupId>
<artifactId>scalardb-cluster-java-client-sdk</artifactId>
<version><X.Y.Z></version>
</dependency>
クライアントモード
ScalarDB Cluster Java Client SDK は、indirect と direct-kubernetes の2つのクライアントモードをサポートしています。以下では、クライアントモードについて説明します。
indirect クライアントモード
このモードでは、単にリクエストを任意のクラスターノードに送信します (通常は Envoy などのロードバランサー経由)。リクエストを受信したクラスターノードは、トランザクション状態を持つ適切なクラスターノードにリクエストをルーティングします。
このモードの利点は、クライアントを軽量に保てることです。 欠点は、正しいクラスターノードに到達するために追加のホップが必要になり、パフォーマンスに影響する可能性があることです。
アプリケーションが別の Kubernetes クラスターで実行されていて、アプリケーションが Kubernetes API と各クラスターノードにアクセスできない場合でも、この接続モードを使用できます。
アプリケーションが ScalarDB Cluster ノードと同じ Kubernetes クラスターで実行されている場合は、direct-kubernetes クライアントモードを使用できます。
direct-kubernetes クライアントモード
このモードでは、クライアントはメンバーシップロジック (Kubernetes API を使用) と分散ロジック (コンシステントハッシュアルゴリズム) を使用して、トランザクション状態を持つ適切なクラスターノードを見つけます。次に、クライアントはクラスターノードに直接リクエストを送信します。
このモードの利点は、適切なクラスターノードに到達するためのホップ数を減らすことができるため、パフォーマンスが向上することです。このモードの欠点は、クライアントにメンバーシップロジックとリクエストルーティングロジックが必要なため、クライアントをファットにする必要があることです。
この接続モードは Kubernetes API と各クラスターノードにアクセスする必要があるため、アプリケーションが ScalarDB Cluster ノードと同じ Kubernetes クラスターで実行されている場合にのみ、この接続モードを使用できます。アプリケーションが別の Kubernetes クラスターで実行されている場合は、indirect クライアントモードを使用します。
direct-kubernetes クライアントモードで Kubernetes にアプリケーションをデプロイする方法の詳細については、direct-kubernetes モードを使用してクライアントアプリケーションを Kubernetes にデプロイする を参照してください。
Java API リファレンス
ScalarDB Cluster Java Client SDK は、アプリケーションが ScalarDB Cluster にアクセスするための Java API を提供します。次の図は、ScalarDB Cluster Java API のアーキテクチャを示しています。
+-----------------------+
| ユーザー/アプリケーション |
+-----------------------+
↓ Java API
+--------------+
| ScalarDB API |
+--------------+
↓ gRPC
+------------------+
| ScalarDB Cluster |
+------------------+
↓ DB ベンダー固有のプロトコル
+----+
| DB |
+----+
ScalarDB Cluster の詳細な Java API リファレンスは、ScalarDB Cluster Java API ガイド で入手できます。
次のセクションでは、ScalarDB Cluster Schema Loader について説明します。
ScalarDB Cluster Schema Loader
ScalarDB Cluster 経由でスキーマをロードするには、専用の ScalarDB Cluster Schema Loader を使用します。ScalarDB Cluster Schema Loader の使用方法は、成果物 (アーティファクト) の名前が異なることを除いて、ScalarDB Schema Loader の使用方法と同じです。
ScalarDB Cluster Schema Loader は、使用している ScalarDB Cluster のバージョンに一致するものを ScalarDB リリース からダウンロードし、次のように実行できます。<X.Y.Z> はそのバージョンに置き換えてください。
java -jar scalardb-cluster-schema-loader-<X.Y.Z>-all.jar --config <PATH_TO_SCALARDB_PROPERTIES_FILE> --schema-file <PATH_TO_SCHEMA_FILE> --coordinator
Scalar コンテナレジストリ のコンテナイメージを使用することもできます。<X.Y.Z> は使用したい ScalarDB Cluster Schema Loader のバージョンに置き換えてください:
docker run --rm -v <PATH_TO_YOUR_LOCAL_SCALARDB_PROPERTIES_FILE>:/scalardb.properties -v <PATH_TO_YOUR_LOCAL_SCHEMA_FILE>:/schema.json ghcr.io/scalar-labs/scalardb-cluster-schema-loader:<X.Y.Z> --config /scalardb.properties --schema-file /schema.json --coordinator
Java での ScalarDB Cluster SQL
ScalarDB Cluster は、JDBC および Spring Data JDBC for ScalarDB を介して、ScalarDB Cluster SQL への Java アクセスも提供します。次の図は、ScalarDB Cluster SQL へのアクセス方法を示しています。
+----------------------------------------------+
| ユーザー/アプリケーション |
+----------------------------------------------+
↓ ↓ Java API
Java API ↓ +-------------------------------+
(JDBC) ↓ | Spring Data JDBC for ScalarDB |
↓ +-------------------------------+
+----------------------------------------------+
| ScalarDB JDBC (ScalarDB SQL) |
+----------------------------------------------+
↓ gRPC
+----------------------+
| ScalarDB Cluster SQL |
+----------------------+
↓ DB ベンダー固有のプロトコル
+----+
| DB |
+----+
JDBC 経由の ScalarDB Cluster SQL
JDBC 経由での ScalarDB Cluster SQL の使用は、ScalarDB Cluster の依存関係を追加する必要がある点を除いて、ScalarDB JDBC を使用する場合とほぼ同じです。
Gradle を使用して依存関係を追加するには、以下を使用します。<X.Y.Z> は使用したい ScalarDB SQL JDBC ドライバーと ScalarDB Cluster Java Client SDK のバージョンに置き換えてください。
dependencies {
implementation 'com.scalar-labs:scalardb-sql-jdbc:<X.Y.Z>'
implementation 'com.scalar-labs:scalardb-cluster-java-client-sdk:<X.Y.Z>'
}
Maven を使用して依存関係を追加するには、以下を使用します。<X.Y.Z> は使用したい ScalarDB SQL JDBC ドライバーと ScalarDB Cluster Java Client SDK のバージョンに置き換えてください。
<dependencies>
<dependency>
<groupId>com.scalar-labs</groupId>
<artifactId>scalardb-sql-jdbc</artifactId>
<version><X.Y.Z></version>
</dependency>
<dependency>
<groupId>com.scalar-labs</groupId>
<artifactId>scalardb-cluster-java-client-sdk</artifactId>
<version><X.Y.Z></version>
</dependency>
</dependencies>
詳細については、ScalarDB JDBC ガイド を参照してください。
Spring Data JDBC for ScalarDB 経由の ScalarDB Cluster SQL
Spring Data JDBC for ScalarDB 経由での ScalarDB Cluster SQL の使用は、ScalarDB Cluster の依存関係を追加する必要がある点を除いて、Spring Data JDBC for ScalarDB を使用することとほぼ同じです。
Gradle を使用して依存関係を追加するには、以下を使用します。<X.Y.Z> は使用したい Spring Data JDBC for ScalarDB と ScalarDB Cluster Java Client SDK のバージョンに置き換えてください。
dependencies {
implementation 'com.scalar-labs:scalardb-sql-spring-data:<X.Y.Z>'
implementation 'com.scalar-labs:scalardb-cluster-java-client-sdk:<X.Y.Z>'
}
Maven を使用して依存関係を追加するには、以下を使用します。<X.Y.Z> は使用したい Spring Data JDBC for ScalarDB と ScalarDB Cluster Java Client SDK のバージョンに置き換 えてください。
<dependencies>
<dependency>
<groupId>com.scalar-labs</groupId>
<artifactId>scalardb-sql-spring-data</artifactId>
<version><X.Y.Z></version>
</dependency>
<dependency>
<groupId>com.scalar-labs</groupId>
<artifactId>scalardb-cluster-java-client-sdk</artifactId>
<version><X.Y.Z></version>
</dependency>
</dependencies>
詳細については、Spring Data JDBC for ScalarDB ガイド を参照してください。
ScalarDB Cluster SQL CLI
他の SQL データベースと同様に、ScalarDB SQL には、コマンドラインシェルで対話的に SQL ステートメントを発行できる CLI ツールが用意されています。
ScalarDB Cluster SQL CLI は、使用している ScalarDB Cluster のバージョンに一致するものを ScalarDB リリース からダウンロードし、次のように実行できます。<X.Y.Z> はそのバージョンに置き換えてください。
java -jar scalardb-cluster-sql-cli-<X.Y.Z>-all.jar --config <PATH_TO_SCALARDB_SQL_PROPERTIES_FILE>
Scalar コンテナレジストリ のコンテナイメージを使用することもできます。<X.Y.Z> は使用したい ScalarDB Cluster SQL CLI のバージョンに置き換えてください:
docker run --rm -it -v <PATH_TO_YOUR_LOCAL_SCALARDB_SQL_PROPERTIES_FILE>:/scalardb-sql.properties ghcr.io/scalar-labs/scalardb-cluster-sql-cli:<X.Y.Z> --config /scalardb-sql.properties
使用方法
CLI の使用方法は、次のように -h オプションを使用して確認できます。
java -jar scalardb-cluster-sql-cli-<X.Y.Z>-all.jar -h
Usage: scalardb-sql-cli [-hs] -c=PROPERTIES_FILE [-e=COMMAND] [-f=FILE]
[-l=LOG_FILE] [-o=<outputFormat>] [-p=PASSWORD]
[-u=USERNAME]
Starts ScalarDB SQL CLI.
-c, --config=PROPERTIES_FILE
A configuration file in properties format.
-e, --execute=COMMAND A command to execute.
-f, --file=FILE A script file to execute.
-h, --help Display this help message.
-l, --log=LOG_FILE A file to write output.
-o, --output-format=<outputFormat>
Format mode for result display. You can specify
table/vertical/csv/tsv/xmlattrs/xmlelements/json/a
nsiconsole.
-p, --password=PASSWORD A password to connect.
-s, --silent Reduce the amount of informational messages
displayed.
-u, --username=USERNAME A username to connect.
参考資料
Java 以外のプログラミング言語で ScalarDB Cluster を使用する場合は、ScalarDB Cluster gRPC API を使用できます。 詳細については、以下を参照してください。
Javadocs も利用可能です: