diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/add-scalardb-to-your-build.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/add-scalardb-to-your-build.mdx new file mode 100644 index 00000000..5c6fdca7 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/add-scalardb-to-your-build.mdx @@ -0,0 +1,43 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# ビルドに ScalarDB を追加する + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +ScalarDB ライブラリは、[Maven Central Repository](https://mvnrepository.com/artifact/com.scalar-labs/scalardb) で入手できます。Gradle または Maven を使用して、ライブラリをビルド依存関係としてアプリケーションに追加できます。 + +## ビルドツールに基づいてアプリケーションを設定する + +ビルドツールを選択し、手順に従って ScalarDB のビルド依存関係をアプリケーションに追加します。 + + + + Gradle を使用して ScalarDB のビルド依存関係を追加するには、アプリケーションの `build.gradle` に次のコードを追加し、`` を使用する ScalarDB のバージョンに置き換えます。 + + ```gradle + dependencies { + implementation 'com.scalar-labs:scalardb:' + } + ``` + + + Maven を使用して ScalarDB のビルド依存関係を追加するには、アプリケーションの `pom.xml` に次のコードを追加し、`` を使用する ScalarDB のバージョンに置き換えます。 + + ```xml + + com.scalar-labs + scalardb + + + ``` + + diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/api-guide.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/api-guide.mdx new file mode 100644 index 00000000..75c9f6d0 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/api-guide.mdx @@ -0,0 +1,1621 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Java API ガイド + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +ScalarDB Java API は、主に管理 API とトランザクション API で設定されています。このガイドでは、どのような種類の API が存在するのか、それらの使用方法、例外の処理方法などの関連トピックについて簡単に説明します。 + +## Administrative API + +このセクションでは、ScalarDB の管理 API を使用してプログラムで管理操作を実行する方法について説明します。 + +:::note + +管理操作を実行する別の方法は、[Schema Loader](schema-loader.mdx) を使用することです。 + +::: + +### `DistributedTransactionAdmin` インスタンスを取得する + +管理操作を実行するには、まず `DistributedTransactionAdmin` インスタンスを取得する必要があります。 + +`DistributedTransactionAdmin` インスタンスを取得するには、次のように `TransactionFactory` を使用します。 + +```java +TransactionFactory transactionFactory = TransactionFactory.create(""); +DistributedTransactionAdmin admin = transactionFactory.getTransactionAdmin(); +``` + +設定の詳細については、[ScalarDB 設定](configurations.mdx)を参照してください。 + +すべての管理操作を実行したら、次のように `DistributedTransactionAdmin` インスタンスを閉じる必要があります。 + +```java +admin.close(); +``` + +### 名前空間を作成する + +テーブルは 1 つの名前空間に属するため、テーブルを作成する前に名前空間を作成する必要があります。 + +名前空間は次のように作成できます。 + +```java +// Create the namespace "ns". If the namespace already exists, an exception will be thrown. +admin.createNamespace("ns"); + +// Create the namespace only if it does not already exist. +boolean ifNotExists = true; +admin.createNamespace("ns", ifNotExists); + +// Create the namespace with options. +Map options = ...; +admin.createNamespace("ns", options); +``` + +#### 作成オプション + +名前空間の作成やテーブルの作成などの作成操作では、オプション名と値のマップであるオプション (`Map`) を指定できます。オプションを使用すると、ストレージアダプタ固有の設定ができます。 + +データベースを選択して、使用可能なオプションを確認します。 + + + + JDBC データベースには使用できるオプションはありません。 + + + | 名前 | 説明 | デフォルト | + |------------|-------------------------------------------------|------------| + | no-scaling | DynamoDB の自動スケーリングを無効にします。 | false | + | no-backup | DynamoDB の継続的なバックアップを無効にします。 | false | + | ru | 基本リソース単位。 | 10 | + + + | 名前 | 説明 | デフォルト | + |------------|--------------------------------------------------------|------------| + | ru | 基本リソース単位。 | 400 | + | no-scaling | Cosmos DB for NoSQL の自動スケーリングを無効にします。 | false | + + + | 名前 | 説明 | デフォルト | + |----------------------|----------------------------------------------------------------------------------------------------------|-------------------| + | replication-strategy | Cassandra レプリケーション戦略。`SimpleStrategy` または `NetworkTopologyStrategy` である必要があります。 | `SimpleStrategy` | + | compaction-strategy | Cassandra 圧縮戦略。`LCS`、`STCS`、または `TWCS` である必要があります。 | `STCS` | + | replication-factor | Cassandra の複製係数。 | 3 | + + + +### テーブルを作成する + +テーブルを作成するときは、テーブルメタデータを定義してからテーブルを作成する必要があります。 + +テーブルメタデータを定義するには、`TableMetadata` を使用できます。次の図は、テーブルの列、パーティションキー、クラスタリングキー (クラスタリング順序を含む)、およびセカンダリインデックスを定義する方法を示しています。 + +```java +// Define the table metadata. +TableMetadata tableMetadata = + TableMetadata.newBuilder() + .addColumn("c1", DataType.INT) + .addColumn("c2", DataType.TEXT) + .addColumn("c3", DataType.BIGINT) + .addColumn("c4", DataType.FLOAT) + .addColumn("c5", DataType.DOUBLE) + .addPartitionKey("c1") + .addClusteringKey("c2", Scan.Ordering.Order.DESC) + .addClusteringKey("c3", Scan.Ordering.Order.ASC) + .addSecondaryIndex("c4") + .build(); +``` + +ScalarDB のデータモデルの詳細については、[データモデル](design.mdx#データモデル)を参照してください。 + +次に、次のようにテーブルを作成します。 + +```java +// Create the table "ns.tbl". If the table already exists, an exception will be thrown. +admin.createTable("ns", "tbl", tableMetadata); + +// Create the table only if it does not already exist. +boolean ifNotExists = true; +admin.createTable("ns", "tbl", tableMetadata, ifNotExists); + +// Create the table with options. +Map options = ...; +admin.createTable("ns", "tbl", tableMetadata, options); +``` + +### セカンダリインデックスを作成する + +セカンダリインデックスは次のように作成できます。 + +```java +// Create a secondary index on column "c5" for table "ns.tbl". If a secondary index already exists, an exception will be thrown. +admin.createIndex("ns", "tbl", "c5"); + +// Create the secondary index only if it does not already exist. +boolean ifNotExists = true; +admin.createIndex("ns", "tbl", "c5", ifNotExists); + +// Create the secondary index with options. +Map options = ...; +admin.createIndex("ns", "tbl", "c5", options); +``` + +### テーブルに新しい列を追加する + +次のように、テーブルに新しい非パーティションキー列を追加できます。 + +```java +// Add a new column "c6" with the INT data type to the table "ns.tbl". +admin.addNewColumnToTable("ns", "tbl", "c6", DataType.INT) +``` + +:::warning + +テーブルに新しい列を追加する場合は、基盤となるストレージによって実行時間が大きく異なる可能性があるため、慎重に検討する必要があります。それに応じて計画を立て、特にデータベースが本番環境で実行されている場合は、次の点を考慮してください。 + +- **Cosmos DB for NoSQL および DynamoDB の場合:** テーブルスキーマは変更されないため、列の追加はほぼ瞬時に行われます。別のテーブルに格納されているテーブルメタデータのみが更新されます。 +- **Cassandra の場合:** 列を追加すると、スキーマメタデータのみが更新され、既存のスキーマレコードは変更されません。クラスタートポロジが実行時間の主な要因です。スキーマメタデータの変更は、ゴシッププロトコルを介して各クラスターノードに共有されます。このため、クラスターが大きいほど、すべてのノードが更新されるまでの時間が長くなります。 +- **リレーショナルデータベース (MySQL、Oracle など) の場合:** 列の追加は実行にそれほど時間がかかりません。 + +::: + +### テーブルを切り捨てる + +テーブルを切り捨てるには、次のようにします。 + +```java +// Truncate the table "ns.tbl". +admin.truncateTable("ns", "tbl"); +``` + +### セカンダリインデックスを削除する + +セカンダリインデックスは次のように削除できます。 + +```java +// Drop the secondary index on column "c5" from table "ns.tbl". If the secondary index does not exist, an exception will be thrown. +admin.dropIndex("ns", "tbl", "c5"); + +// Drop the secondary index only if it exists. +boolean ifExists = true; +admin.dropIndex("ns", "tbl", "c5", ifExists); +``` + +### テーブルを削除する + +テーブルを削除するには、次のようにします。 + +```java +// Drop the table "ns.tbl". If the table does not exist, an exception will be thrown. +admin.dropTable("ns", "tbl"); + +// Drop the table only if it exists. +boolean ifExists = true; +admin.dropTable("ns", "tbl", ifExists); +``` + +### 名前空間を削除する + +名前空間を削除するには、次のようにします。 + +```java +// Drop the namespace "ns". If the namespace does not exist, an exception will be thrown. +admin.dropNamespace("ns"); + +// Drop the namespace only if it exists. +boolean ifExists = true; +admin.dropNamespace("ns", ifExists); +``` + +### 既存の名前空間を取得する + +既存の名前空間は次のように取得できます。 + +```java +Set namespaces = admin.getNamespaceNames(); +``` + +### 名前空間のテーブルを取得する + +名前空間のテーブルは次のように取得できます。 + +```java +// Get the tables of the namespace "ns". +Set tables = admin.getNamespaceTableNames("ns"); +``` + +### テーブルメタデータを取得する + +テーブルメタデータは次のように取得できます。 + +```java +// Get the table metadata for "ns.tbl". +TableMetadata tableMetadata = admin.getTableMetadata("ns", "tbl"); +``` + +### 名前空間を修復する + +名前空間が不明な状態の場合 (たとえば、名前空間が基盤となるストレージに存在するが ScalarDB メタデータが存在しない、またはその逆)、このメソッドは必要に応じて名前空間とそのメタデータを再作成します。 + +名前空間は次のように修復できます。 + +```java +// Repair the namespace "ns" with options. +Map options = ...; +admin.repairNamespace("ns", options); +``` + +### テーブルを修復する + +テーブルが不明な状態の場合 (テーブルは基盤となるストレージに存在するが ScalarDB メタデータは存在しない、またはその逆)、このメソッドは必要に応じてテーブル、そのセカンダリインデックス、およびそのメタデータを再作成します。 + +テーブルは次のように修復できます。 + +```java +// Repair the table "ns.tbl" with options. +TableMetadata tableMetadata = + TableMetadata.newBuilder() + ... + .build(); +Map options = ...; +admin.repairTable("ns", "tbl", tableMetadata, options); +``` + +### 最新の ScalarDB API をサポートするように環境をアップグレードする + +ScalarDB API の最新バージョンをサポートするように ScalarDB 環境をアップグレードできます。通常、リリースノートに記載されているように、アプリケーション環境が使用する ScalarDB バージョンを更新した後、このメソッドを実行する必要があります。 + +```java +// Upgrade the ScalarDB environment. +Map options = ...; +admin.upgrade(options); +``` + +### Coordinator テーブルの操作を指定する + +Coordinator テーブルは、[Transactional API](#transactional-api) によってトランザクションのステータスを追跡するために使用されます。 + +トランザクションマネージャーを使用する場合は、トランザクションを実行するために Coordinator テーブルを作成する必要があります。テーブルの作成に加えて、Coordinator テーブルを切り捨てたり削除したりすることもできます。 + +#### Coordinator テーブルを作成する + +Coordinator テーブルは次のように作成できます。 + +```java +// Create the Coordinator table. +admin.createCoordinatorTables(); + +// Create the Coordinator table only if one does not already exist. +boolean ifNotExist = true; +admin.createCoordinatorTables(ifNotExist); + +// Create the Coordinator table with options. +Map options = ...; +admin.createCoordinatorTables(options); +``` + +#### Coordinator テーブルを切り捨てる + +Coordinator テーブルは次のように切り捨てることができます。 + +```java +// Truncate the Coordinator table. +admin.truncateCoordinatorTables(); +``` + +#### Coordinator テーブルを削除する + +Coordinator テーブルは次のように削除できます。 + +```java +// Drop the Coordinator table. +admin.dropCoordinatorTables(); + +// Drop the Coordinator table if one exist. +boolean ifExist = true; +admin.dropCoordinatorTables(ifExist); +``` + +### テーブルをインポートする + +既存のテーブルを ScalarDB にインポートするには、次のようにします。 + +```java +// Import the table "ns.tbl". If the table is already managed by ScalarDB, the target table does not +// exist, or the table does not meet the requirements of the ScalarDB table, an exception will be thrown. +admin.importTable("ns", "tbl", options); +``` + +:::warning + +運用環境で ScalarDB にテーブルをインポートする場合は、データベーステーブルと ScalarDB メタデータテーブルにトランザクションメタデータ列が追加されるため、慎重に計画する必要があります。この場合、データベースと ScalarDB の間にはいくつかの違いがあり、いくつかの制限もあります。詳細については、[ScalarDB Schema Loader を使用して既存のテーブルを ScalarDB にインポートする](./schema-loader-import.mdx)を参照してください。 + +::: + +## Transactional API + +このセクションでは、ScalarDB の Transactional API を使用してトランザクション操作を実行する方法について説明します。 + +### `DistributedTransactionManager` インスタンスを取得する + +トランザクション操作を実行するには、まず `DistributedTransactionManager` インスタンスを取得する必要があります。 + +`DistributedTransactionManager` インスタンスを取得するには、次のように `TransactionFactory` を使用します。 + +```java +TransactionFactory transactionFactory = TransactionFactory.create(""); +DistributedTransactionManager transactionManager = transactionFactory.getTransactionManager(); +``` + +すべてのトランザクション操作を実行した後、次のように `DistributedTransactionManager` インスタンスを閉じる必要があります。 + +```java +transactionManager.close(); +``` + +### トランザクションを実行する + +このサブセクションでは、複数の CRUD 操作でトランザクションを実行する方法について説明します。 + +#### トランザクションを開始する + +トランザクション CRUD 操作を実行する前に、トランザクションを開始する必要があります。 + +トランザクションは次のように開始できます。 + +```java +// Begin a transaction. +DistributedTransaction transaction = transactionManager.begin(); +``` + +または、次のようにトランザクションを開始することもできます。 + +```java +// Start a transaction. +DistributedTransaction transaction = transactionManager.start(); +``` + +あるいは、次のようにトランザクション ID を指定して、トランザクションに `begin` メソッドを使用することもできます。 + +```java +// Begin a transaction with specifying a transaction ID. +DistributedTransaction transaction = transactionManager.begin(""); +``` + +または、次のようにトランザクション ID を指定して、トランザクションに `start` メソッドを使用することもできます。 + +```java +// Start a transaction with specifying a transaction ID. +DistributedTransaction transaction = transactionManager.start(""); +``` + +:::note + +トランザクション ID を指定すると、外部システムを ScalarDB にリンクする場合に便利です。それ以外の場合は、`begin()` メソッドまたは `start()` メソッドを使用する必要があります。 + +トランザクション ID を指定する場合は、ScalarDB の正確性はトランザクション ID の一意性に依存するため、システム全体で一意の ID (UUID v4 など) を指定してください。 + +::: + +#### トランザクションに参加する + +トランザクションに参加することは、トランザクションが複数のクライアントリクエストにまたがるステートフルアプリケーションで特に便利です。このようなシナリオでは、アプリケーションは最初のクライアントリクエスト中にトランザクションを開始できます。その後、後続のクライアントリクエストで、アプリケーションは `join()` メソッドを使用して進行中のトランザクションに参加できます。 + +次のようにトランザクション ID を指定すると、すでに開始されている進行中のトランザクションに参加できます。 + +```java +// Join a transaction. +DistributedTransaction transaction = transactionManager.join(""); +``` + +:::note + +`getId()` を使用してトランザクション ID を取得するには、次のように指定します。 + +```java +tx.getId(); +``` + +::: + +#### トランザクションを再開する + +トランザクションの再開は、トランザクションが複数のクライアントリクエストにまたがるステートフルアプリケーションで特に役立ちます。このようなシナリオでは、アプリケーションは最初のクライアントリクエスト中にトランザクションを開始できます。その後、後続のクライアントリクエストで、アプリケーションは `resume()` メソッドを使用して進行中のトランザクションを再開できます。 + +次のようにトランザクション ID を指定すると、すでに開始した進行中のトランザクションを再開できます。 + +```java +// Resume a transaction. +DistributedTransaction transaction = transactionManager.resume(""); +``` + +:::note + +`getId()` を使用してトランザクション ID を取得するには、次のように指定します。 + +```java +tx.getId(); +``` + +::: + +#### CRUD 操作を実装する + +次のセクションでは、キーの構築と CRUD 操作について説明します。 + +:::note + +CRUD 操作のすべてのビルダーは `consistency()` メソッドを使用して一貫性を指定できますが、これらのメソッドは無視されます。代わりに、トランザクションでは常に `LINEARIZABLE` 一貫性レベルが使用されます。 + +::: + +##### キーの構築 + +ほとんどの CRUD 操作では、`Key` オブジェクト (パーティションキー、クラスタリングキーなど) を指定する必要があります。そのため、CRUD 操作に進む前に、`Key` オブジェクトの構築方法を次に説明します。 + +単一の列キーの場合、次のように `Key.of()` メソッドを使用してキーを構築できます。 + +```java +// For a key that consists of a single column of INT. +Key key1 = Key.ofInt("col1", 1); + +// For a key that consists of a single column of BIGINT. +Key key2 = Key.ofBigInt("col1", 100L); + +// For a key that consists of a single column of DOUBLE. +Key key3 = Key.ofDouble("col1", 1.3d); + +// For a key that consists of a single column of TEXT. +Key key4 = Key.ofText("col1", "value"); +``` + +2～5 列で設定されるキーの場合は、`Key.of()` メソッドを使用して次のようにキーを構築できます。Guava の `ImmutableMap.of()` と同様に、列名と値を順番に指定する必要があります。 + +```java +// For a key that consists of two to five columns. +Key key1 = Key.of("col1", 1, "col2", 100L); +Key key2 = Key.of("col1", 1, "col2", 100L, "col3", 1.3d); +Key key3 = Key.of("col1", 1, "col2", 100L, "col3", 1.3d, "col4", "value"); +Key key4 = Key.of("col1", 1, "col2", 100L, "col3", 1.3d, "col4", "value", "col5", false); +``` + +5 列を超えるキーの場合は、ビルダーを使用して次のようにキーを構築できます。 + +```java +// For a key that consists of more than five columns. +Key key = Key.newBuilder() + .addInt("col1", 1) + .addBigInt("col2", 100L) + .addDouble("col3", 1.3d) + .addText("col4", "value") + .addBoolean("col5", false) + .addInt("col6", 100) + .build(); +``` + +##### `Get` 操作 + +`Get` は、プライマリーキーで指定された単一のレコードを取得する操作です。 + +まず `Get` オブジェクトを作成し、次に次のように `transaction.get()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create a `Get` operation. +Key partitionKey = Key.ofInt("c1", 10); +Key clusteringKey = Key.of("c2", "aaa", "c3", 100L); + +Get get = + Get.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .projections("c1", "c2", "c3", "c4") + .where(ConditionBuilder.column("c1").isNotEqualToInt(10)) + .build(); + +// Execute the `Get` operation. +Optional result = transaction.get(get); +``` + +射影を指定して、返される列を選択できます。 + +###### `WHERE` 句を使用する + +`where()` メソッドを使用して任意の条件を指定することもできます。取得したレコードが `where()` メソッドで指定された条件と一致しない場合は、`Option.empty()` が返されます。`where()` メソッドの引数として、条件、AND 条件セット、または OR 条件セットを指定できます。`where()` メソッドを呼び出した後、次のように `and()` メソッドまたは `or()` メソッドを使用して、さらに条件または条件セットを追加できます。 + +```java +// Create a `Get` operation with condition sets. +Get get = + Get.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .where( + ConditionSetBuilder.condition(ConditionBuilder.column("c1").isLessThanInt(10)) + .or(ConditionBuilder.column("c1").isGreaterThanInt(20)) + .build()) + .and( + ConditionSetBuilder.condition(ConditionBuilder.column("c2").isLikeText("a%")) + .or(ConditionBuilder.column("c2").isLikeText("b%")) + .build()) + .build(); +``` + +:::note + +`where()` 条件メソッドチェーンでは、条件は上記の例のように `ConditionalExpression` または `OrConditionSet` の AND 結合 (結合正規形と呼ばれる)、または `ConditionalExpression` または `AndConditionSet` の OR 結合 (分離正規形と呼ばれる) である必要があります。 + +::: + +使用可能な条件と条件セットの詳細については、使用している ScalarDB バージョンの [Javadoc](https://javadoc.io/doc/com.scalar-labs/scalardb/latest/index.html) の `ConditionBuilder` および `ConditionSetBuilder` ページを参照してください。 + +###### `Result` オブジェクトの処理 + +`Get` 操作と `Scan` 操作は `Result` オブジェクトを返します。次に、`Result` オブジェクトの処理方法を示します。 + +次のように `get("")` メソッドを使用して、結果の列値を取得できます。 + +```java +// Get the BOOLEAN value of a column. +boolean booleanValue = result.getBoolean(""); + +// Get the INT value of a column. +int intValue = result.getInt(""); + +// Get the BIGINT value of a column. +long bigIntValue = result.getBigInt(""); + +// Get the FLOAT value of a column. +float floatValue = result.getFloat(""); + +// Get the DOUBLE value of a column. +double doubleValue = result.getDouble(""); + +// Get the TEXT value of a column. +String textValue = result.getText(""); + +// Get the BLOB value of a column as a `ByteBuffer`. +ByteBuffer blobValue = result.getBlob(""); + +// Get the BLOB value of a column as a `byte` array. +byte[] blobValueAsBytes = result.getBlobAsBytes(""); +``` + +列の値が null かどうかを確認する必要がある場合は、`isNull("")` メソッドを使用できます。 + +``` java +// Check if a value of a column is null. +boolean isNull = result.isNull(""); +``` + +詳細については、使用している ScalarDB のバージョンの [Javadoc](https://javadoc.io/doc/com.scalar-labs/scalardb/3.13.1/index.html) の `Result` ページを参照してください。 + +###### セカンダリインデックスを使用して `Get` を実行する + +セカンダリインデックスを使用して `Get` 操作を実行できます。 + +パーティションキーを指定する代わりに、次のようにインデックスキー (インデックス付き列) を指定してセカンダリインデックスを使用できます。 + +```java +// Create a `Get` operation by using a secondary index. +Key indexKey = Key.ofFloat("c4", 1.23F); + +Get get = + Get.newBuilder() + .namespace("ns") + .table("tbl") + .indexKey(indexKey) + .projections("c1", "c2", "c3", "c4") + .where(ConditionBuilder.column("c1").isNotEqualToInt(10)) + .build(); + +// Execute the `Get` operation. +Optional result = transaction.get(get); +``` + +`where()` メソッドを使用して任意の条件を指定することもできます。詳細については、[`WHERE` 句を使用する](#where-句を使用する)を参照してください。 + +:::note + +結果に複数のレコードがある場合、`transaction.get()` は例外をスローします。複数の結果を処理する場合は、[セカンダリインデックスを使用して `Scan` を実行する](#セカンダリインデックスを使用して-scan-を実行する)を参照してください。 + +::: + +##### `Scan` 操作 + +`Scan` は、パーティション内の複数のレコードを取得する操作です。`Scan` 操作では、クラスタリングキーの境界とクラスタリングキー列の順序を指定できます。 + +まず `Scan` オブジェクトを作成し、次に次のように `transaction.scan()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create a `Scan` operation. +Key partitionKey = Key.ofInt("c1", 10); +Key startClusteringKey = Key.of("c2", "aaa", "c3", 100L); +Key endClusteringKey = Key.of("c2", "aaa", "c3", 300L); + +Scan scan = + Scan.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .start(startClusteringKey, true) // Include startClusteringKey + .end(endClusteringKey, false) // Exclude endClusteringKey + .projections("c1", "c2", "c3", "c4") + .orderings(Scan.Ordering.desc("c2"), Scan.Ordering.asc("c3")) + .where(ConditionBuilder.column("c1").isNotEqualToInt(10)) + .limit(10) + .build(); + +// Execute the `Scan` operation. +List results = transaction.scan(scan); +``` + +クラスタリングキー境界を省略するか、`start` 境界または `end` 境界のいずれかを指定できます。`orderings` を指定しない場合は、テーブルの作成時に定義したクラスタリング順序で結果が並べられます。 + +さらに、`projections` を指定して返される列を選択し、`limit` を使用して `Scan` 操作で返されるレコードの数を指定できます。 + +###### `WHERE` 句を使用する + +`where()` メソッドを使用してスキャンされたレコードをフィルタリングすることで、任意の条件を指定することもできます。`where()` メソッドの引数として、条件、AND 条件セット、または OR 条件セットを指定できます。`where()` メソッドを呼び出した後、次のように `and()` メソッドまたは `or()` メソッドを使用して、さらに条件または条件セットを追加できます。 + +```java +// Create a `Scan` operation with condition sets. +Scan scan = + Scan.newBuilder() + .namespace("ns") + .table("tbl") + .all() + .where( + ConditionSetBuilder.condition(ConditionBuilder.column("c1").isLessThanInt(10)) + .or(ConditionBuilder.column("c1").isGreaterThanInt(20)) + .build()) + .and( + ConditionSetBuilder.condition(ConditionBuilder.column("c2").isLikeText("a%")) + .or(ConditionBuilder.column("c2").isLikeText("b%")) + .build()) + .limit(10) + .build(); +``` + +:::note + +`where()` 条件メソッドチェーンでは、条件は上記の例のように `ConditionalExpression` または `OrConditionSet` の AND 結合 (結合正規形と呼ばれる)、または `ConditionalExpression` または `AndConditionSet` の OR 結合 (分離正規形と呼ばれる) である必要があります。 + +::: + +使用可能な条件と条件セットの詳細については、使用している ScalarDB のバージョンの [Javadoc](https://javadoc.io/doc/com.scalar-labs/scalardb/latest/index.html) の `ConditionBuilder` および `ConditionSetBuilder` ページを参照してください。 + +###### セカンダリインデックスを使用して `Scan` を実行する + +セカンダリインデックスを使用して、`Scan` 操作を実行できます。 + +パーティションキーを指定する代わりに、次のようにインデックスキー (インデックス付き列) を指定してセカンダリインデックスを使用できます。 + +```java +// Create a `Scan` operation by using a secondary index. +Key indexKey = Key.ofFloat("c4", 1.23F); + +Scan scan = + Scan.newBuilder() + .namespace("ns") + .table("tbl") + .indexKey(indexKey) + .projections("c1", "c2", "c3", "c4") + .where(ConditionBuilder.column("c1").isNotEqualToInt(10)) + .limit(10) + .build(); + +// Execute the `Scan` operation. +List results = transaction.scan(scan); +``` + +`where()` メソッドを使用して任意の条件を指定することもできます。詳細については、[`WHERE` 句を使用する](#where-句を使用する)を参照してください。 + +:::note + +セカンダリインデックスを使用して、`Scan` でクラスタリングキーの境界と順序を指定することはできません。 + +::: + +###### パーティションキーを指定せずにクロスパーティション `Scan` を実行し、テーブルのすべてのレコードを取得します + +ScalarDB プロパティファイルで次の設定を有効にすると、パーティションキーを指定せずに、すべてのパーティションにわたって `Scan` 操作 (クロスパーティションスキャン* と呼びます) を実行できます。 + +```properties +scalar.db.cross_partition_scan.enabled=true +``` + +:::warning + +非 JDBC データベースの場合、`SERIALIZABLE` 分離レベルでクロスパーティションスキャンを有効にした場合でも、トランザクションは読み取りコミットスナップショット分離 (`SNAPSHOT`) で実行される可能性があります。これは、より低い分離レベルです。非 JDBC データベースを使用する場合は、トランザクションの一貫性が重要でない場合にのみ、クロスパーティションスキャンを使用してください。 + +::: + +ビルダーで `partitionKey()` メソッドを呼び出す代わりに、次のように `all()` メソッドを呼び出して、パーティションキーを指定せずにテーブルをスキャンできます。 + +```java +// Create a `Scan` operation without specifying a partition key. +Scan scan = + Scan.newBuilder() + .namespace("ns") + .table("tbl") + .all() + .projections("c1", "c2", "c3", "c4") + .limit(10) + .build(); + +// Execute the `Scan` operation. +List results = transaction.scan(scan); +``` + +:::note + +非 JDBC データベースを使用する場合、クロスパーティション `Scan` で順序を指定することはできません。フィルタリングまたは順序付けを指定したクロスパーティション `Scan` の使用方法の詳細については、[フィルタリングと順序付けを使用してパーティション間の `Scan` を実行する](#フィルタリングと順序付けを使用してパーティション間の-scan-を実行する)を参照してください。 + +::: + +###### フィルタリングと順序付けを使用してパーティション間の `Scan` を実行する + +次のようにフィルタリングと順序付けによるクロスパーティションスキャンオプションを有効にすると、柔軟な条件と順序付けでクロスパーティション `Scan` 操作を実行できます。 + +```properties +scalar.db.cross_partition_scan.enabled=true +scalar.db.cross_partition_scan.filtering.enabled=true +scalar.db.cross_partition_scan.ordering.enabled=true +``` + +:::note + +非 JDBC データベースでは `scalar.db.cross_partition_scan.ordering` を有効にすることはできません。 + +::: + +次のように、`all()` メソッドを呼び出した後に `where()` メソッドと `ordering()` メソッドを呼び出して、任意の条件と順序を指定できます。 + +```java +// Create a `Scan` operation with arbitrary conditions and orderings. +Scan scan = + Scan.newBuilder() + .namespace("ns") + .table("tbl") + .all() + .where(ConditionBuilder.column("c1").isNotEqualToInt(10)) + .projections("c1", "c2", "c3", "c4") + .orderings(Scan.Ordering.desc("c3"), Scan.Ordering.asc("c4")) + .limit(10) + .build(); + +// Execute the `Scan` operation. +List results = transaction.scan(scan); +``` + +`WHERE` 句の詳細については、[`WHERE` 句を使用する](#where-句を使用する)を参照してください。 + +##### `Put` 操作 + +:::note + +`Put` 操作は ScalarDB 3.13 以降では非推奨となり、将来のリリースでは削除される予定です。`Put` 操作の代わりに、`Insert` 操作、`Upsert` 操作、または `Update` 操作を使用してください。 + +::: + +`Put` は、プライマリーキーで指定されたレコードを配置する操作です。この操作はレコードの upsert 操作として動作し、レコードが存在する場合はレコードを更新し、レコードが存在しない場合はレコードを挿入します。 + +:::note + +既存のレコードを更新する場合、`Put` 操作を使用する前に `Get` または `Scan` を使用してレコードを読み取る必要があります。そうしないと、競合により操作が失敗します。これは、トランザクションを適切に管理するための ScalarDB の仕様により発生します。レコードを明示的に読み取る代わりに、暗黙的な事前読み取りを有効にできます。詳細については、[`Put` 操作の暗黙的な事前読み取りを有効にする](#put-操作の暗黙的な事前読み取りを有効にする)を参照してください。 + +::: + +まず `Put` オブジェクトを作成し、次に次のように `transaction.put()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create a `Put` operation. +Key partitionKey = Key.ofInt("c1", 10); +Key clusteringKey = Key.of("c2", "aaa", "c3", 100L); + +Put put = + Put.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .floatValue("c4", 1.23F) + .doubleValue("c5", 4.56) + .build(); + +// Execute the `Put` operation. +transaction.put(put); +``` + +次のように `null` 値を持つレコードを配置することもできます。 + +```java +Put put = + Put.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .floatValue("c4", null) + .doubleValue("c5", null) + .build(); +``` + +###### `Put` 操作の暗黙的な事前読み取りを有効にする + +Consensus Commit では、レコードが存在する場合、レコードの最新の状態を取得するために、アプリケーションは `Put` および `Delete` 操作でレコードを変更する前にレコードを読み取る必要があります。レコードを明示的に読み取る代わりに、*暗黙的な事前読み取り* を有効にすることができます。暗黙的な事前読み取りを有効にすると、アプリケーションがトランザクションでレコードを明示的に読み取らない場合は、ScalarDB がトランザクションをコミットする前にアプリケーションに代わってレコードを読み取ります。 + +`Put` 操作の暗黙的な事前読み取りを有効にするには、次のように `Put` 操作ビルダーで `enableImplicitPreRead()` を指定します。 + +```java +Put put = + Put.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .floatValue("c4", 1.23F) + .doubleValue("c5", 4.56) + .enableImplicitPreRead() + .build(); +``` + +:::note + +変更しようとしているレコードが存在しないことが確実な場合は、パフォーマンスを向上させるために、`Put` 操作の暗黙的な事前読み取りを有効にしないでください。たとえば、初期データをロードする場合は、暗黙的な事前読み取りを有効にしないでください。暗黙的な事前読み取りのない `Put` 操作は、暗黙的な事前読み取りのある `Put` 操作よりも高速です。これは、操作によって不要な読み取りがスキップされるためです。 + +::: + +##### `Insert` 操作 + +`Insert` は、トランザクションを通じて基礎となるストレージにエントリを挿入する操作です。エントリがすでに存在する場合は、競合エラーが発生します。 + +まず `Insert` オブジェクトを作成し、次に次のように `transaction.insert()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create an `Insert` operation. +Key partitionKey = Key.ofInt("c1", 10); +Key clusteringKey = Key.of("c2", "aaa", "c3", 100L); + +Insert insert = + Insert.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .floatValue("c4", 1.23F) + .doubleValue("c5", 4.56) + .build(); + +// Execute the `Insert` operation. +transaction.insert(insert); +``` + +##### `Upsert` 操作 + +`Upsert` は、トランザクションを通じて基礎となるストレージにエントリを挿入したり、エントリを更新したりする操作です。エントリがすでに存在する場合は更新され、そうでない場合はエントリが挿入されます。 + +まず `Upsert` オブジェクトを作成し、次に次のように `transaction.upsert()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create an `Upsert` operation. +Key partitionKey = Key.ofInt("c1", 10); +Key clusteringKey = Key.of("c2", "aaa", "c3", 100L); + +Upsert upsert = + Upsert.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .floatValue("c4", 1.23F) + .doubleValue("c5", 4.56) + .build(); + +// Execute the `Upsert` operation. +transaction.upsert(upsert); +``` + +##### `Update` 操作 + +`Update` は、トランザクションを通じて基礎となるストレージ内のエントリを更新する操作です。エントリが存在しない場合、操作によって変更は行われません。 + +まず `Update` オブジェクトを作成し、次に次のように `transaction.update()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create an `Update` operation. +Key partitionKey = Key.ofInt("c1", 10); +Key clusteringKey = Key.of("c2", "aaa", "c3", 100L); + +Update update = + Update.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .floatValue("c4", 1.23F) + .doubleValue("c5", 4.56) + .build(); + +// Execute the `Update` operation. +transaction.update(update); +``` + +##### `Delete` 操作 + +`Delete` は、プライマリーキーで指定されたレコードを削除する操作です。 + +:::note + +レコードを削除する場合、`Delete` 操作では暗黙的な事前読み取りが常に有効になっているため、事前にレコードを読み取る必要はありません。 + +::: + +まず `Delete` オブジェクトを作成し、次に次のように `transaction.delete()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create a `Delete` operation. +Key partitionKey = Key.ofInt("c1", 10); +Key clusteringKey = Key.of("c2", "aaa", "c3", 100L); + +Delete delete = + Delete.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .build(); + +// Execute the `Delete` operation. +transaction.delete(delete); +``` + +##### 条件付きの `Put`、`Delete`、`Update` + +トランザクション内で条件をチェックするロジックを実装することで、コミット前にトランザクションが満たす必要のある任意の条件 (たとえば、銀行口座の残高が 0 以上である必要がある) を記述できます。または、`Put`、`Delete`、`Update` などのミューテーション操作で単純な条件を記述することもできます。 + +`Put`、`Delete`、`Update` 操作に条件が含まれている場合、指定された条件が満たされた場合にのみ操作が実行されます。操作の実行時に条件が満たされていない場合は、`UnsatisfiedConditionException` という例外がスローされます。 + +:::note + +`Put` 操作で条件を指定する場合は、事前にレコードを読み取るか、暗黙的な事前読み取りを有効にする必要があります。 + +::: + +###### `Put` の条件 + +`Put` 操作では、次のように条件を指定できます。 + +```java +// Build a condition. +MutationCondition condition = + ConditionBuilder.putIf(ConditionBuilder.column("c4").isEqualToFloat(0.0F)) + .and(ConditionBuilder.column("c5").isEqualToDouble(0.0)) + .build(); + +Put put = + Put.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .floatValue("c4", 1.23F) + .doubleValue("c5", 4.56) + .condition(condition) // condition + .build(); + +// Execute the `Put` operation. +transaction.put(put); +``` + +`putIf` 条件を使用するだけでなく、次のように `putIfExists` 条件と `putIfNotExists` 条件を指定することもできます。 + +```java +// Build a `putIfExists` condition. +MutationCondition putIfExistsCondition = ConditionBuilder.putIfExists(); + +// Build a `putIfNotExists` condition. +MutationCondition putIfNotExistsCondition = ConditionBuilder.putIfNotExists(); +``` + +###### `Delete` の条件 + +`Delete` 操作では、次のように条件を指定できます。 + +```java +// Build a condition. +MutationCondition condition = + ConditionBuilder.deleteIf(ConditionBuilder.column("c4").isEqualToFloat(0.0F)) + .and(ConditionBuilder.column("c5").isEqualToDouble(0.0)) + .build(); + +Delete delete = + Delete.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .condition(condition) // condition + .build(); + +// Execute the `Delete` operation. +transaction.delete(delete); +``` + +`deleteIf` 条件を使用するだけでなく、次のように `deleteIfExists` 条件を指定することもできます。 + +```java +// Build a `deleteIfExists` condition. +MutationCondition deleteIfExistsCondition = ConditionBuilder.deleteIfExists(); +``` + +###### `Update` の条件 + +`Update` 操作では、次のように条件を指定できます。 + +```java +// Build a condition. +MutationCondition condition = + ConditionBuilder.updateIf(ConditionBuilder.column("c4").isEqualToFloat(0.0F)) + .and(ConditionBuilder.column("c5").isEqualToDouble(0.0)) + .build(); + +Update update = + Update.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .floatValue("c4", 1.23F) + .doubleValue("c5", 4.56) + .condition(condition) // condition + .build(); + +// Execute the `Update` operation. +transaction.update(update); +``` + +`updateIf` 条件を使用するだけでなく、次のように `updateIfExists` 条件を指定することもできます。 + +```java +// Build a `updateIfExists` condition. +MutationCondition updateIfExistsCondition = ConditionBuilder.updateIfExists(); +``` + +##### Mutate 操作 + +Mutate は、`Put`、`Insert`、`Upsert`、`Update`、`Delete` の複数の操作を実行する操作です。 + +まず Mutate オブジェクトを作成し、次に次のように `transaction.mutate()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create `Put` and `Delete` operations. +Key partitionKey = Key.ofInt("c1", 10); + +Key clusteringKeyForPut = Key.of("c2", "aaa", "c3", 100L); + +Put put = + Put.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKeyForPut) + .floatValue("c4", 1.23F) + .doubleValue("c5", 4.56) + .build(); + +Key clusteringKeyForDelete = Key.of("c2", "bbb", "c3", 200L); + +Delete delete = + Delete.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKeyForDelete) + .build(); + +// Execute the operations. +transaction.mutate(Arrays.asList(put, delete)); +``` + +##### CRUD 操作のデフォルト名前空間 + +すべての CRUD 操作のデフォルト名前空間は、ScalarDB 設定のプロパティを使用して設定できます。 + +```properties +scalar.db.default_namespace_name= +``` + +名前空間を指定しない操作では、設定されたデフォルトの名前空間が使用されます。 + +```java +// This operation will target the default namespace. +Scan scanUsingDefaultNamespace = + Scan.newBuilder() + .table("tbl") + .all() + .build(); +// This operation will target the "ns" namespace. +Scan scanUsingSpecifiedNamespace = + Scan.newBuilder() + .namespace("ns") + .table("tbl") + .all() + .build(); +``` + +#### トランザクションをコミットする + +CRUD 操作を実行した後、トランザクションをコミットして終了する必要があります。 + +トランザクションは次のようにコミットできます。 + +```java +// Commit a transaction. +transaction.commit(); +``` + +#### トランザクションをロールバックまたはアボートする + +トランザクションの実行中にエラーが発生した場合は、トランザクションをロールバックまたはアボートできます。 + +トランザクションは次のようにロールバックできます。 + +```java +// Roll back a transaction. +transaction.rollback(); +``` + +または、次のようにトランザクションをアボートすることもできます。 + +```java +// Abort a transaction. +transaction.abort(); +``` + +ScalarDB で例外を処理する方法の詳細については、[例外の処理方法](#例外の処理方法)を参照してください。 + +### トランザクションを開始せずにトランザクションを実行する + +トランザクションを開始せずにトランザクション操作を実行できます。この場合、ScalarDB は操作を実行する前に自動的にトランザクションを開始し、操作の実行後にトランザクションをコミットします。このセクションでは、トランザクションを開始せずにトランザクションを実行する方法について説明します。 + +#### `Get` 操作を実行する + +`Get` は、プライマリーキーで指定された単一のレコードを取得する操作です。 + +最初に `Get` オブジェクトを作成し、次に次のように `transactionManager.get()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create a `Get` operation. +Key partitionKey = Key.ofInt("c1", 10); +Key clusteringKey = Key.of("c2", "aaa", "c3", 100L); + +Get get = + Get.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .projections("c1", "c2", "c3", "c4") + .build(); + +// Execute the `Get` operation. +Optional result = transactionManager.get(get); +``` + +`Get` 操作の詳細については、[`Get` 操作](#get-操作)を参照してください。 + +#### `Scan` 操作の実行 + +`Scan` は、パーティション内の複数のレコードを取得する操作です。`Scan` 操作では、クラスタリングキーの境界とクラスタリングキー列の順序を指定できます。 + +まず `Scan` オブジェクトを作成し、次に次のように `transactionManager.scan()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create a `Scan` operation. +Key partitionKey = Key.ofInt("c1", 10); +Key startClusteringKey = Key.of("c2", "aaa", "c3", 100L); +Key endClusteringKey = Key.of("c2", "aaa", "c3", 300L); + +Scan scan = + Scan.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .start(startClusteringKey, true) // Include startClusteringKey + .end(endClusteringKey, false) // Exclude endClusteringKey + .projections("c1", "c2", "c3", "c4") + .orderings(Scan.Ordering.desc("c2"), Scan.Ordering.asc("c3")) + .limit(10) + .build(); + +// Execute the `Scan` operation. +List results = transactionManager.scan(scan); +``` + +`Scan` 操作の詳細については、[`Scan` 操作](#scan-操作)を参照してください。 + +#### `Put` 操作を実行します + +:::note + +`Put` 操作は ScalarDB 3.13 以降では非推奨となり、将来のリリースでは削除される予定です。`Put` 操作の代わりに、`Insert` 操作、`Upsert` 操作、または `Update` 操作を使用してください。 + +::: + +まず `Put` オブジェクトを作成し、次に次のように `transactionManager.put()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create a `Put` operation. +Key partitionKey = Key.ofInt("c1", 10); +Key clusteringKey = Key.of("c2", "aaa", "c3", 100L); + +Put put = + Put.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .floatValue("c4", 1.23F) + .doubleValue("c5", 4.56) + .build(); + +// Execute the `Put` operation. +transactionManager.put(put); +``` + +`Put` 操作の詳細については、[`Put` 操作](#put-操作)を参照してください。 + +#### `Insert` 操作の実行 + +`Insert` は、トランザクションを通じて基礎となるストレージにエントリを挿入する操作です。エントリがすでに存在する場合は、競合エラーが発生します。 + +まず `Insert` オブジェクトを作成し、次に次のように `transactionManager.insert()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create an `Insert` operation. +Key partitionKey = Key.ofInt("c1", 10); +Key clusteringKey = Key.of("c2", "aaa", "c3", 100L); + +Insert insert = + Insert.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .floatValue("c4", 1.23F) + .doubleValue("c5", 4.56) + .build(); + +// Execute the `Insert` operation. +transactionManager.insert(insert); +``` + +`Insert` 操作の詳細については、[`Insert` 操作](#insert-操作)を参照してください。 + +#### `Upsert` 操作を実行する + +`Upsert` は、トランザクションを通じて基礎となるストレージにエントリを挿入するか、エントリを更新する操作です。エントリがすでに存在する場合は更新され、そうでない場合はエントリが挿入されます。 + +まず `Upsert` オブジェクトを作成し、次に次のように `transactionManager.upsert()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create an `Upsert` operation. +Key partitionKey = Key.ofInt("c1", 10); +Key clusteringKey = Key.of("c2", "aaa", "c3", 100L); + +Upsert upsert = + Upsert.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .floatValue("c4", 1.23F) + .doubleValue("c5", 4.56) + .build(); + +// Execute the `Upsert` operation. +transactionManager.upsert(upsert); +``` + +`Insert` 操作の詳細については、[`Upsert` 操作](#upsert-操作)を参照してください。 + +#### `Update` 操作の実行 + +`Update` は、トランザクションを通じて基礎となるストレージ内のエントリを更新する操作です。エントリが存在しない場合、操作によって変更は行われません。 + +まず `Update` オブジェクトを作成し、次に次のように `transactionManager.update()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create an `Update` operation. +Key partitionKey = Key.ofInt("c1", 10); +Key clusteringKey = Key.of("c2", "aaa", "c3", 100L); + +Update update = + Update.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .floatValue("c4", 1.23F) + .doubleValue("c5", 4.56) + .build(); + +// Execute the `Update` operation. +transactionManager.update(update); +``` + +`Update` 操作の詳細については、[`Update` 操作](#update-操作)を参照してください。 + +#### `Delete` 操作を実行する + +`Delete` は、プライマリーキーで指定されたレコードを削除する操作です。 + +まず `Delete` オブジェクトを作成し、次に次のように `transaction.delete()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create a `Delete` operation. +Key partitionKey = Key.ofInt("c1", 10); +Key clusteringKey = Key.of("c2", "aaa", "c3", 100L); + +Delete delete = + Delete.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .build(); + +// Execute the `Delete` operation. +transactionManager.delete(delete); +``` + +`Delete` 操作の詳細については、[`Delete` 操作](#delete-操作)を参照してください。 + +#### Mutate 操作の実行 + +Mutate は、複数のミューテーション (`Put`、`Insert`、`Upsert`、`Update`、および `Delete` 操作) を実行する操作です。 + +まずミューテーションオブジェクトを作成し、次に次のように `transactionManager.mutate()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create `Put` and `Delete` operations. +Key partitionKey = Key.ofInt("c1", 10); + +Key clusteringKeyForPut = Key.of("c2", "aaa", "c3", 100L); + +Put put = + Put.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKeyForPut) + .floatValue("c4", 1.23F) + .doubleValue("c5", 4.56) + .build(); + +Key clusteringKeyForDelete = Key.of("c2", "bbb", "c3", 200L); + +Delete delete = + Delete.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKeyForDelete) + .build(); + +// Execute the operations. +transactionManager.mutate(Arrays.asList(put, delete)); +``` + +Mutate 操作の詳細については、[Mutate 操作](#mutate-操作)を参照してください。 + +また、ScalarDB での例外の処理方法の詳細については、[例外の処理方法](#例外の処理方法)を参照してください。 + +## 例外の処理方法 + +トランザクションを実行するときは、例外も適切に処理する必要があります。 + +:::warning + +例外を適切に処理しないと、異常やデータの不整合が発生する可能性があります。 + +::: + +次のサンプルコードは、例外を処理する方法を示しています。 + +```java +public class Sample { + public static void main(String[] args) throws Exception { + TransactionFactory factory = TransactionFactory.create(""); + DistributedTransactionManager transactionManager = factory.getTransactionManager(); + + int retryCount = 0; + TransactionException lastException = null; + + while (true) { + if (retryCount++ > 0) { + // Retry the transaction three times maximum. + if (retryCount >= 3) { + // Throw the last exception if the number of retries exceeds the maximum. + throw lastException; + } + + // Sleep 100 milliseconds before retrying the transaction. + TimeUnit.MILLISECONDS.sleep(100); + } + + DistributedTransaction transaction = null; + try { + // Begin a transaction. + transaction = transactionManager.begin(); + + // Execute CRUD operations in the transaction. + Optional result = transaction.get(...); + List results = transaction.scan(...); + transaction.put(...); + transaction.delete(...); + + // Commit the transaction. + transaction.commit(); + } catch (UnsatisfiedConditionException e) { + // You need to handle `UnsatisfiedConditionException` only if a mutation operation specifies a condition. + // This exception indicates the condition for the mutation operation is not met. + + try { + transaction.rollback(); + } catch (RollbackException ex) { + // Rolling back the transaction failed. Since the transaction should eventually recover, + // you don't need to do anything further. You can simply log the occurrence here. + } + + // You can handle the exception here, according to your application requirements. + + return; + } catch (UnknownTransactionStatusException e) { + // If you catch `UnknownTransactionStatusException` when committing the transaction, + // it indicates that the status of the transaction, whether it was successful or not, is unknown. + // In such a case, you need to check if the transaction is committed successfully or not and + // retry the transaction if it failed. How to identify a transaction status is delegated to users. + return; + } catch (TransactionException e) { + // For other exceptions, you can try retrying the transaction. + + // For `CrudConflictException`, `CommitConflictException`, and `TransactionNotFoundException`, + // you can basically retry the transaction. However, for the other exceptions, the transaction + // will still fail if the cause of the exception is non-transient. In such a case, you will + // exhaust the number of retries and throw the last exception. + + if (transaction != null) { + try { + transaction.rollback(); + } catch (RollbackException ex) { + // Rolling back the transaction failed. The transaction should eventually recover, + // so you don't need to do anything further. You can simply log the occurrence here. + } + } + + lastException = e; + } + } + } +} +``` + +### `TransactionException` および `TransactionNotFoundException` + +`begin()` API は `TransactionException` または `TransactionNotFoundException` をスローする可能性があります: + +- `TransactionException` をキャッチした場合、この例外は、一時的または非一時的障害が原因でトランザクションを開始できなかったことを示します。トランザクションを再試行することはできますが、非一時的障害が原因でトランザクションを開始できない可能性があります。 +- `TransactionNotFoundException` をキャッチした場合、この例外は、一時的障害が原因でトランザクションを開始できなかったことを示します。この場合、トランザクションを再試行できます。 + +`join()` API も `TransactionNotFoundException` をスローする可能性があります。この例外は、`begin()` API の例外を処理するのと同じ方法で処理できます。 + +### `CrudException` および `CrudConflictException` + +CRUD 操作の API (`get()`、`scan()`、`put()`、`delete()`、および `mutate()`) は、`CrudException` または `CrudConflictException` をスローする可能性があります: + +- `CrudException` をキャッチした場合、この例外は、一時的または非一時的障害が原因でトランザクション CRUD 操作が失敗したことを示します。トランザクションを最初から再試行できますが、原因が非一時的である場合は、トランザクションが失敗する可能性があります。 +- `CrudConflictException` をキャッチした場合、この例外は、一時的な障害 (競合エラーなど) が原因でトランザクション CRUD 操作が失敗したことを示します。この場合、トランザクションを最初から再試行できます。 + +### `UnsatisfiedConditionException` + +ミューテーション操作の API (`put()`、`delete()`、および `mutate()`) も `UnsatisfiedConditionException` をスローする可能性があります。 + +`UnsatisfiedConditionException` をキャッチした場合、この例外はミューテーション操作の条件が満たされていないことを示します。この例外は、アプリケーションの要件に従って処理できます。 + +### `CommitException`、`CommitConflictException`、および `UnknownTransactionStatusException` + +`commit()` API は `CommitException`、`CommitConflictException`、または `UnknownTransactionStatusException` をスローする可能性があります。 + +- `CommitException` をキャッチした場合、この例外は、一時的または非一時的障害が原因でトランザクションのコミットが失敗したことを示します。トランザクションを最初から再試行できますが、原因が非一時的である場合はトランザクションが失敗する可能性があります。 +- `CommitConflictException` をキャッチした場合、この例外は、一時的な障害 (競合エラーなど) が原因でトランザクションのコミットが失敗したことを示します。この場合、トランザクションを最初から再試行できます。 +- `UnknownTransactionStatusException` をキャッチした場合、この例外は、トランザクションのステータス (成功したかどうか) が不明であることを示します。この場合、トランザクションが正常にコミットされたかどうかを確認し、失敗した場合はトランザクションを再試行する必要があります。 + +トランザクションステータスを識別する方法は、ユーザーに委任されています。トランザクションステータステーブルを作成し、他のアプリケーションデータを使用してトランザクション的に更新して、ステータステーブルからトランザクションのステータスを取得できるようにすることができます。 + +### 一部の例外に関する注意 + +サンプルコードには示されていませんが、`resume()` API は `TransactionNotFoundException` をスローする可能性もあります。この例外は、指定された ID に関連付けられたトランザクションが見つからなかったか、トランザクションの有効期限が切れた可能性があることを示します。いずれの場合も、この例外の原因は基本的に一時的なものであるため、トランザクションを最初から再試行できます。 + +サンプルコードでは、`UnknownTransactionStatusException` の場合、重複操作の可能性を回避するためにアプリケーションがトランザクションが成功したかどうかを確認する必要があるため、トランザクションは再試行されません。その他の例外の場合、例外の原因が一時的または非一時的であるため、トランザクションは再試行されます。例外の原因が一時的な場合、再試行するとトランザクションが成功する可能性があります。ただし、例外の原因が非一時的である場合、再試行してもトランザクションは失敗します。このような場合、再試行回数を使い果たします。 + +:::note + +サンプルコードでは、トランザクションは最大 3 回再試行され、再試行される前に 100 ミリ秒間スリープします。ただし、アプリケーションの要件に応じて、指数バックオフなどの再試行ポリシーを選択できます。 + +::: + +## Coordinator テーブルのグループコミット + +Consensus Commit トランザクションに使用される Coordinator テーブルは重要なデータストアであり、堅牢なストレージを使用することをお勧めします。ただし、内部でマルチ AZ またはマルチリージョンレプリケーションを活用するなど、より堅牢なストレージオプションを使用すると、ストレージにレコードを書き込むときにレイテンシが増加し、スループットパフォーマンスが低下する可能性があります。 + +ScalarDB は、Coordinator テーブルにグループコミット機能を提供します。この機能は、複数のレコードの書き込みを 1 つの書き込み操作にグループ化し、書き込みスループットを向上させます。この場合、基盤となるデータベースとワークロードに応じて、レイテンシが増加または減少する可能性があります。 + +グループコミット機能を有効にするには、次の設定を追加します。 + +```properties +# By default, this configuration is set to `false`. +scalar.db.consensus_commit.coordinator.group_commit.enabled=true + +# These properties are for tuning the performance of the group commit feature. +# scalar.db.consensus_commit.coordinator.group_commit.group_size_fix_timeout_millis=40 +# scalar.db.consensus_commit.coordinator.group_commit.delayed_slot_move_timeout_millis=800 +# scalar.db.consensus_commit.coordinator.group_commit.old_group_abort_timeout_millis=30000 +# scalar.db.consensus_commit.coordinator.group_commit.timeout_check_interval_millis=10 +# scalar.db.consensus_commit.coordinator.group_commit.metrics_monitor_log_enabled=true +``` + +### 制限事項 + +このセクションでは、グループコミット機能の制限事項について説明します。 + +#### ユーザーが渡したカスタムトランザクション ID + +グループコミット機能は、内部値を暗黙的に生成し、それをトランザクション ID の一部として使用します。したがって、ユーザーが `com.scalar.db.transaction.consensuscommit.ConsensusCommitManager.begin(String txId)` または `com.scalar.db.transaction.consensuscommit.TwoPhaseConsensusCommitManager.begin(String txId)` を介して手動で渡したカスタムトランザクション ID は、その後の API 呼び出しでそのまま使用することはできません。代わりに、`com.scalar.db.transaction.consensuscommit.ConsensusCommit.getId()` または `com.scalar.db.transaction.consensuscommit.TwoPhaseConsensusCommit.getId()` から返されたトランザクション ID を使用する必要があります。 + +```java + // This custom transaction ID needs to be used for ScalarDB transactions. + String myTxId = UUID.randomUUID().toString(); + + ... + + DistributedTransaction transaction = manager.begin(myTxId); + + ... + + // When the group commit feature is enabled, a custom transaction ID passed by users can't be used as is. + // logger.info("The transaction state: {}", manager.getState(myTxId)); + logger.info("The transaction state: {}", manager.getState(transaction.getId())); +``` + +#### 2 フェーズコミットインターフェースでの使用の禁止 + +グループコミット機能は、進行中のすべてのトランザクションをメモリ内で管理します。この機能が 2 フェーズコミットインターフェースで有効になっている場合、Coordinator テーブルへの参加者サービスの一貫性のない書き込みによって生じる競合 (グループ間で異なるトランザクション分散が含まれる場合があります) を防ぐために、情報は Coordinator サービスによってのみ維持される必要があります。 + +この制限により、アプリケーション開発に関連する複雑さと柔軟性が損なわれます。したがって、グループコミット機能と 2 フェーズコミットインターフェースを組み合わせて使用​​することは現在禁止されています。 + +## Consensus Commit トランザクションマネージャーエラーの調査 + +Consensus Commit トランザクションマネージャーの使用時にエラーを調査するには、トランザクションメタデータ列が追加されたテーブルメタデータを返す設定を有効にできます。これは、トランザクション関連の問題を調査するときに役立ちます。この設定は、Consensus Commit トランザクションマネージャーのトラブルシューティング時にのみ使用可能で、`DistributedTransactionAdmin.getTableMetadata()` メソッドを使用して、特定のテーブルのトランザクションメタデータ列の詳細を表示できます。 + +次の設定を追加すると、`Get` および `Scan` 操作の結果に [トランザクションメタデータ](schema-loader.mdx#consensus-commit-の内部メタデータ)が含まれます。 + +```properties +# By default, this configuration is set to `false`. +scalar.db.consensus_commit.include_metadata.enabled=true +``` diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/backup-restore.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/backup-restore.mdx new file mode 100644 index 00000000..f97ba2f6 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/backup-restore.mdx @@ -0,0 +1,180 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB で使用されるデータベースのバックアップと復元方法 + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +ScalarDB は非トランザクションデータベースまたはトランザクションデータベース上で非侵入的にトランザクション機能を提供するため、トランザクション的に一貫性のある方法でデータベースをバックアップおよび復元するには特別な注意が必要です。 + +このガイドでは、ScalarDB がサポートするデータベースをバックアップおよび復元する方法について説明します。 + +## バックアップを作成する + +バックアップの作成方法は、使用しているデータベースと、複数のデータベースを使用しているかどうかによって異なります。次の決定ツリーは、どのアプローチを取るべきかを示しています。 + +```mermaid +flowchart TD + A[ScalarDB で単一のデータベースを使用していますか?] + A -->|はい| B[データベースはトランザクションをサポートしていますか?] + B -->|はい| C[明示的に一時停止せずにバックアップを実行します] + B ---->|いいえ| D[明示的な一時停止を伴うバックアップを実行します] + A ---->|いいえ| D +``` + +### 明示的に一時停止せずにバックアップする + +トランザクションをサポートする単一のデータベースで ScalarDB を使用している場合は、ScalarDB がトランザクションを受け入れ続けている間でも、データベースのバックアップを作成できます。 + +:::warning + +バックアップを作成する前に、データベースのトランザクション的に一貫性のあるバックアップを作成する最も安全な方法を検討し、バックアッププロセスに関連するリスクを理解する必要があります。 + +::: + +ScalarDB でバックアップを作成するための要件の 1 つは、ScalarDB が管理するすべてのテーブル (Coordinator テーブルを含む) のバックアップがトランザクション的に一貫しているか、トランザクション的に一貫した状態に自動的に回復可能である必要があることです。つまり、すべてのテーブルを 1 回のトランザクションでダンプして、一貫性のあるバックアップを作成する必要があります。 + +トランザクション的に一貫性のあるバックアップを作成する方法は、使用しているデータベースの種類によって異なります。データベースを選択して、ScalarDB のトランザクション的に一貫性のあるバックアップを作成する方法を確認してください。 + +:::note + +以下にリストされているデータベース別のバックアップ方法は、ScalarDB がサポートするデータベースの一部の例にすぎません。 + +::: + + + + 自動バックアップ機能を使用すると、バックアップ保持期間内の任意の時点に復元できます。 + + + `--single-transaction` オプションを指定した `mysqldump` コマンドを使用します。 + + + `pg_dump` コマンドを使用します。 + + + [Special commands to sqlite3 (dot-commands)](https://www.sqlite.org/cli.html#special_commands_to_sqlite3_dot_commands_) で指定されているように、`.backup` コマンドを `.timeout` コマンドとともに使用します。 + + 例については、[BASH: SQLite3 .backup command](https://stackoverflow.com/questions/23164445/bash-sqlite3-backup-command) を参照してください。 + + + クラスターはバックアップポリシーに基づいて自動的にバックアップされ、これらのバックアップは特定の期間保持されます。オンデマンドバックアップを実行することもできます。バックアップの実行の詳細については、[YugabyteDB Managed: Back up and restore clusters](https://docs.yugabyte.com/preview/yugabyte-cloud/cloud-clusters/backup-clusters/)を参照してください。 + + + +### 明示的に一時停止してバックアップする + +トランザクション的に一貫性のあるバックアップを作成する別の方法は、ScalarDB インスタンスのクラスターに未処理のトランザクションがないときにバックアップを作成することです。バックアップの作成は、次の条件によって異なります。 + +- 基盤となるデータベースにポイントインタイムスナップショットまたはバックアップ機能がある場合は、未処理のトランザクションが存在しない期間にバックアップを作成できます。 +- 基盤となるデータベースにポイントインタイムリストアまたはリカバリ (PITR) 機能がある場合は、一時停止期間内の未処理のトランザクションが存在しない時間 (できれば中間時間) にリストアポイントを設定できます。 + +:::note + +PITR 機能を使用する場合は、NTP などのクロック同期を使用して、クライアントとサーバー間のクロックのずれを最小限に抑える必要があります。そうしないと、一時停止期間として取得される時間が、一時停止が実際に行われた時間と大きく異なる可能性があり、バックアップが進行中のトランザクションが存在する時点に復元される可能性があります。 + +また、クロック同期ではノード間のクロックを完全に同期できないため、十分な時間 (たとえば、5 秒) 一時停止し、一時停止期間の中間時間を復元ポイントとして使用する必要があります。 + +::: + +ScalarDB が未処理のリクエストを排出し、新しいリクエストの受け入れを停止して一時停止期間を作成できるようにするには、ScalarDB を使用するアプリケーションで [Scalar Admin](https://github.com/scalar-labs/scalar-admin) インターフェースを適切に実装するか、Scalar Admin インターフェースを実装する [ScalarDB Cluster](scalardb-cluster/index.mdx) を使用する必要があります。 + +[Scalar Admin クライアントツール](https://github.com/scalar-labs/scalar-admin/tree/main/java#scalar-admin-client-tool)を使用すると、進行中のトランザクションを失うことなく、Scalar Admin インターフェースを実装するノード、サーバー、またはアプリケーションを一時停止できます。 + +トランザクション的に一貫性のあるバックアップを作成する方法は、使用しているデータベースの種類によって異なります。データベースを選択して、ScalarDB のトランザクション的に一貫性のあるバックアップを作成する方法を確認します。 + +:::note + +以下にリストされているデータベース別のバックアップ方法は、ScalarDB がサポートするデータベースの一部の例にすぎません。 + +::: + + + + DynamoDB テーブルに対して PITR 機能を有効にする必要があります。[ScalarDB Schema Loader](schema-loader.mdx) を使用してスキーマを作成する場合、ツールはデフォルトでテーブルの PITR 機能を有効にします。 + + トランザクション的に一貫性のある復元ポイントを指定するには、[明示的な一時停止によるバックアップ](#明示的に一時停止してバックアップする)の説明に従って、ScalarDB を DynamoDB とともに使用しているアプリケーションを一時停止します。 + + + PITR 機能が有効になっている継続的バックアップポリシーを使用して、Cosmos DB for NoSQL アカウントを作成する必要があります。この機能を有効にすると、バックアップが継続的に作成されます。 + + トランザクション的に一貫性のある復元ポイントを指定するには、[明示的に一時停止してバックアップする](#明示的に一時停止してバックアップする)の説明に従って、ScalarDB を Cosmos DB for NoSQL とともに使用しているアプリケーションを一時停止します。 + + + Cassandra にはレプリケーション機能が組み込まれているため、必ずしもトランザクション的に一貫性のあるバックアップを作成する必要はありません。たとえば、レプリケーション係数が `3` に設定されていて、Cassandra クラスター内のノードの 1 つのデータのみが失われた場合、通常のトランザクション的に一貫性のないバックアップ (スナップショット) と修復機能を使用してノードを回復できるため、トランザクション的に一貫性のあるバックアップ (スナップショット) は必要ありません。 + + ただし、クラスターノードのクォーラムでデータが失われた場合は、クラスターを特定のトランザクション的に一貫性のあるポイントに復元するために、トランザクション的に一貫性のあるバックアップ (スナップショット) が必要になります。 + + トランザクション的に一貫性のあるクラスター全体のバックアップ (スナップショット) を作成するには、ScalarDB または [ScalarDB Cluster](scalardb-cluster/index.mdx) を使用しているアプリケーションを一時停止し、[明示的な一時停止によるバックアップ](#明示的に一時停止してバックアップする)の説明に従ってノードのバックアップ (スナップショット) を作成するか、Cassandra クラスターを停止してノード内のすべてのデータのコピーを作成し、クラスターを起動します。 + + + 一時停止期間中にオンデマンドバックアップまたはスケジュールされたバックアップを実行できます。バックアップの実行の詳細については、[YugabyteDB Managed: Back up and restore clusters](https://docs.yugabyte.com/preview/yugabyte-cloud/cloud-clusters/backup-clusters/) を参照してください。 + + + +## バックアップを復元する + +トランザクション的に一貫性のあるバックアップを復元する方法は、使用しているデータベースの種類によって異なります。データベースを選択して、ScalarDB のトランザクション的に一貫性のあるバックアップを作成する方法を確認してください。 + +:::note + +以下にリストされているデータベース別の復元方法は、ScalarDB がサポートするデータベースの一部の例にすぎません。 + +::: + + + + 自動バックアップ機能を使用すると、バックアップ保持期間内の任意の時点に復元できます。 + + + まず、Cassandra クラスターのすべてのノードを停止します。次に、`data`、`commitlog`、`hints` ディレクトリをクリーンアップし、各ノードにバックアップ (スナップショット) を配置します。 + + 各ノードにバックアップ (スナップショット) を配置したら、Cassandra クラスターのすべてのノードを起動します。 + + + [Azure portal を使用してアカウントを復元する](https://docs.microsoft.com/ja-jp/azure/cosmos-db/restore-account-continuous-backup#restore-account-portal)については、Azure の公式ドキュメントに従ってください。バックアップを復元した後、復元されたデータベースの [既定の整合性レベルを構成する](https://learn.microsoft.com/ja-jp/azure/cosmos-db/nosql/how-to-manage-consistency#configure-the-default-consistency-level)を `STRONG` に設定します。さらに、前述のように、一時停止期間の中間時点を復元ポイントとして使用する必要があります。 + + ScalarDB は、ScalarDB Schema Loader を使用してスキーマを作成するときにインストールされるストアドプロシージャを使用して、Cosmos DB アダプターを実装します。ただし、Cosmos DB の PITR 機能では、ストアドプロシージャは復元されません。このため、復元後にすべてのテーブルに必要なストアドプロシージャを再インストールする必要があります。これは、ScalarDB Schema Loader を `--repair-all` オプションとともに使用することで実行できます。詳細については、[名前空間とテーブルを修復する](schema-loader.mdx#名前空間とテーブルを修復する)を参照してください。 + + + [DynamoDB テーブルを特定の時点に復元](https://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/PointInTimeRecovery.Tutorial.html)については、公式の AWS ドキュメントに従ってください。ただし、テーブルはエイリアスを使用してのみ復元できることに注意してください。このため、エイリアスを使用してテーブルを復元し、元のテーブルを削除して、エイリアスを元の名前に変更し、同じ名前のテーブルを復元する必要があります。 + + この手順を実行するには、次の手順を実行します。 + + 1. バックアップを作成します。 + 1. 一時停止期間の中間時点を復元ポイントとして選択します。 + 2. テーブル A の PITR を使用してテーブル B に復元します。 + 3. 復元されたテーブル B のバックアップを作成します (バックアップの名前がバックアップ B であると仮定します)。 + 4. テーブル B を削除します。 + 2. バックアップを復元します。 + 1. テーブル A を削除します。 + 2. バックアップ B を使用して A という名前のテーブルを作成します。 + +:::note + +* テーブルは一度に 1 つしか復元できないため、上記の手順はテーブルごとに実行する必要があります。 +* 復元されたテーブルでは、PITR や自動スケーリングポリシーなどの設定がデフォルト値にリセットされるため、必要な設定を手動で行う必要があります。詳細については、公式 AWS ドキュメントの [DynamoDB を使用した DynamoDB テーブルのバックアップと復元の仕組み](https://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/CreateBackup.html#CreateBackup_HowItWorks-restore)を参照してください。 + +::: + + + `mysqldump` を使用してバックアップファイルを作成した場合は、[Reloading SQL-Format Backups](https://dev.mysql.com/doc/mysql-backup-excerpt/8.0/en/reloading-sql-format-dumps.html) で指定されているように、`mysql` コマンドを使用してバックアップを復元します。 + + + `pg_dump` を使用してバックアップファイルを作成した場合は、[Restoring the Dump](https://www.postgresql.org/docs/current/backup-dump.html#BACKUP-DUMP-RESTORE) で指定されているように、`psql` コマンドを使用してバックアップを復元します。 + + + [Special commands to sqlite3 (dot-commands)](https://www.sqlite.org/cli.html#special_commands_to_sqlite3_dot_commands_) で指定されているように、`.restore` コマンドを使用します。 + + + バックアップ保持期間内であれば、スケジュールされたバックアップまたはオンデマンドバックアップから復元できます。バックアップの実行の詳細については、[YugabyteDB Managed: Back up and restore clusters](https://docs.yugabyte.com/preview/yugabyte-cloud/cloud-clusters/backup-clusters/) を参照してください。 + + diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/configurations.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/configurations.mdx new file mode 100644 index 00000000..e9b77de6 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/configurations.mdx @@ -0,0 +1,293 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB の設定 + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このページでは、ScalarDB で使用可能な設定について説明します。 + +## ScalarDB クライアントの設定 + +このセクションでは、ScalarDB クライアントの設定について説明します。ScalarDB は、Consensus Commit を使用してトランザクションを実行する方法、非トランザクションストレージ操作を実行する方法、および ScalarDB Cluster を介してトランザクションを実行する方法を提供します。 + +### Consensus Commit を使用してトランザクションを実行する + +ScalarDB は、Consensus Commit と呼ばれる独自のトランザクションプロトコルを提供します。これは、ScalarDB のデフォルトのトランザクションマネージャータイプです。Consensus Commit トランザクションマネージャーを使用するには、ScalarDB プロパティファイルに次の内容を追加します。 + +```properties +scalar.db.transaction_manager=consensus-commit +``` + +:::note + +`scalar.db.transaction_manager` プロパティを指定しない場合は、`consensus-commit` がデフォルト値になります。 + +::: + +#### 基本設定 + +Consensus Commit トランザクションマネージャーでは、次の基本設定が利用可能です。 + +| 名前 | 説明 | デフォルト | +|-------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------| +| `scalar.db.transaction_manager` | `consensus-commit` を指定する必要があります。 | - | +| `scalar.db.consensus_commit.isolation_level` | Consensus Commit に使用される分離レベル。`SNAPSHOT` または `SERIALIZABLE` のいずれかを指定できます。 | `SNAPSHOT` | +| `scalar.db.consensus_commit.serializable_strategy` | Consensus Commit に使用されるシリアル化可能な戦略。`EXTRA_READ` または `EXTRA_WRITE` のいずれかを指定できます。`scalar.db.consensus_commit.isolation_level` プロパティで `SNAPSHOT` が指定されている場合、この設定は無視されます。 | `EXTRA_READ` | +| `scalar.db.consensus_commit.coordinator.namespace` | Coordinator テーブルの名前空間名。 | `coordinator` | +| `scalar.db.consensus_commit.include_metadata.enabled` | `true` に設定すると、`Get` および `Scan` 操作の結果にトランザクションメタデータが含まれます。特定のテーブルのトランザクションメタデータ列の詳細を表示するには、`DistributedTransactionAdmin.getTableMetadata()` メソッドを使用します。このメソッドは、トランザクションメタデータ列が追加されたテーブルメタデータを返します。この設定を使用すると、トランザクション関連の問題を調査するのに役立ちます。 | `false` | + +#### パフォーマンス関連の設定 + +Consensus Commit トランザクションマネージャーでは、次のパフォーマンス関連の設定が利用できます。 + +| 名前 | 説明 | デフォルト | +|----------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------| +| `scalar.db.consensus_commit.parallel_executor_count` | 並列実行のためのエグゼキュータ（スレッド）の数。 | `128` | +| `scalar.db.consensus_commit.parallel_preparation.enabled` | 準備フェーズが並行して実行されるかどうか。 | `true` | +| `scalar.db.consensus_commit.parallel_validation.enabled` | 検証フェーズ (`EXTRA_READ` 内) が並列で実行されるかどうか。 | `scalar.db.consensus_commit.parallel_commit.enabled` の値 | +| `scalar.db.consensus_commit.parallel_commit.enabled` | コミットフェーズが並列で実行されるかどうか。 | `true` | +| `scalar.db.consensus_commit.parallel_rollback.enabled` | ロールバックフェーズが並列で実行されるかどうか。 | `scalar.db.consensus_commit.parallel_commit.enabled` の値 | +| `scalar.db.consensus_commit.async_commit.enabled` | コミットフェーズが非同期で実行されるかどうか。 | `false` | +| `scalar.db.consensus_commit.async_rollback.enabled` | ロールバックフェーズが非同期に実行されるかどうか。 | `scalar.db.consensus_commit.async_commit.enabled` の値 | +| `scalar.db.consensus_commit.parallel_implicit_pre_read.enabled` | 暗黙的な事前読み取りが並列で実行されるかどうか。 | `true` | +| `scalar.db.consensus_commit.coordinator.group_commit.enabled` | トランザクション状態のコミットがバッチモードで実行されるかどうか。この機能は、2 フェーズコミットインターフェイスでは使用できません。 | `false` | +| `scalar.db.consensus_commit.coordinator.group_commit.slot_capacity` | グループコミット機能のグループ内のスロットの最大数。値が大きいとグループコミットの効率は向上しますが、待ち時間が増加し、トランザクションの競合が発生する可能性も高くなります。[^1] | `20` | +| `scalar.db.consensus_commit.coordinator.group_commit.group_size_fix_timeout_millis` | グループ内のスロットのサイズを固定するためのタイムアウト。値が大きいとグループコミットの効率が向上しますが、待ち時間が増加し、トランザクションの競合が発生する可能性も高くなります。[^1] | `40` | +| `scalar.db.consensus_commit.coordinator.group_commit.delayed_slot_move_timeout_millis` | 遅延スロットをグループから別の分離グループに移動して、元のグループが遅延トランザクションの影響を受けないようにするためのタイムアウト。値が大きいとグループコミットの効率が向上しますが、待ち時間が増加し、トランザクションの競合が発生する可能性も高くなります。[^1] | `1200` | +| `scalar.db.consensus_commit.coordinator.group_commit.old_group_abort_timeout_millis` | 進行中の古いグループをアボートするためのタイムアウト。値が小さいと、積極的なアボートによってリソースの消費量が減りますが、長時間実行されるトランザクションで不要なアボートが発生する可能性も高くなります。 | `60000` | +| `scalar.db.consensus_commit.coordinator.group_commit.timeout_check_interval_millis` | グループコミット関連のタイムアウトをチェックする間隔。 | `20` | +| `scalar.db.consensus_commit.coordinator.group_commit.metrics_monitor_log_enabled` | グループコミットのメトリックが定期的にログに記録されるかどうか。 | `false` | + +#### 基盤となるストレージまたはデータベースの設定 + +Consensus Commit にはストレージ抽象化レイヤーがあり、複数の基盤となるストレージをサポートしています。`scalar.db.storage` プロパティを使用してストレージ実装を指定できます。 + +データベースを選択して、各ストレージで使用可能な設定を確認します。 + + + + JDBC データベースでは次の設定を使用できます。 + + | 名前 | 説明 | デフォルト | + |-----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|------------------| + | `scalar.db.storage` | `jdbc` を指定する必要があります。 | - | + | `scalar.db.contact_points` | JDBC 接続 URL。 | | + | `scalar.db.username` | データベースにアクセスするためのユーザー名。 | | + | `scalar.db.password` | データベースにアクセスするためのパスワード。 | | + | `scalar.db.jdbc.connection_pool.min_idle` | 接続プール内のアイドル接続の最小数。 | `20` | + | `scalar.db.jdbc.connection_pool.max_idle` | 接続プール内でアイドル状態のままにできる接続の最大数。 | `50` | + | `scalar.db.jdbc.connection_pool.max_total` | 接続プールで同時にアクティブにできるアイドル接続と借用接続の最大合計数。制限がない場合は負の値を使用します。 | `100` | + | `scalar.db.jdbc.prepared_statements_pool.enabled` | このプロパティを `true` に設定すると、準備済みステートメントプーリングが有効になります。 | `false` | + | `scalar.db.jdbc.prepared_statements_pool.max_open` | ステートメントプールから同時に割り当てることができるオープンステートメントの最大数。制限がない場合は負の値を使用します。 | `-1` | + | `scalar.db.jdbc.isolation_level` | JDBC の分離レベル。`READ_UNCOMMITTED`、`READ_COMMITTED`、`REPEATABLE_READ`、または `SERIALIZABLE` を指定できます。 | 基盤データベース固有 | + | `scalar.db.jdbc.table_metadata.connection_pool.min_idle` | テーブルメタデータの接続プール内のアイドル接続の最小数。 | `5` | + | `scalar.db.jdbc.table_metadata.connection_pool.max_idle` | テーブルメタデータの接続プール内でアイドル状態のままにできる接続の最大数。 | `10` | + | `scalar.db.jdbc.table_metadata.connection_pool.max_total` | テーブルメタデータの接続プールで同時にアクティブにできるアイドル接続と借用接続の最大合計数。制限がない場合は負の値を使用します。 | `25` | + | `scalar.db.jdbc.admin.connection_pool.min_idle` | 管理者の接続プール内のアイドル接続の最小数。 | `5` | + | `scalar.db.jdbc.admin.connection_pool.max_idle` | 管理者の接続プール内でアイドル状態のままにできる接続の最大数。 | `10` | + | `scalar.db.jdbc.admin.connection_pool.max_total` | 管理者の接続プールで同時にアクティブにできるアイドル接続と借用接続の最大合計数。制限がない場合は負の値を使用します。 | `25` | + +:::note + +#### SQLite3 + +SQLite3 を JDBC データベースとして使用している場合は、`scalar.db.contact_points` を次のように設定する必要があります。 + +```properties +scalar.db.contact_points=jdbc:sqlite:?busy_timeout=10000 +``` + +他の JDBC データベースとは異なり、[SQLite3 doesn't fully support concurrent access](https://www.sqlite.org/lang_transaction.html)。[`SQLITE_BUSY`](https://www.sqlite.org/rescode.html#busy) によって内部的に頻繁に発生するエラーを回避するには、[`busy_timeout`](https://www.sqlite.org/c3ref/busy_timeout.html) パラメータを設定することをお勧めします。 + +#### YugabyteDB + +YugabyteDB を JDBC データベースとして使用している場合は、次のように `scalar.db.contact_points` で複数のエンドポイントを指定できます。 + +```properties +scalar.db.contact_points=jdbc:yugabytedb://127.0.0.1:5433\\,127.0.0.2:5433\\,127.0.0.3:5433/?load-balance=true +``` + +複数のエンドポイントはエスケープされたコンマで区切る必要があります。 + +YugabyteDB のスマートドライバーと負荷分散の詳細については、[YugabyteDB smart drivers for YSQL](https://docs.yugabyte.com/preview/drivers-orms/smart-drivers/) を参照してください。 + +::: + + + + DynamoDB では次の設定が利用可能です。 + + | 名前 | 説明 | デフォルト | + |--------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------| + | `scalar.db.storage` | `dynamo` を指定する必要があります。 | - | + | `scalar.db.contact_points` | ScalarDB が通信する AWS リージョン (例: `us-east-1`)。 | | + | `scalar.db.username` | AWS とやり取りするユーザーを識別するために使用される AWS アクセスキー。 | | + | `scalar.db.password` | AWS と対話するユーザーを認証するために使用される AWS シークレットアクセスキー。 | | + | `scalar.db.dynamo.endpoint_override` | ScalarDB が通信する Amazon DynamoDB エンドポイント。これは主に、AWS サービスではなくローカルインスタンスでのテストに使用されます。 | | + | `scalar.db.dynamo.namespace.prefix` | ユーザー名前空間とメタデータ名前空間名のプレフィックス。AWS では単一の AWS リージョン内で一意のテーブル名を持つ必要があるため、単一の AWS リージョン内で複数の ScalarDB 環境 (開発、本番など) を使用する場合に便利です。 | | + + + Cosmos DB for NoSQL では次の設定が利用可能です。 + + | 名前 | 説明 | デフォルト | + |--------------------------------------|------------------------------------------------------------------------------------------------------------|-----------| + | `scalar.db.storage` | `cosmos` を指定する必要があります。 | - | + | `scalar.db.contact_points` | ScalarDB が通信する NoSQL エンドポイント用の Azure Cosmos DB。 | | + | `scalar.db.password` | Azure Cosmos DB for NoSQL にアクセスするための認証を実行するために使用されるマスターキーまたは読み取り専用キーのいずれか。 | | + | `scalar.db.cosmos.consistency_level` | Cosmos DB 操作に使用される一貫性レベル。`STRONG` または `BOUNDED_STALENESS` を指定できます。 | `STRONG` | + + + Cassandra では次の設定が利用可能です。 + + | 名前 | 説明 | デフォルト | + |----------------------------|--------------------------------------|----------| + | `scalar.db.storage` | `cassandra` を指定する必要があります。 | - | + | `scalar.db.contact_points` | カンマで区切られた連絡先。 | | + | `scalar.db.contact_port` | すべての連絡先ポイントのポート番号。 | | + | `scalar.db.username` | データベースにアクセスするためのユーザー名。 | | + | `scalar.db.password` | データベースにアクセスするためのパスワード。 | | + + + +##### マルチストレージのサポート + +ScalarDB は、複数のストレージ実装の同時使用をサポートしています。`scalar.db.storage` プロパティの値として `multi-storage` を指定することで、複数のストレージを使用できます。 + +複数のストレージの使用の詳細については、[マルチストレージトランザクション](multi-storage-transactions.mdx)を参照してください。 + +##### クロスパーティションスキャン設定 + +以下で説明するようにクロスパーティションスキャンオプションを有効にすると、`Scan` 操作でパーティション全体のすべてのレコードを取得できます。さらに、`cross_partition_scan.filtering` と `cross_partition_scan.ordering` をそれぞれ有効にすることで、クロスパーティション `Scan` 操作で任意の条件と順序を指定できます。現在、順序付けオプション付きのクロスパーティションスキャンは、JDBC データベースでのみ使用できます。フィルタリングと順序付けを有効にするには、`scalar.db.cross_partition_scan.enabled` を `true` に設定する必要があります。 + +クロスパーティションスキャンの使用方法の詳細については、[`Scan` 操作](./api-guide.mdx#scan-操作)を参照してください。 + +:::warning + +非 JDBC データベースの場合、`SERIALIZABLE` 分離レベルでクロスパーティションスキャンを有効にした場合でも、トランザクションは読み取りコミットスナップショット分離 (`SNAPSHOT`) で実行される可能性があります。これは、より低い分離レベルです。非 JDBC データベースを使用する場合は、トランザクションの一貫性が重要でない場合にのみ、クロスパーティションスキャンを使用してください。 + +::: + +| 名前 | 説明 | デフォルト | +|----------------------------------------------------|---------------------------------------------------|----------| +| `scalar.db.cross_partition_scan.enabled` | パーティション間スキャンを有効にします。 | `false` | +| `scalar.db.cross_partition_scan.filtering.enabled` | クロスパーティションスキャンでフィルタリングを有効にします。 | `false` | +| `scalar.db.cross_partition_scan.ordering.enabled` | パーティション間スキャンでの順序付けを有効にします。 | `false` | + +### 非トランザクションストレージ操作を実行する + +非トランザクションストレージ操作を実行するには、`scalar.db.transaction_manager` プロパティを `single-crud-operation` に設定する必要があります。 + +```properties +scalar.db.transaction_manager=single-crud-operation +``` + +また、[基盤となるストレージまたはデータベースの設定](#基盤となるストレージまたはデータベースの設定)の説明に従って、基盤となるストレージまたはデータベースを設定する必要があります。 + +### ScalarDB Cluster を介してトランザクションを実行する + +[ScalarDB Cluster](scalardb-cluster/index.mdx) は、ScalarDB に gRPC インターフェースを提供するコンポーネントです。 + +クライアント設定の詳細については、[ScalarDB Cluster クライアント設定](scalardb-cluster/developer-guide-for-scalardb-cluster-with-java-api.mdx#クライアント設定)を参照してください。 + +## その他の ScalarDB 設定 + +ScalarDB で使用できる追加の設定は次のとおりです。 + +| 名前 | 説明 | デフォルト | +|------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------| +| `scalar.db.metadata.cache_expiration_time_secs` | ScalarDB には、データベースへのリクエスト数を減らすためのメタデータキャッシュがあります。この設定では、キャッシュの有効期限を秒単位で指定します。`-1`を指定した場合は、キャッシュは期限切れになりません。 | `60` | +| `scalar.db.active_transaction_management.expiration_time_millis` | ScalarDB は進行中のトランザクションを維持し、トランザクション ID を使用して再開できます。この設定は、このトランザクション管理機能の有効期限をミリ秒単位で指定します。 | `-1` (有効期限なし) | +| `scalar.db.default_namespace_name` | 指定された名前空間名は、名前空間を指定していない操作によって使用されます。 | | +| `scalar.db.system_namespace_name` | 指定された名前空間名は ScalarDB によって内部的に使用されます。 | `scalardb` | + +## プレースホルダーの使用 + +値にプレースホルダーを使用できます。プレースホルダーは環境変数 (`${env:}`) またはシステムプロパティ (`${sys:}`) に置き換えられます。また、`${sys::-}` のようにプレースホルダーにデフォルト値を指定することもできます。 + +以下は、プレースホルダーを使用する設定の例です。 + +```properties +scalar.db.username=${env::-admin} +scalar.db.password=${env:} +``` + +この設定例では、ScalarDB は環境変数からユーザー名とパスワードを読み取ります。環境変数 `SCALAR_DB_USERNAME` が存在しない場合、ScalarDB はデフォルト値 `admin` を使用します。 + +## 設定例 + +このセクションでは、いくつかの設定例を示します。 + +### 設定例 #1 - アプリとデータベース + +```mermaid +flowchart LR + app["アプリ
(ScalarDB ライブラリと
Consensus Commit)"] + db[(基盤となるストレージまたはデータベース)] + app --> db +``` + +この例の設定では、アプリ (Consensus Commit を備えた ScalarDB ライブラリ) が、基盤となるストレージまたはデータベース (この場合は Cassandra) に直接接続します。 + +:::warning + +この設定は開発目的のみに存在し、実稼働環境には適していません。これは、ScalarDB のトランザクション的に一貫性のあるバックアップを取得するために、アプリが [Scalar Admin](https://github.com/scalar-labs/scalar-admin) インターフェースを実装する必要があり、追加の設定が必要になるためです。 + +::: + +以下は、ScalarDB を介してアプリを基盤となるデータベースに接続するための設定の例です。 + +```properties +# Transaction manager implementation. +scalar.db.transaction_manager=consensus-commit + +# Storage implementation. +scalar.db.storage=cassandra + +# Comma-separated contact points. +scalar.db.contact_points= + +# Credential information to access the database. +scalar.db.username= +scalar.db.password= +``` + +### 設定例 #2 - アプリ、ScalarDB Cluster、データベース + +```mermaid +flowchart LR + app["アプリ -
ScalarDB ライブラリと gRPC"] + cluster["ScalarDB Cluster -
(ScalarDB ライブラリと
Consensus Commit)"] + db[(基盤となるストレージまたはデータベース)] + app --> cluster --> db +``` + +この例の設定では、アプリ (gRPC を使用した ScalarDB ライブラリ) は、ScalarDB Enterprise エディションでのみ使用可能なコンポーネントである ScalarDB Cluster を介して、基盤となるストレージまたはデータベース (この場合は Cassandra) に接続します。 + +:::note + +ScalarDB Cluster は [Scalar Admin](https://github.com/scalar-labs/scalar-admin) インターフェイスを実装しており、これにより ScalarDB Cluster を一時停止することで ScalarDB のトランザクション的に一貫性のあるバックアップを取得できるため、この設定は実稼働環境での使用に適しています。 + +::: + +以下は、ScalarDB Cluster を介してアプリを基盤となるデータベースに接続するための設定の例です。 + +```properties +# Transaction manager implementation. +scalar.db.transaction_manager=cluster + +# Contact point of the cluster. +scalar.db.contact_points=indirect: +``` + +クライアント設定の詳細については、[ScalarDB Cluster クライアント設定](scalardb-cluster/developer-guide-for-scalardb-cluster-with-java-api.mdx#クライアント設定) を参照してください。 + +[^1]: アプリケーションのアクセスパターンを考慮し、アプリケーションが使用する同じ基盤ストレージで、いくつかのバリエーション (たとえば、デフォルト値の 75% と 125%) でパフォーマンスをベンチマークして、最適な設定を決定することは価値があります。最適な設定は実際にはこれらの要因によって決まるためです。また、これらのパラメーターの組み合わせ (たとえば、1 番目に `slot_capacity:20` と `group_size_fix_timeout_millis:40`、2 番目に `slot_capacity:30` と `group_size_fix_timeout_millis:40`、3 番目に `slot_capacity:20` と `group_size_fix_timeout_millis:80`) をベンチマークして、最適な組み合わせを決定することも重要です。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/data-modeling.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/data-modeling.mdx new file mode 100644 index 00000000..552a0fd1 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/data-modeling.mdx @@ -0,0 +1,134 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# データをモデル化する + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +データモデリング (つまり、データベーススキーマの設計) とは、データへのアクセスに使用されるパターンと、ビジネスオペレーション内で実行されるクエリの種類を特定することで、データの保存方法と使用方法を概念化して視覚化するプロセスです。 + +このページでは、まず ScalarDB データモデルについて説明し、次にデータモデルに基づいてデータベーススキーマを設計する方法について説明します。 + +## ScalarDB データモデル + +ScalarDB のデータモデルは、Bigtable データモデルにヒントを得た拡張キー値モデルです。リレーショナルモデルに似ていますが、以下に示すようにいくつかの点で異なります。データモデルは、リレーショナルデータベース、NoSQL データベース、NewSQL データベースなど、さまざまなデータベースを抽象化するために選択されます。 + +次の図は、それぞれがレコードのコレクションである ScalarDB テーブルの例を示しています。このセクションでは、まず、テーブルやレコードなどの ScalarDB が定義するオブジェクトについて説明し、次にレコードの検索方法について説明します。 + +![ScalarDB データモデル](images/scalardb_data_model.png) + +### ScalarDB のオブジェクト + +ScalarDB データモデルには、いくつかのオブジェクトがあります。 + +#### 名前空間 + +名前空間は、SQL 名前空間またはデータベースに類似したテーブルのコレクションです。 + +#### テーブル + +テーブルはパーティションのコレクションです。名前空間には、通常、それぞれが名前で識別される 1 つ以上のテーブルが含まれます。 + +#### パーティション + +パーティションはレコードのコレクションであり、論理ノードまたは物理ノードへの分散単位です。したがって、同じパーティション内のレコードは同じノードに配置されます。ScalarDB では、複数のパーティションがハッシュによって分散されていると想定しています。 + +#### レコード / 行 + +レコードまたは行は、他のすべてのレコード間で一意に識別できる列のセットです。 + +#### 列 + +列は基本的なデータ要素であり、これ以上細分化する必要はありません。各レコードは、1 つ以上の列で設定されます。各列にはデータ型があります。データ型の詳細については、[ScalarDB と他のデータベース間のデータ型マッピング](schema-loader.mdx#scalardb-と他のデータベース間のデータ型マッピング)を参照してください。 + +#### セカンダリインデックス + +セカンダリインデックスは、単一の基本テーブル内の列のソートされたコピーです。各インデックスエントリは、対応するテーブルパーティションにリンクされています。ScalarDB は現在、複数列のインデックスをサポートしていないため、1 つの列のみでインデックスを作成できます。 + +### レコードの検索方法 + +このセクションでは、テーブルからレコードを検索する方法について説明します。 + +#### プライマリーキー + +プライマリーキーは各レコードを一意に識別します。2 つのレコードが同じプライマリーキーを持つことはできません。したがって、プライマリーキーを指定してレコードを検索できます。プライマリーキーは、パーティションキーと、オプションでクラスタリングキーで設定されます。 + +#### パーティションキー + +パーティションキーは、パーティションを一意に識別します。パーティションキーは、パーティションキー列と呼ばれる列のセットで設定されます。パーティションキーのみを指定すると、パーティションに属するレコードのセットを取得できます。 + +#### クラスタリングキー + +クラスタリングキーは、パーティション内のレコードを一意に識別します。クラスタリングキー列と呼ばれる列のセットで設定されます。クラスタリングキーを指定する場合は、効率的な検索のためにパーティションキーを指定する必要があります。パーティションキーなしでクラスタリングキーを指定すると、すべてのパーティションをスキャンすることになります。すべてのパーティションをスキャンすると、特にデータ量が多い場合は時間がかかるため、自己判断でのみ実行してください。 + +パーティション内のレコードは、クラスタリング順序として指定されたクラスタリングキー列でソートされていると想定されます。したがって、定義された順序でクラスタリングキー列の一部を指定して、返される結果を絞り込むことができます。 + +#### インデックスキー + +インデックスキーは、インデックス内のキーを検索してレコードを識別します。インデックスキーの検索はすべてのパーティションにまたがるため、特に検索の選択性が低くない場合は、必ずしも効率的であるとは限りません。 + +## データベーススキーマの設計方法 + +データベーススキーマはリレーショナルモデルと同様に設計できますが、基本的な原則があり、従うべきベストプラクティスがいくつかあります。 + +### クエリ駆動型データモデリング + +リレーショナルデータベースでは、データは正規化されたテーブルに整理され、外部キーを使用して他のテーブル内の関連データを参照します。アプリケーションが実行するクエリはテーブルによって構造化され、関連データはテーブル結合としてクエリされます。 + +ScalarDB は ScalarDB SQL での結合操作をサポートしていますが、データモデリングは NoSQL データベースのように、よりクエリ駆動型である必要があります。データアクセスパターンとアプリケーションクエリによって、テーブルの構造と設定が決定されます。 + +### ベストプラクティス + +このセクションでは、データベーススキーマを設計するためのベストプラクティスについて説明します。 + +#### データ分散を考慮する + +パーティションキーとクラスタリングキーを適切に選択して、パーティションへの負荷を分散させることをお勧めします。 + +たとえば、銀行アプリケーションでアカウント ID をパーティションキーとして選択すると、アカウントが属するパーティション内で特定のアカウントに対するすべてのアカウント操作を実行できます。したがって、異なるアカウント ID を操作すると、異なるパーティションにアクセスすることになります。 + +一方、ブランチ ID をパーティションキーとして選択し、アカウント ID をクラスタリングキーとして選択すると、ブランチのアカウント ID へのアクセスはすべて同じパーティションに送られるため、負荷とデータサイズの不均衡が生じます。さらに、少数の大きなパーティションを作成すると負荷とデータサイズの不均衡が生じるため、パーティションキーにはカーディナリティの高い列を選択する必要があります。 + +#### 単一のパーティションの読み取りを試みる + +データモデルの特性により、単一パーティション検索が最も効率的です。スキャンを発行したり、複数パーティションの検索やスキャンを必要とするリクエストを選択したりする必要がある場合は、[クロスパーティションスキャンで有効にする](configurations.mdx#クロスパーティションスキャン設定)ことができますが、独自の判断で実行し、可能であればスキーマの更新を検討してください。 + +たとえば、銀行アプリケーションで、パーティションキーとして電子メールを選択し、クラスタリングキーとしてアカウント ID を選択し、アカウント ID を指定するクエリを発行すると、対応するパーティションを効率的に識別できないため、クエリはすべてのパーティションにまたがって実行されます。このような場合は、常にアカウント ID を使用してテーブルを検索する必要があります。 + +:::note + +適切なインデックスを持つリレーショナルデータベース上の複数のパーティションを読み取る場合、クエリがデータベースにプッシュダウンされるため、クエリが効率的になる可能性があります。 + +::: + +#### セカンダリインデックスの使用を避ける + +上記と同様に、セカンダリインデックスを使用するスキャンまたは選択リクエストを発行する必要がある場合、そのリクエストはテーブルのすべてのパーティションにまたがります。したがって、セカンダリインデックスの使用を避けるようにしてください。セカンダリインデックスを使用する必要がある場合は、小さな部分を検索する低選択性クエリを介して使用します。 + +セカンダリインデックスの代わりに、ベーステーブルのクラスター化インデックスとして機能する別のテーブルを作成できます。 + +たとえば、プライマリーキーが `A` である `table1(A, B, C)` という 3 つの列を持つテーブルがあるとします。次に、`C` をプライマリーキーとして `index-table1(C, A, B)` のようなテーブルを作成し、`C` の値を指定して単一のパーティションを検索できるようにします。このアプローチにより、読み取りクエリは高速化されますが、ScalarDB トランザクションを使用して 2 つのテーブルに書き込む必要があるため、書き込みクエリの負荷が増加する可能性があります。 + +:::note + +将来的には、ScalarDB にテーブルベースのセカンダリインデックス機能が追加される予定です。 + +::: + +#### データはハッシュによって分散されていると想定されていることを考慮する + +現在の ScalarDB データモデルでは、データはハッシュによって分散されていると想定されています。したがって、パーティションキーがないと範囲クエリを効率的に実行できません。 + +範囲クエリを効率的に発行するには、パーティション内で実行する必要があります。ただし、このアプローチに従う場合は、パーティションキーを指定する必要があります。範囲クエリは常に同じパーティションに送信されるので、パーティションが過負荷になる可能性があり、スケーラビリティの問題が発生する可能性があります。この制限は ScalarDB に固有のものではなく、スケーラビリティのためにハッシュによってデータが分散されているデータベースに固有のものです。 + +:::note + +適切なインデックスを持つリレーショナルデータベースで ScalarDB を実行すると、クエリがデータベースにプッシュダウンされるため、範囲クエリが効率的になる可能性があります。 + +::: diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/database-configurations.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/database-configurations.mdx new file mode 100644 index 00000000..3558209c --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/database-configurations.mdx @@ -0,0 +1,122 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB の基盤となるデータベースの設定 + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このドキュメントでは、ScalarDB を使用するアプリケーションが正しく効率的に動作するように、ScalarDB の基盤となるデータベースを設定する方法について説明します。 + +## 基盤となるデータベースの一般的な要件 + +ScalarDB では、基盤となる各データベースが、データベースでトランザクションと分析を実行するための特定の機能を提供する必要があります。このドキュメントでは、一般的な要件と、要件を満たすために各データベースを設定する方法について説明します。 + +### トランザクション + +ScalarDB では、基盤となる各データベースが、データベースでトランザクションを実行するために少なくとも次の機能を提供する必要があります。 + +- 単一のデータベースレコードに対する線形化可能な読み取りと条件付きミューテーション (書き込みと削除)。 +- 書き込まれたデータベースレコードの耐久性。 +- 各データベースレコードにアプリケーションデータのほかに任意のデータを保存できる機能。 + +### 分析 + +ScalarDB では、基盤となる各データベースが、データベースで分析を実行するために次の機能を提供する必要があります。 + +- コミットされたレコードのみを返す機能。 + +:::note + +ScalarDB は、CRUD 操作だけでなく、スキーマ、テーブル、インデックスの作成や変更などの操作を実行するために、基盤となるデータベース上で実行されるため、ScalarDB を介してデータベースにアクセスするのに十分な権限を持つデータベースアカウントが必要です。基本的に、ScalarDB では、基盤となるデータベースにアクセスするために完全な権限を持つアカウントが必要です。 + +::: + +## 一般的な要件を満たすようにデータベースを設定する方法 + +一般的な要件を満たすようにデータベースを設定する方法の詳細については、データベースを選択してください。 + + + +

トランザクション

+ + - すべての操作に単一のプライマリサーバーまたは同期された複数のプライマリサーバーを使用します (プライマリデータベースから非同期にレプリケートされた読み取りレプリカに対する読み取り操作はありません)。 + - 読み取りコミットまたはより厳格な分離レベルを使用します。 + +

分析

+ + - 読み取りコミットまたはより厳格な分離レベルを使用します。 + + +

トランザクション

+ + - すべての操作に単一のプライマリリージョンを使用します。(プライマリリージョン以外のグローバルテーブルに対する読み取りおよび書き込み操作は実行できません。) + - DynamoDB にはプライマリリージョンの概念がないため、プライマリリージョンは自分で指定する必要があります。 + +

分析

+ + - 該当なし。DynamoDB は常にコミットされたレコードを返すため、DynamoDB 固有の要件はありません。 + + +

トランザクション

+ + - 「Strong」または「Bounded Staleness」の一貫性を持つすべての操作に単一のプライマリリージョンを使用します。 + +

分析

+ + - 該当なし。Cosmos DB は常にコミットされたレコードを返すため、Cosmos DB 固有の要件はありません。 + + +

トランザクション

+ + - すべての操作に単一のプライマリクラスターを使用します (プライマリ以外のクラスターでは読み取りまたは書き込み操作は行いません)。 + - `commitlog_sync` には `batch` または `group` を使用します。 + - Cassandra 互換データベースを使用している場合、それらのデータベースは軽量トランザクション (LWT) を適切にサポートしている必要があります。 + +

分析

+ + - 該当なし。Cassandra は常にコミットされたレコードを返すため、Cassandra 固有の要件はありません。 + + + +## 推奨事項 + +ScalarDB の基盤となる各データベースを適切に設定して、高パフォーマンスと高可用性を実現することが推奨されます。次の推奨事項には、更新すべきいくつかのオプションが含まれています。 + +:::note + +ScalarDB は基盤となるデータベースのアプリケーションと見なすことができるため、効率を向上させるためによく使用されるその他のオプションを更新してみることをお勧めします。 + +::: + + + + - パフォーマンスを向上させるには、読み取りコミット分離を使用します。 + - 各データベースのパフォーマンス最適化のベストプラクティスに従います。たとえば、パフォーマンスを向上させるには、通常、バッファサイズ (PostgreSQL の `shared_buffers` など) を増やし、接続数 (PostgreSQL の `max_connections` など) を増やすことが推奨されます。 + + + - 読み取り容量ユニット (RCU) と書き込み容量ユニット (WCU) の数を増やして、スループットを高めます。 + - ポイントインタイムリカバリ (PITR) を有効にします。 + +:::note + +DynamoDB はデフォルトで複数のアベイラビリティーゾーンにデータを保存するため、可用性を向上させるために設定を調整する必要はありません。 + +::: + + + - 高いスループットを実現するために、リクエストユニット (RU) の数を増やします。 + - ポイントインタイムリストア (PITR) を有効にします。 + - 可用性ゾーンを有効にします。 + + + - スループットを高めるために、`concurrent_reads` と `concurrent_writes` を増やします。詳細については、[`concurrent_writes`](https://cassandra.apache.org/doc/stable/cassandra/configuration/cass_yaml_file.html#concurrent_writes) に関する Cassandra の公式ドキュメントを参照してください。 + + diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/deploy-overview.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/deploy-overview.mdx new file mode 100644 index 00000000..3a0d7e1b --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/deploy-overview.mdx @@ -0,0 +1,22 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# デプロイの概要 + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このカテゴリでは、ローカルおよびクラウドベースの Kubernetes 環境での ScalarDB、特に ScalarDB Cluster と ScalarDB Analytics のデプロイに慣れるためのガイドに従うことができます。 + +## ローカル Kubernetes 環境に ScalarDB をデプロイする + +このサブカテゴリでは、ローカル Kubernetes 環境に ScalarDB をデプロイする方法を学習できます。このサブカテゴリの主な焦点は、Scalar Helm Charts の使用方法を学習することです。このため、わかりやすくするために特定のデータベース (PostgreSQL) が指定されています。 + +## クラウドベースの Kubernetes 環境に ScalarDB をデプロイする + +このサブカテゴリでは、クラウドベースの Kubernetes 環境に ScalarDB をデプロイする方法を学習できます。このサブカテゴリでは、Scalar Helm Charts の使用方法と、クラウドベースの Kubernetes 環境で ScalarDB を実行するために必要なその他の手順について説明します。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/design.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/design.mdx new file mode 100644 index 00000000..c38db2a2 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/design.mdx @@ -0,0 +1,43 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB デザイン + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このドキュメントでは、ScalarDB の設計と実装について簡単に説明します。ScalarDB の概要とその使用例については、[ScalarDB の概要](./overview.mdx) を参照してください。 + +## 全体的なアーキテクチャ + +ScalarDB は、アプリケーションとデータベースの間に配置されるハイブリッドトランザクション/分析処理 (HTAP) ミドルウェアです。次の図に示すように、ScalarDB は、コア、クラスター、分析の 3 つのコンポーネントで構成されています。ScalarDB は基本的に階層型アーキテクチャを採用しているため、クラスターコンポーネントと分析コンポーネントは、コアコンポーネントを使用して基盤となるデータベースとやり取りしますが、正確さを犠牲にすることなくパフォーマンスを最適化するためにコアコンポーネントをバイパスすることもあります。同様に、各コンポーネントも複数のレイヤーで構成されています。 + +![ScalarDB architecture](images/scalardb-architecture.png) + +## コンポーネント + +次のサブセクションでは、各コンポーネントについて 1 つずつ説明します。 + +### コア + +Apache 2 ライセンスの下でオープンソースソフトウェアとして提供される ScalarDB Core は、ScalarDB の不可欠な部分です。Core は、基礎となるデータベースを抽象化する抽象化レイヤーと、各データベースの抽象化を実装するアダプター (またはシム) を備えたデータベースマネージャーを提供します。さらに、データベース抽象化の上にトランザクションマネージャーを提供し、Scalar の新しい分散トランザクションプロトコルである Consensus Commit に基づいて、データベースに依存しないトランザクション管理を実現します。Core は、シンプルな CRUD インターフェイスを提供するライブラリとして提供されます。 + +### クラスター + +商用ライセンスでライセンスされている ScalarDB Cluster は、Core コンポーネントがクラスター化されたサーバーとして機能するためのクラスタリングソリューションを提供するコンポーネントです。Cluster は主に、多数の小規模なトランザクションおよび非トランザクションの読み取りと書き込みがある OLTP ワークロード向けに設計されています。さらに、認証、承認、保存時の暗号化、きめ細かなアクセス制御 (まだ開発中) などのエンタープライズ機能もいくつか提供しています。Cluster は Core コンポーネントと同じ CRUD インターフェースを提供するだけでなく、SQL および GraphQL インターフェースも提供しています。Cluster は Kubernetes Pod 内のコンテナーとして提供されるため、コンテナーを増やすことでパフォーマンスと可用性を高めることができます。 + +### 分析 + +商用ライセンスでライセンスされている ScalarDB Analytics は、Core コンポーネントによって管理されるデータ、または ScalarDB を使用しないアプリケーションによって管理されるデータに対してスケーラブルな分析処理を提供するコンポーネントです。Analytics は主に、少数の大規模な分析読み取りクエリがある OLAP ワークロード向けに設計されています。さらに、Spark を通じて SQL および DataSet API も提供されます。Analytics コンポーネントは Apache Spark エンジンにインストールできる Java パッケージとして提供されるため、Spark ワーカーノードを増やすことでパフォーマンスを向上させることができます。 + +## 参照 + +ScalarDB の設計と実装の詳細については、VLDB 2023 カンファレンスで発表された次のドキュメントを参照してください。 + +- **Speakerdeck プレゼンテーション:** [ScalarDB: Universal Transaction Manager for Polystores](https://speakerdeck.com/scalar/scalardb-universal-transaction-manager-for-polystores-vldb23) +- **詳細な論文:** [ScalarDB: Universal Transaction Manager for Polystores](https://www.vldb.org/pvldb/vol16/p3768-yamada.pdf) diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/develop-overview.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/develop-overview.mdx new file mode 100644 index 00000000..efb9a898 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/develop-overview.mdx @@ -0,0 +1,32 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB を用いた開発について開発の概要 + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このカテゴリでは、ScalarDB をよりよく理解するためのガイドに従うことができます。具体的には、トランザクション、分析クエリ、非トランザクションストレージ操作の実行方法です。 + +## トランザクションの実行 + +このサブカテゴリでは、ScalarDB データモデルに基づいてデータをモデル化し、スキーマを作成する方法を学習できます。次に、ScalarDB コアライブラリと、コアライブラリをラップする gRPC サーバーである ScalarDB Cluster を介してトランザクションを実行する方法を学習できます。 + +また、正確で安全でパフォーマンスの高い ScalarDB ベースのアプリケーションを作成する方法も学習できます。 + +## 分析クエリの実行 + +このセクションでは、ScalarDB の分析コンポーネントである ScalarDB Analytics をセットアップおよび設定する方法を学習できます。次に、ScalarDB トランザクションを介して書き込んだデータベースに対して分析クエリを実行します。 + +## 非トランザクションストレージ操作の実行 + +ScalarDB は当初、さまざまなデータベースと、そのようなデータベース間のトランザクション間の統一された抽象化を提供するために設計されました。ただし、複数の、場合によっては多様なデータベースを使用するアプリケーションを簡素化するために、統合抽象化のみが必要な場合もあります。 + +ScalarDB では、基盤となるデータベースとストレージで非トランザクション操作のみを実行できるよう、トランザクション機能なしで統合抽象化のみを提供するように設定することができます。ScalarDB は複数の操作にわたって ACID を保証しないため、より優れたパフォーマンスで操作を実行できます。 + +このサブカテゴリでは、このような非トランザクションストレージ操作を実行する方法を学習できます。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/getting-started-with-scalardb-by-using-kotlin.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/getting-started-with-scalardb-by-using-kotlin.mdx new file mode 100644 index 00000000..49608cf4 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/getting-started-with-scalardb-by-using-kotlin.mdx @@ -0,0 +1,418 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# Kotlin を使って ScalarDB をはじめよう + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +この入門チュートリアルでは、ScalarDB で好みのデータベースを設定し、Kotlin を使用して基本的な電子マネーアプリケーションをセットアップする方法について説明します。Kotlin は Java との相互運用性を備えているため、Kotlin から直接 ScalarDB を使用できます。 + +:::warning + +電子マネーアプリケーションはこのチュートリアル用に簡略化されており、実稼働環境には適していません。 + +::: + +## このサンプルアプリケーションの前提条件 + +ScalarDB は Java で記述されているため、環境に次のいずれかの Java Development Kit (JDK) がインストールされている必要があります。 + +- [Eclipse Temurin](https://adoptium.net/temurin/releases/) の OpenJDK LTS バージョン (8、11、17、または 21) +- [Docker](https://www.docker.com/get-started/) 20.10 以降と [Docker Compose](https://docs.docker.com/compose/install/) V2 以降 + +:::note + +このサンプルアプリケーションは、Eclipse Temurin の OpenJDK でテストされています。ただし、ScalarDB 自体は、さまざまなベンダーの JDK ディストリビューションでテストされています。互換性のある JDK ディストリビューションを含む ScalarDB の要件の詳細については、[要件](./requirements.mdx)を参照してください。 + +::: + +## ScalarDB サンプルリポジトリのクローンを作成する + +**Terminal** を開き、次のコマンドを実行して ScalarDB サンプルリポジトリのクローンを作成します。 + +```console +git clone https://github.com/scalar-labs/scalardb-samples +``` + +次に、次のコマンドを実行して、サンプルアプリケーションが含まれているディレクトリに移動します。 + +```console +cd scalardb-samples/scalardb-kotlin-sample +``` + +## データベースをセットアップする + +データベースを選択し、指示に従って ScalarDB 用に設定します。 + +ScalarDB がサポートするデータベースの一覧については、[データベース](requirements.mdx#データベース)を参照してください。 + + + +

MySQLをローカルで実行する

+ + `scalardb-samples/scalardb-kotlin-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で MySQL を実行できます。 + + MySQL を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d mysql + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-kotlin-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の MySQL のプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For MySQL + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:mysql://localhost:3306/ + scalar.db.username=root + scalar.db.password=mysql + ``` + + +

PostgreSQL をローカルで実行する

+ + `scalardb-samples/scalardb-kotlin-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で PostgreSQL を実行できます。 + + PostgreSQL を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d postgres + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-kotlin-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の PostgreSQL のプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For PostgreSQL + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:postgresql://localhost:5432/ + scalar.db.username=postgres + scalar.db.password=postgres + ``` + + +

Oracle Database をローカルで実行する

+ + `scalardb-samples/scalardb-kotlin-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で Oracle Database を実行できます。 + + Oracle Database を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d oracle + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-kotlin-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の Oracle データベースのプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For Oracle + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:oracle:thin:@//localhost:1521/FREEPDB1 + scalar.db.username=SYSTEM + scalar.db.password=Oracle + ``` + + +

SQL Server をローカルで実行する

+ + `scalardb-samples/scalardb-kotlin-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で SQL Server を実行できます。 + + SQL Server を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d sqlserver + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-kotlin-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の SQL Server のプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For SQL Server + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:sqlserver://localhost:1433;encrypt=true;trustServerCertificate=true + scalar.db.username=sa + scalar.db.password=SqlServer22 + ``` + + +

Amazon DynamoDB をローカルで実行する

+ + `scalardb-samples/scalardb-kotlin-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で Amazon DynamoDB Local を実行できます。 + + Amazon DynamoDB Local を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d dynamodb + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-kotlin-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の Amazon DynamoDB Local のプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For DynamoDB Local + scalar.db.storage=dynamo + scalar.db.contact_points=sample + scalar.db.username=sample + scalar.db.password=sample + scalar.db.dynamo.endpoint_override=http://localhost:8000 + ``` + + + Azure Cosmos DB for NoSQL を使用するには、Azure アカウントが必要です。Azure アカウントをお持ちでない場合は、[Azure Cosmos DB アカウントを作成する](https://learn.microsoft.com/ja-jp/azure/cosmos-db/nosql/quickstart-portal#create-account)にアクセスしてください。 + +

Cosmos DB for NoSQL を設定する

+ + [既定の整合性レベルを構成する](https://learn.microsoft.com/ja-jp/azure/cosmos-db/nosql/how-to-manage-consistency#configure-the-default-consistency-level)の公式ドキュメントに従って、**既定の整合性レベル**を**強力**に設定します。 + +

ScalarDB を設定する

+ + 以下の手順では、ローカル環境に JDK が適切にインストールおよび設定されており、Azure で Cosmos DB for NoSQL アカウントが適切に設定されていることを前提としています。 + + `scalardb-samples/scalardb-kotlin-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。`scalar.db.contact_points` と `scalar.db.password` の値は、説明に従って必ず変更してください。 + + ```properties + # For Cosmos DB + scalar.db.storage=cosmos + scalar.db.contact_points= + scalar.db.password= + ``` + +:::note + +Azure Cosmos DB アカウントのプライマリーキーまたはセカンダリキーを `scalar.db.password` の値として使用できます。 + +::: + + +

Cassandra をローカルで実行する

+ + `scalardb-samples/scalardb-kotlin-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で Apache Cassandra を実行できます。 + + Apache Cassandra を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d cassandra + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-kotlin-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の Cassandra のプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For Cassandra + scalar.db.storage=cassandra + scalar.db.contact_points=localhost + scalar.db.username=cassandra + scalar.db.password=cassandra + ``` + + + +## データベーススキーマをロードする + +アプリケーションでデータベーススキーマ (データを整理する方法) を定義する必要があります。サポートされているデータ型の詳細については、[ScalarDB と他のデータベース間のデータ型マッピング](schema-loader.mdx#scalardb-と他のデータベース間のデータ型マッピング)を参照してください。 + +このチュートリアルでは、**schema.json** というファイルが `scalardb-samples/scalardb-kotlin-sample` ディレクトリに既に存在します。スキーマを適用するには、[`scalardb` Releases](https://github.com/scalar-labs/scalardb/releases) ページに移動し、使用している ScalarDB のバージョンに一致する ScalarDB Schema Loader を `scalardb-samples/scalardb-kotlin-sample` ディレクトリにダウンロードします。 + +次に、データベースに基づいて、`` をダウンロードした ScalarDB Schema Loader のバージョンに置き換えて、次のコマンドを実行します。 + + + + ```console + java -jar scalardb-schema-loader-.jar --config database.properties --schema-file schema.json --coordinator + ``` + +:::note + +`transaction` が `true` に設定されたテーブルがスキーマ内に存在するため、`--coordinator` オプションが指定されています。スキーマの設定とロードの詳細については、[ScalarDB Schema Loader](schema-loader.mdx) を参照してください。 + +::: + + + ```console + java -jar scalardb-schema-loader-.jar --config database.properties --schema-file schema.json --coordinator + ``` + +:::note + +`transaction` が `true` に設定されたテーブルがスキーマ内に存在するため、`--coordinator` オプションが指定されています。スキーマの設定とロードの詳細については、[ScalarDB Schema Loader](schema-loader.mdx) を参照してください。 + +::: + + + ```console + java -jar scalardb-schema-loader-.jar --config database.properties --schema-file schema.json --coordinator + ``` + +:::note + +`transaction` が `true` に設定されたテーブルがスキーマ内に存在するため、`--coordinator` オプションが指定されています。スキーマの設定とロードの詳細については、[ScalarDB Schema Loader](schema-loader.mdx) を参照してください。 + +::: + + + ```console + java -jar scalardb-schema-loader-.jar --config database.properties --schema-file schema.json --coordinator + ``` + +:::note + +`transaction` が `true` に設定されたテーブルがスキーマ内に存在するため、`--coordinator` オプションが指定されています。スキーマの設定とロードの詳細については、[ScalarDB Schema Loader](schema-loader.mdx) を参照してください。 + +::: + + + ```console + java -jar scalardb-schema-loader-.jar --config database.properties --schema-file schema.json --coordinator --no-backup --no-scaling + ``` + +:::note + +`transaction` が `true` に設定されたテーブルがスキーマ内に存在するため、`--coordinator` オプションが指定されています。スキーマの設定とロードの詳細については、[ScalarDB Schema Loader](schema-loader.mdx) を参照してください。 + +また、Amazon DynamoDB Local は継続的なバックアップと自動スケーリングをサポートしていないため、`--no-backup` および `--no-scaling` オプションが指定されています。 + +::: + + + ```console + java -jar scalardb-schema-loader-.jar --config database.properties --schema-file schema.json --coordinator + ``` + +:::note + +`transaction` が `true` に設定されたテーブルがスキーマ内に存在するため、`--coordinator` オプションが指定されています。スキーマの設定とロードの詳細については、[ScalarDB Schema Loader](schema-loader.mdx) を参照してください。 + +::: + + + ```console + java -jar scalardb-schema-loader-.jar --config database.properties --schema-file schema.json --coordinator --replication-factor=1 + ``` + +:::note + +`transaction` が `true` に設定されたテーブルがスキーマ内に存在するため、`--coordinator` オプションが指定されています。スキーマの設定とロードの詳細については、[ScalarDB Schema Loader](schema-loader.mdx) を参照してください。 + +また、`--replication-factor=1` オプションは Cassandra を使用する場合にのみ有効です。デフォルトのレプリケーション係数は `3` ですが、このチュートリアルではセットアップを容易にするために `1` が使用されているため、3 つのノードではなく 1 つのノードを持つクラスターを準備するだけで済みます。ただし、レプリケーション係数 `1` は本番環境には適していないことに注意してください。 + +::: + + + +## 基本的な電子マネーアプリケーションでトランザクションを実行し、データを取得します + +スキーマをロードした後、クローンしたリポジトリに含まれる基本的な電子マネーアプリケーションでトランザクションを実行し、データを取得できます。 + +アプリケーションは、次の種類のトランザクションをサポートしています: + +- アカウントを作成します。 +- アカウントに資金を追加します。 +- 2 つのアカウント間で資金を送信します。 +- アカウント残高を取得します。 + +:::note + +初めて Gradle コマンドを実行すると、Gradle によって必要なライブラリが自動的にインストールされます。 + +::: + +### 残高のあるアカウントを作成する + +アカウント間で資金を送金するには、残高のあるアカウントが必要です。 + +**customer1** の残高が **500** のアカウントを作成するには、次のコマンドを実行します。 + +```console +./gradlew run --args="-action charge -amount 500 -to customer1" +``` + +### 残高のないアカウントを作成する + +残高のあるアカウントを設定したら、資金を送金するための別のアカウントが必要です。 + +残高が **0** の **merchant1** のアカウントを作成するには、次のコマンドを実行します。 + +```console +./gradlew run --args="-action charge -amount 0 -to merchant1" +``` + +### アカウントに資金を追加する + +[残高のあるアカウントを作成する](#残高のあるアカウントを作成する)でアカウントを作成して資金を追加したのと同じ方法で、アカウントに資金を追加できます。 + +**customer1** のアカウントに **500** を追加するには、次のコマンドを実行します。 + +```console +./gradlew run --args="-action charge -amount 500 -to customer1" +``` + +**customer1** のアカウントの残高は **1000** になります。 + +### 2 つのアカウント間で電子マネーを送金する + +これで 2 つのアカウントが作成され、少なくとも 1 つのアカウントに残高があるので、一方のアカウントからもう一方のアカウントに資金を送金できます。 + +**customer1** が **merchant1** に **100** を支払うようにするには、次のコマンドを実行します。 + +```console +./gradlew run --args="-action pay -amount 100 -from customer1 -to merchant1" +``` + +### アカウント残高を取得する + +あるアカウントから別のアカウントに資金を送金した後、各アカウントの残高を確認できます。 + +**customer1** の残高を取得するには、次のコマンドを実行します。 + +```console +./gradlew run --args="-action getBalance -id customer1" +``` + +次の出力が表示されます。 + +```console +... +The balance for customer1 is 900 +... +``` + +**merchant1** の残高を取得するには、次のコマンドを実行します。 + +```console +./gradlew run --args="-action getBalance -id merchant1" +``` + +次の出力が表示されます。 + +```console +... +The balance for merchant1 is 100 +... +``` + +## データベースを停止する + +データベースを停止するには、次のコマンドを実行して Docker コンテナを停止します。 + +```console +docker compose down +``` + +## 参照 + +このチュートリアルで使用されている電子マネーアプリケーションのソースコードを確認するには、[`ElectronicMoney.kt`](https://github.com/scalar-labs/scalardb-samples/blob/main/getting-started-kotlin/src/main/kotlin/sample/ElectronicMoney.kt) を参照してください。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/getting-started-with-scalardb.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/getting-started-with-scalardb.mdx new file mode 100644 index 00000000..fa3d9eba --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/getting-started-with-scalardb.mdx @@ -0,0 +1,537 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB をはじめよう + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +この入門チュートリアルでは、ScalarDB でデータベースを設定する方法について説明し、ScalarDB を使用してクレジットカードでアイテムを注文して支払うことができるサンプルの電子商取引アプリケーションを作成するプロセスを示します。サンプルの電子商取引アプリケーションでは、ユーザーがクレジットラインを使用してアイテムを注文して支払う方法を示します。 + +:::warning + +サンプルアプリケーションは ScalarDB の使用方法を示すことに重点を置いているため、アプリケーション固有のエラー処理、認証処理、および同様の機能はサンプルアプリケーションに含まれていません。ScalarDB での例外処理の詳細については、[例外の処理方法](api-guide.mdx#how-to-handle-exceptions)を参照してください。 + +::: + +## このサンプルアプリケーションの前提条件 + +ScalarDB は Java で記述されているため、環境に次のいずれかの Java Development Kit (JDK) がインストールされている必要があります。 + +- [Eclipse Temurin](https://adoptium.net/temurin/releases/) の OpenJDK LTS バージョン (8、11、17、または 21) +- [Docker](https://www.docker.com/get-started/) 20.10 以降と [Docker Compose](https://docs.docker.com/compose/install/) V2 以降 + +:::note + +このサンプルアプリケーションは、Eclipse Temurin の OpenJDK でテストされています。ただし、ScalarDB 自体は、さまざまなベンダーの JDK ディストリビューションでテストされています。互換性のある JDK ディストリビューションを含む ScalarDB の要件の詳細については、[要件](./requirements.mdx)を参照してください。 + +::: + +## ScalarDB サンプルリポジトリのクローンを作成する + +**Terminal** を開き、次のコマンドを実行して ScalarDB サンプルリポジトリのクローンを作成します。 + +```console +git clone https://github.com/scalar-labs/scalardb-samples +``` + +次に、次のコマンドを実行して、サンプルアプリケーションが含まれているディレクトリに移動します。 + +```console +cd scalardb-samples/scalardb-sample +``` + +## データベースをセットアップする + +データベースを選択し、指示に従って ScalarDB 用に設定します。 + +ScalarDB がサポートするデータベースの一覧については、[データベース](requirements.mdx#データベース)を参照してください。 + + + +

MySQLをローカルで実行する

+ + `scalardb-samples/scalardb-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で MySQL を実行できます。 + + MySQL を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d mysql + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の MySQL のプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For MySQL + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:mysql://localhost:3306/ + scalar.db.username=root + scalar.db.password=mysql + ``` + + +

PostgreSQL をローカルで実行する

+ + `scalardb-samples/scalardb-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で PostgreSQL を実行できます。 + + PostgreSQL を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d postgres + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の PostgreSQL のプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For PostgreSQL + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:postgresql://localhost:5432/ + scalar.db.username=postgres + scalar.db.password=postgres + ``` + + +

Oracle Database をローカルで実行する

+ + `scalardb-samples/scalardb-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で Oracle Database を実行できます。 + + Oracle Database を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d oracle + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の Oracle データベースのプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For Oracle + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:oracle:thin:@//localhost:1521/FREEPDB1 + scalar.db.username=SYSTEM + scalar.db.password=Oracle + ``` + + +

SQL Server をローカルで実行する

+ + `scalardb-samples/scalardb-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で SQL Server を実行できます。 + + SQL Server を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d sqlserver + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の SQL Server のプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For SQL Server + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:sqlserver://localhost:1433;encrypt=true;trustServerCertificate=true + scalar.db.username=sa + scalar.db.password=SqlServer22 + ``` + + +

Amazon DynamoDB をローカルで実行する

+ + `scalardb-samples/scalardb-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で Amazon DynamoDB Local を実行できます。 + + Amazon DynamoDB Local を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d dynamodb + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の Amazon DynamoDB Local のプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For DynamoDB Local + scalar.db.storage=dynamo + scalar.db.contact_points=sample + scalar.db.username=sample + scalar.db.password=sample + scalar.db.dynamo.endpoint_override=http://localhost:8000 + ``` + + + Azure Cosmos DB for NoSQL を使用するには、Azure アカウントが必要です。Azure アカウントをお持ちでない場合は、[Azure Cosmos DB アカウントを作成する](https://learn.microsoft.com/ja-jp/azure/cosmos-db/nosql/quickstart-portal#create-account)にアクセスしてください。 + +

Cosmos DB for NoSQL を設定する

+ + [既定の整合性レベルを構成する](https://learn.microsoft.com/ja-jp/azure/cosmos-db/nosql/how-to-manage-consistency#configure-the-default-consistency-level)の公式ドキュメントに従って、**既定の整合性レベル**を**強力**に設定します。 + +

ScalarDB を設定する

+ + 以下の手順では、ローカル環境に JDK が適切にインストールおよび設定されており、Azure で Cosmos DB for NoSQL アカウントが適切に設定されていることを前提としています。 + + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。`scalar.db.contact_points` と `scalar.db.password` の値は、説明に従って必ず変更してください。 + + ```properties + # For Cosmos DB + scalar.db.storage=cosmos + scalar.db.contact_points= + scalar.db.password= + ``` + +:::note + +Azure Cosmos DB アカウントのプライマリーキーまたはセカンダリキーを `scalar.db.password` の値として使用できます。 + +::: + + +

Cassandra をローカルで実行する

+ + `scalardb-samples/scalardb-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で Apache Cassandra を実行できます。 + + Apache Cassandra を起動するには、次のコマンドを実行します。 + ```console + docker compose up -d cassandra + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の Cassandra のプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For Cassandra + scalar.db.storage=cassandra + scalar.db.contact_points=localhost + scalar.db.username=cassandra + scalar.db.password=cassandra + ``` + + + +## データベーススキーマをロードする + +アプリケーションでデータベーススキーマ (データを整理する方法) を定義する必要があります。サポートされているデータ型の詳細については、[ScalarDB と他のデータベース間のデータ型マッピング](schema-loader.mdx#scalardb-と他のデータベース間のデータ型マッピング)を参照してください。 + +このチュートリアルでは、**schema.json** というファイルが `scalardb-samples/scalardb-sample` ディレクトリに既に存在します。スキーマを適用するには、[`scalardb` Releases](https://github.com/scalar-labs/scalardb/releases) ページに移動し、使用している ScalarDB のバージョンに一致する ScalarDB Schema Loader を `scalardb-samples/scalardb-sample` ディレクトリにダウンロードします。 + +次に、データベースに基づいて、`` をダウンロードした ScalarDB Schema Loader のバージョンに置き換えて、次のコマンドを実行します。 + + + + ```console + java -jar scalardb-schema-loader-.jar --config database.properties --schema-file schema.json --coordinator + ``` + +:::note + +`transaction` が `true` に設定されたテーブルがスキーマ内に存在するため、`--coordinator` オプションが指定されています。スキーマの設定とロードの詳細については、[ScalarDB Schema Loader](schema-loader.mdx) を参照してください。 + +::: + + + ```console + java -jar scalardb-schema-loader-.jar --config database.properties --schema-file schema.json --coordinator + ``` + +:::note + +`transaction` が `true` に設定されたテーブルがスキーマ内に存在するため、`--coordinator` オプションが指定されています。スキーマの設定とロードの詳細については、[ScalarDB Schema Loader](schema-loader.mdx) を参照してください。 + +::: + + + ```console + java -jar scalardb-schema-loader-.jar --config database.properties --schema-file schema.json --coordinator + ``` + +:::note + +`transaction` が `true` に設定されたテーブルがスキーマ内に存在するため、`--coordinator` オプションが指定されています。スキーマの設定とロードの詳細については、[ScalarDB Schema Loader](schema-loader.mdx) を参照してください。 + +::: + + + ```console + java -jar scalardb-schema-loader-.jar --config database.properties --schema-file schema.json --coordinator + ``` + +:::note + +`transaction` が `true` に設定されたテーブルがスキーマ内に存在するため、`--coordinator` オプションが指定されています。スキーマの設定とロードの詳細については、[ScalarDB Schema Loader](schema-loader.mdx) を参照してください。 + +::: + + + ```console + java -jar scalardb-schema-loader-.jar --config database.properties --schema-file schema.json --coordinator --no-backup --no-scaling + ``` + +:::note + +`transaction` が `true` に設定されたテーブルがスキーマ内に存在するため、`--coordinator` オプションが指定されています。スキーマの設定とロードの詳細については、[ScalarDB Schema Loader](schema-loader.mdx) を参照してください。 + +また、Amazon DynamoDB Local は継続的なバックアップと自動スケーリングをサポートしていないため、`--no-backup` および `--no-scaling` オプションが指定されています。 + +::: + + + ```console + java -jar scalardb-schema-loader-.jar --config database.properties --schema-file schema.json --coordinator + ``` + +:::note + +`transaction` が `true` に設定されたテーブルがスキーマ内に存在するため、`--coordinator` オプションが指定されています。スキーマの設定とロードの詳細については、[ScalarDB Schema Loader](schema-loader.mdx) を参照してください。 + +::: + + + ```console + java -jar scalardb-schema-loader-.jar --config database.properties --schema-file schema.json --coordinator --replication-factor=1 + ``` + +:::note + +`transaction` が `true` に設定されたテーブルがスキーマ内に存在するため、`--coordinator` オプションが指定されています。スキーマの設定とロードの詳細については、[ScalarDB Schema Loader](schema-loader.mdx) を参照してください。 + +また、`--replication-factor=1` オプションは Cassandra を使用する場合にのみ有効です。デフォルトのレプリケーション係数は `3` ですが、このチュートリアルではセットアップを容易にするために `1` が使用されているため、3 つのノードではなく 1 つのノードを持つクラスターを準備するだけで済みます。ただし、レプリケーション係数 `1` は本番環境には適していないことに注意してください。 + +::: + + + +### スキーマの詳細 + +サンプルアプリケーションの [`schema.json`](https://github.com/scalar-labs/scalardb-samples/tree/main/scalardb-sample/schema.json) に示されているように、すべてのテーブルは `sample` 名前空間に作成されます。 + +- `sample.customers`: 顧客情報を管理するテーブル + - `credit_limit`: 貸し手が顧客に信用枠から支出を許可する最大金額 + - `credit_total`: 顧客が信用枠から支出した金額 +- `sample.orders`: 注文情報を管理するテーブル +- `sample.statements`: 注文明細情報を管理するテーブル +- `sample.items`: 注文するアイテムの情報を管理するテーブル + +スキーマのエンティティ関係図は次のとおりです。 + +![ERD](images/getting-started-ERD.png) + +### 初期データをロードする + +サンプルアプリケーションを実行する前に、次のコマンドを実行して初期データをロードする必要があります。 + +```console +./gradlew run --args="LoadInitialData" +``` + +初期データがロードされた後、次のレコードがテーブルに保存される必要があります。 + +**`sample.customers` テーブル** + +| customer_id | name | credit_limit | credit_total | +|-------------|---------------|--------------|--------------| +| 1 | Yamada Taro | 10000 | 0 | +| 2 | Yamada Hanako | 10000 | 0 | +| 3 | Suzuki Ichiro | 10000 | 0 | + +**`sample.items` テーブル** + +| item_id | name | price | +|---------|--------|-------| +| 1 | Apple | 1000 | +| 2 | Orange | 2000 | +| 3 | Grape | 2500 | +| 4 | Mango | 5000 | +| 5 | Melon | 3000 | + +## サンプルアプリケーションでトランザクションを実行し、データを取得する + +次のセクションでは、サンプル電子商取引アプリケーションでトランザクションを実行し、データを取得する方法について説明します。 + +### 顧客情報を取得する + +まず、次のコマンドを実行して、ID が `1` である顧客に関する情報を取得します。 + +```console +./gradlew run --args="GetCustomerInfo 1" +``` + +次の出力が表示されます。 + +```console +... +{"id": 1, "name": "Yamada Taro", "credit_limit": 10000, "credit_total": 0} +... +``` + +### 注文する + +次に、次のコマンドを実行して、顧客 ID `1` にリンゴ 3 個とオレンジ 2 個を注文してもらいます。 + +:::note + +このコマンドの注文形式は `./gradlew run --args="PlaceOrder :,:,..."` です。 + +::: + +```console +./gradlew run --args="PlaceOrder 1 1:3,2:2" +``` + +以下のように、`order_id` の UUID が異なる、注文が成功したことを示す類似の出力が表示されます。 + +```console +... +{"order_id": "dea4964a-ff50-4ecf-9201-027981a1566e"} +... +``` + +### 注文の詳細を確認する + +次のコマンドを実行して注文の詳細を確認します。`` は、前のコマンドを実行した後に表示される `order_id` の UUID に置き換えます。 + +```console +./gradlew run --args="GetOrder " +``` + +`order_id` と `timestamp` の UUID が異なる、以下のような出力が表示されます。 + +```console +... +{"order": {"order_id": "dea4964a-ff50-4ecf-9201-027981a1566e","timestamp": 1650948340914,"customer_id": 1,"customer_name": "Yamada Taro","statement": [{"item_id": 1,"item_name": "Apple","price": 1000,"count": 3,"total": 3000},{"item_id": 2,"item_name": "Orange","price": 2000,"count": 2,"total": 4000}],"total": 7000}} +... +``` + +### 別の注文をする + +次のコマンドを実行して、顧客 ID `1` の `credit_total` の残額を使用してメロン 1 個を注文します。 + +```console +./gradlew run --args="PlaceOrder 1 5:1" +``` + +以下のように、`order_id` の UUID が異なる、注文が成功したことを示す類似の出力が表示されます。 + +```console +... +{"order_id": "bcc34150-91fa-4bea-83db-d2dbe6f0f30d"} +... +``` + +### 注文履歴を確認する + +次のコマンドを実行して、顧客 ID `1` のすべての注文履歴を取得します。 + +```console +./gradlew run --args="GetOrders 1" +``` + +`order_id` と `timestamp` の UUID が異なる以下のような出力が表示されます。これは、顧客 ID `1` のすべての注文履歴をタイムスタンプの降順で表示します。 + +```console +... +{"order": [{"order_id": "dea4964a-ff50-4ecf-9201-027981a1566e","timestamp": 1650948340914,"customer_id": 1,"customer_name": "Yamada Taro","statement": [{"item_id": 1,"item_name": "Apple","price": 1000,"count": 3,"total": 3000},{"item_id": 2,"item_name": "Orange","price": 2000,"count": 2,"total": 4000}],"total": 7000},{"order_id": "bcc34150-91fa-4bea-83db-d2dbe6f0f30d","timestamp": 1650948412766,"customer_id": 1,"customer_name": "Yamada Taro","statement": [{"item_id": 5,"item_name": "Melon","price": 3000,"count": 1,"total": 3000}],"total": 3000}]} +... +``` + +### クレジット合計を確認する + +次のコマンドを実行して、顧客 ID `1` のクレジット合計を取得します。 + +```console +./gradlew run --args="GetCustomerInfo 1" +``` + +次の出力が表示されます。これは、顧客 ID `1` が `credit_total` の `credit_limit` に達しており、これ以上注文できないことを示しています。 + +```console +... +{"id": 1, "name": "Yamada Taro", "credit_limit": 10000, "credit_total": 10000} +... +``` + +次のコマンドを実行して、ブドウ 1 個とマンゴー 1 個を注文してみます。 + +```console +./gradlew run --args="PlaceOrder 1 3:1,4:1" +``` + +次の出力が表示されます。これは、`credit_total` 金額が `credit_limit` 金額を超えたために注文が失敗したことを示しています。 + +```console +... +java.lang.RuntimeException: Credit limit exceeded + at sample.Sample.placeOrder(Sample.java:205) + at sample.command.PlaceOrderCommand.call(PlaceOrderCommand.java:33) + at sample.command.PlaceOrderCommand.call(PlaceOrderCommand.java:8) + at picocli.CommandLine.executeUserObject(CommandLine.java:1783) + at picocli.CommandLine.access$900(CommandLine.java:145) + at picocli.CommandLine$RunLast.handle(CommandLine.java:2141) + at picocli.CommandLine$RunLast.handle(CommandLine.java:2108) + at picocli.CommandLine$AbstractParseResultHandler.execute(CommandLine.java:1975) + at picocli.CommandLine.execute(CommandLine.java:1904) + at sample.command.SampleCommand.main(SampleCommand.java:35) +... +``` + +### 支払いを行う + +注文を続行するには、顧客 ID `1` が支払いを行って `credit_total` の金額を減らす必要があります。 + +次のコマンドを実行して支払いを行います。 + +```console +./gradlew run --args="Repayment 1 8000" +``` + +次に、次のコマンドを実行して、顧客 ID `1` の `credit_total` 金額を確認します。 + +```console +./gradlew run --args="GetCustomerInfo 1" +``` + +次の出力が表示されます。これは、顧客 ID `1` に支払いが適用され、`credit_total` の金額が減ったことを示しています。 + +```console +... +{"id": 1, "name": "Yamada Taro", "credit_limit": 10000, "credit_total": 2000} +... +``` + +顧客 ID `1` が支払いを済ませたので、次のコマンドを実行してブドウ 1 個とメロン 1 個を注文します。 + +```console +./gradlew run --args="PlaceOrder 1 3:1,4:1" +``` + +以下のように、`order_id` の UUID が異なる、注文が成功したことを示す類似の出力が表示されます。 + +```console +... +{"order_id": "8911cab3-1c2b-4322-9386-adb1c024e078"} +... +``` + +## データベースを停止する + +データベースを停止するには、次のコマンドを実行して Docker コンテナを停止します。 + +```console +docker compose down +``` + +## 参照 + +このチュートリアルで使用される電子商取引アプリケーションのソースコードを確認するには、[`Sample.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/scalardb-sample/src/main/java/sample/Sample.java) を参照してください。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/data_model.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/data_model.png new file mode 100644 index 00000000..15a0e4d4 Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/data_model.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/getting-started-ERD.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/getting-started-ERD.png new file mode 100644 index 00000000..1a6d13c5 Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/getting-started-ERD.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/scalardb-architecture.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/scalardb-architecture.png new file mode 100644 index 00000000..c44efa81 Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/scalardb-architecture.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/scalardb.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/scalardb.png new file mode 100644 index 00000000..658486cb Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/scalardb.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/scalardb_data_model.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/scalardb_data_model.png new file mode 100644 index 00000000..7a02fa23 Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/scalardb_data_model.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/software_stack.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/software_stack.png new file mode 100644 index 00000000..75fba6e6 Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/software_stack.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/two_phase_commit_load_balancing.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/two_phase_commit_load_balancing.png new file mode 100644 index 00000000..5cdc26f0 Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/two_phase_commit_load_balancing.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/two_phase_commit_sequence_diagram.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/two_phase_commit_sequence_diagram.png new file mode 100644 index 00000000..116ef635 Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/images/two_phase_commit_sequence_diagram.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/manage-backup-and-restore.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/manage-backup-and-restore.mdx new file mode 100644 index 00000000..7244e655 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/manage-backup-and-restore.mdx @@ -0,0 +1,26 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# データベースのバックアップと復元 + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このガイドでは、ScalarDB で使用されるデータベースのバックアップと復元の方法について説明します。 + +## データベースのバックアップと復元の基本ガイドライン + +バックアップを実行する前に、[ScalarDB で使用されるデータベースのバックアップと復元方法](backup-restore.mdx)を必ずお読みください。 + +## Kubernetes 環境で ScalarDB を使用する場合のデータベースのバックアップ + +Kubernetes 環境でデータベースをバックアップする方法の詳細については、[Kubernetes 環境で NoSQL データベースをバックアップする](scalar-kubernetes/BackupNoSQL.mdx)を参照してください。 + +## Kubernetes 環境で ScalarDB を使用する場合のデータベースの復元 + +Kubernetes 環境でデータベースを復元する方法の詳細については、[Kubernetes 環境でデータベースを復元する](scalar-kubernetes/RestoreDatabase.mdx)を参照してください。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/monitor-by-using-scalar-manager.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/monitor-by-using-scalar-manager.mdx new file mode 100644 index 00000000..b119280e --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/monitor-by-using-scalar-manager.mdx @@ -0,0 +1,24 @@ +--- +tags: + - Enterprise Option +--- + +# Scalar Manager を使用して ScalarDB を監視する + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +Scalar Manager は、Kubernetes クラスター環境内の ScalarDB の集中管理および監視ソリューションであり、次のことが可能になります。 + +- ScalarDB の可用性を確認します。 +- ScalarDB が使用するデータベースでトランザクションの一貫性のある期間を作成する一時停止ジョブをスケジュールまたは実行します。 +- Grafana ダッシュボードを介して ScalarDB の時系列メトリックとログを確認します。 + +Scalar Manager の詳細については、[Scalar Manager 概要](scalar-manager/overview.mdx)を参照してください。 + +## Scalar Manager をデプロイする + +Helm Chart を使用して Scalar Manager をデプロイできます。 + +Scalar Manager をデプロイする方法の詳細については、[Scalar Manager のデプロイする方法](helm-charts/how-to-deploy-scalar-manager.mdx)を参照してください。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/multi-storage-transactions.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/multi-storage-transactions.mdx new file mode 100644 index 00000000..3065a4f6 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/multi-storage-transactions.mdx @@ -0,0 +1,71 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# マルチストレージトランザクション + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +ScalarDB トランザクションは、*マルチストレージトランザクション* と呼ばれる機能を使用することで、ACID 準拠を維持しながら複数のストレージまたはデータベースにまたがることができます。 + +このページでは、マルチストレージトランザクションの仕組みと、ScalarDB でこの機能を設定する方法について説明します。 + +## ScalarDB でのマルチストレージトランザクションの仕組み + +ScalarDB では、`マルチストレージ` 実装は複数のストレージインスタンスを保持し、名前空間名から適切なストレージインスタンスへのマッピングを持っています。操作が実行されると、マルチストレージトランザクション機能は、名前空間ストレージマッピングを使用して指定された名前空間から適切なストレージインスタンスを選択し、そのストレージインスタンスを使用します。 + +## マルチストレージトランザクションをサポートするように ScalarDB を設定する方法 + +マルチストレージトランザクションを有効にするには、`scalar.db.transaction_manager` の値として `consensus-commit` を指定し、`scalar.db.storage` の値として `multi-storage` を指定し、ScalarDB プロパティファイルでデータベースを設定する必要があります。 + +以下は、マルチストレージトランザクションの設定例です。 + +```properties +# Consensus Commit is required to support multi-storage transactions. +scalar.db.transaction_manager=consensus-commit + +# Multi-storage implementation is used for Consensus Commit. +scalar.db.storage=multi-storage + +# Define storage names by using a comma-separated format. +# In this case, "cassandra" and "mysql" are used. +scalar.db.multi_storage.storages=cassandra,mysql + +# Define the "cassandra" storage. +# When setting storage properties, such as `storage`, `contact_points`, `username`, and `password`, for multi-storage transactions, the format is `scalar.db.multi_storage.storages..`. +# For example, to configure the `scalar.db.contact_points` property for Cassandra, specify `scalar.db.multi_storage.storages.cassandra.contact_point`. +scalar.db.multi_storage.storages.cassandra.storage=cassandra +scalar.db.multi_storage.storages.cassandra.contact_points=localhost +scalar.db.multi_storage.storages.cassandra.username=cassandra +scalar.db.multi_storage.storages.cassandra.password=cassandra + +# Define the "mysql" storage. +# When defining JDBC-specific configurations for multi-storage transactions, you can follow a similar format of `scalar.db.multi_storage.storages..`. +# For example, to configure the `scalar.db.jdbc.connection_pool.min_idle` property for MySQL, specify `scalar.db.multi_storage.storages.mysql.jdbc.connection_pool.min_idle`. +scalar.db.multi_storage.storages.mysql.storage=jdbc +scalar.db.multi_storage.storages.mysql.contact_points=jdbc:mysql://localhost:3306/ +scalar.db.multi_storage.storages.mysql.username=root +scalar.db.multi_storage.storages.mysql.password=mysql +# Define the JDBC-specific configurations for the "mysql" storage. +scalar.db.multi_storage.storages.mysql.jdbc.connection_pool.min_idle=5 +scalar.db.multi_storage.storages.mysql.jdbc.connection_pool.max_idle=10 +scalar.db.multi_storage.storages.mysql.jdbc.connection_pool.max_total=25 + +# Define namespace mapping from a namespace name to a storage. +# The format is ":,...". +scalar.db.multi_storage.namespace_mapping=user:cassandra,coordinator:mysql + +# Define the default storage that's used if a specified table doesn't have any mapping. +scalar.db.multi_storage.default_storage=cassandra +``` + +追加の設定については、[ScalarDB 設定](configurations.mdx)を参照してください。 + +## 実践的なチュートリアル + +実践的なチュートリアルについては、[マルチストレージトランザクションをサポートするサンプルアプリケーションを作成する](scalardb-samples/multi-storage-transaction-sample/README.mdx)を参照してください。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/overview.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/overview.mdx new file mode 100644 index 00000000..bd025d9a --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/overview.mdx @@ -0,0 +1,81 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB の概要 + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このページでは、ScalarDB の概要と主な使用例について説明します。 + +## ScalarDB とは + +ScalarDB は、さまざまなデータベース向けのハイブリッドトランザクション/分析処理 (HTAP) エンジンです。データベース上でミドルウェアとして実行され、ACID トランザクションとリアルタイム分析を実現することでさまざまなデータベースを仮想的に統合し、複数のデータベースまたは単一のデータベースの複数のインスタンスの管理の複雑さを簡素化します。 + +![ScalarDB が複雑なデータ管理アーキテクチャを簡素化する方法。](images/scalardb.png) + +多用途のソリューションである ScalarDB は、次のようなさまざまなデータベースをサポートしています。 + +- MariaDB、Microsoft SQL Server、MySQL、Oracle Database、PostgreSQL、SQLite などの JDBC をサポートするリレーショナルデータベース、および Amazon Aurora、Google AlloyDB、TiDB、YugabyteDB などの互換性のあるデータベース。 +- Amazon DynamoDB、Apache Cassandra、Azure Cosmos DB などの NoSQL データベース。 + +ScalarDB がサポートするデータベースの詳細については、[データベース](requirements.mdx#データベース) を参照してください。 + +## ScalarDB を選ぶ理由 + +グローバルトランザクションマネージャー、データフェデレーションエンジン、HTAP システムなどのいくつかのソリューションは、同様の目標を持っていますが、次の観点で制限があります。 + +- グローバルトランザクションマネージャー (Oracle MicroTx や Atomikos など) は、限られた異種データベースセット (XA 準拠のデータベースのみなど) でトランザクションを実行するように設計されています。 +- データフェデレーションエンジン (Denodo や Starburst など) は、異種データベースで分析クエリを実行するように設計されています。 +- HTAP システム (TiDB や SingleStore など) は、同種データベースでのみトランザクションと分析クエリの両方を実行します。 + +言い換えれば、これらはデータベースを仮想的に統合しますが、制限があります。たとえば、データフェデレーションエンジンを使用すると、ユーザーは複数のデータベースにまたがる仮想ビューで読み取り専用の分析クエリを実行できます。ただし、多くの場合、データベースごとに更新クエリを個別に実行する必要があります。 + +他のソリューションとは異なり、ScalarDB は、異種データベースでトランザクションクエリと分析クエリの両方を実行できる機能を備えているため、データベース管理を大幅に簡素化できます。 + +次の表は、ScalarDB が他のソリューションとどのように異なるかをまとめたものです。 + +| | 異種データベース間のトランザクション | 異種データベース間の分析 | +| :--------------------------------------------------------------: | :----------------------------------------------------------------------------: | :--------------------------------: | +| グローバルトランザクションマネージャー (Oracle MicroTx や Atomikos など) | はい（ただし、既存のソリューションでは限られたデータベースのセットしかサポートされていません） | いいえ | +| データフェデレーションエンジン (Denodo や Starburst など) | いいえ | はい | +| HTAP システム (TiDB や SingleStore など) | いいえ (同種のデータベースのみサポート) | いいえ (同種のデータベースのみサポート) | +| **ScalarDB** | **はい (各種データベースに対応)** | **はい** | + +## ScalarDB の使用例 + +ScalarDB はさまざまな用途で使用できます。ScalarDB の主な使用例を 3 つ紹介します。 + +### サイロ化されたデータベースを簡単に管理 + +多くの企業は、アジャイルなビジネスオペレーションをサポートするために複数の組織、部門、ビジネスユニットで構成されており、その結果、サイロ化された情報システムになることがよくあります。特に、異なる組織では、異なるデータベースを使用して異なるアプリケーションを管理する可能性があります。このようなサイロ化されたデータベースの管理は、アプリケーションが各データベースと個別に通信し、データベース間の違いを適切に処理する必要があるため、困難です。 + +ScalarDB は、統一されたインターフェイスを使用してサイロ化されたデータベースの管理を簡素化し、ユーザーがデータベースを 1 つのデータベースのように扱えるようにします。たとえば、ユーザーは複数のデータベースに対して (分析的な) 結合クエリを、それぞれのデータベースとやり取りすることなく実行できます。 + +### 複数のデータベース間の一貫性の管理 + +マイクロサービスアーキテクチャなどの最新のアーキテクチャでは、システムでサービスとそのデータベースを小さなサブセットに分割して、システムのモジュール性と開発効率を高めることが推奨されています。しかし、多様なデータベース、特に異なる種類のデータベースを管理するのは困難です。なぜなら、Saga や TCC などのトランザクション管理パターンを使用しても、アプリケーションはそれらのデータベースの正しい状態 (言い換えれば一貫性) を保証する必要があるからです。 + +ScalarDB は、正確性の保証 (言い換えれば、厳密なシリアル化可能性を備えた ACID) によって、このような多様なデータベースの管理を簡素化します。これにより、データベース間の一貫性の保証を気にすることなく、アプリケーション開発に集中できます。 + +### データメッシュでのデータ管理の簡素化 + +企業は、データ利用を合理化および拡張するために、[データメッシュ](https://martinfowler.com/articles/data-mesh-principles.html)の構築に時間を費やしてきました。ただし、データメッシュの構築は必ずしも簡単ではありません。たとえば、分散データの管理方法には多くの技術的な問題があります。 + +ScalarDB は、データメッシュ内のすべてのデータベースに統一された API を提供することで、データメッシュ内の分散データベースの管理を簡素化し「データをプロダクトとして扱う（Data as a Product）」という原則に簡単に適合させます。 + +### データベース移行のハードルを下げる + +アプリケーションは、データベースが提供する特定の機能のために、特定のデータベースを使用するようにロックされる傾向があります。このようなデータベースロックインにより、データベースのアップグレードや変更が妨げられます。アップグレードや変更を行うには、多くの場合、アプリケーションの書き直しが必要になるからです。 + +ScalarDB は、多様なデータベースに統一されたインターフェイスを提供します。したがって、ScalarDB インターフェイスを使用してアプリケーションを作成すると、そのアプリケーションは移植可能になり、アプリケーションを書き直すことなくシームレスなデータベース移行を実現できます。 + +## さらに読む + +- [ScalarDB Technical Overview](https://speakerdeck.com/scalar/scalar-db-universal-transaction-manager) +- [ScalarDB Research Paper [VLDB'23]](https://dl.acm.org/doi/10.14778/3611540.3611563) \ No newline at end of file diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/quick-start-overview.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/quick-start-overview.mdx new file mode 100644 index 00000000..09d1364c --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/quick-start-overview.mdx @@ -0,0 +1,39 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# クイックスタート + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このカテゴリでは、ScalarDB を介してトランザクションとクエリの実行を開始する方法についてのクイックスタートチュートリアルに従うことができます。 + +## ScalarDB コアライブラリを介してトランザクションを実行してみる + +このサブカテゴリでは、Apache 2 ライセンスの下で公開されている ScalarDB コアライブラリを介して ACID トランザクションを実行する方法に関するチュートリアルに従うことができます。 + +## ScalarDB Cluster を介してトランザクションを実行してみる + +このサブカテゴリでは、ScalarDB コアライブラリをラップする [gRPC](https://grpc.io/) サーバーである ScalarDB Cluster を介して ACID トランザクションを実行する方法に関するチュートリアルを参照できます。 + +:::note + +ScalarDB Cluster は Enterprise エディションでのみ利用できます。 + +::: + +## ScalarDB Analytics で分析クエリを実行してみる + +このサブカテゴリでは、ScalarDB Analytics というコンポーネントを使用して、ScalarDB で作成したデータベースに対して分析クエリを実行する方法に関するチュートリアルを参照できます。ScalarDB Analytics は、ScalarDB トランザクションを通じて更新される ScalarDB 管理データベースと、ScalarDB 管理以外のデータベースの両方を対象とします。 + +:::note + +- ScalarDB Analytics with PostgreSQL は Apache 2 ライセンスでのみ利用可能で、商用ライセンスは必要ありません。 +- ScalarDB Analytics with Spark はパブリックプレビュー中です。 + +::: diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/requirements.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/requirements.mdx new file mode 100644 index 00000000..43ce5f29 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/requirements.mdx @@ -0,0 +1,246 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB の要件 + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このページでは、ScalarDB を正しく使用するために必要なツールとそのバージョンについて説明します。 + +## クライアント SDK + +ScalarDB は Java で記述されているため、ScalarDB を操作する最も簡単な方法は、Java Client SDK を使用することです。 + +- [ScalarDB Core 用 SDK](add-scalardb-to-your-build.mdx) +- [ScalarDB Cluster 用 SDK](scalardb-cluster/developer-guide-for-scalardb-cluster-with-java-api.mdx) + +### Java + +次の Java Software Development (JDK) が検証され、サポートされています。 + +- **[Oracle JDK](https://www.oracle.com/java/):** 8、11、17、または 21 (LTS バージョン) +- **[OpenJDK](https://openjdk.org/) ([Eclipse Temurin](https://adoptium.net/temurin/)、[Amazon Corretto](https://aws.amazon.com/corretto/)、または [Microsoft Build of OpenJDK](https://learn.microsoft.com/en-us/java/openjdk/)):** 8、11、17、または 21 (LTS バージョン) + +### .NET + +ScalarDB は、ScalarDB Cluster と呼ばれる gRPC サーバーとして提供され、proto ファイルから生成された .NET クライアントをラップする [.NET Client SDK](scalardb-cluster-dotnet-client-sdk/overview.mdx) も備えています。 + +次の .NET バージョンが検証され、サポートされています。 + +- [.NET 8.0](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) +- [.NET 6.0](https://dotnet.microsoft.com/en-us/download/dotnet/6.0) + +### その他の言語 + +ScalarDB Cluster は gRPC バージョン 1.65.0 を使用するため、好みの言語で生成されたクライアントを使用して独自のクライアントを作成できます。 + +## データベース + +ScalarDB は、次のデータベースとそのバージョン上で実行されるミドルウェアです。 + +### リレーショナルデータベース + + + + +| バージョン | Oracle Database 23ai | Oracle Database 21c | Oracle Database 19c | +|:------------------|:---------------------|:--------------------|:--------------------| +| **ScalarDB 3.14** | ✅ | ✅ | ✅ | +| **ScalarDB 3.13** | ✅ | ✅ | ✅ | +| **ScalarDB 3.12** | ✅ | ✅ | ✅ | +| **ScalarDB 3.11** | ✅ | ✅ | ✅ | +| **ScalarDB 3.10** | ✅ | ✅ | ✅ | +| **ScalarDB 3.9** | ✅ | ✅ | ✅ | +| **ScalarDB 3.8** | ✅ | ✅ | ✅ | +| **ScalarDB 3.7** | ✅ | ✅ | ✅ | + + + + +| バージョン | MySQL 8.1 | MySQL 8.0 | MySQL 5.7 | +|:------------------|:----------|:----------|:----------| +| **ScalarDB 3.14** | ✅ | ✅ | ✅ | +| **ScalarDB 3.13** | ✅ | ✅ | ✅ | +| **ScalarDB 3.12** | ✅ | ✅ | ✅ | +| **ScalarDB 3.11** | ✅ | ✅ | ✅ | +| **ScalarDB 3.10** | ✅ | ✅ | ✅ | +| **ScalarDB 3.9** | ✅ | ✅ | ✅ | +| **ScalarDB 3.8** | ✅ | ✅ | ✅ | +| **ScalarDB 3.7** | ✅ | ✅ | ✅ | + + + + +| バージョン | PostgreSQL 15 | PostgreSQL 14 | PostgreSQL 13 | PostgreSQL 12 | +|:------------------|:--------------|:--------------|:--------------|:--------------| +| **ScalarDB 3.14** | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.13** | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.12** | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.11** | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.10** | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.9** | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.8** | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.7** | ✅ | ✅ | ✅ | ✅ | + + + + +| バージョン | Aurora MySQL 3 | Aurora MySQL 2 | +|:------------------|:---------------|:---------------| +| **ScalarDB 3.14** | ✅ | ✅ | +| **ScalarDB 3.13** | ✅ | ✅ | +| **ScalarDB 3.12** | ✅ | ✅ | +| **ScalarDB 3.11** | ✅ | ✅ | +| **ScalarDB 3.10** | ✅ | ✅ | +| **ScalarDB 3.9** | ✅ | ✅ | +| **ScalarDB 3.8** | ✅ | ✅ | +| **ScalarDB 3.7** | ✅ | ✅ | + + + + +| バージョン | Aurora PostgreSQL 15 | Aurora PostgreSQL 14 | Aurora PostgreSQL 13 | Aurora PostgreSQL 12 | +|:------------------|:---------------------|:---------------------|:---------------------|:---------------------| +| **ScalarDB 3.14** | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.13** | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.12** | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.11** | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.10** | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.9** | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.8** | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.7** | ✅ | ✅ | ✅ | ✅ | + + + + +| バージョン | MariaDB 11.4 | MariaDB 10.11 | +|:------------------|:-------------|:--------------| +| **ScalarDB 3.14** | ✅ | ✅ | +| **ScalarDB 3.13** | ✅ | ✅ | +| **ScalarDB 3.12** | ✅ | ✅ | +| **ScalarDB 3.11** | ✅ | ✅ | +| **ScalarDB 3.10** | ✅ | ✅ | +| **ScalarDB 3.9** | ✅ | ✅ | +| **ScalarDB 3.8** | ✅ | ✅ | +| **ScalarDB 3.7** | ✅ | ✅ | + + + + +| バージョン | SQL Server 2022 | SQL Server 2019 | SQL Server 2017 | +|:------------------|:----------------|:----------------|:----------------| +| **ScalarDB 3.14** | ✅ | ✅ | ✅ | +| **ScalarDB 3.13** | ✅ | ✅ | ✅ | +| **ScalarDB 3.12** | ✅ | ✅ | ✅ | +| **ScalarDB 3.11** | ✅ | ✅ | ✅ | +| **ScalarDB 3.10** | ✅ | ✅ | ✅ | +| **ScalarDB 3.9** | ✅ | ✅ | ✅ | +| **ScalarDB 3.8** | ✅ | ✅ | ✅ | +| **ScalarDB 3.7** | ✅ | ✅ | ✅ | + + + + +| バージョン | SQLite 3 | +|:------------------|:---------| +| **ScalarDB 3.14** | ✅ | +| **ScalarDB 3.13** | ✅ | +| **ScalarDB 3.12** | ✅ | +| **ScalarDB 3.11** | ✅ | +| **ScalarDB 3.10** | ✅ | +| **ScalarDB 3.9** | ✅ | +| **ScalarDB 3.8** | ❌ | +| **ScalarDB 3.7** | ❌ | + + + + +| バージョン | YugabyteDB 2 | +|:------------------|:-------------| +| **ScalarDB 3.14** | ✅ | +| **ScalarDB 3.13** | ✅ | +| **ScalarDB 3.12** | ❌ | +| **ScalarDB 3.11** | ❌ | +| **ScalarDB 3.10** | ❌ | +| **ScalarDB 3.9** | ❌ | +| **ScalarDB 3.8** | ❌ | +| **ScalarDB 3.7** | ❌ | + + + + +### NoSQL データベース + + + + +| バージョン | DynamoDB | +|:------------------|:---------| +| **ScalarDB 3.14** | ✅ | +| **ScalarDB 3.13** | ✅ | +| **ScalarDB 3.12** | ✅ | +| **ScalarDB 3.11** | ✅ | +| **ScalarDB 3.10** | ✅ | +| **ScalarDB 3.9** | ✅ | +| **ScalarDB 3.8** | ✅ | +| **ScalarDB 3.7** | ✅ | + + + + +| バージョン | Cassandra 4.1 | Cassandra 4.0 | Cassandra 3.11 | Cassandra 3.0 | +|:------------------|:--------------|:--------------|:---------------|:--------------| +| **ScalarDB 3.14** | ❌ | ❌ | ✅ | ✅ | +| **ScalarDB 3.13** | ❌ | ❌ | ✅ | ✅ | +| **ScalarDB 3.12** | ❌ | ❌ | ✅ | ✅ | +| **ScalarDB 3.11** | ❌ | ❌ | ✅ | ✅ | +| **ScalarDB 3.10** | ❌ | ❌ | ✅ | ✅ | +| **ScalarDB 3.9** | ❌ | ❌ | ✅ | ✅ | +| **ScalarDB 3.8** | ❌ | ❌ | ✅ | ✅ | +| **ScalarDB 3.7** | ❌ | ❌ | ✅ | ✅ | + + + + +| バージョン | Cosmos DB for NoSQL | +|:------------------|:--------------------| +| **ScalarDB 3.14** | ✅ | +| **ScalarDB 3.13** | ✅ | +| **ScalarDB 3.12** | ✅ | +| **ScalarDB 3.11** | ✅ | +| **ScalarDB 3.10** | ✅ | +| **ScalarDB 3.9** | ✅ | +| **ScalarDB 3.8** | ✅ | +| **ScalarDB 3.7** | ✅ | + + + + +:::note + +各データベースの設定方法の詳細については、[ScalarDB の基盤となるデータベースの設定](./database-configurations.mdx) を参照してください。 + +::: + +## Kubernetes + +ScalarDB は、本番環境では Kubernetes プラットフォーム上の Pod として提供されます。ScalarDB は次のプラットフォームとツールをサポートしています。 + +### プラットフォーム + +- **[Kubernetes](https://kubernetes.io/):** 1.27 - 1.31 + - **[Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/jp/eks/)** + - **[Azure Kubernetes Service (AKS)](https://azure.microsoft.com/ja-jp/products/kubernetes-service)** +- **[Red Hat OpenShift](https://www.redhat.com/en/technologies/cloud-computing/openshift):** TBD + +### パッケージマネージャー + +- **[Helm](https://helm.sh/):** 3.5+ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/roadmap.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/roadmap.mdx new file mode 100644 index 00000000..11aeaab8 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/roadmap.mdx @@ -0,0 +1,96 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB ロードマップ + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このロードマップは、ScalarDB の今後の計画の概要を示しています。このロードマップの目的は、今後どのような変更が行われる可能性があるかを把握できるようにし、進捗状況をより詳しく追跡し、主要なマイルストーンを把握し、開発中にフィードバックを提供することです。このロードマップは、ScalarDB の新しいバージョンがリリースされるたびに更新されます。 + +:::warning + +開発の過程で、このロードマップはユーザーのニーズやフィードバックに基づいて変更される可能性があります。**このロードマップの内容に従ってリリース計画をスケジュールしないでください。** + +機能リクエストがある場合、または機能開発を優先したい場合は、[GitHub](https://github.com/scalar-labs/scalardb/issues) で問題を作成してください。 + +::: + +### CY2024 Q4 + +#### 新しい機能 + +- **分析のためのデータ仮想化** + - ユーザーは、ScalarDB Analytics を介してさまざまなデータソースで読み取り専用の OLAP SQL クエリを実行できるようになります。ScalarDB Analytics は現在、ScalarDB 管理のデータストアのみをサポートしているため、この機能強化により、データソースが ScalarDB トランザクションによって管理されているかどうかに関係なく、リレーショナルデータベースや NoSQL データベースなどのさまざまなデータストアと、Amazon S3 などのクラウドオブジェクトストア内のファイルが仮想的に統合されます。 +- **ベクトルストアの抽象化** + - ユーザーは、ScalarDB の新しいベクトルストアインターフェイスを介して、ベクトルストアに埋め込み (ベクトル) を保存したり、ベクトルストアから埋め込みを検索したりできるようになります。この機能により、ユーザーは、既存の ScalarDB インターフェイスを介してデータベースからデータを読み取り、データから埋め込みを作成し、新しいインターフェイスを介してベクトルストアに埋め込みを保存したり、ベクトルストアから埋め込みを検索したりすることで、大規模言語モデル (LLM) を使用した検索拡張生成 (RAG) を実現するプロセスを簡素化できます。 + +#### セキュリティ + +- **きめ細かなアクセス制御** + - ユーザーは、基盤となるデータベースへのアクセスをよりきめ細かに承認できるようになります。ScalarDB は、ユーザーが特定の操作を発行する権限を持っているかどうかを確認する現在の単純な承認に加えて、ユーザーが特定のレコードにアクセスできるかどうかも確認します。 + +#### ユーザビリティ + +- **時間関連のデータ型の追加** + - ユーザーは時間関連のデータ型を使用できるようになり、既存のアプリケーションの移行が容易になります。 +- **追加書き込み戦略の削除** + - ユーザーは、トランザクションをシリアル化可能にするために追加書き込み戦略を使用できなくなります。ScalarDB は現在、トランザクションをシリアル化可能にするために追加読み取り戦略と追加書き込み戦略の 2 つの戦略を提供していますが、追加書き込み戦略にはいくつかの制限があります。たとえば、ユーザーは同じトランザクションで書き込み操作とスキャン操作を発行できません。したがって、この戦略は削除され、ユーザーはアプリケーションを作成するときにこのような制限を心配する必要がなくなります。 + +#### パフォーマンス + +- **1 フェーズコミットの最適化** + - ユーザーは、単一のパーティションに書き込む単純なトランザクションの実行速度が速くなります。ScalarDB は、基礎となるデータベースの単一パーティション線形化可能な操作を利用して、トランザクションが 1 つのパーティションのみを更新する場合、正確さを犠牲にすることなく、レコード準備フェーズとコミット状態フェーズを省略します。 +- **ScalarDB メタデータの管理に必要なストレージ領域の削減** + - ユーザーは、ScalarDB を実行するために使用するストレージ領域が少なくなる可能性があります。ScalarDB は、コミットされたトランザクションがコミットされた後に、コミット前のイメージを削除します。ただし、コミットされたトランザクションが実際のストレージ領域に影響を与えるかどうかは、基礎となるデータベースによって異なります。 +- **読み取り専用トランザクションのコーディネータ書き込みの削除** + - 読み取り専用トランザクションのコーディネータ書き込みを削除することで、ユーザーは読み取り専用トランザクションの実行速度が向上します。 + +#### クラウドサポート + +- **Azure Marketplace でのコンテナオファリング** + - ユーザーは、Azure コンテナオファリングを使用して ScalarDB Cluster をデプロイできるようになります。これにより、ユーザーは従量課金制のサブスクリプションモデルを利用できるようになります。 +- **Google Cloud Platform (GCP) のサポート** + - ユーザーは、GCP の Google Kubernetes Engine (GKE) に ScalarDB Cluster をデプロイできるようになります。 + +### CY2025 Q1 + +#### 新しい機能 + +- **ネイティブセカンダリインデックス** + - ユーザーは柔軟なセカンダリインデックスを定義できるようになります。既存のセカンダリインデックスは、サポートされているデータベースのセカンダリインデックスの共通機能に基づいて実装されているため、制限があります。したがって、たとえば、複数列のインデックスを定義することはできません。新しいセカンダリインデックスは ScalarDB レイヤーで作成されるため、複数列のインデックスなど、より柔軟なインデックスを作成できます。 + +#### ユーザビリティ + +- **集計用の SQL 操作の追加** + - ユーザーは ScalarDB SQL で集計操作を発行できるようになります。 +- **大規模なスキャンによるメモリ不足エラーの排除** + - ユーザーはメモリ不足エラーを経験することなく大規模なスキャンを発行できるようになります。 +- **一時停止期間中の読み取り操作の有効化** + - ユーザーは一時停止期間中でも読み取り操作を発行できるため、バックアップを取りながらデータを読み取ることができます。 +- **より多くのデータタイプの追加** + - ユーザーはより多くのデータタイプを使用できるようになるため、既存のアプリケーションの移行が容易になります。 + +### CY2025 Q2 - + +#### ユーザビリティ + +- **ビュー** + - ユーザーはビューを定義して、複数の異なるデータベースをより簡単かつ簡素化された方法で管理できるようになります。 + +#### スケーラビリティと可用性 + +- **半同期レプリケーション** + - ユーザーは、災害復旧可能な方法で ScalarDB ベースのアプリケーションを提供できます。たとえば、東京でプライマリサービスを提供し、大阪でスタンバイサービスを提供するとします。東京で壊滅的な障害が発生した場合、プライマリサービスを大阪に切り替えることで、データ損失や長時間のダウンタイムなしにサービスを継続できます。 + +#### クラウドサポート + +- **Red Hat OpenShift のサポート** + - ユーザーは、OpenShift 環境で ScalarDB Cluster 用の Red Hat 認定 Helm Charts を使用できるようになります。 +- **Google Cloud Marketplace でのコンテナの提供** + - ユーザーは、Google Cloud コンテナの提供を使用して ScalarDB Cluster をデプロイできるようになります。これにより、ユーザーは従量課金制のサブスクリプションモデルを利用できるようになります。 \ No newline at end of file diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/run-non-transactional-storage-operations-through-library.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/run-non-transactional-storage-operations-through-library.mdx new file mode 100644 index 00000000..c8ff048e --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/run-non-transactional-storage-operations-through-library.mdx @@ -0,0 +1,274 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# コアライブラリを通じて非トランザクションストレージ操作を実行する + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このガイドでは、ScalarDB コアライブラリを通じて非トランザクションストレージ操作を実行する方法について説明します。 + +## 準備 + +このガイドでは、ScalarDB サンプルリポジトリのサンプルを使用して、データベースと ScalarDB をセットアップします。 + +### ScalarDB サンプルリポジトリのクローンを作成する + +**Terminal** を開き、次のコマンドを実行して ScalarDB サンプル リポジトリのクローンを作成します。 + +```console +git clone https://github.com/scalar-labs/scalardb-samples +``` + +次に、次のコマンドを実行して、必要なファイルが含まれているディレクトリに移動します。 + +```console +cd scalardb-samples/scalardb-sample +``` + +## データベースをセットアップする + +データベースを選択し、指示に従って ScalarDB 用に設定します。 + +ScalarDB がサポートするデータベースの一覧については、[データベース](requirements.mdx#データベース)を参照してください。 + + + +

MySQLをローカルで実行する

+ + `scalardb-samples/scalardb-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で MySQL を実行できます。 + + MySQL を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d mysql + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の MySQL のプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For MySQL + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:mysql://localhost:3306/ + scalar.db.username=root + scalar.db.password=mysql + ``` + + +

PostgreSQL をローカルで実行する

+ + `scalardb-samples/scalardb-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で PostgreSQL を実行できます。 + + PostgreSQL を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d postgres + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の PostgreSQL のプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For PostgreSQL + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:postgresql://localhost:5432/ + scalar.db.username=postgres + scalar.db.password=postgres + ``` + + +

Oracle Database をローカルで実行する

+ + `scalardb-samples/scalardb-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で Oracle Database を実行できます。 + + Oracle Database を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d oracle + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の Oracle データベースのプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For Oracle + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:oracle:thin:@//localhost:1521/FREEPDB1 + scalar.db.username=SYSTEM + scalar.db.password=Oracle + ``` + + +

SQL Server をローカルで実行する

+ + `scalardb-samples/scalardb-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で SQL Server を実行できます。 + + SQL Server を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d sqlserver + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の SQL Server のプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For SQL Server + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:sqlserver://localhost:1433;encrypt=true;trustServerCertificate=true + scalar.db.username=sa + scalar.db.password=SqlServer22 + ``` + + +

Amazon DynamoDB をローカルで実行する

+ + `scalardb-samples/scalardb-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で Amazon DynamoDB Local を実行できます。 + + Amazon DynamoDB Local を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d dynamodb + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の Amazon DynamoDB Local のプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For DynamoDB Local + scalar.db.storage=dynamo + scalar.db.contact_points=sample + scalar.db.username=sample + scalar.db.password=sample + scalar.db.dynamo.endpoint_override=http://localhost:8000 + ``` + + + Azure Cosmos DB for NoSQL を使用するには、Azure アカウントが必要です。Azure アカウントをお持ちでない場合は、[Azure Cosmos DB アカウントを作成する](https://learn.microsoft.com/ja-jp/azure/cosmos-db/nosql/quickstart-portal#create-account)にアクセスしてください。 + +

Cosmos DB for NoSQL を設定する

+ + [既定の整合性レベルを設定する](https://learn.microsoft.com/ja-jp/azure/cosmos-db/nosql/how-to-manage-consistency#configure-the-default-consistency-level)の公式ドキュメントに従って、**既定の整合性レベル**を**強力**に設定します。 + +

ScalarDB を設定する

+ + 以下の手順では、ローカル環境に JDK が適切にインストールおよび設定されており、Azure で Cosmos DB for NoSQL アカウントが適切に設定されていることを前提としています。 + + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。`scalar.db.contact_points` と `scalar.db.password` の値は、説明に従って必ず変更してください。 + + ```properties + # For Cosmos DB + scalar.db.storage=cosmos + scalar.db.contact_points= + scalar.db.password= + ``` + +:::note + +Azure Cosmos DB アカウントのプライマリーキーまたはセカンダリキーを `scalar.db.password` の値として使用できます。 + +::: + + +

Cassandra をローカルで実行する

+ + `scalardb-samples/scalardb-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で Apache Cassandra を実行できます。 + + Apache Cassandra を起動するには、次のコマンドを実行します。 + ```console + docker compose up -d cassandra + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の Cassandra のプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For Cassandra + scalar.db.storage=cassandra + scalar.db.contact_points=localhost + scalar.db.username=cassandra + scalar.db.password=cassandra + ``` + + + +ScalarDB の設定の包括的なリストについては、[ScalarDB 設定](configurations.mdx)を参照してください。 + +## 非トランザクションストレージ操作を実行するようにScalarDBを設定する + +非トランザクションストレージ操作を実行するには、設定ファイル **database.properties** で `scalar.db.transaction_manager` プロパティを `single-crud-operation` に設定する必要があります。 + +```properties +scalar.db.transaction_manager=single-crud-operation +``` + +## スキーマを作成またはインポートする + +ScalarDB には、実装固有のデータモデルとスキーマにマップされる独自のデータモデルとスキーマがあります。 + +- **データベーススキーマを作成する必要がありますか?** [ScalarDB Schema Loader](schema-loader.mdx) を参照してください。 +- **既存のデータベースをインポートする必要がありますか?** [ScalarDB Schema Loader を使用して既存のテーブルを ScalarDB にインポートする](schema-loader-import.mdx)を参照してください。 + +## Java アプリケーションを作成する + +このセクションでは、ScalarDB コアライブラリをプロジェクトに追加する方法と、Java を使用して非トランザクションストレージ操作を実行するように設定する方法について説明します。 + +### ScalarDB をプロジェクトに追加する + +ScalarDB ライブラリは、[Maven Central Repository](https://mvnrepository.com/artifact/com.scalar-labs/scalardb) で入手できます。Gradle または Maven を使用して、ライブラリをビルド依存関係としてアプリケーションに追加できます。 + +ビルドツールを選択し、手順に従って ScalarDB のビルド依存関係をアプリケーションに追加します。 + + + + Gradle を使用して ScalarDB のビルド依存関係を追加するには、アプリケーションの `build.gradle` に以下を追加します。 + + ```gradle + dependencies { + implementation 'com.scalar-labs:scalardb:3.13.1' + } + ``` + + + Maven を使用して ScalarDB のビルド依存関係を追加するには、アプリケーションの `pom.xml` に以下を追加します。 + + ```xml + + com.scalar-labs + scalardb + 3.13.1 + + ``` + + + +### Java API を使用する + +Java API の詳細については、[ScalarDB Java API ガイド](api-guide.mdx)を参照してください。 + +:::note + +非トランザクションストレージ操作には、次の制限が適用されます: + +- トランザクションの開始はサポートされていません。詳細については、[トランザクションを開始せずにトランザクションを実行する](api-guide.mdx#トランザクションを開始せずにトランザクションを実行する)を参照してください。 +- 1 つのトランザクションで複数のミューテーションを実行することはサポートされていません。 + +::: + +### 詳細はこちら + +- [Javadoc](https://javadoc.io/doc/com.scalar-labs/scalardb/3.13.1/index.html) diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/run-non-transactional-storage-operations-through-primitive-crud-interface.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/run-non-transactional-storage-operations-through-primitive-crud-interface.mdx new file mode 100644 index 00000000..465278dd --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/run-non-transactional-storage-operations-through-primitive-crud-interface.mdx @@ -0,0 +1,882 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# プリミティブ CRUD インターフェースを介して非トランザクションストレージ操作を実行する + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このページでは、プリミティブ CRUD インターフェース (Storage API とも呼ばれる) を通じて非トランザクションストレージ操作を実行する方法について説明します。このガイドでは、読者が ScalarDB について高度な知識を持っていることを前提としています。 + +既存のストレージおよびデータベースシステム上でストレージに依存しない、またはデータベースに依存しない ACID トランザクションを実現するための鍵の 1 つは、ScalarDB が提供するストレージ抽象化機能です。ストレージ抽象化は、[データモデル](design.mdx#データモデル) と、データモデルに基づいて操作を発行する API (Storage API) を定義します。 + +ほとんどの場合、[Transactional API](api-guide.mdx#transactional-api) を使用することになりますが、別のオプションとして Storage API を使用することもできます。 + +Storage API を使用する利点は次のとおりです。 + +- トランザクション API と同様に、基盤となるストレージ実装についてあまり気にせずにアプリケーションコードを作成できます。 +- アプリケーション内の一部のデータに対してトランザクションが必要ない場合は、Storage API を使用してトランザクションを部分的に回避し、実行を高速化できます。 + +:::warning + +ストレージ API を直接使用したり、トランザクション API とストレージ API を混在させたりした場合、予期しない動作が発生する可能性があります。たとえば、ストレージ API はトランザクション機能を提供できないため、操作の実行時に障害が発生すると、API によって異常やデータの不整合が発生する可能性があります。 + +したがって、ストレージ API の使用には *非常に* 注意し、何をしているのかを正確に理解している場合にのみ使用してください。 + +::: + +## ストレージ API の例 + +このセクションでは、基本的な電子マネーアプリケーションでストレージ API を使用する方法について説明します。 + +:::warning + +この例では電子マネーアプリケーションが簡略化されており、実稼働環境には適していません。 + +::: + +### ScalarDB の設定 + +開始する前に、[ScalarDB をはじめよう](getting-started-with-scalardb.mdx) で説明されているのと同じ方法で ScalarDB を設定する必要があります。 + +これを念頭に置いて、このストレージ API の例では、設定ファイル `scalardb.properties` が存在することを前提としています。 + +### データベーススキーマの設定 + +アプリケーションでデータベーススキーマ (データを整理する方法) を定義する必要があります。サポートされているデータ型の詳細については、[ScalarDB と他のデータベース間のデータ型マッピング](schema-loader.mdx#scalardb-と他のデータベース間のデータ型マッピング)を参照してください。 + +この例では、`scalardb/docs/getting-started` ディレクトリに `emoney-storage.json` という名前のファイルを作成します。次に、次の JSON コードを追加してスキーマを定義します。 + +:::note + +次の JSON では、`transaction` フィールドが `false` に設定されており、このテーブルを Storage API で使用する必要があることを示しています。 + +::: + +```json +{ + "emoney.account": { + "transaction": false, + "partition-key": [ + "id" + ], + "clustering-key": [], + "columns": { + "id": "TEXT", + "balance": "INT" + } + } +} +``` + +スキーマを適用するには、[ScalarDB Releases](https://github.com/scalar-labs/scalardb/releases) ページに移動し、使用している ScalarDB のバージョンに一致する ScalarDB Schema Loader を `getting-started` フォルダーにダウンロードします。 + +次に、`` をダウンロードした ScalarDB Schema Loader のバージョンに置き換えて、次のコマンドを実行します。 + +```console +java -jar scalardb-schema-loader-.jar --config scalardb.properties -f emoney-storage.json +``` + +### サンプルコード + +以下は、Storage API を使用する電子マネーアプリケーションのサンプルソースコードです。 + +:::warning + +前述のとおり、Storage API はトランザクション機能を提供できないため、操作の実行中に障害が発生すると、API によって異常やデータの不整合が発生する可能性があります。したがって、Storage API の使用には十分注意し、何をしているのかを正確に理解している場合にのみ使用してください。 + +::: + +```java +public class ElectronicMoney { + + private static final String SCALARDB_PROPERTIES = + System.getProperty("user.dir") + File.separator + "scalardb.properties"; + private static final String NAMESPACE = "emoney"; + private static final String TABLENAME = "account"; + private static final String ID = "id"; + private static final String BALANCE = "balance"; + + private final DistributedStorage storage; + + public ElectronicMoney() throws IOException { + StorageFactory factory = StorageFactory.create(SCALARDB_PROPERTIES); + storage = factory.getStorage(); + } + + public void charge(String id, int amount) throws ExecutionException { + // Retrieve the current balance for id + Get get = + Get.newBuilder() + .namespace(NAMESPACE) + .table(TABLENAME) + .partitionKey(Key.ofText(ID, id)) + .build(); + Optional result = storage.get(get); + + // Calculate the balance + int balance = amount; + if (result.isPresent()) { + int current = result.get().getInt(BALANCE); + balance += current; + } + + // Update the balance + Put put = + Put.newBuilder() + .namespace(NAMESPACE) + .table(TABLENAME) + .partitionKey(Key.ofText(ID, id)) + .intValue(BALANCE, balance) + .build(); + storage.put(put); + } + + public void pay(String fromId, String toId, int amount) throws ExecutionException { + // Retrieve the current balances for ids + Get fromGet = + Get.newBuilder() + .namespace(NAMESPACE) + .table(TABLENAME) + .partitionKey(Key.ofText(ID, fromId)) + .build(); + Get toGet = + Get.newBuilder() + .namespace(NAMESPACE) + .table(TABLENAME) + .partitionKey(Key.ofText(ID, toId)) + .build(); + Optional fromResult = storage.get(fromGet); + Optional toResult = storage.get(toGet); + + // Calculate the balances (it assumes that both accounts exist) + int newFromBalance = fromResult.get().getInt(BALANCE) - amount; + int newToBalance = toResult.get().getInt(BALANCE) + amount; + if (newFromBalance < 0) { + throw new RuntimeException(fromId + " doesn't have enough balance."); + } + + // Update the balances + Put fromPut = + Put.newBuilder() + .namespace(NAMESPACE) + .table(TABLENAME) + .partitionKey(Key.ofText(ID, fromId)) + .intValue(BALANCE, newFromBalance) + .build(); + Put toPut = + Put.newBuilder() + .namespace(NAMESPACE) + .table(TABLENAME) + .partitionKey(Key.ofText(ID, toId)) + .intValue(BALANCE, newToBalance) + .build(); + storage.put(fromPut); + storage.put(toPut); + } + + public int getBalance(String id) throws ExecutionException { + // Retrieve the current balances for id + Get get = + Get.newBuilder() + .namespace(NAMESPACE) + .table(TABLENAME) + .partitionKey(Key.ofText(ID, id)) + .build(); + Optional result = storage.get(get); + + int balance = -1; + if (result.isPresent()) { + balance = result.get().getInt(BALANCE); + } + return balance; + } + + public void close() { + storage.close(); + } +} +``` + +## ストレージ API ガイド + +ストレージ API は、管理 API と CRUD API で設定されています。 + +### 管理 API + +このセクションで説明するように、管理操作をプログラムで実行できます。 + +:::note + +管理操作を実行するために使用できる別の方法は、[Schema Loader](schema-loader.mdx) を使用することです。 + +::: + +#### `DistributedStorageAdmin` インスタンスを取得する + +管理操作を実行するには、まず `DistributedStorageAdmin` インスタンスを取得する必要があります。次のように `StorageFactory` から `DistributedStorageAdmin` インスタンスを取得できます。 + +```java +StorageFactory storageFactory = StorageFactory.create(""); +DistributedStorageAdmin admin = storageFactory.getStorageAdmin(); +``` + +設定の詳細については、[ScalarDB 設定](configurations.mdx)を参照してください。 + +すべての管理操作を実行したら、次のように `DistributedStorageAdmin` インスタンスを閉じる必要があります。 + +```java +admin.close(); +``` + +#### 名前空間を作成する + +テーブルは 1 つの名前空間に属するため、テーブルを作成する前に名前空間を作成する必要があります。 + +名前空間は次のように作成できます。 + +```java +// Create the namespace "ns". If the namespace already exists, an exception will be thrown. +admin.createNamespace("ns"); + +// Create the namespace only if it does not already exist. +boolean ifNotExists = true; +admin.createNamespace("ns", ifNotExists); + +// Create the namespace with options. +Map options = ...; +admin.createNamespace("ns", options); +``` + +作成オプションの詳細については、[作成オプション](api-guide.mdx#作成オプション)を参照してください。 + +#### テーブルを作成する + +テーブルを作成するときは、テーブルメタデータを定義してからテーブルを作成する必要があります。 + +テーブルメタデータを定義するには、`TableMetadata` を使用できます。次に、テーブルの列、パーティションキー、クラスタリングキー (クラスタリング順序を含む)、およびセカンダリインデックスを定義する方法を示します。 + +```java +// Define the table metadata. +TableMetadata tableMetadata = + TableMetadata.newBuilder() + .addColumn("c1", DataType.INT) + .addColumn("c2", DataType.TEXT) + .addColumn("c3", DataType.BIGINT) + .addColumn("c4", DataType.FLOAT) + .addColumn("c5", DataType.DOUBLE) + .addPartitionKey("c1") + .addClusteringKey("c2", Scan.Ordering.Order.DESC) + .addClusteringKey("c3", Scan.Ordering.Order.ASC) + .addSecondaryIndex("c4") + .build(); +``` + +ScalarDB のデータモデルの詳細については、[データモデル](design.mdx#データモデル)を参照してください。 + +次に、次のようにテーブルを作成します。 + +```java +// Create the table "ns.tbl". If the table already exists, an exception will be thrown. +admin.createTable("ns", "tbl", tableMetadata); + +// Create the table only if it does not already exist. +boolean ifNotExists = true; +admin.createTable("ns", "tbl", tableMetadata, ifNotExists); + +// Create the table with options. +Map options = ...; +admin.createTable("ns", "tbl", tableMetadata, options); +``` + +#### セカンダリインデックスを作成する + +セカンダリインデックスは次のように作成できます。 + +```java +// Create a secondary index on column "c5" for table "ns.tbl". If a secondary index already exists, an exception will be thrown. +admin.createIndex("ns", "tbl", "c5"); + +// Create the secondary index only if it does not already exist. +boolean ifNotExists = true; +admin.createIndex("ns", "tbl", "c5", ifNotExists); + +// Create the secondary index with options. +Map options = ...; +admin.createIndex("ns", "tbl", "c5", options); +``` + +#### テーブルに新しい列を追加する + +次のように、テーブルに新しい非パーティションキー列を追加できます。 + +```java +// Add a new column "c6" with the INT data type to the table "ns.tbl". +admin.addNewColumnToTable("ns", "tbl", "c6", DataType.INT) +``` + +:::warning + +テーブルに新しい列を追加する場合は、基盤となるストレージによって実行時間が大きく異なる可能性があるため、慎重に検討する必要があります。それに応じて計画を立て、特にデータベースが本番環境で実行されている場合は、次の点を考慮してください。 + +- **Cosmos DB for NoSQL および DynamoDB の場合:** テーブルスキーマは変更されないため、列の追加はほぼ瞬時に行われます。別のテーブルに格納されているテーブルメタデータのみが更新されます。 +- **Cassandra の場合:** 列を追加すると、スキーマメタデータのみが更新され、既存のスキーマレコードは変更されません。クラスタートポロジが実行時間の主な要因です。スキーマメタデータの変更は、ゴシッププロトコルを介して各クラスターノードに共有されます。このため、クラスターが大きいほど、すべてのノードが更新されるまでの時間が長くなります。 +- **リレーショナルデータベース (MySQL、Oracle など) の場合:** 列の追加は実行にそれほど時間がかかりません。 + +::: + +#### テーブルを切り捨てる + +テーブルを切り捨てるには、次のようにします。 + +```java +// Truncate the table "ns.tbl". +admin.truncateTable("ns", "tbl"); +``` + +#### セカンダリインデックスを削除する + +セカンダリインデックスは次のように削除できます。 + +```java +// Drop the secondary index on column "c5" from table "ns.tbl". If the secondary index does not exist, an exception will be thrown. +admin.dropIndex("ns", "tbl", "c5"); + +// Drop the secondary index only if it exists. +boolean ifExists = true; +admin.dropIndex("ns", "tbl", "c5", ifExists); +``` + +#### テーブルを削除する + +テーブルを削除するには、次のようにします。 + +```java +// Drop the table "ns.tbl". If the table does not exist, an exception will be thrown. +admin.dropTable("ns", "tbl"); + +// Drop the table only if it exists. +boolean ifExists = true; +admin.dropTable("ns", "tbl", ifExists); +``` + +#### 名前空間を削除する + +名前空間を削除するには、次のようにします。 + +```java +// Drop the namespace "ns". If the namespace does not exist, an exception will be thrown. +admin.dropNamespace("ns"); + +// Drop the namespace only if it exists. +boolean ifExists = true; +admin.dropNamespace("ns", ifExists); +``` + +#### 既存の名前空間を取得する + +既存の名前空間は次のように取得できます。 + +```java +Set namespaces = admin.getNamespaceNames(); +``` + +#### 名前空間のテーブルを取得する + +名前空間のテーブルは次のように取得できます。 + +```java +// Get the tables of the namespace "ns". +Set tables = admin.getNamespaceTableNames("ns"); +``` + +#### テーブルメタデータを取得する + +テーブルメタデータは次のように取得できます。 + +```java +// Get the table metadata for "ns.tbl". +TableMetadata tableMetadata = admin.getTableMetadata("ns", "tbl"); +``` + +#### 名前空間を修復する + +名前空間が不明な状態の場合 (名前空間が基盤となるストレージに存在するが ScalarDB メタデータが存在しない、またはその逆)、このメソッドは必要に応じて名前空間とそのメタデータを再作成します。 + +名前空間は次のように修復できます。 + +```java +// Repair the namespace "ns" with options. +Map options = ...; + admin.repairNamespace("ns", options); +``` + +#### テーブルを修復する + +テーブルが不明な状態の場合 (テーブルは基盤となるストレージに存在するが ScalarDB メタデータは存在しない、またはその逆)、このメソッドは必要に応じてテーブル、そのセカンダリインデックス、およびそのメタデータを再作成します。 + +テーブルは次のように修復できます。 + +```java +// Repair the table "ns.tbl" with options. +TableMetadata tableMetadata = + TableMetadata.newBuilder() + ... + .build(); +Map options = ...; +admin.repairTable("ns", "tbl", tableMetadata, options); +``` + +#### 最新の ScalarDB API をサポートするように環境をアップグレードする + +ScalarDB API の最新バージョンをサポートするように ScalarDB 環境をアップグレードできます。通常、リリースノートに記載されているように、アプリケーション環境が使用する ScalarDB バージョンを更新した後、このメソッドを実行する必要があります。 + +```java +// Upgrade the ScalarDB environment. +Map options = ...; +admin.upgrade(options); +``` + +### CRUD 操作を実装する + +次のセクションでは、CRUD 操作について説明します。 + +#### `DistributedStorage` インスタンスを取得する + +Storage API で CRUD 操作を実行するには、`DistributedStorage` インスタンスを取得する必要があります。 + +インスタンスは次のように取得できます。 + +```java +StorageFactory storageFactory = StorageFactory.create(""); +DistributedStorage storage = storageFactory.getStorage(); +``` + +すべての CRUD 操作を実行したら、次のように `DistributedStorage` インスタンスを閉じる必要があります。 + +```java +storage.close(); +``` + +#### `Get` 操作 + +`Get` は、プライマリーキーで指定された単一のレコードを取得する操作です。 + +まず `Get` オブジェクトを作成し、次に次のように `storage.get()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create a `Get` operation. +Key partitionKey = Key.ofInt("c1", 10); +Key clusteringKey = Key.of("c2", "aaa", "c3", 100L); + +Get get = + Get.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .projections("c1", "c2", "c3", "c4") + .build(); + +// Execute the `Get` operation. +Optional result = storage.get(get); +``` + +また、投影を指定して、返される列を選択することもできます。 + +`Key` オブジェクトの構築方法の詳細については、[キーの構築](api-guide.mdx#キーの構築)を参照してください。また、`Result` オブジェクトの処理方法の詳細については、[Result オブジェクトの処理](api-guide.mdx#result-オブジェクトの処理)を参照してください。 + +##### 一貫性レベルを指定する + +Storage API の各操作 (`Get`、`Scan`、`Put`、`Delete`) で一貫性レベルを次のように指定できます。 + +```java +Get get = + Get.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .consistency(Consistency.LINEARIZABLE) // Consistency level + .build(); +``` + +次の表は、3 つの一貫性レベルについて説明しています。 + +| 一貫性レベル | 説明 | +| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `SEQUENTIAL` | 順次一貫性は、基礎となるストレージ実装によってすべての操作が何らかの順次順序で実行されるようにされ、各プロセスの操作がこの順序で実行されることを前提としています。 | +| `EVENTUAL` | 結果一貫性は、基礎となるストレージ実装によってすべての操作が最終的に実行されることを前提としています。 | +| `LINEARIZABLE` | 線形化可能な一貫性は、基礎となるストレージ実装によって各操作が呼び出しから完了までの間のある時点でアトミックに実行されるようにされることを前提としています。 | + +##### セカンダリインデックスを使用して `Get` を実行する + +セカンダリインデックスを使用して `Get` 操作を実行できます。 + +パーティションキーを指定する代わりに、次のようにインデックスキー (インデックス付き列) を指定してセカンダリインデックスを使用できます。 + +```java +// Create a `Get` operation by using a secondary index. +Key indexKey = Key.ofFloat("c4", 1.23F); + +Get get = + Get.newBuilder() + .namespace("ns") + .table("tbl") + .indexKey(indexKey) + .projections("c1", "c2", "c3", "c4") + .build(); + +// Execute the `Get` operation. +Optional result = storage.get(get); +``` + +:::note + +結果に複数のレコードがある場合、`storage.get()` は例外をスローします。 + +::: + +#### `Scan` 操作 + +`Scan` は、パーティション内の複数のレコードを取得する操作です。`Scan` 操作では、クラスタリングキーの境界とクラスタリングキー列の順序を指定できます。 + +まず `Scan` オブジェクトを作成し、次に次のように `storage.scan()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create a `Scan` operation. +Key partitionKey = Key.ofInt("c1", 10); +Key startClusteringKey = Key.of("c2", "aaa", "c3", 100L); +Key endClusteringKey = Key.of("c2", "aaa", "c3", 300L); + +Scan scan = + Scan.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .start(startClusteringKey, true) // Include startClusteringKey + .end(endClusteringKey, false) // Exclude endClusteringKey + .projections("c1", "c2", "c3", "c4") + .orderings(Scan.Ordering.desc("c2"), Scan.Ordering.asc("c3")) + .limit(10) + .build(); + +// Execute the `Scan` operation. +Scanner scanner = storage.scan(scan); +``` + +クラスタリングキー境界を省略するか、`start` 境界または `end` 境界のいずれかを指定できます。`orderings` を指定しない場合は、テーブルの作成時に定義したクラスタリング順序で結果が並べられます。 + +さらに、`projections` を指定して返される列を選択し、`limit` を使用して `Scan` 操作で返されるレコードの数を指定できます。 + +##### `Scanner` オブジェクトの処理 + +Storage API の `Scan` 操作は `Scanner` オブジェクトを返します。 + +`Scanner` オブジェクトから結果を 1 つずつ取得する場合は、次のように `one()` メソッドを使用できます。 + +```java +Optional result = scanner.one(); +``` + +または、すべての結果のリストを取得する場合は、次のように `all()` メソッドを使用できます。 + +```java +List results = scanner.all(); +``` + +さらに、`Scanner` は `Iterable` を実装しているので、次のように for-each ループ内で `Scanner` を使用できます。 + +```java +for (Result result : scanner) { + ... +} +``` + +結果を取得した後は、`Scanner` オブジェクトを閉じることを忘れないでください。 + +```java +scanner.close(); +``` + +または、次のように `try`-with-resources を使用することもできます。 + +```java +try (Scanner scanner = storage.scan(scan)) { + ... +} +``` + +##### セカンダリインデックスを使用して `Scan` を実行する + +セカンダリインデックスを使用して `Scan` 操作を実行できます。 + +パーティションキーを指定する代わりに、次のようにインデックスキー (インデックス付き列) を指定してセカンダリインデックスを使用できます。 + +```java +// Create a `Scan` operation by using a secondary index. +Key indexKey = Key.ofFloat("c4", 1.23F); + +Scan scan = + Scan.newBuilder() + .namespace("ns") + .table("tbl") + .indexKey(indexKey) + .projections("c1", "c2", "c3", "c4") + .limit(10) + .build(); + +// Execute the `Scan` operation. +Scanner scanner = storage.scan(scan); +``` + +:::note + +セカンダリインデックスを使用して、`Scan` でクラスタリングキーの境界と順序を指定することはできません。 + +::: + +##### パーティションキーを指定せずに `Scan` を実行して、テーブルのすべてのレコードを取得します + +パーティションキーを指定せずに `Scan` 操作を実行できます。 + +ビルダーで `partitionKey()` メソッドを呼び出す代わりに、次のように `all()` メソッドを呼び出して、パーティションキーを指定せずにテーブルをスキャンできます。 + +```java +// Create a `Scan` operation without specifying a partition key. +Key partitionKey = Key.ofInt("c1", 10); +Key startClusteringKey = Key.of("c2", "aaa", "c3", 100L); +Key endClusteringKey = Key.of("c2", "aaa", "c3", 300L); + +Scan scan = + Scan.newBuilder() + .namespace("ns") + .table("tbl") + .all() + .projections("c1", "c2", "c3", "c4") + .limit(10) + .build(); + +// Execute the `Scan` operation. +Scanner scanner = storage.scan(scan); +``` + +:::note + +パーティションキーを指定せずに `Scan` でクラスタリングキーの境界と順序を指定することはできません。 + +::: + +#### `Put` 操作 + +`Put` は、プライマリーキーで指定されたレコードを配置する操作です。この操作はレコードの upsert 操作として動作し、レコードが存在する場合はレコードを更新し、レコードが存在しない場合はレコードを挿入します。 + +まず `Put` オブジェクトを作成し、次に次のように `storage.put()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create a `Put` operation. +Key partitionKey = Key.ofInt("c1", 10); +Key clusteringKey = Key.of("c2", "aaa", "c3", 100L); + +Put put = + Put.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .floatValue("c4", 1.23F) + .doubleValue("c5", 4.56) + .build(); + +// Execute the `Put` operation. +storage.put(put); +``` + +次のように `null` 値を持つレコードを配置することもできます。 + +```java +Put put = + Put.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .floatValue("c4", null) + .doubleValue("c5", null) + .build(); +``` + +:::note + +`Put` 操作ビルダーで `enableImplicitPreRead()`、`disableImplicitPreRead()`、または `implicitPreReadEnabled()` を指定した場合、それらは無視されます。 + +::: + +#### `Delete` 操作 + +`Delete` は、プライマリーキーで指定されたレコードを削除する操作です。 + +まず `Delete` オブジェクトを作成し、次に次のように `storage.delete()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create a `Delete` operation. +Key partitionKey = Key.ofInt("c1", 10); +Key clusteringKey = Key.of("c2", "aaa", "c3", 100L); + +Delete delete = + Delete.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .build(); + +// Execute the `Delete` operation. +storage.delete(delete); +``` + +#### 条件付きの `Put` および `Delete` + +条件をチェックするロジックを実装することで、操作を実行する前に満たす必要がある任意の条件 (たとえば、銀行口座の残高は 0 以上である必要があります) を記述できます。または、`Put` や `Delete` などのミューテーション操作で単純な条件を記述することもできます。 + +`Put` または `Delete` 操作に条件が含まれている場合、指定された条件が満たされた場合にのみ操作が実行されます。操作の実行時に条件が満たされていない場合は、`NoMutationException` という例外がスローされます。 + +##### `Put` の条件 + +Storage API の `Put` 操作では、指定された条件が一致した場合にのみ `Put` 操作が実行されるようにする条件を指定できます。この操作は、条件が比較され、更新がアトミックに実行される比較とスワップの操作に似ています。 + +`Put` 操作では次のように条件を指定できます。 + +```java +// Build a condition. +MutationCondition condition = + ConditionBuilder.putIf(ConditionBuilder.column("c4").isEqualToFloat(0.0F)) + .and(ConditionBuilder.column("c5").isEqualToDouble(0.0)) + .build(); + +Put put = + Put.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .floatValue("c4", 1.23F) + .doubleValue("c5", 4.56) + .condition(condition) // condition + .build(); +``` + +`putIf` 条件以外に、`putIfExists` および `putIfNotExists` 条件を次のように指定できます。 + +```java +// Build a `putIfExists` condition. +MutationCondition putIfExistsCondition = ConditionBuilder.putIfExists(); + +// Build a `putIfNotExists` condition. +MutationCondition putIfNotExistsCondition = ConditionBuilder.putIfNotExists(); +``` + +##### `Delete` の条件 + +`Put` 操作と同様に、Storage API の `Delete` 操作でも条件を指定できます。 + +`Delete` 操作では、次のように条件を指定できます。 + +```java +// Build a condition. +MutationCondition condition = + ConditionBuilder.deleteIf(ConditionBuilder.column("c4").isEqualToFloat(0.0F)) + .and(ConditionBuilder.column("c5").isEqualToDouble(0.0)) + .build(); + +Delete delete = + Delete.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKey) + .condition(condition) // condition + .build(); +``` + +`deleteIf` 条件を使用するだけでなく、次のように `deleteIfExists` 条件を指定することもできます。 + +```java +// Build a `deleteIfExists` condition. +MutationCondition deleteIfExistsCondition = ConditionBuilder.deleteIfExists(); +``` + +#### ミューテート操作 + +ミューテートは、単一のパーティションで複数のミューテート (`Put` および `Delete` 操作) を実行する操作です。 + +まずミューテートオブジェクトを作成し、次に次のように `storage.mutate()` メソッドを使用してオブジェクトを実行する必要があります。 + +```java +// Create `Put` and `Delete` operations. +Key partitionKey = Key.ofInt("c1", 10); + +Key clusteringKeyForPut = Key.of("c2", "aaa", "c3", 100L); + +Put put = + Put.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKeyForPut) + .floatValue("c4", 1.23F) + .doubleValue("c5", 4.56) + .build(); + +Key clusteringKeyForDelete = Key.of("c2", "bbb", "c3", 200L); + +Delete delete = + Delete.newBuilder() + .namespace("ns") + .table("tbl") + .partitionKey(partitionKey) + .clusteringKey(clusteringKeyForDelete) + .build(); + +// Execute the operations. +storage.mutate(Arrays.asList(put, delete)); +``` + +:::note + +Mutate 操作では、単一のパーティションのミューテーションのみが受け入れられます。それ以外の場合は、例外がスローされます。 + +さらに、Mutate 操作で複数の条件を指定すると、すべての条件が一致した場合にのみ操作が実行されます。 + +::: + +#### CRUD 操作のデフォルト名前空間 + +すべての CRUD 操作のデフォルト名前空間は、ScalarDB 設定のプロパティを使用して設定できます。 + +```properties +scalar.db.default_namespace_name= +``` + +名前空間を指定しない操作では、設定で設定されたデフォルトの名前空間が使用されます。 + +```java +// This operation will target the default namespace. +Scan scanUsingDefaultNamespace = + Scan.newBuilder() + .table("tbl") + .all() + .build(); +// This operation will target the "ns" namespace. +Scan scanUsingSpecifiedNamespace = + Scan.newBuilder() + .namespace("ns") + .table("tbl") + .all() + .build(); +``` diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/run-transactions-through-scalardb-core-library.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/run-transactions-through-scalardb-core-library.mdx new file mode 100644 index 00000000..5402ef0a --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/run-transactions-through-scalardb-core-library.mdx @@ -0,0 +1,222 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB コアライブラリを介してトランザクションを実行する + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このガイドでは、ScalarDB コアライブラリを使用して、ScalarDB プロパティファイルを設定し、1 フェーズまたは 2 フェーズのコミットインターフェイスを介してトランザクションを実行するためのスキーマを作成する方法について説明します。 + +## 準備 + +このガイドでは、ScalarDB サンプルリポジトリのサンプルを使用して、データベースと ScalarDB をセットアップします。 + +### ScalarDB サンプルリポジトリのクローンを作成する + +**Terminal** を開き、次のコマンドを実行して ScalarDB サンプルリポジトリのクローンを作成します。 + +```console +git clone https://github.com/scalar-labs/scalardb-samples +``` + +次に、次のコマンドを実行して、必要なファイルが含まれているディレクトリに移動します。 + +```console +cd scalardb-samples/scalardb-sample +``` + +## データベースをセットアップする + +データベースを選択し、指示に従って ScalarDB 用に設定します。 + +ScalarDB がサポートするデータベースの一覧については、[データベース](requirements.mdx#データベース)を参照してください。 + + + +

MySQLをローカルで実行する

+ + `scalardb-samples/scalardb-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で MySQL を実行できます。 + + MySQL を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d mysql + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の MySQL のプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For MySQL + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:mysql://localhost:3306/ + scalar.db.username=root + scalar.db.password=mysql + ``` + + +

PostgreSQL をローカルで実行する

+ + `scalardb-samples/scalardb-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で PostgreSQL を実行できます。 + + PostgreSQL を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d postgres + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の PostgreSQL のプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For PostgreSQL + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:postgresql://localhost:5432/ + scalar.db.username=postgres + scalar.db.password=postgres + ``` + + +

Oracle Database をローカルで実行する

+ + `scalardb-samples/scalardb-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で Oracle Database を実行できます。 + + Oracle Database を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d oracle + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の Oracle データベースのプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For Oracle + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:oracle:thin:@//localhost:1521/FREEPDB1 + scalar.db.username=SYSTEM + scalar.db.password=Oracle + ``` + + +

SQL Server をローカルで実行する

+ + `scalardb-samples/scalardb-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で SQL Server を実行できます。 + + SQL Server を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d sqlserver + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の SQL Server のプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For SQL Server + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:sqlserver://localhost:1433;encrypt=true;trustServerCertificate=true + scalar.db.username=sa + scalar.db.password=SqlServer22 + ``` + + +

Amazon DynamoDB をローカルで実行する

+ + `scalardb-samples/scalardb-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で Amazon DynamoDB Local を実行できます。 + + Amazon DynamoDB Local を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d dynamodb + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の Amazon DynamoDB Local のプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For DynamoDB Local + scalar.db.storage=dynamo + scalar.db.contact_points=sample + scalar.db.username=sample + scalar.db.password=sample + scalar.db.dynamo.endpoint_override=http://localhost:8000 + ``` + + + Azure Cosmos DB for NoSQL を使用するには、Azure アカウントが必要です。Azure アカウントをお持ちでない場合は、[Azure Cosmos DB アカウントを作成する](https://learn.microsoft.com/ja-jp/azure/cosmos-db/nosql/quickstart-portal#create-account)にアクセスしてください。 + +

Cosmos DB for NoSQL を設定する

+ + [既定の整合性レベルを設定する](https://learn.microsoft.com/ja-jp/azure/cosmos-db/nosql/how-to-manage-consistency#configure-the-default-consistency-level)の公式ドキュメントに従って、**既定の整合性レベル**を**強力**に設定します。 + +

ScalarDB を設定する

+ + 以下の手順では、ローカル環境に JDK が適切にインストールおよび設定されており、Azure で Cosmos DB for NoSQL アカウントが適切に設定されていることを前提としています。 + + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。`scalar.db.contact_points` と `scalar.db.password` の値は、説明に従って必ず変更してください。 + + ```properties + # For Cosmos DB + scalar.db.storage=cosmos + scalar.db.contact_points= + scalar.db.password= + ``` + +:::note + +Azure Cosmos DB アカウントのプライマリーキーまたはセカンダリキーを `scalar.db.password` の値として使用できます。 + +::: + + +

Cassandra をローカルで実行する

+ + `scalardb-samples/scalardb-sample` ディレクトリの `docker-compose.yml` ファイルを使用して、Docker Compose で Apache Cassandra を実行できます。 + + Apache Cassandra を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d cassandra + ``` + +

ScalarDB を設定する

+ + `scalardb-samples/scalardb-sample` ディレクトリの **database.properties** ファイルには、ScalarDB のデータベース設定が含まれています。**database.properties** ファイル内の Cassandra のプロパティのコメントを解除して、設定が次のようになるようにしてください。 + + ```properties + # For Cassandra + scalar.db.storage=cassandra + scalar.db.contact_points=localhost + scalar.db.username=cassandra + scalar.db.password=cassandra + ``` + + + +ScalarDB の設定の包括的なリストについては、[ScalarDB 設定](configurations.mdx)を参照してください。 + +## スキーマを作成またはインポートする + +ScalarDB には、実装固有のデータモデルとスキーマにマップされる独自のデータモデルとスキーマがあります。 + +- **データベーススキーマを作成する必要がありますか?** [ScalarDB Schema Loader](schema-loader.mdx) を参照してください。 +- **既存のデータベースをインポートする必要がありますか?** [ScalarDB Schema Loader を使用して既存のテーブルを ScalarDB にインポートする](schema-loader-import.mdx)を参照してください。 + +## Javaを使用してトランザクションを実行する + +- **1 フェーズコミットインターフェイスを使用してトランザクションを実行しますか?** [ScalarDB Java API ガイド](api-guide.mdx#transactional-api)を参照してください。 +- **2 フェーズコミットインターフェイスを使用してトランザクションを実行しますか?** [2 フェーズコミットインターフェースを使用したトランザクション](two-phase-commit-transactions.mdx)を参照してください。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-postgresql/getting-started.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-postgresql/getting-started.mdx new file mode 100644 index 00000000..4f60b24a --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-postgresql/getting-started.mdx @@ -0,0 +1,101 @@ +--- +tags: + - Community +--- + +# ScalarDB Analytics with PostgreSQL をはじめよう + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このドキュメントでは、ScalarDB Analytics with PostgreSQL の使用を開始する方法について説明します。ScalarDB Analytics with PostgreSQL がすでにインストールされており、必要なサービスがすべて実行されていることを前提としています。そのような環境がない場合は、[Docker を使用してローカル環境に ScalarDB Analytics with PostgreSQL をインストールする方法](./installation.mdx)の手順に従ってください。ScalarDB Analytics with PostgreSQL は PostgreSQL 経由でクエリを実行するため、PostgreSQL にクエリを送信するための `psql` クライアントまたは別の PostgreSQL クライアントがすでにあることも前提としています。 + +## ScalarDB Analytics with PostgreSQL とは + +ユニバーサルトランザクションマネージャーである ScalarDB は、主にトランザクションワークロードを対象としているため、リレーショナルクエリの限られたサブセットをサポートしています。 + +ScalarDB Analytics with PostgreSQL は、PostgreSQL とその外部データラッパー (FDW) 拡張機能を使用して、ScalarDB の機能を拡張し、ScalarDB が管理するデータに対する分析クエリを処理します。 + +ScalarDB Analytics with PostgreSQL は、主に PostgreSQL と Schema Importer の 2 つのコンポーネントで構成されています。 + +PostgreSQL はサービスとして実行され、ユーザーからのクエリを受け入れて処理します。FDW 拡張機能は、ScalarDB が管理するバックエンドストレージからデータを読み取るために使用されます。Schema Importer は、ScalarDB データベースのスキーマを PostgreSQL にインポートするツールです。これにより、ユーザーは PostgreSQL 側のテーブル (ScalarDB 側のテーブルと同一) を表示できます。 + +## ScalarDB データベースをセットアップする + +まず、ScalarDB Analytics with PostgreSQL で分析クエリを実行するには、1 つ以上の ScalarDB データベースが必要です。独自の ScalarDB データベースがある場合は、このセクションをスキップして、代わりにそのデータベースを使用できます。[scalardb-samples/scalardb-analytics-postgresql-sample](https://github.com/scalar-labs/scalardb-samples/tree/main/scalardb-analytics-postgresql-sample) プロジェクトを使用する場合は、プロジェクトディレクトリで次のコマンドを実行してサンプルデータベースを設定できます。 + +```console +docker compose run --rm schema-loader \ + -c /etc/scalardb.properties \ + --schema-file /etc/schema.json \ + --coordinator \ + --no-backup \ + --no-scaling +``` + +このコマンドは、DynamoDB、PostgreSQL、Cassandra で設定される [複数のストレージインスタンス](../multi-storage-transactions.mdx)を設定します。次に、これらのストレージにマップされる `dynamons`、`postgresns`、`cassandrans` の名前空間を作成し、[ScalarDB Schema Loader](https://scalardb.scalar-labs.com/docs/latest/schema-loader/)を使用して `dynamons.customer`、`postgresns.orders`、`cassandrans.lineitem` のテーブルを作成します。 + +![マルチストレージの概要](./images/multi-storage-overview.png) + +次のコマンドを実行すると、作成されたテーブルにサンプルデータをロードできます。 + +```console +docker compose run --rm sample-data-loader +``` + +## PostgreSQL に ScalarDB 管理下のデータベースのスキーマをインポートする + +次に、分析クエリを処理する PostgreSQL に ScalarDB 管理下のデータベースのスキーマをインポートします。ScalarDB Analytics with PostgreSQL には、この目的のためのツールである Schema Importer が用意されています。このツールを使用すると、分析クエリを実行するために必要なすべての準備が整います。 + +```console +docker compose run --rm schema-importer \ + import \ + --config /etc/scalardb.properties \ + --host analytics \ + --port 5432 \ + --database test \ + --user postgres \ + --password postgres \ + --namespace cassandrans \ + --namespace postgresns \ + --namespace dynamons \ + --config-on-postgres-host /etc/scalardb.properties +``` + +独自の ScalarDB データベースを使用する場合は、`--config` および `--config-on-postgres-host` オプションを ScalarDB 設定ファイルに置き換え、`--namespace` オプションをインポートする ScalarDB 名前空間に置き換える必要があります。 + +これにより、ScalarDB データベース内のテーブルと同じ名前のテーブル (正確にはビュー) が作成されます。この例では、`dynamons.customer`、`postgresns.orders`、および `cassandrans.lineitem` のテーブルが作成されます。列定義も ScalarDB データベースと同一です。これらのテーブルは、FDW を使用して ScalarDB データベースの基盤となるストレージに接続された [外部テーブル](https://www.postgresql.org/docs/current/sql-createforeigntable.html)です。したがって、PostgreSQL 内のこれらのテーブルを ScalarDB データベース内のテーブルと同等と見なすことができます。 + +![インポートされたスキーマ](./images/imported-schema.png) + +## 分析クエリを実行する + +これで、ScalarDB データベース内の同じデータを読み取るすべてのテーブルが揃い、PostgreSQL でサポートされている任意の分析クエリを実行できるようになりました。クエリを実行するには、`psql` またはその他のクライアントを使用して PostgreSQL に接続してください。 + +```console +psql -U postgres -h localhost test +Password for user postgres: + +> select c_mktsegment, count(*) from dynamons.customer group by c_mktsegment; + c_mktsegment | count +--------------+------- + AUTOMOBILE | 4 + BUILDING | 2 + FURNITURE | 1 + HOUSEHOLD | 2 + MACHINERY | 1 +(5 rows) +``` + +サンプルデータと追加の実作業の詳細については、サンプルアプリケーションページを参照してください。 + +## 注意事項 + +### 分離レベル + +ScalarDB Analytics with PostgreSQL は、**Read Committed** 分離レベルを設定してデータを読み取ります。この分離レベルにより、読み取るデータが過去にコミットされていることが保証されますが、特定の時点で一貫性のあるデータを読み取ることができることは保証されません。 + +### 書き込み操作はサポートされていません + +ScalarDB Analytics with PostgreSQL は、読み取り専用クエリのみをサポートします。`INSERT`、`UPDATE`、およびその他の書き込み操作はサポートされていません。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-postgresql/images/imported-schema.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-postgresql/images/imported-schema.png new file mode 100644 index 00000000..1cf8fea3 Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-postgresql/images/imported-schema.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-postgresql/images/multi-storage-overview.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-postgresql/images/multi-storage-overview.png new file mode 100644 index 00000000..fc8df1cb Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-postgresql/images/multi-storage-overview.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-postgresql/installation.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-postgresql/installation.mdx new file mode 100644 index 00000000..b1e66411 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-postgresql/installation.mdx @@ -0,0 +1,64 @@ +--- +tags: + - Community +--- + +# Docker を使用してローカル環境に ScalarDB Analytics with PostgreSQL をインストールする方法 + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このドキュメントでは、[Docker Compose](https://docs.docker.com/compose/) を使用して、Cassandra、PostgreSQL、および DynamoDB ローカルサーバーのマルチストレージバックエンドを使用して、ScalarDB Analytics with PostgreSQL を実行するローカル環境を設定する方法について説明します。 + +## 前提条件 + +- [Docker Engine](https://docs.docker.com/engine/) および [Docker Compose](https://docs.docker.com/compose/)。 + +プラットフォームに応じて、Docker ウェブサイトの手順に従ってください。 + +## ステップ 1. `scalardb-samples` リポジトリを複製します + +[scalardb-samples/scalardb-analytics-postgresql-sample](https://github.com/scalar-labs/scalardb-samples/tree/main/scalardb-analytics-postgresql-sample) リポジトリは、ScalarDB Analytics with PostgreSQL を設定するためのサンプル設定を含むプロジェクトです。 + +scalardb-analytics-postgresql-sample アプリを実行するローカルマシン上の場所を決定します。次に、ターミナルを開き、`cd` コマンドを使用してその場所に移動し、次のコマンドを実行します。 + +```console +git clone https://github.com/scalar-labs/scalardb-samples.git +cd scalardb-samples/scalardb-analytics-postgresql-sample +``` + +## ステップ 2. ScalarDB Analytics with PostgreSQL サービスを起動する + +次のコマンドは、ScalarDB Analytics with PostgreSQL を提供する PostgreSQL インスタンスと、Docker コンテナ内の Cassandra、PostgreSQL、および DynamoDB ローカルのバックエンドサーバーを起動します。このコマンドを初めて実行すると、必要な Docker イメージが GitHub Container Registry からダウンロードされます。 + +```console +docker-compose up +``` + +コンテナをバックグラウンドで実行する場合は、`-d` (--detach) オプションを追加します。 + +```console +docker-compose up -d +``` + +すでに独自の ScalarDB データベースがあり、それをバックエンドサービスとして使用したい場合は、コンテナー内で追加のバックエンドサーバーを起動せずに、PostgreSQL インスタンスのみを起動できます。 + +```console +docker-compose up analytics +``` + +## ステップ 3. 分析クエリを実行する + +これで、必要なサービスがすべて実行されているはずです。分析クエリを実行するには、[ScalarDB Analytics with PostgreSQL の開始方法](./getting-started.mdx)を参照してください。 + +## ステップ 4. ScalarDB Analytics with PostgreSQL サービスをシャットダウンする + +コンテナをシャットダウンするには、方法に応じて、ターミナルで次のいずれかを実行します。 + +- フォアグラウンドでコンテナを起動した場合は、`docker-compose` が実行されている場所で Ctrl+C を押します。 +- バックグラウンドでコンテナを起動した場合は、次のコマンドを実行します。 + +```console +docker-compose down +``` diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-postgresql/scalardb-fdw.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-postgresql/scalardb-fdw.mdx new file mode 100644 index 00000000..38345761 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-postgresql/scalardb-fdw.mdx @@ -0,0 +1,183 @@ +--- +tags: + - Community +--- + +# ScalarDB FDW + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +ScalarDB FDW は、[ScalarDB](https://www.scalar-labs.com/scalardb/) の外部データラッパー (FDW) を実装する PostgreSQL 拡張機能です。 + +ScalarDB FDW は、Java Native Interface を使用して、FDW 内のライブラリとして ScalarDB を直接利用し、ScalarDB のスキャン操作を介して外部データベースからデータを読み取ります。 + +## 前提条件 + +環境に次の前提条件が設定されている必要があります。 + +### JDK + +ScalarDB と互換性のあるバージョンの Java Development Kit (JDK) をインストールする必要があります。さらに、JDK インストールディレクトリを指す `JAVA_HOME` 環境変数を設定する必要があります。 + +これらの拡張機能は内部で Java Native Interface (JNI) を使用するため、ライブラリ検索パスに `libjvm.so` などの Java 仮想マシン (JVM) の動的ライブラリを含める必要があることに注意してください。 + +### PostgreSQL + +この拡張機能は PostgreSQL 13 以降をサポートしています。PostgreSQL のインストール方法の詳細については、[サーバー管理](https://www.postgresql.org/docs/current/admin.html)の公式ドキュメントを参照してください。 + +## ビルドとインストール + +以下のコマンドを実行すると、この拡張機能をビルドしてインストールできます。 + +```console +make install +``` + +### 一般的なビルドエラー + +このセクションでは、発生する可能性のある一般的なビルドエラーについて説明します。 + +#### ld: -ljvm のライブラリが見つかりません + +通常、ビルドスクリプトは `libjvm.so` のパスを見つけ、それをライブラリ検索パスとして適切に設定しています。ただし、`ld: library not found for -ljvm` というエラーが発生した場合は、`libjvm.so` ファイルをデフォルトのライブラリ検索パスにコピーしてください。例: + +```console +ln -s //libjvm.so /usr/lib64/libjvm.so +``` + +## 使用方法 + +このセクションでは、ScalarDB の FDW の使用例と利用可能なオプションについて説明します。 + +### 例 + +次の例では、必要なコンポーネントをインストールして作成し、FDW 拡張機能を使用してクエリを実行する方法を示します。 + +#### 1. 拡張機能をインストールする + +拡張機能のインストール方法の詳細については、[ビルドとインストール](#ビルドとインストール)セクションを参照してください。 + +#### 2. 拡張機能を作成する + +拡張機能を作成するには、次のコマンドを実行します。 + +```sql +CREATE EXTENSION scalardb_fdw; +``` + +#### 3. 外部サーバーを作成する + +外部サーバーを作成するには、次のコマンドを実行します。 + +```sql +CREATE SERVER scalardb FOREIGN DATA WRAPPER scalardb_fdw OPTIONS ( + config_file_path '/path/to/scalardb.properties' +); +``` + +#### 4. ユーザーマッピングを作成する + +ユーザーマッピングを作成するには、次のコマンドを実行します。 + +```sql +CREATE USER MAPPING FOR PUBLIC SERVER scalardb; +``` + +#### 5. 外部テーブルを作成する + +外部テーブルを作成するには、次のコマンドを実行します。 + +```sql +CREATE FOREIGN TABLE sample_table ( + pk int, + ck1 int, + ck2 int, + boolean_col boolean, + bigint_col bigint, + float_col double precision, + double_col double precision, + text_col text, + blob_col bytea +) SERVER scalardb OPTIONS ( + namespace 'ns', + table_name 'sample_table' +); +``` + +#### 6. クエリを実行する + +クエリを実行するには、次のコマンドを実行します。 + +```sql +select * from sample_table; +``` + +### 使用可能なオプション + +ScalarDB FDW オブジェクトには次のオプションを設定できます。 + +#### `CREATE SERVER` + +ScalarDB 外部サーバーオブジェクトには次のオプションを設定できます。 + +| 名前 | 必須 | タイプ | 説明 | +| ------------------ | ------- | -------- | ------------------------------------------- | +| `config_file_path` | **はい** | `string` | ScalarDB 設定ファイルへのパス。 | +| `max_heap_size` | いいえ | `string` | JVM の最大ヒープサイズ。形式は `-Xmx` と同じです。 | + +#### `CREATE USER MAPPING` + +現在、`CREATE USER MAPPING` のオプションはありません。 + +#### `CREATE FOREIGN SERVER` + +ScalarDB 外部テーブルオブジェクトには次のオプションを設定できます。 + +| 名前 | 必須 | タイプ | 説明 | +| ------------ | ------- | -------- | -------------------------------------------- | +| `namespace` | **はい** | `string` | ScalarDB インスタンス内のテーブルの名前空間の名前。 | +| `table_name` | **はい** | `string` | ScalarDB インスタンス内のテーブルの名前。 | + +### データ型のマッピング + +| ScalarDB | PostgreSQL | +| -------- | ---------------- | +| BOOLEAN | boolean | +| INT | int | +| BIGINT | bigint | +| FLOAT | float | +| DOUBLE | double precision | +| TEXT | text | +| BLOB | bytea | + +## テスト + +このセクションでは、ScalarDB の FDW をテストする方法について説明します。 + +### テスト用の ScalarDB インスタンスの設定 + +ScalarDB の FDW をテストする前に、テストデータを含む実行中の ScalarDB インスタンスが必要です。次のコマンドを実行して、インスタンスを設定し、テストデータをロードできます。 + +```console +./test/setup.sh +``` + +インスタンスをリセットする場合は、次のコマンドを実行してから、上記のセットアップコマンドを再度実行します。 + +```console +./test/cleanup.sh +``` + +### 回帰テストを実行する + +FDW 拡張機能をインストールした後、次のコマンドを実行すると、回帰テストを実行できます。 + +```console +make installcheck +``` + +## 制限事項 + +- この拡張機能は、ScalarDB 管理データベースでの分析クエリ処理を可能にすることを目的としています。したがって、この拡張機能は ScalarDB からのデータの読み取りのみをサポートします。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-postgresql/schema-importer.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-postgresql/schema-importer.mdx new file mode 100644 index 00000000..c724d4c6 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-postgresql/schema-importer.mdx @@ -0,0 +1,68 @@ +--- +tags: + - Community +--- + +# Schema Importer + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +Schema Importer は、PostgreSQL を自動的に設定するための CLI ツールです。このツールを使用すると、PostgreSQL データベースに、ScalarDB インスタンスと同じデータベースオブジェクト (名前空間やテーブルなど) を持たせることができます。 + +Schema Importer は、ScalarDB 設定ファイルを読み取り、ScalarDB で定義されているテーブルのスキーマを取得し、対応する外部データラッパーの外部テーブルとビューをこの順序で作成します。詳細については、[PostgreSQL での ScalarDB 分析の開始](getting-started.mdx)を参照してください。 + +## Schema Importer のビルド + +[Gradle](https://gradle.org/) を使用して Schema Importer をビルドできます。Schema Importer をビルドするには、次のコマンドを実行します。 + +```console +./gradlew build +``` + +`java -jar` を使用して Schema Importer を起動できるように、Fat JAR ファイルを作成する必要があります。Fat JAR を作成するには、次のコマンドを実行します。 + + ```console + ./gradlew shadowJar + ``` + +fat JAR をビルドすると、`app/build/libs/` ディレクトリに fat JAR ファイルが作成されます。 + +## Schema Importer を実行する + +fat JAR ファイルを使用して Schema Importer を実行するには、次のコマンドを実行します。 + +```console +java -jar +``` +利用可能なオプションは次のとおりです。 + +| 名前 | 必須 | 説明 | デフォルト | +| --------------------------- | -------- | ----------------------------------------------------------------------------------------------------- | ------------------------------- | +| `--config` | **はい** | ScalarDB 設定ファイルへのパス | | +| `--config-on-postgres-host` | No | PostgreSQL を実行しているホスト上の ScalarDB 設定ファイルへのパス | `--config` と同じ値が使用されます。 | +| `--namespace`, `-n` | **はい** | 分析インスタンスにインポートする名前空間。2 つ以上の名前空間がある場合は、`--namespace` オプションを複数回指定できます。 | | +| `--host` | いいえ | PostgreSQL ホスト | localhost | +| `--port` | いいえ | PostgreSQL ポート | 5432 | +| `--database` | いいえ | PostgreSQL ポート | postgres | +| `--user` | いいえ | PostgreSQL ユーザー | postgres | +| `--password` | いいえ | PostgreSQL パスワード | | +| `--debug` | いいえ | デバッグモードを有効にする | | + + +## Schema Importer のテスト + +Schema Importer をテストするには、次のコマンドを実行します。 + +```console +./gradlew test +``` + +## Schema Importer の Docker イメージをビルドする + +Schema Importer の Docker イメージをビルドするには、次のコマンドを実行します。`` は、使用する Schema Importer のタグバージョンに置き換えます。 + +```console +docker build -t ghcr.io/scalar-labs/scalardb-analytics-postgresql-schema-importer: -f ./app/Dockerfile . +``` diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-spark/README.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-spark/README.mdx new file mode 100644 index 00000000..458796e7 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-spark/README.mdx @@ -0,0 +1,30 @@ +--- +tags: + - Enterprise Option + - Public Preview +--- + +# ScalarDB Analytics with Spark + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +ScalarDB は、ユニバーサルトランザクションマネージャーとして、主にトランザクションワークロードを対象としているため、リレーショナルクエリの限定されたサブセットをサポートしています。 + +ScalarDB Analytics with Spark は、Apache Spark と Spark SQL を使用して、ScalarDB が管理するデータに対する分析クエリを処理するために ScalarDB の機能を拡張します。 + +ScalarDB Analytics with Spark は Spark カタログプラグインとして提供されるため、外部で管理されるデータソースをそのデータスキーマで読み取ることができます。このプラグインを使用すると、ScalarDB テーブルから同じスキーマを持つ Spark SQL テーブルとしてデータを読み取ることができます。 + +:::warning + +ScalarDB Analytics with Spark を使用するには、商用ライセンスが必要です。商用ライセンスが必要な場合は、[お問い合わせ](https://scalar-labs.com/contact_us/)ください。 + +::: + +## 参考資料 + +* ScalarDB Analytics with Spark を使用してアドホック分析クエリまたは開発アプリケーションを実行するには、[ScalarDB Analytics with Spark の使用開始](getting-started.mdx)を参照してください。 +* サンプルデータセットとアプリケーションを使用して ScalarDB Analytics with Spark を使用する方法に関するチュートリアルについては、[ScalarDB Analytics with Spark を使用してサンプルデータで分析クエリを実行する](../scalardb-samples/scalardb-analytics-spark-sample/README.mdx)を参照してください。 +* ScalarDB Analytics with Spark を設定する方法の詳細については、[ScalarDB Analytics with Spark の設定](configuration.mdx)を参照してください。 +* サポートされている Spark および Scala のバージョンについては、[ScalarDB Analytics with Spark のバージョン互換性](version-compatibility.mdx)を参照してください。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-spark/version-compatibility.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-spark/version-compatibility.mdx new file mode 100644 index 00000000..71d489b4 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics-spark/version-compatibility.mdx @@ -0,0 +1,21 @@ +--- +tags: + - Enterprise Option + - Public Preview +--- + +# ScalarDB Analytics with Spark のバージョン互換性 + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +Spark と Scala はマイナーバージョン間で互換性がない場合があるため、ScalarDB Analytics with Spark では、さまざまな Spark および Scala バージョンに対して、`scalardb-analytics-spark-_` という形式で名前が付けられたさまざまなアーティファクトを提供しています。使用している Spark および Scala のバージョンに一致するアーティファクトを選択してください。たとえば、Scala 2.13 で Spark 3.5 を使用している場合は、`scalardb-analytics-spark-3.5_2.13` を指定する必要があります。 + +Java バージョンに関しては、ScalarDB Analytics with Spark は Java 8 以降をサポートしています。 + +以下は、ScalarDB Analytics with Spark の各バージョンでサポートされている Spark および Scalar バージョンのリストです。 + +| ScalarDB Analytics with Spark バージョン | ScalarDB バージョン | サポートされている Spark バージョン | サポートされている Scala バージョン | 最小 Java バージョン | +|:---------------------------------------|:------------------|:-------------------------------|:-------------------------------|:-------------------| +| 3.12 | 3.12 | 3.5, 3.4 | 2.13, 2.12 | 8 | diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-benchmarks/README.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-benchmarks/README.mdx new file mode 100644 index 00000000..08cc7c8e --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-benchmarks/README.mdx @@ -0,0 +1,216 @@ +--- +tags: + - Community +--- + +# ScalarDB ベンチマークツール + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このチュートリアルでは、ScalarDB のベンチマークツールを実行する方法について説明します。データベースベンチマークは、一連の標準データセットワークロードに対するデータベースのパフォーマンスを評価するのに役立ちます。 + +## ベンチマークのワークロード + +- TPC-C +- YCSB (ワークロード A、C、および F) +- マルチストレージ YCSB (ワークロード C および F) + - この YCSB バリアントは、ScalarDB を使用するマルチストレージ環境用です。 + - マルチストレージ YCSB のワーカーは、2 つの名前空間 (`ycsb_primary` と `ycsb_secondary`) で同じ数の読み取り操作と書き込み操作を実行します。 + +## 前提条件 + +- 次の Java 開発キット (JDK) のいずれか: + - [Oracle JDK](https://www.oracle.com/java/technologies/downloads/) LTS バージョン 8 + - [OpenJDK](https://openjdk.org/install/) LTS バージョン 8 +- Gradle +- [Kelpie](https://github.com/scalar-labs/kelpie) + - Kelpie は、システムのベンチマークや検証などのエンドツーエンドのテストを実行するためのフレームワークです。 [Kelpie Releases](https://github.com/scalar-labs/kelpie) から最新バージョンを入手し、アーカイブファイルを解凍します。 +- ベンチマークツールを実行するクライアント +- ターゲットデータベース + - ScalarDB がサポートするデータベースの一覧については、[Supported Databases](../scalardb-supported-databases.mdx) を参照してください。 + +:::note + +現在、ベンチマークツールを実行するときに使用できるのは JDK 8 のみです。 + +::: + +## ベンチマークツールをセットアップする + +次のセクションでは、ベンチマークツールのセットアップ方法について説明します。 + +### ScalarDB ベンチマークリポジトリをクローンする + +**ターミナル**を開き、次のコマンドを実行して ScalarDB ベンチマークリポジトリのクローンを作成します。 + +```console +git clone https://github.com/scalar-labs/scalardb-benchmarks +``` + +次に、下記のコマンドを実行して、ベンチマークファイルが含まれるディレクトリに移動します。 + +```console +cd scalardb-benchmarks +``` + +### ツールをビルドする + +ベンチマークツールをビルドするには、次のコマンドを実行します。 + +```console +./gradlew shadowJar +``` + +### スキーマをロードする + +初期データをロードする前に、[ScalarDB Schema Loader](../schema-loader.mdx) を使用してテーブルを定義する必要があります。スキーマを適用するには、[ScalarDB Releases](https://github.com/scalar-labs/scalardb/releases) ページに移動し、使用している ScalarDB のバージョンに一致する ScalarDB Schema Loader を `scalardb-benchmarks` ルートフォルダーにダウンロードします。 + +さらに、ScalarDB のデータベース設定を含むプロパティファイルが必要です。ScalarDB プロパティファイルの設定の詳細については、[ScalarDB 設定](../configurations.mdx)を参照してください。 + +スキーマを適用してプロパティファイルを設定したら、ベンチマークを選択し、指示に従ってテーブルを作成します。 + + + + TPC-C ベンチマーク用のテーブル ([`tpcc-schema.json`](https://github.com/scalar-labs/scalardb-benchmarks/blob/master/tpcc-schema.json)) を作成するには、山括弧内の内容を説明に従って置き換えて、次のコマンドを実行します。 + + ```console + java -jar scalardb-schema-loader-.jar --config -f tpcc-schema.json --coordinator + ``` + + + YCSB ベンチマーク用のテーブル ([`ycsb-schema.json`](https://github.com/scalar-labs/scalardb-benchmarks/blob/master/ycsb-schema.json)) を作成するには、山括弧内の内容を説明に従って置き換えて、次のコマンドを実行します。 + + ```console + java -jar scalardb-schema-loader-.jar --config -f ycsb-schema.json --coordinator + ``` + + + マルチストレージ YCSB ベンチマーク用のテーブル ([`ycsb-multi-storage-schema.json`](https://github.com/scalar-labs/scalardb-benchmarks/blob/master/ycsb-multi-storage-schema.json)) を作成するには、山括弧内の内容を説明に従って置き換えて、次のコマンドを実行します。 + + ```console + java -jar scalardb-schema-loader-.jar --config -f ycsb-multi-storage-schema.json --coordinator + ``` + + + +### ベンチマーク設定ファイルを準備する + +ベンチマークを実行するには、まずベンチマーク設定ファイルを準備する必要があります。設定ファイルには、少なくとも実行するワークロードモジュールの場所とデータベース設定が必要です。 + +以下は、TPC-C ベンチマークを実行するための設定例です。`config_file` に指定する ScalarDB プロパティファイルは、[以前に設定したベンチマーク環境](#ベンチマーク-ツールをセットアップする)のプロパティファイルである必要があります。 + +:::note + +または、ScalarDB プロパティファイルを使用する代わりに、`.toml` ファイルで各データベース設定項目を指定することもできます。`config_file` が指定されている場合、`[database_config]` の下の他のすべての設定は、コメントが解除されていても無視されます。 + +::: + +```toml +[modules] +[modules.preprocessor] +name = "com.scalar.db.benchmarks.tpcc.TpccLoader" +path = "./build/libs/scalardb-benchmarks-all.jar" +[modules.processor] +name = "com.scalar.db.benchmarks.tpcc.TpccBench" +path = "./build/libs/scalardb-benchmarks-all.jar" +[modules.postprocessor] +name = "com.scalar.db.benchmarks.tpcc.TpccReporter" +path = "./build/libs/scalardb-benchmarks-all.jar" + +[database_config] +config_file = "" +#contact_points = "localhost" +#contact_port = 9042 +#username = "cassandra" +#password = "cassandra" +#storage = "cassandra" +``` + +モジュールに渡すパラメータは設定ファイルで定義できます。詳細については、以下のサンプル設定ファイルと [共通パラメータ](#共通パラメータ)で使用可能なパラメータを参照してください。 + +- **TPC-C:** [`tpcc-benchmark-config.toml`](https://github.com/scalar-labs/scalardb-benchmarks/blob/master/tpcc-benchmark-config.toml) +- **YCSB:** [`ycsb-benchmark-config.toml`](https://github.com/scalar-labs/scalardb-benchmarks/blob/master/ycsb-benchmark-config.toml) +- **マルチストレージ YCSB:** [`ycsb-multi-storage-benchmark-config.toml`](https://github.com/scalar-labs/scalardb-benchmarks/blob/master/ycsb-multi-storage-benchmark-config.toml) + +## ベンチマークを実行する + +ベンチマークを選択し、指示に従ってベンチマークを実行します。 + + + + TPC-C ベンチマークを実行するには、`` を Kelpie ディレクトリへのパスに置き換えて、次のコマンドを実行します。 + + ```console + //bin/kelpie --config tpcc-benchmark-config.toml + ``` + + + YCSB ベンチマークを実行するには、`` を Kelpie ディレクトリへのパスに置き換えて、次のコマンドを実行します。 + + ```console + //bin/kelpie --config ycsb-benchmark-config.toml + ``` + + + マルチストレージ YCSB ベンチマークを実行するには、`` を Kelpie ディレクトリへのパスに置き換えて、次のコマンドを実行します。 + + ```console + //bin/kelpie --config ycsb-multi-storage-benchmark-config.toml + ``` + + + +さらに、次のオプションが利用可能です。 + +- `--only-pre`。データのみをロードします。 +- `--only-process`。ベンチマークのみを実行します。 +- `--except-pre`。データをロードせずにジョブを実行します。 +- `--except-process`。ベンチマークを実行せずにジョブを実行します。 + +## 共通パラメータ + +| 名前 | 説明 | デフォルト | +|:---------------|:----------------------------------|:----------| +| `concurrency` | ベンチマーク用のスレッド数。 | `1` | +| `run_for_sec` | ベンチマークの継続時間 (秒単位)。 | `60` | +| `ramp_for_sec` | ベンチマーク前の立ち上げ時間 (秒単位)。 | `0` | + +## ワークロード固有のパラメータ + +ワークロードを選択すると、使用可能なパラメータが表示されます。 + + + + | 名前 | 説明 | デフォルト | + |:-----------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------| + | `num_warehouses` | ベンチマーク用のウェアハウスの数 (スケール係数)。 | `1` | + | `load_concurrency` | ロード用のスレッド数。 | `1` | + | `load_start_warehouse` | ロード中のウェアハウスの開始 ID。このオプションは、複数のクライアントで大規模なデータをロードする場合や、ウェアハウスを追加する場合に、`--skip-item-load` と一緒に使用すると便利です。 | `1` | + | `load_end_warehouse` | ロード中のウェアハウスの終了 ID。ロード中のウェアハウスの数を指定するには、`--num-warehouses` または `--end-warehouse` のいずれかを使用できます。 | `1` | + | `skip_item_load` | アイテムテーブルのロードをスキップするかどうか。 | `false` | + | `use_table_index` | ScalarDB のセカンダリインデックスの代わりに、汎用テーブルベースのセカンダリインデックスを使用するかどうか。 | `false` | + | `np_only` | 新規注文と支払いトランザクションのみ (それぞれ 50%) でベンチマークを実行します。 | `false` | + | `rate_new_order` | 新規注文トランザクションの割合。必要に応じてこの割合を指定する場合、他のすべてのレートパラメータの割合を指定する必要があります。その場合、すべてのレートパラメータの合計は 100% に等しくなければなりません。 | N/A | + | `rate_payment` | 支払いトランザクションの割合。必要に応じてこの割合を指定する場合、他のすべてのレートパラメータの割合を指定する必要があります。その場合、すべてのレートパラメータの合計は 100% に等しくなければなりません。 | N/A | + | `rate_order_status` | 注文ステータストランザクションの割合。ニーズに基づいてこのパーセンテージを指定する場合、他のすべてのレートパラメータのパーセンテージを指定する必要があります。その場合、すべてのレートパラメータの合計は 100 パーセントに等しくなければなりません。 | N/A | + | `rate_delivery` | 配送トランザクションのパーセンテージ。ニーズに基づいてこのパーセンテージを指定する場合、他のすべてのレートパラメータのパーセンテージを指定する必要があります。その場合、すべてのレートパラメータの合計は 100 パーセントに等しくなければなりません。 | N/A | + | `rate_stock_level` | 在庫レベルトランザクションのパーセンテージ。ニーズに基づいてこのパーセンテージを指定する場合、他のすべてのレートパラメータのパーセンテージを指定する必要があります。その場合、すべてのレートパラメータの合計は 100 パーセントに等しくなければなりません。 | N/A | + | `backoff` | 競合によりトランザクションがアボートされた後に挿入されるスリープ時間 (ミリ秒単位)。 | `0` | + + + | 名前 | 説明 | デフォルト | + |:------------------------|:----------------------------------------------------------------------------------|:----------------------------------------------| + | `load_concurrency` | ロード用のスレッド数。 | `1` | + | `load_batch_size` | 1回のロードトランザクションで入力されるレコード数。 | `1` | + | `load_overwrite` | レコードをロードするときに上書きするかどうか。 | `false` | + | `ops_per_tx` | 1回のトランザクションでの操作数。 | `2` (ワークロード A および C)
`1` (ワークロード F) | + | `record_count` | ターゲットテーブル内のレコード数。 | `1000` | + | `use_read_modify_write` | ワークロード A でブラインド書き込みではなく読み取り、変更、書き込みを使用するかどうか。 | `false`[^rmw] | + + [^rmw]: ワークロード A はトランザクションが最初に元のレコードを読み取ることを想定していないため、`use_read_modify_write` のデフォルト値は `false` です。ただし、トランザクションマネージャーとして Consensus Commit を使用している場合は、`use_read_modify_write` を `true` に設定する必要があります。これは、ScalarDB が既存のレコードに対するブラインド書き込みを許可しないためです。 + + diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/common-reference.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/common-reference.mdx new file mode 100644 index 00000000..2b3c265d --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/common-reference.mdx @@ -0,0 +1,166 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster .NET Client SDK リファレンス + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このリファレンスでは、ScalarDB Cluster .NET Client SDK の動作について詳しく説明します。 + +## クライアント設定 + +クライアントは、次のものを使用して設定できます。 + +- 設定ファイル (`appsettings.json` など) またはカスタム JSON ファイル +- 環境変数 +- `ScalarDbOptions` オブジェクト + +ASP.NET Core で SDK を使用する場合は、アプリをさまざまな方法で設定できます。詳細については、[ASP.NET Core の構成](https://learn.microsoft.com/ja-jp/aspnet/core/fundamentals/configuration/?view=aspnetcore-8.0)を参照してください。 + +設定できるオプションの一覧については、[使用可能なオプション](#使用可能なオプション)を参照してください。 + +### 設定ファイルの使用 + +SDK は、標準の `appsettings.json` とカスタム JSON 設定ファイルの両方をサポートしています。 JSON ファイルでクライアントを設定するには、`ScalarDbOptions` セクションを追加し、必要なオプションを設定します。例: + +```json +{ + "ScalarDbOptions": { + "Address": "http://localhost:60053", + "HopLimit": 10 + } +} +``` + +次に、次のように設定された `TransactionFactory` オブジェクトを作成します。 + +```c# +// If appsettings.json is used, call the Create() method without parameters. +var factory = TransactionFactory.Create(); + +// Or, if a custom file is used, call the Create() method that is passed in the path to the custom file as a parameter. +factory = TransactionFactory.Create("scalardb-options.json"); +``` + +ASP.NET Core で SDK を使用する場合、登録されたトランザクションマネージャーや `ScalarDbContext` が作成されると、`appsettings.json` の設定が自動的に適用されます。カスタム JSON ファイルを使用する場合は、次のように設定フレームワークに追加します。 + +```c# +var builder = WebApplication.CreateBuilder(args); + +// ... + +builder.Configuration.AddJsonFile("scalardb-options.json"); +``` + +:::warning + +カスタム JSON ファイルはすべての標準設定プロバイダーの後に適用されるため、カスタムファイルの値が他のソースの値を上書きします。 + +::: + +### 環境変数の使用 + +クライアントが環境変数を使用するように設定するには、プレフィックス `ScalarDbOptions__` を使用します。例: + +```console +export ScalarDbOptions__Address="http://localhost:60053" +export ScalarDbOptions__HopLimit=10 +``` + +:::warning + +環境変数の値は設定ファイルの値を上書きします。 + +::: + +### `ScalarDbOptions` オブジェクトの使用 + +次のように `ScalarDbOptions` オブジェクトを使用して、実行時にクライアントを設定できます。 + +```c# +var options = new ScalarDbOptions() +{ + Address = "http://localhost:60053", + HopLimit = 10 +}; + +var factory = TransactionFactory.Create(options); +``` + +また、次のように、JSON ファイルや環境変数の値を使用して `ScalarDbOptions` オブジェクトを初期化し、残りの値を実行時に設定することもできます。 + +```c# +// If appsettings.json is used, call the Load() method without parameters. +var options = ScalarDbOptions.Load(); + +// Or, if a custom file is used, call the Load() method that is passed in the path to the custom file as a parameter. +options = ScalarDbOptions.Load("scalardb-options.json"); + +options.HopLimit = 10; + +var factory = TransactionFactory.Create(options); +``` + +ASP.NET Core で SDK を使用する場合は、次のように `AddScalarDb` および `AddScalarDbContext` のラムダ式を使用できます。 + +```c# +var builder = WebApplication.CreateBuilder(args); + +//... + +builder.Services.AddScalarDb(options => +{ + options.Address = "http://localhost:60053"; + options.HopLimit = 10; +}); + +builder.Services.AddScalarDbContext(options => +{ + options.Address = "http://localhost:60053"; + options.HopLimit = 10; +}); +``` + +この構成を使用すると、ラムダ式に渡される `ScalarDbOptions` オブジェクト (上記の例では `options` という名前) が、JSON ファイル、環境変数、およびその他のソースからの値で初期化されます。 + +### 使用可能なオプション + +利用可能なオプションは次のとおりです。 + +| 名前 | 説明 | デフォルト | +|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------| +| `Address` | **必須:** クラスターのアドレス。形式は `://:` です。``: ワイヤ暗号化 (TLS) が有効な場合は `https`、それ以外の場合は `http` です。``: クラスターの FQDN または IP アドレスです。``: クラスターのポート番号 (デフォルトでは `60053`)。 | - | +| `HopLimit` | クラスターへのリクエストのホップ数。`HopLimit` の目的は、クラスター内での無限ループを防ぐことです。リクエストが別のクラスターノードに転送されるたびに、`HopLimit` は 1 ずつ減少します。`HopLimit` が 0 に達すると、リクエストは拒否されます。 | `3` | +| `RetryCount` | クラスターが利用できない場合にクライアントがクラスターへの接続を試行できる回数。 | `10` | +| `AuthEnabled` | 認証と認可が有効かどうか。 | `false` | +| `Username` | 認証/認可のためのユーザー名。 | | +| `Password` | 認証用のパスワード。設定されていない場合は、パスワードなしで認証が行われます。 | | +| `AuthTokenExpirationTime` | 認証トークンを更新するまでの時間。`AuthTokenExpirationTime` に設定された時間がクラスターの有効期限よりも長い場合、認証エラーを受信すると認証トークンが更新されます。認証トークンが正常に更新されると、認証エラーはクライアントコードに伝播されません。代わりに、認証エラーで失敗した操作が自動的に再試行されます。複数の操作が並行して実行されている場合、認証トークンが更新される前に、これらすべての操作が認証エラーで一度失敗します。 | `00:00:00` (クラスターから受信した認証トークンの有効期限が使用されます。) | +| `TlsRootCertPem` | TLS 通信用のカスタム CA ルート証明書 (PEM データ)。 | | +| `TlsRootCertPath` | TLS 通信用のカスタム CA ルート証明書へのファイルパス。 | | +| `TlsOverrideAuthority` | TLS 通信のカスタム認証局。これは、実際に接続しているホストを変更するものではありません。これは主にテストを目的としています。たとえば、クラスターの証明書 (クラスターの `scalar.db.cluster.node.tls.cert_chain_path` パラメータ) に記載されているホスト名を指定できます。クラスターの証明書に複数のホスト名がある場合は、最初のホスト名のみがチェックされます。 | | +| `LogSensitiveData` | `true` に設定すると、gRPC リクエストとレスポンスをログに記録するときに、ユーザー名、パスワード、認証トークンなどの情報がマスクされずにそのままログに記録されます。 | `false` | +| `GrpcRequestTimeout` | gRPC リクエストのタイムアウト。内部的には、タイムアウトの値はクラスターへの各 gRPC リクエストのデッドラインを計算して設定するために使用されます。設定されたデッドラインを超えると、リクエストはキャンセルされ、`DeadlineExceededException` がスローされます。タイムアウトが `0` に設定されている場合、デッドラインは設定されません。 | `00:01:00` | +| `GrpcMaxReceiveMessageSize` | クライアントが受信できる最大メッセージ サイズ (バイト単位)。`0` に設定すると、メッセージ サイズは無制限になります。 | `4 MB` | +| `GrpcMaxSendMessageSize` | クライアントから送信できる最大メッセージ サイズ (バイト単位)。`0` に設定すると、メッセージ サイズは無制限になります。 | `0` (無制限) | + +## ScalarDB 列型と .NET 型間の変換方法 + +[LINQ](getting-started-with-linq.mdx#クラスを設定する) または [Transactional API](getting-started-with-scalardb-tables-as-csharp-classes.mdx#すべての-scalardb-テーブルのクラスを作成する)、[SQL API](getting-started-with-distributed-sql-transactions.mdx#sql-クエリを実行する)、または [Administrative API](getting-started-with-scalardb-tables-as-csharp-classes.mdx#administrative-api-を使用する) の拡張メソッドを使用すると、クラスターから受信した列の値は、対応する .NET 型に自動的に変換されます。同様に、オブジェクトがクラスターに保存されるときに、.NET プロパティの値は対応するクラスターの型に自動的に変換されます。 + +次の表に、型がどのように変換されるかを示します。 + +| ScalarDB 型 | .NET 型 | C# エイリアス | +|------------|----------------------------|-------------| +| TEXT | System.String | string | +| INT | System.Int32 | int | +| BIGINT | System.Int64 | long | +| FLOAT | System.Single | float | +| DOUBLE | System.Double | double | +| BOOLEAN | System.Boolean | bool | +| BLOB | Google.Protobuf.ByteString | | diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/exception-handling.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/exception-handling.mdx new file mode 100644 index 00000000..5170e6c5 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/exception-handling.mdx @@ -0,0 +1,176 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster .NET Client SDK での例外処理 + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +トランザクションを実行するときは、例外も適切に処理する必要があります。 + +:::warning + +例外を適切に処理しないと、異常やデータの不整合が発生する可能性があります。 + +::: + +:::note + +この例では Transactional API が使用されていますが、SQL API または `ScalarDbContext` を使用する場合も例外は同じ方法で処理できます。 + +::: + +次のサンプルコードは、例外を処理する方法を示しています。 + +```c# +using System.ComponentModel.DataAnnotations.Schema; +using ScalarDB.Client; +using ScalarDB.Client.DataAnnotations; +using ScalarDB.Client.Exceptions; +using ScalarDB.Client.Extensions; + +var options = new ScalarDbOptions { Address = "http://:"}; + +var factory = TransactionFactory.Create(options); +using var manager = factory.GetTransactionManager(); + +var retryCount = 0; +TransactionException? lastException = null; + +while (true) +{ + if (retryCount++ > 0) + { + // Retry the transaction three times maximum in this sample code + if (retryCount > 3) + // Throw the last exception if the number of retries exceeds the maximum + throw lastException!; + + // Sleep 100 milliseconds before retrying the transaction in this sample code + await Task.Delay(100); + } + + // Begin a transaction + var tran = await manager.BeginAsync(); + try + { + // Execute CRUD operations in the transaction + var getKeys = new Dictionary { { nameof(Item.Id), 1 } }; + var result = await tran.GetAsync(getKeys); + + var scanKeys = new Dictionary { { nameof(Item.Id), 1 } }; + await foreach (var item in tran.ScanAsync(scanKeys, null)) + Console.WriteLine($"{item.Id}, {item.Name}, {item.Price}"); + + await tran.InsertAsync(new Item { Id = 1, Name = "Watermelon", Price = 4500 }); + await tran.DeleteAsync(new Item { Id = 1 }); + + // Commit the transaction + await tran.CommitAsync(); + + return; + } + catch (UnsatisfiedConditionException) + { + // You need to handle `UnsatisfiedConditionException` only if a mutation operation specifies + // a condition. This exception indicates the condition for the mutation operation is not met. + // InsertAsync/UpdateAsync implicitlly sets IfNotExists/IfExists condition + + try + { + await tran.RollbackAsync(); + } + catch (TransactionException ex) + { + // Rolling back the transaction failed. As the transaction should eventually recover, you + // don't need to do anything further. You can simply log the occurrence here + Console.WriteLine($"Rollback error: {ex}"); + } + + // You can handle the exception here, according to your application requirements + + return; + } + catch (UnknownTransactionStatusException) + { + // If you catch `UnknownTransactionStatusException` when committing the transaction, 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 + return; + } + catch (TransactionException ex) + { + // For other exceptions, you can try retrying the transaction. + + // For `TransactionConflictException` and `TransactionNotFoundException`, + // you can basically retry the transaction. However, for the other exceptions, + // the transaction may still fail if the cause of the exception is nontransient. + // In such a case, you will exhaust the number of retries and throw the last exception + + try + { + await tran.RollbackAsync(); + } + catch (TransactionException e) + { + // Rolling back the transaction failed. As the transaction should eventually recover, + // you don't need to do anything further. You can simply log the occurrence here + Console.WriteLine($"Rollback error: {e}"); + } + + lastException = ex; + } +} + +[Table("order_service.items")] +public class Item +{ + [PartitionKey] + [Column("item_id", Order = 0)] + public int Id { get; set; } + + [Column("name", Order = 1)] + public string Name { get; set; } = String.Empty; + + [Column("price", Order = 2)] + public int Price { get; set; } +} + +``` + +:::note + +サンプルコードでは、トランザクションは最大 3 回再試行され、再試行される前に 100 ミリ秒間スリープします。アプリケーションの要件に応じて、指数バックオフなどの再試行ポリシーを選択できます。 + +::: + +### 例外の詳細 + +以下の表は、クラスターとの通信時に発生する可能性のあるトランザクション例外を示しています。 + +| 例外 | 操作 | 説明 | +|-----------------------------------|--------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| AuthorizationErrorException | Put, Insert, Update, Delete, Mutate, Execute, Administrative | 権限が不足しているため、認証に失敗しました。 | +| IllegalArgumentException | 全て | 要求メッセージ内の引数が無効です。 | +| IllegalStateException | 全て | RPC が無効な状態で呼び出されました。 | +| InternalErrorException | 全て | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合は、トランザクションが失敗する可能性があります。 | +| TransactionConflictException | Begin、Join、Rollback を除くすべて | トランザクションの競合が発生しました。このエラーが発生した場合は、トランザクションを最初から再試行してください。 | +| TransactionNotFoundException | Begin、Join を除くすべて | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。このエラーは、トランザクションの有効期限が切れたか、クラスタートポロジの変更によりルーティング情報が更新されたことを示します。この場合、トランザクションを最初から再試行してください。 | +| UnavailableException | 全て | ScalarDB Cluster は、複数回接続を試みても利用できません。 | +| UnknownTransactionStatusException | Commit | トランザクションのステータスは不明です (トランザクションが正常にコミットされたかどうかは不明です)。この状況では、トランザクションが正常にコミットされたかどうかを確認し、そうでない場合は再試行する必要があります。トランザクションステータスの判断はユーザーの責任です。トランザクションステータステーブルを作成し、他のアプリケーションデータと連動して更新すると、役立つ場合があります。そうすることで、テーブル自体からトランザクションのステータスを判断できるようになります。 | +| UnsatisfiedConditionException | Put, Insert, Update, Delete, Mutate | 突然変異条件が満たされていません。 | + +例外が発生した場合は、`Begin` の場合を除き、トランザクションをロールバックする必要があります。トランザクションをロールバックした後、再試行によって解決できる例外については、トランザクションを最初から再試行できます。 + +上記の例外の他に、gRPC ライブラリによってスローされる例外が発生する場合があります。このような場合は、`RpcException` プロパティで詳細を確認できます。 + +また、`ScalarDbContext` は、次の場合に `TransactionException` タイプの例外をスローします。 + +- すでにアクティブなトランザクションがあるときに `BeginTransaction` または `JoinTransaction` が呼び出された場合 +- アクティブなトランザクションがない状態で `CommitTransaction` または `RollbackTransaction` が呼び出された場合 +- アクティブな 2 フェーズコミットトランザクションがない状態で `PrepareTransaction` または `ValidateTransaction` が呼び出された場合 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-admin-api.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-admin-api.mdx new file mode 100644 index 00000000..dba34141 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-admin-api.mdx @@ -0,0 +1,131 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster .NET Client SDK の Administrative API をはじめよう + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +ScalarDB Cluster .NET Client SDK は、ScalarDB Cluster の Administrative API をサポートしています。この API を使用すると、.NET アプリケーションから ScalarDB Cluster を管理できます。 + +:::note + +次の例のように非同期メソッドを使用することをお勧めしますが、代わりに同期メソッドを使用することもできます。 + +::: + +## SDK をインストールする + +ScalarDB Cluster と同じメジャーバージョンとマイナーバージョンの [SDK](https://www.nuget.org/packages/ScalarDB.Client) を .NET プロジェクトにインストールします。組み込みの NuGet パッケージマネージャーを使用してこれを行うことができます。`.` を、使用しているバージョンに置き換えます。 + +```console +dotnet add package ScalarDB.Client --version '..*' +``` + +## 設定ファイルを作成する + +`scalardb-options.json` ファイルを作成し、次の内容を追加します。`` を FQDN または IP アドレスに、`` をクラスターのポート番号 (デフォルトでは `60053`) に置き換えます。 + +```json +{ + "ScalarDbOptions": { + "Address": "http://:", + "HopLimit": 10 + } +} +``` + +設定ファイルやクライアントを設定するその他の方法の詳細については、[クライアント設定](common-reference.mdx#クライアント設定)を参照してください。 + +## トランザクションマネージャーを取得する + +Administrative API とやり取りするためのオブジェクトを取得する必要があります。オブジェクトを取得するには、次のように `TransactionFactory` を使用します。 + +```c# +// Pass the path to the settings file created in the previous step. +var factory = TransactionFactory.Create("scalardb-options.json"); + +using var admin = factory.GetTransactionAdmin(); +``` + +## ScalarDB Cluster の管理 + +ScalarDB Cluster .NET Client SDK を使用して、次の操作を実行できます。 + +### 新しい名前空間を作成する + +```c# +await admin.CreateNamespaceAsync("ns", ifNotExists: true); +``` + +### 名前空間を削除する + +```c# +await admin.DropNamespaceAsync("ns", ifExists: true); +``` + +### 名前空間が存在するかどうかを確認する + +```c# +var namespaceExists = await admin.IsNamespacePresentAsync("ns"); +``` + +### 新しいテーブルを作成する + +```c# +// ... +using ScalarDB.Client.Builders.Admin; +using ScalarDB.Client.Core; + +// ... + +var tableMetadata = + new TableMetadataBuilder() + .AddPartitionKey("pk", DataType.Int) + .AddClusteringKey("ck", DataType.Double) + .AddSecondaryIndex("index", DataType.Float) + .AddColumn("ordinary", DataType.Text) + .Build(); + +await admin.CreateTableAsync("ns", "table_name", tableMetadata, ifNotExists: true); +``` + +### テーブルを削除する + +```c# +await admin.DropTableAsync("ns", "table_name", ifExists: true); +``` + +### テーブルが存在するかどうかを確認する + +```c# +var tableExists = await admin.IsTablePresentAsync("ns", "table_name"); +``` + +### 既存のテーブルの名前を取得する + +```c# +var tablesList = await admin.GetTableNamesAsync("ns"); +``` + +### Coordinator テーブルを作成する + +```c# +await admin.CreateCoordinatorTablesAsync(); +``` + +### Coordinator テーブルを削除する + +```c# +await admin.DropCoordinatorTablesAsync(); +``` + +### Coordinator テーブルが存在するかどうかを確認します + +```c# +var exists = await admin.AreCoordinatorTablesPresentAsync(); +``` diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-aspnet-and-di.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-aspnet-and-di.mdx new file mode 100644 index 00000000..88b2263a --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-aspnet-and-di.mdx @@ -0,0 +1,81 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster .NET Client SDK での ASP.NET Core と依存性注入をはじめよう + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +ScalarDB Cluster .NET Client SDK は、ASP.NET Core などのフレームワークでの依存性注入をサポートしています。 + +## SDK をインストールする + +ScalarDB Cluster と同じメジャーバージョンとマイナーバージョンの [SDK](https://www.nuget.org/packages/ScalarDB.Client) を .NET プロジェクトにインストールします。組み込みの NuGet パッケージマネージャーを使用してこれを行うことができます。`.` を使用しているバージョンに置き換えます。 + +```console +dotnet add package ScalarDB.Client --version '..*' +``` + +## クライアント設定の追加 + +ASP.NET Core アプリの `appsettings.json` ファイルに `ScalarDbOptions` セクションを追加し、`` を FQDN または IP アドレスに、`` をクラスターのポート番号 (デフォルトでは `60053`) に置き換えます。 + +```json +{ + "ScalarDbOptions": { + "Address": "http://:", + "HopLimit": 10 + } +} +``` + +設定ファイルやクライアントを設定するその他の方法の詳細については、[クライアント設定](common-reference.mdx#クライアント設定)を参照してください。 + +## トランザクションマネージャーをセットアップする + +次のように、ScalarDB トランザクションマネージャーを `IServiceCollection` のサービスとして登録できます。 + +```c# +using ScalarDB.Client.Extensions; + +//... + +var builder = WebApplication.CreateBuilder(args); + +//... + +builder.Services.AddScalarDb(); +``` + +トランザクションマネージャーを登録したら、次のようにコントローラーのコンストラクターに挿入できます。 + +```c# +[ApiController] +public class OrderController: ControllerBase +{ + private readonly IDistributedTransactionManager _manager; + private readonly ISqlTransactionManager _sqlManager; + private readonly ITwoPhaseCommitTransactionManager _twoPhaseManager; + private readonly ISqlTwoPhaseCommitTransactionManager _sqlTwoPhaseManager; + private readonly IDistributedTransactionAdmin _admin; + + public OrderController(IDistributedTransactionManager manager, + ISqlTransactionManager sqlManager, + ITwoPhaseCommitTransactionManager twoPhaseManager, + ISqlTwoPhaseCommitTransactionManager sqlTwoPhaseManager, + IDistributedTransactionAdmin admin) + { + _manager = manager; + _sqlManager = sqlManager; + _twoPhaseManager = twoPhaseManager; + _sqlTwoPhaseManager = sqlTwoPhaseManager; + _admin = admin; + } +} +``` + +これらの例は WebApi プロジェクト用ですが、GrpcService プロジェクトでも同様に動作します。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-auth.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-auth.mdx new file mode 100644 index 00000000..3af384cb --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-auth.mdx @@ -0,0 +1,70 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster .NET Client SDK を使用した認証と認可をはじめよう + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +ScalarDB Cluster .NET Client SDK は [認証と認可](../scalardb-cluster/scalardb-auth-with-sql.mdx)をサポートしており、これにより ScalarDB Cluster へのリクエストを認証および認可できます。 + +## SDK をインストールする + +ScalarDB Cluster と同じメジャーバージョンとマイナーバージョンの [SDK](https://www.nuget.org/packages/ScalarDB.Client) を .NET プロジェクトにインストールします。組み込みの NuGet パッケージマネージャーを使用してこれを行うことができます。`.` を使用しているバージョンに置き換えます。 + +```console +dotnet add package ScalarDB.Client --version '..*' +``` + +## 設定ファイルで資格情報を設定する + +設定ファイルの資格情報を次のように設定し、山括弧内の内容を置き換えてください。 + +```json +{ + "ScalarDbOptions": { + "Address": "http://:", + "HopLimit": 10, + "AuthEnabled": true, + "Username": "", + "Password": "" + } +} +``` + +設定ファイルやクライアントを設定するその他の方法の詳細については、[クライアント設定](common-reference.mdx#クライアント設定)を参照してください。 + +## トランザクションマネージャーを取得する + +次のように `TransactionFactory` を使用して、トランザクションマネージャーまたはトランザクション管理オブジェクトを取得する必要があります。`` を `GetTransactionManager()`、`GetTwoPhaseCommitTransactionManager()`、`GetSqlTransactionManager()`、または `GetSqlTwoPhaseCommitTransactionManager()` に置き換えてください。 + +```c# +// Pass the path to the settings file. +var factory = TransactionFactory.Create("scalardb-options.json"); + +// To get a transaction manager +using var manager = factory.(); + +// To get a transaction admin +using var admin = factory.GetTransactionAdmin(); +``` + +提供された資格情報を使用して `TransactionFactory` から作成されたトランザクションマネージャーまたはトランザクション管理オブジェクトは、ScalarDB Cluster に自動的にログインし、通信できます。 + +## ワイヤ暗号化 + +[ワイヤ暗号化](../scalardb-cluster/scalardb-auth-with-sql.mdx#ワイヤ暗号化) もサポートされています。次のように `Address` を `https` で始まる URL に設定することで有効にできます。 + +```json +{ + "ScalarDbOptions": { + "Address": "https://:" + } +} +``` + +設定ファイルやクライアントを設定するその他の方法の詳細については、[クライアント設定](common-reference.mdx#クライアント設定)を参照してください。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-distributed-sql-transactions.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-distributed-sql-transactions.mdx new file mode 100644 index 00000000..1e5ccb6b --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-distributed-sql-transactions.mdx @@ -0,0 +1,195 @@ +--- +tags: + - Enterprise Premium +--- + +# ScalarDB Cluster .NET Client SDK での分散 SQL トランザクションをはじめよう + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +ScalarDB Cluster .NET Client SDK は、ScalarDB Cluster の分散 SQL トランザクション機能をサポートします。SDK には、クラスター内での通信を容易にするためのトランザクションとマネージャーの抽象化が含まれています。 + +:::note + +次の例のように非同期メソッドを使用することをお勧めしますが、代わりに同期メソッドを使用することもできます。 + +::: + +分散非 SQL トランザクションの詳細については、[ScalarDB Cluster .NET Client SDK での分散トランザクションをはじめよう](getting-started-with-distributed-transactions.mdx)を参照してください。 + +## SDK をインストールする + +ScalarDB Cluster と同じメジャーバージョンとマイナーバージョンの [SDK](https://www.nuget.org/packages/ScalarDB.Client) を .NET プロジェクトにインストールします。組み込みの NuGet パッケージマネージャーを使用してこれを行うことができます。`.` を、使用しているバージョンに置き換えます。 + +```console +dotnet add package ScalarDB.Client --version '..*' +``` + +## 設定ファイルを作成する + +`scalardb-options.json` ファイルを作成し、次の内容を追加します。`` を FQDN または IP アドレスに、`` をクラスターのポート番号 (デフォルトでは `60053`) に置き換えます。 + +```json +{ + "ScalarDbOptions": { + "Address": "http://:", + "HopLimit": 10 + } +} +``` + +設定ファイルやクライアントを設定するその他の方法の詳細については、[クライアント設定](common-reference.mdx#クライアント設定)を参照してください。 + +## トランザクションマネージャーを取得する + +分散 SQL トランザクション用のトランザクションマネージャーオブジェクトを取得する必要があります。トランザクションマネージャーオブジェクトを取得するには、次のように `TransactionFactory` を使用します。 + +```c# +// Pass the path to the settings file created in the previous step. +var factory = TransactionFactory.Create("scalardb-options.json"); + +using var manager = factory.GetSqlTransactionManager(); +``` + +## SQL クエリを実行する + +SQL ステートメントを実行するには、次のようにビルダーを使用して作成できる `ISqlStatement` オブジェクトが必要です。 + +```c# +using ScalarDB.Client.Builders.Sql; + +// ... + +var sqlStatement = + new SqlStatementBuilder() + .SetSql("SELECT * FROM order_service.statements WHERE item_id = :item_id") + .AddParam("item_id", 2) + .Build(); +``` + +次のようにトランザクションマネージャーを使用して、単一の SQL ステートメントを直接実行できます。 + +```c# +var resultSet = await manager.ExecuteAsync(sqlStatement); +``` + +`ExecuteAsync` メソッドの結果には、クラスターから受信したレコードが含まれます。特定の列の値は、次の方法で取得できます。 + +```c# +foreach (var record in resultSet.Records) +{ + // Getting an integer value from the "item_id" column. + // If it fails, an exception will be thrown. + var itemId = record.GetValue("item_id"); + + // Trying to get a string value from the "order_id" column. + // If it fails, no exception will be thrown. + if (record.TryGetValue("order_id", out var orderId)) + Console.WriteLine($"order_id: {orderId}"); + + // Checking if the "count" column is null. + if (record.IsNull("count")) + Console.WriteLine("'count' is null"); +} +``` + +`GetValue` および `TryGetValue` で使用する型の詳細については、[ScalarDB 列型を .NET 型に変換する方法](common-reference.mdx#scalardb-列型と-net-型間の変換方法) を参照してください。 + +## トランザクションで SQL クエリを実行する + +1 つのトランザクションの一部として複数の SQL ステートメントを実行するには、トランザクションオブジェクトが必要です。 + +次のようにトランザクションマネージャーを使用してトランザクションオブジェクトを作成できます。 + +```c# +var transaction = await manager.BeginAsync(); +``` + +次のようにして、すでに開始されているトランザクションを再開することもできます。 + +```c# +var transaction = manager.Resume(transactionIdString); +``` + +:::note + +`Resume` メソッドはトランザクションオブジェクトを作成するだけなので、非同期バージョンはありません。このため、間違った ID を使用してトランザクションを再開する可能性があります。 + +::: + +トランザクションには、トランザクションマネージャーと同じ `ExecuteAsync` メソッドがあります。このメソッドを使用して、SQL ステートメントを実行できます。 + +トランザクションをコミットする準備ができたら、次のようにトランザクションの `CommitAsync` メソッドを呼び出すことができます。 + +```c# +await transaction.CommitAsync(); +``` + +トランザクションをロールバックするには、`RollbackAsync` メソッドを使用できます。 + +```c# +await transaction.RollbackAsync(); +``` + +## メタデータを取得する + +次のように、Metadata プロパティを使用して ScalarDB のメタデータを取得できます。 + +```c# +// namespaces, tables metadata +var namespaceNames = new List(); + +await foreach (var ns in manager.Metadata.GetNamespacesAsync()) +{ + namespaceNames.Add(ns.Name); + Console.WriteLine($"Namespace: {ns.Name}"); + + await foreach (var tbl in ns.GetTablesAsync()) + { + Console.WriteLine($" Table: {tbl.Name}"); + + Console.WriteLine($" Columns:"); + foreach (var col in tbl.Columns) + Console.WriteLine($" {col.Name} [{col.DataType}]"); + + Console.WriteLine($" PartitionKey:"); + foreach (var col in tbl.PartitionKey) + Console.WriteLine($" {col.Name}"); + + Console.WriteLine($" ClusteringKey:"); + foreach (var col in tbl.ClusteringKey) + Console.WriteLine($" {col.Name} [{col.ClusteringOrder}]"); + + Console.WriteLine($" Indexes:"); + foreach (var index in tbl.Indexes) + Console.WriteLine($" {index.ColumnName}"); + + Console.WriteLine(); + } +} + +// users metadata +await foreach (var user in manager.Metadata.GetUsersAsync()) +{ + Console.WriteLine($"User: {user.Name} [IsSuperuser: {user.IsSuperuser}]"); + + foreach (var nsName in namespaceNames) + { + Console.WriteLine($" Namespace: {nsName}"); + + Console.WriteLine($" Privileges:"); + foreach (var privilege in await user.GetPrivilegesAsync(nsName)) + Console.WriteLine($" {privilege}"); + } + + Console.WriteLine(); +} +``` + +:::note + +`IAsyncEnumerable` で LINQ メソッドを使用するには、[System.Linq.Async](https://www.nuget.org/packages/System.Linq.Async/) パッケージをインストールします。 + +::: diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-distributed-transactions.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-distributed-transactions.mdx new file mode 100644 index 00000000..91a4e612 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-distributed-transactions.mdx @@ -0,0 +1,329 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster .NET Client SDK での分散トランザクションをはじめよう + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +ScalarDB Cluster .NET Client SDK は、ScalarDB Cluster の分散トランザクション機能をサポートします。SDK には、クラスター内での通信を容易にするためのトランザクションとマネージャーの抽象化が含まれています。 + +:::note + +次の例のように非同期メソッドを使用することをお勧めしますが、代わりに同期バージョンを使用することもできます。 + +::: + +分散 SQL トランザクションの詳細については、[ScalarDB Cluster .NET Client SDK での分散 SQL トランザクションをはじめよう](getting-started-with-distributed-sql-transactions.mdx)を参照してください。 + +## SDK をインストールする + +ScalarDB Cluster と同じメジャーバージョンとマイナーバージョンの [SDK](https://www.nuget.org/packages/ScalarDB.Client) を .NET プロジェクトにインストールします。組み込みの NuGet パッケージマネージャーを使用して、`.` を使用しているバージョンに置き換えることでこれを行うことができます。 + +```console +dotnet add package ScalarDB.Client --version '..*' +``` + +## 設定ファイルを作成する + +`scalardb-options.json` ファイルを作成し、次の内容を追加します。`` を FQDN または IP アドレスに、`` をクラスターのポート番号 (デフォルトでは `60053`) に置き換えます。 + +```json +{ + "ScalarDbOptions": { + "Address": "http://:", + "HopLimit": 10 + } +} +``` + +設定ファイルやクライアントを設定するその他の方法の詳細については、[クライアント設定](common-reference.mdx#クライアント設定)を参照してください。 + +## トランザクションマネージャーを取得する + +分散トランザクションにはトランザクションマネージャーを取得する必要があります。トランザクションマネージャーを取得するには、次のように `TransactionFactory` を使用します。 + +```c# +// Pass the path to the settings file created in the previous step. +var factory = TransactionFactory.Create("scalardb-options.json"); + +using var manager = factory.GetTransactionManager(); +``` + +## トランザクションを管理する + +複数の CRUD 操作を単一のトランザクションの一部として実行するには、まずトランザクションを開始する必要があります。次のようにトランザクションマネージャーを使用してトランザクションを開始できます。 + +```c# +var transaction = await manager.BeginAsync(); +``` + +次のようにして、すでに実行中のトランザクションを再開することもできます。 + +```c# +var transaction = manager.Resume(transactionIdString); +``` + +:::note + +`Resume` メソッドはトランザクションオブジェクトを作成するだけなので、非同期バージョンはありません。このため、間違った ID を使用してトランザクションを再開する可能性があります。 + +::: + +トランザクションをコミットする準備ができたら、次のようにトランザクションの `CommitAsync` メソッドを呼び出すことができます。 + +```c# +await transaction.CommitAsync(); +``` + +トランザクションをロールバックするには、`RollbackAsync` メソッドを使用できます。 + +```c# +await transaction.RollbackAsync(); +``` + +## CRUD 操作を実行する + +トランザクションには、クラスターに対して CRUD 操作を実行するための `GetAsync`、`ScanAsync`、`InsertAsync`、`UpsertAsync`、`UpdateAsync`、`DeleteAsync`、および `MutateAsync` メソッドがあります。パラメーターとして、これらのメソッドには操作オブジェクトがあります。操作オブジェクトは、このセクションにリストされているビルダーを使用して作成できます。 + +:::note + +CRUD 操作は、トランザクションを明示的に作成する必要なく、ワンショットトランザクション方式で実行できます。そのために、マネージャーオブジェクトには、トランザクションオブジェクトと同じ CRUD メソッドがあります。 + +::: + +ビルダーを使用するには、`using` セクションに次の名前空間を追加します。 + +```c# +using ScalarDB.Client.Builders; +``` + +:::note + +クラスターは 1 つのトランザクション内でのコマンドの並列実行をサポートしていないため、非同期メソッドには必ず `await` を使用してください。 + +::: + +### `GetAsync` メソッドの例 + +単一のレコードを取得するには、次のように `GetAsync` メソッドを使用します。 + +```c# +var get = + new GetBuilder() + .SetNamespaceName("ns") + .SetTableName("statements") + .AddPartitionKey("order_id", "1") + .AddClusteringKey("item_id", 2) + .SetProjections("item_id", "count") + .Build(); + +var getResult = await transaction.GetAsync(get); +``` + +パーティションキーの代わりにインデックスを使用してレコードを取得することも可能です。そのためには、次のように操作の種類を `GetWithIndex` に設定する必要があります。 + +```c# +// ... +using ScalarDB.Client.Core; + +// ... + +var get = + new GetBuilder() + // ... + .SetGetType(GetOperationType.GetWithIndex) + .AddPartitionKey("index_column", "1") + .Build(); +``` + +取得されたレコードが満たす必要のある任意の条件を指定することもできます。満たさない場合はレコードは返されません。条件は、次のように条件の結合として設定できます。 + +```c# +var get = + new GetBuilder() + // ... + .AddConjunction(c => c.AddCondition("cost", 1000, Operator.LessThan)) + .AddConjunction(c => + { + c.AddCondition("cost", 10000, Operator.LessThan); + c.AddCondition("in_stock", true, Operator.Equal); + }) + .Build(); +``` + +上記の例では、`cost` が `1000` 未満の場合、または `cost` が `10000` 未満で `in_stock` が true の場合にのみ、レコードが返されます。 + +#### `IResult` オブジェクトの処理 + +`GetAsync` メソッドと `ScanAsync` メソッドは `IResult` オブジェクトを返します。`IResult` オブジェクトには、取得されたレコードの列が含まれます。特定の列の値は、次の方法で取得できます。 + +```c# +// Getting an integer value from the "item_id" column. +// If it fails, an exception will be thrown. +var itemId = result.GetValue("item_id"); + +// Trying to get a string value from the "order_id" column. +// If it fails, no exception will be thrown. +if (result.TryGetValue("order_id", out var orderId)) + Console.WriteLine($"order_id: {orderId}"); + +// Checking if the "count" column is null. +if (result.IsNull("count")) + Console.WriteLine("'count' is null"); +``` + +`GetValue` および `TryGetValue` で使用する型の詳細については、[ScalarDB 列型と .NET 型間の変換方法](common-reference.mdx#scalardb-列型を-net-型間の変換方法) を参照してください。 + +### `ScanAsync` メソッドの例 + +レコードの範囲を取得するには、次のように `ScanAsync` メソッドを使用できます。 + +```c# +var scan = + new ScanBuilder() + .SetNamespaceName("ns") + .SetTableName("statements") + .AddPartitionKey("order_id", "1") + .AddStartClusteringKey("item_id", 2) + .SetStartInclusive(true) + .AddEndClusteringKey("item_id", 8) + .SetEndInclusive(true) + .SetProjections("item_id", "count") + .Build(); + +var scanResult = await transaction.ScanAsync(scan); +``` + +パーティションキーの代わりにインデックスを使用してレコードを取得することも可能です。そのためには、次のように操作の種類を `ScanWithIndex` に設定する必要があります。 + +```c# +// ... +using ScalarDB.Client.Core; + +// ... +var scan = + new ScanBuilder() + // ... + .SetScanType(ScanOperationType.ScanWithIndex) + .AddPartitionKey("index_column", "1") + .Build(); +``` + +取得されたレコードが満たす必要のある任意の条件は、[get 操作](getting-started-with-distributed-transactions.mdx#getasync-メソッドの例)の場合と同様に、スキャン操作に対しても設定できます。 + +### `InsertAsync` メソッドの例 + +新しいレコードを挿入するには、次のように `InsertAsync` メソッドを使用します。 + +```c# +var insert = + new InsertBuilder() + .SetNamespaceName("ns") + .SetTableName("statements") + .AddPartitionKey("order_id", "1") + .AddClusteringKey("item_id", 2) + .AddColumn("count", 11) + .Build(); + +await transaction.InsertAsync(insert); +``` + +### `UpsertAsync` メソッドの例 + +レコードをUPSERTする (既存のレコードを更新するか、新しいレコードを挿入する) には、次のように `UpsertAsync` メソッドを使用できます。 + +```c# +var upsert = + new UpsertBuilder() + .SetNamespaceName("ns") + .SetTableName("statements") + .AddPartitionKey("order_id", "1") + .AddClusteringKey("item_id", 2) + .AddColumn("count", 11) + .Build(); + +await transaction.UpsertAsync(upsert); +``` + +### `UpdateAsync` メソッドの例 + +既存のレコードを更新するには、次のように `UpdateAsync` メソッドを使用します。 + +```c# +// ... +using ScalarDB.Client.Core; + +// ... + +var update = + new UpdateBuilder() + .SetNamespaceName("ns") + .SetTableName("statements") + .AddPartitionKey("order_id", "1") + .AddClusteringKey("item_id", 2) + .AddColumn("count", 11) + .AddCondition("processed", false, Operator.Equal) + .Build(); + +await transaction.UpdateAsync(update); +``` + +### `DeleteAsync` メソッドの例 + +レコードを削除するには、次のように `DeleteAsync` メソッドを使用します。 + +```c# +// ... +using ScalarDB.Client.Core; + +// ... +var delete = + new DeleteBuilder() + .SetNamespaceName("ns") + .SetTableName("statements") + .AddPartitionKey("order_id", "1") + .AddClusteringKey("item_id", 2) + .AddCondition("processed", false, Operator.Equal) + .Build(); + +await transaction.DeleteAsync(delete); +``` + +### `MutateAsync` メソッドの例 + +`MutateAsync` メソッドを使用すると、クラスターへの 1 回の呼び出しで複数のミューテーション操作を実行できます。これは次の方法で実行できます。 + +```c# +// ... +using ScalarDB.Client.Core; + +// ... +var mutations = new IMutation[] + { + new InsertBuilder() + // ... + .Build(), + new UpsertBuilder() + // ... + .Build(), + new UpdateBuilder() + // ... + .Build(), + new DeleteBuilder() + // ... + .Build() + }; + +await transaction.MutateAsync(mutations); +``` + +:::note + +`InsertAsync`、`UpsertAsync`、`UpdateAsync`、`DeleteAsync`、または `MutateAsync` メソッドを使用してデータを変更するには、まず `GetAsync` または `ScanAsync` メソッドを使用してデータを取得する必要があります。 + +::: diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-linq.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-linq.mdx new file mode 100644 index 00000000..6f6545ef --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-linq.mdx @@ -0,0 +1,366 @@ +--- +tags: + - Enterprise Premium +--- + +# ScalarDB Cluster .NET Client SDK での LINQ をはじめよう + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +ScalarDB Cluster .NET Client SDK は、LINQ と Entity Framework のような機能を使用してクラスターをクエリすることをサポートしています。 + +:::note + +この SDK は [Entity Framework](https://learn.microsoft.com/ja-jp/ef/) をサポートしていません。代わりに、この SDK は Entity Framework に似た機能を実装します。 + +::: + +:::note + +LINQ を使用するには、クラスターで SQL サポートを有効にする必要があります。 + +::: + +## SDK をインストールする + +ScalarDB Cluster と同じメジャーバージョンとマイナーバージョンの [SDK](https://www.nuget.org/packages/ScalarDB.Client) を .NET プロジェクトにインストールします。組み込みの NuGet パッケージマネージャーを使用してこれを行うことができます。`.` を、使用しているバージョンに置き換えます。 + +```console +dotnet add package ScalarDB.Client --version '..*' +``` + +## クライアント設定の追加 + +ASP.NET Core アプリの `appsettings.json` ファイルに `ScalarDbOptions` セクションを追加し、`` を FQDN または IP アドレスに、`` をクラスターのポート番号 (デフォルトでは `60053`) に置き換えます。 + +```json +{ + "ScalarDbOptions": { + "Address": "http://:", + "HopLimit": 10 + } +} +``` + +設定ファイルやクライアントを設定するその他の方法の詳細については、[クライアント設定](common-reference.mdx#クライアント設定)を参照してください。 + +## クラスを設定する + +SQL サポートが有効になっていることを確認したら、使用する ScalarDB テーブルごとに C# クラスを作成します。例: + +```c# +using System.ComponentModel.DataAnnotations.Schema; +using ScalarDB.Client.DataAnnotations; + +// ... + +[Table("ns.statements")] +public class Statement +{ + [PartitionKey] + [Column("statement_id", Order = 0)] + public int Id { get; set; } + + [SecondaryIndex] + [Column("order_id", Order = 1)] + public string OrderId { get; set; } = String.Empty; + + [SecondaryIndex] + [Column("item_id", Order = 2)] + public int ItemId { get; set; } + + [Column("count", Order = 3)] + public int Count { get; set; } +} + +[Table("order_service.items")] +public class Item +{ + [PartitionKey] + [Column("item_id", Order = 0)] + public int Id { get; set; } + + [Column("name", Order = 1)] + public string Name { get; set; } = String.Empty; + + [Column("price", Order = 2)] + public int Price { get; set; } +} +``` + +パーティションキー、クラスタリングキー、またはセカンダリインデックスが複数の列で設定されている場合、`ColumnAttribute` の `Order` プロパティによってキーまたはインデックス内の順序が決まります。 + +プロパティに使用する型の詳細については、[ScalarDB 列型と .NET 型間の変換方法](common-reference.mdx#scalardb-列型と-net-型間の変換方法) を参照してください。 + +使用するすべてのテーブルのプロパティを持つコンテキストクラスを作成します。例: + +```c# + public class MyDbContext: ScalarDbContext + { + public ScalarDbSet Statements { get; set; } + public ScalarDbSet Items { get; set; } + } +``` + +すべてのクラスが作成されたら、作成されたコンテキストを依存性注入に追加する必要があります。例: + +```c# +using ScalarDB.Client.Extensions; + +//... + +var builder = WebApplication.CreateBuilder(args); + +//... + +builder.Services.AddScalarDbContext(); +``` + +コンテキストは、次のようにコントローラーのコンストラクターに挿入できます。 + +```c# +[ApiController] +public class OrderController: ControllerBase +{ + private readonly MyDbContext _myDbContext; + + public OrderController(MyDbContext myDbContext) + { + _myDbContext = myDbContext; + } +} +``` + +## LINQ を使用してプロパティをクエリする + +コントローラーで `MyDbContext` を受け取ったら、LINQ を使用してそのプロパティをクエリできます。例: + +### クエリ構文を使用する + +```c# +from stat in _myDbContext.Statements +join item in _myDbContext.Items on stat.ItemId equals item.Id +where stat.Count > 2 && item.Name.Contains("apple") +orderby stat.Count descending, stat.ItemId +select new { item.Name, stat.Count }; +``` + +### メソッド構文を使用する + +```c# +_myDbContext.Statements + .Where(stat => stat.OrderId == "1") + .Skip(1) + .Take(2); +``` + +### `First` メソッドを使用して、パーティションキーで 1 つの `Statement` を取得します。 + +```c# +_myDbContext.Statements.First(stat => stat.OrderId == "1"); +``` + +### `DefaultIfEmpty` メソッドを使用して左外部結合を実行します + +```c# +from stat in _myDbContext.Statements +join item in _myDbContext.Items on stat.ItemId equals item.Id into items +from i in items.DefaultIfEmpty() +select new { ItemName = i != null ? i.Name : "" } +``` + +以下のメソッドがサポートされています: + +- `Select` +- `Where` +- `Join` +- `GroupJoin` +- `First`/`FirstOrDefault` +- `Skip` +- `Take` +- `OrderBy`/`OrderByDescending` +- `ThenBy`/`ThenByDescending` + +次の `String` メソッドは、`Where` メソッドと `First`/`FirstOrDefault` メソッドの述語内でサポートされています。 + +- `Contains` +- `StartsWith` +- `EndsWith` + +サポートされていない LINQ メソッドは、サポートされているメソッドの後に使用できます。例: + +```c# +_myDbContext.Statements + .Where(stat => stat.OrderId == "1") // Will be executed remotely on the cluster. + .Distinct() // Will be executed locally in the app. + .Where(stat => stat.ItemId < 5); // Will be executed locally. +``` + +:::note + +`Take` または `First`/`FirstOrDefault` の前に `Skip` が指定されている場合、`Skip` に渡される数値が SQL クエリの `LIMIT` 数値に追加されます。`Skip` 自体では、結果の SQL クエリは変更されません。 + +::: + +## `ScalarDbSet{T}` オブジェクトに対して LINQ を使用する場合の制限 + +- すべてのメソッド呼び出しは `Select` 内でサポートされます。例: + +```c# +.Select(stat => convertToSomething(stat.ItemId)) +//... +.Select(stat => stat.ItemId * getSomeNumber()) +``` + +- クエリオブジェクトに対する呼び出しを除くメソッド呼び出しは、`Where` および `First`/`FirstOrDefault` 内でもサポートされます。例: + +```c# +.Where(stat => stat.ItemId == getItemId()) // is OK +//... +.Where(stat => stat.ItemId.ToString() == "1") // is not supported +``` + +- すべてのメソッド呼び出しは、`Join` および `GroupJoin` の結果選択ラムダ内でサポートされます。例: + +```c# +.Join(_myDbContext.Items, + stat => stat.ItemId, + item => item.Id, + (stat, item) => new { ItemName = convertToSomething(item.Name), + ItemCount = stat.Count.ToString() }) +``` + +- `Join` および `GroupJoin` のキー選択ラムダ内では、メソッド呼び出しはサポートされていません。 +- カスタム等価比較子はサポートされていません。`Join` および `GroupJoin` メソッドの `comparer` 引数は、引数が渡された場合は無視されます。 +- `DefaultIfEmpty` メソッドを使用して左外部結合を実行する場合を除き、1 つのクエリ内で複数の `from` を直接使用することはサポートされていません。後続の各 `from` は、個別のクエリと見なされます。 + +```c# +var firstQuery = from stat in _myDbContext.Statements + where stat.Count > 2 + select new { stat.Count }; + +var secondQuery = from item in _myDbContext.Items + where item.Price > 6 + select new { item.Name }; + +var finalQuery = from first in firstQuery + from second in secondQuery + select new { first.Count, second.Name }; + +// 1. firstQuery will be executed against the cluster. +// 2. secondQuery will be executed against the cluster for each object (row) from 1. +// 3. finalQuery will be executed locally with the results from 1 and 2. +var result = finalQuery.ToArray(); +``` + +- メソッド呼び出しは、`OrderBy`/`OrderByDescending` または `ThenBy`/`ThenByDescending` 内ではサポートされていません。 +- `Where` および `First`/`FirstOrDefault` 内では、単一の文字列引数を持つ `Contains`、`StartsWith`、および `EndsWith` メソッドのオーバーロードのみがサポートされています。 + +## `ScalarDbContext` を使用してクラスター内のデータを変更する + +`ScalarDbContext` から継承されたクラスのプロパティを使用して、データを変更できます。 + +### `AddAsync` メソッドを使用して新しいオブジェクトを追加します + +```c# +var statement = new Statement + { + OrderId = "2", + ItemId = 4, + Count = 8 + }; +await _myDbContext.Statements.AddAsync(statement); +``` + +### `UpdateAsync` メソッドを使用してオブジェクトを更新する + +```c# +var statement = _myDbContext.Statements.First(stat => stat.Id == 1); + +// ... + +statement.Count = 10; +await _myDbContext.Statements.UpdateAsync(statement); +``` + +### `RemoveAsync` メソッドを使用してオブジェクトを削除する + +```c# +var statement = _myDbContext.Statements.First(stat => stat.Id == 1); + +// ... + +await _myDbContext.Statements.RemoveAsync(statement); +``` + +## トランザクションの管理 + +LINQ クエリと `AddAsync`、`UpdateAsync`、および `RemoveAsync` メソッドは、明示的に開始されたトランザクションなしで実行できます。ただし、1 つのトランザクションの一部として複数のクエリとメソッドを実行するには、トランザクションを明示的に開始してコミットする必要があります。`ScalarDbContext` は、通常のトランザクションと、ScalarDB の 2 フェーズコミットインターフェイスを使用したトランザクションの両方をサポートします。 + +### 新しいトランザクションを開始する + +```c# +await _myDbContext.BeginTransactionAsync(); +``` + +### 2 フェーズコミットインターフェースで新しいトランザクションを開始する + +```c# +await _myDbContext.BeginTwoPhaseCommitTransactionAsync(); +``` + +### 現在アクティブなトランザクションのIDを取得する + +```c# +var transactionId = _myDbContext.CurrentTransactionId; +``` + +### 2 フェーズコミットインターフェースを使用して既存のトランザクションに参加する + +```c# +await _myDbContext.JoinTwoPhaseCommitTransactionAsync(transactionId); +``` + +### 既存のトランザクションを再開する + +```c# +await _myDbContext.ResumeTransaction(transactionId); +``` + +### 2 フェーズコミットインターフェースを使用して既存のトランザクションを再開する + +```c# +await _myDbContext.ResumeTwoPhaseCommitTransaction(transactionId); +``` + +:::note + +`ResumeTransaction`/`ResumeTwoPhaseCommitTransaction` メソッドには非同期バージョンがありません。これは、クラスターを照会せずに `ScalarDbContext` 継承オブジェクト内のトランザクションデータを初期化するだけだからです。このため、間違った ID を使用してトランザクションを再開する可能性があります。 + +::: + +### トランザクションをコミットする（通常または 2 フェーズコミット） + +```c# +await _myDbContext.CommitTransactionAsync(); +``` + +### トランザクションをロールバックする（通常または 2 フェーズコミット） + +```c# +await _myDbContext.RollbackTransactionAsync(); +``` + +### コミット用の 2 フェーズコミットインターフェースを使用してトランザクションを準備する + +```c# +await _myDbContext.PrepareTransactionAsync(); +``` + +### コミット前に 2 フェーズコミットインターフェースでトランザクションを検証する + +```c# +await _myDbContext.ValidateTransactionAsync(); +``` diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-scalardb-tables-as-csharp-classes.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-scalardb-tables-as-csharp-classes.mdx new file mode 100644 index 00000000..7a5fb2cc --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-scalardb-tables-as-csharp-classes.mdx @@ -0,0 +1,207 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster .NET Client SDK で C# クラスとしてテーブルをはじめよう + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +ScalarDB Cluster .NET Client SDK は、ScalarDB テーブルを C# オブジェクトとして抽象化することで、クラスターにアクセスするコードの作成に役立ちます。クラスター内のテーブルを表すクラスを定義すると、クラスターをクエリするときに列名やその型が混同されないようにすることができます。さらに、テーブルの構造が変更された場合は、IDE のリファクタリング機能を使用してコードに変更を適用できます。 + +:::note + +次の例のように非同期メソッドを使用することをお勧めしますが、代わりに同期メソッドを使用することもできます。 + +::: + +## SDK をインストールする + +ScalarDB Cluster と同じメジャーバージョンとマイナーバージョンの [SDK](https://www.nuget.org/packages/ScalarDB.Client) を .NET プロジェクトにインストールします。組み込みの NuGet パッケージマネージャーを使用してこれを行うことができます。`.` を、使用しているバージョンに置き換えます。 + +```console +dotnet add package ScalarDB.Client --version '..*' +``` + +## すべての ScalarDB テーブルのクラスを作成する + +ScalarDB テーブルを C# オブジェクトとして操作するには、使用するテーブルごとにクラスを作成する必要があります。例: + +```c# +using System.ComponentModel.DataAnnotations.Schema; +using ScalarDB.Client.DataAnnotations; + +// ... + +[Table("ns.statements")] +public class Statement +{ + [PartitionKey] + [Column("order_id", Order = 0)] + public string OrderId { get; set; } = String.Empty; + + [ClusteringKey] + [Column("item_id", Order = 1)] + public int ItemId { get; set; } + + [Column("count", Order = 2)] + public int Count { get; set; } +} +``` + +プロパティに使用する型の詳細については、[ScalarDB 列型と .NET 型間の変換方法](common-reference.mdx#scalardb-列型と-net-型間の変換方法)を参照してください。 + +## CRUD 操作を実行する + +各テーブルのクラスを作成した後、`ITransactionCrudOperable` の汎用 `GetAsync`、`ScanAsync`、`InsertAsync`、`UpdateAsync`、`DeleteAsync`、`UpsertAsync`、または `MutateAsync` メソッドを使用して、クラスをオブジェクトとして使用できます。 + +これらの汎用メソッドを使用するには、`using` セクションに次の名前空間を追加します。 + +```c# +using ScalarDB.Client.Extensions; +``` + +### `GetAsync` メソッドを使用して 1 つのオブジェクトを取得します + +```c# +var keys = new Dictionary + { + { nameof(Statement.OrderId), "1" } + }; +var statement = await transaction.GetAsync(keys); + +Console.WriteLine($"ItemId: {statement.ItemId}, Count: {statement.Count}"); +``` + +### `ScanAsync` メソッドを使用して複数のオブジェクトを取得する + +```c# +var startKeys = new Dictionary + { + { nameof(Statement.OrderId), "1" }, + { nameof(Statement.ItemId), 3 } + }; +var endKeys = new Dictionary + { + { nameof(Statement.ItemId), 6} + }; + +await foreach (var s in transaction.ScanAsync(startKeys, endKeys)) + Console.WriteLine($"ItemId: {s.ItemId}, Count: {s.Count}"); +``` + +:::note + +`IAsyncEnumerable` で LINQ メソッドを使用するには、[System.Linq.Async](https://www.nuget.org/packages/System.Linq.Async/) パッケージをインストールします。 + +::: + +### `InsertAsync` メソッドを使用して新しいオブジェクトを挿入します + +```c# +var statement = new Statement + { + OrderId = "2", + ItemId = 4, + Count = 8 + }; +await transaction.InsertAsync(statement); +``` + +### `UpdateAsync` メソッドを使用してオブジェクトを更新する + +```c# +// ... +statement.ItemId = 4; +statement.Count = 8; + +await transaction.UpdateAsync(statement); +``` + +### `DeleteAsync` メソッドを使用してオブジェクトを削除する + +```c# +// ... +await transaction.DeleteAsync(statement); +``` + +### `UpsertAsync` メソッドを使用してオブジェクトをUPSERTする + +```c# +var statement = new Statement + { + OrderId = "2", + ItemId = 4, + Count = 8 + }; +await transaction.UpsertAsync(statement); +``` + +### `MutateAsync` メソッドを使用して複数のオブジェクトを一度にUPSERTおよび削除する + +```c# +var statement = new Statement + { + OrderId = "2", + ItemId = 4, + Count = 16 + }; + +// ... + +await transaction.MutateAsync(objectsToUpsert: new[] { statement }, + objectsToDelete: new[] { statement2 }); +``` + +:::note + +`UpdateAsync`、`DeleteAsync`、`UpsertAsync`、または `MutateAsync` メソッドを使用してオブジェクトを変更するには、まず `GetAsync` または `ScanAsync` メソッドを使用してオブジェクトを取得する必要があります。 + +::: + +## Administrative API を使用する + +C# オブジェクトも Administrative API で使用できます。汎用 Administrative API メソッドを使用するには、次の名前空間を `using` セクションに追加します。 + +```c# +using ScalarDB.Client.Extensions; +``` + +### 新しい名前空間を作成する + +```c# +await admin.CreateNamespaceAsync(); +``` + +### 既存の名前空間を削除する + +```c# +await admin.DropNamespaceAsync(); +``` + +### 名前空間が存在するかどうかを確認する + +```c# +var namespaceExists = await admin.IsNamespacePresentAsync(); +``` + +### 新しいテーブルを作成する + +```c# +await admin.CreateTableAsync(); +``` + +### 既存のテーブルを削除する + +```c# +await admin.DropTableAsync(); +``` + +### テーブルが存在するかどうかを確認する + +```c# +var tableExists = await admin.IsTablePresentAsync(); +``` diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-two-phase-commit-transactions.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-two-phase-commit-transactions.mdx new file mode 100644 index 00000000..03d6bbb6 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/getting-started-with-two-phase-commit-transactions.mdx @@ -0,0 +1,145 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster .NET Client SDK の 2 フェーズコミットインターフェイスを使用した分散トランザクションをはじめよう + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +ScalarDB Cluster .NET Client SDK は、ScalarDB の 2 フェーズコミットインターフェイスを使用したトランザクションをサポートします。SDK には、クラスター内の通信を強化するためのトランザクションとマネージャーの抽象化が含まれています。 + +:::note + +次の例のように非同期メソッドを使用することをお勧めしますが、代わりに同期メソッドを使用することもできます。 + +::: + +## 2 フェーズコミットインターフェースを使用したトランザクションについて + +SDK を使用すると、複数のアプリケーションにまたがる 2 フェーズコミットインターフェースを使用したトランザクションを実行できます。たとえば、複数のマイクロサービスがある場合、それぞれのマイクロサービスにトランザクションマネージャーを作成し、それらのマイクロサービスにまたがるトランザクションを実行できます。 + +2 フェーズコミットインターフェースを使用したトランザクションには、コーディネーターと参加者の 2 つのロールがあり、これらが協力して 1 つのトランザクションを実行します。 + +コーディネータープロセスは最初にトランザクションを開始し、トランザクションの ID をすべての参加者に送信し、参加者プロセスがトランザクションに参加します。 CRUD または SQL 操作を実行した後、コーディネータープロセスと参加者プロセスは 2 フェーズインターフェースを使用してトランザクションをコミットします。 + +## SDK をインストールする + +ScalarDB Cluster と同じメジャーバージョンとマイナーバージョンの [SDK](https://www.nuget.org/packages/ScalarDB.Client) を .NET プロジェクトにインストールします。組み込みの NuGet パッケージマネージャーを使用してこれを行うことができます。`.` を、使用しているバージョンに置き換えます。 + +```console +dotnet add package ScalarDB.Client --version '..*' +``` + +## 設定ファイルを作成する + +`scalardb-options.json` ファイルを作成し、次の内容を追加します。`` を FQDN または IP アドレスに、`` をクラスターのポート番号 (デフォルトでは `60053`) に置き換えます。 + +```json +{ + "ScalarDbOptions": { + "Address": "http://:", + "HopLimit": 10 + } +} +``` + +設定ファイルやクライアントを設定するその他の方法の詳細については、[クライアント設定](common-reference.mdx#クライアント設定)を参照してください。 + +## トランザクションマネージャーを取得します (コーディネータと参加者用) + +2 フェーズコミットインターフェイスを使用した分散トランザクションには、トランザクションマネージャーを取得する必要があります。トランザクションマネージャーを取得するには、次のように `TransactionFactory` を使用します。 + +```c# +// Pass the path to the settings file created in the previous step. +var factory = TransactionFactory.Create("scalardb-options.json"); + +using var manager = factory.GetTwoPhaseCommitTransactionManager(); +``` + +あるいは、次のトランザクションマネージャーを指定して、2 フェーズコミットインターフェイスを使用したトランザクションに CRUD 操作の代わりに SQL を使用することもできます。 + +```c# +using var manager = factory.GetSqlTwoPhaseCommitTransactionManager(); +``` + +## トランザクションを開始する (コーディネータ用) + +次のように、コーディネータの 2 フェーズコミットインターフェイスを使用してトランザクションを開始できます。 + +```c# +var transaction = await manager.BeginAsync(); +``` + +開始されたトランザクションの ID は、次のコードで取得できます。 + +```c# +var transactionId = transaction.Id; +``` + +## トランザクションに参加する (参加者向け) + +参加者の 2 フェーズコミットインターフェイスを使用して、次のようにトランザクションに参加できます。 + +```c# +var transaction = await manager.JoinAsync(transactionId); +``` + +## トランザクションを再開する (コーディネータと参加者用) + +通常、2 フェーズコミットインターフェイスを使用したトランザクションには、複数の要求と応答の交換が含まれます。以前の要求で開始または参加したトランザクションを操作する必要がある場合は、次のようにしてそのトランザクションを再開できます。 + +```c# +var transaction = manager.Resume(transactionId); +``` + +:::note + +`Resume` メソッドはトランザクションオブジェクトを作成するだけなので、非同期バージョンはありません。このため、間違った ID を使用してトランザクションを再開する可能性があります。 + +::: + +## トランザクションをロールバックする + +トランザクションがコミットに失敗した場合は、次のようにトランザクションをロールバックできます。 + +```c# +await transaction.RollbackAsync(); +``` + +## トランザクションをコミットする (コーディネータと参加者用) + +CRUD または SQL 操作を完了したら、トランザクションをコミットする必要があります。ただし、2 フェーズコミットインターフェイスを使用したトランザクションの場合は、まずコーディネータとすべての参加者でトランザクションを準備する必要があります。 + +```c# +await transaction.PrepareAsync(); +``` + +次に、同時実行制御プロトコルに応じて、次のようにコーディネーターとすべての参加者でトランザクションを検証する必要がある場合があります。 + +```c# +await transaction.ValidateAsync(); +``` + +最後に、次のようにしてコーディネーターとすべての参加者にトランザクションをコミットできます。 + +```c# +await transaction.CommitAsync(); +``` + +コーディネータまたは参加者のいずれかがトランザクションの準備または検証に失敗した場合は、コーディネータとすべての参加者で `RollbackAsync` を呼び出す必要があります。 + +また、コーディネータとすべての参加者がトランザクションのコミットに失敗した場合は、コーディネータとすべての参加者で `RollbackAsync` を呼び出す必要があります。 + +ただし、コーディネータまたは一部の参加者のみがトランザクションのコミットに失敗した場合は、コーディネータまたはいずれかの参加者がトランザクションのコミットに成功している限り、トランザクションはコミットされたとみなされます。 + +## CRUD 操作を実行する + +トランザクションの 2 フェーズコミットインターフェイスには、通常のトランザクションと同じ CRUD 操作メソッドがあります。詳細については、[CRUD 操作を実行する](getting-started-with-distributed-transactions.mdx#crud-操作を実行する) を参照してください。 + +## SQL ステートメントを実行する + +SQL トランザクションの 2 フェーズコミットインターフェイスには、通常の SQL トランザクションと同じ SQL クエリを実行するメソッドがあります。詳細については、[SQL クエリを実行する](getting-started-with-distributed-sql-transactions.mdx#sql-クエリを実行する)を参照してください. diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/index.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/index.mdx new file mode 100644 index 00000000..29e08a9a --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster-dotnet-client-sdk/index.mdx @@ -0,0 +1,25 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster .NET Client SDK の概要 + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +ScalarDB Cluster .NET Client SDK を使用すると、アプリケーションは gRPC を使用して ScalarDB Cluster に接続できるようになります。 + +ScalarDB Cluster .NET Client SDK を使用するには、次の入門ガイドを参照してください。 + +* [分散トランザクションをはじめよう](getting-started-with-distributed-transactions.mdx) +* [分散 SQL トランザクションをはじめよう](getting-started-with-distributed-sql-transactions.mdx) +* [Administrative API をはじめよう](getting-started-with-admin-api.mdx) +* [C# クラスとしての ScalarDB テーブルをはじめよう](getting-started-with-scalardb-tables-as-csharp-classes.mdx) +* [ASP.NET Core と依存性注入をはじめよう](getting-started-with-aspnet-and-di.mdx) +* [LINQ をはじめよう](getting-started-with-linq.mdx) +* [2 フェーズコミットインターフェイスを使用した分散トランザクションをはじめよう](getting-started-with-two-phase-commit-transactions.mdx) +* [認証と認可をはじめよう](getting-started-with-auth.mdx) +* [例外処理](exception-handling.mdx) diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/compatibility.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/compatibility.mdx new file mode 100644 index 00000000..01d53eeb --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/compatibility.mdx @@ -0,0 +1,42 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster 互換性マトリックス + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このドキュメントでは、クライアント SDK バージョン間の ScalarDB Cluster バージョンの互換性を示します。 + +## ScalarDB Cluster とクライアント SDK の互換性 + +| ScalarDB Cluster バージョン | ScalarDB Cluster Java Client SDK バージョン | ScalarDB Cluster .NET Client SDK バージョン | +|:-----------------------|:---------------------------------------|:---------------------------------------| +| 3.14 | 3.9 - 3.14 | 3.12* - 3.13 | +| 3.13 | 3.9 - 3.13 | 3.12* - 3.13 | +| 3.12 | 3.9 - 3.12 | 3.12* | +| 3.11 | 3.9 - 3.11 | サポート対象外 | +| 3.10 | 3.9 - 3.10 | サポート対象外 | +| 3.9 | 3.9 | サポート対象外 | + +\* このバージョンはプライベートプレビュー段階であるため、将来のバージョンでは下位互換性のない更新が行われる可能性があります。 + +## バージョンスキューポリシー + +:::note + +バージョンは `x.y.z` として表されます。`x` はメジャーバージョン、`y` はマイナーバージョン、`z` はパッチバージョンを表します。この形式は [セマンティックバージョニング](https://semver.org/) に従います。 + +::: + +- ScalarDB Cluster とクライアント SDK の **メジャー** バージョンが異なる場合、それらは **互換性がない** ため、**サポートされていません**。 +- ScalarDB Cluster とクライアント SDK の **メジャー** バージョンが同じで、**マイナー** バージョンが異なる場合、ScalarDB Cluster のバージョンはクライアント SDK バージョン以上である必要があります。例: + - **サポート対象:** ScalarDB Cluster 3.13 とクライアント SDK 3.11 の組み合わせ + - **サポート対象外:** ScalarDB Cluster 3.11 とクライアント SDK 3.13 の組み合わせ +- **メジャー** バージョンと **マイナー** バージョンが同じ場合、ScalarDB Cluster とクライアント SDK 間で異なる **パッチ** バージョンを使用できます。例: + - **サポート対象:** ScalarDB Cluster 3.13.2 とクライアント SDK 3.13.0 の組み合わせ + - **サポート対象:** ScalarDB Cluster 3.13.0 とクライアント SDK 3.13.2 の組み合わせ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/developer-guide-for-scalardb-cluster-with-java-api.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/developer-guide-for-scalardb-cluster-with-java-api.mdx new file mode 100644 index 00000000..aae903d8 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/developer-guide-for-scalardb-cluster-with-java-api.mdx @@ -0,0 +1,302 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# Java API を使用した ScalarDB Cluster の開発者ガイド + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +ScalarDB Cluster は、アプリケーションを開発するための Java API を提供します。このドキュメントでは、Java API の使用方法を説明します。 + +## ビルドに ScalarDB Cluster Java Client SDK を追加する + +ScalarDB Cluster Java Client SDK は、[Maven Central Repository](https://mvnrepository.com/artifact/com.scalar-labs/scalardb-cluster-java-client-sdk) で入手できます。 + +Gradle を使用して ScalarDB Cluster Java Client SDK への依存関係を追加するには、以下を使用します。 + +```gradle +dependencies { + implementation 'com.scalar-labs:scalardb-cluster-java-client-sdk:3.14.0' +} +``` + +Maven を使用して依存関係を追加するには、以下を使用します。 + +```xml + + com.scalar-labs + scalardb-cluster-java-client-sdk + 3.14.0 + +``` + +## クライアントモード + +ScalarDB Cluster Java Client SDK は、`indirect` と `direct-kubernetes` の 2 つのクライアントモードをサポートしています。以下では、クライアントモードについて説明します。 + +### `indirect` クライアントモード + +このモードでは、単にリクエストを任意のクラスターノードに送信します (通常は Envoy などのロードバランサー経由)。リクエストを受信したクラスターノードは、トランザクション状態を持つ適切なクラスターノードにリクエストをルーティングします。 + +![ScalarDB Cluster アーキテクチャ](images/indirect-client-mode.png) + +このモードの利点は、クライアントを軽量に保てることです。 +欠点は、正しいクラスターノードに到達するために追加のホップが必要になり、パフォーマンスに影響する可能性があることです。 + +アプリケーションが別の Kubernetes クラスターで実行されていて、アプリケーションが Kubernetes API と各クラスターノードにアクセスできない場合でも、この接続モードを使用できます。 +アプリケーションが ScalarDB Cluster ノードと同じ Kubernetes クラスターで実行されている場合は、`direct-kubernetes` クライアントモードを使用できます。 + +### `direct-kubernetes` クライアントモード + +このモードでは、クライアントはメンバーシップロジック (Kubernetes API を使用) と分散ロジック (コンシステントハッシュアルゴリズム) を使用して、トランザクション状態を持つ適切なクラスターノードを見つけます。次に、クライアントはクラスターノードに直接リクエストを送信します。 + +![ScalarDB Cluster アーキテクチャ](images/direct-kubernetes-client-mode.png) + +このモードの利点は、適切なクラスターノードに到達するためのホップ数を減らすことができるため、パフォーマンスが向上することです。このモードの欠点は、クライアントにメンバーシップロジックとリクエストルーティングロジックが必要なため、クライアントをファットにする必要があることです。 + +この接続モードは Kubernetes API と各クラスターノードにアクセスする必要があるため、アプリケーションが ScalarDB Cluster ノードと同じ Kubernetes クラスターで実行されている場合にのみ、この接続モードを使用できます。アプリケーションが別の Kubernetes クラスターで実行されている場合は、`indirect` クライアントモードを使用します。 + +`direct-kubernetes` クライアントモードで Kubernetes にアプリケーションをデプロイする方法の詳細については、[`direct-kubernetes` モードを使用してクライアントアプリケーションを Kubernetes にデプロイする](../helm-charts/how-to-deploy-scalardb-cluster.mdx#direct-kubernetes-モードを使用してクライアント-アプリケーションを-kubernetes-にデプロイします) を参照してください。 + +## ScalarDB Cluster 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 の使用は、クライアント構成と Schema Loader が異なることを除いて、ScalarDB Java API の使用とほぼ同じです。詳細については、[ScalarDB Java API ガイド](../api-guide.mdx) を参照してください。 + +次のセクションでは、ScalarDB Cluster Java API とクラスター用 Schema Loader のクライアント構成について説明します。 + +### クライアント構成 + +次の表は、ScalarDB Cluster Java API のクライアント構成を示しています。 + +| 名前 | 説明 | デフォルト | +|----------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------| +| `scalar.db.transaction_manager` | `cluster` を指定する必要があります。 | - | +| `scalar.db.contact_points` | クラスターの連絡先。`indirect` クライアントモードを使用する場合は、`indirect:` の形式を使用して、クラスターノードの前にあるロードバランサーの IP アドレスを指定します。`direct-kubernetes` クライアントモードを使用する場合は、`direct-kubernetes:/` または単に `direct-kubernetes:` の形式を使用して、名前空間名 (オプション) と [エンドポイントリソース](https://kubernetes.io/docs/concepts/services-networking/service/#endpoints) の名前を指定して、メンバーシップ情報を取得します。名前空間名を指定しない場合、クライアントは `default` 名前空間を使用します。 | | +| `scalar.db.contact_port` | 連絡先のポート番号。 | `60053` | +| `scalar.db.cluster.grpc.deadline_duration_millis` | gRPC の期限期間（ミリ秒単位）。 | `60000` (60 秒) | +| `scalar.db.cluster.grpc.max_inbound_message_size` | 単一の gRPC フレームに許可される最大メッセージサイズ。 | gRPCのデフォルト値 | +| `scalar.db.cluster.grpc.max_inbound_metadata_size` | 受信できるメタデータの最大サイズ。 | gRPCのデフォルト値 | + +たとえば、`indirect` クライアントモードを使用し、ロードバランサーの IP アドレスが `192.168.10.1` の場合、クライアントを次のように構成できます。 + +```properties +scalar.db.transaction_manager=cluster +scalar.db.contact_points=indirect:192.168.10.1 +``` + +または、エンドポイントの名前空間を `ns`、エンドポイント名を `scalardb-cluster` として `direct-kubernetes` クライアントモードを使用する場合は、次のようにクライアントを構成できます。 + +```properties +scalar.db.transaction_manager=cluster +scalar.db.contact_points=direct-kubernetes:ns/scalardb-cluster +``` + +### クラスター用 Schema Loader + +ScalarDB Cluster 経由でスキーマをロードするには、専用の ScalarDB Cluster 用 Schema Loader (クラスター用 Schema Loader) を使用する必要があります。クラスター用Schema Loader の使用方法は、JAR ファイルの名前が異なることを除いて、[ScalarDB Schema Loader](../schema-loader.mdx) の使用方法と基本的に同じです。クラスター用 Schema Loader は、[ScalarDB リリース](https://github.com/scalar-labs/scalardb/releases/tag/v3.14.0) からダウンロードできます。JAR ファイルをダウンロードしたら、次のコマンドでクラスター用 Schema Loader を実行できます。 + +```console +java -jar scalardb-cluster-schema-loader-3.14.0-all.jar --config -f --coordinator +``` + +## ScalarDB Cluster SQL + +ScalarDB Cluster SQL には、次のように Java の ScalarDB 用 JDBC および Spring Data JDBC を介してアクセスできます。 + +``` + +----------------------------------------------+ + | ユーザー/アプリケーション | + +----------------------------------------------+ + ↓ ↓ Java API +Java API ↓ +-------------------------------+ + (JDBC) ↓ | Spring Data JDBC for ScalarDB | + ↓ +-------------------------------+ ++----------------------------------------------+ +| ScalarDB JDBC (ScalarDB SQL) | ++----------------------------------------------+ + ↓ gRPC + +----------------------+ + | ScalarDB Cluster SQL | + +----------------------+ + ↓ DB ベンダー固有のプロトコル + +----+ + | DB | + +----+ +``` + +このセクションでは、JDBC 経由で ScalarDB Cluster SQL を使用する方法と、Spring Data JDBC for ScalarDB を使用する方法について説明します。 + +### JDBC 経由の ScalarDB Cluster SQL + +JDBC 経由での ScalarDB Cluster SQL の使用は、プロジェクトに JDBC ドライバーを追加する方法を除いて、[ScalarDB JDBC](../scalardb-sql/jdbc-guide.mdx) を使用する場合とほぼ同じです。 + +[ビルドに ScalarDB Cluster Java Client SDK を追加する](#add-scalardb-cluster-java-client-sdk-to-your-build) で説明されているように ScalarDB Cluster Java Client SDK を追加することに加えて、プロジェクトに次の依存関係を追加する必要があります。 + +Gradle を使用して ScalarDB Cluster JDBC ドライバーへの依存関係を追加するには、以下を使用します。 + +```gradle +dependencies { + implementation 'com.scalar-labs:scalardb-sql-jdbc:3.14.0' + implementation 'com.scalar-labs:scalardb-cluster-java-client-sdk:3.14.0' +} +``` + +Maven を使用して依存関係を追加するには、以下を使用します。 + +```xml + + + com.scalar-labs + scalardb-sql-jdbc + 3.14.0 + + + com.scalar-labs + scalardb-cluster-java-client-sdk + 3.14.0 + + +``` + +それ以外は、JDBC 経由で ScalarDB Cluster SQL を使用することは、ScalarDB JDBC を使用することと同じです。ScalarDB JDBC の詳細については、[ScalarDB JDBC ガイド](../scalardb-sql/jdbc-guide.mdx) を参照してください。 + +### Spring Data JDBC for ScalarDB 経由の ScalarDB Cluster SQL + +JDBC 経由の ScalarDB Cluster SQL と同様に、Spring Data JDBC for ScalarDB 経由の ScalarDB Cluster SQL を使用することは、プロジェクトへの追加方法を除いて、[Spring Data JDBC for ScalarDB](../scalardb-sql/spring-data-guide.mdx) を使用することとほぼ同じです。 + +[ScalarDB Cluster Java Client SDK をビルドに追加する](#add-scalardb-cluster-java-client-sdk-to-your-build) で説明されているように ScalarDB Cluster Java Client SDK を追加することに加えて、プロジェクトに次の依存関係を追加する必要があります: + +Gradle を使用して依存関係を追加するには、以下を使用します: + +```gradle +dependencies { + implementation 'com.scalar-labs:scalardb-sql-spring-data:3.14.0' + implementation 'com.scalar-labs:scalardb-cluster-java-client-sdk:3.14.0' +} +``` + +Maven を使用して依存関係を追加するには、以下を使用します。 + +```xml + + + com.scalar-labs + scalardb-sql-spring-data + 3.14.0 + + + com.scalar-labs + scalardb-cluster-java-client-sdk + 3.14.0 + + +``` + +それ以外では、Spring Data JDBC for ScalarDB 経由で ScalarDB Cluster SQL を使用することは、Spring Data JDBC for ScalarDB を使用することと同じです。Spring Data JDBC for ScalarDB の詳細については、[Spring Data JDBC for ScalarDB ガイド](../scalardb-sql/spring-data-guide.mdx) を参照してください。 + +### ScalarDB Cluster SQL クライアント構成 + +次の表は、ScalarDB Cluster SQL の構成を示しています。 + +| 名前 | 説明 | デフォルト | +|----------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------| +| `scalar.db.sql.connection_mode` | `cluster` を指定する必要があります。 | - | +| `scalar.db.sql.cluster_mode.contact_points` | クラスターの連絡先。`indirect` クライアントモードを使用する場合は、`indirect:` の形式を使用して、クラスターノードの前にあるロードバランサーの IP アドレスを指定します。`direct-kubernetes` クライアントモードを使用する場合は、`direct-kubernetes:/` または単に `direct-kubernetes:` の形式を使用して、名前空間名 (オプション) と [エンドポイントリソース](https://kubernetes.io/docs/concepts/services-networking/service/#endpoints) の名前を指定して、メンバーシップ情報を取得します。名前空間名を指定しない場合、クライアントは `default` 名前空間を使用します。 | | +| `scalar.db.sql.cluster_mode.contact_port` | 連絡先のポート番号。 | `60053` | +| `scalar.db.sql.default_transaction_mode` | デフォルトのトランザクションモード。`TRANSACTION` または `TWO_PHASE_COMMIT_TRANSACTION` を設定できます。 | `TRANSACTION` | +| `scalar.db.sql.default_namespace_name` | デフォルトの名前空間名。SQL ステートメントで名前空間名を指定しない場合は、この値が使用されます。 | | +| `scalar.db.cluster.grpc.deadline_duration_millis` | gRPC の期限期間（ミリ秒単位）。 | `60000` (60 秒) | +| `scalar.db.cluster.grpc.max_inbound_message_size` | 単一の gRPC フレームに許可される最大メッセージサイズ。 | gRPCのデフォルト値 | +| `scalar.db.cluster.grpc.max_inbound_metadata_size` | 受信できるメタデータの最大サイズ。 | gRPCのデフォルト値 | + +たとえば、`indirect` クライアントモードを使用し、ロードバランサーの IP アドレスが `192.168.10.1` の場合、クライアントを次のように構成できます。 + +```properties +scalar.db.sql.connection_mode=cluster +scalar.db.sql.cluster_mode.contact_points=indirect:192.168.10.1 +``` + +または、エンドポイントの名前空間を `ns`、エンドポイント名を `scalardb-cluster` として `direct-kubernetes` クライアントモードを使用する場合は、次のようにクライアントを構成できます。 + +```properties +scalar.db.sql.connection_mode=cluster +scalar.db.sql.cluster_mode.contact_points=direct-kubernetes:ns/scalardb-cluster +``` + +ScalarDB JDBC の構成方法の詳細については、[JDBC 接続 URL](../scalardb-sql/jdbc-guide.mdx#jdbc-接続-url) を参照してください。 + +Spring Data JDBC for ScalarDB の構成方法の詳細については、[構成](../scalardb-sql/spring-data-guide.mdx#構成) を参照してください。 + +### SQL CLI + +他の SQL データベースと同様に、ScalarDB SQL にも、コマンドラインシェルで対話的に SQL ステートメントを発行できる CLI ツールが用意されています。 + +Cluster 用の SQL CLI は、[ScalarDB リリース](https://github.com/scalar-labs/scalardb/releases/tag/v3.14.0) からダウンロードできます。JAR ファイルをダウンロードしたら、次のコマンドで SQL CLI を実行できます。 + +```console +java -jar scalardb-cluster-sql-cli-3.14.0-all.jar --config +``` + +#### 使用方法 + +CLI の使用方法は、次のように `-h` オプションを使用して確認できます。 + +```console +java -jar scalardb-cluster-sql-cli-3.14.0-all.jar -h +Usage: scalardb-sql-cli [-hs] -c=PROPERTIES_FILE [-e=COMMAND] [-f=FILE] + [-l=LOG_FILE] [-o=] [-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= + 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 を使用できます。 +ScalarDB Cluster gRPC API の詳細については、以下を参照してください。 + +* [ScalarDB Cluster gRPC API ガイド](scalardb-cluster-grpc-api-guide.mdx) +* [ScalarDB Cluster SQL gRPC API ガイド](scalardb-cluster-sql-grpc-api-guide.mdx) + +Javadocs も利用可能です: + +* [ScalarDB Cluster Java Client SDK](https://javadoc.io/doc/com.scalar-labs/scalardb-cluster-java-client-sdk/3.14.0/index.html) +* [ScalarDB Cluster Common](https://javadoc.io/doc/com.scalar-labs/scalardb-cluster-common/3.14.0/index.html) +* [ScalarDB Cluster RPC](https://javadoc.io/doc/com.scalar-labs/scalardb-cluster-rpc/3.14.0/index.html) diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/encrypt-data-at-rest.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/encrypt-data-at-rest.mdx new file mode 100644 index 00000000..d5b900b7 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/encrypt-data-at-rest.mdx @@ -0,0 +1,316 @@ +--- +tags: + - Enterprise Premium +--- + +# 保存データの暗号化 + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; +import WarningLicenseKeyContact from '/src/components/ja-jp/_warning-license-key-contact.mdx'; + + + +このドキュメントでは、ScalarDB に保存されているデータを暗号化する方法について説明します。 + +## 概要 + +ScalarDB は、それを介して保存されたデータを暗号化できます。暗号化機能は、主要なデータベースシステムの透過的データ暗号化 (TDE) に似ているため、アプリケーションに対して透過的です。ScalarDB は、バックエンドデータベースに書き込む前にデータを暗号化し、そこから読み取るときに復号します。 + +現在、ScalarDB は列レベルの暗号化をサポートしており、テーブル内の特定の列を暗号化できます。 + +## 設定 + +暗号化機能を有効にするには、ScalarDB Cluster ノード設定ファイルで `scalar.db.cluster.encryption.enabled` を `true` に設定する必要があります。 + +| 名前 | 説明 | デフォルト | +|----------------------------------------|-----------------------------------------|---------| +| `scalar.db.cluster.encryption.enabled` | ScalarDB が保存データを暗号化するかどうか。 | `false` | + +:::note + +暗号化はクライアントに対して透過的であるため、クライアントの設定を変更する必要はありません。 + +::: + +:::note + +暗号化機能を有効にする場合は、内部的にパーティション間スキャンを実行するため、システム名前空間 (デフォルトでは `scalardb`) の `scalar.db.cross_partition_scan.enabled` を `true` に設定する必要もあります。 + +::: + +その他の設定は、選択した暗号化実装によって異なります。現在、ScalarDB は次の暗号化実装をサポートしています。 + +- HashiCorp Vault 暗号化 +- 自己暗号化 + +次のセクションでは、各暗号化実装の設定方法について説明します。 + +### HashiCorp Vault 暗号化 + +HashiCorp Vault 暗号化では、ScalarDB は HashiCorp Vault の [encryption as a service](https://developer.hashicorp.com/vault/tutorials/encryption-as-a-service/eaas-transit) を使用してデータを暗号化および復号します。この実装では、ScalarDB は暗号化キーの管理とデータの暗号化および復号を HashiCorp Vault に委任します。 + +HashiCorp Vault 暗号化を使用するには、ScalarDB Cluster ノード設定ファイルでプロパティ `scalar.db.cluster.encryption.type` を `vault` に設定する必要があります。 + +| 名前 | 説明 | デフォルト | +|-------------------------------------|-------------------------------------------------------------|---------| +| `scalar.db.cluster.encryption.type` | HashiCorp Vault 暗号化を使用するには、`vault` に設定する必要があります。 | | + +次のプロパティも設定する必要があります。 + +| 名前 | 説明 | デフォルト | +|------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------| +| `scalar.db.cluster.encryption.vault.key_type` | キーの種類。現在、`aes128-gcm96`、`aes256-gcm96`、`chacha20-poly1305` がサポートされています。キーの種類の詳細については、[Key types](https://developer.hashicorp.com/vault/docs/secrets/transit#key-types) を参照してください。 | `aes128-gcm96` | +| `scalar.db.cluster.encryption.vault.associated_data_required` | AEAD 暗号化に関連データが必要かどうか。 | `false` | +| `scalar.db.cluster.encryption.vault.address` | HashiCorp Vault サーバーのアドレス。 | | +| `scalar.db.cluster.encryption.vault.token` | HashiCorp Vault で認証するためのトークン。 | | +| `scalar.db.cluster.encryption.vault.namespace` | HashiCorp Vault の名前空間。この設定はオプションです。 | | +| `scalar.db.cluster.encryption.vault.transit_secrets_engine_path` | トランジットシークレットエンジンのパス。 | `transit` | +| `scalar.db.cluster.encryption.vault.column_batch_size` | HashiCorp Vault サーバーへの単一のリクエストに含まれる列の数。 | `64` | + +### 自己暗号化 + +自己暗号化では、ScalarDB がデータ暗号化キー (DEK) を管理し、暗号化と復号を実行します。ScalarDB はテーブルの作成時にテーブルごとに DEK を生成し、Kubernetes Secrets に保存します。 + +自己暗号化を使用するには、ScalarDB Cluster ノード設定ファイルでプロパティ `scalar.db.cluster.encryption.type` を `self` に設定する必要があります。 + +| 名前 | 説明 | デフォルト | +|-------------------------------------|-------------------------------------------------|---------| +| `scalar.db.cluster.encryption.type` | 自己暗号化を使用するには `self` に設定する必要があります。 | | + +次のプロパティも設定する必要があります。 + +| 名前 | 説明 | デフォルト | +|-------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------| +| `scalar.db.cluster.encryption.self.key_type` | キーの種類。現在、`AES128_GCM`、`AES256_GCM`、`AES128_EAX`、`AES256_EAX`、`AES128_CTR_HMAC_SHA256`、`AES256_CTR_HMAC_SHA256`、`CHACHA20_POLY1305`、および `XCHACHA20_POLY1305` がサポートされています。キーの種類の詳細については、[キータイプの選択](https://developers.google.com/tink/aead?hl=ja#choose_a_key_type)を参照してください。 | `AES128_GCM` | +| `scalar.db.cluster.encryption.self.associated_data_required` | AEAD 暗号化に関連データが必要かどうか。 | `false` | +| `scalar.db.cluster.encryption.self.kubernetes.secret.namespace_name` | Kubernetes Secrets の名前空間名。 | `default` | +| `scalar.db.cluster.encryption.self.data_encryption_key_cache_expiration_time` | DEK キャッシュの有効期限（ミリ秒単位）。 | `60000` (60 秒) | + +### テーブルを削除するときに DEK を削除する + +デフォルトでは、ScalarDB はテーブルを削除しても、テーブルに関連付けられたデータ暗号化キー (DEK) を削除しません。ただし、テーブルを削除するときに DEK を削除するように ScalarDB を設定できます。これを有効にするには、ScalarDB Cluster ノード設定ファイルでプロパティ `scalar.db.cluster.encryption.delete_data_encryption_key_on_drop_table.enabled` を `true` に設定します。 + +| 名前 | 説明 | デフォルト | +|---------------------------------------------------------------------------------|-------------------------------------------|----------| +| `scalar.db.cluster.encryption.delete_data_encryption_key_on_drop_table.enabled` | テーブルを削除するときに DEK を削除するかどうか。 | `false` | + +## 制限事項 + +暗号化機能にはいくつかの制限事項があります: + +- 主キー列 (パーティションキー列とクラスタリングキー列) は暗号化できません。 +- セカンダリインデックス列は暗号化できません。 +- 暗号化された列は WHERE 句または ORDER BY 句で指定できません。 +- 暗号化された列は、基になるデータベースに BLOB 型として保存されるため、BLOB 型の最大サイズより大きい暗号化された列は保存できません。BLOB 型の最大サイズについては、[ScalarDB と他のデータベース間のデータ型マッピング](../schema-loader.mdx#scalardb-と他のデータベース間のデータ型マッピング)を参照してください。 + +## ワイヤ暗号化 + +暗号化機能を有効にする場合は、データを保護するために本番環境でワイヤ暗号化を有効にすることを強くお勧めします。ワイヤ暗号化の詳細については、[ScalarDB Cluster ワイヤ暗号化](encrypt-wire-communications.mdx)を参照してください。 + +## チュートリアル - HashiCorp Vault 暗号化を設定してデータを暗号化する + +このチュートリアルでは、HashiCorp Vault 暗号化を使用して ScalarDB で保存されたデータを暗号化する方法について説明します。 + + + +### ステップ 1. HashiCorp Vault をインストールします + +HashiCorp の公式ドキュメント [Install Vault](https://developer.hashicorp.com/vault/tutorials/getting-started/getting-started-install) を参照して、HashiCorp Vault をインストールします。 + +### ステップ 2. ScalarDB Cluster 設定ファイルを作成します + +次の設定ファイルを `scalardb-cluster-node.properties` として作成し、`` と `` を ScalarDB ライセンスキーとライセンスチェック証明書の値に置き換えます。ライセンスキーと証明書の詳細については、[製品ライセンスキーの設定方法](../scalar-licensing/README.mdx)を参照してください。 + +```properties +scalar.db.storage=jdbc +scalar.db.contact_points=jdbc:postgresql://postgresql:5432/postgres +scalar.db.username=postgres +scalar.db.password=postgres +scalar.db.cluster.node.standalone_mode.enabled=true +scalar.db.cross_partition_scan.enabled=true +scalar.db.sql.enabled=true + +# Encryption configurations +scalar.db.cluster.encryption.enabled=true +scalar.db.cluster.encryption.type=vault +scalar.db.cluster.encryption.vault.address=http://vault:8200 +scalar.db.cluster.encryption.vault.token=root + +# License key configurations +scalar.db.cluster.node.licensing.license_key= +scalar.db.cluster.node.licensing.license_check_cert_pem= +``` + +### ステップ 3. Docker Compose 設定ファイルを作成する + +次の設定ファイルを `docker-compose.yaml` として作成します。 + +```yaml +services: + vault: + container_name: "vault" + image: "hashicorp/vault:1.17.3" + ports: + - 8200:8200 + environment: + - VAULT_DEV_ROOT_TOKEN_ID=root + - VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200 + cap_add: + - IPC_LOCK + + postgresql: + container_name: "postgresql" + image: "postgres:15" + ports: + - 5432:5432 + environment: + - POSTGRES_PASSWORD=postgres + healthcheck: + test: ["CMD-SHELL", "pg_isready || exit 1"] + interval: 1s + timeout: 10s + retries: 60 + start_period: 30s + + scalardb-cluster-standalone: + container_name: "scalardb-cluser-node" + image: "ghcr.io/scalar-labs/scalardb-cluster-node-byol-premium:3.14.0" + ports: + - 60053:60053 + - 9080:9080 + volumes: + - ./scalardb-cluster-node.properties:/scalardb-cluster/node/scalardb-cluster-node.properties + depends_on: + postgresql: + condition: service_healthy +``` + +### ステップ 4. HashiCorp Vault サーバーを起動します + +次のコマンドを実行して、HashiCorp Vault サーバーを開発モードで起動します。 + +```console +docker compose up vault -d +``` + +HashiCorp Vault サーバーが実行したら、次のコマンドを実行して環境変数を設定します。 + +```console +export VAULT_ADDR="http://127.0.0.1:8200" +export VAULT_TOKEN=root +``` + +### ステップ 5. HashiCorp Vault サーバーでトランジットシークレットエンジンを有効にする + +次のコマンドを実行して、HashiCorp Vault サーバーでトランジットシークレットエンジンを有効にします。 + +```console +vault secrets enable transit +``` + +### ステップ 6. PostgreSQL と ScalarDB Cluster を起動する + +次のコマンドを実行して、PostgreSQL と ScalarDB Cluster をスタンドアロンモードで起動します。 + +```console +docker compose up postgresql scalardb-cluster-standalone -d +``` + +ScalarDB Cluster が完全に起動するまでに数分かかる場合があります。 + +### ステップ 7. ScalarDB Cluster に接続する + +ScalarDB Cluster に接続するために、このチュートリアルでは、ScalarDB Cluster に接続して SQL クエリを実行するツールである SQL CLI を使用します。SQL CLI は、[ScalarDB Releases ページ](https://github.com/scalar-labs/scalardb/releases)からダウンロードできます。 + +`scalardb-cluster-sql-cli.properties` という名前の設定ファイルを作成します。このファイルは、SQL CLI を使用して ScalarDB Cluster に接続するために使用されます。 + +```properties +scalar.db.sql.connection_mode=cluster +scalar.db.sql.cluster_mode.contact_points=indirect:localhost +``` + +次に、次のコマンドを実行して SQL CLI を起動します。 + +```console +java -jar scalardb-cluster-sql-cli-3.14.0-all.jar --config scalardb-cluster-sql-cli.properties +``` + +まず、ScalarDB トランザクション実行に必要な Coordinator テーブルを作成します。 + +```sql +CREATE COORDINATOR TABLES IF NOT EXISTS; +``` + +これで、ScalarDB Cluster で暗号化機能を有効にしたデータベースを使用する準備が整いました。 + +### ステップ 8. テーブルを作成する + +テーブルを作成する前に、名前空間を作成する必要があります。 + +```sql +CREATE NAMESPACE ns; +``` + +次に、テーブルを作成します。 + +```sql +CREATE TABLE ns.tbl ( + id INT PRIMARY KEY, + col1 TEXT ENCRYPTED, + col2 INT ENCRYPTED, + col3 INT); +``` + +`ENCRYPTED` キーワードを使用すると、指定された列のデータが暗号化されます。この例では、`col1` と `col2` のデータが暗号化されます。 + +### ステップ 9. テーブルにデータを挿入する + +テーブルにデータを挿入するには、次の SQL クエリを実行します。 + +```sql +INSERT INTO ns.tbl (id, col1, col2, col3) VALUES (1, 'data1', 123, 456); +``` + +挿入されたデータを確認するには、次の SQL クエリを実行します。 + +```sql +SELECT * FROM ns.tbl; +``` + +```console ++----+-------+------+------+ +| id | col1 | col2 | col3 | ++----+-------+------+------+ +| 1 | data1 | 123 | 456 | ++----+-------+------+------+ +``` + +### ステップ 10. データの暗号化を確認する + +データが暗号化されていることを確認するには、PostgreSQL に直接接続してデータをチェックします。 + +:::warning + +ScalarDB では、バックエンドデータベースからのデータの直接読み取りまたは書き込みはサポートされていません。このような場合、ScalarDB はデータの一貫性を保証できません。このガイドでは、テスト目的でバックエンドデータベースに直接アクセスしますが、実稼働環境ではこれを行うことはできません。 + +::: + +PostgreSQL に接続するには、次のコマンドを実行します。 + +```console +docker exec -it postgresql psql -U postgres +``` + +次に、次の SQL クエリを実行してテーブル内のデータを確認します。 + +```sql +SELECT id, col1, col2, col3 FROM ns.tbl; +``` + +以下のような出力が表示され、`col1` と `col2` のデータが暗号化されていることが確認されます。 + +```console + id | col1 | col2 | col3 +----+--------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+------ + 1 | \x7661756c743a76313a6b6f76455062316a676e6a4a596b643743765539315a49714d625564545a61697152666c7967367837336e66 | \x7661756c743a76313a4b6244543162764678676d44424b526d7037794f5176423569616e615635304c473079664354514b3866513d | 456 +``` diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/encrypt-wire-communications.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/encrypt-wire-communications.mdx new file mode 100644 index 00000000..959b31b5 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/encrypt-wire-communications.mdx @@ -0,0 +1,67 @@ +--- +tags: + - Enterprise Premium +--- + +# ワイヤ通信の暗号化 + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +ScalarDB Cluster は、トランスポート層セキュリティ (TLS) を使用したワイヤ暗号化をサポートしています。このドキュメントでは、ScalarDB Cluster でのワイヤ暗号化の設定について説明します。 + +ワイヤ暗号化機能では、次のものが暗号化されます: + +* ScalarDB Cluster ノードとクライアント間の通信。 +* すべての ScalarDB Cluster ノード間の通信 (クラスターの内部通信)。 + +この機能では、gRPC の TLS サポートが使用されます。詳細については、公式の gRPC [Security Policy](https://github.com/grpc/grpc-java/blob/master/SECURITY.md) を参照してください。 + +:::note + +実稼働環境では、ScalarDB Cluster ノードと基盤となるデータベース間のワイヤ暗号化を有効にすることを強くお勧めします。ScalarDB Cluster ノードと基盤となるデータベース間のワイヤ暗号化を有効にする方法については、基盤となるデータベースの製品ドキュメントを参照してください。 + +::: + +## 設定 + +このセクションでは、ワイヤ暗号化に使用できる設定について説明します。 + +### ScalarDB Cluster ノードの設定 + +ワイヤ暗号化を有効にするには、`scalar.db.cluster.tls.enabled` を `true` に設定する必要があります。 + +| 名前 | 説明 | デフォルト | +|---------------------------------|--------------------------------|-----------| +| `scalar.db.cluster.tls.enabled` | ワイヤ暗号化 (TLS) が有効かどうか。 | `false` | + +次の設定も設定する必要があります。 + +| 名前 | 説明 | デフォルト | +|-----------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------| +| `scalar.db.cluster.tls.ca_root_cert_pem` | TLS 通信用のカスタム CA ルート証明書 (PEM データ)。 | | +| `scalar.db.cluster.tls.ca_root_cert_path` | TLS 通信用のカスタム CA ルート証明書 (ファイルパス)。 | | +| `scalar.db.cluster.tls.override_authority` | TLS 通信のカスタム権限。これは、実際に接続しているホストを変更するものではありません。これはテスト用ですが、DNS オーバーライドの代替としてテスト以外でも安全に使用できます。たとえば、`scalar.db.cluster.node.tls.cert_chain_path` に設定した証明書チェーンファイルで提示 されるホスト名を指定できます。 | | +| `scalar.db.cluster.node.tls.cert_chain_path` | TLS 通信に使用される証明書チェーンファイル。 | | +| `scalar.db.cluster.node.tls.private_key_path` | TLS 通信に使用されるシークレット鍵ファイル。 | | + +証明機関 (CA) ルート証明書を指定するには、`scalar.db.cluster.tls.ca_root_cert_pem` または `scalar.db.cluster.tls.ca_root_cert_path` のいずれかを設定する必要があります。両方を設定すると、`scalar.db.cluster.tls.ca_root_cert_pem` が使用されます。 + +### ScalarDB Cluster Java Client SDK 設定 + +クライアント側でワイヤ暗号化を有効にするには、`scalar.db.cluster.tls.enabled` を `true` に設定する必要があります。 + +| 名前 | 説明 | デフォルト | +|---------------------------------|--------------------------------|-----------| +| `scalar.db.cluster.tls.enabled` | ワイヤ暗号化 (TLS) が有効かどうか。 | `false` | + +次の設定も設定する必要があります。 + +| 名前 | 説明 | デフォルト | +|--------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------| +| `scalar.db.cluster.tls.ca_root_cert_pem` | TLS 通信用のカスタム CA ルート証明書 (PEM データ)。 | | +| `scalar.db.cluster.tls.ca_root_cert_path` | TLS 通信用のカスタム CA ルート証明書 (ファイルパス)。 | | +| `scalar.db.cluster.tls.override_authority` | TLS 通信のカスタム権限。これは、実際に接続しているホストを変更するものではありません。これはテスト用ですが、DNS オーバーライドの代替としてテスト以外でも安全に使用できます。たとえば、`scalar.db.cluster.node.tls.cert_chain_path` に設定した証明書チェーンファイルで提示されるホスト名を指定できます。 | | + +CA ルート証明書を指定するには、`scalar.db.cluster.tls.ca_root_cert_pem` または `scalar.db.cluster.tls.ca_root_cert_path` のいずれかを設定する必要があります。両方を設定すると、`scalar.db.cluster.tls.ca_root_cert_pem` が使用されます。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/getting-started-with-scalardb-cluster-graphql.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/getting-started-with-scalardb-cluster-graphql.mdx new file mode 100644 index 00000000..a71847a5 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/getting-started-with-scalardb-cluster-graphql.mdx @@ -0,0 +1,324 @@ +--- +tags: + - Enterprise Premium +--- + +# ScalarDB Cluster GraphQL をはじめよう + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +ScalarDB Cluster gRPC API の詳細については、以下を参照してください。 + +## 前提条件 + +- 以下のいずれかの Java 開発キット (JDK): + - [Oracle JDK](https://www.oracle.com/java/technologies/downloads/) LTS バージョン (8、11、17、または 21) + - [OpenJDK](https://openjdk.org/install/) LTS バージョン (8、11、17、または 21) +- Kubernetes クラスターで実行されている ScalarDB Cluster + - [ScalarDB Cluster をローカルにデプロイする方法](setup-scalardb-cluster-on-kubernetes-by-using-helm-chart.mdx) の手順に従ってデプロイした Kubernetes クラスターで ScalarDB Cluster が実行されていることを前提としています。 + +## サンプルアプリケーション + +このチュートリアルでは、口座間で資金を移動できる電子マネーアプリケーションを作成するプロセスについて説明します。 + +次の図は、サンプルアプリケーションのシステムアーキテクチャを示しています。 + +``` + +-----------------------------------------------------------------------------------------------------------------------------------------+ + | [Kubernetes クラスター] | + | | + | [ポッド] [ポッド] [ポッド] | + | | + | +-------+ | + | +---> | Envoy | ---+ | + | | +-------+ | | + | | | | + +------------------------+ | +---------+ | +-------+ | +--------------------+ | + | Schema Loader | --+-> | サービス | ---+---> | Envoy | ---+---------> | サービス | ---+ | + | (間接クライアントモード) | | | (Envoy) | | +-------+ | | (ScalarDB Cluster) | | | + +------------------------+ | +---------+ | | +--------------------+ | +------------------------+ | + | | +-------+ | | +---> | ScalarDB Cluster ノード | ---+ | + | +---> | Envoy | ---+ | | +------------------------+ | | + | +-------+ | | | | + | | | +------------------------+ | +------------+ | + | +---+---> | ScalarDB Cluster ノード | ---+---> | PostgreSQL | | + | | | +------------------------+ | +------------+ | + | | | | | + | | | +------------------------+ | | + | | +---> | ScalarDB Cluster ノード | ---+ | + | | +------------------------+ | + +------------+ | +----------------------------+ | | + | ブラウザ | ------+---------------------------------------> | サービス | ---+ | + | (GraphiQL) | | | (ScalarDB Cluster GraphQL) | | + +------------+ | +----------------------------+ | + | | + +-----------------------------------------------------------------------------------------------------------------------------------------+ +``` + +## ステップ 1. `schema.json` を作成する + +以下は簡単なサンプルスキーマです。 + +`schema.json` を作成し、ファイルに次の内容を追加します。 + +```json +{ + "emoney.account": { + "transaction": true, + "partition-key": [ + "id" + ], + "clustering-key": [], + "columns": { + "id": "TEXT", + "balance": "INT" + } + } +} +``` + +## ステップ 2. `database.properties` を作成する + +ScalarDB Cluster の Schema Loader 用に `database.properties` を作成する必要があります。 + +ただし、まず Envoy (`scalardb-cluster-envoy`) のサービスリソースの `EXTERNAL-IP` アドレスを取得する必要があります。 + +`EXTERNAL-IP` アドレスを確認するには、次のコマンドを実行します。 + +```console +kubectl get svc scalardb-cluster-envoy +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +scalardb-cluster-envoy LoadBalancer 10.105.121.51 localhost 60053:30641/TCP 16h +``` + +この場合、`EXTERNAL-IP` アドレスは `localhost` です。 + +次に、`database.properties` を作成し、ファイルに次の内容を追加します。 + +```properties +scalar.db.transaction_manager=cluster +scalar.db.contact_points=indirect:localhost +``` + +ScalarDB Cluster に接続するには、`scalar.db.transaction_manager` プロパティに `cluster` を指定する必要があります。 + +また、このチュートリアルでは `indirect` クライアントモードを使用して Envoy のサービスリソースに接続します。 + +クライアントモードの詳細については、[Java API を使用した ScalarDB Cluster の開発者ガイド](developer-guide-for-scalardb-cluster-with-java-api.mdx) を参照してください。 + +## ステップ 3. スキーマをロードする + +ScalarDB Cluster 経由でスキーマをロードするには、ScalarDB Cluster 専用の Schema Loader (Schema Loader for Cluster) を使用する必要があります。Schema Loader for Cluster の使用方法は、JAR ファイルの名前が異なることを除いて、[Schema Loader for ScalarDB](../schema-loader.mdx) の使用方法と基本的に同じです。Cluster 用の Schema Loader は、[ScalarDB リリース](https://github.com/scalar-labs/scalardb/releases/tag/v3.14.0) からダウンロードできます。JAR ファイルをダウンロードしたら、次のコマンドで Cluster 用の Schema Loader を実行できます。 + +```console +java -jar scalardb-cluster-schema-loader-3.14.0-all.jar --config database.properties -f schema.json --coordinator +``` + +## ステップ 4. GraphiQL から操作を実行する + +ScalarDB Cluster では、`scalar.db.graphql.graphiql` プロパティが `true` に設定されている場合 (`true` がデフォルト値)、GraphiQL IDE が使用可能になります。 + +ScalarDB Cluster GraphQL (`scalardb-cluster-graphql`) のサービスリソースの `EXTERNAL-IP` アドレスを取得するには、次のコマンドを実行します。 + +```console +kubectl get svc scalardb-cluster-graphql +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +scalardb-cluster-graphql LoadBalancer 10.105.74.214 localhost 8080:30514/TCP 16h +``` + +この場合、`EXTERNAL-IP` アドレスは `localhost`、GraphiQL IDE のエンドポイント URL は `http://localhost:8080/graphql` です。 +Web ブラウザでその URL を開くと、GraphiQL 画面が表示されます。 + +最初のレコードを挿入してみましょう。左ペインに次のミューテーションを貼り付け、ウィンドウ上部の三角形の `Execute Query` ボタンを押します。 + +```graphql +mutation PutUser1 { + account_put(put: {key: {id: "user1"}, values: {balance: 1000}}) +} +``` + +ScalarDB GraphQL は常にトランザクションを使用してクエリを実行します。上記のクエリは新しいトランザクションを開始し、ScalarDB Put コマンドを実行し、実行の最後にトランザクションをコミットします。 + +GraphQL サーバーからの次の応答が右側のペインに表示されます。 + +```json +{ + "data": { + "account_put": true + } +} +``` + +`"data"` フィールドには実行結果が含まれます。この応答は、ミューテーションの `account_put` フィールドが成功したことを示しています。ミューテーションの結果タイプは `Boolean!` で、操作が成功したかどうかを示します。 + +次に、挿入したレコードを取得しましょう。左ペインの前のミューテーションの横に次のクエリを貼り付けて、`Execute Query` ボタンをクリックします。上記の `mutation PutUser1` を削除していないため、ボタンの下にプルダウンメニューが表示され、実行する操作を選択できます。 以下に示すように、`GetUser1` を選択します。 + +```graphql +query GetUser1 { + account_get(get: {key: {id: "user1"}}) { + account { + id + balance + } + } +} +``` + +右側のペインに次の結果が表示されます。 + +```json +{ + "data": { + "account_get": { + "account": { + "id": "user1", + "balance": 1000 + } + } + } +} +``` + +### GraphQL API と ScalarDB Java API 間のマッピング + +自動的に生成された GraphQL スキーマは、クエリ、ミューテーション、および入出力のオブジェクトタイプを定義し、ターゲット名前空間内のすべてのテーブルに対して CRUD 操作を実行できるようにします。 + +これらの操作は、[`DistributedTransaction`](https://javadoc.io/doc/com.scalar-labs/scalardb/3.14.0/com/scalar/db/api/DistributedTransaction.html) インターフェースで定義されている ScalarDB API と一致するように設計されています。 + +名前空間に `account` テーブルがあると仮定すると、次のクエリとミューテーションが生成されます。 + +| ScalarDB API | GraphQL ルートタイプ | GraphQL フィールド | +|--------------------------------------------------------|-------------------|------------------------------------------------------------------------------------| +| `get(Get get)` | `Query` | `account_get(get: account_GetInput!): account_GetPayload` | +| `scan(Scan scan)` | `Query` | `account_scan(scan: account_ScanInput!): account_ScanPayload` | +| `put(Put put)` | `Mutation` | `account_put(put: account_PutInput!): Boolean!` | +| `put(java.util.List puts)` | `Mutation` | `account_bulkPut(put: [account_PutInput!]!): Boolean!` | +| `delete(Delete delete)` | `Mutation` | `account_delete(delete: account_DeleteInput!): Boolean!` | +| `delete(java.util.List deletes)` | `Mutation` | `account_bulkDelete(delete: [account_DeleteInput!]!): Boolean!` | +| `mutate(java.util.List mutations)` | `Mutation` | `account_mutate(put: [account_PutInput!]delete: [account_DeleteInput!]): Boolean!` | + +クラスタリングキーのないテーブルでは、`scan` フィールドは生成されないことに注意してください。これが、この電子マネーサンプルアプリケーションで `account_scan` フィールドが使用できない理由です。 + +生成されたすべての GraphQL タイプは、GraphiQL のドキュメントエクスプローラー (左上隅の `< Docs` リンク) で確認できます。 + +## ステップ 5. GraphiQL からの複数のリクエストにまたがるトランザクションを実行する + +複数の GraphQL リクエストにまたがるトランザクションを実行してみましょう。 + +生成されたスキーマには、トランザクションを識別できる `@transaction` ディレクティブが用意されています。このディレクティブは、クエリとミューテーションの両方で使用できます。 + +トランザクションを開始する前に、次のミューテーションを使用して必要なレコードを挿入する必要があります。 + +```graphql +mutation PutUser2 { + account_put(put: {key: {id: "user2"}, values: {balance: 1000}}) +} +``` + +### 操作を実行する前にトランザクションを開始する + +以下を実行して、クエリまたはミューテーションに引数のない `@transaction` ディレクティブを追加すると、実行時に新しいトランザクションが開始されます。 + +```graphql +query GetAccounts @transaction { + user1: account_get(get: {key: {id: "user1"}}) { + account { balance } + } + user2: account_get(get: {key: {id: "user2"}}) { + account { balance } + } +} +``` + +上記のコマンドを実行すると、`extensions` フィールドにトランザクション ID が入った結果が返されます。extensions の `id` 値は、リクエスト内の操作が実行されたトランザクション ID です。この場合、リクエストによって開始されたトランザクションの新しい ID は次のとおりです。 + +```json +{ + "data": { + "user1": { + "account": { + "balance": 1000 + } + }, + "user2": { + "account": { + "balance": 1000 + } + } + }, + "extensions": { + "transaction": { + "id": "c88da8a6-a13f-4857-82fe-45f1ab4150f9" + } + } +} +``` + +### 継続トランザクションで操作を実行する + +開始したトランザクションで次のクエリまたはミューテーションを実行するには、トランザクション ID を `@transaction` の `id` 引数として指定します。次の例では、同じトランザクションで user1 のアカウントから user2 のアカウントに残高を転送することにより、前の例で取得した 2 つのアカウントを更新します。 + +```graphql +mutation Transfer @transaction(id: "c88da8a6-a13f-4857-82fe-45f1ab4150f9") { + user1: account_put(put: {key: {id: "user1"}, values: {balance: 750}}) + user2: account_put(put: {key: {id: "user2"}, values: {balance: 1250}}) +} +``` + +GraphQL で開始されたトランザクションには 1 分のタイムアウト (デフォルト) があり、タイムアウトを超えると自動的にアボートされることに注意してください。 + +### トランザクションをコミットする + +継続中のトランザクションをコミットするには、`@transaction` ディレクティブの引数として `id` と `commit: true` フラグの両方を指定します。 + +```graphql +query GetAndCommit @transaction(id: "c88da8a6-a13f-4857-82fe-45f1ab4150f9", commit: true) { + user1: account_get(get: {key: {id: "user1"}}) { + account { balance } + } + user2: account_get(get: {key: {id: "user2"}}) { + account { balance } + } +} +``` + +**注:** `@transaction(commit: true)` のように `id` 引数なしで `commit: true` フラグを指定すると、新しいトランザクションが開始され、1 つの操作に対してのみコミットされます。この動作は、GraphiQL を使用した上記の例で見られるように、`@transaction` ディレクティブを指定しない場合とまったく同じです。つまり、`@transaction(commit: true)` が指定されている場合は、ディレクティブ自体を省略できます。 + +### トランザクションをアボートまたはロールバックする + +トランザクションを明示的にアボートまたはロールバックする必要がある場合は、`abort` または `rollback` ミューテーションフィールドを互換的に使用できます (どちらも効果と使用方法は同じです)。これらのフィールドを他の操作と混在させることはできないため、次のように `abort` または `rollback` ミューテーションフィールドのみを指定する必要があります。 + +```graphql +mutation AbortTx @transaction(id: "c88da8a6-a13f-4857-82fe-45f1ab4150f9") { + abort +} +``` + +または: + +```graphql +mutation RollbackTx @transaction(id: "c88da8a6-a13f-4857-82fe-45f1ab4150f9") { + rollback +} +``` + +## 参照 + +その他の ScalarDB Cluster チュートリアルについては、以下を参照してください。 + +- [ScalarDB Cluster をはじめよう](getting-started-with-scalardb-cluster.mdx) +- [JDBC 経由の ScalarDB Cluster SQL をはじめよう](getting-started-with-scalardb-cluster-sql-jdbc.mdx) +- [Spring Data JDBC for ScalarDB を使用した ScalarDB Cluster SQL をはじめよう](getting-started-with-scalardb-cluster-sql-spring-data-jdbc.mdx) +- [ScalarDB Cluster での Go をはじめよう](getting-started-with-using-go-for-scalardb-cluster.mdx) +- [ScalarDB Cluster での Python をはじめよう](getting-started-with-using-python-for-scalardb-cluster.mdx) + +Java API で ScalarDB Cluster を使用するアプリケーションの開発の詳細については、以下を参照してください。 + +- [Java API を使用した ScalarDB Cluster の開発者ガイド](developer-guide-for-scalardb-cluster-with-java-api.mdx) + +ScalarDB Cluster gRPC API の詳細については、以下を参照してください。 + +- [ScalarDB Cluster gRPC API ガイド](scalardb-cluster-grpc-api-guide.mdx) +- [ScalarDB Cluster SQL gRPC API ガイド](scalardb-cluster-sql-grpc-api-guide.mdx) diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/getting-started-with-scalardb-cluster-sql-jdbc.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/getting-started-with-scalardb-cluster-sql-jdbc.mdx new file mode 100644 index 00000000..49cd6fd1 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/getting-started-with-scalardb-cluster-sql-jdbc.mdx @@ -0,0 +1,230 @@ +--- +tags: + - Enterprise Premium +--- + +# JDBC 経由の ScalarDB Cluster SQL をはじめよう + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このチュートリアルでは、JDBC 経由で ScalarDB Cluster SQL を使用してサンプルアプリケーションを作成する方法について説明します。 + +## このサンプルアプリケーションの前提条件 + +- [Eclipse Temurin](https://adoptium.net/temurin/releases/) の OpenJDK LTS バージョン (8、11、17、または 21) +- Kubernetes クラスターで実行されている ScalarDB Cluster + - [ScalarDB Cluster をローカルにデプロイする方法](setup-scalardb-cluster-on-kubernetes-by-using-helm-chart.mdx) の手順に従ってデプロイした Kubernetes クラスターで ScalarDB Cluster が実行されていることを前提としています。 + +:::note + +このサンプルアプリケーションは、Eclipse Temurin の OpenJDK でテストされています。ただし、ScalarDB 自体は、さまざまなベンダーの JDK ディストリビューションでテストされています。互換性のある JDK ディストリビューションを含む ScalarDB の要件の詳細については、[要件](../requirements.mdx)を参照してください。 + +::: + +## サンプルアプリケーション + +このチュートリアルでは、ScalarDB JDBC を使用して、クレジットラインでアイテムを注文し、支払いを行うことができるサンプル電子商取引アプリケーションを作成するプロセスについて説明します。 + +次の図は、サンプルアプリケーションのシステムアーキテクチャを示しています。 + +``` + +------------------------------------------------------------------------------------------------------------------------------+ + | [Kubernetes クラスター] | + | | + | [ポッド] [ポッド] [ポッド] | + +------------------------+ | | + | SQL CLI | | +-------+ +-----------------------+ | + | (間接クライアントモード) | --+ | +---> | Envoy | ---+ +---> | ScalarDB Cluster ノード | ---+ | + +------------------------+ | | | +-------+ | | +-----------------------+ | | + | | | | | | | + | | +---------+ | +-------+ | +--------------------+ | +-----------------------+ | +------------+ | + +--+-> | サービス | ---+---> | Envoy | ---+---> | サービス | ---+---> | ScalarDB Cluster ノード | ---+---> | PostgreSQL | | + | | | (Envoy) | | +-------+ | | (ScalarDB Cluster) | | +-----------------------+ | +------------+ | + +-------------------------+ | | +---------+ | | +--------------------+ | | | + | ScalarDB JDBC の | | | | +-------+ | | +-----------------------+ | | + | サンプルアプリケーション | --+ | +---> | Envoy | ---+ +---> | ScalarDB Cluster ノード | ---+ | + | (間接クライアントモード) | | +-------+ +-----------------------+ | + +-------------------------+ | | + +------------------------------------------------------------------------------------------------------------------------------+ +``` + +## ステップ 1. ScalarDB サンプルリポジトリをクローンする + +```console +git clone https://github.com/scalar-labs/scalardb-samples.git +cd scalardb-samples/scalardb-sql-jdbc-sample +``` + +## ステップ 2. `scalardb-sql.properties` を変更する + +ScalarDB Cluster に接続するには、`scalardb-sql.properties` も変更する必要があります。ただし、その前に、次のように Envoy (`scalardb-cluster-envoy`) のサービスリソースの `EXTERNAL-IP` アドレスを取得する必要があります。 + +```console +kubectl get svc scalardb-cluster-envoy +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +scalardb-cluster-envoy LoadBalancer 10.105.121.51 localhost 60053:30641/TCP 16h +``` + +この場合、`EXTERNAL-IP` アドレスは `localhost` です。 + +次に、`scalardb-sql.properties` を開きます。 + +```console +vim scalardb-sql.properties +``` + +次に、`scalardb-sql.properties` を次のように変更します。 + +```properties +scalar.db.sql.connection_mode=cluster +scalar.db.sql.cluster_mode.contact_points=indirect:localhost +``` + +ScalarDB Cluster に接続するには、`scalar.db.sql.connection_mode` プロパティに `cluster` を指定する必要があります。また、このチュートリアルでは `indirect` クライアントモードを使用して Envoy のサービスリソースに接続します。クライアントモードの詳細については、[Java API を使用した ScalarDB Cluster の開発者ガイド](developer-guide-for-scalardb-cluster-with-java-api.mdx) を参照してください。 + +## ステップ 3. スキーマをロードする + +スキーマをロードするには、[SQL CLI](developer-guide-for-scalardb-cluster-with-java-api.mdx#sql-cli) を使用する必要があります。SQL CLI は [ScalarDB リリース](https://github.com/scalar-labs/scalardb/releases/tag/v3.14.0) からダウンロードできます。JAR ファイルをダウンロードしたら、次のコマンドを実行して Cluster 用の SQL CLI を使用できます。 + +```console +java -jar scalardb-cluster-sql-cli-3.14.0-all.jar --config scalardb-sql.properties --file schema.sql +``` + +## ステップ 4. 初期データをロードする + +サンプルアプリケーションを実行する前に、次のコマンドを実行して初期データをロードする必要があります。 + +```console +./gradlew run --args="LoadInitialData" +``` + +初期データがロードされた後、次のレコードがテーブルに保存されます: + +- `sample.customers` テーブルの場合: + +| customer_id | name | credit_limit | credit_total | +|-------------|---------------|--------------|--------------| +| 1 | Yamada Taro | 10000 | 0 | +| 2 | Yamada Hanako | 10000 | 0 | +| 3 | Suzuki Ichiro | 10000 | 0 | + +- `sample.items` テーブルの場合: + +| item_id | name | price | +|---------|--------|-------| +| 1 | Apple | 1000 | +| 2 | Orange | 2000 | +| 3 | Grape | 2500 | +| 4 | Mango | 5000 | +| 5 | Melon | 3000 | + +## ステップ 5. サンプルアプリケーションを実行する + +まず、ID が `1` である顧客に関する情報を取得します。 + +```console +./gradlew run --args="GetCustomerInfo 1" +... +{"id": 1, "name": "Yamada Taro", "credit_limit": 10000, "credit_total": 0} +... +``` + +次に、顧客 ID `1` を使用して、リンゴ 3 個とオレンジ 2 個を注文します。注文形式は `:,:,...` であることに注意してください。 + +```console +./gradlew run --args="PlaceOrder 1 1:3,2:2" +... +{"order_id": "454f9c97-f456-44fd-96da-f527187fe39b"} +... +``` + +このコマンドを実行すると、注文 ID が表示されます。 + +注文 ID を使用して注文の詳細を確認してみましょう。 + +```console +./gradlew run --args="GetOrder 454f9c97-f456-44fd-96da-f527187fe39b" +... +{"order": {"order_id": "454f9c97-f456-44fd-96da-f527187fe39b","timestamp": 1685602722821,"customer_id": 1,"customer_name": "Yamada Taro","statement": [{"item_id": 1, "name": "Apple", "price": 1000, "count": 3},{"item_id": 2, "name": "Orange", "price": 2000, "count": 2}],"total": 7000}} +... +``` + +次に、別の注文を出して、顧客 ID `1` の注文履歴を取得しましょう。 + +```console +./gradlew run --args="PlaceOrder 1 5:1" +... +{"order_id": "3f40c718-59ec-48aa-a6fe-2fdaf12ad094"} +... +./gradlew run --args="GetOrders 1" +... +{"order": [{"order_id": "454f9c97-f456-44fd-96da-f527187fe39b","timestamp": 1685602722821,"customer_id": 1,"customer_name": "Yamada Taro","statement": [{"item_id": 1, "name": "Apple", "price": 1000, "count": 3},{"item_id": 2, "name": "Orange", "price": 2000, "count": 2}],"total": 7000},{"order_id": "3f40c718-59ec-48aa-a6fe-2fdaf12ad094","timestamp": 1685602811718,"customer_id": 1,"customer_name": "Yamada Taro","statement": [{"item_id": 5, "name": "Melon", "price": 3000, "count": 1}],"total": 3000}]} +... +``` + +この注文履歴は、タイムスタンプの降順で表示されます。 + +顧客の現在の `credit_total` は `10000` です。顧客は、情報を取得したときに表示された `credit_limit` に達したため、これ以上注文することはできません。 + +```console +./gradlew run --args="GetCustomerInfo 1" +... +{"id": 1, "name": "Yamada Taro", "credit_limit": 10000, "credit_total": 10000} +... +./gradlew run --args="PlaceOrder 1 3:1,4:1" +... +java.lang.RuntimeException: Credit limit exceeded + at sample.Sample.placeOrder(Sample.java:184) + at sample.command.PlaceOrderCommand.call(PlaceOrderCommand.java:32) + at sample.command.PlaceOrderCommand.call(PlaceOrderCommand.java:8) + at picocli.CommandLine.executeUserObject(CommandLine.java:2041) + at picocli.CommandLine.access$1500(CommandLine.java:148) + at picocli.CommandLine$RunLast.executeUserObjectOfLastSubcommandWithSameParent(CommandLine.java:2461) + at picocli.CommandLine$RunLast.handle(CommandLine.java:2453) + at picocli.CommandLine$RunLast.handle(CommandLine.java:2415) + at picocli.CommandLine$AbstractParseResultHandler.execute(CommandLine.java:2273) + at picocli.CommandLine$RunLast.execute(CommandLine.java:2417) + at picocli.CommandLine.execute(CommandLine.java:2170) + at sample.command.SampleCommand.main(SampleCommand.java:35) +... +``` + +支払いが完了すると、顧客は再度注文できるようになります。 + +```console +./gradlew run --args="Repayment 1 8000" +... +./gradlew run --args="GetCustomerInfo 1" +... +{"id": 1, "name": "Yamada Taro", "credit_limit": 10000, "credit_total": 2000} +... +./gradlew run --args="PlaceOrder 1 3:1,4:1" +... +{"order_id": "fb71279d-88ea-4974-a102-0ec4e7d65e25"} +... +``` + +## サンプルアプリケーションのソースコード + +ScalarDB Cluster SQL JDBC の詳細については、[サンプルアプリケーションのソースコード](https://github.com/scalar-labs/scalardb-samples/tree/main/scalardb-sql-jdbc-sample/src/main/java/sample) を参照してください。 + +## 参照 + +その他の ScalarDB Cluster チュートリアルについては、以下を参照してください。 + +- [ScalarDB Cluster をはじめよう](getting-started-with-scalardb-cluster.mdx) +- [ScalarDB Cluster GraphQL をはじめよう](getting-started-with-scalardb-cluster-graphql.mdx) +- [Spring Data JDBC for ScalarDB を使用した ScalarDB Cluster SQL をはじめよう](getting-started-with-scalardb-cluster-sql-spring-data-jdbc.mdx) +- [ScalarDB Cluster での Go をはじめよう](getting-started-with-using-go-for-scalardb-cluster.mdx) +- [ScalarDB Cluster での Python をはじめよう](getting-started-with-using-python-for-scalardb-cluster.mdx) + +Java API で ScalarDB Cluster を使用するアプリケーションの開発の詳細については、以下を参照してください。 + +- [Java API を使用した ScalarDB Cluster の開発者ガイド](developer-guide-for-scalardb-cluster-with-java-api.mdx) + +ScalarDB Cluster gRPC API の詳細については、以下を参照してください。 + +- [ScalarDB Cluster gRPC API ガイド](scalardb-cluster-grpc-api-guide.mdx) +- [ScalarDB Cluster SQL gRPC API ガイド](scalardb-cluster-sql-grpc-api-guide.mdx) diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/getting-started-with-scalardb-cluster-sql-spring-data-jdbc.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/getting-started-with-scalardb-cluster-sql-spring-data-jdbc.mdx new file mode 100644 index 00000000..22b7d6ac --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/getting-started-with-scalardb-cluster-sql-spring-data-jdbc.mdx @@ -0,0 +1,271 @@ +--- +tags: + - Enterprise Premium +--- + +# Spring Data JDBC for ScalarDB を使用した ScalarDB Cluster SQL をはじめよう + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このチュートリアルでは、Spring Data JDBC for ScalarDB を介して ScalarDB Cluster SQL を使用してサンプルアプリケーションを作成する方法について説明します。 + +## このサンプルアプリケーションの前提条件 + +- [Eclipse Temurin](https://adoptium.net/temurin/releases/) の OpenJDK LTS バージョン (8、11、17、または 21) +- Kubernetes クラスターで実行されている ScalarDB Cluster + - [ScalarDB Cluster をローカルにデプロイする方法](setup-scalardb-cluster-on-kubernetes-by-using-helm-chart.mdx) の手順に従ってデプロイした Kubernetes クラスターで ScalarDB Cluster が実行されていることを前提としています。 + +:::note + +このサンプルアプリケーションは、Eclipse Temurin の OpenJDK でテストされています。ただし、ScalarDB 自体は、さまざまなベンダーの JDK ディストリビューションでテストされています。互換性のある JDK ディストリビューションを含む ScalarDB の要件の詳細については、[要件](../requirements.mdx)を参照してください。 + +::: + +## サンプルアプリケーション + +このチュートリアルでは、Spring Data JDBC for ScalarDB を使用して、クレジットラインでアイテムを注文して支払うことができるサンプル電子商取引アプリケーションを作成するプロセスについて説明します。 + +次の図は、サンプルアプリケーションのシステムアーキテクチャを示しています。 + +``` + +------------------------------------------------------------------------------------------------------------------------------+ + | [Kubernetes クラスター] | + | | + | [ポッド] [ポッド] [ポッド] | + +------------------------+ | | + | SQL CLI | | +-------+ +------------------------+ | + | (間接クライアントモード) | --+ | +---> | Envoy | ---+ +---> | ScalarDB Cluster ノード | ---+ | + +------------------------+ | | | +-------+ | | +------------------------+ | | + | | | | | | | + | | +---------+ | +-------+ | +--------------------+ | +-----------------------+ | +------------+ | + +--+-> | サービス | ---+---> | Envoy | ---+---> | サービス | ---+---> | ScalarDB Cluster ノード | ---+---> | PostgreSQL | | + +------------------------+ | | | (Envoy) | | +-------+ | | (ScalarDB Cluster) | | +-----------------------+ | +------------+ | + | Spring Data JDBC for | | | +---------+ | | +--------------------+ | | | + | ScalarDB の | | | | +-------+ | | +------------------------+ | | + | サンプルアプリケーション | --+ | +---> | Envoy | ---+ +---> | ScalarDB Cluster ノード | ---+ | + | (間接クライアントモード) | | +-------+ +-----------------------+ | + +------------------------+ | | + +------------------------------------------------------------------------------------------------------------------------------+ +``` + +## ステップ 1. ScalarDB サンプルリポジトリをクローンする + +```console +git clone https://github.com/scalar-labs/scalardb-samples.git +cd scalardb-samples/spring-data-sample +``` + +## ステップ 2. `scalardb-sql.properties` を変更する + +ScalarDB Cluster に接続するには、`scalardb-sql.properties` も変更する必要があります。ただし、その前に、次のように Envoy (`scalardb-cluster-envoy`) のサービスリソースの `EXTERNAL-IP` アドレスを取得する必要があります。 + +```console +kubectl get svc scalardb-cluster-envoy +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +scalardb-cluster-envoy LoadBalancer 10.105.121.51 localhost 60053:30641/TCP 16h +``` + +この場合、`EXTERNAL-IP` アドレスは `localhost` です。 + +次に、`scalardb-sql.properties` を開きます。 + +```console +vim scalardb-sql.properties +``` + +次に、`scalardb-sql.properties` を次のように変更します。 + +```properties +scalar.db.sql.connection_mode=cluster +scalar.db.sql.cluster_mode.contact_points=indirect:localhost +``` + +ScalarDB Cluster に接続するには、`scalar.db.sql.connection_mode` プロパティに `cluster` を指定する必要があります。 + +また、このチュートリアルでは `indirect` クライアントモードを使用して Envoy のサービスリソースに接続します。 + +クライアントモードの詳細については、[Java API を使用した ScalarDB Cluster の開発者ガイド](developer-guide-for-scalardb-cluster-with-java-api.mdx)を参照してください。 + +## ステップ 3. スキーマをロードする + +スキーマをロードするには、[SQL CLI](developer-guide-for-scalardb-cluster-with-java-api.mdx#sql-cli) を使用する必要があります。SQL CLI は [ScalarDB リリース](https://github.com/scalar-labs/scalardb/releases/tag/v3.14.0)からダウンロードできます。JAR ファイルをダウンロードしたら、次のコマンドを実行して Cluster 用の SQL CLI を使用できます。 + +```console +java -jar scalardb-cluster-sql-cli-3.14.0-all.jar --config scalardb-sql.properties --file schema.sql +``` + +## ステップ 4.`application.properties`を変更する + +次に、ScalarDB Cluster に接続するために `application.properties` も変更する必要があります。 + +```console +vim src/main/resources/application.properties +``` + +`scalardb-sql.properties` と同様に、`scalar.db.sql.connection_mode` プロパティに `cluster` を指定し、`indirect` クライアントモードを使用する必要があります。そのためには、`application.properties` を次のように変更します。 + +```properties +spring.datasource.driver-class-name=com.scalar.db.sql.jdbc.SqlJdbcDriver +spring.datasource.url=jdbc:scalardb:\ +?scalar.db.sql.connection_mode=cluster\ +&scalar.db.sql.cluster_mode.contact_points=indirect:localhost\ +&scalar.db.consensus_commit.isolation_level=SERIALIZABLE\ +&scalar.db.sql.default_namespace_name=sample +``` + +## ステップ 5. 初期データをロードする + +サンプルアプリケーションを実行する前に、次のコマンドを実行して初期データをロードする必要があります。 + +```console +./gradlew run --args="LoadInitialData" +``` + +初期データがロードされた後、次のレコードがテーブルに保存される必要があります。 + +- `sample.customers` テーブルの場合: + +| customer_id | name | credit_limit | credit_total | +|-------------|---------------|--------------|--------------| +| 1 | Yamada Taro | 10000 | 0 | +| 2 | Yamada Hanako | 10000 | 0 | +| 3 | Suzuki Ichiro | 10000 | 0 | + +- `sample.items` テーブルの場合: + +| item_id | name | price | +|---------|--------|-------| +| 1 | Apple | 1000 | +| 2 | Orange | 2000 | +| 3 | Grape | 2500 | +| 4 | Mango | 5000 | +| 5 | Melon | 3000 | + +## ステップ 6. サンプルアプリケーションを実行する + +まず、ID が `1` である顧客に関する情報を取得します。 + +```console +./gradlew run --args="GetCustomerInfo 1" +... +{"customer_id":1,"name":"Yamada Taro","credit_limit":10000,"credit_total":0} +... +``` + +次に、顧客 ID `1` を使用して、リンゴ 3 個とオレンジ 2 個を注文します。注文形式は `:,:,...` であることに注意してください。 + +```console +./gradlew run --args="PlaceOrder 1 1:3,2:2" +... +{"order_id":"2358ab35-5819-4f8f-acb1-12e73d97d34e","customer_id":1,"timestamp":1677478005400} +... +``` + +このコマンドを実行すると、注文 ID が表示されます。 + +注文 ID を使用して注文の詳細を確認してみましょう。 + +```console +./gradlew run --args="GetOrder 2358ab35-5819-4f8f-acb1-12e73d97d34e" +... +{"order_id":"2358ab35-5819-4f8f-acb1-12e73d97d34e","timestamp":1677478005400,"customer_id":1,"customer_name":"Yamada Taro","statements":[{"item_id":1,"item_name":"Apple","price":1000,"count":3,"total":3000},{"item_id":2,"item_name":"Orange","price":2000,"count":2,"total":4000}],"total":7000} +... +``` + +次に、別の注文を出して、顧客 ID `1` の注文履歴を取得しましょう。 + +```console +./gradlew run --args="PlaceOrder 1 5:1" +... +{"order_id":"46062b16-b71b-46f9-a9ff-dc6b0991259b","customer_id":1,"timestamp":1677478201428} +... +./gradlew run --args="GetOrders 1" +... +[{"order_id":"46062b16-b71b-46f9-a9ff-dc6b0991259b","timestamp":1677478201428,"customer_id":1,"customer_name":"Yamada Taro","statements":[{"item_id":5,"item_name":"Melon","price":3000,"count":1,"total":3000}],"total":3000},{"order_id":"2358ab35-5819-4f8f-acb1-12e73d97d34e","timestamp":1677478005400,"customer_id":1,"customer_name":"Yamada Taro","statements":[{"item_id":1,"item_name":"Apple","price":1000,"count":3,"total":3000},{"item_id":2,"item_name":"Orange","price":2000,"count":2,"total":4000}],"total":7000}] +... +``` + +この注文履歴は、タイムスタンプの降順で表示されます。 + +顧客の現在の `credit_total` は `10000` です。顧客は、情報を取得したときに表示された `credit_limit` に達したため、これ以上注文することはできません。 + +```console +./gradlew run --args="GetCustomerInfo 1" +... +{"id": 1, "name": "Yamada Taro", "credit_limit": 10000, "credit_total": 10000} +... +./gradlew run --args="PlaceOrder 1 3:1,4:1" +... +java.lang.RuntimeException: Credit limit exceeded. limit:10000, total:17500 + at sample.SampleService.placeOrder(SampleService.java:102) + at sample.SampleService$$FastClassBySpringCGLIB$$1123c447.invoke() + at org.springframework.cglib.proxy.MethodProxy.invoke(MethodProxy.java:218) + at org.springframework.aop.framework.CglibAopProxy$CglibMethodInvocation.invokeJoinpoint(CglibAopProxy.java:793) + at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(ReflectiveMethodInvocation.java:163) + at org.springframework.aop.framework.CglibAopProxy$CglibMethodInvocation.proceed(CglibAopProxy.java:763) + at org.springframework.transaction.interceptor.TransactionInterceptor$1.proceedWithInvocation(TransactionInterceptor.java:123) + at org.springframework.transaction.interceptor.TransactionAspectSupport.invokeWithinTransaction(TransactionAspectSupport.java:388) + at org.springframework.transaction.interceptor.TransactionInterceptor.invoke(TransactionInterceptor.java:119) + at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(ReflectiveMethodInvocation.java:186) + at org.springframework.aop.framework.CglibAopProxy$CglibMethodInvocation.proceed(CglibAopProxy.java:763) + at org.springframework.aop.framework.CglibAopProxy$DynamicAdvisedInterceptor.intercept(CglibAopProxy.java:708) + at sample.SampleService$$EnhancerBySpringCGLIB$$a94e1d9.placeOrder() + at sample.command.PlaceOrderCommand.call(PlaceOrderCommand.java:37) + at sample.command.PlaceOrderCommand.call(PlaceOrderCommand.java:13) + at picocli.CommandLine.executeUserObject(CommandLine.java:2041) + at picocli.CommandLine.access$1500(CommandLine.java:148) + at picocli.CommandLine$RunLast.executeUserObjectOfLastSubcommandWithSameParent(CommandLine.java:2461) + at picocli.CommandLine$RunLast.handle(CommandLine.java:2453) + at picocli.CommandLine$RunLast.handle(CommandLine.java:2415) + at picocli.CommandLine$AbstractParseResultHandler.execute(CommandLine.java:2273) + at picocli.CommandLine$RunLast.execute(CommandLine.java:2417) + at picocli.CommandLine.execute(CommandLine.java:2170) + at sample.SampleApp.run(SampleApp.java:26) + at org.springframework.boot.SpringApplication.callRunner(SpringApplication.java:768) + at org.springframework.boot.SpringApplication.callRunners(SpringApplication.java:752) + at org.springframework.boot.SpringApplication.run(SpringApplication.java:314) + at org.springframework.boot.SpringApplication.run(SpringApplication.java:1303) + at org.springframework.boot.SpringApplication.run(SpringApplication.java:1292) + at sample.SampleApp.main(SampleApp.java:35) +... +``` + +支払いが完了すると、顧客は再度注文できるようになります。 + +```console +./gradlew run --args="Repayment 1 8000" +... +./gradlew run --args="GetCustomerInfo 1" +... +{"customer_id":1,"name":"Yamada Taro","credit_limit":10000,"credit_total":2000} +... +./gradlew run --args="PlaceOrder 1 3:1,4:1" +... +{"order_id":"0350947a-9003-46f2-870e-6aa4b2df0f1f","customer_id":1,"timestamp":1677478728134} +... +``` + +## サンプルアプリケーションのソースコード + +Spring Data JDBC for ScalarDB の詳細については、[サンプルアプリケーションのソースコード](https://github.com/scalar-labs/scalardb-samples/tree/main/spring-data-sample/src/main)を確認してください。 + +## 参照 + +その他の ScalarDB Cluster チュートリアルについては、以下を参照してください。 + +- [ScalarDB Cluster をはじめよう](getting-started-with-scalardb-cluster.mdx) +- [ScalarDB Cluster GraphQL をはじめよう](getting-started-with-scalardb-cluster-graphql.mdx) +- [JDBC 経由の ScalarDB Cluster SQL をはじめよう](getting-started-with-scalardb-cluster-sql-jdbc.mdx) +- [ScalarDB Cluster での Go をはじめよう](getting-started-with-using-go-for-scalardb-cluster.mdx) +- [ScalarDB Cluster での Python をはじめよう](getting-started-with-using-python-for-scalardb-cluster.mdx) + +Java API で ScalarDB Cluster を使用するアプリケーションの開発の詳細については、以下を参照してください。 + +- [Java API を使用した ScalarDB Cluster の開発者ガイド](developer-guide-for-scalardb-cluster-with-java-api.mdx) + +ScalarDB Cluster gRPC API の詳細については、以下を参照してください。 + +- [ScalarDB Cluster gRPC API ガイド](scalardb-cluster-grpc-api-guide.mdx) +- [ScalarDB Cluster SQL gRPC API ガイド](scalardb-cluster-sql-grpc-api-guide.mdx) diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/getting-started-with-scalardb-cluster.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/getting-started-with-scalardb-cluster.mdx new file mode 100644 index 00000000..9571994b --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/getting-started-with-scalardb-cluster.mdx @@ -0,0 +1,408 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster をはじめよう + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このチュートリアルでは、Java API を通じて [ScalarDB Cluster](index.mdx) を使用するサンプルアプリケーションを作成する方法について説明します。 + +## 概要 + +このチュートリアルでは、ScalarDB を使用して商品を注文し、信用枠で支払いを行うことができるサンプルの電子商取引アプリケーションを作成するプロセスについて説明します。 + +:::note + +サンプルアプリケーションの焦点は ScalarDB の使用方法を示すことにあるため、アプリケーション固有のエラー処理、認証処理、および同様の機能はサンプルアプリケーションには含まれていません。ScalarDB での例外処理の詳細については、[例外の処理](../api-guide.mdx#例外の処理)を参照してください。 + +::: + +次の図は、サンプルアプリケーションのシステムアーキテクチャを示しています。 + +```mermaid +stateDiagram-v2 + state "Schema Loader
(間接クライアントモード)" as SL + state "Java API を使用したサンプルアプリケーション
(間接クライアントモード)" as SA + state "Kubernetes クラスタ" as KC + state "サービス (Envoy)" as SE + state "ポッド" as P1 + state "ポッド" as P2 + state "ポッド" as P3 + state "Envoy" as E1 + state "Envoy" as E2 + state "Envoy" as E3 + state "サービス (ScalarDB Cluster)" as SSC + state "ScalarDB Cluster" as SC1 + state "ScalarDB Cluster" as SC2 + state "ScalarDB Cluster" as SC3 + state "PostgreSQL" as PSQL + SL --> SE + SA --> SE + state KC { + SE --> E1 + SE --> E2 + SE --> E3 + state P1 { + E1 --> SSC + E2 --> SSC + E3 --> SSC + } + SSC --> SC1 + SSC --> SC2 + SSC --> SC3 + state P2 { + SC1 --> PSQL + SC1 --> SC2 + SC1 --> SC3 + SC2 --> PSQL + SC2 --> SC1 + SC2 --> SC3 + SC3 --> PSQL + SC3 --> SC1 + SC3 --> SC2 + } + state P3 { + PSQL + } + } +``` + +### このサンプルアプリケーションで実行できること + +サンプルアプリケーションは、次の種類のトランザクションをサポートしています: + +- 顧客情報を取得します。 +- 信用枠を使用して注文を行います。 + - 注文のコストが顧客の信用限度額を下回っているかどうかを確認します。 + - チェックが成功した場合は、注文履歴を記録し、顧客が支払った金額を更新します。 +- 注文 ID で注文情報を取得します。 +- 顧客 ID で注文情報を取得します。 +- 支払いを行います。 + - 顧客が支払った金額を減らします。 + +## このサンプルアプリケーションの前提条件 + +- [Eclipse Temurin](https://adoptium.net/temurin/releases/) の OpenJDK LTS バージョン (8、11、17、または 21) +- Kubernetes クラスターで実行されている ScalarDB Cluster + - [ScalarDB Cluster をローカルにデプロイする方法](setup-scalardb-cluster-on-kubernetes-by-using-helm-chart.mdx) の手順に従ってデプロイした Kubernetes クラスターで ScalarDB Cluster が実行されていることを前提としています。 + +:::note + +このサンプルアプリケーションは、Eclipse Temurin の OpenJDK でテストされています。ただし、ScalarDB 自体は、さまざまなベンダーの JDK ディストリビューションでテストされています。互換性のある JDK ディストリビューションを含む ScalarDB の要件の詳細については、[要件](../requirements.mdx)を参照してください。 + +::: + +## ScalarDB Cluster のセットアップ + +次のセクションでは、サンプルの電子商取引アプリケーションをセットアップする方法について説明します。 + +### ScalarDB サンプルリポジトリのクローンを作成する + +**ターミナル** を開き、次のコマンドを実行して ScalarDB サンプルリポジトリのクローンを作成します。 + +```console +git clone https://github.com/scalar-labs/scalardb-samples +``` + +次に、次のコマンドを実行して、サンプルアプリケーションが含まれているディレクトリに移動します。 + +```console +cd scalardb-samples/scalardb-sample +``` + +### `build.gradle` を変更する + +ScalarDB Cluster を使用するには、任意のテキストエディターで `build.gradle` を開きます。次に、`dependencies` セクションから `com.scalar-labs:scalardb` の既存の依存関係を削除し、`dependencies` セクションに次の依存関係を追加します。 + +```gradle +dependencies { + ... + + implementation 'com.scalar-labs:scalardb-cluster-java-client-sdk:3.14.0' +} +``` + +### `database.properties` を変更する + +ScalarDB Cluster に接続するには、`database.properties` も変更する必要があります。ただし、その前に、Envoy サービスリソース (`scalardb-cluster-envoy`) の `EXTERNAL-IP` アドレスを取得する必要があります。サービスリソースを取得するには、次のコマンドを実行します。 + +```console +kubectl get svc scalardb-cluster-envoy +``` + +`CLUSTER-IP`、`PORT(S)`、`AGE` の値がそれぞれ異なる、以下のような出力が表示されます。 + +```console +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +scalardb-cluster-envoy LoadBalancer 10.105.121.51 localhost 60053:30641/TCP 16h +``` + +この場合、`EXTERNAL-IP` アドレスは `localhost` です。 + +`database.properties` では、`scalar.db.transaction_manager` プロパティに `cluster` を指定し、`scalar.db.contact_points` が Envoy サービスリソースに接続するためのクライアントモードとして `indirect` を使用する必要があります。 + +次のコマンドを実行して `database.properties` を開きます。 + +```console +vim database.properties +``` + +次に、`database.properties` を次のように変更します。 + +```properties +scalar.db.transaction_manager=cluster +scalar.db.contact_points=indirect:localhost +``` + +:::note + +クライアントモードの詳細については、[Java API を使用した ScalarDB Cluster の開発者ガイド](developer-guide-for-scalardb-cluster-with-java-api.mdx). + +::: + +### スキーマをロードする + +サンプルアプリケーションのデータベーススキーマ (データを整理する方法) は、[`schema.json`](https://github.com/scalar-labs/scalardb-samples/tree/main/scalardb-sample/schema.json) ですでに定義されています。 + +スキーマを適用するには、[ScalarDB リリース](https://github.com/scalar-labs/scalardb/releases/tag/v3.14.0)に移動し、ScalarDB Cluster Schema Loader を `scalardb-samples/scalardb-sample` フォルダーにダウンロードします。 + +次に、次のコマンドを実行します。 + +```console +java -jar scalardb-cluster-schema-loader-3.14.0-all.jar --config database.properties -f schema.json --coordinator +``` + +#### スキーマの詳細 + +サンプルアプリケーションの [`schema.json`](https://github.com/scalar-labs/scalardb-samples/tree/main/scalardb-sample/schema.json) に示されているように、すべてのテーブルは `sample` 名前空間に作成されます。 + +- `sample.customers`: 顧客情報を管理するテーブル + - `credit_limit`: 貸し手が顧客に信用枠から支出を許可する最大金額 + - `credit_total`: 顧客が信用枠から支出した金額 +- `sample.orders`: 注文情報を管理するテーブル +- `sample.statements`: 注文明細情報を管理するテーブル +- `sample.items`: 注文するアイテムの情報を管理するテーブル + +スキーマのエンティティ関係図は次のとおりです。 + +![ERD](images/getting-started-ERD.png) + +### 初期データをロードする + +サンプルアプリケーションを実行する前に、次のコマンドを実行して初期データをロードする必要があります。 + +```console +./gradlew run --args="LoadInitialData" +``` + +初期データがロードされたら、次のレコードがテーブルに保存されます。 + +**`sample.customers` テーブル** + +| customer_id | name | credit_limit | credit_total | +|-------------|---------------|--------------|--------------| +| 1 | Yamada Taro | 10000 | 0 | +| 2 | Yamada Hanako | 10000 | 0 | +| 3 | Suzuki Ichiro | 10000 | 0 | + +**`sample.items` テーブル** + +| item_id | name | price | +|---------|--------|-------| +| 1 | Apple | 1000 | +| 2 | Orange | 2000 | +| 3 | Grape | 2500 | +| 4 | Mango | 5000 | +| 5 | Melon | 3000 | + +## サンプルアプリケーションでトランザクションを実行し、データを取得する + +次のセクションでは、サンプル電子商取引アプリケーションでトランザクションを実行し、データを取得する方法について説明します。 + +### 顧客情報を取得する + +次のコマンドを実行して、ID が `1` である顧客に関する情報を取得することから始めます。 + +```console +./gradlew run --args="GetCustomerInfo 1" +``` + +次の出力が表示されます。 + +```console +... +{"id": 1, "name": "Yamada Taro", "credit_limit": 10000, "credit_total": 0} +... +``` + +### 注文する + +次に、次のコマンドを実行して、顧客 ID `1` にリンゴ 3 個とオレンジ 2 個を注文してもらいます。 + +:::note + +このコマンドの注文形式は `./gradlew run --args="PlaceOrder :,:,..."` です。 + +::: + +```console +./gradlew run --args="PlaceOrder 1 1:3,2:2" +``` + +以下のように、`order_id` の UUID が異なる、注文が成功したことを示す類似の出力が表示されます。 + +```console +... +{"order_id": "dea4964a-ff50-4ecf-9201-027981a1566e"} +... +``` + +### 注文の詳細を確認する + +次のコマンドを実行して注文の詳細を確認します。`` は、前のコマンドを実行した後に表示される `order_id` の UUID に置き換えます。 + +```console +./gradlew run --args="GetOrder " +``` + +`order_id` と `timestamp` の UUID が異なる、以下のような出力が表示されます。 + +```console +... +{"order": {"order_id": "dea4964a-ff50-4ecf-9201-027981a1566e","timestamp": 1650948340914,"customer_id": 1,"customer_name": "Yamada Taro","statement": [{"item_id": 1,"item_name": "Apple","price": 1000,"count": 3,"total": 3000},{"item_id": 2,"item_name": "Orange","price": 2000,"count": 2,"total": 4000}],"total": 7000}} +... +``` + +### 別の注文をする + +次のコマンドを実行して、顧客 ID `1` の `credit_total` の残額を使用してメロン 1 個を注文します。 + +```console +./gradlew run --args="PlaceOrder 1 5:1" +``` + +以下のように、`order_id` の UUID が異なる、注文が成功したことを示す類似の出力が表示されます。 + +```console +... +{"order_id": "bcc34150-91fa-4bea-83db-d2dbe6f0f30d"} +... +``` + +### 注文履歴を確認する + +次のコマンドを実行して、顧客 ID `1` のすべての注文履歴を取得します。 + +```console +./gradlew run --args="GetOrders 1" +``` + +`order_id` と `timestamp` の UUID が異なる以下のような出力が表示されます。これは、顧客 ID `1` のすべての注文履歴をタイムスタンプの降順で表示します。 + +```console +... +{"order": [{"order_id": "dea4964a-ff50-4ecf-9201-027981a1566e","timestamp": 1650948340914,"customer_id": 1,"customer_name": "Yamada Taro","statement": [{"item_id": 1,"item_name": "Apple","price": 1000,"count": 3,"total": 3000},{"item_id": 2,"item_name": "Orange","price": 2000,"count": 2,"total": 4000}],"total": 7000},{"order_id": "bcc34150-91fa-4bea-83db-d2dbe6f0f30d","timestamp": 1650948412766,"customer_id": 1,"customer_name": "Yamada Taro","statement": [{"item_id": 5,"item_name": "Melon","price": 3000,"count": 1,"total": 3000}],"total": 3000}]} +... +``` + +### クレジット合計の確認 + +次のコマンドを実行して、顧客 ID `1` のクレジット合計を取得します。 + +```console +./gradlew run --args="GetCustomerInfo 1" +``` + +次の出力が表示されます。これは、顧客 ID `1` が `credit_total` の `credit_limit` に達しており、これ以上注文できないことを示しています。 + +```console +... +{"id": 1, "name": "Yamada Taro", "credit_limit": 10000, "credit_total": 10000} +... +``` + +次のコマンドを実行して、ブドウ 1 個とマンゴー 1 個を注文してみます。 + +```console +./gradlew run --args="PlaceOrder 1 3:1,4:1" +``` + +次の出力が表示されます。これは、`credit_total` 金額が `credit_limit` 金額を超えたために注文が失敗したことを示しています。 + +```console +... +java.lang.RuntimeException: Credit limit exceeded + at sample.Sample.placeOrder(Sample.java:205) + at sample.command.PlaceOrderCommand.call(PlaceOrderCommand.java:33) + at sample.command.PlaceOrderCommand.call(PlaceOrderCommand.java:8) + at picocli.CommandLine.executeUserObject(CommandLine.java:1783) + at picocli.CommandLine.access$900(CommandLine.java:145) + at picocli.CommandLine$RunLast.handle(CommandLine.java:2141) + at picocli.CommandLine$RunLast.handle(CommandLine.java:2108) + at picocli.CommandLine$AbstractParseResultHandler.execute(CommandLine.java:1975) + at picocli.CommandLine.execute(CommandLine.java:1904) + at sample.command.SampleCommand.main(SampleCommand.java:35) +... +``` + +### 支払いを行う + +注文を続行するには、顧客 ID `1` が支払いを行って `credit_total` の金額を減らす必要があります。 + +次のコマンドを実行して支払いを行います。 + +```console +./gradlew run --args="Repayment 1 8000" +``` + +次に、次のコマンドを実行して、顧客 ID `1` の `credit_total` 金額を確認します。 + +```console +./gradlew run --args="GetCustomerInfo 1" +``` + +次の出力が表示されます。これは、顧客 ID `1` に支払いが適用され、`credit_total` の金額が減ったことを示しています。 + +```console +... +{"id": 1, "name": "Yamada Taro", "credit_limit": 10000, "credit_total": 2000} +... +``` + +顧客 ID `1` が支払いを済ませたので、次のコマンドを実行してブドウ 1 個とメロン 1 個を注文します。 + +```console +./gradlew run --args="PlaceOrder 1 3:1,4:1" +``` + +以下のように、`order_id` の UUID が異なる、注文が成功したことを示す類似の出力が表示されます。 + +```console +... +{"order_id": "8911cab3-1c2b-4322-9386-adb1c024e078"} +... +``` + +## 参照 + +その他の ScalarDB Cluster チュートリアルについては、以下を参照してください。 + +- [ScalarDB Cluster GraphQL をはじめよう](getting-started-with-scalardb-cluster-graphql.mdx) +- [JDBC 経由の ScalarDB Cluster SQL をはじめよう](getting-started-with-scalardb-cluster-sql-jdbc.mdx) +- [Spring Data JDBC for ScalarDB を使用した ScalarDB Cluster SQL をはじめよう](getting-started-with-scalardb-cluster-sql-spring-data-jdbc.mdx) +- [ScalarDB Cluster での Go をはじめよう](getting-started-with-using-go-for-scalardb-cluster.mdx) +- [ScalarDB Cluster での Python をはじめよう](getting-started-with-using-python-for-scalardb-cluster.mdx) + +Java API で ScalarDB Cluster を使用するアプリケーションの開発の詳細については、以下を参照してください。 + +- [Java API を使用した ScalarDB Cluster の開発者ガイド](developer-guide-for-scalardb-cluster-with-java-api.mdx) + +ScalarDB Cluster gRPC API の詳細については、以下を参照してください。 + +- [ScalarDB Cluster gRPC API ガイド](scalardb-cluster-grpc-api-guide.mdx) +- [ScalarDB Cluster SQL gRPC API ガイド](scalardb-cluster-sql-grpc-api-guide.mdx) diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/getting-started-with-using-go-for-scalardb-cluster.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/getting-started-with-using-go-for-scalardb-cluster.mdx new file mode 100644 index 00000000..65b6116c --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/getting-started-with-using-go-for-scalardb-cluster.mdx @@ -0,0 +1,443 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster での Go をはじめよう + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; +import WarningLicenseKeyContact from '/src/components/ja-jp/_warning-license-key-contact.mdx'; + + + +このドキュメントでは、Go を使用して ScalarDB Cluster の gRPC クライアントコードを記述する方法について説明します。 + +## 前提条件 + +- [Go](https://go.dev/dl/) (最新の 3 つのメジャーリリースのいずれか) +- Kubernetes クラスターで実行されている ScalarDB Cluster + - [ScalarDB Cluster をローカルにデプロイする方法](setup-scalardb-cluster-on-kubernetes-by-using-helm-chart.mdx)の手順に従ってデプロイした Kubernetes クラスターで ScalarDB Cluster が実行されていることを前提としています。 + + + +## サンプルアプリケーション + +このチュートリアルでは、口座間で送金できる電子マネーアプリケーションを作成するプロセスについて説明します。 + +## ステップ 1. `schema.json` を作成する + +以下は簡単なサンプルスキーマです。 + +`schema.json` を作成し、ファイルに次の内容を追加します。 + +```json +{ + "emoney.account": { + "transaction": true, + "partition-key": [ + "id" + ], + "clustering-key": [], + "columns": { + "id": "TEXT", + "balance": "INT" + } + } +} +``` + +## ステップ 2. `database.properties` を作成する + +ScalarDB Cluster の Schema Loader 用に `database.properties` を作成する必要があります。ただし、まず `LoadBalancer` サービス (`scalardb-cluster-envoy`) のサービスリソースの `EXTERNAL-IP` アドレスを取得する必要があります。 + +`EXTERNAL-IP` アドレスを確認するには、次のコマンドを実行します。 + +```console +kubectl get svc scalardb-cluster-envoy +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +scalardb-cluster-envoy LoadBalancer 10.105.121.51 localhost 60053:30641/TCP 16h +``` + +この場合、`EXTERNAL-IP` アドレスは `localhost` です。 + +次に、`database.properties` を作成し、ファイルに次の内容を追加します。 + +```properties +scalar.db.transaction_manager=cluster +scalar.db.contact_points=indirect:localhost +``` + +ScalarDB Cluster に接続するには、`scalar.db.transaction_manager` プロパティに `cluster` を指定する必要があります。また、このチュートリアルでは `indirect` クライアントモードを使用して Envoy のサービスリソースに接続します。クライアントモードの詳細については、[Java API を使用した ScalarDB Cluster の開発者ガイド](developer-guide-for-scalardb-cluster-with-java-api.mdx)を参照してください。 + +## ステップ 3. スキーマをロードする + +ScalarDB Cluster 経由でスキーマをロードするには、専用の ScalarDB Cluster 用 Schema Loader (Schema Loader for Cluster) を使用する必要があります。Schema Loader for Cluster の使用方法は、JAR ファイルの名前が異なることを除いて、[Schema Loader for ScalarDB](../schema-loader.mdx) の使用方法と基本的に同じです。Schema Loader for Cluster は、[ScalarDB リリース](https://github.com/scalar-labs/scalardb/releases/tag/v3.14.0)からダウンロードできます。JAR ファイルをダウンロードしたら、次のコマンドで Schema Loader for Cluster を実行できます。 + +```console +java -jar scalardb-cluster-schema-loader-3.14.0-all.jar --config database.properties -f schema.json --coordinator +``` + +## ステップ 4. Go 環境をセットアップする + +gRPC クイックスタートドキュメントの [Prerequisites](https://grpc.io/docs/languages/go/quickstart/#prerequisites) セクションに従って、次のコンポーネントをインストールします。 + +- Go +- プロトコルバッファコンパイラ、`protoc`、バージョン 3.15 以降 +- プロトコルコンパイラ用の Go プラグイン + +## ステップ 5. ScalarDB Cluster gRPC のスタブコードを生成する + +ScalarDB Cluster の gRPC サーバーと通信するには、proto ファイルからスタブコードを生成する必要があります。 + +まず、新しい作業ディレクトリに、次のコマンドを実行して、gRPC コードの生成に使用する `scalardb-cluster` という名前のディレクトリを作成します。 + +```console +mkdir scalardb-cluster +``` + +次に、`scalardb-cluster.proto` ファイルをダウンロードし、作成したディレクトリに保存します。商用ライセンスをお持ちの ScalarDB Cluster ユーザーで、`scalardb-cluster.proto` ファイルが必要な場合は、[お問い合わせ](https://www.scalar-labs.com/contact)ください。 + +次のコマンドを実行して gRPC コードを生成します。 + +```console +protoc --go_out=. --go_opt=paths=source_relative \ + --go_opt=Mscalardb-cluster/scalardb-cluster.proto=example.com/scalardb-cluster \ + --go-grpc_out=. --go-grpc_opt=paths=source_relative \ + --go-grpc_opt=Mscalardb-cluster/scalardb-cluster.proto=example.com/scalardb-cluster \ + scalardb-cluster/scalardb-cluster.proto +``` + +コマンドを実行すると、`scalardb-cluster` サブディレクトリに `scalardb-cluster.pb.go` と `scalardb-cluster_grpc.pb.go` という 2 つのファイルが表示されます。 + +## ステップ 6. サンプルアプリケーションの作成 + +以下は、gRPC コードを使用するプログラムです。これを作業ディレクトリに `main.go` として保存します。このプログラムは、[ScalarDB をはじめよう](https://scalardb.scalar-labs.com/docs/latest/getting-started-with-scalardb/)の `ElectronicMoney.java` プログラムと同じことを行います。環境内の ScalarDB Cluster `LoadBalancer` サービスの `EXTERNAL-IP` 値に基づいて `SERVER_ADDRESS` の値を更新する必要があることに注意してください。 + +```go +package main + +import ( + "context" + "errors" + "flag" + "fmt" + "log" + "os" + "time" + + pb "emoney/scalardb-cluster" + + "google.golang.org/grpc" + "google.golang.org/grpc/credentials/insecure" +) + +const ( + SERVER_ADDRESS = "localhost:60053" + NAMESPACE = "emoney" + TABLENAME = "account" + ID = "id" + BALANCE = "balance" +) + +var requestHeader = pb.RequestHeader{HopLimit: 10} + +type TxFn func(ctx context.Context, client pb.DistributedTransactionClient, transactionId string) error + +func withTransaction(fn TxFn) error { + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + + // Set up a connection to the server. + conn, err := grpc.Dial(SERVER_ADDRESS, grpc.WithTransportCredentials(insecure.NewCredentials())) + if err != nil { + return err + } + defer conn.Close() + + client := pb.NewDistributedTransactionClient(conn) + + // Begin a transaction + beginResponse, err := client.Begin(ctx, &pb.BeginRequest{RequestHeader: &requestHeader}) + if err != nil { + return err + } + transactionId := beginResponse.TransactionId + + // Execute the function + err = fn(ctx, client, transactionId) + if err != nil { + // Rollback the transaction if there is an error + client.Rollback(ctx, &pb.RollbackRequest{TransactionId: transactionId}) + return err + } + + // Commit the transaction + _, err = client.Commit(ctx, &pb.CommitRequest{RequestHeader: &requestHeader, TransactionId: transactionId}) + return err +} + +func charge(ctx context.Context, client pb.DistributedTransactionClient, transactionId string, id string, amount int) error { + partitionKey := pb.Key{Columns: []*pb.Column{{Name: ID, Value: &pb.Column_TextValue_{TextValue: &pb.Column_TextValue{Value: &id}}}}} + + // Retrieve the current balance for id + get := pb.Get{ + NamespaceName: NAMESPACE, TableName: TABLENAME, + PartitionKey: &partitionKey, ClusteringKey: nil, + GetType: pb.Get_GET_TYPE_GET, + } + getResponse, err := client.Get(ctx, &pb.GetRequest{RequestHeader: &requestHeader, TransactionId: transactionId, Get: &get}) + if err != nil { + return err + } + + // Calculate the balance + balance := int32(amount) + if result := getResponse.GetResult(); result != nil { + for _, column := range result.GetColumns() { + if column.Name == BALANCE { + balance += column.GetIntValue().GetValue() + break + } + } + } + + // Update the balance + put := pb.Put{ + NamespaceName: NAMESPACE, TableName: TABLENAME, + PartitionKey: &partitionKey, ClusteringKey: nil, + Columns: []*pb.Column{ + {Name: BALANCE, Value: &pb.Column_IntValue_{IntValue: &pb.Column_IntValue{Value: &balance}}}, + }, + } + _, err = client.Put(ctx, &pb.PutRequest{RequestHeader: &requestHeader, TransactionId: transactionId, Puts: []*pb.Put{&put}}) + return err +} + +func pay(ctx context.Context, client pb.DistributedTransactionClient, transactionId string, fromId string, toId string, amount int) error { + fromPartitionKey := pb.Key{Columns: []*pb.Column{{Name: ID, Value: &pb.Column_TextValue_{TextValue: &pb.Column_TextValue{Value: &fromId}}}}} + toPartitionKey := pb.Key{Columns: []*pb.Column{{Name: ID, Value: &pb.Column_TextValue_{TextValue: &pb.Column_TextValue{Value: &toId}}}}} + + // Retrieve the current balances for ids + fromGet := pb.Get{ + NamespaceName: NAMESPACE, TableName: TABLENAME, + PartitionKey: &fromPartitionKey, ClusteringKey: nil, + GetType: pb.Get_GET_TYPE_GET, + } + fromGetResponse, err := client.Get(ctx, &pb.GetRequest{RequestHeader: &requestHeader, TransactionId: transactionId, Get: &fromGet}) + if err != nil { + return err + } + toGet := pb.Get{ + NamespaceName: NAMESPACE, TableName: TABLENAME, + PartitionKey: &toPartitionKey, ClusteringKey: nil, + GetType: pb.Get_GET_TYPE_GET, + } + toGetResponse, err := client.Get(ctx, &pb.GetRequest{RequestHeader: &requestHeader, TransactionId: transactionId, Get: &toGet}) + if err != nil { + return err + } + + // Calculate the balances (it assumes that both accounts exist) + var ( + fromBalance int32 + toBalance int32 + ) + for _, column := range fromGetResponse.GetResult().GetColumns() { + if column.Name == BALANCE { + fromBalance = column.GetIntValue().GetValue() + break + } + } + for _, column := range toGetResponse.GetResult().GetColumns() { + if column.Name == BALANCE { + toBalance = column.GetIntValue().GetValue() + break + } + } + newFromBalance := fromBalance - int32(amount) + newToBalance := toBalance + int32(amount) + + if newFromBalance < 0 { + return errors.New(fromId + " doesn't have enough balance.") + } + + // Update the balances + fromPut := pb.Put{ + NamespaceName: NAMESPACE, TableName: TABLENAME, + PartitionKey: &fromPartitionKey, ClusteringKey: nil, + Columns: []*pb.Column{ + {Name: BALANCE, Value: &pb.Column_IntValue_{IntValue: &pb.Column_IntValue{Value: &newFromBalance}}}, + }, + } + toPut := pb.Put{ + NamespaceName: NAMESPACE, TableName: TABLENAME, + PartitionKey: &toPartitionKey, ClusteringKey: nil, + Columns: []*pb.Column{ + {Name: BALANCE, Value: &pb.Column_IntValue_{IntValue: &pb.Column_IntValue{Value: &newToBalance}}}, + }, + } + _, err = client.Put(ctx, &pb.PutRequest{RequestHeader: &requestHeader, TransactionId: transactionId, Puts: []*pb.Put{&fromPut, &toPut}}) + return err +} + +func getBalance(ctx context.Context, client pb.DistributedTransactionClient, transactionId string, id string) (int, error) { + // Retrieve the current balance for id + get := pb.Get{ + NamespaceName: NAMESPACE, TableName: TABLENAME, + PartitionKey: &pb.Key{Columns: []*pb.Column{{Name: ID, Value: &pb.Column_TextValue_{TextValue: &pb.Column_TextValue{Value: &id}}}}}, + ClusteringKey: nil, + GetType: pb.Get_GET_TYPE_GET, + } + getResponse, err := client.Get(ctx, &pb.GetRequest{RequestHeader: &requestHeader, TransactionId: transactionId, Get: &get}) + if err != nil { + return 0, err + } + if getResponse.GetResult() == nil || len(getResponse.GetResult().GetColumns()) == 0 { + return 0, errors.New("Account " + id + " doesn't exist.") + } + + var balance int + for _, column := range getResponse.GetResult().GetColumns() { + if column.Name == BALANCE { + balance = int(column.GetIntValue().GetValue()) + break + } + } + return balance, nil +} + +func main() { + var ( + action = flag.String("action", "", "Action to perform: charge / pay / getBalance") + fromId = flag.String("from", "", "From account (needed for pay)") + toId = flag.String("to", "", "To account (needed for charge and pay)") + id = flag.String("id", "", "Account id (needed for getBalance)") + ) + var amount int + flag.IntVar(&amount, "amount", 0, "Amount to transfer (needed for charge and pay)") + flag.Parse() + + if *action == "charge" { + if *toId == "" || amount < 0 { + printUsageAndExit() + } + err := withTransaction(func(ctx context.Context, client pb.DistributedTransactionClient, txId string) error { + return charge(ctx, client, txId, *toId, amount) + }) + if err != nil { + log.Fatalf("error: %v", err) + } + } else if *action == "pay" { + if *toId == "" || *fromId == "" || amount < 0 { + printUsageAndExit() + } + err := withTransaction(func(ctx context.Context, client pb.DistributedTransactionClient, txId string) error { + return pay(ctx, client, txId, *fromId, *toId, amount) + }) + if err != nil { + log.Fatalf("error: %v", err) + } + } else if *action == "getBalance" { + if *id == "" { + printUsageAndExit() + } + var balance int + err := withTransaction(func(ctx context.Context, client pb.DistributedTransactionClient, txId string) error { + var err error + balance, err = getBalance(ctx, client, txId, *id) + return err + }) + if err != nil { + log.Fatalf("error: %v", err) + } + fmt.Println(balance) + } else { + fmt.Fprintln(os.Stderr, "Unknown action "+*action) + printUsageAndExit() + } +} + +func printUsageAndExit() { + flag.Usage() + os.Exit(1) +} +``` + +`main.go` ファイルを作成した後、次のコマンドを実行して `go.mod` ファイルを作成する必要があります。 + +```console +go mod init emoney +go mod tidy +``` + +これで、ディレクトリ構造は次のようになります。 + +```text +. +├── go.mod +├── go.sum +├── main.go +└── scalardb-cluster + ├── scalardb-cluster.pb.go + ├── scalardb-cluster.proto + └── scalardb-cluster_grpc.pb.go +``` + +その後、次のようにプログラムを実行できます: + +- `user1` に `1000` を請求します: + + ```console + go run main.go -action charge -amount 1000 -to user1 + ``` + +- `merchant1` に `0` を請求します (`merchant1` のアカウントを作成するだけです): + + ```console + go run main.go -action charge -amount 0 -to merchant1 + ``` + +- `user1` から `merchant1` に `100` を支払います: + + ```console + go run main.go -action pay -amount 100 -from user1 -to merchant1 + ``` + +- `user1` の残高を取得します。 + + ```console + go run main.go -action getBalance -id user1 + ``` + +- `merchant1` の残高を取得します。 + + ```console + go run main.go -action getBalance -id merchant1 + ``` + +`go build` を使用してバイナリを取得してから実行することもできます。 + +```console +go build +./emoney -action getBalance -id user1 +``` + +## 参照 + +その他の ScalarDB Cluster チュートリアルについては、以下を参照してください。 + +- [ScalarDB Cluster をはじめよう](getting-started-with-scalardb-cluster.mdx) +- [ScalarDB Cluster GraphQL をはじめよう](getting-started-with-scalardb-cluster-graphql.mdx) +- [JDBC 経由の ScalarDB Cluster SQL をはじめよう](getting-started-with-scalardb-cluster-sql-jdbc.mdx) +- [Spring Data JDBC for ScalarDB を使用した ScalarDB Cluster SQL をはじめよう](getting-started-with-scalardb-cluster-sql-spring-data-jdbc.mdx) +- [ScalarDB Cluster での Python をはじめよう](getting-started-with-using-python-for-scalardb-cluster.mdx) + +Java API で ScalarDB Cluster を使用するアプリケーションの開発の詳細については、以下を参照してください。 + +- [Java API を使用した ScalarDB Cluster の開発者ガイド](developer-guide-for-scalardb-cluster-with-java-api.mdx) + +ScalarDB Cluster gRPC API の詳細については、以下を参照してください。 + +- [ScalarDB Cluster gRPC API ガイド](scalardb-cluster-grpc-api-guide.mdx) +- [ScalarDB Cluster SQL gRPC API ガイド](scalardb-cluster-sql-grpc-api-guide.mdx) diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/getting-started-with-using-python-for-scalardb-cluster.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/getting-started-with-using-python-for-scalardb-cluster.mdx new file mode 100644 index 00000000..40bad077 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/getting-started-with-using-python-for-scalardb-cluster.mdx @@ -0,0 +1,486 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster での Python をはじめよう + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; +import WarningLicenseKeyContact from '/src/components/ja-jp/_warning-license-key-contact.mdx'; + + + +このドキュメントでは、Python を使用して ScalarDB Cluster の gRPC クライアントコードを記述する方法について説明します。 + +## 前提条件 + +- [Python](https://www.python.org/downloads) 3.7 以降 +- Kubernetes クラスターで実行されている ScalarDB Cluster + - [ScalarDB Cluster をローカルにデプロイする方法](setup-scalardb-cluster-on-kubernetes-by-using-helm-chart.mdx)の手順に従ってデプロイした Kubernetes クラスターで ScalarDB Cluster が実行されていることを前提としています。 + + + +## サンプルアプリケーション + +このチュートリアルでは、口座間で送金できる電子マネーアプリケーションを作成するプロセスについて説明します。 + +## ステップ 1. `schema.json` を作成する + +以下は簡単なサンプルスキーマです。 + +`schema.json` を作成し、ファイルに次の内容を追加します。 + +```json +{ + "emoney.account": { + "transaction": true, + "partition-key": [ + "id" + ], + "clustering-key": [], + "columns": { + "id": "TEXT", + "balance": "INT" + } + } +} +``` + +## ステップ 2. `database.properties` を作成する + +ScalarDB Cluster の Schema Loader 用に `database.properties` を作成する必要があります。ただし、まず `LoadBalancer` サービス (`scalardb-cluster-envoy`) のサービスリソースの `EXTERNAL-IP` アドレスを取得する必要があります。 + +`EXTERNAL-IP` アドレスを確認するには、次のコマンドを実行します。 + +```console +kubectl get svc scalardb-cluster-envoy +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +scalardb-cluster-envoy LoadBalancer 10.105.121.51 localhost 60053:30641/TCP 16h +``` + +この場合、`EXTERNAL-IP` アドレスは `localhost` です。 + +次に、`database.properties` を作成し、ファイルに次の内容を追加します。 + +```properties +scalar.db.transaction_manager=cluster +scalar.db.contact_points=indirect:localhost +``` + +ScalarDB Cluster に接続するには、`scalar.db.transaction_manager` プロパティに `cluster` を指定する必要があります。また、このチュートリアルでは `indirect` クライアントモードを使用して Envoy のサービスリソースに接続します。クライアントモードの詳細については、[Java API を使用した ScalarDB Cluster の開発者ガイド](developer-guide-for-scalardb-cluster-with-java-api.mdx)を参照してください。 + +## ステップ 3. スキーマをロードする + +ScalarDB Cluster 経由でスキーマをロードするには、専用の ScalarDB Cluster 用 Schema Loader (Schema Loader for Cluster) を使用する必要があります。Schema Loader for Cluster の使用方法は、JAR ファイルの名前が異なることを除いて、[Schema Loader for ScalarDB](../schema-loader.mdx) の使用方法と基本的に同じです。Schema Loader for Cluster は、[ScalarDB リリース](https://github.com/scalar-labs/scalardb/releases/tag/v3.14.0)からダウンロードできます。JAR ファイルをダウンロードしたら、次のコマンドで Schema Loader for Cluster を実行できます。 + +```console +java -jar scalardb-cluster-schema-loader-3.14.0-all.jar --config database.properties -f schema.json --coordinator +``` + +## ステップ 4. Python 環境をセットアップする + +Python 環境の管理方法は自由に選択できます。このガイドでは、Python アプリケーションが `venv` を使用して環境で実行されていることを前提としています。 + +任意の場所に作業ディレクトリを作成し、そこに移動します。次に、次のコマンドを実行して `venv` をアクティブ化します。 + +```console +python3 -m venv venv +source venv/bin/activate +``` + +`pip` コマンドを使用して gRPC パッケージをインストールしましょう。 + +```console +pip install grpcio grpcio-tools +``` + +## ステップ 5. ScalarDB Cluster gRPC のスタブコードを生成する + +ScalarDB Cluster の gRPC サーバーと通信するには、proto ファイルからスタブコードを生成する必要があります。 + +まず、`scalardb-cluster.proto` ファイルをダウンロードし、作業ディレクトリに保存します。商用ライセンスをお持ちの ScalarDB Cluster ユーザーで、`scalardb-cluster.proto` ファイルが必要な場合は、[お問い合わせ](https://www.scalar-labs.com/contact)ください。 + +次のコマンドを実行すると、スタブコードを生成できます。 + +```console +python -m grpc_tools.protoc -I . --python_out=. --pyi_out=. --grpc_python_out=. scalardb-cluster.proto +``` + +次のファイルが生成されます: + +- `scalardb_cluster_pb2.py` +- `scalardb_cluster_pb2.pyi` +- `scalardb_cluster_pb2_grpc.py` + +## ステップ 6. サンプルアプリケーションの作成 + +以下は、スタブコードを使用するサンプル Python アプリケーション (`electronic_money.py`) です。このプログラムは、[ScalarDB をはじめよう](https://scalardb.scalar-labs.com/docs/latest/getting-started-with-scalardb/) の `ElectronicMoney.java` プログラムと同じことを行います。環境内の ScalarDB Cluster `LoadBalancer` サービスの `EXTERNAL-IP` 値に基づいて `SERVER_ADDRESS` の値を更新する必要があることに注意してください。 + +```python +import argparse +from typing import Optional + +import grpc + +import scalardb_cluster_pb2_grpc +from scalardb_cluster_pb2 import ( + BeginRequest, + BeginResponse, + Column, + CommitRequest, + Get, + GetRequest, + GetResponse, + Key, + Put, + PutRequest, + RequestHeader, + RollbackRequest, +) + +SERVER_ADDRESS = "localhost:60053" +NAMESPACE = "emoney" +TABLENAME = "account" +ID = "id" +BALANCE = "balance" + +request_header = RequestHeader(hop_limit=10) + + +def charge(id: str, amount: int) -> None: + with grpc.insecure_channel(SERVER_ADDRESS) as channel: + stub = scalardb_cluster_pb2_grpc.DistributedTransactionStub(channel) + + begin_response: BeginResponse = stub.Begin( + BeginRequest(request_header=request_header) + ) + + transaction_id = begin_response.transaction_id + + try: + pkey = Key( + columns=[ + Column( + name=ID, + text_value=Column.TextValue(value=id), + ) + ] + ) + + # Retrieve the current balance for id + get = Get( + namespace_name=NAMESPACE, + table_name=TABLENAME, + get_type=Get.GetType.GET_TYPE_GET, + partition_key=pkey, + ) + get_response: GetResponse = stub.Get( + GetRequest( + request_header=request_header, + transaction_id=transaction_id, + get=get, + ) + ) + + # Calculate the balance + balance = amount + if get_response.result.columns: + balance_column = next( + c for c in get_response.result.columns if c.name == BALANCE + ) + current = balance_column.int_value.value + balance += current + + # Update the balance + put = Put( + namespace_name=NAMESPACE, + table_name=TABLENAME, + partition_key=pkey, + columns=[ + Column(name=BALANCE, int_value=Column.IntValue(value=balance)) + ], + ) + stub.Put( + PutRequest( + request_header=request_header, + transaction_id=transaction_id, + puts=[put], + ) + ) + + # Commit the transaction + stub.Commit( + CommitRequest( + request_header=request_header, + transaction_id=transaction_id, + ) + ) + except Exception as e: + # Rollback the transaction + stub.Rollback( + RollbackRequest( + request_header=request_header, + transaction_id=transaction_id, + ) + ) + raise e + + +def pay(from_id: str, to_id: str, amount: int) -> None: + with grpc.insecure_channel(SERVER_ADDRESS) as channel: + stub = scalardb_cluster_pb2_grpc.DistributedTransactionStub(channel) + + begin_response: BeginResponse = stub.Begin( + BeginRequest(request_header=request_header) + ) + + transaction_id = begin_response.transaction_id + + try: + from_pkey = Key( + columns=[ + Column( + name=ID, + text_value=Column.TextValue(value=from_id), + ) + ] + ) + to_pkey = Key( + columns=[ + Column( + name=ID, + text_value=Column.TextValue(value=to_id), + ) + ] + ) + + # Retrieve the current balances for ids + from_get = Get( + namespace_name=NAMESPACE, + table_name=TABLENAME, + get_type=Get.GetType.GET_TYPE_GET, + partition_key=from_pkey, + ) + from_get_response: GetResponse = stub.Get( + GetRequest( + request_header=request_header, + transaction_id=transaction_id, + get=from_get, + ) + ) + to_get = Get( + namespace_name=NAMESPACE, + table_name=TABLENAME, + get_type=Get.GetType.GET_TYPE_GET, + partition_key=to_pkey, + ) + to_get_response: GetResponse = stub.Get( + GetRequest( + request_header=request_header, + transaction_id=transaction_id, + get=to_get, + ) + ) + + # Calculate the balances (it assumes that both accounts exist) + new_from_balance = ( + next( + c for c in from_get_response.result.columns if c.name == BALANCE + ).int_value.value + - amount + ) + new_to_balance = ( + next( + c for c in to_get_response.result.columns if c.name == BALANCE + ).int_value.value + + amount + ) + + if new_from_balance < 0: + raise RuntimeError(from_id + " doesn't have enough balance.") + + # Update the balances + from_put = Put( + namespace_name=NAMESPACE, + table_name=TABLENAME, + partition_key=from_pkey, + columns=[ + Column( + name=BALANCE, int_value=Column.IntValue(value=new_from_balance) + ) + ], + ) + to_put = Put( + namespace_name=NAMESPACE, + table_name=TABLENAME, + partition_key=to_pkey, + columns=[ + Column( + name=BALANCE, int_value=Column.IntValue(value=new_to_balance) + ) + ], + ) + stub.Put( + PutRequest( + request_header=request_header, + transaction_id=transaction_id, + puts=[from_put, to_put], + ) + ) + + # Commit the transaction (records are automatically recovered in case of failure) + stub.Commit( + CommitRequest( + request_header=request_header, + transaction_id=transaction_id, + ) + ) + except Exception as e: + # Rollback the transaction + stub.Rollback( + RollbackRequest( + request_header=request_header, + transaction_id=transaction_id, + ) + ) + raise e + + +def get_balance(id: str) -> Optional[int]: + with grpc.insecure_channel(SERVER_ADDRESS) as channel: + stub = scalardb_cluster_pb2_grpc.DistributedTransactionStub(channel) + + begin_response: BeginResponse = stub.Begin( + BeginRequest(request_header=request_header) + ) + + transaction_id = begin_response.transaction_id + + try: + # Retrieve the current balance for id + get = Get( + namespace_name=NAMESPACE, + table_name=TABLENAME, + get_type=Get.GetType.GET_TYPE_GET, + partition_key=Key( + columns=[ + Column( + name=ID, + text_value=Column.TextValue(value=id), + ) + ] + ), + ) + get_response: GetResponse = stub.Get( + GetRequest( + request_header=request_header, + transaction_id=transaction_id, + get=get, + ) + ) + + balance = None + if get_response.result.columns: + balance_column = next( + c for c in get_response.result.columns if c.name == BALANCE + ) + balance = balance_column.int_value.value + + # Commit the transaction + stub.Commit( + CommitRequest( + request_header=request_header, + transaction_id=transaction_id, + ) + ) + + return balance + + except Exception as e: + # Rollback the transaction + stub.Rollback( + RollbackRequest( + request_header=request_header, + transaction_id=transaction_id, + ) + ) + raise e + + +if __name__ == "__main__": + parser = argparse.ArgumentParser() + subparsers = parser.add_subparsers(required=True) + + parser_charge = subparsers.add_parser("charge") + parser_charge.add_argument("-amount", type=int, required=True) + parser_charge.add_argument("-to", type=str, required=True, dest="to_id") + parser_charge.set_defaults(func=lambda args: charge(args.to_id, args.amount)) + + parser_pay = subparsers.add_parser("pay") + parser_pay.add_argument("-amount", type=int, required=True) + parser_pay.add_argument("-from", type=str, required=True, dest="from_id") + parser_pay.add_argument("-to", type=str, required=True, dest="to_id") + parser_pay.set_defaults( + func=lambda args: pay(args.from_id, args.to_id, args.amount) + ) + + parser_get_balance = subparsers.add_parser("get-balance") + parser_get_balance.add_argument("-id", type=str, required=True) + parser_get_balance.set_defaults(func=lambda args: print(get_balance(args.id))) + + args = parser.parse_args() + args.func(args) + +``` + +その後、次のようにプログラムを実行できます: + +- `user1` に `1000` を請求します: + + ```console + python electronic_money.py charge -amount 1000 -to user1 + ``` + +- `merchant1` に `0` を請求します (`merchant1` のアカウントを作成するだけです): + + ```console + python electronic_money.py charge -amount 0 -to merchant1 + ``` + +- `user1` から `merchant1` に `100` を支払います: + + ```console + python electronic_money.py pay -amount 100 -from user1 -to merchant1 + ``` + +- `user1` の残高を取得します。 + + ```console + python electronic_money.py get-balance -id user1 + ``` + +- `merchant1` の残高を取得します。 + + ```console + python electronic_money.py get-balance -id merchant1 + ``` + +## 参照 + +その他の ScalarDB Cluster チュートリアルについては、以下を参照してください。 + +- [ScalarDB Cluster をはじめよう](getting-started-with-scalardb-cluster.mdx) +- [ScalarDB Cluster GraphQL をはじめよう](getting-started-with-scalardb-cluster-graphql.mdx) +- [JDBC 経由の ScalarDB Cluster SQL をはじめよう](getting-started-with-scalardb-cluster-sql-jdbc.mdx) +- [Spring Data JDBC for ScalarDB を使用した ScalarDB Cluster SQL をはじめよう](getting-started-with-scalardb-cluster-sql-spring-data-jdbc.mdx) +- [ScalarDB Cluster での Go をはじめよう](getting-started-with-using-go-for-scalardb-cluster.mdx) + +Java API で ScalarDB Cluster を使用するアプリケーションの開発の詳細については、以下を参照してください。 + +- [Java API を使用した ScalarDB Cluster の開発者ガイド](developer-guide-for-scalardb-cluster-with-java-api.mdx) + +ScalarDB Cluster gRPC API の詳細については、以下を参照してください。 + +- [ScalarDB Cluster gRPC API ガイド](scalardb-cluster-grpc-api-guide.mdx) +- [ScalarDB Cluster SQL gRPC API ガイド](scalardb-cluster-sql-grpc-api-guide.mdx) diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/images/direct-kubernetes-client-mode.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/images/direct-kubernetes-client-mode.png new file mode 100644 index 00000000..13df52e6 Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/images/direct-kubernetes-client-mode.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/images/getting-started-ERD.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/images/getting-started-ERD.png new file mode 100644 index 00000000..1a6d13c5 Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/images/getting-started-ERD.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/images/indirect-client-mode.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/images/indirect-client-mode.png new file mode 100644 index 00000000..4e96108f Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/images/indirect-client-mode.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/images/scalardb-cluster-architecture.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/images/scalardb-cluster-architecture.png new file mode 100644 index 00000000..24a0a50d Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/images/scalardb-cluster-architecture.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/index.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/index.mdx new file mode 100644 index 00000000..d57c4ea0 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/index.mdx @@ -0,0 +1,71 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +ScalarDB Cluster は、[ScalarDB](../overview.mdx) のクラスタリングソリューションであり、一連のクラスターノードで構成され、各ノードは ScalarDB 機能を提供します。各クラスターノードには、トランザクション要求をクラスター内の適切なクラスターノードに転送するルーティングメカニズムがあります。 + +## ScalarDB Cluster を使用する理由 + +マイクロサービストランザクションなど、複数のクライアント要求にまたがるトランザクションを実行する場合、トランザクション処理のステートフルな性質のため、トランザクションのすべての要求は同じサーバーで処理する必要があります。ただし、分散環境では、スケーラビリティと可用性のためにサービスは通常複数のサーバー (またはホスト) で実行されるため、同じサーバーに要求をルーティングするのは簡単ではありません。このシナリオでは、トランザクション内のすべての要求を同じサーバーにルーティングする必要があり、負荷分散を確実にするために異なるトランザクションを分散する必要があります。 + +この課題に対処するには、セッションアフィニティ (スティッキーセッションとも呼ばれます) などのルーティングメカニズムを構成する必要があります。この戦略により、トランザクション内のリクエストが一貫して同じサーバーにルーティングされるようになります。または、gRPC を使用して双方向ストリーミング RPC を活用することもできます。ただし、これらの構成を実装するには通常、かなりの時間と労力が必要であることに注意してください。さらに、使用しているロードバランサー製品によっては、特定の構成調整が必要になる場合があります。 + +このトピックの詳細については、[2 フェーズコミットインターフェイスを使用したトランザクションでのリクエストルーティング](../two-phase-commit-transactions.mdx#2-フェーズコミットインターフェイスを使用したトランザクションでのリクエストルーティング) を参照してください。 + +ScalarDB Cluster は、リクエストをクラスター内の適切なクラスターノードに転送できるルーティングメカニズムを提供することで、この問題に対処します。したがって、クラスターノードがリクエストを受信すると、ノードはそのリクエストをクラスター内の正しいクラスターノードにルーティングできます。 + +## アーキテクチャ + +ScalarDB Cluster は、それぞれ ScalarDB 機能を備えた一連のクラスターノードで構成されています。このソリューションを使用することで、各クラスターノードは独立してトランザクションを実行できます。 + +ScalarDB Cluster の注目すべき機能は、ルーティングメカニズムを使用してトランザクション要求を分散することです。クラスターノードが要求を受信すると、ノードは要求を処理するのに適切なクラスターノードであるかどうかを判断します。適切なノードでない場合、ノードは要求をクラスター内の適切なクラスターノードにルーティングします。適切なクラスターノードを判断するために、ScalarDB Cluster はコンシステントハッシュアルゴリズムを使用します。 + +メンバーシップ管理は、ScalarDB Cluster で重要な役割を果たします。クラスターノードがクラスターに参加または離脱すると、クラスターの構成が自動的に調整され、この変更が反映されます。ScalarDB Cluster は現在、Kubernetes API を使用してメンバーシップ情報を取得します。 + +:::note + +現在、ScalarDB Cluster は Kubernetes 上での実行のみをサポートしています。 + +::: + +![ScalarDB Cluster アーキテクチャ](images/scalardb-cluster-architecture.png) + +## はじめに + +チュートリアルを開始する前に、ScalarDB Cluster をセットアップする必要があります。ScalarDB Cluster をセットアップするには、[ScalarDB Cluster をローカルにデプロイする方法](setup-scalardb-cluster-on-kubernetes-by-using-helm-chart.mdx) を参照してください。 + +ScalarDB Cluster の使用開始に関するチュートリアルについては、以下を参照してください。 + +* [ScalarDB Cluster をはじめよう](getting-started-with-scalardb-cluster.mdx) +* [ScalarDB Cluster GraphQL をはじめよう](getting-started-with-scalardb-cluster-graphql.mdx) +* [JDBC 経由の ScalarDB Cluster SQL をはじめよう](getting-started-with-scalardb-cluster-sql-jdbc.mdx) +* [Spring Data JDBC for ScalarDB を使用した ScalarDB Cluster SQL をはじめよう](getting-started-with-scalardb-cluster-sql-spring-data-jdbc.mdx) + +## 参考資料 + +ScalarDB Cluster Helm Chart の詳細については、以下を参照してください。 + +* [ScalarDB Cluster Helm Chart](https://github.com/scalar-labs/helm-charts/tree/main/charts/scalardb-cluster) +* [Scalar Helm Chart を使用して Scalar 製品をデプロイする](../helm-charts/how-to-deploy-scalar-products.mdx) +* [ScalarDB Cluster のデプロイする方法](../helm-charts/how-to-deploy-scalardb-cluster.mdx) + +For details about the configurations for ScalarDB Cluster, refer to the following: + +* [ScalarDB Cluster の構成](scalardb-cluster-configurations.mdx) + +Java API で ScalarDB Cluster を使用するアプリケーションの開発の詳細については、以下を参照してください。 + +* [Java API を使用した ScalarDB Cluster の開発者ガイド](developer-guide-for-scalardb-cluster-with-java-api.mdx) + +ScalarDB Cluster gRPC API の詳細については、以下を参照してください。 + +* [ScalarDB Cluster gRPC API ガイド](scalardb-cluster-grpc-api-guide.mdx) +* [ScalarDB Cluster SQL gRPC API ガイド](scalardb-cluster-sql-grpc-api-guide.mdx) diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/run-non-transactional-storage-operations-through-scalardb-cluster.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/run-non-transactional-storage-operations-through-scalardb-cluster.mdx new file mode 100644 index 00000000..0e52df5a --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/run-non-transactional-storage-operations-through-scalardb-cluster.mdx @@ -0,0 +1,313 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster を通じて非トランザクションストレージ操作を実行する + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + +このガイドでは、ScalarDB Cluster を介して非トランザクションストレージ操作を実行する方法について説明します。 + +:::warning + +ScalarDB Cluster のライセンスキー (試用ライセンスまたは商用ライセンス) が必要です。ライセンスキーをお持ちでない場合は、[お問い合わせ](https://www.scalar-labs.com/contact)ください。 + +::: + +## 準備 + +このガイドでは、ScalarDB サンプルリポジトリのサンプルを使用して、データベースと ScalarDB Cluster をスタンドアロンモードでセットアップします。 + +:::note + +スタンドアロンモードの ScalarDB Cluster は、主に開発とテストを目的としています。 + +::: + +### ScalarDB サンプルリポジトリのクローンを作成する + +**ターミナル** を開き、次のコマンドを実行して ScalarDB サンプルリポジトリのクローンを作成します。 + +```console +git clone https://github.com/scalar-labs/scalardb-samples +``` + +次に、次のコマンドを実行して、必要なファイルが含まれているディレクトリに移動します。 + +```console +cd scalardb-samples/scalardb-cluster-standalone-mode +``` + +## データベースをセットアップする + +データベースを選択し、指示に従って ScalarDB Cluster 用に設定します。 + +ScalarDB がサポートするデータベースの一覧については、[データベース](../requirements.mdx#データベース)を参照してください。 + + + +

MySQL をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で MySQL を実行できます。 + + MySQL を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d mysql + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の MySQL のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For MySQL + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:mysql://mysql-1:3306/ + scalar.db.username=root + scalar.db.password=mysql + ``` + + +

PostgreSQL をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で PostgreSQL を実行できます。 + + PostgreSQL を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d postgres + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の PostgreSQL のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For PostgreSQL + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:postgresql://postgres-1:5432/ + scalar.db.username=postgres + scalar.db.password=postgres + ``` + + +

Oracle Database をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で Oracle Database を実行できます。 + + Oracle Database を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d oracle + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の Oracle データベースのプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For Oracle + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:oracle:thin:@//oracle-1:1521/FREEPDB1 + scalar.db.username=SYSTEM + scalar.db.password=Oracle + ``` + + +

SQL Server をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で SQL Server を実行できます。 + + SQL Server を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d sqlserver + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の SQL Server のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For SQL Server + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:sqlserver://sqlserver-1:1433;encrypt=true;trustServerCertificate=true + scalar.db.username=sa + scalar.db.password=SqlServer22 + ``` + + +

Amazon DynamoDB Local を実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で Amazon DynamoDB Local を実行できます。 + + Amazon DynamoDB Local を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d dynamodb + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の Amazon DynamoDB Local のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For DynamoDB Local + scalar.db.storage=dynamo + scalar.db.contact_points=sample + scalar.db.username=sample + scalar.db.password=sample + scalar.db.dynamo.endpoint_override=http://dynamodb-1:8000 + ``` + + + Azure Cosmos DB for NoSQL を使用するには、Azure アカウントが必要です。Azure アカウントがない場合は、[Azure Cosmos DB アカウントを作成する](https://learn.microsoft.com/ja-jp/azure/cosmos-db/nosql/quickstart-portal#create-account)にアクセスしてください。 + +

Cosmos DB for NoSQL を構成する

+ + [既定の整合性レベルを構成する](https://learn.microsoft.com/ja-jp/azure/cosmos-db/nosql/how-to-manage-consistency#configure-the-default-consistency-level)の公式ドキュメントに従って、**既定の整合性レベル** を **強力** に設定します。 + +

ScalarDB Cluster を構成する

+ + 次の手順では、ローカル環境に JDK が適切にインストールおよび構成されており、Azure で Cosmos DB for NoSQL アカウントが適切に構成されていることを前提としています。 + + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。説明に従って、`scalar.db.contact_points` と `scalar.db.password` の値を必ず変更してください。 + + ```properties + # For Cosmos DB + scalar.db.storage=cosmos + scalar.db.contact_points= + scalar.db.password= + ``` + +:::note + +Azure Cosmos DB アカウントのプライマリーキーまたはセカンダリキーを `scalar.db.password` の値として使用できます。 + +::: + + +

Cassandra をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で Apache Cassandra を実行できます。 + + Apache Cassandra を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d cassandra + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の Cassandra のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For Cassandra + scalar.db.storage=cassandra + scalar.db.contact_points=cassandra-1 + scalar.db.username=cassandra + scalar.db.password=cassandra + ``` + + + +ScalarDB の構成の包括的なリストについては、[ScalarDB 構成](configurations.mdx)を参照してください。 + +## スタンドアロンモードで ScalarDB Cluster を設定する + +スタンドアロンモードで ScalarDB Cluster を設定するには、非トランザクションストレージ操作を実行するように ScalarDB Cluster を構成し、ライセンスキーを設定してから、ScalarDB Cluster を起動する必要があります。 + +### 非トランザクションストレージ操作を実行するように ScalarDB Cluster を構成する + +非トランザクションストレージ操作を実行するには、構成ファイル `scalardb-cluster-node.properties` で `scalar.db.transaction_manager` プロパティを `single-crud-operation` に設定する必要があります。 + +```properties +scalar.db.transaction_manager=single-crud-operation +``` + +### ライセンスキーの設定 + +プロパティファイルで ScalarDB Cluster のライセンスキー (試用ライセンスまたは商用ライセンス) を設定します。詳細については、[製品ライセンスキーの設定方法](../scalar-licensing/README.mdx)を参照してください。 + +### スタンドアロンモードで ScalarDB Cluster を起動 + +スタンドアロンモードで ScalarDB Cluster を起動するには、次のコマンドを実行します。 + +:::note + +ScalarDB Cluster のその他の設定を変更する場合は、以下のコマンドを実行する前に `scalardb-cluster-node.properties` ファイルを更新してください。 + +::: + +```console +docker compose up -d scalardb-cluster-node +``` + +## スキーマを作成またはインポートする + +ScalarDB には、実装固有のデータモデルとスキーマにマップされる独自のデータモデルとスキーマがあります。 + +- **データベーススキーマを作成する必要がありますか?** [クラスター用 Schema Loader](developer-guide-for-scalardb-cluster-with-java-api.mdx#クラスター用-schema-loader) を参照してください。 +- **既存のデータベースをインポートする必要がありますか?** [ScalarDB Schema Loader を使用して既存のテーブルを ScalarDB にインポートする](../schema-loader-import.mdx)を参照してください。 + +## Java アプリケーションを作成する + +このセクションでは、ScalarDB Cluster Java Client SDK をプロジェクトに追加する方法と、Java を使用して非トランザクションストレージ操作を実行するようにプロジェクトを構成する方法について説明します。 + +### ScalarDB Cluster Java Client SDK をビルドに追加する + +ScalarDB Cluster Java Client SDK は、[Maven Central Repository](https://mvnrepository.com/artifact/com.scalar-labs/scalardb-cluster-java-client-sdk) で入手できます。Gradle または Maven を使用して、SDK をビルド依存関係としてアプリケーションに追加できます。 + +ビルドツールを選択し、手順に従って ScalarDB Cluster Java Client SDK のビルド依存関係をアプリケーションに追加します。 + + + + Gradle を使用して ScalarDB Cluster Java Client SDK のビルド依存関係を追加するには、アプリケーションの `build.gradle` に以下を追加します。 + + ```gradle + dependencies { + implementation 'com.scalar-labs:scalardb-cluster-java-client-sdk:3.14.0' + } + ``` + + + Maven を使用して ScalarDB Cluster Java Client SDK のビルド依存関係を追加するには、アプリケーションの `pom.xml` に以下を追加します。 + + ```xml + + com.scalar-labs + scalardb-cluster-java-client-sdk + 3.14.0 + + ``` + + + +### ScalarDB Cluster Java SDK を構成する + +ScalarDB Cluster Java SDK の構成の詳細については、[クライアント構成](developer-guide-for-scalardb-cluster-with-java-api.mdx#クライアント構成)を参照してください。 + +### Java API を使用する + +Java API の詳細については、[ScalarDB Java API ガイド](../api-guide.mdx)を参照してください。 + +:::note + +非トランザクションストレージ操作には、次の制限が適用されます: + +- トランザクションの開始はサポートされていません。詳細については、[トランザクションを開始または開始せずにトランザクションを実行する](../api-guide.mdx#トランザクションを開始または開始せずにトランザクションを実行する)を参照してください。 +- 1 つのトランザクションで複数のミューテーションを実行することはサポートされていません。 + +::: + +### 詳細 + +- [Javadoc](https://javadoc.io/doc/com.scalar-labs/scalardb/3.14.0/index.html) +- [Java API を使用した ScalarDB Cluster の開発者ガイド](developer-guide-for-scalardb-cluster-with-java-api.mdx) diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/run-non-transactional-storage-operations-through-sql-interface.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/run-non-transactional-storage-operations-through-sql-interface.mdx new file mode 100644 index 00000000..96ac1e68 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/run-non-transactional-storage-operations-through-sql-interface.mdx @@ -0,0 +1,394 @@ +--- +tags: + - Enterprise Premium +--- + +# SQL インターフェースを介して非トランザクションストレージ操作を実行する + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + +このガイドでは、ScalarDB Cluster の SQL インターフェースを通じて非トランザクションストレージ操作を実行する方法について説明します。 + +:::warning + +ScalarDB Cluster のライセンスキー (試用ライセンスまたは商用ライセンス) が必要です。ライセンスキーをお持ちでない場合は、[お問い合わせ](https://www.scalar-labs.com/contact)ください。 + +::: + +## 準備 + +このガイドでは、ScalarDB サンプルリポジトリのサンプルを使用して、データベースと ScalarDB Cluster をスタンドアロンモードでセットアップします。 + +:::note + +スタンドアロンモードの ScalarDB Cluster は、主に開発とテストを目的としています。 + +::: + +### ScalarDB サンプルリポジトリのクローンを作成する + +**ターミナル** を開き、次のコマンドを実行して ScalarDB サンプルリポジトリのクローンを作成します。 + +```console +git clone https://github.com/scalar-labs/scalardb-samples +``` + +次に、次のコマンドを実行して、必要なファイルが含まれているディレクトリに移動します。 + +```console +cd scalardb-samples/scalardb-cluster-standalone-mode +``` + +## データベースをセットアップする + +データベースを選択し、指示に従って ScalarDB Cluster 用に設定します。 + +ScalarDB がサポートするデータベースの一覧については、[データベース](../requirements.mdx#データベース)を参照してください。 + + + +

MySQL をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で MySQL を実行できます。 + + MySQL を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d mysql + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の MySQL のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For MySQL + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:mysql://mysql-1:3306/ + scalar.db.username=root + scalar.db.password=mysql + ``` + + +

PostgreSQL をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で PostgreSQL を実行できます。 + + PostgreSQL を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d postgres + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の PostgreSQL のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For PostgreSQL + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:postgresql://postgres-1:5432/ + scalar.db.username=postgres + scalar.db.password=postgres + ``` + + +

Oracle Database をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で Oracle Database を実行できます。 + + Oracle Database を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d oracle + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の Oracle データベースのプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For Oracle + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:oracle:thin:@//oracle-1:1521/FREEPDB1 + scalar.db.username=SYSTEM + scalar.db.password=Oracle + ``` + + +

SQL Server をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で SQL Server を実行できます。 + + SQL Server を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d sqlserver + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の SQL Server のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For SQL Server + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:sqlserver://sqlserver-1:1433;encrypt=true;trustServerCertificate=true + scalar.db.username=sa + scalar.db.password=SqlServer22 + ``` + + +

Amazon DynamoDB Local を実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で Amazon DynamoDB Local を実行できます。 + + Amazon DynamoDB Local を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d dynamodb + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の Amazon DynamoDB Local のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For DynamoDB Local + scalar.db.storage=dynamo + scalar.db.contact_points=sample + scalar.db.username=sample + scalar.db.password=sample + scalar.db.dynamo.endpoint_override=http://dynamodb-1:8000 + ``` + + + Azure Cosmos DB for NoSQL を使用するには、Azure アカウントが必要です。Azure アカウントがない場合は、[Azure Cosmos DB アカウントを作成する](https://learn.microsoft.com/ja-jp/azure/cosmos-db/nosql/quickstart-portal#create-account)にアクセスしてください。 + +

Cosmos DB for NoSQL を構成する

+ + [既定の整合性レベルを構成する](https://learn.microsoft.com/ja-jp/azure/cosmos-db/nosql/how-to-manage-consistency#configure-the-default-consistency-level)の公式ドキュメントに従って、**既定の整合性レベル** を **強力** に設定します。 + +

ScalarDB Cluster を構成する

+ + 次の手順では、ローカル環境に JDK が適切にインストールおよび構成されており、Azure で Cosmos DB for NoSQL アカウントが適切に構成されていることを前提としています。 + + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。説明に従って、`scalar.db.contact_points` と `scalar.db.password` の値を必ず変更してください。 + + ```properties + # For Cosmos DB + scalar.db.storage=cosmos + scalar.db.contact_points= + scalar.db.password= + ``` + +:::note + +Azure Cosmos DB アカウントのプライマリーキーまたはセカンダリキーを `scalar.db.password` の値として使用できます。 + +::: + + +

Cassandra をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で Apache Cassandra を実行できます。 + + Apache Cassandra を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d cassandra + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の Cassandra のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For Cassandra + scalar.db.storage=cassandra + scalar.db.contact_points=cassandra-1 + scalar.db.username=cassandra + scalar.db.password=cassandra + ``` + + + +ScalarDB の構成の包括的なリストについては、[ScalarDB 構成](configurations.mdx)を参照してください。 + +## スタンドアロンモードで ScalarDB Cluster を設定する + +スタンドアロンモードで ScalarDB Cluster を設定するには、非トランザクションストレージ操作を実行するように ScalarDB Cluster を構成し、ライセンスキーを設定してから、ScalarDB Cluster を起動する必要があります。 + +### 非トランザクションストレージ操作を実行するように ScalarDB Cluster を構成する + +非トランザクションストレージ操作を実行するには、構成ファイル `scalardb-cluster-node.properties` で `scalar.db.transaction_manager` プロパティを `single-crud-operation` に設定する必要があります。 + +```properties +scalar.db.transaction_manager=single-crud-operation +``` + +### ライセンスキーの設定 + +プロパティファイルで ScalarDB Cluster のライセンスキー (試用ライセンスまたは商用ライセンス) を設定します。詳細については、[製品ライセンスキーの設定方法](../scalar-licensing/README.mdx)を参照してください。 + +### スタンドアロンモードで ScalarDB Cluster を起動 + +スタンドアロンモードで ScalarDB Cluster を起動するには、次のコマンドを実行します。 + +:::note + +ScalarDB Cluster のその他の設定を変更する場合は、以下のコマンドを実行する前に `scalardb-cluster-node.properties` ファイルを更新してください。 + +::: + +```console +docker compose up -d scalardb-cluster-node +``` + +## スキーマを作成またはインポートする + +ScalarDB には、実装固有のデータモデルとスキーマにマップされる独自のデータモデルとスキーマがあります。 + +- **データベーススキーマを作成する必要がありますか?** [クラスター用 Schema Loader](developer-guide-for-scalardb-cluster-with-java-api.mdx#クラスター用-schema-loader) を参照してください。 +- **既存のデータベースをインポートする必要がありますか?** [ScalarDB Schema Loader を使用して既存のテーブルを ScalarDB にインポートする](../schema-loader-import.mdx)を参照してください。 + +また、サポートされている DDL のリストについては、[ScalarDB SQL 文法](../scalardb-sql/grammar.mdx)を参照してください。 + +## アプリケーションを作成する + + + +

JDBC アプリケーションを構成する

+ + このセクションでは、ScalarDB JDBC ドライバーをプロジェクトに追加する方法と、Java を使用して非トランザクションストレージ操作を実行するように構成する方法について説明します。 + +

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

+ + Gradle または Maven を使用して、ScalarDB JDBC ドライバーをビルド依存関係としてアプリケーションに追加できます。 + + ビルドツールを選択し、手順に従って ScalarDB JDBC ドライバーのビルド依存関係をアプリケーションに追加します。 + + + + Gradle を使用して ScalarDB JDBC ドライバーのビルド依存関係を追加するには、アプリケーションの `build.gradle` に以下を追加します。 + + ```gradle + dependencies { + implementation 'com.scalar-labs:scalardb-sql-jdbc:3.14.0' + implementation 'com.scalar-labs:scalardb-cluster-java-client-sdk:3.14.0' + } + ``` + + + Maven を使用して ScalarDB SQL API のビルド依存関係を追加するには、アプリケーションの `pom.xml` に以下を追加します。 + + ```xml + + + com.scalar-labs + scalardb-sql-jdbc + 3.14.0 + + + com.scalar-labs + scalardb-cluster-java-client-sdk + 3.14.0 + + + ``` + + + +

SQL インターフェース用に ScalarDB Cluster Java SDK を構成する

+ + SQL インターフェース用に ScalarDB Cluster Java SDK を構成する方法の詳細については、[ScalarDB Cluster SQL クライアント構成](developer-guide-for-scalardb-cluster-with-java-api.mdx#scalardb-cluster-sql-クライアント構成)を参照してください。 + +

JDBC API を使用する

+ + JDBC API の詳細については、[ScalarDB JDBC ガイド](../scalardb-sql/jdbc-guide.mdx)を参照してください。 + +:::note + +非トランザクションストレージ操作には、次の制限が適用されます: + +- トランザクションの開始はサポートされていません。 +- 単一の SQL ステートメントで複数のミューテーションを実行することはサポートされていません。 +- 分離レベルは常に `READ_COMMITTED` です。 + +::: + +

詳細

+ + - [Java API を使用した ScalarDB Cluster の開発者ガイド](developer-guide-for-scalardb-cluster-with-java-api.mdx) + - [Java JDBC API](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) + + +

Java アプリケーションを構成する

+ + このセクションでは、ScalarDB SQL API をプロジェクトに追加する方法と、Java を使用して非トランザクションストレージ操作を実行するように構成する方法について説明します。 + +

ScalarDB SQL API をプロジェクトに追加する

+ + Gradle または Maven を使用して、ScalarDB SQL API をビルド依存関係としてアプリケーションに追加できます。 + + ビルドツールを選択し、手順に従って ScalarDB SQL API のビルド依存関係をアプリケーションに追加します。 + + + + Gradle を使用して ScalarDB SQL API のビルド依存関係を追加するには、アプリケーションの `build.gradle` に以下を追加します。 + + ```gradle + dependencies { + implementation 'com.scalar-labs:scalardb-sql:3.14.0' + implementation 'com.scalar-labs:scalardb-cluster-java-client-sdk:3.14.0' + } + ``` + + + Maven を使用して ScalarDB SQL API のビルド依存関係を追加するには、アプリケーションの `pom.xml` に以下を追加します。 + + ```xml + + + com.scalar-labs + scalardb-sql + 3.14.0 + + + com.scalar-labs + scalardb-cluster-java-client-sdk + 3.14.0 + + + ``` + + + +

SQL インターフェース用に ScalarDB Cluster Java SDK を構成する

+ + SQL インターフェース用に ScalarDB Cluster Java SDK を構成する方法の詳細については、[ScalarDB Cluster SQL クライアント構成](developer-guide-for-scalardb-cluster-with-java-api.mdx#scalardb-cluster-sql-クライアント構成)を参照してください。 + +

Java API を使用する

+ + SQL API の詳細については、[ScalarDB SQL API ガイド](../scalardb-sql/sql-api-guide.mdx)を参照してください。 + +:::note + +非トランザクションストレージ操作には、次の制限が適用されます: + +- トランザクションの開始はサポートされていません。 +- 単一の SQL ステートメントで複数のミューテーションを実行することはサポートされていません。 +- 分離レベルは常に `READ_COMMITTED` です。 + +::: + +

詳細

+ + - [Javadoc](https://javadoc.io/doc/com.scalar-labs/scalardb-sql/3.14.0/index.html) + + + diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/run-transactions-through-scalardb-cluster-sql.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/run-transactions-through-scalardb-cluster-sql.mdx new file mode 100644 index 00000000..94e28102 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/run-transactions-through-scalardb-cluster-sql.mdx @@ -0,0 +1,300 @@ +--- +tags: + - Enterprise Premium +--- + +# ScalarDB Cluster SQL を介してトランザクションを実行する + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + +このガイドでは、ScalarDB プロパティファイルを構成する方法と、ScalarDB Cluster SQL を使用して 1 フェーズまたは 2 フェーズのコミットインターフェイスを介してトランザクションを実行するためのスキーマを作成する方法について説明します。 + +:::warning + +ScalarDB Cluster のライセンスキー (試用ライセンスまたは商用ライセンス) が必要です。ライセンスキーをお持ちでない場合は、[お問い合わせ](https://www.scalar-labs.com/contact)ください。 + +::: + +## 準備 + +このガイドでは、ScalarDB サンプルリポジトリのサンプルを使用して、データベースと ScalarDB Cluster をスタンドアロンモードでセットアップします。 + +:::note + +スタンドアロンモードの ScalarDB Cluster は、主に開発とテストを目的としています。 + +::: + +### ScalarDB サンプルリポジトリのクローンを作成する + +**ターミナル** を開き、次のコマンドを実行して ScalarDB サンプルリポジトリのクローンを作成します。 + +```console +git clone https://github.com/scalar-labs/scalardb-samples +``` + +次に、次のコマンドを実行して、必要なファイルが含まれているディレクトリに移動します。 + +```console +cd scalardb-samples/scalardb-cluster-standalone-mode +``` + +## データベースをセットアップする + +データベースを選択し、指示に従って ScalarDB Cluster 用に設定します。 + +ScalarDB がサポートするデータベースの一覧については、[データベース](../requirements.mdx#データベース)を参照してください。 + + + +

MySQL をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で MySQL を実行できます。 + + MySQL を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d mysql + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の MySQL のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For MySQL + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:mysql://mysql-1:3306/ + scalar.db.username=root + scalar.db.password=mysql + ``` + + +

PostgreSQL をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で PostgreSQL を実行できます。 + + PostgreSQL を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d postgres + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の PostgreSQL のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For PostgreSQL + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:postgresql://postgres-1:5432/ + scalar.db.username=postgres + scalar.db.password=postgres + ``` + + +

Oracle Database をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で Oracle Database を実行できます。 + + Oracle Database を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d oracle + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の Oracle データベースのプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For Oracle + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:oracle:thin:@//oracle-1:1521/FREEPDB1 + scalar.db.username=SYSTEM + scalar.db.password=Oracle + ``` + + +

SQL Server をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で SQL Server を実行できます。 + + SQL Server を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d sqlserver + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の SQL Server のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For SQL Server + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:sqlserver://sqlserver-1:1433;encrypt=true;trustServerCertificate=true + scalar.db.username=sa + scalar.db.password=SqlServer22 + ``` + + +

Amazon DynamoDB Local を実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で Amazon DynamoDB Local を実行できます。 + + Amazon DynamoDB Local を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d dynamodb + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の Amazon DynamoDB Local のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For DynamoDB Local + scalar.db.storage=dynamo + scalar.db.contact_points=sample + scalar.db.username=sample + scalar.db.password=sample + scalar.db.dynamo.endpoint_override=http://dynamodb-1:8000 + ``` + + + Azure Cosmos DB for NoSQL を使用するには、Azure アカウントが必要です。Azure アカウントがない場合は、[Azure Cosmos DB アカウントを作成する](https://learn.microsoft.com/ja-jp/azure/cosmos-db/nosql/quickstart-portal#create-account)にアクセスしてください。 + +

Cosmos DB for NoSQL を構成する

+ + [既定の整合性レベルを構成する](https://learn.microsoft.com/ja-jp/azure/cosmos-db/nosql/how-to-manage-consistency#configure-the-default-consistency-level)の公式ドキュメントに従って、**既定の整合性レベル** を **強力** に設定します。 + +

ScalarDB Cluster を構成する

+ + 次の手順では、ローカル環境に JDK が適切にインストールおよび構成されており、Azure で Cosmos DB for NoSQL アカウントが適切に構成されていることを前提としています。 + + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。説明に従って、`scalar.db.contact_points` と `scalar.db.password` の値を必ず変更してください。 + + ```properties + # For Cosmos DB + scalar.db.storage=cosmos + scalar.db.contact_points= + scalar.db.password= + ``` + +:::note + +Azure Cosmos DB アカウントのプライマリーキーまたはセカンダリキーを `scalar.db.password` の値として使用できます。 + +::: + + +

Cassandra をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で Apache Cassandra を実行できます。 + + Apache Cassandra を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d cassandra + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の Cassandra のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For Cassandra + scalar.db.storage=cassandra + scalar.db.contact_points=cassandra-1 + scalar.db.username=cassandra + scalar.db.password=cassandra + ``` + + + +ScalarDB Cluster SQL の構成の包括的なリストについては、[ScalarDB Cluster SQL クライアント構成](developer-guide-for-scalardb-cluster-with-java-api.mdx#scalardb-cluster-sql-クライアント構成)を参照してください。 + +## スタンドアロンモードで ScalarDB Cluster を設定する + +スタンドアロンモードで ScalarDB Cluster を設定するには、ライセンスキーを設定してから ScalarDB Cluster を起動する必要があります。 + +### ライセンスキーの設定 + +プロパティファイルで ScalarDB Cluster のライセンスキー (試用ライセンスまたは商用ライセンス) を設定します。詳細については、[製品ライセンスキーの設定方法](../scalar-licensing/README.mdx)を参照してください。 + +### スタンドアロンモードで ScalarDB Cluster を起動 + +スタンドアロンモードで ScalarDB Cluster を起動するには、次のコマンドを実行します。 + +:::note + +ScalarDB Cluster のその他の設定を変更する場合は、以下のコマンドを実行する前に `scalardb-cluster-node.properties` ファイルを更新してください。 + +::: + +```console +docker compose up -d scalardb-cluster-node +``` + +## スキーマを作成またはインポートする + +ScalarDB には、実装固有のデータモデルとスキーマにマップされる独自のデータモデルとスキーマがあります。 + +- **データベーススキーマを作成する必要がありますか?** [クラスター用 Schema Loader](developer-guide-for-scalardb-cluster-with-java-api.mdx#クラスター用-schema-loader) を参照してください。 +- **既存のデータベースをインポートする必要がありますか?** [ScalarDB Schema Loader を使用して既存のテーブルを ScalarDB にインポートする](../schema-loader-import.mdx)を参照してください。 + +## トランザクションを実行する + +1 フェーズまたは 2 フェーズのコミットインターフェースを使用してトランザクションを実行できます。トランザクションを実行する方法を選択します。 + + + +

1 フェーズコミットインターフェース

+ + 1 フェーズコミットインターフェースを使用してトランザクションを実行する方法の詳細については、[ScalarDB SQL JDBC ガイド](../scalardb-sql/jdbc-guide.mdx)を参照してください。 + +:::note + +2 フェーズコミットインターフェースでトランザクションを実行する方法に関するドキュメントは近日公開予定です。 + +::: + + +

1 フェーズコミットインターフェース

+ + 1 フェーズコミットインターフェースを使用してトランザクションを実行する方法の詳細については、[ScalarDB SQL API ガイド](../scalardb-sql/sql-api-guide.mdx)を参照してください。 + +:::note + +2 フェーズコミットインターフェースでトランザクションを実行する方法に関するドキュメントは近日公開予定です。 + +::: + +

詳細

+ + ScalarDB Cluster SQL を使用してトランザクションを実行する方法の詳細については、以下を参照してください。 + + - [ScalarDB Cluster SQL gRPC API ガイド](scalardb-cluster-sql-grpc-api-guide.mdx) + + +

1 フェーズまたは 2 フェーズコミットインターフェイス

+ + 1 フェーズまたは 2 フェーズコミットインターフェイスを使用してトランザクションを実行する方法の詳細については、[ScalarDB Cluster .NET Client SDK での LINQ をはじめよう](../scalardb-cluster-dotnet-client-sdk/getting-started-with-linq.mdx#トランザクションの管理)を参照してください。 + + +

1 フェーズコミットインターフェース

+ + 1 フェーズコミットインターフェイスを使用してトランザクションを実行する方法の詳細については、[ScalarDB Cluster .NET Client SDK での分散 SQL トランザクションをはじめよう](../scalardb-cluster-dotnet-client-sdk/getting-started-with-distributed-sql-transactions.mdx)を参照してください。 + +:::note + +2 フェーズコミットインターフェースでトランザクションを実行する方法に関するドキュメントは近日公開予定です。今のところは、[ScalarDB Cluster .NET Client SDK の 2 フェーズコミットインターフェイスを使用した分散トランザクションをはじめよう](../scalardb-cluster-dotnet-client-sdk/getting-started-with-two-phase-commit-transactions.mdx) を参照してください。 + +::: + + diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/run-transactions-through-scalardb-cluster.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/run-transactions-through-scalardb-cluster.mdx new file mode 100644 index 00000000..24475586 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/run-transactions-through-scalardb-cluster.mdx @@ -0,0 +1,299 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster を介してトランザクションを実行する + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + +このガイドでは、ScalarDB プロパティファイルを構成し、ScalarDB Cluster を使用して 1 フェーズまたは 2 フェーズのコミットインターフェイスを介してトランザクションを実行するためのスキーマを作成する方法について説明します。 + +:::warning + +ScalarDB Cluster のライセンスキー (試用ライセンスまたは商用ライセンス) が必要です。ライセンスキーをお持ちでない場合は、[お問い合わせ](https://www.scalar-labs.com/contact)ください。 + +::: + +## 準備 + +このガイドでは、ScalarDB サンプルリポジトリのサンプルを使用して、データベースと ScalarDB Cluster をスタンドアロンモードでセットアップします。 + +:::note + +スタンドアロンモードの ScalarDB Cluster は、主に開発とテストを目的としています。 + +::: + +### ScalarDB サンプルリポジトリのクローンを作成する + +**ターミナル** を開き、次のコマンドを実行して ScalarDB サンプルリポジトリのクローンを作成します。 + +```console +git clone https://github.com/scalar-labs/scalardb-samples +``` + +次に、次のコマンドを実行して、必要なファイルが含まれているディレクトリに移動します。 + +```console +cd scalardb-samples/scalardb-cluster-standalone-mode +``` + +## データベースをセットアップする + +データベースを選択し、指示に従って ScalarDB Cluster 用に設定します。 + +ScalarDB がサポートするデータベースの一覧については、[データベース](../requirements.mdx#データベース)を参照してください。 + + + +

MySQL をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で MySQL を実行できます。 + + MySQL を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d mysql + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の MySQL のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For MySQL + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:mysql://mysql-1:3306/ + scalar.db.username=root + scalar.db.password=mysql + ``` + + +

PostgreSQL をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で PostgreSQL を実行できます。 + + PostgreSQL を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d postgres + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の PostgreSQL のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For PostgreSQL + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:postgresql://postgres-1:5432/ + scalar.db.username=postgres + scalar.db.password=postgres + ``` + + +

Oracle Database をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で Oracle Database を実行できます。 + + Oracle Database を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d oracle + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の Oracle データベースのプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For Oracle + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:oracle:thin:@//oracle-1:1521/FREEPDB1 + scalar.db.username=SYSTEM + scalar.db.password=Oracle + ``` + + +

SQL Server をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で SQL Server を実行できます。 + + SQL Server を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d sqlserver + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の SQL Server のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For SQL Server + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:sqlserver://sqlserver-1:1433;encrypt=true;trustServerCertificate=true + scalar.db.username=sa + scalar.db.password=SqlServer22 + ``` + + +

Amazon DynamoDB Local を実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で Amazon DynamoDB Local を実行できます。 + + Amazon DynamoDB Local を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d dynamodb + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の Amazon DynamoDB Local のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For DynamoDB Local + scalar.db.storage=dynamo + scalar.db.contact_points=sample + scalar.db.username=sample + scalar.db.password=sample + scalar.db.dynamo.endpoint_override=http://dynamodb-1:8000 + ``` + + + Azure Cosmos DB for NoSQL を使用するには、Azure アカウントが必要です。Azure アカウントがない場合は、[Azure Cosmos DB アカウントを作成する](https://learn.microsoft.com/ja-jp/azure/cosmos-db/nosql/quickstart-portal#create-account)にアクセスしてください。 + +

Cosmos DB for NoSQL を構成する

+ + [既定の整合性レベルを構成する](https://learn.microsoft.com/ja-jp/azure/cosmos-db/nosql/how-to-manage-consistency#configure-the-default-consistency-level)の公式ドキュメントに従って、**既定の整合性レベル** を **強力** に設定します。 + +

ScalarDB Cluster を構成する

+ + 次の手順では、ローカル環境に JDK が適切にインストールおよび構成されており、Azure で Cosmos DB for NoSQL アカウントが適切に構成されていることを前提としています。 + + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。説明に従って、`scalar.db.contact_points` と `scalar.db.password` の値を必ず変更してください。 + + ```properties + # For Cosmos DB + scalar.db.storage=cosmos + scalar.db.contact_points= + scalar.db.password= + ``` + +:::note + +Azure Cosmos DB アカウントのプライマリーキーまたはセカンダリキーを `scalar.db.password` の値として使用できます。 + +::: + + +

Cassandra をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で Apache Cassandra を実行できます。 + + Apache Cassandra を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d cassandra + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の Cassandra のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For Cassandra + scalar.db.storage=cassandra + scalar.db.contact_points=cassandra-1 + scalar.db.username=cassandra + scalar.db.password=cassandra + ``` + + + +ScalarDB Cluster の構成の包括的なリストについては、[ScalarDB Cluster の構成](developer-guide-for-scalardb-cluster-with-java-api.mdx#scalardb-cluster-sql-クライアント構成) を参照してください。 + +## スタンドアロンモードで ScalarDB Cluster を設定する + +スタンドアロンモードで ScalarDB Cluster を設定するには、ライセンスキーを設定してから ScalarDB Cluster を起動する必要があります。 + +### ライセンスキーの設定 + +プロパティファイルで ScalarDB Cluster のライセンスキー (試用ライセンスまたは商用ライセンス) を設定します。詳細については、[製品ライセンスキーの設定方法](../scalar-licensing/README.mdx)を参照してください。 + +### スタンドアロンモードで ScalarDB Cluster を起動 + +スタンドアロンモードで ScalarDB Cluster を起動するには、次のコマンドを実行します。 + +:::note + +ScalarDB Cluster のその他の設定を変更する場合は、以下のコマンドを実行する前に `scalardb-cluster-node.properties` ファイルを更新してください。 + +::: + +```console +docker compose up -d scalardb-cluster-node +``` + +## スキーマを作成またはインポートする + +ScalarDB には、実装固有のデータモデルとスキーマにマップされる独自のデータモデルとスキーマがあります。 + +- **データベーススキーマを作成する必要がありますか?** [ScalarDB Schema Loader](../schema-loader.mdx) を参照してください。 +- **既存のデータベースをインポートする必要がありますか?** [ScalarDB Schema Loader を使用して既存のテーブルを ScalarDB にインポートする](../schema-loader-import.mdx)を参照してください。 + +## トランザクションを実行する + +1 フェーズまたは 2 フェーズのコミットインターフェースを使用してトランザクションを実行できます。トランザクションを実行する方法を選択します。 + + + +

1 フェーズコミットインターフェース

+ + 1 フェーズコミットインターフェイスを使用してトランザクションを実行する方法の詳細については、[ScalarDB Java API ガイド](../api-guide.mdx#transactional-api)を参照してください。 + +:::note + +1 フェーズコミットインターフェースを使用してトランザクションを実行するには、次のサンプルチュートリアルを参照してください。 + +- [マルチストレージトランザクションをサポートするサンプルアプリケーションを作成する](../scalardb-samples/multi-storage-transaction-sample/README.mdx) +- [マルチストレージトランザクションを備えた Spring Data JDBC for ScalarDB のサンプルアプリケーション](../scalardb-samples/spring-data-multi-storage-transaction-sample/README.mdx) + +::: + +

2 フェーズコミットインターフェース

+ + 2 フェーズコミットインターフェイスを使用してトランザクションを実行する方法の詳細については、[2 フェーズコミットインターフェイスを使用したトランザクション](../two-phase-commit-transactions.mdx)を参照してください。 + +:::note + +2 フェーズコミットインターフェースを使用してトランザクションを実行するには、次のサンプルチュートリアルを参照してください。 + +- [マイクロサービストランザクションをサポートするサンプルアプリケーションを作成する](../scalardb-samples/microservice-transaction-sample/README.mdx) +- [マイクロサービストランザクションを使用した Spring Data JDBC for ScalarDB のサンプルアプリケーション](../scalardb-samples/spring-data-microservice-transaction-sample/README.mdx) + +::: + +

詳細

+ + ScalarDB Cluster を使用してトランザクションを実行する方法の詳細については、以下を参照してください。 + + - [ScalarDB Cluster gRPC API ガイド](scalardb-cluster-grpc-api-guide.mdx) + + +

1 フェーズコミットインターフェース

+ + 1 フェーズコミットインターフェイスを使用してトランザクションを実行する方法の詳細については、[ScalarDB Cluster .NET Client SDK での分散トランザクションをはじめよう](../scalardb-cluster-dotnet-client-sdk/getting-started-with-distributed-transactions.mdx)を参照してください。 + +

2 フェーズコミットインターフェース

+ + 2 フェーズコミットインターフェイスを使用してトランザクションを実行する方法の詳細については、[ScalarDB Cluster .NET Client SDK の 2 フェーズコミットインターフェイスを使用した分散トランザクションをはじめよう](../scalardb-cluster-dotnet-client-sdk/getting-started-with-two-phase-commit-transactions.mdx)を参照してください。 + + diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/scalardb-auth-status-codes.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/scalardb-auth-status-codes.mdx new file mode 100644 index 00000000..f1d28a0c --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/scalardb-auth-status-codes.mdx @@ -0,0 +1,304 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# 認証および認可エラーコード + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このページでは、認証および認可に関連するエラーコードの一覧を示します。 + +## エラーコードのクラスと説明 + +| クラス | 説明 | +|:-------------|:--------------------------| +| `AUTH-1xxxx` | ユーザーエラーカテゴリのエラー | +| `AUTH-3xxxx` | 内部エラーカテゴリのエラー | + +## `AUTH-1xxxx` ステータスコード + +### `AUTH-10000` + +**メッセージ** + +```markdown +The user already exists. Username: %s +``` + +### `AUTH-10001` + +**メッセージ** + +```markdown +The user does not exist. Username: %s +``` + +### `AUTH-10003` + +**メッセージ** + +```markdown +The namespace does not exist. Namespace: %s +``` + +### `AUTH-10004` + +**メッセージ** + +```markdown +The table does not exist. Table: %s +``` + +### `AUTH-10005` + +**メッセージ** + +```markdown +Invalid username or password +``` + +### `AUTH-10006` + +**メッセージ** + +```markdown +Access denied: Invalid auth token +``` + +### `AUTH-10007` + +**メッセージ** + +```markdown +Access denied: You need the %s privilege on the namespace %s to execute this operation +``` + +### `AUTH-10008` + +**メッセージ** + +```markdown +Access denied: You need the %s privilege on the table %s to execute this operation +``` + +### `AUTH-10009` + +**メッセージ** + +```markdown +Access denied: You can't grant the %s privilege because you don't have the same privilege on the table %s +``` + +### `AUTH-10010` + +**メッセージ** + +```markdown +Access denied: You can't access information about the user %s +``` + +### `AUTH-10011` + +**メッセージ** + +```markdown +Access denied: You can't alter the user %s +``` + +### `AUTH-10012` + +**メッセージ** + +```markdown +Access denied: You must be a superuser to change the SUPERUSER attribute +``` + +### `AUTH-10013` + +**メッセージ** + +```markdown +You can't change the SUPERUSER attribute for the current user %s +``` + +### `AUTH-10014` + +**メッセージ** + +```markdown +You can't drop the current user %s +``` + +### `AUTH-10015` + +**メッセージ** + +```markdown +Access denied: You can't grant the %s privilege because you don't have the same privilege for the table %s +``` + +### `AUTH-10016` + +**メッセージ** + +```markdown +Access denied: You can't grant the %s privilege because you don't have the same privilege on the namespace %s +``` + +### `AUTH-10017` + +**メッセージ** + +```markdown +Access denied: You can't revoke the %s privilege because you don't have the same privilege on the table %s +``` + +### `AUTH-10018` + +**メッセージ** + +```markdown +Access denied: You can't revoke the %s privilege because you don't have the same privilege on the namespace %s +``` + +### `AUTH-10019` + +**メッセージ** + +```markdown +The operation does not have the target namespace or table name. Operation: %s +``` + +## `AUTH-3xxxx` ステータスコード + +### `AUTH-30000` + +**メッセージ** + +```markdown +Getting auth token information failed +``` + +### `AUTH-30001` + +**メッセージ** + +```markdown +Getting the user failed. Username: %s +``` + +### `AUTH-30002` + +**メッセージ** + +```markdown +Creating a user failed. Username: %s +``` + +### `AUTH-30003` + +**メッセージ** + +```markdown +Altering the user failed. Username: %s +``` + +### `AUTH-30004` + +**メッセージ** + +```markdown +Dropping the user failed. Username: %s +``` + +### `AUTH-30005` + +**メッセージ** + +```markdown +Granting privileges failed. Username: %s; Namespace: %s; Privileges: %s +``` + +### `AUTH-30006` + +**メッセージ** + +```markdown +Granting privileges failed. Username: %s; Table: %s; Privileges: %s +``` + +### `AUTH-30007` + +**メッセージ** + +```markdown +Revoking privileges failed. Username: %s; Namespace: %s; Privileges: %s +``` + +### `AUTH-30008` + +**メッセージ** + +```markdown +Revoking privileges failed. Username: %s; Table: %s; Privileges: %s +``` + +### `AUTH-30009` + +**メッセージ** + +```markdown +Getting users failed +``` + +### `AUTH-30010` + +**メッセージ** + +```markdown +Getting privileges failed. Username: %s; Namespace: %s +``` + +### `AUTH-30011` + +**メッセージ** + +```markdown +Getting privileges failed. Username: %s; Table: %s +``` + +### `AUTH-30012` + +**メッセージ** + +```markdown +Deleting privileges failed. Namespace: %s +``` + +### `AUTH-30013` + +**メッセージ** + +```markdown +Deleting privileges failed. Table: %s +``` + +### `AUTH-30014` + +**メッセージ** + +```markdown +Logging in failed. Username: %s +``` + +### `AUTH-30015` + +**メッセージ** + +```markdown +Logging out failed +``` diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/scalardb-auth-with-sql.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/scalardb-auth-with-sql.mdx new file mode 100644 index 00000000..ff6160a6 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/scalardb-auth-with-sql.mdx @@ -0,0 +1,361 @@ +--- +tags: + - Enterprise Premium +--- + +# ユーザーの認証と認可 + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; +import WarningLicenseKeyContact from '/src/components/en-us/_warning-license-key-contact.mdx'; + + + +ScalarDB Cluster には、ユーザーを認証および認可するメカニズムがあります。 + +このガイドでは、ScalarDB Cluster で認証と認可を使用する方法について説明します。 + +## 概要 + +認証と認可を使用することで、ユーザーを作成し、その権限を付与または取り消すことができます。`CREATE USER` コマンドを使用してユーザーを作成し、`GRANT` コマンドまたは `REVOKE` コマンドを使用して、それぞれテーブルまたは名前空間に対する権限を付与または取り消すことができます。このようなデータ制御言語 (DCL) コマンドの詳細については、[DCL](../scalardb-sql/grammar.mdx#dcl) を参照してください。 + +ユーザーは、必要な権限を持っている場合、ユーザー名とパスワードを使用して ScalarDB Cluster にログインし、SQL ステートメントを実行できます。 + +認証と認可では、次の 2 種類のユーザーがサポートされます。 + +- **スーパーユーザー:** このタイプのユーザーにはすべての権限があります。スーパーユーザーのみが他のユーザーや名前空間を作成または削除できます。 +- **通常のユーザー:** このタイプのユーザーには最初は権限がないため、スーパーユーザーまたは `GRANT` 権限を持つ別のユーザーによって権限を付与する必要があります。 + +認証と認可を使用する場合、次の権限が利用できます。 + +- `SELECT` +- `INSERT` +- `UPDATE` +- `DELETE` +- `CREATE` +- `DROP` +- `TRUNCATE` +- `ALTER` +- `GRANT` + +権限の詳細については、[各タイプの操作に必要な権限](#各タイプの操作に必要な権限)を参照してください。 + +## 構成 + +このセクションでは、認証と認可に使用できる構成について説明します。 + +### ScalarDB Cluster ノードの構成 + +認証と認可を有効にするには、`scalar.db.cluster.auth.enabled` を `true` に設定する必要があります。 + +| 名前 | 説明 | デフォルト | +|----------------------------------|-----------------------------|-----------| +| `scalar.db.cluster.auth.enabled` | 認証と認可が有効かどうか。 | `false` | + +次の構成を設定することもできます。 + +| 名前 | 説明 | デフォルト | +|----------------------------------------------------------------|---------------------------------------------------------------------------------------------------|-----------------| +| `scalar.db.cluster.auth.cache_expiration_time_millis` | 認証および認可情報のキャッシュ有効期限（ミリ秒単位）。 | `60000` (1 分) | +| `scalar.db.cluster.auth.auth_token_expiration_time_minutes` | 認証および認可トークンの有効期限（分単位）。 | `1440` (1 日) | +| `scalar.db.cluster.auth.auth_token_gc_thread_interval_minutes` | 認証および認可トークンのガベージコレクション (GC) スレッド間隔 (分単位)。 | 360（6 時間） | +| `scalar.db.cluster.auth.pepper` | ハッシュ化の前にパスワードに追加されるシークレットの値。指定しない場合、パスワードはペッパーなしでハッシュ化されます。 | | + +:::note + +認証と認可を有効にする場合は、認証と認可によって内部的にパーティション間スキャンが実行されるため、システム名前空間 (デフォルトでは `scalardb`) の `scalar.db.cross_partition_scan.enabled` を `true` に設定する必要もあります。 + +::: + +### ScalarDB Cluster Java Client SDK 構成 + +クライアント側で認証と認可を有効にするには、`scalar.db.cluster.auth.enabled` を `true` に設定する必要があります。 + +| 名前 | 説明 | デフォルト | +|----------------------------------|------------------------|----------| +| `scalar.db.cluster.auth.enabled` | 認証と認可が有効かどうか。 | `false` | + +[ScalarDB Cluster SQL クライアント構成](developer-guide-for-scalardb-cluster-with-java-api.mdx#scalardb-cluster-sql-クライアント構成) セクションの構成に加えて、クライアントのユーザー名とパスワードを指定するために `scalar.db.sql.cluster_mode.username` と `scalar.db.sql.cluster_mode.password` も設定する必要があります。 + +| 名前 | 説明 | デフォルト | +|---------------------------------------|-----------------------------|---------| +| `scalar.db.sql.cluster_mode.username` | クライアントのユーザー名。 | | +| `scalar.db.sql.cluster_mode.password` | クライアントのパスワード。 | | + +## 初期ユーザー + +認証と認可を有効にすると、初期ユーザー `admin` が作成され、そのユーザーの初期パスワードは `admin` になります。このユーザーはスーパーユーザーであり、すべての権限を持ちます。このユーザーでログインし、必要に応じて他のユーザーを作成できます。 + +:::warning + +セキュリティ上の理由から、特に実稼働環境にデプロイする前に、初期ユーザーのパスワードを必ず変更してください。 + +::: + +## 各タイプの操作に必要な権限 + +次の表は、各タイプの操作に必要な権限を示しています。 + +### DDL + +| コマンド | スーパーユーザーが必要です | 必要な権限 | +|-------------------------------|-----------------------|---------------------| +| `CREATE NAMESPACE` | `true` | | +| `DROP NAMESPACE` | `true` | | +| `CREATE TABLE` | | `CREATE` | +| `DROP TABLE` | | `DROP` | +| `CREATE INDEX` | | `CREATE` | +| `DROP INDEX` | | `DROP` | +| `TRUNCATE TABLE` | | `TRUNCATE` | +| `ALTER TABLE` | | `ALTER` | +| `CREATE COORDINATOR TABLES` | `true` | | +| `DROP COORDINATOR TABLES` | `true` | | +| `TRUNCATE COORDINATOR TABLES` | `true` | | + +### DML + +| コマンド | スーパーユーザーが必要です | 必要な権限 | +|----------|------------------------|----------------------| +| `SELECT` | | `SELECT` | +| `INSERT` | | `INSERT` | +| `UPSERT` | | `INSERT` | +| `UPDATE` | | `SELECT` と `UPDATE` | +| `DELETE` | | `SELECT` と `DELETE` | + +### DCL + +| コマンド | スーパーユーザーが必要です | 必要な権限 | +|---------------|---------------------------------------------|-------------------------------------------------------------| +| `CREATE USER` | `true` | | +| `ALTER USER` | `true` (ユーザーは自分のパスワードを変更できます。) | | +| `DROP USER` | `true` | | +| `GRANT` | | `GRANT` (ユーザーは自分が持っている権限のみを付与できます。) | +| `REVOKE` | | `GRANT` (ユーザーは自分が持っている権限のみを取り消すことができます。) | + +## 制限事項 + +認証と認可で付与または取り消される権限には、いくつかの制限があります: + +- `INSERT` 権限と `UPDATE` 権限は、一緒に付与または取り消す必要があります。 +- ユーザーに `UPDATE` 権限または `DELETE` 権限を付与するには、対象ユーザーに `SELECT` 権限が必要です。 +- 対象ユーザーに `INSERT` 権限または `UPDATE` 権限がある場合、そのユーザーから `SELECT` 権限を取り消すことはできません。 + +## ワイヤ暗号化 + +認証と認可を有効にする場合は、ユーザー資格情報を保護するために、本番環境でワイヤ暗号化を有効にすることを強くお勧めします。ワイヤ暗号化の詳細については、[ScalarDB Cluster ワイヤ暗号化](encrypt-wire-communications.mdx)を参照してください。 + +## チュートリアル - ユーザーの認証と認可 + +このチュートリアルでは、認証と認可の使用方法を説明します。 + + + +### 1. ScalarDB Cluster 設定ファイルを作成する + +次の設定ファイルを `scalardb-cluster-node.properties` として作成し、`` と `` を ScalarDB ライセンスキーとライセンスチェック証明書の値に置き換えます。ライセンスキーと証明書の詳細については、[製品ライセンスキーの設定方法](../scalar-licensing/README.mdx)を参照してください。 + +```properties +scalar.db.storage=jdbc +scalar.db.contact_points=jdbc:postgresql://postgresql:5432/postgres +scalar.db.username=postgres +scalar.db.password=postgres +scalar.db.cluster.node.standalone_mode.enabled=true +scalar.db.cross_partition_scan.enabled=true +scalar.db.sql.enabled=true + +# Enable authentication and authorization +scalar.db.cluster.auth.enabled=true + +# License key configurations +scalar.db.cluster.node.licensing.license_key= +scalar.db.cluster.node.licensing.license_check_cert_pem= +``` + +### 2. Docker Compose ファイルを作成する + +次の設定ファイルを `docker-compose.yaml` として作成します。 + +```yaml +services: + postgresql: + container_name: "postgresql" + image: "postgres:15" + ports: + - 5432:5432 + environment: + - POSTGRES_PASSWORD=postgres + healthcheck: + test: ["CMD-SHELL", "pg_isready || exit 1"] + interval: 1s + timeout: 10s + retries: 60 + start_period: 30s + + scalardb-cluster-standalone: + container_name: "scalardb-cluser-node" + image: "ghcr.io/scalar-labs/scalardb-cluster-node-byol-premium:3.14.0" + ports: + - 60053:60053 + - 9080:9080 + volumes: + - ./scalardb-cluster-node.properties:/scalardb-cluster/node/scalardb-cluster-node.properties + depends_on: + postgresql: + condition: service_healthy +``` + +### 3. PostgreSQL と ScalarDB Cluster を起動します + +次のコマンドを実行して、PostgreSQL と ScalarDB Cluster をスタンドアロンモードで起動します。 + +```console +docker compose up -d +``` + +### 4. ScalarDB Cluster に接続する + +ScalarDB Cluster に接続するために、このチュートリアルでは、ScalarDB Cluster に接続して SQL クエリを実行するツールである SQL CLI を使用します。SQL CLI は、[ScalarDB Releases ページ](https://github.com/scalar-labs/scalardb/releases)からダウンロードできます。 + +`scalardb-cluster-sql-cli.properties` という名前の設定ファイルを作成します。このファイルは、SQL CLI を使用して ScalarDB Cluster に接続するために使用されます。 + +```properties +scalar.db.sql.connection_mode=cluster +scalar.db.sql.cluster_mode.contact_points=indirect:localhost + +# Enable authentication and authorization +scalar.db.cluster.auth.enabled=true +``` + +次に、次のコマンドを実行して SQL CLI を起動します。 + +```console +java -jar scalardb-cluster-sql-cli-3.14.0-all.jar --config scalardb-cluster-sql-cli.properties +``` + +ユーザー名とパスワードをそれぞれ `admin` と `admin` と入力します。 + +これで、ScalarDB Cluster で認証と認可を有効にしてデータベースを使用する準備が整いました。 + +### 5. 名前空間とテーブルを作成する + +名前空間を作成します。 + +```sql +CREATE NAMESPACE ns1; + +CREATE NAMESPACE ns2; +``` + +次に、`ns1` 名前空間にテーブルを作成します。 + +```sql +CREATE TABLE ns1.tbl ( + id INT PRIMARY KEY, + col1 TEXT, + col2 INT); +``` + +### 6. ユーザーを作成する + +`user1` という名前のユーザーを作成します。 + +```sql +CREATE USER user1 WITH PASSWORD 'user1'; +``` + +ユーザーを確認するには、次のコマンドを実行します。 + +```sql +SHOW USERS; +``` + +```console ++----------+-------------+ +| username | isSuperuser | ++----------+-------------+ +| user1 | false | +| admin | true | ++----------+-------------+ +``` + +`user1` ユーザーが作成されたことがわかります。 + +### 7. 権限の付与 + +`ns1.tbl` テーブルで `user1` に `SELECT`、`INSERT`、および `UPDATE` 権限を付与します。 + +```sql +GRANT SELECT, INSERT, UPDATE ON ns1.tbl TO user1; +``` + +次に、`ns2` 名前空間の `user1` に `SELECT` 権限を付与します。 + +```sql +GRANT SELECT ON NAMESPACE ns2 TO user1; +``` + +権限を確認するには、次のコマンドを実行します。 + +```sql +SHOW GRANTS FOR user1; +``` + +```console ++---------+-----------+-----------+ +| name | type | privilege | ++---------+-----------+-----------+ +| ns2 | NAMESPACE | SELECT | +| ns1.tbl | TABLE | SELECT | +| ns1.tbl | TABLE | INSERT | +| ns1.tbl | TABLE | UPDATE | ++---------+-----------+-----------+ +``` + +`user1` に `ns.tbl` テーブルに対する `SELECT`、`INSERT`、`UPDATE` 権限と、`ns2` 名前空間に対する `SELECT` 権限が付与されていることがわかります。 + +### 8. `user1` としてログインする + +`user1` としてログインし、SQL ステートメントを実行します。 + +```console +java -jar scalardb-cluster-sql-cli-3.14.0-all.jar --config scalardb-cluster-sql-cli.properties +``` + +ユーザー名とパスワードをそれぞれ `user1` と `user1` として入力します。 + +これで、`user1` として SQL ステートメントを実行できます。 + +### 9. DML ステートメントを実行する + +`user1` として次の `INSERT` ステートメントを実行します。 + +```sql +INSERT INTO ns1.tbl VALUES (1, 'a', 1); +``` + +次に、`user1` として次の `SELECT` ステートメントを実行します。 + +```sql +SELECT * FROM ns1.tbl; +``` + +```console ++----+------+------+ +| id | col1 | col2 | ++----+------+------+ +| 1 | a | 1 | ++----+------+------+ +``` + +`user1` が `INSERT` および `SELECT` ステートメントを実行できることがわかります。 + +次に、`user1` として次の `DELETE` ステートメントを実行してみてください。 + +```sql +DELETE FROM ns1.tbl WHERE id = 1; +``` + +```console +Error: Authorization error (PERMISSION_DENIED: SQL-10021: Access denied: You need the DELETE privilege on the table ns1.tbl to execute this operation) (state=SDB11,code=9911) +``` + +`user1` には `ns1.tbl` テーブルに対する `DELETE` 権限がないため、上記のエラーメッセージが表示されます。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/scalardb-cluster-configurations.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/scalardb-cluster-configurations.mdx new file mode 100644 index 00000000..d525d7f0 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/scalardb-cluster-configurations.mdx @@ -0,0 +1,242 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster の構成 + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + +このドキュメントでは、ScalarDB Cluster の構成について説明します。ScalarDB Cluster は複数のクラスターノードで構成されており、各クラスターノードを構成する必要があります。 + +## 基本構成 + +クラスターノードの基本構成は次のとおりです。 + +| 名前 | 説明 | デフォルト | +|-------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|----------------| +| `scalar.db.cluster.membership.type` | メンバーシップの種類。現在、`KUBERNETES` のみ指定できます。 | `KUBERNETES` | +| `scalar.db.cluster.membership.kubernetes.endpoint.namespace_name` | この構成は、`KUBERNETES` メンバーシップタイプ用です。[endpoint resource](https://kubernetes.io/docs/concepts/services-networking/service/#endpoints) の名前空間名。 | `default` | +| `scalar.db.cluster.membership.kubernetes.endpoint.name` | この構成は、`KUBERNETES` メンバーシップタイプ用です。メンバーシップ情報を取得するための [endpoint resource](https://kubernetes.io/docs/concepts/services-networking/service/#endpoints) の名前。 | | +| `scalar.db.cluster.node.decommissioning_duration_secs` | 廃止期間（秒単位）。 | `30` | +| `scalar.db.cluster.node.grpc.max_inbound_message_size` | 受信可能な最大メッセージサイズ。 | gRPCのデフォルト値 | +| `scalar.db.cluster.node.grpc.max_inbound_metadata_size` | 受信できるメタデータの最大サイズ。 | gRPCのデフォルト値 | +| `scalar.db.cluster.node.port` | ScalarDB Cluster ノードのポート番号。 | `60053` | +| `scalar.db.cluster.node.prometheus_exporter_port` | Prometheus エクスポーターのポート番号。 | `9080` | +| `scalar.db.cluster.grpc.deadline_duration_millis` | gRPC の期限期間（ミリ秒単位）。 | `60000` (60 秒) | +| `scalar.db.cluster.node.standalone_mode.enabled` | スタンドアロンモードが有効かどうか。スタンドアロンモードが有効になっている場合、メンバーシップ構成 (`scalar.db.cluster.membership.*`) は無視されることに注意してください。 | `false` | +| `scalar.db.metadata.cache_expiration_time_secs` | ScalarDB には、データベースへのリクエスト数を減らすためのメタデータキャッシュがあります。この設定では、キャッシュの有効期限を秒単位で指定します。`-1`を指定した場合は、キャッシュは期限切れになりません。 | `60` | +| `scalar.db.active_transaction_management.expiration_time_millis` | ScalarDB Cluster ノードは進行中のトランザクションを維持し、トランザクション ID を使用して再開できます。この構成では、このトランザクション管理機能の有効期限をミリ秒単位で指定します。 | `60000` (60 秒) | +| `scalar.db.system_namespace_name` | 指定された名前空間名は ScalarDB によって内部的に使用されます。 | `scalardb` | + +## トランザクションマネージャーの構成 + +このセクションでは、トランザクションマネージャーの構成について説明します。ScalarDB は、コンセンサスコミットを使用してトランザクションを実行する方法と、非トランザクションストレージ操作を実行する方法を提供します。 + +### コンセンサスコミットを使用してトランザクションを実行する + +ScalarDB は、コンセンサスコミットと呼ばれる独自のトランザクションプロトコルを提供します。これは、ScalarDB のデフォルトのトランザクションマネージャータイプです。コンセンサスコミットトランザクションマネージャーを使用するには、ScalarDB プロパティファイルに次の内容を追加します。 + +```properties +scalar.db.transaction_manager=consensus-commit +``` + +:::note + +`scalar.db.transaction_manager` プロパティを指定しない場合は、`consensus-commit` がデフォルト値になります。 + +::: + +#### 基本設定 + +コンセンサスコミットトランザクションマネージャーでは、次の基本設定が利用可能です。 + +| 名前 | 説明 | デフォルト | +|-------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------| +| `scalar.db.transaction_manager` | `consensus-commit` を指定する必要があります。 | - | +| `scalar.db.consensus_commit.isolation_level` | コンセンサスコミットに使用される分離レベル。`SNAPSHOT` または `SERIALIZABLE` のいずれかを指定できます。 | `SNAPSHOT` | +| `scalar.db.consensus_commit.serializable_strategy` | コンセンサスコミットに使用されるシリアル化可能な戦略。`EXTRA_READ` または `EXTRA_WRITE` のいずれかを指定できます。`scalar.db.consensus_commit.isolation_level` プロパティで `SNAPSHOT` が指定されている場合、この構成は無視されます。 | `EXTRA_READ` | +| `scalar.db.consensus_commit.coordinator.namespace` | コーディネーターテーブルの名前空間名。 | `coordinator` | +| `scalar.db.consensus_commit.include_metadata.enabled` | `true` に設定すると、`Get` および `Scan` 操作の結果にトランザクションメタデータが含まれます。特定のテーブルのトランザクションメタデータ列の詳細を表示するには、`DistributedTransactionAdmin.getTableMetadata()` メソッドを使用します。このメソッドは、トランザクションメタデータ列が追加されたテーブルメタデータを返します。この構成を使用すると、トランザクション関連の問題を調査するのに役立ちます。 | `false` | + +#### パフォーマンス関連の構成 + +コンセンサスコミットトランザクションマネージャーでは、次のパフォーマンス関連の構成が利用できます。 + +| 名前 | 説明 | デフォルト | +|----------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------| +| `scalar.db.consensus_commit.parallel_executor_count` | 並列実行のためのエグゼキュータ（スレッド）の数。 | `128` | +| `scalar.db.consensus_commit.parallel_preparation.enabled` | 準備フェーズが並行して実行されるかどうか。 | `true` | +| `scalar.db.consensus_commit.parallel_validation.enabled` | 検証フェーズ (`EXTRA_READ` 内) が並列で実行されるかどうか。 | `scalar.db.consensus_commit.parallel_commit.enabled` の値 | +| `scalar.db.consensus_commit.parallel_commit.enabled` | コミットフェーズが並列で実行されるかどうか。 | `true` | +| `scalar.db.consensus_commit.parallel_rollback.enabled` | ロールバックフェーズが並列で実行されるかどうか。 | `scalar.db.consensus_commit.parallel_commit.enabled` の値 | +| `scalar.db.consensus_commit.async_commit.enabled` | コミットフェーズが非同期で実行されるかどうか。 | `false` | +| `scalar.db.consensus_commit.async_rollback.enabled` | ロールバックフェーズが非同期に実行されるかどうか。 | `scalar.db.consensus_commit.async_commit.enabled` の値 | +| `scalar.db.consensus_commit.parallel_implicit_pre_read.enabled` | 暗黙的な事前読み取りが並列で実行されるかどうか。 | `true` | +| `scalar.db.consensus_commit.coordinator.group_commit.enabled` | トランザクション状態のコミットがバッチモードで実行されるかどうか。この機能は、2 フェーズコミットインターフェイスでは使用できません。 | `false` | +| `scalar.db.consensus_commit.coordinator.group_commit.slot_capacity` | グループコミット機能のグループ内のスロットの最大数。値が大きいとグループコミットの効率は向上しますが、待ち時間が増加し、トランザクションの競合が発生する可能性も高くなります。[^1] | `20` | +| `scalar.db.consensus_commit.coordinator.group_commit.group_size_fix_timeout_millis` | グループ内のスロットのサイズを固定するためのタイムアウト。値が大きいとグループコミットの効率が向上しますが、待ち時間が増加し、トランザクションの競合が発生する可能性も高くなります。[^1] | `40` | +| `scalar.db.consensus_commit.coordinator.group_commit.delayed_slot_move_timeout_millis` | 遅延スロットをグループから別の分離グループに移動して、元のグループが遅延トランザクションの影響を受けないようにするためのタイムアウト。値が大きいとグループコミットの効率が向上しますが、待ち時間が増加し、トランザクションの競合が発生する可能性も高くなります。[^1] | `1200` | +| `scalar.db.consensus_commit.coordinator.group_commit.old_group_abort_timeout_millis` | 進行中の古いグループをアボートするためのタイムアウト。値が小さいと、積極的なアボートによってリソースの消費量が減りますが、長時間実行されるトランザクションで不要なアボートが発生する可能性も高くなります。 | `60000` | +| `scalar.db.consensus_commit.coordinator.group_commit.timeout_check_interval_millis` | グループコミット関連のタイムアウトをチェックする間隔。 | `20` | +| `scalar.db.consensus_commit.coordinator.group_commit.metrics_monitor_log_enabled` | グループコミットのメトリックが定期的にログに記録されるかどうか。 | `false` | + +#### 基盤となるストレージまたはデータベースの構成 + +Consensus Commit にはストレージ抽象化レイヤーがあり、複数の基盤となるストレージをサポートしています。`scalar.db.storage` プロパティを使用してストレージ実装を指定できます。 + +データベースを選択して、各ストレージで使用可能な構成を確認します。 + + + + JDBC データベースでは次の構成を使用できます。 + + | 名前 | 説明 | デフォルト | + |-----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------| + | `scalar.db.storage` | `jdbc` を指定する必要があります。 | - | + | `scalar.db.contact_points` | JDBC 接続 URL。 | | + | `scalar.db.username` | データベースにアクセスするためのユーザー名。 | | + | `scalar.db.password` | データベースにアクセスするためのパスワード。 | | + | `scalar.db.jdbc.connection_pool.min_idle` | 接続プール内のアイドル接続の最小数。 | `20` | + | `scalar.db.jdbc.connection_pool.max_idle` | 接続プール内でアイドル状態のままにできる接続の最大数。 | `50` | + | `scalar.db.jdbc.connection_pool.max_total` | 接続プールで同時にアクティブにできるアイドル接続と借用接続の最大合計数。制限がない場合は負の値を使用します。 | `100` | + | `scalar.db.jdbc.prepared_statements_pool.enabled` | このプロパティを `true` に設定すると、準備されたステートメントのプールが有効になります。 | `false` | + | `scalar.db.jdbc.prepared_statements_pool.max_open` | ステートメントプールから同時に割り当てることができるオープンステートメントの最大数。制限がない場合は負の値を使用します。 | `-1` | + | `scalar.db.jdbc.isolation_level` | JDBC の分離レベル。`READ_UNCOMMITTED`、`READ_COMMITTED`、`REPEATABLE_READ`、または `SERIALIZABLE` を指定できます。 | 基盤データベース固有 | + | `scalar.db.jdbc.table_metadata.connection_pool.min_idle` | テーブルメタデータの接続プール内のアイドル接続の最小数。 | `5` | + | `scalar.db.jdbc.table_metadata.connection_pool.max_idle` | テーブルメタデータの接続プール内でアイドル状態のままにできる接続の最大数。 | `10` | + | `scalar.db.jdbc.table_metadata.connection_pool.max_total` | テーブルメタデータの接続プールで同時にアクティブにできるアイドル接続と借用接続の最大合計数。制限がない場合は負の値を使用します。 | `25` | + | `scalar.db.jdbc.admin.connection_pool.min_idle` | 管理者の接続プール内のアイドル接続の最小数。 | `5` | + | `scalar.db.jdbc.admin.connection_pool.max_idle` | 管理者の接続プール内でアイドル状態のままにできる接続の最大数。 | `10` | + | `scalar.db.jdbc.admin.connection_pool.max_total` | 管理者の接続プールで同時にアクティブにできるアイドル接続と借用接続の最大合計数。制限がない場合は負の値を使用します。 | `25` | + +:::note + +SQLite3 を JDBC データベースとして使用している場合は、`scalar.db.contact_points` を次のように設定する必要があります。 + +```properties +scalar.db.contact_points=jdbc:sqlite:?busy_timeout=10000 +``` + +他の JDBC データベースとは異なり、[SQLite3 doesn't fully support concurrent access](https://www.sqlite.org/lang_transaction.html)。[`SQLITE_BUSY`](https://www.sqlite.org/rescode.html#busy) によって内部的に頻繁に発生するエラーを回避するには、[`busy_timeout`](https://www.sqlite.org/c3ref/busy_timeout.html) パラメータを設定することをお勧めします。 + +::: + + +DynamoDB では次の構成が利用可能です。 + + | 名前 | 説明 | デフォルト | + |---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------| + | `scalar.db.storage` | `dynamo` を指定する必要があります。 | - | + | `scalar.db.contact_points` | ScalarDB が通信する AWS リージョン (例: `us-east-1`)。 | | + | `scalar.db.username` | AWS とやり取りするユーザーを識別するために使用される AWS アクセスキー。 | | + | `scalar.db.password` | AWS と対話するユーザーを認証するために使用される AWS シークレットアクセスキー。 | | + | `scalar.db.dynamo.endpoint_override` | ScalarDB が通信する Amazon DynamoDB エンドポイント。これは主に、AWS サービスではなくローカルインスタンスでのテストに使用されます。 | | + | `scalar.db.dynamo.namespace.prefix` | ユーザー名前空間とメタデータ名前空間名のプレフィックス。AWS では単一の AWS リージョン内で一意のテーブル名を持つ必要があるため、単一の AWS リージョン内で複数の ScalarDB 環境 (開発、本番など) を使用する場合に便利です。 | | + + + CosmosDB for NoSQL では次の構成が利用可能です。 + + | 名前 | 説明 | デフォルト | + |--------------------------------------|----------------------------------------------------------------------------------------------------------|----------| + | `scalar.db.storage` | `cosmos` を指定する必要があります。 | - | + | `scalar.db.contact_points` | ScalarDB が通信する NoSQL エンドポイント用の Azure Cosmos DB。 | | + | `scalar.db.password` | Azure Cosmos DB for NoSQL にアクセスするための認証を実行するために使用されるマスターキーまたは読み取り専用キーのいずれか。 | | + | `scalar.db.cosmos.consistency_level` | Cosmos DB 操作に使用される一貫性レベル。`STRONG` または `BOUNDED_STALENESS` を指定できます。 | `STRONG` | + + + Cassandra では次の構成が利用可能です。 + + | 名前 | 説明 | デフォルト | + |-----------------------------------------|-----------------------------------------------------------------------|------------| + | `scalar.db.storage` | `cassandra` を指定する必要があります。 | - | + | `scalar.db.contact_points` | カンマで区切られた連絡先。 | | + | `scalar.db.contact_port` | すべての連絡先ポイントのポート番号。 | | + | `scalar.db.username` | データベースにアクセスするためのユーザー名。 | | + | `scalar.db.password` | データベースにアクセスするためのパスワード。 | | + + + +##### マルチストレージのサポート + +ScalarDB は、複数のストレージ実装を同時に使用することをサポートしています。`scalar.db.storage` プロパティの値として `multi-storage` を指定すると、複数のストレージを使用できます。 + +複数のストレージの使用の詳細については、[マルチストレージトランザクション](../multi-storage-transactions.mdx)を参照してください。 + +##### パーティション間スキャン構成 + +以下で説明するようにパーティション間スキャンオプションを有効にすると、`Scan` 操作でパーティション全体のすべてのレコードを取得できます。さらに、`cross_partition_scan.filtering` と `cross_partition_scan.ordering` をそれぞれ有効にすることで、パーティション間 `Scan` 操作で任意の条件と順序を指定できます。現在、順序付けオプション付きのパーティション間スキャンは、JDBC データベースでのみ使用できます。フィルタリングと順序付けを有効にするには、`scalar.db.cross_partition_scan.enabled` を `true` に設定する必要があります。 + +パーティション間スキャンの使用方法の詳細については、[スキャン操作](../api-guide.mdx#スキャン操作)を参照してください。 + +:::warning + +非 JDBC データベースの場合、トランザクションはより低い分離レベル (つまり、`SNAPSHOT`) で実行される可能性があるため、`SERIALIAZABLE` 分離レベルでパーティション間スキャンを有効にすることはお勧めしません。非 JDBC データベースを使用する場合は、トランザクションの一貫性が重要でない場合にのみ、自己責任でパーティション間スキャンを使用してください。 + +::: + +| 名前 | 説明 | デフォルト | +|----------------------------------------------------|-----------------------------------------------|---------| +| `scalar.db.cross_partition_scan.enabled` | パーティション間スキャンを有効にします。 | `false` | +| `scalar.db.cross_partition_scan.filtering.enabled` | パーティション間スキャンでフィルタリングを有効にします。 | `false` | +| `scalar.db.cross_partition_scan.ordering.enabled` | パーティション間スキャンで順序付けを有効にします。 | `false` | + +### 非トランザクションストレージ操作を実行する + +非トランザクションストレージ操作を実行するには、`scalar.db.transaction_manager` プロパティを `single-crud-operation` に設定する必要があります。 + +```properties +scalar.db.transaction_manager=single-crud-operation +``` + +また、[基盤となるストレージまたはデータベースの構成](#基盤となるストレージまたはデータベースの構成)の説明に従って、基盤となるストレージまたはデータベースを構成する必要があります。 + +## ScalarDB Cluster GraphQL 構成 + +ScalarDB Cluster GraphQL の構成は次のとおりです。 + +| 名前 | 説明 | デフォルト | +|-----------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------| +| `scalar.db.graphql.enabled` | ScalarDB Cluster GraphQL が有効かどうか。 | `false` | +| `scalar.db.graphql.port` | GraphQL サーバーのポート番号。 | `8080` | +| `scalar.db.graphql.path` | GraphQL エンドポイントの URL のパスコンポーネント。 | `/graphql` | +| `scalar.db.graphql.namespaces` | GraphQL サーバーがスキーマを生成するテーブルの名前空間のコンマ区切りリスト。指定しない場合、GraphQL サーバーは、すべての ScalarDB 管理名前空間内のすべてのテーブルのスキーマを生成します。 | | +| `scalar.db.graphql.graphiql` | GraphQL サーバーが [GraphiQL](https://github.com/graphql/graphiql) IDE を提供するかどうか。 | `true` | +| `scalar.db.graphql.schema_checking_interval_millis` | ScalarDB スキーマに変更が検出された場合に GraphQL サーバーが GraphQL スキーマを再構築する間隔 (ミリ秒単位)。 | `30000` (30 秒) | + +### サーバーの実行中に ScalarDB スキーマを作成または変更する + +GraphQL スキーマはサーバーの起動時に静的に構築されるため、ScalarDB スキーマが変更された場合 (たとえば、テーブルが追加、変更、または削除された場合)、対応する GraphQL スキーマは再構築されない限り変更を反映しません。これに対処するために、GraphQL サーバーは、定期的なチェックとオンデマンドチェックの 2 つのメカニズムを提供します。 + +#### 定期的なチェックを実行する + +サーバーは、ScalarDB スキーマに変更が発生したかどうかを定期的にチェックし、必要に応じて対応する GraphQL スキーマを再構築します。デフォルトでは、チェックは 30 秒ごとに行われますが、間隔は `scalar.db.graphql.schema_checking_interval_millis` プロパティを使用して構成できます。 + +定期的なチェックを実行する必要がない場合は、プロパティ値を `-1` に設定して無効にすることができます。 + +#### オンデマンドチェックを実行する + +また、HTTP API の `/update-graphql-schema` エンドポイントに POST リクエストを実行して、サーバーに ScalarDB スキーマの変更をチェックし、必要に応じて対応する GraphQL スキーマを再構築するように要求することもできます。 + +たとえば、HTTP API が `localhost:8080` で実行されていて、`scalar.db.graphql.path` プロパティが `/graphql` に設定されている場合、次のコマンドを実行してこのエンドポイントを呼び出すことができます。 + +```console +curl -X POST http://localhost:8080/graphql/update-graphql-schema +``` + +## ScalarDB Cluster SQL 構成 + +ScalarDB Cluster SQL の構成は次のとおりです。 + +| 名前 | 説明 | デフォルト | +|------------------------------------------|----------------------------------------------------------------------------------------------------------|---------------| +| `scalar.db.sql.enabled` | ScalarDB Cluster SQL が有効かどうか。 | `false` | +| `scalar.db.sql.statement_cache.enabled` | ステートメントキャッシュを有効にします。 | `false` | +| `scalar.db.sql.statement_cache.size` | キャッシュされたステートメントの最大数。 | `100` | +| `scalar.db.sql.default_transaction_mode` | デフォルトのトランザクションモード。`TRANSACTION` または `TWO_PHASE_COMMIT_TRANSACTION` を設定できます。 | `TRANSACTION` | +| `scalar.db.sql.default_namespace_name` | デフォルトの名前空間名。SQL ステートメントで名前空間名を指定しない場合は、この値が使用されます。 | | diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/scalardb-cluster-grpc-api-guide.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/scalardb-cluster-grpc-api-guide.mdx new file mode 100644 index 00000000..0c225b81 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/scalardb-cluster-grpc-api-guide.mdx @@ -0,0 +1,211 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster gRPC API ガイド + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; +import WarningLicenseKeyContact from '/src/components/ja-jp/_warning-license-key-contact.mdx'; + + + +このドキュメントでは、ScalarDB Cluster gRPC API について説明します。 + + + +ScalarDB Cluster は、内部で gRPC API を使用する Java API を提供します。 + +Java または JVM 言語を使用する場合は、ScalarDB Cluster gRPC API を直接使用する代わりに、Java API を使用できます。 + +Java API の詳細については、[Java API を使用した ScalarDB Cluster の開発者ガイド](developer-guide-for-scalardb-cluster-with-java-api.mdx)を参照してください。 + +ScalarDB Cluster gRPC API のサービスとメッセージの詳細については、`scalardb-cluster.proto` ファイルの定義を参照してください。商用ライセンスを持つ ScalarDB Cluster ユーザーで、`scalardb-cluster.proto` ファイルが必要な場合は、[お問い合わせ](https://www.scalar-labs.com/contact)ください。 + +ScalarDB Cluster gRPC API は、次のサービスで構成されています。 + +- `scalardb.cluster.rpc.v1.DistributedTransaction`: ScalarDB Cluster に分散トランザクション機能を提供します。 +- `scalardb.cluster.rpc.v1.TwoPhaseCommitTransaction`: ScalarDB Cluster に 2 フェーズコミットトランザクション機能を提供します。 +- `scalardb.cluster.rpc.v1.DistributedTransactionAdmin`: 包括的な管理操作を提供します。 + +次のセクションでは、各サービスの使用方法について説明します。 + +## ScalarDB Cluster gRPC API でのエラー処理の概要 + +各サービスの使用方法を説明する前に、このセクションでは ScalarDB Cluster gRPC API でのエラー処理の仕組みについて説明します。 + +ScalarDB Cluster gRPC API は、エラー処理に [Richer error model](https://grpc.io/docs/guides/error/#richer-error-model) を採用しています。このモデルにより、サーバーは 1 つ以上の protobuf メッセージとして表現される追加のエラー詳細を返すことができ、クライアントはそれを利用できるようになります。ScalarDB Cluster gRPC API は、[standard set of error message types](https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto) の 1 つである `google.rpc.ErrorInfo` を使用し、追加のエラー詳細を `ErrorInfo` フィールドに格納します。 + +`ErrorInfo` には次のフィールドがあります: + +- `reason`: エラーの簡単な説明を提供する文字列。次のセクションでは、各サービスにおける `reason` の可能な値について説明します。 +- `domain`: エラーの原因を示す文字列。ScalarDB Cluster gRPC API では、この文字列は常に `com.scalar.db.cluster` に設定されます。 +- `metadata`: 特定のエラーのメタデータのマップ。ScalarDB Cluster gRPC API では、エラーがトランザクションに関連している場合、マップに `transactionId` キーを持つトランザクション ID が配置されます。 + +エラーが発生した場合は、gRPC レスポンスの `google.rpc.Status` から `ErrorInfo` を取得できますが、取得方法はプログラミング言語によって異なります。 + +特定のプログラミング言語で `ErrorInfo` を取得する方法については、適切なドキュメントを参照してください。 + +## `DistributedTransaction` サービスの使用方法 + +`DistributedTransaction` サービスは次の RPC を提供します: + +- `Begin`: トランザクションを開始します。 +- `Get`: レコードを取得します。 +- `Scan`: レコードをスキャンします。 +- `Put`: レコードを配置します。 +- `Delete`: レコードを削除します。 +- `Mutate` 複数のレコードを変更 (配置および削除) します。 +- `Commit`: トランザクションをコミットします。 +- `Rollback`: トランザクションをロールバックします。 + +まず、`Begin` を呼び出してトランザクションを開始します。 + +次に、`Get` と `Scan` を呼び出してレコードを読み取り、`Put` と `Mutate` を呼び出してレコードを書き込み、`Delete` と `Mutate` を呼び出してレコードを削除します。 + +トランザクションを終了するには、`Commit` を呼び出します。あるいは、トランザクションがコミットされる前にいつでも `Rollback` を呼び出してキャンセルできます。`Begin` を呼び出すと、応答でトランザクション ID を受け取ります。これを使用して、`Get`、`Scan`、`Put`、`Delete`、`Mutate`、`Commit`、および `Rollback` を呼び出すことができます。 + +`Begin` を呼び出すときに、オプションでトランザクション ID を指定できます。トランザクション ID を指定する場合、ユーザーは ID の一意性を保証する責任があります。トランザクション ID を指定しない場合は、ScalarDB Cluster がトランザクションのトランザクション ID を生成します。 + +RPC リクエストごとに `RequestHeader` を設定する必要があります。`RequestHeader` には、リクエストのホップ数を制限している `hop_limit` フィールドが含まれています。`hop_limit` の目的は、クラスター内での無限ループを防ぐことです。リクエストが別のクラスターノードに転送されるたびに、`hop_limit` は 1 つ減少します。`hop_limit` が 0 に達すると、リクエストは拒否されます。 + +### エラー処理 + +以下の表は、`DistributedTransaction` サービスの各 RPC におけるステータスコードと `ErrorInfo` の `reason` の可能な値を示しています。 + +| RPC | ステータスコード | `ErrorInfo` の `reason` | 説明 | +|--------------------------------|---------------------|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Begin | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 | +| Begin | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 | +| Begin | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 | +| Begin | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 | +| Get, Scan, Put, Delete, Mutate | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 | +| Get, Scan, Put, Delete, Mutate | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 | +| Get, Scan, Put, Delete, Mutate | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。このエラーは、トランザクションの有効期限が切れたか、クラスタートポロジの変更によりルーティング情報が更新されたことを示します。この場合は、トランザクションを最初から再試行してください。 | +| Get, Scan, Put, Delete, Mutate | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 | +| Get, Scan, Put, Delete, Mutate | FAILED_PRECONDITION | TRANSACTION_CONFLICT | トランザクションの競合が発生しました。このエラーが発生した場合は、トランザクションを最初から再試行してください。 | +| Get, Scan, Put, Delete, Mutate | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 | +| Put, Delete, Mutate | FAILED_PRECONDITION | UNSATISFIED_CONDITION | 突然変異条件が満たされていません。 | +| Commit | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 | +| Commit | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 | +| Commit | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。このエラーは、トランザクションの有効期限が切れたか、クラスタートポロジの変更によりルーティング情報が更新されたことを示します。この場合は、トランザクションを最初から再試行してください。 | +| Commit | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 | +| Commit | FAILED_PRECONDITION | TRANSACTION_CONFLICT | トランザクションの競合が発生しました。このエラーが発生した場合は、トランザクションを最初から再試行してください。 | +| Commit | INTERNAL | UNKNOWN_TRANSACTION_STATUS | トランザクションのステータスは不明です (トランザクションが正常にコミットされたかどうかは不明です)。この状況では、トランザクションが正常にコミットされたかどうかを確認し、そうでない場合は再試行する必要があります。トランザクションステータスを判別する責任はユーザーにあります。トランザクションステータステーブルを作成し、他のアプリケーションデータと連動して更新すると、テーブル自体からトランザクションのステータスを判別できるため、便利です。 | +| Commit | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 | +| Rollback | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 | +| Rollback | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 | +| Rollback | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。ロールバックの場合、トランザクションは自動的に期限切れになるため、トランザクションを再試行する必要はありません。 | +| Rollback | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。ロールバックの場合、トランザクションは自動的に期限切れになるため、トランザクションを再試行する必要はありません。 | +| Rollback | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 | + +エラーが発生した場合は、`Begin` の場合を除き、トランザクションをロールバックする必要があります。その後、再試行によって解決できるエラーについては、トランザクションを最初から再試行できます。 + +上記のエラーの他に、gRPC ライブラリによって返されるエラーが発生する場合があります。これらの場合、応答には `ErrorInfo` は含まれません。詳細については、[gRPC ドキュメント](https://grpc.io/docs/guides/error/#error-status-codes)を参照してください。 + +gRPC では、RPC ごとに期限を設定できます。期限を超えると、`DEADLINE_EXCEEDED` エラーが表示されます。一般に、RPC が `Begin` または `Commit` でない限り、この状況ではトランザクションをロールバックする必要があります。`Commit` の場合は `UNKNOWN_TRANSACTION_STATUS` (トランザクションが正常にコミットされたかどうか不明) と同等の状況となり、同様にエラーを処理する必要があります。 + +## `TwoPhaseCommitTransaction` サービスの使用方法 + +`TwoPhaseCommitTransaction` サービスは次の RPC を提供します: + +- `Begin`: トランザクションを開始します。 +- `Join`: トランザクションに参加します。 +- `Get`: レコードを取得します。 +- `Scan`: レコードをスキャンします。 +- `Put`: レコードを配置します。 +- `Delete`: レコードを削除します。 +- `Mutate`: 複数のレコードを変更 (配置および削除) します。 +- `Prepare`: トランザクションを準備します。 +- `Validate`: トランザクションを検証します。 +- `Commit`: トランザクションをコミットします。 +- `Rollback`: トランザクションをロールバックします。 + +まず、コーディネータープロセスの場合は、`Begin` を呼び出してトランザクションを開始します。あるいは、参加プロセスの場合は、`Join` を呼び出して、コーディネーターがすでに開始しているトランザクションに参加できます。次に、`Get` と `Scan` を呼び出してレコードを読み取り、`Put` と `Mutate` を呼び出してレコードを書き込み、`Delete` と `Mutate` を呼び出してレコードを削除できます。トランザクションを確定するには、`Prepare`、`Validate`、`Commit` の順に呼び出します。または、トランザクションがコミットされる前であればいつでも `Rollback` を呼び出してトランザクションをキャンセルできます。`Begin` または `Join` を呼び出すと、応答でトランザクション ID が返されます。これを使用して、`Get`、`Scan`、`Put`、`Delete`、`Mutate`、`Prepare`、`Validate`、`Commit`、`Rollback` を呼び出すことができます。 + +`Begin` を呼び出すときに、オプションでトランザクション ID を指定できます。トランザクション ID を指定する場合、ID の一意性を保証するのはユーザーの責任です。トランザクション ID を指定しない場合、ScalarDB Cluster はトランザクションのトランザクション ID を生成します。 + +RPC リクエストごとに `RequestHeader` を設定する必要があります。`RequestHeader` には、リクエストのホップ数を制限している `hop_limit` フィールドが含まれています。`hop_limit` の目的は、クラスター内での無限ループを防ぐことです。リクエストが別のクラスターノードに転送されるたびに、`hop_limit` は 1 つ減ります。`hop_limit` が 0 に達すると、リクエストは拒否されます。 + +### エラー処理 + +次の表は、`TwoPhaseCommitTransaction` サービスの各 RPC のステータスコードと `ErrorInfo` の `reason` の可能な値を示しています。 + +| RPC | ステータスコード | `ErrorInfo` の `reason` | 説明 | +|--------------------------------|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Begin, Join | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 | +| Begin, Join | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 | +| Begin, Join | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 | +| Begin, Join | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 | +| Get, Scan, Put, Delete, Mutate | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 | +| Get, Scan, Put, Delete, Mutate | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 | +| Get, Scan, Put, Delete, Mutate | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。これは、トランザクションの有効期限が切れたか、クラスタートポロジの変更によりルーティング情報が更新されたことを示します。この場合は、トランザクションを最初から再試行してください。 | +| Get, Scan, Put, Delete, Mutate | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 | +| Get, Scan, Put, Delete, Mutate | FAILED_PRECONDITION | TRANSACTION_CONFLICT | トランザクションの競合が発生しました。このエラーが発生した場合は、トランザクションを最初から再試行してください。 | +| Get, Scan, Put, Delete, Mutate | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 | +| Put, Delete, Mutate | FAILED_PRECONDITION | UNSATISFIED_CONDITION | 突然変異条件が満たされていません。 | +| Prepare, Validate | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 | +| Prepare, Validate | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 | +| Prepare, Validate | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。このエラーは、トランザクションの有効期限が切れたか、クラスタートポロジの変更によりルーティング情報が更新されたことを示します。この場合は、トランザクションを最初から再試行してください。 | +| Prepare, Validate | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 | +| Prepare, Validate | FAILED_PRECONDITION | TRANSACTION_CONFLICT | トランザクションの競合が発生しました。このエラーが発生した場合は、トランザクションを最初から再試行してください。 | +| Prepare, Validate | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 | +| Commit | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 | +| Commit | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 | +| Commit | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。このエラーは、トランザクションの有効期限が切れたか、クラスタートポロジの変更によりルーティング情報が更新されたことを示します。この場合は、トランザクションを最初から再試行してください。 | +| Commit | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 | +| Commit | FAILED_PRECONDITION | TRANSACTION_CONFLICT | トランザクションの競合が発生しました。このエラーが発生した場合は、トランザクションを最初から再試行してください。 | +| Commit | INTERNAL | UNKNOWN_TRANSACTION_STATUS | トランザクションのステータスは不明です (トランザクションが正常にコミットされたかどうかは不明です)。この状況では、トランザクションが正常にコミットされたかどうかを確認し、そうでない場合は再試行する必要があります。トランザクションステータスを判別する責任はユーザーにあります。トランザクションステータステーブルを作成し、他のアプリケーションデータと連動して更新すると、テーブル自体からトランザクションのステータスを判別できるため、便利です。 | +| Commit | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 | +| Rollback | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 | +| Rollback | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 | +| Rollback | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。ロールバックの場合、トランザクションは自動的に期限切れになるため、トランザクションを再試行する必要はありません。 | +| Rollback | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。ロールバックの場合、トランザクションは自動的に期限切れになるため、トランザクションを再試行する必要はありません。 | +| Rollback | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 | + +エラーが発生した場合は、`Begin` または `Join` の場合を除き、トランザクションをロールバックする必要があります。その後、再試行によって解決できるエラーについては、トランザクションを最初から再試行できます。 + +上記のエラーの他に、gRPC ライブラリによって返されるエラーが発生する場合があります。これらの場合、応答には `ErrorInfo` は含まれません。詳細については、[gRPC ドキュメント](https://grpc.io/docs/guides/error/#error-status-codes)を参照してください。 + +gRPC では、各 RPC に期限を設定できます。期限を超えると、`DEADLINE_EXCEEDED` エラーが表示されます。一般に、RPC が `Begin`、`Join`、または `Commit` でない限り、この状況ではトランザクションをロールバックする必要があります。`Commit` の場合、状況は `UNKNOWN_TRANSACTION_STATUS` (トランザクションが正常にコミットされたかどうか不明) と同等であり、同じ方法でエラーを処理する必要があります。 + +## `DistributedTransactionAdmin` サービスの使用方法 + +`DistributedTransactionAdmin` サービスは、次の RPC を提供します。 + +- `CreateNamespace`: 名前空間を作成します。 +- `DropNamespace`: 名前空間を削除します。 +- `NamespaceExists`: 指定された名前空間が存在するかどうかを返します。 +- `CreateTable`: テーブルを作成します。 +- `DropTable`: テーブルを削除します。 +- `TruncateTable`: テーブルを切り捨てます。 +- `TableExists`: 指定されたテーブルが存在するかどうかを返します。 +- `CreateIndex`: インデックスを作成します。 +- `DropIndex`: インデックスを削除します。 +- `IndexExists`: 指定されたインデックスが存在するかどうかを返します。 +- `RepairNamespace`: 不明な状態にある可能性がある名前空間を修復します。 +- `RepairTable`: 不明な状態にある可能性がある名前空間を修復します。 +- `AddNewColumnToTable`: テーブルに新しい列を追加します。 +- `CreateCoordinatorTables`: コーディネーターテーブルを作成します。 +- `DropCoordinatorTables`: コーディネーターテーブルを削除します。 +- `TruncateCoordinatorTables`: コーディネーターテーブルを切り捨てます。 +- `CoordinatorTablesExist`: コーディネーターテーブルが存在するかどうかを返します。 +- `RepairCoordinatorTables`: コーディネーターテーブルを修復します。 +- `GetTableMetadata`: 指定されたテーブルのテーブルメタデータを返します。 +- `GetNamespaceTableNames`: 指定された名前空間内のテーブルを返します。 +- `GetNamespaceNames`: ScalarDB によって作成された既存の名前空間名を返します。 +- `ImportTable`: ScalarDB によって管理されていない既存のテーブルをインポートします。 +- `Upgrade`: ScalarDB 環境をアップグレードして、最新バージョンの ScalarDB API をサポートします。 + +### エラー処理 + +以下の表は、`DistributedTransactionAdmin` サービスのすべての RPC のステータスコードと `ErrorInfo` の `reason` の可能な値を示しています。 + +| ステータスコード | `ErrorInfo` の `reason` | 説明 | +|---------------------|----------------------------|------------------------------| +| INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 | +| FAILED_PRECONDITION | ILLEGAL_STATE | が無効な状態で呼び出されました。 | +| INTERNAL | INTERNAL_ERROR | 操作が失敗しました。 | + +上記のエラー以外にも、gRPC ライブラリによって返されるエラーが発生する場合があります。このような場合、応答には `ErrorInfo` は含まれません。詳細については、[gRPC ドキュメント](https://grpc.io/docs/guides/error/#error-status-codes)を参照してください。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/scalardb-cluster-sql-grpc-api-guide.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/scalardb-cluster-sql-grpc-api-guide.mdx new file mode 100644 index 00000000..099acaa0 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/scalardb-cluster-sql-grpc-api-guide.mdx @@ -0,0 +1,184 @@ +--- +tags: + - Enterprise Premium +--- + +# ScalarDB Cluster SQL gRPC API ガイド + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; +import WarningLicenseKeyContact from '/src/components/ja-jp/_warning-license-key-contact.mdx'; + + + +このドキュメントでは、ScalarDB Cluster SQL gRPC API について説明します。 + + + +ScalarDB Cluster SQL は、内部で gRPC API を使用する Java API を提供します。Java または JVM 言語を使用する場合は、ScalarDB Cluster SQL gRPC API を直接使用する代わりに、Java API を使用できます。Java API の詳細については、[Java API を使用した ScalarDB Cluster の開発者ガイド](developer-guide-for-scalardb-cluster-with-java-api.mdx)を参照してください。 + +ScalarDB Cluster SQL gRPC API のサービスとメッセージの詳細については、`scalardb-cluster-sql.proto` ファイルの定義を参照してください。商用ライセンスを持つ ScalarDB Cluster ユーザーで、`scalardb-cluster-sql.proto` ファイルが必要な場合は、[お問い合わせ](https://www.scalar-labs.com/contact)ください。 + +ScalarDB Cluster SQL gRPC API は、次のサービスで構成されています: + +- `scalardb.cluster.rpc.v1.sql.SqlTransaction`: ScalarDB Cluster SQL のトランザクション機能を提供します。 +- `scalardb.cluster.rpc.v1.sql.SqlTwoPhaseCommitTransaction`: ScalarDB Cluster SQL の 2 フェーズコミットトランザクション機能を提供します。 +- `scalardb.cluster.rpc.v1.sql.Metadata`: ScalarDB Cluster SQL のメタデータビューを提供します。 + +次のセクションでは、各サービスの使用方法について説明します。 + +## ScalarDB Cluster SQL gRPC API でのエラー処理の概要 + +各サービスの使用方法を説明する前に、このセクションでは、ScalarDB Cluster SQL gRPC API でのエラー処理の仕組みについて説明します。 + +ScalarDB Cluster SQL gRPC API は、エラー処理に [Richer error model](https://grpc.io/docs/guides/error/#richer-error-model) を採用しています。 + +このモデルにより、サーバーは 1 つ以上の protobuf メッセージとして表現される追加のエラー詳細を返すことができ、クライアントはそれを利用できるようになります。 + +ScalarDB Cluster SQL gRPC API は、[standard set of error message types](https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto) の 1 つである `google.rpc.ErrorInfo` を使用し、追加のエラー詳細を `ErrorInfo` フィールドに格納します。 + +`ErrorInfo` には次のフィールドがあります: + +- `reason`: エラーの簡単な説明を提供する文字列。次のセクションでは、各サービスにおける `reason` の可能な値について説明します。 +- `domain`: エラーの原因を示す文字列。ScalarDB Cluster SQL gRPC API では、この文字列は常に `com.scalar.db.cluster.sql` に設定されます。 +- `metadata`: 特定のエラーのメタデータのマップ。ScalarDB Cluster SQL gRPC API では、エラーがトランザクションに関連している場合、マップに `transactionId` キーを持つトランザクション ID が配置されます。 + +エラーが発生した場合は、gRPC レスポンスの `google.rpc.Status` から `ErrorInfo` を取得できますが、その方法はプログラミング言語によって異なります。 + +特定のプログラミング言語で `ErrorInfo` を取得する方法については、適切なドキュメントを参照してください。 + +## `SqlTransaction` サービスの使用方法 + +`SqlTransaction` サービスは次の RPC を提供します: + +- `Begin`: トランザクションを開始します。 +- `Execute`: SQL ステートメントを実行します。 +- `Commit`: トランザクションをコミットします。 +- `Rollback`: トランザクションをロールバックします。 + +まず、`Begin` を呼び出してトランザクションを開始します。その後、`Execute` を呼び出してレコードの読み取り、書き込み、削除を行うことができます。トランザクションを終了するには、`Commit` を呼び出します。 + +または、トランザクションがコミットされる前であればいつでも `Rollback` を呼び出してキャンセルできます。`Begin` を呼び出すと、レスポンスでトランザクション ID を受け取ります。この ID を使用して、`Execute`、`Commit`、および `Rollback` を呼び出すことができます。 + +また、トランザクション ID なしで `Execute` を呼び出して、ワンショットトランザクションを実行することもできます。この場合、トランザクションは実行後に自動的にコミットされます。このメソッドを使用して、DDL ステートメントを実行することもできます。サポートされている SQL ステートメントの詳細については、[ScalarDB SQL 文法](../scalardb-sql/grammar.mdx)を参照してください。ただし、`Execute` は DML ステートメントと DDL ステートメントのみをサポートすることに注意してください。 + +`Begin` を呼び出すときに、オプションでトランザクション ID を指定できます。トランザクション ID を指定する場合、ユーザーは ID の一意性を保証する責任があります。トランザクション ID を指定しない場合、ScalarDB Cluster はトランザクションのトランザクション ID を生成します。 + +各 RPC リクエストに対して `RequestHeader` を設定する必要があります。`RequestHeader` には、リクエストのホップ数を制限する `hop_limit` フィールドが含まれています。`hop_limit` の目的は、クラスター内での無限ループを防ぐことです。リクエストが別のクラスターノードに転送されるたびに、`hop_limit` は 1 つ減ります。`hop_limit` が 0 に達すると、リクエストは拒否されます。 + +### エラー処理 + +以下の表は、`SqlTransaction` サービスの各 RPC におけるステータスコードと `ErrorInfo` の `reason` の可能な値を示しています。 + +| RPC | ステータスコード | `ErrorInfo` の `reason` | 説明 | +|----------|---------------------|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Begin | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 | +| Begin | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 | +| Begin | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 | +| Begin | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 | +| Execute | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 | +| Execute | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 | +| Execute | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。このエラーは、トランザクションの有効期限が切れたか、クラスタートポロジの変更によりルーティング情報が更新されたことを示します。この場合、トランザクションを最初から再試行してください。 | +| Execute | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 | +| Execute | FAILED_PRECONDITION | TRANSACTION_CONFLICT | トランザクションの競合が発生しました。このエラーが発生した場合は、トランザクションを最初から再試行してください。 | +| Execute | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 | +| Commit | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 | +| Commit | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 | +| Commit | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。このエラーは、トランザクションの有効期限が切れたか、クラスタートポロジの変更によりルーティング情報が更新されたことを示します。この場合、トランザクションを最初から再試行してください。 | +| Commit | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 | +| Commit | FAILED_PRECONDITION | TRANSACTION_CONFLICT | トランザクションの競合が発生しました。このエラーが発生した場合は、トランザクションを最初から再試行してください。 | +| Commit | INTERNAL | UNKNOWN_TRANSACTION_STATUS | トランザクションのステータスは不明です (トランザクションが正常にコミットされたかどうかは不明です)。この状況では、トランザクションが正常にコミットされたかどうかを確認し、そうでない場合は再試行する必要があります。トランザクションステータスを判別する責任はユーザーにあります。トランザクションステータステーブルを作成し、他のアプリケーションデータと連動して更新すると、テーブル自体からトランザクションのステータスを判別できるため、便利です。 | +| Commit | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 | +| Rollback | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 | +| Rollback | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 | +| Rollback | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。ロールバックの場合、トランザクションは自動的に期限切れになるため、トランザクションを再試行する必要はありません。 | +| Rollback | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。ロールバックの場合、トランザクションは自動的に期限切れになるため、トランザクションを再試行する必要はありません。 | +| Rollback | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 | + +エラーが発生した場合は、`Begin` の場合を除き、トランザクションをロールバックする必要があります。その後、再試行によって解決できるエラーについては、トランザクションを最初から再試行できます。 + +上記のエラーの他に、gRPC ライブラリによって返されるエラーが発生する場合があります。これらの場合、応答には `ErrorInfo` は含まれません。詳細については、[gRPC ドキュメント](https://grpc.io/docs/guides/error/#error-status-codes)を参照してください。 + +gRPC では、RPC ごとに期限を設定できます。期限を超えると、`DEADLINE_EXCEEDED` エラーが表示されます。一般に、RPC が `Begin` または `Commit` でない限り、この状況ではトランザクションをロールバックする必要があります。`Commit` の場合は `UNKNOWN_TRANSACTION_STATUS` (トランザクションが正常にコミットされたかどうか不明) と同等の状況となり、同様にエラーを処理する必要があります。 + +## `SqlTwoPhaseCommitTransaction` サービスの使用方法 + +`SqlTwoPhaseCommitTransaction` サービスは次の RPC を提供します: + +- `Begin`: トランザクションを開始します。 +- `Join`: トランザクションに参加します。 +- `Execute`: SQL ステートメントを実行します。 +- `Prepare`: トランザクションを準備します。 +- `Validate`: トランザクションを検証します。 +- `Commit`: トランザクションをコミットします。 +- `Rollback`: トランザクションをロールバックします。 + +まず、コーディネータープロセスの場合は、`Begin` を呼び出してトランザクションを開始します。または、参加者プロセスの場合は、`Join` を呼び出して、コーディネーターが既に開始しているトランザクションに参加できます。その後、`Execute` を呼び出してレコードの読み取り、書き込み、および削除を行うことができます。 +トランザクションを確定するには、`Prepare`、`Validate`、`Commit` の順に呼び出します。または、トランザクションがコミットされる前であればいつでも `Rollback` を呼び出してキャンセルできます。`Begin` または `Join` を呼び出すと、応答でトランザクション ID が返されます。これを使用して、`Execute`、`Prepare`、`Validate`、`Commit`、および `Rollback` を呼び出すことができます。 + +また、トランザクション ID なしで `Execute` を呼び出して、ワンショットトランザクションを実行することもできます。この場合、トランザクションは実行後に自動的にコミットされます。この方法を使用して、DDL ステートメントを実行することもできます。 サポートされている SQL ステートメントの詳細については、[ScalarDB SQL 文法](../scalardb-sql/grammar.mdx)を参照してください。ただし、`Execute` は DML ステートメントと DDL ステートメントのみをサポートすることに注意してください。 + +`Begin` を呼び出すときに、オプションでトランザクション ID を指定できます。トランザクション ID を指定する場合、ID の一意性を保証するのはユーザーの責任です。トランザクション ID を指定しない場合、ScalarDB Cluster はトランザクションのトランザクション ID を生成します。 + +RPC リクエストごとに `RequestHeader` を設定する必要があります。`RequestHeader` には、リクエストのホップ数を制限している `hop_limit` フィールドが含まれています。`hop_limit` の目的は、クラスター内での無限ループを防ぐことです。リクエストが別のクラスターノードに転送されるたびに、`hop_limit` は 1 つ減ります。`hop_limit` が 0 に達すると、リクエストは拒否されます。 + +### エラー処理 + +次の表は、`SqlTwoPhaseCommitTransaction` サービスの各 RPC のステータスコードと `ErrorInfo` の `reason` の可能な値を示しています。 + +| RPC | ステータスコード | `ErrorInfo` の `reason` | 説明 | +|-------------------|---------------------|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Begin, Join | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 | +| Begin, Join | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 | +| Begin, Join | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 | +| Begin, Join | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 | +| Execute | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 | +| Execute | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 | +| Execute | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。このエラーは、トランザクションの有効期限が切れたか、クラスタートポロジの変更によりルーティング情報が更新されたことを示します。この場合、トランザクションを最初から再試行してください。 | +| Execute | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 | +| Execute | FAILED_PRECONDITION | TRANSACTION_CONFLICT | トランザクションの競合が発生しました。このエラーが発生した場合は、トランザクションを最初から再試行してください。 | +| Execute | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 | +| Prepare, Validate | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 | +| Prepare, Validate | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 | +| Prepare, Validate | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。このエラーは、トランザクションの有効期限が切れたか、クラスタートポロジの変更によりルーティング情報が更新されたことを示します。この場合、トランザクションを最初から再試行してください。 | +| Prepare, Validate | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 | +| Prepare, Validate | FAILED_PRECONDITION | TRANSACTION_CONFLICT | トランザクションの競合が発生しました。このエラーが発生した場合は、トランザクションを最初から再試行してください。 | +| Prepare, Validate | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 | +| Commit | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 | +| Commit | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 | +| Commit | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。このエラーは、トランザクションの有効期限が切れたか、クラスタートポロジの変更によりルーティング情報が更新されたことを示します。この場合、トランザクションを最初から再試行してください。 | +| Commit | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 | +| Commit | FAILED_PRECONDITION | TRANSACTION_CONFLICT | トランザクションの競合が発生しました。このエラーが発生した場合は、トランザクションを最初から再試行してください。 | +| Commit | INTERNAL | UNKNOWN_TRANSACTION_STATUS | トランザクションのステータスは不明です (トランザクションが正常にコミットされたかどうかは不明です)。この状況では、トランザクションが正常にコミットされたかどうかを確認し、そうでない場合は再試行する必要があります。トランザクションステータスを判別する責任はユーザーにあります。トランザクションステータステーブルを作成し、他のアプリケーションデータと連動して更新すると、テーブル自体からトランザクションのステータスを判別できるため、便利です。 | +| Commit | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 | +| Rollback | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 | +| Rollback | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 | +| Rollback | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。ロールバックの場合、トランザクションは自動的に期限切れになるため、トランザクションを再試行する必要はありません。 | +| Rollback | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。ロールバックの場合、トランザクションは自動的に期限切れになるため、トランザクションを再試行する必要はありません。 | +| Rollback | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 | + +エラーが発生した場合は、`Begin` または `Join` の場合を除き、トランザクションをロールバックする必要があります。その後、再試行によって解決できるエラーについては、トランザクションを最初から再試行できます。 + +上記のエラーの他に、gRPC ライブラリによって返されるエラーが発生する場合があります。これらの場合、応答には `ErrorInfo` は含まれません。詳細については、[gRPC ドキュメント](https://grpc.io/docs/guides/error/#error-status-codes)を参照してください。 + +gRPC では、各 RPC に期限を設定できます。期限を超えると、`DEADLINE_EXCEEDED` エラーが表示されます。一般に、RPC が `Begin`、`Join`、または `Commit` でない限り、この状況ではトランザクションをロールバックする必要があります。`Commit` の場合は `UNKNOWN_TRANSACTION_STATUS` (トランザクションが正常にコミットされたかどうか不明) と同等の状況となり、同様にエラーを処理する必要があります。 + +## `Metadata` サービスの使用方法 + +`Metadata` サービスは次の RPC を提供します: + +- `GetNamespaceMetadata`: 指定された名前空間の名前空間メタデータを取得します。 +- `ListTableMetadataInNamespace`: 指定された名前空間内のテーブルのテーブルメタデータを取得します。 +- `GetTableMetadata`: 指定されたテーブルのテーブルメタデータを取得します。 +- `ListNamespaceMetadata`: 名前空間メタデータのリストを取得します。 + +### エラー処理 + +以下の表は、`Metadata` サービスのすべての RPC のステータスコードと `ErrorInfo` の `reason` の可能な値を示しています: + +| ステータスコード | `ErrorInfo` の `reason` | 説明 | +|---------------------|----------------------------|---------------------------------| +| INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です | +| FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 | +| INTERNAL | INTERNAL_ERROR | 操作が失敗しました。 | + +上記のエラー以外にも、gRPC ライブラリによって返されるエラーが発生する場合があります。このような場合、応答には `ErrorInfo` は含まれません。詳細については、[gRPC ドキュメント](https://grpc.io/docs/guides/error/#error-status-codes)を参照してください。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/scalardb-cluster-status-codes.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/scalardb-cluster-status-codes.mdx new file mode 100644 index 00000000..ddee9a3a --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/scalardb-cluster-status-codes.mdx @@ -0,0 +1,403 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster のエラーコード + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このページでは、ScalarDB Cluster のエラーコードの一覧を示します。 + +## エラーコードのクラスと説明 + +| クラス | 説明 | +|:----------------|:--------------------------| +| `CLUSTER-1xxxx` | ユーザーエラーカテゴリのエラー | +| `CLUSTER-2xxxx` | 同時実行エラーカテゴリのエラー | +| `CLUSTER-3xxxx` | 内部エラーカテゴリのエラー | + +## `CLUSTER-1xxxx` ステータスコード + +### `CLUSTER-10000` + +**メッセージ** + +```markdown +The namespace does not exist. Namespace: %s +``` + +### `CLUSTER-10001` + +**メッセージ** + +```markdown +The table does not exist. Table: %s +``` + +### `CLUSTER-10002` + +**メッセージ** + +```markdown +The user does not exist. User: %s +``` + +### `CLUSTER-10003` + +**メッセージ** + +```markdown +ClusterConfig is not specified +``` + +### `CLUSTER-10004` + +**メッセージ** + +```markdown +The get type is unspecified +``` + +### `CLUSTER-10005` + +**メッセージ** + +```markdown +The get type is unrecognized +``` + +### `CLUSTER-10006` + +**メッセージ** + +```markdown +The value of the column is not set. Column: %s +``` + +### `CLUSTER-10007` + +**メッセージ** + +```markdown +The scan type is unspecified +``` + +### `CLUSTER-10008` + +**メッセージ** + +```markdown +The scan type is unrecognized +``` + +### `CLUSTER-10009` + +**メッセージ** + +```markdown +The order is unspecified +``` + +### `CLUSTER-10010` + +**メッセージ** + +```markdown +The order is unrecognized +``` + +### `CLUSTER-10011` + +**メッセージ** + +```markdown +The clustering order is unspecified +``` + +### `CLUSTER-10012` + +**メッセージ** + +```markdown +The clustering order is unrecognized +``` + +### `CLUSTER-10013` + +**メッセージ** + +```markdown +The put condition type is unspecified +``` + +### `CLUSTER-10014` + +**メッセージ** + +```markdown +The put condition type is unrecognized +``` + +### `CLUSTER-10015` + +**メッセージ** + +```markdown +The delete condition type is unspecified +``` + +### `CLUSTER-10016` + +**メッセージ** + +```markdown +The delete condition type is unrecognized +``` + +### `CLUSTER-10017` + +**メッセージ** + +```markdown +The operator is unspecified +``` + +### `CLUSTER-10018` + +**メッセージ** + +```markdown +The operator is unrecognized +``` + +### `CLUSTER-10019` + +**メッセージ** + +```markdown +The mutation is not set +``` + +### `CLUSTER-10020` + +**メッセージ** + +```markdown +The data type is unspecified +``` + +### `CLUSTER-10021` + +**メッセージ** + +```markdown +The data type is unrecognized +``` + +### `CLUSTER-10022` + +**メッセージ** + +```markdown +The user option is unspecified +``` + +### `CLUSTER-10023` + +**メッセージ** + +```markdown +The user option is unrecognized +``` + +### `CLUSTER-10024` + +**メッセージ** + +```markdown +The privilege is unspecified +``` + +### `CLUSTER-10025` + +**メッセージ** + +```markdown +The privilege is unrecognized +``` + +### `CLUSTER-10026` + +**メッセージ** + +```markdown +The username is not set +``` + +### `CLUSTER-10027` + +**メッセージ** + +```markdown +This feature is not supported in ScalarDB Cluster +``` + +### `CLUSTER-10028` + +**メッセージ** + +```markdown +The property 'scalar.db.contact_points' must not be empty +``` + +### `CLUSTER-10029` + +**メッセージ** + +```markdown +The property 'scalar.db.contact_points' must be prefixed with 'indirect:' or 'direct-kubernetes:' +``` + +### `CLUSTER-10030` + +**メッセージ** + +```markdown +The format of the property 'scalar.db.contact_points' for direct-kubernetes client mode is 'direct-kubernetes:/' or 'direct-kubernetes:' +``` + +### `CLUSTER-10031` + +**メッセージ** + +```markdown +The property 'scalar.db.sql.cluster_mode.contact_points' must not be empty +``` + +### `CLUSTER-10032` + +**メッセージ** + +```markdown +The property 'scalar.db.sql.cluster_mode.contact_points' must be prefixed with 'indirect:' or 'direct-kubernetes:' +``` + +### `CLUSTER-10033` + +**メッセージ** + +```markdown +The format of the property 'scalar.db.sql.cluster_mode.contact_points' for direct-kubernetes client mode is 'direct-kubernetes:/' or 'direct-kubernetes:' +``` + +### `CLUSTER-10034` + +**メッセージ** + +```markdown +ClusterNodeManagerFactory is not specified +``` + +### `CLUSTER-10035` + +**メッセージ** + +```markdown +The update condition type is unspecified +``` + +### `CLUSTER-10036` + +**メッセージ** + +```markdown +The update condition type is unrecognized +``` + +### `CLUSTER-10037` + +**メッセージ** + +```markdown +The two-phase commit interface is not supported +``` + +## `CLUSTER-2xxxx` ステータスコード + +### `CLUSTER-20000` + +**メッセージ** + +```markdown +The hop limit is exceeded +``` + +### `CLUSTER-20001` + +**メッセージ** + +```markdown +A transaction associated with the specified transaction ID is not found. The transaction might have expired, or the cluster node that handled the transaction might have been restarted. Transaction ID: %s +``` + +## `CLUSTER-3xxxx` ステータスコード + +### `CLUSTER-30000` + +**メッセージ** + +```markdown +Getting local IP addresses failed +``` + +### `CLUSTER-30001` + +**メッセージ** + +```markdown +Getting a cluster node object from the cache failed. Cluster Node IP Address: %s +``` + +### `CLUSTER-30002` + +**メッセージ** + +```markdown +The ring is empty +``` + +### `CLUSTER-30003` + +**メッセージ** + +```markdown +Getting the Kubernetes API client failed +``` + +### `CLUSTER-30004` + +**メッセージ** + +```markdown +Reading the Kubernetes endpoint failed. Namespace: %s; Name: %s; Code: %d; Response Headers: %s; Response Body: %s +``` + +### `CLUSTER-30005` + +**メッセージ** + +```markdown +Configuring TLS failed +``` + +### `CLUSTER-30006` + +**メッセージ** + +```markdown +No nearest cluster nodes are found +``` diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/setup-scalardb-cluster-on-kubernetes-by-using-helm-chart.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/setup-scalardb-cluster-on-kubernetes-by-using-helm-chart.mdx new file mode 100644 index 00000000..bc5d7b05 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/setup-scalardb-cluster-on-kubernetes-by-using-helm-chart.mdx @@ -0,0 +1,257 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster をローカルにデプロイする方法 + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; +import WarningLicenseKeyContact from '/src/components/ja-jp/_warning-license-key-contact.mdx'; + + + +このガイドでは、テスト環境向けに特別に設計されたローカル Kubernetes クラスターで Helm Chart を使用して ScalarDB Cluster をデプロイする方法について説明します。 + +## 前提条件 + +- [Docker](https://www.docker.com/get-started/) 20.10 以降と [Docker Compose](https://docs.docker.com/compose/install/) V2 以降 +- Kubernetes クラスター ([minikube](https://minikube.sigs.k8s.io/docs/start/) または [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) のいずれか) +- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) +- [Helm](https://helm.sh/docs/intro/install/) + + + +## 作成するもの + +以下に示すように、ローカル Kubernetes クラスターに次のコンポーネントをデプロイします。 + +``` ++----------------------------------------------------------------------------------------------------------------------------------------+ +| [Kubernetes クラスター] | +| | +| [ポッド] [ポッド] [ポッド] | +| | +| +-------+ | +| +---> | Envoy | ---+ | +| | +-------+ | | +| | | | +| +---------+ | +-------+ | +--------------------+ | +| | サービス | ---+---> | Envoy | ---+---------> | サービス | ---+ | +| | (Envoy) | | +-------+ | | (ScalarDB Cluster) | | | +| +---------+ | | +--------------------+ | +------------------------+ | +| | +-------+ | | +---> | ScalarDB Cluster ノード | ---+ | +| +---> | Envoy | ---+ | | +------------------------+ | | +| +-------+ | | | | +| | | +------------------------+ | +------------+ | +| +---+---> | ScalarDB Cluster ノード | ---+---> | PostgreSQL | | +| | | +------------------------+ | +------------+ | +| | | | | +| | | +------------------------+ | | +| | +---> | ScalarDB Cluster ノード | ---+ | +| | +------------------------+ | +| +-----------------------------+ | | +| | サービス | ---+ | +| | (ScalarDB Cluster GraphQL) | | +| +-----------------------------+ | +| | ++----------------------------------------------------------------------------------------------------------------------------------------+ +``` + +## ステップ 1. PostgreSQL コンテナを起動する + +ScalarDB Cluster は、バックエンドデータベースとして何らかのデータベースシステムを使用する必要があります。このガイドで使用するデータベースは PostgreSQL です。 + +次のようにして、Kubernetes クラスターに PostgreSQL をデプロイできます。 + +1. 次のコマンドを実行して、Bitnami Helm リポジトリを追加します。 + + ```console + helm repo add bitnami https://charts.bitnami.com/bitnami + ``` + +2. 次のコマンドを実行して PostgreSQL をデプロイします。 + + ```console + helm install postgresql-scalardb-cluster bitnami/postgresql \ + --set auth.postgresPassword=postgres \ + --set primary.persistence.enabled=false + ``` + +3. 次のコマンドを実行して、PostgreSQL コンテナが実行されているかどうかを確認します。 + + ```console + kubectl get pod + ``` + + 次の出力が表示されます。 + + ```console + NAME READY STATUS RESTARTS AGE + postgresql-scalardb-cluster-0 1/1 Running 0 17s + ``` + +## ステップ 2. Helm Chart を使用して Kubernetes クラスターに ScalarDB Cluster をデプロイする + +1. 次のコマンドを実行して Scalar Helm Charts リポジトリを追加します。 + + ```console + helm repo add scalar-labs https://scalar-labs.github.io/helm-charts + ``` + +2. ライセンスキーと証明書を環境変数として設定します。ライセンスキーがない場合は、[お問い合わせ](https://www.scalar-labs.com/contact)ください。`` の値の詳細については、[製品ライセンスキーの設定方法](../scalar-licensing/README.mdx)を参照してください。 + + ```console + SCALAR_DB_CLUSTER_LICENSE_KEY='' + SCALAR_DB_CLUSTER_LICENSE_CHECK_CERT_PEM='' + ``` + +3. 次のコマンドを実行して、ScalarDB Cluster のカスタム値ファイル (`scalardb-cluster-custom-values.yaml`) を作成します。 + + ```console + cat << 'EOF' > scalardb-cluster-custom-values.yaml + envoy: + enabled: true + service: + type: "LoadBalancer" + + scalardbCluster: + + image: + repository: "ghcr.io/scalar-labs/scalardb-cluster-node-byol-premium" + + scalardbClusterNodeProperties: | + # ScalarDB Cluster configurations + scalar.db.cluster.membership.type=KUBERNETES + scalar.db.cluster.membership.kubernetes.endpoint.namespace_name=${env:SCALAR_DB_CLUSTER_MEMBERSHIP_KUBERNETES_ENDPOINT_NAMESPACE_NAME} + scalar.db.cluster.membership.kubernetes.endpoint.name=${env:SCALAR_DB_CLUSTER_MEMBERSHIP_KUBERNETES_ENDPOINT_NAME} + + # Storage configurations + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:postgresql://postgresql-scalardb-cluster.default.svc.cluster.local:5432/postgres + scalar.db.username=${env:SCALAR_DB_CLUSTER_POSTGRES_USERNAME} + scalar.db.password=${env:SCALAR_DB_CLUSTER_POSTGRES_PASSWORD} + + # For ScalarDB Cluster GraphQL tutorial. + scalar.db.graphql.enabled=true + + # For ScalarDB Cluster SQL tutorial. + scalar.db.sql.enabled=true + + ### License key configurations + scalar.db.cluster.node.licensing.license_key=${env:SCALAR_DB_CLUSTER_LICENSE_KEY} + scalar.db.cluster.node.licensing.license_check_cert_pem=${env:SCALAR_DB_CLUSTER_LICENSE_CHECK_CERT_PEM} + graphql: + enabled: true + service: + type: "LoadBalancer" + + secretName: "scalardb-credentials-secret" + EOF + ``` + +:::note + + このガイドでは、ScalarDB Cluster GraphQL および Envoy のサービスタイプは `LoadBalancer` に設定されています。 + +::: + +4. 資格情報とライセンスキーを含む `scalardb-credentials-secret` という名前のシークレットリソースを作成します。 + + ```console + kubectl create secret generic scalardb-credentials-secret \ + --from-literal=SCALAR_DB_CLUSTER_POSTGRES_USERNAME=postgres \ + --from-literal=SCALAR_DB_CLUSTER_POSTGRES_PASSWORD=postgres \ + --from-literal=SCALAR_DB_CLUSTER_LICENSE_KEY="${SCALAR_DB_CLUSTER_LICENSE_KEY}" \ + --from-file=SCALAR_DB_CLUSTER_LICENSE_CHECK_CERT_PEM=<(echo ${SCALAR_DB_CLUSTER_LICENSE_CHECK_CERT_PEM} | sed 's/\\n/\ + /g') \ + -n default + ``` + +5. ScalarDB Cluster のチャートバージョンを設定します。 + + ```console + SCALAR_DB_CLUSTER_VERSION=3.14.0 + SCALAR_DB_CLUSTER_CHART_VERSION=$(helm search repo scalar-labs/scalardb-cluster -l | grep -F "${SCALAR_DB_CLUSTER_VERSION}" | awk '{print $2}' | sort --version-sort -r | head -n 1) + ``` + +6. ScalarDB Cluster をデプロイします。 + + ```console + helm install scalardb-cluster scalar-labs/scalardb-cluster -f scalardb-cluster-custom-values.yaml --version ${SCALAR_DB_CLUSTER_CHART_VERSION} -n default + ``` + +7. ScalarDB Cluster ポッドがデプロイされているかどうかを確認します。 + + ```console + kubectl get pod + ``` + + 次の出力が表示されます。 + + ```console + NAME READY STATUS RESTARTS AGE + postgresql-scalardb-cluster-0 1/1 Running 0 84s + scalardb-cluster-envoy-59899dc588-477tg 1/1 Running 0 35s + scalardb-cluster-envoy-59899dc588-dpvhx 1/1 Running 0 35s + scalardb-cluster-envoy-59899dc588-lv9hx 1/1 Running 0 35s + scalardb-cluster-node-866c756c79-5v2tk 1/1 Running 0 35s + scalardb-cluster-node-866c756c79-9zhq5 1/1 Running 0 35s + scalardb-cluster-node-866c756c79-t6v86 1/1 Running 0 35s + ``` + + ScalarDB Cluster Node Pod と Envoy Pod が適切にデプロイされている場合、各 Pod の `STATUS` は `Running` になります。 + +6. 次のコマンドを実行して、ScalarDB Cluster のサービスリソースがデプロイされているかどうかを確認します。 + + ```console + kubectl get svc + ``` + + 次の出力が表示されます。 + + ```console + NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE + kubernetes ClusterIP 10.96.0.1 443/TCP 260d + postgresql-scalardb-cluster ClusterIP 10.110.97.40 5432/TCP 86s + postgresql-scalardb-cluster-hl ClusterIP None 5432/TCP 86s + scalardb-cluster-envoy LoadBalancer 10.105.121.51 localhost 60053:30641/TCP 49s + scalardb-cluster-envoy-metrics ClusterIP 10.111.131.189 9001/TCP 49s + scalardb-cluster-graphql LoadBalancer 10.105.74.214 localhost 8080:30514/TCP 49s + scalardb-cluster-headless ClusterIP None 60053/TCP 49s + scalardb-cluster-metrics ClusterIP 10.110.132.22 9080/TCP 49s + ``` + + ScalarDB Cluster と Envoy のサービスリソースが適切にデプロイされている場合、`CLUSTER-IP` 列にプライベート IP アドレスが表示されます。 + + :::note + + `scalardb-cluster-headless` には `CLUSTER-IP` アドレスがありません。 + + ::: + + また、`TYPE` が `LoadBalancer` に設定されている ScalarDB Cluster GraphQL (`scalardb-cluster-graphql`) のサービスリソースと Envoy (`scalardb-cluster-envoy`) のサービスリソースに割り当てられた `EXTERNAL-IP` アドレスも確認できます。 + + また、環境から `LoadBalancer` サービスにアクセスする方法は、Kubernetes ディストリビューションごとに異なります。例: + + - minikube を使用している場合は、[`minikube tunnel` コマンド](https://minikube.sigs.k8s.io/docs/commands/tunnel/)を使用できます。 + - kind を使用している場合は、[Cloud Provider KIND](https://kind.sigs.k8s.io/docs/user/loadbalancer/) を使用できます。 + + `LoadBalancer` サービスにアクセスする方法の詳細については、使用している Kubernetes ディストリビューションの公式ドキュメントを参照してください。 + +## すべてのリソースを削除する + +以下のコマンドを実行すると、このガイドで作成したすべてのリソースを削除できます。 + +```console +helm uninstall scalardb-cluster postgresql-scalardb-cluster +``` + +## 詳細 + +ScalarDB Cluster の他のユースケースについて詳しく知るには、次のチュートリアルをお試しください。 + +- [ScalarDB Cluster をはじめよう](getting-started-with-scalardb-cluster.mdx) +- [ScalarDB Cluster GraphQL をはじめよう](getting-started-with-scalardb-cluster-graphql.mdx) +- [JDBC 経由の ScalarDB Cluster SQL をはじめよう](getting-started-with-scalardb-cluster-sql-jdbc.mdx) +- [Spring Data JDBC for ScalarDB を使用した ScalarDB Cluster SQL をはじめよう](getting-started-with-scalardb-cluster-sql-spring-data-jdbc.mdx) diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/standalone-mode.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/standalone-mode.mdx new file mode 100644 index 00000000..ee166bde --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/standalone-mode.mdx @@ -0,0 +1,238 @@ +--- +tags: + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Cluster スタンドアロンモード + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import WarningLicenseKeyContact from '/src/components/ja-jp/_warning-license-key-contact.mdx'; + + + +Kubernetes クラスターをセットアップし、Helm Chart を使用してその上に ScalarDB Cluster をデプロイする代わりに、ScalarDB Cluster をスタンドアロンモードで実行できます。これにより、開発プロセスとテストプロセスが簡素化されます。この主な使用例は、ローカルマシン上の Docker を介して ScalarDB Cluster をスタンドアロンモードで起動し、開発とテストに使用する場合です。 + +ScalarDB Cluster をスタンドアロンモードで実行するには、`scalar.db.cluster.node.standalone_mode.enabled` プロパティを `true` に設定する必要があります。 + +```properties +scalar.db.cluster.node.standalone_mode.enabled=true +``` + +## Docker Compose で ScalarDB Cluster をスタンドアロンモードで実行 + +このセクションでは、Docker Compose で ScalarDB Cluster をスタンドアロンモードで起動する方法について説明します。 + + + +### ScalarDB サンプルリポジトリのクローンを作成する + +**ターミナル** を開き、次のコマンドを実行して ScalarDB サンプルリポジトリのクローンを作成します。 + +```console +git clone https://github.com/scalar-labs/scalardb-samples +``` + +次に、次のコマンドを実行して、必要なファイルが含まれているディレクトリに移動します。 + +```console +cd scalardb-samples/scalardb-cluster-standalone-mode/ +``` + +### ScalarDB Cluster 用にデータベースをセットアップする + +データベースを選択し、指示に従って ScalarDB Cluster 用に構成します。 + +ScalarDB がサポートするデータベースの一覧については、[データベース](../requirements.mdx#databases)を参照してください。 + + + +

MySQL をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で MySQL を実行できます。 + + MySQL を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d mysql + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の MySQL のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For MySQL + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:mysql://mysql-1:3306/ + scalar.db.username=root + scalar.db.password=mysql + ``` + + +

PostgreSQL をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で PostgreSQL を実行できます。 + + PostgreSQL を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d postgres + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の PostgreSQL のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For PostgreSQL + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:postgresql://postgres-1:5432/ + scalar.db.username=postgres + scalar.db.password=postgres + ``` + + +

Oracle Database をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で Oracle Database を実行できます。 + + Oracle Database を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d oracle + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の Oracle データベースのプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For Oracle + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:oracle:thin:@//oracle-1:1521/FREEPDB1 + scalar.db.username=SYSTEM + scalar.db.password=Oracle + ``` + + +

SQL Server をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で SQL Server を実行できます。 + + SQL Server を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d sqlserver + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の SQL Server のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For SQL Server + scalar.db.storage=jdbc + scalar.db.contact_points=jdbc:sqlserver://sqlserver-1:1433;encrypt=true;trustServerCertificate=true + scalar.db.username=sa + scalar.db.password=SqlServer22 + ``` + + +

Amazon DynamoDB Local を実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で Amazon DynamoDB Local を実行できます。 + + Amazon DynamoDB Local を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d dynamodb + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の Amazon DynamoDB Local のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For DynamoDB Local + scalar.db.storage=dynamo + scalar.db.contact_points=sample + scalar.db.username=sample + scalar.db.password=sample + scalar.db.dynamo.endpoint_override=http://dynamodb-1:8000 + ``` + + + Azure Cosmos DB for NoSQL を使用するには、Azure アカウントが必要です。Azure アカウントがない場合は、[Azure Cosmos DB アカウントを作成する](https://learn.microsoft.com/ja-jp/azure/cosmos-db/nosql/quickstart-portal#create-account)にアクセスしてください。 + +

Cosmos DB for NoSQL を構成する

+ + [既定の整合性レベルを構成する](https://learn.microsoft.com/ja-jp/azure/cosmos-db/nosql/how-to-manage-consistency#configure-the-default-consistency-level)の公式ドキュメントに従って、**既定の整合性レベル** を **強力** に設定します。 + +

ScalarDB Cluster を構成する

+ + 次の手順では、ローカル環境に JDK が適切にインストールおよび構成されており、Azure で Cosmos DB for NoSQL アカウントが適切に構成されていることを前提としています。 + + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。説明に従って、`scalar.db.contact_points` と `scalar.db.password` の値を必ず変更してください。 + + ```properties + # For Cosmos DB + scalar.db.storage=cosmos + scalar.db.contact_points= + scalar.db.password= + ``` + +:::note + +Azure Cosmos DB アカウントのプライマリーキーまたはセカンダリキーを `scalar.db.password` の値として使用できます。 + +::: + + +

Cassandra をローカルで実行する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの `docker-compose.yaml` ファイルを使用して、Docker Compose で Apache Cassandra を実行できます。 + + Apache Cassandra を起動するには、次のコマンドを実行します。 + + ```console + docker compose up -d cassandra + ``` + +

ScalarDB Cluster を構成する

+ + `scalardb-samples/scalardb-cluster-standalone-mode` ディレクトリの **scalardb-cluster-node.properties** ファイルには、ScalarDB Cluster のデータベース構成が含まれています。**scalardb-cluster-node.properties** ファイル内の Cassandra のプロパティのコメントを解除して、構成が次のようになるようにしてください。 + + ```properties + # For Cassandra + scalar.db.storage=cassandra + scalar.db.contact_points=cassandra-1 + scalar.db.username=cassandra + scalar.db.password=cassandra + ``` + + + +### ライセンスキーを設定する + +構成ファイル `scalardb-cluster-node.properties` で、ScalarDB Cluster のライセンスキー (試用ライセンスまたは商用ライセンス) を設定します。詳細については、[製品ライセンスキーの設定方法](../scalar-licensing/README.mdx) を参照してください。 + +### スタンドアロンモードで ScalarDB Cluster を起動する + +スタンドアロンモードで ScalarDB Cluster を起動するには、次のコマンドを実行します。 + +:::note + +ScalarDB Cluster のその他の設定を変更する場合は、以下のコマンドを実行する前に `scalardb-cluster-node.properties` ファイルを更新してください。 + +::: + +```console +docker compose up -d scalardb-cluster-node +``` + +## ScalarDB Cluster Java API のクライアント構成 + +`indirect` クライアントモードを使用して、スタンドアロンモードで ScalarDB Cluster に接続できます。ScalarDB Cluster Java API のクライアント構成の詳細については、[Java API を使用した ScalarDB Cluster の開発者ガイド](developer-guide-for-scalardb-cluster-with-java-api.mdx) を参照してください。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/standalone-mode/docker-compose.yaml b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/standalone-mode/docker-compose.yaml new file mode 100644 index 00000000..005e1608 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/standalone-mode/docker-compose.yaml @@ -0,0 +1,28 @@ +version: "3.5" +services: + + postgresql: + container_name: "postgresql" + image: "postgres:15" + ports: + - 5432:5432 + environment: + - POSTGRES_PASSWORD=postgres + healthcheck: + test: ["CMD-SHELL", "pg_isready || exit 1"] + interval: 1s + timeout: 10s + retries: 60 + start_period: 30s + + scalardb-cluster-standalone: + container_name: "scalardb-cluser-node" + image: "ghcr.io/scalar-labs/scalardb-cluster-node:4.0.0-SNAPSHOT" + ports: + - 60053:60053 + - 9080:9080 + volumes: + - ./scalardb-cluster-node.properties:/scalardb-cluster/node/scalardb-cluster-node.properties + depends_on: + postgresql: + condition: service_healthy diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/standalone-mode/scalardb-cluster-node.properties b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/standalone-mode/scalardb-cluster-node.properties new file mode 100644 index 00000000..6ec8f9a0 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/standalone-mode/scalardb-cluster-node.properties @@ -0,0 +1,5 @@ +scalar.db.storage=jdbc +scalar.db.contact_points=jdbc:postgresql://postgresql:5432/postgres +scalar.db.username=postgres +scalar.db.password=postgres +scalar.db.cluster.node.standalone_mode.enabled=true diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-core-status-codes.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-core-status-codes.mdx new file mode 100644 index 00000000..3b25878c --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-core-status-codes.mdx @@ -0,0 +1,1783 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB エラーコード + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このページでは、ScalarDB のエラーコードの一覧を示します。 + +## エラーコードのクラスと説明 + +| クラス | 説明 | +|:-------------|:----------------------------------------------| +| `CORE-1xxxx` | ユーザーエラーカテゴリのエラー | +| `CORE-2xxxx` | 同時実行エラーカテゴリのエラー | +| `CORE-3xxxx` | 内部エラーカテゴリのエラー | +| `CORE-4xxxx` | 不明なトランザクションステータスエラーカテゴリのエラー | + +## `CORE-1xxxx` ステータスコード + +### `CORE-10000` + +**メッセージ** + +```markdown +Only a single-column index is supported. Operation: %s +``` + +### `CORE-10001` + +**メッセージ** + +```markdown +The column of the specified index key is not indexed. Operation: %s +``` + +### `CORE-10002` + +**メッセージ** + +```markdown +The index key is not properly specified. Operation: %s +``` + +### `CORE-10003` + +**メッセージ** + +```markdown +Clustering keys cannot be specified when using an index. Operation: %s +``` + +### `CORE-10004` + +**メッセージ** + +```markdown +Orderings cannot be specified when using an index. Operation: %s +``` + +### `CORE-10005` + +**メッセージ** + +```markdown +The limit cannot be negative. Operation: %s +``` + +### `CORE-10006` + +**メッセージ** + +```markdown +Cross-partition scan is not enabled. Operation: %s +``` + +### `CORE-10007` + +**メッセージ** + +```markdown +Cross-partition scan ordering is not enabled. Operation: %s +``` + +### `CORE-10008` + +**メッセージ** + +```markdown +Cross-partition scan filtering is not enabled. Operation: %s +``` + +### `CORE-10009` + +**メッセージ** + +```markdown +The specified projection is not found. Projection: %s, Operation: %s +``` + +### `CORE-10010` + +**メッセージ** + +```markdown +The clustering key boundary is not properly specified. Operation: %s +``` + +### `CORE-10011` + +**メッセージ** + +```markdown +The start clustering key is not properly specified. Operation: %s +``` + +### `CORE-10012` + +**メッセージ** + +```markdown +The end clustering key is not properly specified. Operation: %s +``` + +### `CORE-10013` + +**メッセージ** + +```markdown +Orderings are not properly specified. Operation: %s +``` + +### `CORE-10014` + +**メッセージ** + +```markdown +The specified ordering column is not found. Ordering: %s, Operation: %s +``` + +### `CORE-10015` + +**メッセージ** + +```markdown +The condition is not properly specified. Operation: %s +``` + +### `CORE-10016` + +**メッセージ** + +```markdown +The table does not exist. Table: %s +``` + +### `CORE-10017` + +**メッセージ** + +```markdown +The column value is not properly specified. Column: %s, Operation: %s +``` + +### `CORE-10018` + +**メッセージ** + +```markdown +The mutations are empty +``` + +### `CORE-10019` + +**メッセージ** + +```markdown +Mutations that span multiple partitions are not supported. Mutations: %s +``` + +### `CORE-10020` + +**メッセージ** + +```markdown +The partition key is not properly specified. Operation: %s +``` + +### `CORE-10021` + +**メッセージ** + +```markdown +The clustering key is not properly specified. Operation: %s +``` + +### `CORE-10022` + +**メッセージ** + +```markdown +The encryption feature is not enabled. To encrypt data at rest, you must enable this feature. Note that this feature is supported only in the ScalarDB Enterprise edition +``` + +### `CORE-10023` + +**メッセージ** + +```markdown +This condition is not allowed for the PutIf operation. Condition: %s +``` + +### `CORE-10024` + +**メッセージ** + +```markdown +This condition is not allowed for the DeleteIf operation. Condition: %s +``` + +### `CORE-10025` + +**メッセージ** + +```markdown +Operator must be LIKE or NOT_LIKE. Operator: %s +``` + +### `CORE-10026` + +**メッセージ** + +```markdown +An escape character must be a string of a single character or an empty string +``` + +### `CORE-10027` + +**メッセージ** + +```markdown +The LIKE pattern must not be null +``` + +### `CORE-10028` + +**メッセージ** + +```markdown +The LIKE pattern must not include only an escape character +``` + +### `CORE-10029` + +**メッセージ** + +```markdown +The LIKE pattern must not end with an escape character +``` + +### `CORE-10030` + +**メッセージ** + +```markdown +The column %s does not exist +``` + +### `CORE-10031` + +**メッセージ** + +```markdown +This operation is not supported when getting records of a database without using an index +``` + +### `CORE-10032` + +**メッセージ** + +```markdown +This operation is not supported when getting records of a database by using an index +``` + +### `CORE-10033` + +**メッセージ** + +```markdown +This operation is not supported when scanning all the records of a database or scanning records of a database by using an index +``` + +### `CORE-10034` + +**メッセージ** + +```markdown +This operation is supported only when scanning records of a database by using an index +``` + +### `CORE-10035` + +**メッセージ** + +```markdown +This operation is not supported when scanning records of a database by using an index +``` + +### `CORE-10037` + +**メッセージ** + +```markdown +This operation is supported only when no conditions are specified. If you want to modify a condition, please use clearConditions() to remove all existing conditions first +``` + +### `CORE-10038` + +**メッセージ** + +```markdown +One or more columns must be specified. +``` + +### `CORE-10039` + +**メッセージ** + +```markdown +One or more partition keys must be specified. +``` + +### `CORE-10040` + +**メッセージ** + +```markdown +The column definition must be specified since %s is specified as a partition key +``` + +### `CORE-10041` + +**メッセージ** + +```markdown +The column definition must be specified since %s is specified as a clustering key +``` + +### `CORE-10042` + +**メッセージ** + +```markdown +Invalid ID specified. ID: %d +``` + +### `CORE-10043` + +**メッセージ** + +```markdown +The transaction is not active. Status: %s +``` + +### `CORE-10044` + +**メッセージ** + +```markdown +The transaction has already been committed or rolled back. Status: %s +``` + +### `CORE-10045` + +**メッセージ** + +```markdown +The transaction has not been prepared. Status: %s +``` + +### `CORE-10046` + +**メッセージ** + +```markdown +The transaction has not been prepared or validated. Status: %s +``` + +### `CORE-10047` + +**メッセージ** + +```markdown +The transaction already exists +``` + +### `CORE-10048` + +**メッセージ** + +```markdown +A transaction associated with the specified transaction ID is not found. The transaction might have expired +``` + +### `CORE-10049` + +**メッセージ** + +```markdown +%s is the system namespace name +``` + +### `CORE-10050` + +**メッセージ** + +```markdown +The namespace already exists. Namespace: %s +``` + +### `CORE-10051` + +**メッセージ** + +```markdown +The namespace does not exist. Namespace: %s +``` + +### `CORE-10052` + +**メッセージ** + +```markdown +The table already exists. Table: %s +``` + +### `CORE-10053` + +**メッセージ** + +```markdown +The namespace is not empty. Namespace: %s; Tables in the namespace: %s +``` + +### `CORE-10054` + +**メッセージ** + +```markdown +The column does not exist. Table: %s; Column: %s +``` + +### `CORE-10055` + +**メッセージ** + +```markdown +The index already exists. Table: %s; Column: %s +``` + +### `CORE-10056` + +**メッセージ** + +```markdown +The index does not exist. Table: %s; Column: %s +``` + +### `CORE-10057` + +**メッセージ** + +```markdown +The column already exists. Table: %s; Column: %s +``` + +### `CORE-10058` + +**メッセージ** + +```markdown +The operation does not have the target namespace or table name. Operation: %s +``` + +### `CORE-10059` + +**メッセージ** + +```markdown +The specified value of the property '%s' is not a number. Value: %s +``` + +### `CORE-10060` + +**メッセージ** + +```markdown +The specified value of the property '%s' is not a boolean. Value: %s +``` + +### `CORE-10061` + +**メッセージ** + +```markdown +Reading the file failed. File: %s +``` + +### `CORE-10062` + +**メッセージ** + +```markdown +The property 'scalar.db.cross_partition_scan.enabled' must be set to true to use cross-partition scan with filtering or ordering +``` + +### `CORE-10063` + +**メッセージ** + +```markdown +This column value is out of range for BigInt. Value: %s +``` + +### `CORE-10064` + +**メッセージ** + +```markdown +This type is not supported. Name: %s, Type: %s +``` + +### `CORE-10065` + +**メッセージ** + +```markdown +Storage '%s' is not found +``` + +### `CORE-10066` + +**メッセージ** + +```markdown +Transaction manager '%s' is not found +``` + +### `CORE-10068` + +**メッセージ** + +```markdown +Please use scan() for non-exact match selection. Operation: %s +``` + +### `CORE-10069` + +**メッセージ** + +```markdown +Import-related functionality is not supported in Cassandra +``` + +### `CORE-10070` + +**メッセージ** + +```markdown +The %s network strategy does not exist +``` + +### `CORE-10071` + +**メッセージ** + +```markdown +The property 'scalar.db.contact_port' must be greater than or equal to zero +``` + +### `CORE-10073` + +**メッセージ** + +```markdown +The BLOB type is not supported for clustering keys in Cosmos DB. Column: %s +``` + +### `CORE-10074` + +**メッセージ** + +```markdown +Import-related functionality is not supported in Cosmos DB +``` + +### `CORE-10075` + +**メッセージ** + +```markdown +The property 'scalar.db.contact_points' must not be empty +``` + +### `CORE-10076` + +**メッセージ** + +```markdown +Cosmos DB supports only EQ, NE, IS_NULL, and IS_NOT_NULL operations for the BLOB type in conditions. Mutation: %s +``` + +### `CORE-10077` + +**メッセージ** + +```markdown +The specified consistency level is not supported. Consistency level: %s +``` + +### `CORE-10078` + +**メッセージ** + +```markdown +0x00 bytes are not accepted in BLOB values in DESC order +``` + +### `CORE-10079` + +**メッセージ** + +```markdown +Cannot encode a Text value that contains '\u0000' +``` + +### `CORE-10081` + +**メッセージ** + +```markdown +An index column cannot be set to null or an empty value for Text or Blob in DynamoDB. Operation: %s +``` + +### `CORE-10082` + +**メッセージ** + +```markdown +DynamoDB supports only EQ, NE, IS_NULL, and IS_NOT_NULL operations for the BOOLEAN type in conditions. Mutation: %s +``` + +### `CORE-10083` + +**メッセージ** + +```markdown +Nested multi-storage definitions are not supported. Storage: %s +``` + +### `CORE-10084` + +**メッセージ** + +```markdown +Storage not found. Storage: %s +``` + +### `CORE-10085` + +**メッセージ** + +```markdown +The namespace name is not acceptable. Namespace: %s +``` + +### `CORE-10086` + +**メッセージ** + +```markdown +The table name is not acceptable. Table: %s +``` + +### `CORE-10087` + +**メッセージ** + +```markdown +Importing tables is not allowed in the RDB engine. RDB engine: %s +``` + +### `CORE-10088` + +**メッセージ** + +```markdown +The %s table must have a primary key +``` + +### `CORE-10089` + +**メッセージ** + +```markdown +The RDB engine is not supported. JDBC connection URL: %s +``` + +### `CORE-10090` + +**メッセージ** + +```markdown +Data type %s(%d) is not supported: %s +``` + +### `CORE-10091` + +**メッセージ** + +```markdown +Data type %s is not supported: %s +``` + +### `CORE-10092` + +**メッセージ** + +```markdown +Getting a transaction state is not supported in JDBC transactions +``` + +### `CORE-10093` + +**メッセージ** + +```markdown +Rolling back a transaction is not supported in JDBC transactions +``` + +### `CORE-10094` + +**メッセージ** + +```markdown +Coordinator tables already exist +``` + +### `CORE-10095` + +**メッセージ** + +```markdown +Coordinator tables do not exist +``` + +### `CORE-10096` + +**メッセージ** + +```markdown +The namespace %s is reserved. Any operations on this namespace are not allowed +``` + +### `CORE-10097` + +**メッセージ** + +```markdown +Mutating transaction metadata columns is not allowed. Table: %s; Column: %s +``` + +### `CORE-10098` + +**メッセージ** + +```markdown +A %s condition is not allowed on Put operations +``` + +### `CORE-10099` + +**メッセージ** + +```markdown +A %s condition is not allowed on Delete operations +``` + +### `CORE-10100` + +**メッセージ** + +```markdown +The condition is not allowed to target transaction metadata columns. Column: %s +``` + +### `CORE-10101` + +**メッセージ** + +```markdown +The column '%s' is reserved as transaction metadata +``` + +### `CORE-10102` + +**メッセージ** + +```markdown +Non-primary key columns with the 'before_' prefix, '%s', are reserved as transaction metadata +``` + +### `CORE-10103` + +**メッセージ** + +```markdown +Put cannot have a condition when the target record is unread and implicit pre-read is disabled. Please read the target record beforehand or enable implicit pre-read: %s +``` + +### `CORE-10104` + +**メッセージ** + +```markdown +Writing already-deleted data is not allowed +``` + +### `CORE-10105` + +**メッセージ** + +```markdown +Getting data neither in the read set nor the delete set is not allowed +``` + +### `CORE-10106` + +**メッセージ** + +```markdown +Reading already-written data is not allowed +``` + +### `CORE-10107` + +**メッセージ** + +```markdown +The transaction is not validated. When using the EXTRA_READ serializable strategy, you need to call validate() before calling commit() +``` + +### `CORE-10108` + +**メッセージ** + +```markdown +DynamoDB cannot batch more than 100 mutations at once +``` + +### `CORE-10109` + +**メッセージ** + +```markdown +The partition keys of the table %s.%s were modified, but altering partition keys is not supported +``` + +### `CORE-10110` + +**メッセージ** + +```markdown +The clustering keys of the table %s.%s were modified, but altering clustering keys is not supported +``` + +### `CORE-10111` + +**メッセージ** + +```markdown +The clustering ordering of the table %s.%s were modified, but altering clustering ordering is not supported +``` + +### `CORE-10112` + +**メッセージ** + +```markdown +The column %s of the table %s.%s has been deleted. Column deletion is not supported when altering a table +``` + +### `CORE-10113` + +**メッセージ** + +```markdown +The data type of the column %s of the table %s.%s was modified, but altering data types is not supported +``` + +### `CORE-10114` + +**メッセージ** + +```markdown +Specifying the '--schema-file' option is required when using the '--repair-all' option +``` + +### `CORE-10115` + +**メッセージ** + +```markdown +Specifying the '--schema-file' option is required when using the '--alter' option +``` + +### `CORE-10116` + +**メッセージ** + +```markdown +Specifying the '--schema-file' option is required when using the '--import' option +``` + +### `CORE-10117` + +**メッセージ** + +```markdown +Specifying the '--coordinator' option with the '--import' option is not allowed. Create Coordinator tables separately +``` + +### `CORE-10118` + +**メッセージ** + +```markdown +Reading the configuration file failed. File: %s +``` + +### `CORE-10119` + +**メッセージ** + +```markdown +Reading the schema file failed. File: %s +``` + +### `CORE-10120` + +**メッセージ** + +```markdown +Parsing the schema JSON failed. Details: %s +``` + +### `CORE-10121` + +**メッセージ** + +```markdown +The table name must contain the namespace and the table. Table: %s +``` + +### `CORE-10122` + +**メッセージ** + +```markdown +The partition key must be specified. Table: %s +``` + +### `CORE-10123` + +**メッセージ** + +```markdown +Invalid clustering-key format. The clustering key must be in the format of 'column_name' or 'column_name ASC/DESC'. Table: %s; Clustering key: %s +``` + +### `CORE-10124` + +**メッセージ** + +```markdown +Columns must be specified. Table: %s +``` + +### `CORE-10125` + +**メッセージ** + +```markdown +Invalid column type. Table: %s; Column: %s; Type: %s +``` + +### `CORE-10126` + +**メッセージ** + +```markdown +The mutation type is not supported. Only the Put or Delete type is supported. Mutation: %s +``` + +### `CORE-10127` + +**メッセージ** + +```markdown +This condition is not allowed for the UpdateIf operation. Condition: %s +``` + +### `CORE-10128` + +**メッセージ** + +```markdown +Cross-partition scan with ordering is not supported in Cassandra +``` + +### `CORE-10129` + +**メッセージ** + +```markdown +Cross-partition scan with ordering is not supported in Cosmos DB +``` + +### `CORE-10130` + +**メッセージ** + +```markdown +Cross-partition scan with ordering is not supported in DynamoDB +``` + +### `CORE-10131` + +**メッセージ** + +```markdown +The directory '%s' does not have write permissions. Please ensure that the current user has write access to the directory. +``` + +### `CORE-10132` + +**メッセージ** + +```markdown +Failed to create the directory '%s'. Please check if you have sufficient permissions and if there are any file system restrictions. Details: %s +``` + +### `CORE-10133` + +**メッセージ** + +```markdown +Directory path cannot be null or empty. +``` + +### `CORE-10134` + +**メッセージ** + +```markdown +No file extension was found on the provided file name %s. +``` + +### `CORE-10135` + +**メッセージ** + +```markdown +Invalid file extension: %s. Allowed extensions are: %s +``` + +### `CORE-10136` + +**メッセージ** + +```markdown +Getting a transaction state is not supported in single CRUD operation transactions +``` + +### `CORE-10137` + +**メッセージ** + +```markdown +Rolling back a transaction is not supported in single CRUD operation transactions +``` + +### `CORE-10138` + +**メッセージ** + +```markdown +Multiple mutations are not supported in single CRUD operation transactions +``` + +### `CORE-10139` + +**メッセージ** + +```markdown +Beginning a transaction is not allowed in single CRUD operation transactions +``` + +### `CORE-10140` + +**メッセージ** + +```markdown +Resuming a transaction is not allowed in single CRUD operation transactions +``` + +### `CORE-10141` + +**メッセージ** + +```markdown +Using the group commit feature on the Coordinator table with a two-phase commit interface is not allowed +``` + +### `CORE-10142` + +**メッセージ** + +```markdown +This operation is supported only when no conditions are specified. If you want to modify a condition, please use clearConditions() to remove all existing conditions first +``` + +### `CORE-10143` + +**メッセージ** + +```markdown +ScalarDB Transparent Data Encryption is not enabled. To use ScalarDB Transparent Data Encryption, you must enable it. Note that this feature is supported only in the ScalarDB Enterprise edition +``` + +### `CORE-10144` + +**メッセージ** + +```markdown +The variable key column size must be greater than or equal to 64 +``` + +### `CORE-10145` + +**メッセージ** + +```markdown +The value of the column %s in the primary key contains an illegal character. Primary-key columns must not contain any of the following characters in Cosmos DB: ':', '/', '\', '#', '?'. Value: %s +``` + +## `CORE-2xxxx` ステータスコード + +### `CORE-20000` + +**メッセージ** + +```markdown +No mutation was applied +``` + +### `CORE-20001` + +**メッセージ** + +```markdown +Logging failed in the batch +``` + +### `CORE-20002` + +**メッセージ** + +```markdown +The operation failed in the batch with type %s +``` + +### `CORE-20003` + +**メッセージ** + +```markdown +An error occurred in the batch. Details: %s +``` + +### `CORE-20004` + +**メッセージ** + +```markdown +A Paxos phase in the CAS operation failed +``` + +### `CORE-20005` + +**メッセージ** + +```markdown +The learn phase in the CAS operation failed +``` + +### `CORE-20006` + +**メッセージ** + +```markdown +A simple write operation failed +``` + +### `CORE-20007` + +**メッセージ** + +```markdown +An error occurred in the mutation. Details: %s +``` + +### `CORE-20008` + +**メッセージ** + +```markdown +A RetryWith error occurred in the mutation. Details: %s +``` + +### `CORE-20009` + +**メッセージ** + +```markdown +A transaction conflict occurred in the mutation. Details: %s +``` + +### `CORE-20010` + +**メッセージ** + +```markdown +A transaction conflict occurred in the mutation. Details: %s +``` + +### `CORE-20011` + +**メッセージ** + +```markdown +A conflict occurred. Please try restarting the transaction. Details: %s +``` + +### `CORE-20012` + +**メッセージ** + +```markdown +The %s condition of the %s operation is not satisfied. Targeting column(s): %s +``` + +### `CORE-20013` + +**メッセージ** + +```markdown +The record being prepared already exists +``` + +### `CORE-20014` + +**メッセージ** + +```markdown +A conflict occurred when preparing records +``` + +### `CORE-20015` + +**メッセージ** + +```markdown +The committing state in the coordinator failed. The transaction has been aborted +``` + +### `CORE-20016` + +**メッセージ** + +```markdown +A conflict occurred during implicit pre-read +``` + +### `CORE-20017` + +**メッセージ** + +```markdown +This record needs to be recovered +``` + +### `CORE-20018` + +**メッセージ** + +```markdown +The record does not exist, so the %s condition is not satisfied +``` + +### `CORE-20019` + +**メッセージ** + +```markdown +The record exists, so the %s condition is not satisfied +``` + +### `CORE-20020` + +**メッセージ** + +```markdown +The condition on the column '%s' is not satisfied +``` + +### `CORE-20021` + +**メッセージ** + +```markdown +Reading empty records might cause a write skew anomaly, so the transaction has been aborted for safety purposes +``` + +### `CORE-20022` + +**メッセージ** + +```markdown +An anti-dependency was found. The transaction has been aborted +``` + +### `CORE-20023` + +**メッセージ** + +```markdown +A transaction conflict occurred in the Insert operation +``` + +### `CORE-20024` + +**メッセージ** + +```markdown +The %s condition of the %s operation is not satisfied. Targeting column(s): %s +``` + +### `CORE-20025` + +**メッセージ** + +```markdown +A transaction conflict occurred in the Insert operation +``` + +## `CORE-3xxxx` ステータスコード + +### `CORE-30000` + +**メッセージ** + +```markdown +Creating the namespace failed. Namespace: %s +``` + +### `CORE-30001` + +**メッセージ** + +```markdown +Dropping the namespace failed. Namespace: %s +``` + +### `CORE-30002` + +**メッセージ** + +```markdown +Creating the table failed. Table: %s +``` + +### `CORE-30003` + +**メッセージ** + +```markdown +Dropping the table failed. Table: %s +``` + +### `CORE-30004` + +**メッセージ** + +```markdown +Truncating the table failed. Table: %s +``` + +### `CORE-30005` + +**メッセージ** + +```markdown +Creating the index failed. Table: %s, Column: %s +``` + +### `CORE-30006` + +**メッセージ** + +```markdown +Dropping the index failed. Table: %s, Column: %s +``` + +### `CORE-30007` + +**メッセージ** + +```markdown +Getting the table metadata failed. Table: %s +``` + +### `CORE-30008` + +**メッセージ** + +```markdown +Getting the table names in the namespace failed. Namespace: %s +``` + +### `CORE-30009` + +**メッセージ** + +```markdown +Checking the namespace existence failed. Namespace: %s +``` + +### `CORE-30010` + +**メッセージ** + +```markdown +Checking the table existence failed. Table: %s +``` + +### `CORE-30011` + +**メッセージ** + +```markdown +Checking the index existence failed. Table: %s; Column: %s +``` + +### `CORE-30012` + +**メッセージ** + +```markdown +Repairing the namespace failed. Namespace: %s +``` + +### `CORE-30013` + +**メッセージ** + +```markdown +Repairing the table failed. Table: %s +``` + +### `CORE-30014` + +**メッセージ** + +```markdown +Adding a new column to the table failed. Table: %s; Column: %s; ColumnType: %s +``` + +### `CORE-30015` + +**メッセージ** + +```markdown +Getting the namespace names failed +``` + +### `CORE-30016` + +**メッセージ** + +```markdown +Getting the table metadata of the table being imported failed. Table: %s +``` + +### `CORE-30017` + +**メッセージ** + +```markdown +Importing the table failed. Table: %s +``` + +### `CORE-30018` + +**メッセージ** + +```markdown +Adding the raw column to the table failed. Table: %s; Column: %s; ColumnType: %s +``` + +### `CORE-30019` + +**メッセージ** + +```markdown +Upgrading the ScalarDB environment failed +``` + +### `CORE-30020` + +**メッセージ** + +```markdown +Something wrong because WriteType is neither CAS nor SIMPLE +``` + +### `CORE-30021` + +**メッセージ** + +```markdown +An error occurred in the selection. Details: %s +``` + +### `CORE-30022` + +**メッセージ** + +```markdown +An error occurred in the mutation. Details: %s +``` + +### `CORE-30023` + +**メッセージ** + +```markdown +An error occurred in the selection. Details: %s +``` + +### `CORE-30024` + +**メッセージ** + +```markdown +An error occurred in the mutation. Details: %s +``` + +### `CORE-30025` + +**メッセージ** + +```markdown +An error occurred in the selection. Details: %s +``` + +### `CORE-30026` + +**メッセージ** + +```markdown +An error occurred in the mutation. Details: %s +``` + +### `CORE-30027` + +**メッセージ** + +```markdown +An error occurred in the selection. Details: %s +``` + +### `CORE-30028` + +**メッセージ** + +```markdown +Fetching the next result failed +``` + +### `CORE-30029` + +**メッセージ** + +```markdown +Rolling back the transaction failed +``` + +### `CORE-30030` + +**メッセージ** + +```markdown +Committing the transaction failed. Details: %s +``` + +### `CORE-30031` + +**メッセージ** + +```markdown +The Get operation failed. Details: %s +``` + +### `CORE-30032` + +**メッセージ** + +```markdown +The Scan operation failed. Details: %s +``` + +### `CORE-30033` + +**メッセージ** + +```markdown +The Put operation failed. Details: %s +``` + +### `CORE-30034` + +**メッセージ** + +```markdown +The Delete operation failed. Details: %s +``` + +### `CORE-30035` + +**メッセージ** + +```markdown +Beginning a transaction failed. Details: %s +``` + +### `CORE-30036` + +**メッセージ** + +```markdown +Preparing records failed +``` + +### `CORE-30037` + +**メッセージ** + +```markdown +Validation failed +``` + +### `CORE-30038` + +**メッセージ** + +```markdown +Executing implicit pre-read failed +``` + +### `CORE-30039` + +**メッセージ** + +```markdown +Reading a record from the underlying storage failed +``` + +### `CORE-30040` + +**メッセージ** + +```markdown +Scanning records from the underlying storage failed +``` + +### `CORE-30041` + +**メッセージ** + +```markdown +Rollback failed because the transaction has already been committed +``` + +### `CORE-30042` + +**メッセージ** + +```markdown +Rollback failed +``` + +### `CORE-30043` + +**メッセージ** + +```markdown +The Insert operation failed. Details: %s +``` + +### `CORE-30044` + +**メッセージ** + +```markdown +The Upsert operation failed. Details: %s +``` + +### `CORE-30045` + +**メッセージ** + +```markdown +The Update operation failed. Details: %s +``` + +## `CORE-4xxxx` ステータスコード + +### `CORE-40000` + +**メッセージ** + +```markdown +Rolling back the transaction failed. Details: %s +``` + +### `CORE-40001` + +**メッセージ** + +```markdown +Committing state failed with NoMutationException, but the coordinator status does not exist +``` + +### `CORE-40002` + +**メッセージ** + +```markdown +The state cannot be retrieved +``` + +### `CORE-40003` + +**メッセージ** + +```markdown +The coordinator status is unknown +``` + +### `CORE-40004` + +**メッセージ** + +```markdown +Aborting state failed with NoMutationException, but the coordinator status does not exist +``` diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-data-loader/easy-to-start.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-data-loader/easy-to-start.mdx new file mode 100644 index 00000000..4866fce7 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-data-loader/easy-to-start.mdx @@ -0,0 +1,40 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB Data Loader API + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このドキュメントでは、ScalarDB Data Loader API を開始する方法について説明します。 + +## ScalarDB Data Loader API を起動します + +* `scalardb-data-loader` リポジトリをクローンします +``` +git clone https://github.com/scalar-labs/scalardb-data-loader.git +``` + +* `scalardb-data-loader` ディレクトリに移動します + +* 適切なクラウド認証情報を使用して、`fixtures/test/conf/application.yml` ファイル内の次のプロパティを更新します + * storage.jclouds.provider + * storage.jclouds.identity + * storage.jclouds.credential + * storage.jclouds.container + +* `scalardb-data-loader-api` Docker イメージをビルドします +``` +./gradlew :api:docker +``` + +* `scalardb-data-loader-api` を起動します +``` +cd fixtures/test +docker-compose up +``` diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-data-loader/getting-started-export.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-data-loader/getting-started-export.mdx new file mode 100644 index 00000000..bac1bdca --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-data-loader/getting-started-export.mdx @@ -0,0 +1,62 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# データのエクスポート + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このドキュメントでは、ScalarDB Data Loader のエクスポート機能について説明します。 + +## 機能 + +ScalarDB Data Loader を使用すると、次の形式でデータをエクスポートできます。 + +- JSON +- JSONLines +- CSV + +各エクスポートでは、Data Loader の実行時に指定された CLI 引数に基づいて ScalarDB スキャン操作が実行されます。 + +## 使用方法 + +Data Loader のエクスポート機能は、次の最小限の設定で開始できます。 + +```console +./scalardb-data-loader export --config scalardb.properties --namespace namespace --table tableName +``` + +- --config: 接続プロパティファイルへのパス +- --namespace: データを含むテーブルの名前空間 +- --table: データを含むテーブルの名前 + +デフォルトでは、`--output-file` 引数も省略されている場合、Data Loader は作業ディレクトリに出力ファイルを作成します。 + +### コマンドラインオプション + +ScalarDB Data Loader で使用できるオプションの一覧を次に示します。 + +| オプション | 説明 | 使用方法 | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | +| --config | 設定ファイルへのパス。省略すると、ツールは現在のフォルダーで `scalardb.properties` という名前のファイルを検索します。 | `scalardb-data-loader --config scalardb.properties` | +| --namespace | テーブルデータをエクスポートする名前空間。必須。 | `scalardb-data-loader --namespace namespace` | +| --table | データをエクスポートするテーブルの名前。必須。 | `scalardb-data-loader --table tableName` | +| --key | 特定のパーティションキーのデータをエクスポートします。デフォルトでは、指定されたテーブルのすべてのデータがエクスポートされます。 | `scalardb-data-loader --key columnName=value` | +| --sort | 並べ替える列を指定します。列はクラスタリングキーである必要があります。引数を繰り返して複数の並べ替えを行うことができます。このオプションは `--key` にのみ適用されます。 | `scalardb-data-loader --sort columnName=desc` | +| --projection | 投影を指定してエクスポートする列を制限します。引数を繰り返して複数の投影を指定できます。 | `scalardb-data-loader --projection columnName` | +| --start | スキャン開始をマークするクラスタリングキー。このオプションは `--key` にのみ適用されます。 | `scalardb-data-loader --start columnName=value` | +| --start-exclusive | スキャン開始が排他的かどうか。省略した場合、デフォルト値は `false` です。このオプションは `--key` にのみ適用されます。 | `scalardb-data-loader --start-exclusive` | +| --end | スキャン終了をマークするクラスタリングキー。このオプションは `--key` にのみ適用されます。 | `scalardb-data-loader --end columnName=value` | +| --end-exclusive | スキャン開始が排他的かどうか。省略した場合、デフォルト値は `false` です。このオプションは `--key` にのみ適用されます。 | `scalardb-data-loader --end-exclusive` | +| --limit | スキャンの結果を制限します。省略した場合、デフォルト値は `0` で、制限がないことを意味します。 | `scalardb-data-loader --limit 1000` | +| --output-file | 出力ファイルの名前とパス。省略した場合、ツールは現在のフォルダーに次の名前形式でファイルを保存します:
`export_namespace.tableName_timestamp.json` または `export_namespace.tableName_timestamp.csv`

出力フォルダーが存在する必要があります。dataloader は出力フォルダーを作成しません。 | `scalardb-data-loader --output-file ./out/output.json` | +| --format | 出力形式。デフォルトでは `json` が選択されます。 | `scalardb-data-loader --format json` | +| --metadata | `true` に設定すると、トランザクションメタデータがエクスポートに含まれます。デフォルトでは `false` に設定されています。 | `scalardb-data-loader --metadata` | +| --delimiter | CSV ファイルで使用される区切り文字。デフォルト値は `;` です。 | `scalardb-data-loader --delimiter ;` | +| --no-headers | CSV ファイルからヘッダー行を除外します。デフォルトは `false` です。 | `scalardb-data-loader --no-headers` | +| --threads | 同時処理のスレッド数。 | `scalardb-data-loader --threads 500` | diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-data-loader/getting-started-import.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-data-loader/getting-started-import.mdx new file mode 100644 index 00000000..e40d579d --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-data-loader/getting-started-import.mdx @@ -0,0 +1,276 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# データのインポート + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このドキュメントでは、ScalarDB Data Loader のインポート機能について説明します。 + +## 機能 + +- JSON または JSONLines ファイルからデータをインポート +- ソースフィールド名マッピングに基づく自動データマッピング +- JSON 制御ファイルによるカスタムデータマッピング +- 1 つのレコードまたは行から複数​​のテーブルにデータをインポート +- INSERT、UPDATE、UPSERT のサポート + +## 使用方法 + +Data Loader のインポート機能は、次の最小限の設定で開始できます: + +```console +./scalardb-data-loader import --config scalardb.properties --namespace namespace --table tableName +``` + +上記の設定により、制御ファイルが使用されず、データマッピングが自動的に適用されるインポートプロセスが開始されます。 + +新規または既存のデータを正常にインポートするには、次の手順を実行してください + +- インポートする必要があるデータを含むソースファイルを準備します。 + +- 適切なインポートモードを選択します。デフォルトでは、インポートは `upsert` モードで実行されます。つまり、新しい場合はデータが挿入され、パーティションキーやクラスタリングキーが見つかった場合は更新されます。その他のオプションは、`insert` モードまたは `update` モードです。 + +- データをインポートする正しい `namespace` および `table` 名を見つけます。 + +- 各データ行に対して `all required columns` チェックを実行するかどうかを決定します。有効にすると、列が欠落しているデータ行は失敗として扱われ、インポートされません。 + +- `success` および `failed` 出力ファイルのパス名を指定します。デフォルトでは、Data Loader は作業ディレクトリにファイルを作成します。 + +- JSON データを処理する場合、成功または失敗のログファイルの JSON 出力を `pretty print` にするかどうかを決定します。デフォルトでは、このオプションはパフォーマンスのために無効になっています + +- 必要に応じて `threads` 引数を指定してパフォーマンスを調整します + +- コマンドラインからインポートを実行して、データのインポートを開始します。実行中の ScalarDB インスタンスに応じて、ScalarDB Data Loader を正しい `storage` または `transaction` モードで実行してください。 + +### コマンドラインオプション + +ScalarDB Data Loader で使用できるオプションの一覧を次に示します。 + +| オプション | 説明 | 使用方法 | +|---------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------| +| --mode | ScalarDB の実行モード。省略した場合、デフォルト値は `storage` です。 | `scalardb-data-loader --mode transaction` | +| --config | 設定ファイルへのパス。省略した場合、ツールは現在のフォルダーで `scalardb.properties` という名前のファイルを検索します。 | `scalardb-data-loader --config scalardb.properties` | +| --namespace | テーブルデータをエクスポートする名前空間。制御ファイルが指定されていない場合は必須です。 | `scalardb-data-loader --namespace namespace` | +| --table | データをエクスポートするテーブルの名前。制御ファイルが指定されていない場合は必須です。 | `scalardb-data-loader --table tableName` | +| --import-mode | ScalarDB テーブルにデータをインポートするモード。サポートされているモードは `insert`、`update`、および `upsert` です。オプション。デフォルトでは、値は `upsert` に設定されています。 | `scalardb-data-loader --import-mode=upsert` | +| --all-columns-required | 設定されている場合、列が欠落しているデータ行はインポートできません。オプションです。デフォルトでは、チェックは実行されません。 | `scalardb-data-loader --all-columns-required` | +| --file | インポートするファイルへのパスを指定します。必須。 | `scalardb-data-loader --file ` | +| --success | 成功したインポート結果を書き込むために作成されるファイルへのパス。成功したインポート結果と失敗したインポート結果は、両方とも別のファイルに書き込まれます。
オプションです。デフォルトでは、現在の作業ディレクトリに新しいファイルが作成されます。

注: ファイルが既に存在する場合は、上書きされます。 | `scalardb-data-loader --success ` | +| --failed | 失敗したインポート結果を書き込むために作成されるファイルへのパス。
オプション。デフォルトでは、現在の作業ディレクトリに新しいファイルが作成されます。

注: ファイルがすでに存在する場合は、上書きされます。 | `scalardb-data-loader --failed ` | +| --threads | 同時処理のスレッド数。 | `scalardb-data-loader --threads 500` | +| --format | インポートファイルの形式。`json` および `jsonl` ファイルがサポートされています。オプション。デフォルトでは値 `json` が選択されます。 | `scalardb-data-loader --format json` | +| --ignore-null | ソースファイル内の null 値は無視されます。つまり、既存のデータは上書きされません。オプション。デフォルトでは値は `false` です。 | `scalardb-data-loader --ignore-null` | +| --pretty | 設定すると、成功ファイルと失敗ファイルへの出力は `pretty print` モードで行われます。デフォルトでは、このオプションは有効になっていません。 | `scalardb-data-loader --pretty` | +| --control-file | カスタムデータマッピングやマルチテーブルインポートのルールを指定する JSON 制御ファイルへのパス。 | `scalardb-data-loader --control-file control.json` | +| --control-file-validation-level | 制御ファイルの検証レベル。`MAPPED`、`KEYS`、または` FULL`。

オプションで、デフォルトではレベルは `MAPPED` に設定されています。 | `scalardb-data-loader --control-file-validation-level FULL` | +| --log-put-value | ScalarDB `PUT` 操作で使用された値がログファイルに含まれるかどうか。
オプションで、デフォルトでは無効になっています。 | `scalardb-data-loader --log-put-value` | +| --error-file-required | インポートファイルに CSV データが含まれている場合に、オプションの JSON タイプのエラーファイルをエクスポートします。デフォルトでは、このオプションは無効になっています。 | `scalardb-data-loader --error-file-required` | +| --error | インポートファイルに CSV データが含まれている場合に、オプションのエラーファイルを指定します。 | `scalardb-data-loader --error ` | +| --delimiter | インポートファイルに CSV データが含まれている場合に、カスタム区切り文字を指定します。 | `scalardb-data-loader --delimiter ` | +| --header | インポートファイルに CSV データが含まれていて、ヘッダー行がない場合に、ヘッダー行データを指定します。 | `scalardb-data-loader --header ` | + +## インポートモード + +Data Loader は、次のインポートモードをサポートしています: + +| モード | 説明 | +| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| INSERT | 各ソースレコードは新しいデータとして扱われます。パーティションとクラスタリングキーに基づいて、ScalarDB テーブルにデータがすでに存在する場合、このソースデータのインポートは失敗します。 | +| UPDATE | 各ソースレコードは、ScalarDB テーブル内の既存のデータの更新として扱われます。パーティションキーとクラスタリングキーに基づいて、テーブルにデータが存在しない場合、このソースデータのインポートは失敗します。 | +| UPSERT | ターゲット ScalarDB テーブルにすでにデータが含まれている場合、インポートは UPDATE によって行われます。ターゲットデータがない場合は、INSERT として扱われます。 | + +*注*: + + `INSERT` の場合、自動マッピングまたは制御ファイルによるカスタムマッピングによって、各ターゲット列のソースファイル内に一致するフィールドが必要です。これは、`INSERT` に変わる `UPSERT` にも適用されます。 + +## データマッピング + +### 自動マッピング + +制御ファイルが指定されていない場合、Data Loader はソース JSON データ内のフィールドを ScalarDB テーブル内の使用可能な列に自動的にマッピングします。名前が一致せず、すべての列が必須である場合は、検証エラーとして扱われます。この場合、このレコードのインポートは失敗し、結果は失敗した出力ログに追加されます。 + +### カスタムマッピング + +ソースフィールドがターゲット列名と一致しない場合は、制御ファイルを使用する必要があります。この制御ファイルでは、フィールド名のカスタムマッピングルールを指定できます。 + +たとえば、次の制御ファイルは、ソースファイルのフィールド `custom_id` をターゲットテーブルの `id` にマッピングします。 + +```json +{ + "tables": [{ + "namespace": "sample", + "table_name": "table1", + "mappings": [{ + "source_field": "custom_id", + "target_column": "id" + }] + } + ] +} +``` + +## 制御ファイル + +カスタムデータマッピングまたは複数テーブルのインポートを可能にするために、Data Loader は JSON 制御ファイルによる設定をサポートしています。このファイルは、Data Loader を起動するときに `--control-file` 引数で渡す必要があります。 + +### 制御ファイルの検証レベル + +制御ファイルの検証を強制するために、Data Loader では検証レベルを指定できます。設定されたレベルに基づいて、Data Loader は事前チェックを実行し、レベルルールに基づいて制御ファイルを検証します。 + +次のレベルがサポートされています。 + +| レベル | 説明 | +| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| FULL | この検証では、制御ファイルにターゲット ScalarDB テーブルの各列のマッピングがあることを確認します。 | +| KEYS | この検証では、各 ScalarDB テーブルパーティションのマッピングと、使用可能な場合は制御ファイルマッピングのクラスタリングキー列のマッピングが使用可能であることを確認します。 | +| MAPPED | この検証では、指定されたソースフィールドとターゲット列が、制御ファイルで指定されたマッピングに対してのみ存在することを確認します。
その他のフィールドはチェックされません。 | + +検証レベルはオプションであり、Data Loader の起動時に `--control-file-validation-level` 引数で設定できます。 + +*注*: + +この検証は事前チェックとして実行されるものであり、インポートプロセスが自動的に成功することを意味するものではありません。 + +例:レベルがマップ済みに設定されていて、制御ファイルに INSERT の各列のマッピングが含まれていない場合、INSERT にはすべての列をマップする必要があるため、インポートプロセスは失敗します。 + +## 複数テーブルのインポート + +Data Loader は、複数テーブルのターゲットインポートをサポートしています。 + +JSON または JSONLine ファイル内の 1 つの行を、制御ファイルでテーブルマッピングルールを指定することにより、複数のテーブルにインポートできます。現在、制御ファイルなしでは複数テーブルのインポートはサポートされていません。 + +ScalarDB トランザクションモードで複数テーブルのインポートを使用する場合、各テーブルのインポートごとにトランザクションが作成されます。例: ソースレコードが制御ファイルで 3 つのテーブルにマップされている場合、3 つの個別のトランザクションが作成されます。 + +例: 次のソースレコードを `table1` と `table2` にインポートするには、次の手順を実行します: + +| Table1 | Table2 | +| ------ | ------ | +| Id | Id | +| price | amount | + +**ソースレコード** + +```json +[{ + "custom_id": 1, + "custom_price": 1000, + "custom_amount": 100 + +}] +``` + +**制御ファイル** + +```json +{ + "tables": [{ + "namespace": "sample", + "table_name": "table1", + "mappings": [{ + "source_field": "custom_id", + "target_column": "id" + }, { + "source_field": "custom_price", + "target_column": "price" + }] + }, + { + "namespace": "sample", + "table_name": "table2", + "mappings": [{ + "source_field": "custom_id", + "target_column": "id" + }, { + "source_field": "custom_amount", + "target_column": "amount" + }] + } + ] +} +``` + +## 出力ログ + +インポートタスクを開始すると、Data Loader はインポート結果を 2 つのファイルに記録します。1 つのファイルには正常にインポートされたインポートデータが含まれ、もう 1 つのファイルにはインポートできなかったデータが含まれます。失敗したデータには、データをインポートできなかった理由を説明する追加フィールドが含まれます。このフィールドは `data_loader_import_status` と呼ばれます。 + +失敗したインポートを含むファイルは、問題を修正するために編集し、そのまま新しいインポートタスクのソースファイルとして使用できます。エラーを含む `data_loader_import_status` フィールドを最初に削除する必要はありません。このフィールドはインポートプロセス中に無視され、元の値は成功または失敗した出力ファイルの新しいバージョンには含まれません。 + +正常にインポートされたデータを含むファイルには `data_loader_import_status` フィールドも含まれます。このファイルは、インポートされた各データ行に関するステータスメッセージ（新しい行が作成されたか、既存のデータが更新されたか）を含みます。 + +### ログ形式 + +| フィールド | 説明 | +| -------------- | -------------------------------------------------------------------------------------- | +| action | データレコードのインポートプロセスの結果。UPDATE、INSERT、または FAILED_DURING_VALIDATION。 | +| namespace | データがインポートされるテーブルの名前空間。 | +| tablename | データがインポートされるテーブルの名前。 | +| is_data_mapped | 使用可能な制御ファイルに基づいて、カスタムデータマッピングが適用されたかどうか。 | +| tx_id | トランザクションの ID。Data Loader が `transaction` モードで実行されている場合にのみ使用できます。 | +| value | オプションのデータマッピング後の最終値。Data Loader が `PUT` 操作で使用する値。 | +| row_number | ソースデータの行番号またはレコード番号。 | +| Errors | インポートプロセス中に問題が発生した検証エラーまたはその他のエラーのリスト。 | + +JSON 形式の成功ログファイルの例: + +```json +[{ + "column_1": 1, + "column_2": 2, + "column_n": 3, + "data_loader_import_status": { + "results": [{ + "action": "UPDATE", + "namespace": "namespace1", + "tableName": "table1", + "is_data_mapped": true, + "tx_id": "value", + "value": "value", + "row_number": "value" + }] + } +}] +``` + +JSON 形式の失敗したログファイルの例: + +```json +[{ + "column_1": 1, + "column_2": 2, + "column_n": 3, + "data_loader_import_status": { + "results": [{ + "action": "FAILED_DURING_VALIDATION", + "namespace": "namespace1", + "tableName": "table1", + "is_data_mapped": false, + "value": "value", + "row_number": "value", + "errors": [ + "missing columns found during validation" + ] + }] + } +}] +``` + +## データの重複 + +Data Loader は重複を単独では処理しません。ScalarDB トランザクションモードでは、同じターゲットデータを連続して更新しようとすると `No Mutation` エラーが発生しますが、これは Data Loader では処理されません。これらの失敗したデータ行は、失敗したインポート結果の出力ファイルに追加され、後でインポートを再試行できます。 + +ただし、Data Loader では正しい状態を保証できないため、インポートファイルに同じパーティションキーやクラスタリングキーの更新や挿入が含まれていないことを確認することをお勧めします。 + +## ストレージモードとトランザクションモード + +ScalarDB はストレージモードとトランザクションモードの両方をサポートしており、このサポートは Data Loader のインポートプロセスに含まれています。 + +ローダーがストレージモードで起動されると、各インポートは非​​トランザクション方式で実行されます。 + +ローダーをトランザクションモードで起動すると、トランザクションを使用してデータがインポートされます。現在、各行は個別のトランザクションを介してインポートされます。1 つのレコードを複数のテーブルにインポートする場合、各テーブルのインポートごとに個別のトランザクションが作成されます。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-graphql/how-to-run-two-phase-commit-transaction.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-graphql/how-to-run-two-phase-commit-transaction.mdx new file mode 100644 index 00000000..818a7a8c --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-graphql/how-to-run-two-phase-commit-transaction.mdx @@ -0,0 +1,144 @@ +--- +tags: + - Enterprise Premium +--- + +# 2 フェーズコミットトランザクションを実行する方法 + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +ScalarDB GraphQL は、[2 フェーズコミットトランザクション](../two-phase-commit-transactions.mdx)と呼ばれるトランザクションをサポートしています。 +2 フェーズコミットトランザクションを使用すると、複数のプロセス/アプリケーション (マイクロサービスなど) にまたがるトランザクションを実行できます。 +トランザクションを開始するアプリケーションを「コーディネーター」と名付け、トランザクションに参加するアプリケーションを「参加者」と名付けます。 +すべての 2 フェーズコミット操作では、ミューテーションまたはクエリ操作に `@twoPhaseCommit` ディレクティブをアノテーションする必要があります。以下は、このような操作の説明です。 + +## トランザクションを開始する + +トランザクションを開始するには、パラメータを設定せずに `@twoPhaseCommit` ディレクティブを追加します。 + +```graphql +query some_query @twoPhaseCommit { + # some query +} +``` + +開始されたトランザクションのトランザクション ID は、結果の一部である拡張オブジェクトで返されます。 + +```json +{ + "data": { + ... + }, + "extensions": { + "transaction": { + "id": "the_transaction_id" + } + } +} +``` + +## トランザクションに参加する (参加者用) + +参加者アプリケーションで、コーディネーターアプリケーションによって開始されたトランザクションに参加するには、トランザクション ID を `id` パラメータで設定し、`join` パラメータを true に設定します。 + +```graphql +query some_query_from_participant @twoPhaseCommit(id:"the_transaction_id", join:true) { + # some query +} +``` + +## トランザクションを再開する + +開始または結合されたトランザクションで操作の実行を継続するには、`@twoPhaseCommit` ディレクティブの `id` パラメータにトランザクション ID 値を設定します。 + +```graphql +mutation some_mutation @twoPhaseCommit(id:"the_transaction_id") { + # some mutation +} +``` + +## トランザクションの準備、検証、コミット + +クエリと変更操作が完了したら、トランザクションをコミットする必要があります。 + +よく知られている 2 フェーズコミットプロトコルと同様に、準備とコミットの 2 つのフェーズがあります。 + +まず、すべてのコーディネータ/参加者アプリケーションでトランザクションを準備し、次にすべてのコーディネータ/参加者アプリケーションでトランザクションをコミットする必要があります。 + +Consensus Commit トランザクションマネージャーが `SERIALIZABLE` 分離レベルで `EXTRA_READ` シリアル化可能戦略を使用して設定されている場合、準備フェーズとコミットフェーズの間に追加の「検証」フェーズが必要です。 + +準備とコミットと同様に、検証はすべてのコーディネータ/参加者アプリケーションで実行する必要があります。 + +準備、検証、コミットは、すべてのコーディネータ/参加者アプリケーションで並行して実行できます。 + +### トランザクションを準備する + +2 フェーズコミットトランザクションを準備するには、2 つのオプションがあります。 + +#### ディレクティブパラメータ経由 + +ディレクティブの `prepare` パラメータを使用すると、操作フィールドの実行後に、エラーが発生しない場合にのみトランザクションが準備されます。 + +```graphql +mutation some_mutation_then_prepare_tx @twoPhaseCommit(id:"the_transaction_id", prepare:true) { + mutation1 : ... + mutation2 : ... + # the transaction will be prepared after the execution of the mutation1 and mutation2 fields +} +``` + +#### ミューテーションフィールド経由 + +ミューテーション操作に `prepare` フィールドを追加します。このフィールドはトランザクションの準備を開始します。 + +```graphql +mutation prepare_tx @twoPhaseCommit(id:"the_transaction_id") { + prepare +} +``` + +### トランザクションを検証する + +ミューテーション操作に `validate` フィールドを追加します。このフィールドはトランザクションの検証をトリガーします。 + +```graphql +mutation validate_tx @twoPhaseCommit(id:"the_transaction_id") { + validate +} +``` + +### トランザクションをコミットする + +ミューテーション操作に `commit` フィールドを追加します。このフィールドはトランザクションのコミットをトリガーします。 + +```graphql +mutation commit_tx @twoPhaseCommit(id:"the_transaction_id") { + commit +} +``` + +### トランザクションのアボート/ロールバック + +トランザクションを明示的にアボート/ロールバックする必要がある場合は、`abort` または `rollback` ミューテーションフィールドを互換的に使用できます (どちらも効果と使用法は同じです)。他の操作と混在させることはできないため、単独で指定する必要があります。 + +```graphql +mutation AbortTx @twoPhaseCommit(id: "the_transaction_id") { + abort +} +``` + +または + +```graphql +mutation RollbackTx @twoPhaseCommit(id: "the_transaction_id") { + rollback +} +``` + +## エラー処理 + +`@twoPhaseCommit` 操作によって例外がスローされた場合、ScalarDB GraphQL はトランザクションを回復するロールバックプロシージャをトリガーします。 +2 フェーズコミットトランザクションでの例外処理の詳細については、 +[ScalarDB 2 フェーズコミットトランザクションの例外処理ガイド](../two-phase-commit-transactions.mdx#handle-exceptions) を参照してください。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-graphql/scalardb-graphql-status-codes.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-graphql/scalardb-graphql-status-codes.mdx new file mode 100644 index 00000000..480e58ff --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-graphql/scalardb-graphql-status-codes.mdx @@ -0,0 +1,244 @@ +--- +tags: + - Enterprise Premium +--- + +# ScalarDB GraphQL エラーコード + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このページでは、ScalarDB GraphQL のエラーコードの一覧を示します。 + +## エラーコードのクラスと説明 + +| クラス | 説明 | +|:----------------|:--------------------------| +| `GRAPHQL-1xxxx` | ユーザーエラーカテゴリのエラー | + +## `GRAPHQL-1xxxx` ステータスコード + +### `GRAPHQL-10000` + +**メッセージ** + +```markdown +A long value was expected +``` + +### `GRAPHQL-10001` + +**メッセージ** + +```markdown +The value is out of range for BigIntValue +``` + +### `GRAPHQL-10002` + +**メッセージ** + +```markdown +A long, integer, or string value was expected +``` + +### `GRAPHQL-10003` + +**メッセージ** + +```markdown +The AST type `IntValue` was expected +``` + +### `GRAPHQL-10004` + +**メッセージ** + +```markdown +A float value was expected +``` + +### `GRAPHQL-10005` + +**メッセージ** + +```markdown +An integer or float value was expected +``` + +### `GRAPHQL-10006` + +**メッセージ** + +```markdown +The AST type `IntValue` or `FloatValue` was expected +``` + +### `GRAPHQL-10007` + +**メッセージ** + +```markdown +The type is not supported. Type: %s +``` + +### `GRAPHQL-10008` + +**メッセージ** + +```markdown +The field `%s` requires a `@transaction` or `@twoPhaseCommit` directive with proper arguments +``` + +### `GRAPHQL-10009` + +**メッセージ** + +```markdown +The field `%s` cannot be used together with other fields +``` + +### `GRAPHQL-10010` + +**メッセージ** + +```markdown +The `@twoPhaseCommit` directive with the `id` argument is required to `%s` the transaction +``` + +### `GRAPHQL-10011` + +**メッセージ** + +```markdown +`%s` and `prepare` cannot be run simultaneously +``` + +### `GRAPHQL-10012` + +**メッセージ** + +```markdown +`%s` and `join` cannot be run simultaneously +``` + +### `GRAPHQL-10013` + +**メッセージ** + +```markdown +The `@transaction` directive with the `id` argument is required to `%s` the transaction +``` + +### `GRAPHQL-10014` + +**メッセージ** + +```markdown +`%s` and `commit` cannot be run simultaneously +``` + +### `GRAPHQL-10015` + +**メッセージ** + +```markdown +An object cannot be annotated with both `@transaction` and `@twoPhaseCommit` directives +``` + +### `GRAPHQL-10016` + +**メッセージ** + +```markdown +The `join` argument of the `@twoPhaseCommit` directive requires a transaction `id` argument +``` + +### `GRAPHQL-10017` + +**メッセージ** + +```markdown +`%s` requires the mutation object to be annotated with a `@twoPhaseCommit` directive +``` + +### `GRAPHQL-10018` + +**メッセージ** + +```markdown +The `%s` clustering key must have only one of the following: %s +``` + +### `GRAPHQL-10019` + +**メッセージ** + +```markdown +A string variable is expected but got %s +``` + +### `GRAPHQL-10020` + +**メッセージ** + +```markdown +Unexpected value of id: %s +``` + +### `GRAPHQL-10021` + +**メッセージ** + +```markdown +A Boolean variable is expected but got %s +``` + +### `GRAPHQL-10022` + +**メッセージ** + +```markdown +Unexpected value of %s: %s +``` + +### `GRAPHQL-10023` + +**メッセージ** + +```markdown +Invalid column. Column: %s; Type: %s +``` + +### `GRAPHQL-10024` + +**メッセージ** + +```markdown +Unexpected value of type: %s +``` + +### `GRAPHQL-10025` + +**メッセージ** + +```markdown +Only one of the following can be specified: %s +``` + +### `GRAPHQL-10026` + +**メッセージ** + +```markdown +Unexpected mutation field: %s +``` + +### `GRAPHQL-10027` + +**メッセージ** + +```markdown +Invalid type: %s +``` diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/README.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/README.mdx new file mode 100644 index 00000000..542c1b4e --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/README.mdx @@ -0,0 +1,21 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# ScalarDB サンプル + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +以下は ScalarDB のサンプルアプリケーションです: + +- [マルチストレージトランザクションサンプル](multi-storage-transaction-sample/README.mdx) +- [マイクロサービストランザクションサンプル](microservice-transaction-sample/README.mdx) +- [ScalarDB Analytics with PostgreSQL](scalardb-analytics-postgresql-sample/README.mdx) +- [ScalarDB Analytics with Spark](scalardb-analytics-spark-sample/README.mdx) +- [マルチストレージトランザクションサンプルを使用した Spring Data JDBC for ScalarDB](spring-data-multi-storage-transaction-sample/README.mdx) +- [マイクロサービストランザクションサンプルを使用した Spring Data JDBC for ScalarDB](spring-data-microservice-transaction-sample/README.mdx) diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/microservice-transaction-sample/README.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/microservice-transaction-sample/README.mdx new file mode 100644 index 00000000..33f3908d --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/microservice-transaction-sample/README.mdx @@ -0,0 +1,537 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# マイクロサービストランザクションをサポートするサンプルアプリケーションを作成する + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このチュートリアルでは、ScalarDB でマイクロサービストランザクションをサポートするサンプルアプリケーションを作成する方法について説明します。 + +## 概要 + +このチュートリアルでは、ScalarDB の [2 フェーズコミットインターフェースを使用したトランザクション](../../two-phase-commit-transactions.mdx)を通じてアイテムを注文し、信用枠で支払いを行うことができるサンプル電子商取引アプリケーションを作成するプロセスを示します。 + +サンプルアプリケーションには、[database-per-service pattern](https://microservices.io/patterns/data/database-per-service.html) に基づく *Customer Service* と *Order Service* という 2 つのマイクロサービスがあります。 + +- **Customer Service** は、信用枠情報、信用限度額、信用合計などの顧客情報を管理します。 +- **Order Service** は、注文の確定や注文履歴の取得などの注文操作を担当します。 + +各サービスには gRPC エンドポイントがあります。クライアントはエンドポイントを呼び出し、サービスも各エンドポイントを呼び出します。 + +サンプルアプリケーションで使用するデータベースは Cassandra と MySQL です。 Customer Service と Order Service は、それぞれ ScalarDB を介して Cassandra と MySQL を使用します。 + +![概要](images/overview.png) + +図に示されているように、両方のサービスは、Consensus Commit プロトコルに使用される小さな Coordinator データベースにアクセスします。データベースはサービスに依存せず、Consensus Commit のトランザクションメタデータを高可用性の方法で管理するために存在します。 + +サンプルアプリケーションでは、セットアップと説明を簡単にするために、Coordinator データベースを Order Service の同じ Cassandra インスタンスに共存させています。または、Coordinator データベースを別のデータベースとして管理することもできます。 + +:::note + +サンプルアプリケーションは ScalarDB の使用方法を示すことに重点を置いているため、アプリケーション固有のエラー処理、認証処理、および同様の機能はサンプルアプリケーションに含まれていません。ScalarDB での例外処理の詳細については、[例外の処理方法](../../api-guide.mdx#例外の処理方法)を参照してください。 + +さらに、サンプルアプリケーションの目的上、各サービスには 1 つのコンテナがあるため、サービス間のリクエストルーティングは不要です。ただし、実稼働環境では、スケーラビリティと可用性のために各サービスに複数のサーバーまたはホストがあるため、2 フェーズコミットインターフェイスを使用したトランザクションでは、サービス間のリクエストルーティングを検討する必要があります。要求ルーティングの詳細については、[2 フェーズコミットインターフェイスを使用したトランザクションでのリクエストルーティング](../../two-phase-commit-transactions.mdx#2-フェーズコミットインターフェイスを使用したトランザクションでのリクエストルーティング) を参照してください。 + +::: + +### サービスエンドポイント + +サービスで定義されているエンドポイントは次のとおりです。 + +- Customer Service + - `getCustomerInfo` + - `payment` + - `prepare` + - `validate` + - `commit` + - `rollback` + - `repayment` + +- Order Service + - `placeOrder` + - `getOrder` + - `getOrders` + +### このサンプルアプリケーションで実行できること + +サンプルアプリケーションは、次の種類のトランザクションをサポートしています。 + +- Customer Service の `getCustomerInfo` エンドポイントを介して顧客情報を取得します。 +- Order Service の `placeOrder` エンドポイントと、Customer Service の `payment`、`prepare`、`validate`、`commit`、`rollback` エンドポイントを介して、信用枠を使用して注文を行います。 + - 注文のコストが顧客の信用限度額を下回っているかどうかを確認します。 + - チェックに合格した場合、注文履歴を記録し、顧客が支払った金額を更新します。 +- Order Service の `getOrder` エンドポイントと、Customer Service の `getCustomerInfo`、`prepare`、`validate`、`commit`、`rollback` エンドポイントを介して、注文 ID で注文情報を取得します。 +- Order Service の `getOrders` エンドポイントと、Customer Service の `getCustomerInfo`、`prepare`、`validate`、`commit`、`rollback` エンドポイントを介して、顧客 ID で注文情報を取得します。 +- Customer Service の `repayment` エンドポイントを介して支払いを行います。 + - 顧客が支払った金額を減らします。 + +:::note + +`getCustomerInfo` エンドポイントは、コーディネーターからトランザクション ID を受信するときに、参加者サービスエンドポイントとして機能します。 + +::: + +## このサンプルアプリケーションの前提条件 + +- [Eclipse Temurin](https://adoptium.net/temurin/releases/) の OpenJDK LTS バージョン (8、11、17、または 21) +- [Docker](https://www.docker.com/get-started/) 20.10 以降 ([Docker Compose](https://docs.docker.com/compose/install/) V2 以降) + +:::note + +このサンプルアプリケーションは、Eclipse Temurin の OpenJDK でテストされています。ただし、ScalarDB 自体は、さまざまなベンダーの JDK ディストリビューションでテストされています。互換性のある JDK ディストリビューションを含む ScalarDB の要件の詳細については、[要件](../../requirements.mdx)を参照してください。 + +::: + +## ScalarDB のセットアップ + +次のセクションでは、ScalarDB でマイクロサービストランザクションをサポートするサンプルアプリケーションをセットアップする方法について説明します。 + +### ScalarDB サンプルリポジトリをクローンする + +**ターミナル** を開き、次のコマンドを実行して ScalarDB サンプルリポジトリをクローンします。 + +```console +git clone https://github.com/scalar-labs/scalardb-samples +``` + +次に、次のコマンドを実行して、サンプルアプリケーションが含まれているディレクトリに移動します。 + +```console +cd scalardb-samples/microservice-transaction-sample +``` + +### CassandraとMySQLを起動する + +Cassandra と MySQL は、それぞれ [`database-cassandra.properties`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/database-cassandra.properties) と [`database-mysql.properties`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/database-mysql.properties) に示されているように、サンプルアプリケーション用にすでに設定されています。ScalarDB でのマルチストレージトランザクション機能の設定の詳細については、[マルチストレージトランザクションをサポートするように ScalarDB を設定する方法](../../multi-storage-transactions.mdx#マルチストレージトランザクションをサポートするように-scalardb-を設定する方法)を参照してください。 + +サンプルアプリケーションの Docker コンテナに含まれている Cassandra と MySQL を起動するには、次のコマンドを実行します。 + +```console +docker-compose up -d mysql cassandra +``` + +:::note + +開発環境によっては、Docker コンテナの起動に 1 分以上かかる場合があります。 + +::: + +### スキーマをロードします + +サンプルアプリケーションのデータベーススキーマ (データを整理する方法) は、Customer Service の場合は [`customer-service-schema.json`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/customer-service-schema.json)、Order Service の場合は [`order-service-schema.json`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/order-service-schema.json) で既に定義されています。 + +スキーマを適用するには、[ScalarDB リリース](https://github.com/scalar-labs/scalardb/releases)ページに移動し、使用する ScalarDB のバージョンに一致する ScalarDB スキーマローダーを `scalardb-samples/microservice-transaction-sample` フォルダーにダウンロードします。 + +#### MySQL + +[`customer-service-schema.json`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/customer-service-schema.json) のスキーマを MySQL にロードするには、次のコマンドを実行します。`` は、ダウンロードした ScalarDB Schema Loader のバージョンに置き換えます。 + +```console +java -jar scalardb-schema-loader-.jar --config database-mysql.properties --schema-file customer-service-schema.json +``` + +#### Cassandra + +[`order-service-schema.json`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/order-service-schema.json) のスキーマを Cassandra にロードするには、次のコマンドを実行します。`` は、ダウンロードした ScalarDB Schema Loader のバージョンに置き換えます。 + +```console +java -jar scalardb-schema-loader-.jar --config database-cassandra.properties --schema-file order-service-schema.json --coordinator +``` + +#### Schema details + +[`customer-service-schema.json`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/customer-service-schema.json) に示されているように、Customer Service のすべてのテーブルは `customer_service` 名前空間に作成されます。 + +- `customer_service.customers`: 顧客の情報を管理するテーブル + - `credit_limit`: 貸し手が各顧客に信用枠の使用を許可する最大金額 + - `credit_total`: 各顧客が信用枠を使用してすでに使用した金額 + +[`order-service-schema.json`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/order-service-schema.json) に示されているように、Order Service のすべてのテーブルは `order_service` 名前空間に作成されます。 + +- `order_service.orders`: 注文情報を管理するテーブル +- `order_service.statements`: 注文明細情報を管理するテーブル +- `order_service.items`: 注文する商品の情報を管理するテーブル + +スキーマのエンティティリレーションシップダイアグラムは次のとおりです。 + +![ERD](images/ERD.png) + +### マイクロサービスを起動して初期データをロードします + +マイクロサービスを起動する前に、次のコマンドを実行してサンプルアプリケーションの Docker イメージをビルドします。 + +```console +./gradlew docker +``` + +次に、次のコマンドを実行してマイクロサービスを起動します。 + +```console +docker-compose up -d customer-service order-service +``` + +マイクロサービスを起動し、初期データが読み込まれた後、次のレコードが `customer_service.customers` テーブルに保存されるはずです。 + +| customer_id | name | credit_limit | credit_total | +|-------------|---------------|--------------|--------------| +| 1 | Yamada Taro | 10000 | 0 | +| 2 | Yamada Hanako | 10000 | 0 | +| 3 | Suzuki Ichiro | 10000 | 0 | + +そして、次のレコードが `order_service.items` テーブルに保存される必要があります。 + +| item_id | name | price | +|---------|--------|-------| +| 1 | Apple | 1000 | +| 2 | Orange | 2000 | +| 3 | Grape | 2500 | +| 4 | Mango | 5000 | +| 5 | Melon | 3000 | + +## サンプルアプリケーションでトランザクションを実行し、データを取得する + +次のセクションでは、サンプル電子商取引アプリケーションでトランザクションを実行し、データを取得する方法について説明します。 + +### 顧客情報を取得する + +次のコマンドを実行して、ID が `1` である顧客に関する情報を取得することから始めます。 + +```console +./gradlew :client:run --args="GetCustomerInfo 1" +``` + +次の出力が表示されます。 + +```console +... +{"id": 1,"name": "Yamada Taro","credit_limit": 10000} +... +``` + +この時点では、`credit_total` は表示されません。つまり、`credit_total` の現在の値は `0` です。 + +### 注文する + +次に、次のコマンドを実行して、顧客 ID `1` にリンゴ 3 個とオレンジ 2 個を注文してもらいます。 + +:::note + +このコマンドの注文形式は `./gradlew run --args="PlaceOrder :,:,..."` です。 + +::: + +```console +./gradlew :client:run --args="PlaceOrder 1 1:3,2:2" +``` + +以下のように、`order_id` の UUID が異なる、注文が成功したことを示す出力が表示されます。 + +```console +... +{"order_id": "4ccdb21c-ac03-4b48-bcb7-cad57eac1e79"} +... +``` + +### 注文の詳細を確認する + +次のコマンドを実行して注文の詳細を確認します。`` は、前のコマンドを実行した後に表示される `order_id` の UUID に置き換えます。 + +```console +./gradlew :client:run --args="GetOrder " +``` + +`order_id` と `timestamp` の UUID が異なる、以下のような出力が表示されます。 + +```console +... +{"order": {"order_id": "4ccdb21c-ac03-4b48-bcb7-cad57eac1e79","timestamp": 1631605253126,"customer_id": 1,"customer_name": "Yamada Taro","statement": [{"item_id": 1,"item_name": "Apple","price": 1000,"count": 3,"total": 3000},{"item_id": 2,"item_name": "Orange","price": 2000,"count": 2,"total": 4000}],"total": 7000}} +... +``` + +### 別の注文をする + +次のコマンドを実行して、顧客 ID `1` の `credit_total` の残額を使用してメロン 1 個を注文します。 + +```console +./gradlew :client:run --args="PlaceOrder 1 5:1" +``` + +以下のように、`order_id` の UUID が異なる、注文が成功したことを示す出力が表示されます。 + +```console +... +{"order_id": "0b10db66-faa6-4323-8a7a-474e8534a7ee"} +... +``` + +### 注文履歴を確認する + +次のコマンドを実行して、顧客 ID `1` のすべての注文履歴を取得します。 + +```console +./gradlew :client:run --args="GetOrders 1" +``` + +`order_id` と `timestamp` の UUID が異なる以下のような出力が表示されます。これは、顧客 ID `1` のすべての注文履歴をタイムスタンプの降順で表示します。 + +```console +... +{"order": [{"order_id": "0b10db66-faa6-4323-8a7a-474e8534a7ee","timestamp": 1631605501485,"customer_id": 1,"customer_name": "Yamada Taro","statement": [{"item_id": 5,"item_name": "Melon","price": 3000,"count": 1,"total": 3000}],"total": 3000},{"order_id": "4ccdb21c-ac03-4b48-bcb7-cad57eac1e79","timestamp": 1631605253126,"customer_id": 1,"customer_name": "Yamada Taro","statement": [{"item_id": 1,"item_name": "Apple","price": 1000,"count": 3,"total": 3000},{"item_id": 2,"item_name": "Orange","price": 2000,"count": 2,"total": 4000}],"total": 7000}]} +... +``` + +### クレジット合計の確認 + +次のコマンドを実行して、顧客 ID `1` のクレジット合計を取得します。 + +```console +./gradlew :client:run --args="GetCustomerInfo 1" +``` + +次の出力が表示されます。これは、顧客 ID `1` が `credit_total` の `credit_limit` に達しており、これ以上注文できないことを示しています。 + +```console +... +{"id": 1,"name": "Yamada Taro","credit_limit": 10000,"credit_total": 10000} +... +``` + +次のコマンドを実行して、ブドウ 1 個とマンゴー 1 個を注文してみます。 + +```console +./gradlew :client:run --args="PlaceOrder 1 3:1,4:1" +``` + +次の出力が表示されます。これは、`credit_total` 金額が `credit_limit` 金額を超えたために注文が失敗したことを示しています。 + +```console +... +io.grpc.StatusRuntimeException: FAILED_PRECONDITION: Credit limit exceeded + at io.grpc.stub.ClientCalls.toStatusRuntimeException(ClientCalls.java:271) + at io.grpc.stub.ClientCalls.getUnchecked(ClientCalls.java:252) + at io.grpc.stub.ClientCalls.blockingUnaryCall(ClientCalls.java:165) + at sample.rpc.OrderServiceGrpc$OrderServiceBlockingStub.placeOrder(OrderServiceGrpc.java:296) + at sample.client.command.PlaceOrderCommand.call(PlaceOrderCommand.java:38) + at sample.client.command.PlaceOrderCommand.call(PlaceOrderCommand.java:12) + at picocli.CommandLine.executeUserObject(CommandLine.java:2041) + at picocli.CommandLine.access$1500(CommandLine.java:148) + at picocli.CommandLine$RunLast.executeUserObjectOfLastSubcommandWithSameParent(CommandLine.java:2461) + at picocli.CommandLine$RunLast.handle(CommandLine.java:2453) + at picocli.CommandLine$RunLast.handle(CommandLine.java:2415) + at picocli.CommandLine$AbstractParseResultHandler.execute(CommandLine.java:2273) + at picocli.CommandLine$RunLast.execute(CommandLine.java:2417) + at picocli.CommandLine.execute(CommandLine.java:2170) + at sample.client.Client.main(Client.java:39) +... +``` + +### 支払いを行う + +注文を続行するには、顧客 ID `1` が支払いを行って `credit_total` の金額を減らす必要があります。 + +次のコマンドを実行して支払いを行います。 + +```console +./gradlew :client:run --args="Repayment 1 8000" +``` + +次に、次のコマンドを実行して、顧客 ID `1` の `credit_total` 金額を確認します。 + +```console +./gradlew :client:run --args="GetCustomerInfo 1" +``` + +次の出力が表示されます。これは、顧客 ID `1` に支払いが適用され、`credit_total` の金額が減ったことを示しています。 + +```console +... +{"id": 1,"name": "Yamada Taro","credit_limit": 10000,"credit_total": 2000} +... +``` + +顧客 ID `1` が支払いを済ませたので、次のコマンドを実行してブドウ 1 個とメロン 1 個を注文します。 + +```console +./gradlew :client:run --args="PlaceOrder 1 3:1,4:1" +``` + +以下のように、`order_id` の UUID が異なる、注文が成功したことを示す出力が表示されます。 + +```console +... +{"order_id": "dd53dd9d-aaf4-41db-84b2-56951fed6425"} +... +``` + +## サンプルアプリケーションを停止する + +サンプルアプリケーションを停止するには、Cassandra、MySQL、およびマイクロサービスを実行している Docker コンテナを停止する必要があります。Docker コンテナを停止するには、次のコマンドを実行します。 + +```console +docker-compose down +``` + +## リファレンス - マイクロサービストランザクションの実現方法 + +注文、単一注文の取得、注文履歴の取得のトランザクションは、マイクロサービストランザクションを実現します。このセクションでは、注文を例に、Customer Service と Order Service にまたがるトランザクションの実装方法に焦点を当てます。 + +次のシーケンス図は、注文を行うトランザクションを示しています。 + +![マイクロサービストランザクションシーケンス図](images/sequence_diagram.png) + +### 1. 2 フェーズコミットインターフェースを使用したトランザクションが開始されます + +クライアントが Order Service に注文リクエストを送信すると、`OrderService.placeOrder()` が呼び出され、マイクロサービストランザクションが開始されます。 + +最初に、Order Service は次のように `start()` を使用して 2 フェーズコミットインターフェースを使用したトランザクションを開始します。参考として、[`OrderService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/order-service/src/main/java/sample/order/OrderService.java) を参照してください。 + +```java +transaction = twoPhaseCommitTransactionManager.start(); +``` + +### 2. CRUD 操作が実行されます + +2 フェーズコミットインターフェースを使用したトランザクションが開始されると、CRUD 操作が実行されます。Order Service は、次のように、注文情報を `order_service.orders` テーブルに、詳細情報を `order_service.statements` テーブルに格納します。参考として、[`OrderService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/order-service/src/main/java/sample/order/OrderService.java) を参照してください。 + +```java +// Put the order info into the `orders` table. +Order.put(transaction, orderId, request.getCustomerId(), System.currentTimeMillis()); + +int amount = 0; +for (ItemOrder itemOrder : request.getItemOrderList()) { + // Put the order statement into the `statements` table. + Statement.put(transaction, orderId, itemOrder.getItemId(), itemOrder.getCount()); + + // Retrieve the item info from the `items` table. + Optional item = Item.get(transaction, itemOrder.getItemId()); + if (!item.isPresent()) { + responseObserver.onError( + Status.NOT_FOUND.withDescription("Item not found").asRuntimeException()); + return; + } + + // Calculate the total amount. + amount += item.get().price * itemOrder.getCount(); +} +``` + +次に、Order Service は、トランザクション ID とともに Customer Service の `payment` gRPC エンドポイントを呼び出します。参考として、[`OrderService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/order-service/src/main/java/sample/order/OrderService.java) を参照してください。 + +```java +customerServiceStub.payment( + PaymentRequest.newBuilder() + .setTransactionId(transactionId) + .setCustomerId(customerId) + .setAmount(amount) + .build()); +``` + +Customer Service の `payment` エンドポイントは、まず次のように `join()` を使用してトランザクションを結合します。参考として、[`CustomerService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/customer-service/src/main/java/sample/customer/CustomerService.java) を参照してください。 + +```java +private void execOperationsAsParticipant(String funcName, String transactionId, + TransactionFunction operations, + StreamObserver responseObserver) { + try { + // Join the transaction + TwoPhaseCommitTransaction transaction = twoPhaseCommitTransactionManager.join(transactionId); + + // Execute operations + T response = operations.apply(transaction); +``` + +次に、エンドポイントは顧客情報を取得し、支払い後に顧客のクレジット合計がクレジット限度額を超えているかどうかを確認します。クレジット合計がクレジット限度額を超えていない場合、エンドポイントは顧客のクレジット合計を更新します。参考として、[`CustomerService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/customer-service/src/main/java/sample/customer/CustomerService.java) を参照してください。 + +```java +execOperationsAsParticipant("Payment", request.getTransactionId(), + transaction -> { + // Retrieve the customer info for the customer ID + Optional result = Customer.get(transaction, request.getCustomerId()); + if (!result.isPresent()) { + throw Status.NOT_FOUND.withDescription("Customer not found").asRuntimeException(); + } + + int updatedCreditTotal = result.get().creditTotal + request.getAmount(); + + // Check if the credit total exceeds the credit limit after payment + if (updatedCreditTotal > result.get().creditLimit) { + throw Status.FAILED_PRECONDITION + .withDescription("Credit limit exceeded") + .asRuntimeException(); + } + + // Update `credit_total` for the customer + Customer.updateCreditTotal(transaction, request.getCustomerId(), updatedCreditTotal); + + return Empty.getDefaultInstance(); + }, responseObserver +); +``` + +### 3. 2 フェーズコミットプロトコルを使用してトランザクションがコミットされます + +Order Service は、支払いが成功したという更新を受信すると、トランザクションをコミットしようとします。 + +トランザクションをコミットするために、Order Service はトランザクションの準備から始めます。Order Service は、トランザクションオブジェクトから `prepare()` を呼び出し、Customer Service の `prepare` gRPC エンドポイントを呼び出します。参考として、[`OrderService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/order-service/src/main/java/sample/order/OrderService.java) を参照してください。 + +```java +transaction.prepare(); +callPrepareEndpoint(transaction.getId()); +``` + +このエンドポイントでは、Customer Service がトランザクションを再開し、トランザクションオブジェクトから `prepare()` も呼び出します。参考として、[`CustomerService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/customer-service/src/main/java/sample/customer/CustomerService.java) を参照してください。 + +```java +// Resume the transaction. +transaction = twoPhaseCommitTransactionManager.resume(request.getTransactionId()); + +// Prepare the transaction. +transaction.prepare(); +``` + +同様に、Order Service と Customer Service は、トランザクションオブジェクトから `validate()` を呼び出します。参考として、[`OrderService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/order-service/src/main/java/sample/order/OrderService.java) と [`CustomerService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/customer-service/src/main/java/sample/customer/CustomerService.java) を参照してください。`validate()` の詳細については、[トランザクションの検証](../../two-phase-commit-transactions.mdx#トランザクションの検証)を参照してください。 + +Order Service と Customer Service の両方でトランザクションの準備と検証が成功したら、トランザクションをコミットできます。この場合、Order Service はトランザクションオブジェクトから `commit()` を呼び出し、次に Customer Service の `commit` gRPC エンドポイントを呼び出します。参考として、[`OrderService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/order-service/src/main/java/sample/order/OrderService.java) を参照してください。 + +```java +transaction.commit(); +callCommitEndpoint(transaction.getId()); +``` + +このエンドポイントでは、Customer Service がトランザクションを再開し、トランザクションオブジェクトから `commit()` も呼び出します。参考として、[`CustomerService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/customer-service/src/main/java/sample/customer/CustomerService.java) を参照してください。 + +```java +// Resume the transaction. +transaction = twoPhaseCommitTransactionManager.resume(request.getTransactionId()); + +// Commit the transaction. +transaction.commit(); +``` + +### エラー処理 + +トランザクションの実行中にエラーが発生した場合は、トランザクションをロールバックする必要があります。この場合、Order Service はトランザクションオブジェクトから `rollback()` を呼び出し、次に Customer Service の `rollback` gRPC エンドポイントを呼び出します。参考として、[`OrderService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/order-service/src/main/java/sample/order/OrderService.java) を参照してください。 + +```java +transaction.rollback(); +callRollbackEndpoint(transaction.getId()); +``` + +このエンドポイントでは、Customer Service がトランザクションを再開し、トランザクションオブジェクトから `rollback()` も呼び出します。参考として、[`CustomerService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/microservice-transaction-sample/customer-service/src/main/java/sample/customer/CustomerService.java) を参照してください。 + +```java +// Resume the transaction. +TwoPhaseCommitTransaction transaction = + twoPhaseCommitTransactionManager.resume(request.getTransactionId()); + +// Roll back the transaction. +transaction.rollback(); +``` + +ScalarDB で例外を処理する方法の詳細については、[例外の処理方法](../../api-guide.mdx#例外の処理方法)を参照してください。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/microservice-transaction-sample/images/ERD.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/microservice-transaction-sample/images/ERD.png new file mode 100644 index 00000000..c0468efa Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/microservice-transaction-sample/images/ERD.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/microservice-transaction-sample/images/overview.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/microservice-transaction-sample/images/overview.png new file mode 100644 index 00000000..4340b4f5 Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/microservice-transaction-sample/images/overview.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/microservice-transaction-sample/images/sequence_diagram.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/microservice-transaction-sample/images/sequence_diagram.png new file mode 100644 index 00000000..0317b5f3 Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/microservice-transaction-sample/images/sequence_diagram.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/multi-storage-transaction-sample/README.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/multi-storage-transaction-sample/README.mdx new file mode 100644 index 00000000..999ea4f5 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/multi-storage-transaction-sample/README.mdx @@ -0,0 +1,317 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +--- + +# マルチストレージトランザクションをサポートするサンプルアプリケーションを作成する + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このチュートリアルでは、ScalarDB のマルチストレージトランザクション機能をサポートするサンプルアプリケーションを作成する方法について説明します。 + +## 概要 + +このチュートリアルでは、ScalarDB の[マルチストレージトランザクション](../../multi-storage-transactions.mdx)機能を使用して、アイテムを注文し、信用枠で支払うことができるサンプル電子商取引アプリケーションを作成するプロセスを示します。 + +このチュートリアルでは、Cassandra と MySQL の両方を使用するアプリケーションを構築します。ScalarDB のマルチストレージトランザクション機能を使用すると、Cassandra と MySQL の両方にまたがるトランザクションを実行できます。 + +![概要](images/overview.png) + +:::note + +サンプルアプリケーションは ScalarDB の使用方法を示すことに重点を置いているため、アプリケーション固有のエラー処理、認証処理、および同様の機能はサンプルアプリケーションに含まれていません。ScalarDB での例外処理の詳細については、[例外の処理方法](../../api-guide.mdx#例外の処理方法)を参照してください。 + +::: + +### このサンプルアプリケーションで実行できること + +サンプルアプリケーションは、次の種類のトランザクションをサポートしています: + +- 顧客情報を取得します。 +- 信用枠を使用して注文を行います。 + - 注文のコストが顧客の信用限度額を下回っているかどうかを確認します。 + - チェックが成功した場合は、注文履歴を記録し、顧客が支払った金額を更新します。 +- 注文 ID で注文情報を取得します。 +- 顧客 ID で注文情報を取得します。 +- 支払いを行います。 + - 顧客が支払った金額を減らします。 + +## このサンプルアプリケーションの前提条件 + +- [Eclipse Temurin](https://adoptium.net/temurin/releases/) の OpenJDK LTS バージョン (8、11、17、または 21) +- [Docker](https://www.docker.com/get-started/) 20.10 以降 ([Docker Compose](https://docs.docker.com/compose/install/) V2 以降) + +:::note + +このサンプルアプリケーションは、Eclipse Temurin の OpenJDK でテストされています。ただし、ScalarDB 自体は、さまざまなベンダーの JDK ディストリビューションでテストされています。互換性のある JDK ディストリビューションを含む ScalarDB の要件の詳細については、[要件](../../requirements.mdx)を参照してください。 + +::: + +## ScalarDB のセットアップ + +次のセクションでは、ScalarDB のマルチストレージトランザクション機能をサポートするサンプルアプリケーションをセットアップする方法について説明します。 + +### ScalarDB サンプルリポジトリをクローンする + +**ターミナル** を開き、次のコマンドを実行して ScalarDB サンプルリポジトリをクローンします。 + +```console +git clone https://github.com/scalar-labs/scalardb-samples +``` + +次に、次のコマンドを実行して、サンプルアプリケーションが含まれているディレクトリに移動します。 + +```console +cd scalardb-samples/multi-storage-transaction-sample +``` + +### Cassandra と MySQL を起動します + +[`database.properties`](https://github.com/scalar-labs/scalardb-samples/tree/master/multi-storage-transaction-sample/database.properties) に示されているように、Cassandra と MySQL はサンプルアプリケーション用にすでに設定されています。ScalarDB のマルチストレージトランザクション機能の設定の詳細については、[マルチストレージトランザクションをサポートするように ScalarDB を設定する方法](../../multi-storage-transactions.mdx#マルチストレージトランザクションをサポートするように-scalardb-を設定する方法)を参照してください。 + +サンプルアプリケーションの Docker コンテナに含まれている Cassandra と MySQL を起動するには、Docker が実行されていることを確認してから、次のコマンドを実行します。 + +```console +docker-compose up -d +``` + +:::note + +開発環境によっては、Docker コンテナの起動に 1 分以上かかる場合があります。 + +::: + +### スキーマをロードする + +サンプルアプリケーションのデータベーススキーマ (データを整理する方法) は、すでに [`schema.json`](https://github.com/scalar-labs/scalardb-samples/tree/master/multi-storage-transaction-sample/schema.json) で定義されています。 + +スキーマを適用するには、[ScalarDB リリース](https://github.com/scalar-labs/scalardb/releases)ページに移動し、使用する ScalarDB のバージョンに一致する ScalarDB Schema Loader を `scalardb-samples/multi-storage-transaction-sample` フォルダーにダウンロードします。 + +次に、次のコマンドを実行します。`` は、ダウンロードした ScalarDB Schema Loader のバージョンに置き換えます。 + +```console +java -jar scalardb-schema-loader-.jar --config database.properties --schema-file schema.json --coordinator +``` + +#### スキーマの詳細 + +サンプルアプリケーションの [`schema.json`](https://github.com/scalar-labs/scalardb-samples/tree/master/multi-storage-transaction-sample/schema.json) に示されているように、すべてのテーブルは `customer` および `order` 名前空間に作成されます。 + +- `customer.customers`: 顧客の情報を管理するテーブル + - `credit_limit`: 貸し手が各顧客に信用枠の使用を許可する最大金額 + - `credit_total`: 各顧客が信用枠を使用してすでに使用した金額 +- `order.orders`: 注文情報を管理するテーブル +- `order.statements`: 注文明細情報を管理するテーブル +- `order.items`: 注文するアイテムの情報を管理するテーブル + +スキーマのエンティティリレーションシップダイアグラムは次のとおりです。 + +![ERD](images/ERD.png) + +### 初期データをロードする + +Docker コンテナが起動したら、次のコマンドを実行して初期データをロードします。 + +```console +./gradlew run --args="LoadInitialData" +``` + +初期データがロードされた後、次のレコードがテーブルに保存される必要があります。 + +**`customer.customers` テーブル** + +| customer_id | name | credit_limit | credit_total | +|-------------|---------------|--------------|--------------| +| 1 | Yamada Taro | 10000 | 0 | +| 2 | Yamada Hanako | 10000 | 0 | +| 3 | Suzuki Ichiro | 10000 | 0 | + +**`order.items` テーブル** + +| item_id | name | price | +|---------|--------|-------| +| 1 | Apple | 1000 | +| 2 | Orange | 2000 | +| 3 | Grape | 2500 | +| 4 | Mango | 5000 | +| 5 | Melon | 3000 | + +## サンプルアプリケーションでトランザクションを実行し、データを取得する + +次のセクションでは、サンプル電子商取引アプリケーションでトランザクションを実行し、データを取得する方法について説明します。 + +### 顧客情報を取得する + +次のコマンドを実行して、ID が `1` である顧客に関する情報を取得することから始めます。 + +```console +./gradlew run --args="GetCustomerInfo 1" +``` + +次の出力が表示されます。 + +```console +... +{"id": 1, "name": "Yamada Taro", "credit_limit": 10000, "credit_total": 0} +... +``` + +### 注文する + +次に、次のコマンドを実行して、顧客 ID `1` にリンゴ 3 個とオレンジ 2 個を注文してもらいます。 + +:::note + +このコマンドの注文形式は `./gradlew run --args="PlaceOrder :,:,..."` です。 + +::: + +```console +./gradlew run --args="PlaceOrder 1 1:3,2:2" +``` + +以下のように、`order_id` の UUID が異なる、注文が成功したことを示す出力が表示されます。 + +```console +... +{"order_id": "dea4964a-ff50-4ecf-9201-027981a1566e"} +... +``` + +### 注文の詳細を確認する + +次のコマンドを実行して注文の詳細を確認します。`` は、前のコマンドを実行した後に表示される `order_id` の UUID に置き換えます。 + +```console +./gradlew run --args="GetOrder " +``` + +`order_id` と `timestamp` の UUID が異なる、以下のような出力が表示されます。 + +```console +... +{"order": {"order_id": "dea4964a-ff50-4ecf-9201-027981a1566e","timestamp": 1650948340914,"customer_id": 1,"customer_name": "Yamada Taro","statement": [{"item_id": 1,"item_name": "Apple","price": 1000,"count": 3,"total": 3000},{"item_id": 2,"item_name": "Orange","price": 2000,"count": 2,"total": 4000}],"total": 7000}} +... +``` + +### 別の注文をする + +次のコマンドを実行して、顧客 ID `1` の `credit_total` の残額を使用してメロン 1 個を注文します。 + +```console +./gradlew run --args="PlaceOrder 1 5:1" +``` + +以下のように、`order_id` の UUID が異なる、注文が成功したことを示す出力が表示されます。 + +```console +... +{"order_id": "bcc34150-91fa-4bea-83db-d2dbe6f0f30d"} +... +``` + +### 注文履歴を確認する + +次のコマンドを実行して、顧客 ID `1` のすべての注文履歴を取得します。 + +```console +./gradlew run --args="GetOrders 1" +``` + +`order_id` と `timestamp` の UUID が異なる以下のような出力が表示されます。これは、顧客 ID `1` のすべての注文履歴をタイムスタンプの降順で表示します。 + +```console +... +{"order": [{"order_id": "dea4964a-ff50-4ecf-9201-027981a1566e","timestamp": 1650948340914,"customer_id": 1,"customer_name": "Yamada Taro","statement": [{"item_id": 1,"item_name": "Apple","price": 1000,"count": 3,"total": 3000},{"item_id": 2,"item_name": "Orange","price": 2000,"count": 2,"total": 4000}],"total": 7000},{"order_id": "bcc34150-91fa-4bea-83db-d2dbe6f0f30d","timestamp": 1650948412766,"customer_id": 1,"customer_name": "Yamada Taro","statement": [{"item_id": 5,"item_name": "Melon","price": 3000,"count": 1,"total": 3000}],"total": 3000}]} +... +``` + +### クレジット合計の確認 + +次のコマンドを実行して、顧客 ID `1` のクレジット合計を取得します。 + +```console +./gradlew run --args="GetCustomerInfo 1" +``` + +次の出力が表示されます。これは、顧客 ID `1` が `credit_total` の `credit_limit` に達しており、これ以上注文できないことを示しています。 + +```console +... +{"id": 1, "name": "Yamada Taro", "credit_limit": 10000, "credit_total": 10000} +... +``` + +次のコマンドを実行して、ブドウ 1 個とマンゴー 1 個を注文してみます。 + +```console +./gradlew run --args="PlaceOrder 1 3:1,4:1" +``` + +次の出力が表示されます。これは、`credit_total` 金額が `credit_limit` 金額を超えたために注文が失敗したことを示しています。 + +```console +... +java.lang.RuntimeException: Credit limit exceeded + at sample.Sample.placeOrder(Sample.java:205) + at sample.command.PlaceOrderCommand.call(PlaceOrderCommand.java:33) + at sample.command.PlaceOrderCommand.call(PlaceOrderCommand.java:8) + at picocli.CommandLine.executeUserObject(CommandLine.java:1783) + at picocli.CommandLine.access$900(CommandLine.java:145) + at picocli.CommandLine$RunLast.handle(CommandLine.java:2141) + at picocli.CommandLine$RunLast.handle(CommandLine.java:2108) + at picocli.CommandLine$AbstractParseResultHandler.execute(CommandLine.java:1975) + at picocli.CommandLine.execute(CommandLine.java:1904) + at sample.command.SampleCommand.main(SampleCommand.java:35) +... +``` + +### 支払いを行う + +注文を続行するには、顧客 ID `1` が支払いを行って `credit_total` の金額を減らす必要があります。 + +次のコマンドを実行して支払いを行います。 + +```console +./gradlew run --args="Repayment 1 8000" +``` + +次に、次のコマンドを実行して、顧客 ID `1` の `credit_total` 金額を確認します。 + +```console +./gradlew run --args="GetCustomerInfo 1" +``` + +次の出力が表示されます。これは、顧客 ID `1` に支払いが適用され、`credit_total` の金額が減ったことを示しています。 + +```console +... +{"id": 1, "name": "Yamada Taro", "credit_limit": 10000, "credit_total": 2000} +... +``` + +顧客 ID `1` が支払いを済ませたので、次のコマンドを実行してブドウ 1 個とメロン 1 個を注文します。 + +```console +./gradlew run --args="PlaceOrder 1 3:1,4:1" +``` + +以下のように、`order_id` の UUID が異なる、注文が成功したことを示す出力が表示されます。 + +```console +... +{"order_id": "8911cab3-1c2b-4322-9386-adb1c024e078"} +... +``` + +## サンプルアプリケーションを停止します + +サンプルアプリケーションを停止するには、次のコマンドを実行して Docker コンテナを停止します。 + +```console +docker-compose down +``` diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/multi-storage-transaction-sample/images/ERD.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/multi-storage-transaction-sample/images/ERD.png new file mode 100644 index 00000000..02100437 Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/multi-storage-transaction-sample/images/ERD.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/multi-storage-transaction-sample/images/overview.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/multi-storage-transaction-sample/images/overview.png new file mode 100644 index 00000000..16749f3b Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/multi-storage-transaction-sample/images/overview.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/scalardb-analytics-postgresql-sample/README.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/scalardb-analytics-postgresql-sample/README.mdx new file mode 100644 index 00000000..75e65c50 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/scalardb-analytics-postgresql-sample/README.mdx @@ -0,0 +1,308 @@ +--- +tags: + - Community +--- + +# ScalarDB Analytics with PostgreSQL を使用してサンプルデータに対して分析クエリを実行する + +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このチュートリアルでは、ScalarDB Analytics with PostgreSQL を使用してサンプルデータに対して分析クエリを実行する方法について説明します。 + +## 概要 + +このサンプルチュートリアルでは、単一テーブルクエリと複数テーブルクエリの 2 種類のクエリを実行する方法を示します。 + +### このサンプルチュートリアルで実行できること + +このサンプルチュートリアルでは、次の種類のクエリを実行する方法を示します。 + +- データを読み取り、要約を計算します。 +- 複数のストレージにまたがるテーブルを結合します。 + +:::note + +このサンプルチュートリアルでインポートされたテーブルに対して、PostgreSQL がサポートする任意のクエリを実行できます。ScalarDB Analytics with PostgreSQL は PostgreSQL がサポートするすべてのクエリをサポートしているため、例に示されている結合、集計、フィルタリング、順序付けだけでなく、ウィンドウ関数、ラテラル結合、さまざまな分析操作も使用できます。 + +PostgreSQL がサポートするクエリの種類を確認するには、[PostgreSQL ドキュメント](https://www.postgresql.org/docs/current/index.html)を参照してください。 + +::: + +## 前提条件 + +- [Docker](https://www.docker.com/get-started/) 20.10 以降、および [Docker Compose](https://docs.docker.com/compose/install/) V2 以降 +- [psql](https://www.postgresql.org/docs/current/app-psql.html) + +## ScalarDB Analytics with PostgreSQL を設定する + +まず、ScalarDB Analytics with PostgreSQL を使用して分析クエリを実行するためにデータベースを設定する必要があります。まだデータベースを設定していない場合は、[ScalarDB Analytics with PostgreSQL の使用開始](../../scalardb-analytics-postgresql/getting-started.mdx)の手順に従ってください。 + +### ScalarDB のスキーマの詳細 + +このサンプルチュートリアルでは、ScalarDB データベースに次のスキーマを持つテーブルがあります。 + +```mermaid +erDiagram + "dynamons.customer" ||--|{ "postgresns.orders" : "custkey" + "dynamons.customer" { + int c_custkey + text c_name + text c_address + int c_nationkey + text c_phone + double c_acctbal + text c_mktsegment + text c_comment + } + "postgresns.orders" ||--|{ "cassandrans.lineitem" : "orderkey" + "postgresns.orders" { + int o_orderkey + int o_custkey + text o_orderstatus + double o_totalprice + text o_orderdate + text o_orderpriority + text o_clerk + int o_shippriority + text o_comment + } + "cassandrans.lineitem" { + int l_orderkey + int l_partkey + int l_suppkey + int l_linenumber + double l_quantity + double l_extendedprice + double l_discount + double l_tax + text l_returnflag + text l_linestatus + text l_shipdate + text l_commitdate + text l_receiptdate + text l_shipinstruct + text l_shipmode + text l_comment + } +``` + +参考までに、この図には次の内容が示されています。 + +- `dynamons`、`postgresns`、`cassandrans`。それぞれ DynamoDB、PostgreSQL、Cassandra のバックエンドストレージにマップされる名前空間。 +- `dynamons.customer`。顧客に関する情報を表すテーブル。このテーブルには、顧客キー、名前、住所、電話番号、口座残高などの属性が含まれます。 +- `postgresns.orders`。顧客が行った注文に関する情報を含むテーブル。このテーブルには、注文キー、顧客キー、注文ステータス、注文日、注文優先度などの属性が含まれます。 +- `cassandrans.lineitem`。注文に関連付けられた明細項目を表すテーブル。このテーブルには、注文キー、部品キー、サプライヤーキー、数量、価格、出荷日などの属性が含まれます。 + +### PostgreSQL のスキーマの詳細 + +ScalarDB の設定時にスキーマインポーターを実行すると、ScalarDB データベースのテーブルスキーマを PostgreSQL データベースにインポートできます。より正確には、ScalarDB データベースの各 `namespace_name.table_name` テーブルに対して、PostgreSQL データベースに `namespace_name._table_name` の外部テーブルと `namespace_name.table_name` のビューが作成されます。 + +作成された外部テーブルには、ScalarDB テーブルと同じ列と、ScalarDB が内部で管理するトランザクションメタデータ列が含まれます。作成されたビューは、外部テーブルからトランザクションメタデータ列を除外するように定義されているため、作成されたビューには ScalarDB テーブルと同じ列のみが含まれます。 + +ScalarDB テーブルのスキーマは `schema.json` にあります。たとえば、`dynamons.customer` テーブルは次のように定義されています。 + +```json + "dynamons.customer": { + "transaction": true, + "partition-key": [ + "c_custkey" + ], + "columns": { + "c_custkey": "INT", + "c_name": "TEXT", + "c_address": "TEXT", + "c_nationkey": "INT", + "c_phone": "TEXT", + "c_acctbal": "DOUBLE", + "c_mktsegment": "TEXT", + "c_comment": "TEXT" + } + }, +``` + +PostgreSQL データベース内の `dynamons._customer` の外部テーブルを表示するには、次のコマンドを実行し、プロンプトが表示されたら PostgreSQL ユーザーパスワードを入力します。 + +```console +psql -U postgres -h localhost test -c '\d dynamons._customer'; +``` + +パスワードを入力すると、次の出力が表示されます。これには、`dynamons.customer` テーブルと同じ `c_` 列が表示されます。 + +```console + Foreign table "dynamons._customer" + Column | Type | Collation | Nullable | Default | FDW options +------------------------+------------------+-----------+----------+---------+------------- + c_custkey | integer | | | | + c_name | text | | | | + c_address | text | | | | + c_nationkey | integer | | | | + c_phone | text | | | | + c_acctbal | double precision | | | | + c_mktsegment | text | | | | + c_comment | text | | | | + tx_id | text | | | | + tx_version | integer | | | | + tx_state | integer | | | | + tx_prepared_at | bigint | | | | + tx_committed_at | bigint | | | | + before_tx_id | text | | | | + before_tx_version | integer | | | | + before_tx_state | integer | | | | + before_tx_prepared_at | bigint | | | | + before_tx_committed_at | bigint | | | | + before_c_name | text | | | | + before_c_address | text | | | | + before_c_nationkey | integer | | | | + before_c_phone | text | | | | + before_c_acctbal | double precision | | | | + before_c_mktsegment | text | | | | + before_c_comment | text | | | | +Server: multi_storage_dynamodb +FDW options: (namespace 'dynamons', table_name 'customer') +``` + +外部テーブルを見るとわかるように、テーブルにはトランザクションメタデータ列も含まれています。これらの列は、Read Committed 分離レベルを確保するために必要です。 + +`dynamons.customer` のビューを表示するには、次のコマンドを実行し、プロンプトが表示されたら PostgreSQL ユーザーパスワードを入力します。 + +```console +psql -U postgres -h localhost test -c '\d dynamons.customer'; +``` + +パスワードを入力すると、次の出力が表示されます。 + +```console + View "dynamons.customer" + Column | Type | Collation | Nullable | Default +--------------+------------------+-----------+----------+--------- + c_custkey | integer | | | + c_name | text | | | + c_address | text | | | + c_nationkey | integer | | | + c_phone | text | | | + c_acctbal | double precision | | | + c_mktsegment | text | | | + c_comment | text | | | +``` + +このビューの列定義は、ScalarDB データベースの元のテーブルと同じです。このビューは、トランザクションメタデータ列を解釈して、Read Committed 分離レベルで有効なデータのみを公開するために、上で説明した外部テーブルに基づいて作成されます。 + +:::note + +通常、外部テーブルに直接アクセスする必要はありません。代わりに、ビューを ScalarDB データベース内のテーブルと同等にすることができます。 + +::: + +ScalarDB と PostgreSQL 間の型マッピングの詳細については、[ScalarDB と他のデータベース間のデータ型マッピング](../../schema-loader.mdx#scalardb-と他のデータベース間のデータ型マッピング) を参照してください。 + +## 分析クエリを実行する + +次のセクションでは、データの読み取り、サマリーの計算、複数のストレージにまたがるテーブルの結合方法について説明します。 + +### データの読み取りとサマリーの計算 + +Cassandra バックエンドに保存されている実際のデータを使用して `cassandrans.lineitem` からデータを読み取り、データを集計して順序付けられた明細項目の複数のサマリーを計算するクエリを実行できます。 + +クエリを実行するには、次のコマンドを実行して psql ターミナルにログインします。 + +```console +psql -U postgres -h localhost test +``` + +パスワードを入力した後、psql ターミナルに次のクエリを入力します。 + +```console +SELECT + l_returnflag, + l_linestatus, + sum(l_quantity) AS sum_qty, + sum(l_extendedprice) AS sum_base_price, + sum(l_extendedprice * (1 - l_discount)) AS sum_disc_price, + sum(l_extendedprice * (1 - l_discount) * (1 + l_tax)) AS sum_charge, + avg(l_quantity) AS avg_qty, + avg(l_extendedprice) AS avg_price, + avg(l_discount) AS avg_disc, + count(*) AS count_order +FROM + cassandrans.lineitem +WHERE + to_date(l_shipdate, 'YYYY-MM-DD') <= date '1998-12-01' - 3 +GROUP BY + l_returnflag, + l_linestatus +ORDER BY + l_returnflag, + l_linestatus; +``` + +次の出力が表示されます。 + +```console + l_returnflag | l_linestatus | sum_qty | sum_base_price | sum_disc_price | sum_charge | avg_qty | avg_price | avg_disc | count_order +--------------+--------------+---------+--------------------+--------------------+--------------------+---------------------+--------------------+---------------------+------------- + A | F | 1519 | 2374824.6560430005 | 1387363.5818635763 | 1962762.9341866106 | 26.6491228070175439 | 41663.590456894744 | 0.4150182982456142 | 57 + N | F | 98 | 146371.22954200002 | 85593.92837883368 | 121041.52567369482 | 32.6666666666666667 | 48790.409847333336 | 0.4098473333333333 | 3 + N | O | 5374 | 8007373.247144971 | 4685645.630765834 | 6624209.157932242 | 24.4272727272727273 | 36397.15112338623 | 0.414759749999999 | 220 + R | F | 1461 | 2190869.967642001 | 1284177.8484816086 | 1814150.7929095028 | 25.1896551724137931 | 37773.62013175864 | 0.41323520689655185 | 58 +(4 rows) +``` + +### 複数のストレージにまたがるテーブルを結合する + +クエリを実行して、3 つのバックエンドストレージに接続されているテーブルを結合し、特定の日付に最も高い収益を持つ未出荷の注文を計算することもできます。 + +クエリを実行するには、次のコマンドを実行して psql ターミナルにログインします。 + +```console +psql -U postgres -h localhost test +``` + +パスワードを入力した後、psql ターミナルに次のクエリを入力します。 + +```console +SELECT + l_orderkey, + sum(l_extendedprice * (1 - l_discount)) AS revenue, + o_orderdate, + o_shippriority +FROM + dynamons.customer, + postgresns.orders, + cassandrans.lineitem +WHERE + c_mktsegment = 'AUTOMOBILE' + AND c_custkey = o_custkey + AND l_orderkey = o_orderkey + AND o_orderdate < '1995-03-15' + AND l_shipdate > '1995-03-15' +GROUP BY + l_orderkey, + o_orderdate, + o_shippriority +ORDER BY + revenue DESC, + o_orderdate, + l_orderkey +LIMIT 10; +``` + +次の出力が表示されます。 + +```console + l_orderkey | revenue | o_orderdate | o_shippriority +------------+--------------------+-------------+---------------- + 1071617 | 128186.94002748765 | 1995-03-10 | 0 + 1959075 | 33104.49713665398 | 1994-12-23 | 0 + 430243 | 19476.107574179696 | 1994-12-24 | 0 +(3 rows) +``` + +## ScalarDB Analytics with PostgreSQL とデータベースを停止する + +ScalarDB Analytics with PostgreSQL とデータベースを停止するには、次のコマンドを実行して Docker コンテナを停止します。 + +```console +docker-compose down +``` diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/scalardb-analytics-spark-sample/README.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/scalardb-analytics-spark-sample/README.mdx new file mode 100644 index 00000000..a9325d77 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/scalardb-analytics-spark-sample/README.mdx @@ -0,0 +1,283 @@ +--- +tags: + - Enterprise Option + - Private Preview +--- + +# ScalarDB Analytics with Spark を使用してサンプルデータに対して分析クエリを実行する + +import WarningLicenseKeyContact from '/src/components/ja-jp/_warning-license-key-contact.mdx'; +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このチュートリアルでは、ScalarDB Analytics with Spark を使用してサンプルデータに対して分析クエリを実行する方法について説明します。ソースコードは https://github.com/scalar-labs/scalardb-samples/scalardb-analytics-spark-sample で入手できます。 + +## このサンプルアプリケーションでできること + +このサンプルチュートリアルでは、ScalarDB Analytics with Spark を使用して Spark シェルでインタラクティブ分析を実行する方法を説明します。特に、次の 2 種類のクエリを実行する方法を学習します。 + +- データを読み取り、要約を計算します。 +- 複数のストレージにまたがるテーブルを結合します。 + +## 前提条件 + +- [Docker](https://www.docker.com/get-started/) 20.10 以降と [Docker Compose](https://docs.docker.com/compose/install/) V2 以降 + + + +## ScalarDB Analytics with Spark を設定する + +### ScalarDB サンプルリポジトリをクローンする + +**ターミナル** を開き、次のコマンドを実行して ScalarDB サンプルリポジトリをクローンします。 + +```console +git clone https://github.com/scalar-labs/scalardb-samples +``` + +次に、次のコマンドを実行して、サンプルアプリケーションが含まれているディレクトリに移動します。 + +```console +cd scalardb-samples/scalardb-analytics-spark-sample +``` + +### ライセンス証明書をサンプルディレクトリに追加する + +次のコマンドを実行して、ライセンス証明書 (`cert.pem`) をサンプルディレクトリにコピーします。`` はライセンスへのパスに置き換えてください。 + +```console +cp //cert.pem cert.pem +``` + +### ScalarDB でサンプルの基礎データベースを設定する + +ScalarDB のサンプルの基礎データベースを設定するには、次のコマンドを実行します。 + +```console +docker compose up -d --wait +``` + +このコマンドは、PostgreSQL、Cassandra、DynamoDB の 3 つのサービスをローカルで起動します。 + +次に、次のコマンドを実行して、これらのサービスにサンプルデータベースを設定します。 + +```console +docker compose run --rm sample-data-loader +``` + +このコマンドは、それぞれローカルの PostgreSQL、Cassandra、DyanmoDB サービスにマップされる `postgresns`、`cassandrans`、`dynamons` 名前空間を作成し、`postgresns.orders`、`cassandrans.lineitem`、`dynamons.customer` テーブルを作成し、サンプルデータをそれらのテーブルにロードします。テーブルスキーマの詳細については、[スキーマの詳細](#schema-details) を参照してください。 + +### Spark シェルで ScalarDB Analytics with Spark を設定する + +Spark シェルを起動するには、次のコマンドを実行します。 + +```console +docker compose run --rm spark-shell +``` + +`docker-compose.yml` でわかるように、このコマンドは `--packages com.scalar-labs:scalardb-analytics-spark-_:` オプションを指定して `spark-shell` コマンドを実行します。このオプションを使用すると、`spark-shell` は Maven Central Repository から ScalarDB Analytics with Spark を自動的にダウンロードし、それを `spark-shell` のクラスパスに追加します。 + +Spark シェルコンソールで、次のコマンドを実行して ScalarDB Analytics with Spark を設定できます。 + +```console +scala> import com.scalar.db.analytics.spark.implicits._ +scala> spark.setupScalarDbAnalytics( + | configPath = "/etc/scalardb.properties", + | namespaces = Set("postgresns", "cassandrans", "dynamons"), + | license = License.certPath("""{"your":"license", "key":"in", "json":"format"}""", "/etc/cert.pem") + | ) +``` + +:::warning + +ライセンスは JSON 文字列で参照されるため、[ライセンス証明書をサンプルディレクトリに追加する](#ライセンス証明書をサンプルディレクトリに追加する)の説明に従って、ライセンス証明書をサンプルディレクトリにコピーしておく必要があることに注意してください。 + +::: + +これで、Spark 側に、ScalarDB のテーブルと同等の `postgresns.orders`、`cassandrans.lineitem`、`dynamons.customer` のテーブルが作成されます。例: + +```console +scala> sql("DESCRIBE postgresns.orders").show() ++---------------+---------+-------+ +| col_name|data_type|comment| ++---------------+---------+-------+ +| o_orderkey| int| NULL| +| o_custkey| int| NULL| +| o_orderstatus| string| NULL| +| o_totalprice| double| NULL| +| o_orderdate| string| NULL| +|o_orderpriority| string| NULL| +| o_clerk| string| NULL| +| o_shippriority| int| NULL| +| o_comment| string| NULL| ++---------------+---------+-------+ +``` + +## 分析クエリを実行する + +次のセクションでは、データの読み取り、サマリーの計算、複数のストレージにまたがるテーブルの結合方法について説明します。 + +### データの読み取りとサマリーの計算 + +Cassandra に保存されている実際のデータを使用して `cassandrans.lineitem` からデータを読み取り、データを集計して順序付けられた明細項目の複数のサマリーを計算するクエリを実行できます。 + +クエリを実行するには、Spark シェルコンソールで次のコマンドを実行します。 + +```scala +scala> sql(""" + SELECT + l_returnflag, + l_linestatus, + sum(l_quantity) AS sum_qty, + sum(l_extendedprice) AS sum_base_price, + sum(l_extendedprice * (1 - l_discount)) AS sum_disc_price, + sum(l_extendedprice * (1 - l_discount) * (1 + l_tax)) AS sum_charge, + avg(l_quantity) AS avg_qty, + avg(l_extendedprice) AS avg_price, + avg(l_discount) AS avg_disc, + count(*) AS count_order + FROM + cassandrans.lineitem + WHERE + to_date(l_shipdate, 'yyyy-MM-dd') <= date '1998-12-01' - 3 + GROUP BY + l_returnflag, + l_linestatus + ORDER BY + l_returnflag, + l_linestatus; + """).show() +``` + +次の出力が表示されます。 + +```console ++------------+------------+-------+------------------+------------------+------------------+------------------+------------------+-------------------+-----------+ +|l_returnflag|l_linestatus|sum_qty| sum_base_price| sum_disc_price| sum_charge| avg_qty| avg_price| avg_disc|count_order| ++------------+------------+-------+------------------+------------------+------------------+------------------+------------------+-------------------+-----------+ +| A| F| 1519|2374824.6560278563|1387364.2207725341|1962763.4654265852|26.649122807017545|41663.590456629056|0.41501802923479575| 57| +| N| F| 98| 146371.2295412012| 85593.96776336085|121041.55837332775|32.666666666666664|48790.409847067065|0.40984706454007996| 3| +| N| O| 5374| 8007373.247086477| 4685647.785126835| 6624210.945739046|24.427272727272726| 36397.15112312035| 0.4147594809559689| 220| +| R| F| 1461|2190869.9676265526|1284178.4378283697|1814151.2807494882|25.189655172413794| 37773.62013149229|0.41323493790730753| 58| ++------------+------------+-------+------------------+------------------+------------------+------------------+------------------+-------------------+-----------+ +``` + +### 複数のデータベースにまたがるテーブルを結合する + +クエリを実行して、3 つのバックエンドデータベースに接続されているテーブルを結合し、特定の日付に最も高い収益を持つ未出荷の注文を計算することもできます。 + +クエリを実行するには、Spark シェルコンソールで次のコマンドを実行します。 + +```scala +scala> sql(""" + SELECT + l_orderkey, + sum(l_extendedprice * (1 - l_discount)) AS revenue, + o_orderdate, + o_shippriority + FROM + dynamons.customer, + postgresns.orders, + cassandrans.lineitem + WHERE + c_mktsegment = 'AUTOMOBILE' + AND c_custkey = o_custkey + AND l_orderkey = o_orderkey + AND o_orderdate < '1995-03-15' + AND l_shipdate > '1995-03-15' + GROUP BY + l_orderkey, + o_orderdate, + o_shippriority + ORDER BY + revenue DESC, + o_orderdate, + l_orderkey + LIMIT 10; + """).show() +``` + +次の出力が表示されます。 + +```console ++----------+------------------+-----------+--------------+ +|l_orderkey| revenue|o_orderdate|o_shippriority| ++----------+------------------+-----------+--------------+ +| 1071617|128186.99915996166| 1995-03-10| 0| +| 1959075| 33104.51278645416| 1994-12-23| 0| +| 430243|19476.115819260962| 1994-12-24| 0| ++----------+------------------+-----------+--------------+ +``` + +:::note + +このサンプルチュートリアルでインポートされたテーブルに対して、Apache Spark および Spark SQL がサポートする任意のクエリを実行することもできます。ScalarDB Analytics with Spark は、Spark SQL がサポートするすべてのクエリをサポートしているため、例に示されている結合、集計、フィルタリング、順序付けだけでなく、ウィンドウ関数、ラテラル結合、さまざまな分析操作も使用できます。 + +Spark SQL がサポートするクエリの種類を確認するには、[Spark SQL ドキュメント](https://spark.apache.org/docs/latest/sql-ref.html)を参照してください。 + +::: + +## サンプルアプリケーションを停止します + +サンプルアプリケーションを停止するには、次のコマンドを実行して Docker コンテナを停止します。 + +```console +docker compose down +``` + +## リファレンス - スキーマの詳細 + +このサンプルチュートリアルでは、ScalarDB の基盤となるデータベースに次のスキーマを持つテーブルがあります。 + +```mermaid +erDiagram + "dynamons.customer" ||--|{ "postgresns.orders" : "custkey" + "dynamons.customer" { + int c_custkey + text c_name + text c_address + int c_nationkey + text c_phone + double c_acctbal + text c_mktsegment + text c_comment + } + "postgresns.orders" ||--|{ "cassandrans.lineitem" : "orderkey" + "postgresns.orders" { + int o_orderkey + int o_custkey + text o_orderstatus + double o_totalprice + text o_orderdate + text o_orderpriority + text o_clerk + int o_shippriority + text o_comment + } + "cassandrans.lineitem" { + int l_orderkey + int l_partkey + int l_suppkey + int l_linenumber + double l_quantity + double l_extendedprice + double l_discount + double l_tax + text l_returnflag + text l_linestatus + text l_shipdate + text l_commitdate + text l_receiptdate + text l_shipinstruct + text l_shipmode + text l_comment + } +``` + +参考までに、この図には次の内容が示されています。 + +- `dynamons`、`postgresns`、`cassandrans`。それぞれ DynamoDB、PostgreSQL、Cassandra のバックエンドストレージにマップされる名前空間。 +- `dynamons.customer`。顧客に関する情報を表すテーブル。このテーブルには、顧客キー、名前、住所、電話番号、口座残高などの属性が含まれます。 +- `postgresns.orders`。顧客が行った注文に関する情報を含むテーブル。このテーブルには、注文キー、顧客キー、注文ステータス、注文日、注文優先度などの属性が含まれます。 +- `cassandrans.lineitem`。注文に関連付けられた明細項目を表すテーブル。このテーブルには、注文キー、部品キー、サプライヤーキー、数量、価格、出荷日などの属性が含まれます。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-microservice-transaction-sample/README.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-microservice-transaction-sample/README.mdx new file mode 100644 index 00000000..c251e259 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-microservice-transaction-sample/README.mdx @@ -0,0 +1,532 @@ +--- +tags: + - Enterprise Premium +--- + +# マイクロサービストランザクションを使用した Spring Data JDBC for ScalarDB のサンプルアプリケーション + +import WarningLicenseKeyContact from '/src/components/ja-jp/_warning-license-key-contact.mdx'; +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このチュートリアルでは、Spring Data JDBC for ScalarDB を使用してマイクロサービストランザクション用のサンプル Spring Boot アプリケーションを作成する方法について説明します。 + +これらの機能の詳細については、[2 フェーズコミットトランザクション](../../two-phase-commit-transactions.mdx) および [Spring Data JDBC for ScalarDB ガイド](../../scalardb-sql/spring-data-guide.mdx)を参照してください。 + +## このサンプルアプリケーションの前提条件 + +- [Eclipse Temurin](https://adoptium.net/temurin/releases/) の OpenJDK LTS バージョン (8、11、17、または 21) +- [Docker](https://www.docker.com/get-started/) 20.10 以降 ([Docker Compose](https://docs.docker.com/compose/install/) V2 以降) + +:::note + +このサンプルアプリケーションは、Eclipse Temurin の OpenJDK でテストされています。ただし、ScalarDB 自体は、さまざまなベンダーの JDK ディストリビューションでテストされています。互換性のある JDK ディストリビューションを含む ScalarDB の要件の詳細については、[要件](../../requirements.mdx)を参照してください。 + +::: + + + +## サンプルアプリケーション + +### 概要 + +このチュートリアルでは、ScalarDB の [2 フェーズコミットインターフェースを使用したトランザクション](../../two-phase-commit-transactions.mdx)を通じて、アイテムを注文し、信用枠で支払うことができるサンプル電子商取引アプリケーションを作成するプロセスについて説明します。 + +このサンプルアプリケーションには、[*Database-per-service* pattern](https://microservices.io/patterns/data/database-per-service.html) に基づく *Customer Service* と *Order Service* という 2 つのマイクロサービスがあります。 + +Customer Service は、クレジット限度額やクレジット合計などのクレジットカード情報を含む顧客情報を管理します。Order Service は、注文の確定や注文履歴の取得などの注文操作を担当します。 + +各サービスには gRPC エンドポイントがあります。クライアントはエンドポイントを呼び出し、サービスも互いにエンドポイントを呼び出します。Customer Service と Order Service は、それぞれ ScalarDB を介して MySQL と Cassandra を使用します。 + +![概要](images/overview.png) + +各サービスは、専用の ScalarDB Cluster を介してデータベースにアクセスします。 + +:::note + +両方の ScalarDB Cluster は、Consensus Commit プロトコルに使用される小さなコーディネーターデータベースにアクセスします。このサンプルアプリケーションでは、セットアップと説明を簡単にするために、コーディネーターデータベースは Order Service の同じ Cassandra インスタンスに共存していますが、もちろん、コーディネーターデータベースは別のデータベースとして管理できます。 + +また、サンプルアプリケーションでは ScalarDB の使用方法の説明に重点を置いているため、アプリケーション固有のエラー処理、認証処理などは省略されています。 + +ScalarDB での例外処理の詳細については、[例外の処理方法](../../two-phase-commit-transactions.mdx#例外の処理方法)を参照してください。 + +::: + +### サービスエンドポイント + +サービスで定義されているエンドポイントは次のとおりです。 + +- Customer Service + - `getCustomerInfo` + - `payment` + - `prepare` + - `validate` + - `commit` + - `rollback` + - `repayment` + +- Order Service + - `placeOrder` + - `getOrder` + - `getOrders` + +### このサンプルアプリケーションで実行できること + +サンプルアプリケーションは、次の種類のトランザクションをサポートしています。 + +- Customer Service の `getCustomerInfo` エンドポイントを介して顧客情報を取得します。 +- Order Service の `placeOrder` エンドポイントと、Customer Service の `payment`、`prepare`、`validate`、`commit`、`rollback` エンドポイントを介して、信用枠を使用して注文を行います。 + - 注文のコストが顧客の信用限度額を下回っているかどうかを確認します。 + - チェックに合格した場合、注文履歴を記録し、顧客が支払った金額を更新します。 +- Order Service の `getOrder` エンドポイントと、Customer Service の `getCustomerInfo`、`prepare`、`validate`、`commit`、`rollback` エンドポイントを介して、注文 ID で注文情報を取得します。 +- Order Service の `getOrders` エンドポイントと、Customer Service の `getCustomerInfo`、`prepare`、`validate`、`commit`、`rollback` エンドポイントを介して、顧客 ID で注文情報を取得します。 +- Customer Service の `repayment` エンドポイントを介して支払いを行います。 + - 顧客が支払った金額を減らします。 + +:::note + +`getCustomerInfo` エンドポイントは、コーディネーターからトランザクション ID を受信するときに、参加者サービスエンドポイントとして機能します。 + +::: + +## ScalarDB Cluster の設定 + +[Customer Service 用の ScalarDB Cluster の設定](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/scalardb-cluster-node-for-customer-service.properties)は次のとおりです。 + +```properties +scalar.db.storage=multi-storage +scalar.db.multi_storage.storages=cassandra,mysql +scalar.db.multi_storage.storages.cassandra.storage=cassandra +scalar.db.multi_storage.storages.cassandra.contact_points=cassandra-1 +scalar.db.multi_storage.storages.cassandra.username=cassandra +scalar.db.multi_storage.storages.cassandra.password=cassandra +scalar.db.multi_storage.storages.mysql.storage=jdbc +scalar.db.multi_storage.storages.mysql.contact_points=jdbc:mysql://mysql-1:3306/ +scalar.db.multi_storage.storages.mysql.username=root +scalar.db.multi_storage.storages.mysql.password=mysql +scalar.db.multi_storage.namespace_mapping=customer_service:mysql,coordinator:cassandra +scalar.db.multi_storage.default_storage=mysql +scalar.db.consensus_commit.isolation_level=SERIALIZABLE + +scalar.db.cluster.node.standalone_mode.enabled=true +scalar.db.sql.enabled=true + +# License key configurations +scalar.db.cluster.node.licensing.license_key= +scalar.db.cluster.node.licensing.license_check_cert_pem= +``` + +- `scalar.db.sql.connection_mode`: この設定は、ScalarDB への接続方法を決定します。 +- `scalar.db.storage`: ScalarDB でマルチストレージトランザクションを使用するには、`multi-storage` を指定する必要があります。 +- `scalar.db.multi_storage.storages`: ここでストレージ名を定義する必要があります。 +- `scalar.db.multi_storage.storages.cassandra.*`: これらの設定は、`scalar.db.multi_storage.storages` で定義されているストレージ名の 1 つである `cassandra` ストレージ用です。`cassandra` ストレージのすべての `scalar.db.*` プロパティをここで設定できます。 +- `scalar.db.multi_storage.storages.mysql.*`: これらの設定は、`scalar.db.multi_storage.storages` で定義されているストレージ名の 1 つである `mysql` ストレージ用です。ここで、`mysql` ストレージのすべての `scalar.db.*` プロパティを設定できます。 +- `scalar.db.multi_storage.namespace_mapping`: この設定は、名前空間をストレージにマップします。このサンプルアプリケーションでは、`customer_service` 名前空間テーブルの操作は `mysql` ストレージにマップされ、`order_service` 名前空間テーブルの操作は `cassandra` ストレージにマップされます。また、Consensus Commit トランザクションで使用される `coordinator` 名前空間にマップされるストレージを定義することもできます。 +- `scalar.db.multi_storage.default_storage`: この設定は、マッピングされていない名前空間テーブルでの操作に使用されるデフォルトのストレージを設定します。 +- `scalar.db.sql.default_transaction_mode`: ScalarDB で 2 フェーズコミットトランザクションモードを使用するには、`two_phase_commit_transaction` を指定する必要があります。 +- `scalar.db.consensus_commit.isolation_level`: この設定は、ConsensusCommit に使用される分離レベルを決定します。 + +詳細については、[マルチストレージトランザクション](../../multi-storage-transactions.mdx)を参照してください。 + +[Order Service 用の ScalarDB Cluster の設定](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/scalardb-cluster-node-for-order-service.properties)は次のとおりです。 + +```properties +scalar.db.storage=cassandra +scalar.db.contact_points=cassandra-1 +scalar.db.username=cassandra +scalar.db.password=cassandra +scalar.db.consensus_commit.isolation_level=SERIALIZABLE + +scalar.db.cluster.node.standalone_mode.enabled=true +scalar.db.sql.enabled=true + +# License key configurations +scalar.db.cluster.node.licensing.license_key= +scalar.db.cluster.node.licensing.license_check_cert_pem= +``` + +- `scalar.db.storage`: このサービスは Cassandra のみを基盤データベースとして使用するため、`cassandra` が指定されています。 +- `scalar.db.contact_points`: この設定では、Cassandra に接続するための連絡先 (ホストなど) を指定します。 +- `scalar.db.username`: この設定では、Cassandra に接続するためのユーザー名を指定します。 +- `scalar.db.password`: この設定では、Cassandra に接続するためのパスワードを指定します。 +- `scalar.db.sql.default_namespace_name`: この設定では、デフォルトの名前空間が `order_service` に設定されるため、アプリケーションで名前空間を指定する必要がなくなります。 +- `scalar.db.sql.default_transaction_mode`: ScalarDB で 2 フェーズコミットトランザクションモードを使用するには、`two_phase_commit_transaction` を指定する必要があります。 +- `scalar.db.consensus_commit.isolation_level`: この設定は、ConsensusCommit に使用される分離レベルを決定します。 + +このサンプルアプリケーションでは、ScalarDB Cluster はスタンドアロンモード (`scalar.db.cluster.node.standalone_mode.enabled=true`) で実行されています。 + +また、設定ファイルで ScalarDB Cluster のライセンスキー (試用ライセンスまたは商用ライセンス) を設定する必要があります。詳細については、[製品ライセンスキーの設定方法](../../scalar-licensing/README.mdx)を参照してください。 + +## セットアップ + +### ScalarDB サンプルリポジトリのクローンを作成する + +ターミナルを開き、次のコマンドを実行して ScalarDB サンプルリポジトリのクローンを作成します。 + +```console +git clone https://github.com/scalar-labs/scalardb-samples +``` + +次に、次のコマンドを実行して、このサンプルがあるディレクトリに移動します。 + +```console +cd scalardb-samples/spring-data-microservice-transaction-sample +``` + +### ライセンスキーを設定する + +設定ファイル [`scalardb-cluster-node-for-customer-service.properties`](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/scalardb-cluster-node-for-customer-service.properties) および [`scalardb-cluster-node-for-order-service.properties`](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/scalardb-cluster-node-for-order-service.properties) で、ScalarDB Clusters のライセンスキー (試用ライセンスまたは商用ライセンス) を設定します。詳細については、[製品ライセンスキーの設定方法](../../scalar-licensing/README.mdx) を参照してください。 + +### Cassandra、MySQL、および ScalarDB Cluster を起動する + +Cassandra、MySQL、および ScalarDB Cluster を起動するには、次の `docker-compose` コマンドを実行する必要があります。 + +```console +docker-compose up -d cassandra mysql scalardb-cluster-node-for-customer-service scalardb-cluster-node-for-order-service +``` + +:::note + +コンテナが完全に起動するまで 1 分以上待つ必要があります。 + +::: + +### スキーマをロード + +サンプルアプリケーションのデータベーススキーマ (データを整理する方法) は、Customer Service の場合は [`schema-for-customer-service.sql`](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/schema-for-customer-service.sql)、Order Service の場合は [`schema-for-order-service.sql`](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/schema-for-order-service.sql) で既に定義されています。 + +スキーマを適用するには、[ScalarDB リリース](https://github.com/scalar-labs/scalardb/releases)ページに移動し、使用する ScalarDB のバージョンに一致する SQL CLI ツールをダウンロードします。 + +#### MySQL + +[`schema-for-customer-service.sql`](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/schema-for-customer-service.sql) のスキーマを MySQL にロードするには、`` をダウンロードした ScalarDB Schema Loader のバージョンに置き換えて、次のコマンドを実行します。 + +```console +java -jar scalardb-cluster-sql-cli--all.jar --config scalardb-cluster-node-for-customer-service-client.properties --file schema-for-customer-service.sql +``` + +#### Cassandra + +[`schema-for-order-service.sql`](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/schema-for-order-service.sql) のスキーマを Cassandra にロードするには、`` をダウンロードした ScalarDB Schema Loader のバージョンに置き換えて、次のコマンドを実行します。 + +```console +java -jar scalardb-cluster-sql-cli--all.jar --config scalardb-cluster-node-for-order-service-client.properties --file schema-for-order-service.sql +``` + +#### スキーマの詳細 + +[`schema-for-customer-service.sql`](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/schema-for-customer-service.sql) に示されているように、Customer Service のすべてのテーブルは `customer_service` 名前空間に作成されます。 + +- `customer_service.customers`: 顧客の情報を管理するテーブル + - `credit_limit`: 貸し手が各顧客に信用枠の使用を許可する最大金額 + - `credit_total`: 各顧客が信用枠を使用してすでに使用した金額 + +[`schema-for-order-service.sql`](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/schema-for-order-service.sql) に示されているように、Order Service のすべてのテーブルは `order_service` 名前空間に作成されます。 + +- `order_service.orders`: 注文情報を管理するテーブル +- `order_service.statements`: 注文明細情報を管理するテーブル +- `order_service.items`: 注文する商品の情報を管理するテーブル + +スキーマのエンティティリレーションシップダイアグラムは次のとおりです。 + +![ERD](images/ERD.png) + +### マイクロサービスを開始する + +まず、次のコマンドを使用してサンプルアプリケーションの Docker イメージをビルドする必要があります。 + +```console +./gradlew docker +``` + +次に、次の `docker-compose` コマンドを使用してマイクロサービスを起動できます。 + +```console +docker-compose up -d customer-service order-service +``` + +### 初期データ + +マイクロサービスが起動すると、初期データが自動的にロードされます。 + +初期データがロードされたら、次のレコードがテーブルに保存されます: + +- `customer_service.customers` テーブルの場合: + +| customer_id | name | credit_limit | credit_total | +|-------------|---------------|--------------|--------------| +| 1 | Yamada Taro | 10000 | 0 | +| 2 | Yamada Hanako | 10000 | 0 | +| 3 | Suzuki Ichiro | 10000 | 0 | + +- `order_service.items` テーブルの場合: + +| item_id | name | price | +|---------|--------|-------| +| 1 | Apple | 1000 | +| 2 | Orange | 2000 | +| 3 | Grape | 2500 | +| 4 | Mango | 5000 | +| 5 | Melon | 3000 | + +## サンプルアプリケーションを実行する + +まず、ID が `1` である顧客に関する情報を取得します。 + +```console +./gradlew :client:run --args="GetCustomerInfo 1" +... +{"id": 1,"name": "Yamada Taro","credit_limit": 10000} +... +``` + +この時点では、`credit_total` は表示されません。つまり、`credit_total` の現在の値は `0` です。 + +次に、顧客 ID `1` を使用して、リンゴ 3 個とオレンジ 2 個を注文します。 + +注文の形式は `:,:,...` であることに注意してください。 + +```console +./gradlew :client:run --args="PlaceOrder 1 1:3,2:2" +... +{"order_id": "415a453b-cfee-4c48-b8f6-d103d3e10bdb"} +... +``` + +このコマンドを実行すると、注文 ID が表示されます。 + +注文 ID を使用して注文の詳細を確認してみましょう。 + +```console +./gradlew :client:run --args="GetOrder 415a453b-cfee-4c48-b8f6-d103d3e10bdb" +... +{"order": {"order_id": "415a453b-cfee-4c48-b8f6-d103d3e10bdb","timestamp": 1686555272435,"customer_id": 1,"customer_name": "Yamada Taro","statement": [{"item_id": 1,"item_name": "Apple","price": 1000,"count": $ +,"total": 3000},{"item_id": 2,"item_name": "Orange","price": 2000,"count": 2,"total": 4000}],"total": 7000}} +... +``` + +次に、別の注文を出して、顧客 ID `1` の注文履歴を取得しましょう。 + +```console +./gradlew :client:run --args="PlaceOrder 1 5:1" +... +{"order_id": "069be075-98f7-428c-b2e0-6820693fc41b"} +... +./gradlew :client:run --args="GetOrders 1" +... +{"order": [{"order_id": "069be075-98f7-428c-b2e0-6820693fc41b","timestamp": 1686555279366,"customer_id": 1,"customer_name": "Yamada Taro","statement": [{"item_id": 5,"item_name": "Melon","price": 3000,"count": 1,"total": 3000}],"total": 3000},{"order_id": "415a453b-cfee-4c48-b8f6-d103d3e10bdb","timestamp": 1686555272435,"customer_id": 1,"customer_name": "Yamada Taro","statement": [{"item_id": 1,"item_name": "Apple","price": 1000,"count": 3,"total": 3000},{"item_id": 2,"item_name": "Orange","price": 2000,"count": 2,"total": 4000}],"total": 7000}]} +... +``` + +この注文履歴は、タイムスタンプの降順で表示されます。 + +顧客の現在の `credit_total` は `10000` です。顧客は、情報を取得したときに表示された `credit_limit` に達したため、これ以上注文することはできません。 + +```console +./gradlew :client:run --args="GetCustomerInfo 1" +... +{"id": 1,"name": "Yamada Taro","credit_limit": 10000,"credit_total": 10000} +... +./gradlew :client:run --args="PlaceOrder 1 3:1,4:1" +... +io.grpc.StatusRuntimeException: FAILED_PRECONDITION: Credit limit exceeded. creditTotal:10000, payment:7500 + at io.grpc.stub.ClientCalls.toStatusRuntimeException(ClientCalls.java:271) + at io.grpc.stub.ClientCalls.getUnchecked(ClientCalls.java:252) + at io.grpc.stub.ClientCalls.blockingUnaryCall(ClientCalls.java:165) + at sample.rpc.OrderServiceGrpc$OrderServiceBlockingStub.placeOrder(OrderServiceGrpc.java:296) + at sample.client.command.PlaceOrderCommand.call(PlaceOrderCommand.java:38) + at sample.client.command.PlaceOrderCommand.call(PlaceOrderCommand.java:12) + at picocli.CommandLine.executeUserObject(CommandLine.java:2041) + at picocli.CommandLine.access$1500(CommandLine.java:148) + at picocli.CommandLine$RunLast.executeUserObjectOfLastSubcommandWithSameParent(CommandLine.java:2461) + at picocli.CommandLine$RunLast.handle(CommandLine.java:2453) + at picocli.CommandLine$RunLast.handle(CommandLine.java:2415) + at picocli.CommandLine$AbstractParseResultHandler.execute(CommandLine.java:2273) + at picocli.CommandLine$RunLast.execute(CommandLine.java:2417) + at picocli.CommandLine.execute(CommandLine.java:2170) + at sample.client.Client.main(Client.java:39) +... +``` + +支払いが完了すると、顧客は再度注文できるようになります。 + +```console +./gradlew :client:run --args="Repayment 1 8000" +... +./gradlew :client:run --args="GetCustomerInfo 1" +... +{"id": 1,"name": "Yamada Taro","credit_limit": 10000,"credit_total": 2000} +... +./gradlew :client:run --args="PlaceOrder 1 3:1,4:1" +... +{"order_id": "b6adabd8-0a05-4109-9618-3420fea3161f"} +... +``` + +## クリーンアップ + +Cassandra、MySQL、マイクロサービスを停止するには、次のコマンドを実行します。 + +```console +docker-compose down +``` + +## リファレンス - マイクロサービストランザクションの実現方法 + +注文、単一注文の取得、注文履歴の取得のトランザクションは、マイクロサービストランザクションを実現します。このセクションでは、注文を例に、Customer Service と Order Service にまたがるトランザクションの実装方法に焦点を当てます。 + +次のシーケンス図は、注文を行うトランザクションを示しています。 + +![シーケンス図](images/sequence_diagram.png) + +### 1. 2 フェーズコミットインターフェースによるトランザクションが開始されます + +クライアントが Order Service に注文リクエストを送信すると、`OrderService.placeOrder()` が呼び出され、マイクロサービストランザクションが開始されます。 + +最初に、Order Service は次のように `ScalarDbTwoPcRepository.executeTwoPcTransaction()` を使用して 2 フェーズコミットインターフェースによるトランザクションを開始します。参考として、[`OrderService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/order-service/src/main/java/sample/order/OrderService.java) を参照してください。 + +```java +// Start a two-phase commit interface transaction +TwoPcResult result = orderRepository.executeTwoPcTransaction(txId -> { + ... +}, ...); +``` + +[CRUD 操作が実行される](#2-crud-operations-are-executed)、[2 フェーズコミットプロトコルを使用してトランザクションがコミットされる](#3-トランザクションは-2-相コミットプロトコルを使用してコミットされます)、[エラー処理](#エラー処理)のアクションは、API によって自動的に実行されます。 + +### 2. CRUD 操作が実行される + +2 フェーズコミットインターフェイスを使用したトランザクションが開始されると、`ScalarDbTwoPcRepository.executeTwoPcTransaction()` によって CRUD 操作が実行されます。Order Service は、注文情報を `order_service.orders` テーブルに、詳細情報を `order_service.statements` テーブルに次のように格納します。参考までに、[`OrderService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/order-service/src/main/java/sample/order/OrderService.java) を参照してください。 + +```java +// Put the order info into the `orders` table +orderRepository.insert(order); + +AtomicInteger amount = new AtomicInteger(); +for (ItemOrder itemOrder : request.getItemOrderList()) { + int itemId = itemOrder.getItemId(); + int count = itemOrder.getCount(); + // Retrieve the item info from the `items` table + Optional itemOpt = itemRepository.findById(itemId); + if (!itemOpt.isPresent()) { + String message = "Item not found: " + itemId; + responseObserver.onError( + Status.NOT_FOUND.withDescription(message).asRuntimeException()); + throw new ScalarDbNonTransientException(message); + } + Item item = itemOpt.get(); + + int cost = item.price * count; + // Put the order statement into the `statements` table + statementRepository.insert(new Statement(itemId, orderId, count)); + // Calculate the total amount + amount.addAndGet(cost); +} +``` + +次に、Order Service は、トランザクション ID とともに Customer Service の `payment` gRPC エンドポイントを呼び出します。参考については、[`OrderService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/order-service/src/main/java/sample/order/OrderService.java) を参照してください。 + +```java +customerServiceStub.payment( + PaymentRequest.newBuilder() + .setTransactionId(transactionId) + .setCustomerId(customerId) + .setAmount(amount) + .build()); +``` + +Customer Service の `payment` エンドポイントは、まず次のように `ScalarDbTwoPcRepository.joinTransactionOnParticipant()` を使用してトランザクションを結合します。参考として、[`CustomerService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/customer-service/src/main/java/sample/customer/CustomerService.java) を参照してください。 + +```java +customerRepository.joinTransactionOnParticipant(request.getTransactionId(), ...); +``` + +次に、エンドポイントは顧客情報を取得し、支払い後に顧客のクレジット合計がクレジット限度額を超えているかどうかを確認します。クレジット合計がクレジット限度額を超えていない場合、エンドポイントは顧客のクレジット合計を更新します。参考として、[`CustomerService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/customer-service/src/main/java/sample/customer/CustomerService.java) を参照してください。 + +```java +Customer customer = getCustomer(responseObserver, request.getCustomerId()); + +int updatedCreditTotal = customer.creditTotal + request.getAmount(); +// Check if the credit total exceeds the credit limit after payment +if (updatedCreditTotal > customer.creditLimit) { + String message = String.format( + "Credit limit exceeded. creditTotal:%d, payment:%d", customer.creditTotal, request.getAmount()); + responseObserver.onError( + Status.FAILED_PRECONDITION.withDescription(message).asRuntimeException()); + throw new ScalarDbNonTransientException(message); +} + +// Reduce `credit_total` for the customer +customerRepository.update(customer.withCreditTotal(updatedCreditTotal)); +``` + +### 3. トランザクションは 2 相コミットプロトコルを使用してコミットされます + +Order Service は、支払いが成功したという更新を受け取った後、トランザクションをコミットしようとします。 + +Order Service で呼び出された `ScalarDbTwoPcRepository.executeTwoPcTransaction()` API は、ローカル Order Service とリモート Customer Service の両方の準備、検証、およびコミットを自動的に実行します。これらの手順は、上記の CRUD 操作が正常に終了した後に順番に実行されます。Customer Service の `prepare`、`validate`、および `commit` gRPC エンドポイントを呼び出す実装は、API にパラメーターとして渡す必要があります。参考として、[`OrderService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/order-service/src/main/java/sample/order/OrderService.java) を参照してください。 + +```java +TwoPcResult result = orderRepository.executeTwoPcTransaction(txId ->{ + ... + }, + + Collections.singletonList( + RemotePrepareCommitPhaseOperations.createSerializable( + this::callPrepareEndpoint, + this::callValidateEndpoint, + this::callCommitEndpoint, + this::callRollbackEndpoint + ) + ) +); +``` + +![高レベル 2PC API のシーケンス図](images/seq-diagram-high-level-2pc-api.png) + +Customer Service の `prepare` エンドポイントでは、エンドポイントは `ScalarDbTwoPcRepository.prepareTransactionOnParticipant()` を使用してトランザクションを再開し、準備します。参考として、[`CustomerService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/customer-service/src/main/java/sample/customer/CustomerService.java) を参照してください。 + +```java +customerRepository.prepareTransactionOnParticipant(request.getTransactionId()); +``` + +Customer Service の `validate` エンドポイントでは、エンドポイントは `ScalarDbTwoPcRepository.validateTransactionOnParticipant()` を使用してトランザクションを再開し、検証します。参考として、[`CustomerService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/customer-service/src/main/java/sample/customer/CustomerService.java) を参照してください。 + +```java +customerRepository.validateTransactionOnParticipant(request.getTransactionId()); +``` + +Customer Service の `commit` エンドポイントでは、エンドポイントは `ScalarDbTwoPcRepository.commitTransactionOnParticipant()` を使用してトランザクションを再開し、コミットします。参考として、[`CustomerService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/customer-service/src/main/java/sample/customer/CustomerService.java) を参照してください。 + +```java +customerRepository.commitTransactionOnParticipant(request.getTransactionId()); +``` + +### エラー処理 + +トランザクションの実行中にエラーが発生した場合、`ScalarDbTwoPcRepository.executeTwoPcTransaction()` は、ローカルの Order Service とリモートの Customer Service の両方でトランザクションを自動的にロールバックします。Customer Service の `rollback` gRPC エンドポイントを呼び出す実装も、他の実装とともに API にパラメータとして渡す必要があります。参考として、[`OrderService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/order-service/src/main/java/sample/order/OrderService.java) を参照してください。 + +```java +TwoPcResult result = orderRepository.executeTwoPcTransaction(txId ->{ + ... + }, + + Collections.singletonList( + RemotePrepareCommitPhaseOperations.createSerializable( + this::callPrepareEndpoint, + this::callValidateEndpoint, + this::callCommitEndpoint, + this::callRollbackEndpoint + ) + ) +); +``` + +Customer Service の `rollback` エンドポイントでは、エンドポイントがトランザクションを再開してロールバックします。参考として、[`CustomerService.java`](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-microservice-transaction-sample/customer-service/src/main/java/sample/customer/CustomerService.java) を参照してください。 + +```java +customerRepository.rollbackTransactionOnParticipant(request.getTransactionId()); +``` + +ScalarDB で例外を処理する方法の詳細については、[例外の処理方法](../../two-phase-commit-transactions.mdx#例外の処理方法)を参照してください。 diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-microservice-transaction-sample/images/ERD.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-microservice-transaction-sample/images/ERD.png new file mode 100644 index 00000000..c0468efa Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-microservice-transaction-sample/images/ERD.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-microservice-transaction-sample/images/overview.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-microservice-transaction-sample/images/overview.png new file mode 100644 index 00000000..223c8ad7 Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-microservice-transaction-sample/images/overview.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-microservice-transaction-sample/images/seq-diagram-high-level-2pc-api.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-microservice-transaction-sample/images/seq-diagram-high-level-2pc-api.png new file mode 100644 index 00000000..724e52b5 Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-microservice-transaction-sample/images/seq-diagram-high-level-2pc-api.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-microservice-transaction-sample/images/sequence_diagram.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-microservice-transaction-sample/images/sequence_diagram.png new file mode 100644 index 00000000..0317b5f3 Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-microservice-transaction-sample/images/sequence_diagram.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-multi-storage-transaction-sample/README.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-multi-storage-transaction-sample/README.mdx new file mode 100644 index 00000000..ab59aad2 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-multi-storage-transaction-sample/README.mdx @@ -0,0 +1,334 @@ +--- +tags: + - Enterprise Premium +--- + +# マルチストレージトランザクションを備えた Spring Data JDBC for ScalarDB のサンプルアプリケーション + +import WarningLicenseKeyContact from '/src/components/ja-jp/_warning-license-key-contact.mdx'; +import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; + + + +このチュートリアルでは、マルチストレージトランザクションを備えた Spring Data JDBC for ScalarDB を使用してサンプル Spring Boot アプリケーションを作成する方法について説明します。 + +## このサンプルアプリケーションの前提条件 + +- [Eclipse Temurin](https://adoptium.net/temurin/releases/) の OpenJDK LTS バージョン (8、11、17、または 21) +- [Docker](https://www.docker.com/get-started/) 20.10 以降 ([Docker Compose](https://docs.docker.com/compose/install/) V2 以降) + +:::note + +このサンプルアプリケーションは、Eclipse Temurin の OpenJDK でテストされています。ただし、ScalarDB 自体は、さまざまなベンダーの JDK ディストリビューションでテストされています。互換性のある JDK ディストリビューションを含む ScalarDB の要件の詳細については、[要件](../../requirements.mdx)を参照してください。 + +::: + + + +## サンプルアプリケーション + +### 概要 + +このチュートリアルでは、ScalarDB の [マルチストレージトランザクション](../../multi-storage-transactions.mdx)機能を使用して、アイテムを注文し、信用枠で支払いを行うことができるサンプル電子商取引アプリケーションを作成するプロセスについて説明します。 + +:::note + +このチュートリアルでは、マルチストレージトランザクションで Spring Data JDBC for ScalarDB を使用する方法を説明することに重点を置いているため、サンプルアプリケーションではアプリケーション固有のエラー処理、認証処理などは省略されています。 + +詳細については、[Spring Data JDBC for ScalarDB ガイド](../../scalardb-sql/spring-data-guide.mdx)を参照してください。 + +::: + +![概要](images/overview.png) + +アプリケーションは、ScalarDB Cluster を介してデータベースにアクセスします。 + +### スキーマ + +[スキーマ](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-multi-storage-transaction-sample/schema.sql)は次のとおりです。 + +```sql +CREATE COORDINATOR TABLES IF NOT EXIST; + +CREATE NAMESPACE IF NOT EXISTS customer; + +CREATE TABLE IF NOT EXISTS customer.customers ( + customer_id INT PRIMARY KEY, + name TEXT, + credit_limit INT, + credit_total INT +); + +CREATE NAMESPACE IF NOT EXISTS "order"; + +CREATE TABLE IF NOT EXISTS "order".orders ( + customer_id INT, + timestamp BIGINT, + order_id TEXT, + PRIMARY KEY (customer_id, timestamp) +); + +CREATE INDEX IF NOT EXISTS ON "order".orders (order_id); + +CREATE TABLE IF NOT EXISTS "order".statements ( + order_id TEXT, + item_id INT, + count INT, + PRIMARY KEY (order_id, item_id) +); + +CREATE TABLE IF NOT EXISTS "order".items ( + item_id INT PRIMARY KEY, + name TEXT, + price INT +); +``` + +すべてのテーブルは、`customer` および `order` 名前空間に作成されます。 + +- `customer.customers`: 顧客の情報を管理するテーブル + - `credit_limit`: 貸し手が各顧客にクレジットカードの使用を許可する最大金額 + - `credit_total`: 各顧客がクレジットカードを使用してすでに使用した金額 +- `order.orders`: 注文情報を管理するテーブル +- `order.statements`: 注文明細情報を管理するテーブル +- `order.items`: 注文するアイテムの情報を管理するテーブル + +スキーマのエンティティ関係図は次のとおりです。 + +![ERD](images/ERD.png) + +### トランザクション + +このサンプルアプリケーションでは、次の 5 つのトランザクションが実装されています: + +1. 顧客情報の取得 +2. クレジットカードによる注文 (注文のコストがクレジット限度額を下回っているかどうかを確認し、注文履歴を記録して、チェックに合格した場合は `credit_total` を更新します) +3. 注文 ID による注文情報の取得 +4. 顧客 ID による注文情報の取得 +5. 返済 (`credit_total` の金額を減らします) + +## ScalarDB Cluster の設定 + +[ScalarDB Cluster の設定](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-multi-storage-transaction-sample/scalardb-cluster-node.properties)は次のとおりです: + +```properties +scalar.db.storage=multi-storage +scalar.db.multi_storage.storages=cassandra,mysql +scalar.db.multi_storage.storages.cassandra.storage=cassandra +scalar.db.multi_storage.storages.cassandra.contact_points=cassandra-1 +scalar.db.multi_storage.storages.cassandra.username=cassandra +scalar.db.multi_storage.storages.cassandra.password=cassandra +scalar.db.multi_storage.storages.mysql.storage=jdbc +scalar.db.multi_storage.storages.mysql.contact_points=jdbc:mysql://mysql-1:3306/ +scalar.db.multi_storage.storages.mysql.username=root +scalar.db.multi_storage.storages.mysql.password=mysql +scalar.db.multi_storage.namespace_mapping=customer:mysql,order:cassandra,coordinator:cassandra +scalar.db.multi_storage.default_storage=cassandra + +scalar.db.cluster.node.standalone_mode.enabled=true +scalar.db.sql.enabled=true + +# License key configurations +scalar.db.cluster.node.licensing.license_key= +scalar.db.cluster.node.licensing.license_check_cert_pem= +``` + +- `scalar.db.storage`: ScalarDB でマルチストレージトランザクションを使用するには、`multi-storage` を指定する必要があります。 +- `scalar.db.multi_storage.storages`: ここでストレージ名を定義する必要があります。 +- `scalar.db.multi_storage.storages.cassandra.*`: これらの設定は、`scalar.db.multi_storage.storages` で定義されているストレージ名の 1 つである `cassandra` ストレージ用です。ここで、`cassandra` ストレージのすべての `scalar.db.*` プロパティを設定できます。 +- `scalar.db.multi_storage.storages.mysql.*`: これらの設定は、`scalar.db.multi_storage.storages` で定義されているストレージ名の 1 つである `mysql` ストレージ用です。ここで、`mysql` ストレージのすべての `scalar.db.*` プロパティを設定できます。 +- `scalar.db.multi_storage.namespace_mapping`: この設定は、名前空間をストレージにマップします。このサンプルアプリケーションでは、`customer` 名前空間テーブルの操作は `mysql` ストレージにマップされ、`order` 名前空間テーブルの操作は `cassandra` ストレージにマップされます。また、Consensus Commit トランザクションで使用される `coordinator` 名前空間にマップされるストレージを定義することもできます。 +- `scalar.db.multi_storage.default_storage`: この設定は、マップされていない名前空間テーブルの操作に使用されるデフォルトのストレージを設定します。 + +詳細については、[マルチストレージトランザクション](../../multi-storage-transactions.mdx)を参照してください。 + +このサンプル アプリケーションでは、ScalarDB Cluster はスタンドアロンモード (`scalar.db.cluster.node.standalone_mode.enabled=true`) で実行されています。 + +また、設定ファイルで ScalarDB Cluster のライセンスキー (試用ライセンスまたは商用ライセンス) を設定する必要があります。 詳細については、[製品ライセンスキーの設定方法](../../scalar-licensing/README.mdx)を参照してください。 + +## クライアント設定 + +[クライアント設定](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-multi-storage-transaction-sample/scalardb-sql.properties)は次のとおりです。 + +```properties +scalar.db.sql.connection_mode=cluster +scalar.db.sql.cluster_mode.contact_points=indirect:localhost +``` + +## セットアップ + +### ScalarDB サンプルリポジトリのクローンを作成する + +ターミナルを開き、次のコマンドを実行して ScalarDB サンプルリポジトリのクローンを作成します。 + +```console +git clone https://github.com/scalar-labs/scalardb-samples +``` + +次に、次のコマンドを実行して、このサンプルがあるディレクトリに移動します。 + +```console +cd scalardb-samples/spring-data-multi-storage-transaction-sample +``` + +### ライセンスキーを設定する + +設定ファイル [`scalardb-cluster-node.properties`](https://github.com/scalar-labs/scalardb-samples/blob/main/spring-data-multi-storage-transaction-sample/scalardb-cluster-node.properties) で ScalarDB Cluster のライセンスキー (試用ライセンスまたは商用ライセンス) を設定します。詳細については、[製品ライセンスキーの設定方法](../../scalar-licensing/README.mdx)を参照してください。 + +### Cassandra、MySQL、および ScalarDB Cluster を起動する + +Cassandra、MySQL、および ScalarDB Cluster を起動するには、次の `docker-compose` コマンドを実行する必要があります。 + +```console +docker-compose up -d +``` + +コンテナの起動には 1 分以上かかる場合があることに注意してください。 + +### スキーマをロード + +次に、次のコマンドでスキーマを適用する必要があります。SQL CLI ツール `scalardb-cluster-sql-cli--all.jar` をダウンロードするには、ScalarDB の [リリース](https://github.com/scalar-labs/scalardb/releases)を参照して、使用するバージョンをダウンロードしてください。 + +```console +java -jar scalardb-cluster-sql-cli--all.jar --config scalardb-sql.properties --file schema.sql +``` + +### 初期データをロードする + +コンテナが起動したら、次のコマンドを実行して初期データをロードする必要があります。 + +```console +./gradlew run --args="LoadInitialData" +``` + +初期データがロードされた後、次のレコードがテーブルに保存されます: + +- `customer.customers` テーブルの場合: + +| customer_id | name | credit_limit | credit_total | +|-------------|---------------|--------------|--------------| +| 1 | Yamada Taro | 10000 | 0 | +| 2 | Yamada Hanako | 10000 | 0 | +| 3 | Suzuki Ichiro | 10000 | 0 | + +- `order.items` テーブルの場合: + +| item_id | name | price | +|---------|--------|-------| +| 1 | Apple | 1000 | +| 2 | Orange | 2000 | +| 3 | Grape | 2500 | +| 4 | Mango | 5000 | +| 5 | Melon | 3000 | + +## サンプルアプリケーションを実行する + +まず、ID が `1` である顧客に関する情報を取得します。 + +```console +./gradlew run --args="GetCustomerInfo 1" +... +{"customer_id":1,"name":"Yamada Taro","credit_limit":10000,"credit_total":0} +... +``` + +次に、顧客 ID `1` を使用して、リンゴ 3 個とオレンジ 2 個を注文します。注文形式は `:,:,...` であることに注意してください。 + +```console +./gradlew run --args="PlaceOrder 1 1:3,2:2" +... +{"order_id":"5d49eb62-fcb9-4dd2-9ae5-e714d989937f","customer_id":1,"timestamp":1677564659810} +... +``` + +このコマンドを実行すると、注文 ID が表示されます。 + +注文 ID を使用して注文の詳細を確認してみましょう。 + +```console +./gradlew run --args="GetOrder 5d49eb62-fcb9-4dd2-9ae5-e714d989937f" +... +{"order_id":"5d49eb62-fcb9-4dd2-9ae5-e714d989937f","timestamp":1677564659810,"customer_id":1,"customer_name":"Yamada Taro","statements":[{"item_id":1,"item_name":"Apple","price":1000,"count":3,"total":3000},{"item_id":2,"item_name":"Orange","price":2000,"count":2,"total":4000}],"total":7000} +... +``` + +次に、別の注文を出して、顧客 ID `1` の注文履歴を取得しましょう。 + +```console +./gradlew run --args="PlaceOrder 1 5:1" +... +{"order_id":"ccd97d75-ee57-4393-a0bb-5230c4a8c68a","customer_id":1,"timestamp":1677564776069} +... +./gradlew run --args="GetOrders 1" +... +[{"order_id":"ccd97d75-ee57-4393-a0bb-5230c4a8c68a","timestamp":1677564776069,"customer_id":1,"customer_name":"Yamada Taro","statements":[{"item_id":5,"item_name":"Melon","price":3000,"count":1,"total":3000}],"total":3000},{"order_id":"5d49eb62-fcb9-4dd2-9ae5-e714d989937f","timestamp":1677564659810,"customer_id":1,"customer_name":"Yamada Taro","statements":[{"item_id":1,"item_name":"Apple","price":1000,"count":3,"total":3000},{"item_id":2,"item_name":"Orange","price":2000,"count":2,"total":4000}],"total":7000}] +... +``` + +この注文履歴は、タイムスタンプの降順で表示されます。 + +顧客の現在の `credit_total` は `10000` です。顧客は、情報を取得したときに表示された `credit_limit` に達したため、これ以上注文することはできません。 + +```console +./gradlew run --args="GetCustomerInfo 1" +... +{"customer_id":1,"name":"Yamada Taro","credit_limit":10000,"credit_total":10000} +... +./gradlew run --args="PlaceOrder 1 3:1,4:1" +... +java.lang.RuntimeException: Credit limit exceeded. limit:10000, total:17500 + at sample.SampleService.placeOrder(SampleService.java:102) + at sample.SampleService$$FastClassBySpringCGLIB$$1123c447.invoke() + at org.springframework.cglib.proxy.MethodProxy.invoke(MethodProxy.java:218) + at org.springframework.aop.framework.CglibAopProxy$CglibMethodInvocation.invokeJoinpoint(CglibAopProxy.java:793) + at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(ReflectiveMethodInvocation.java:163) + at org.springframework.aop.framework.CglibAopProxy$CglibMethodInvocation.proceed(CglibAopProxy.java:763) + at org.springframework.transaction.interceptor.TransactionInterceptor$1.proceedWithInvocation(TransactionInterceptor.java:123) + at org.springframework.transaction.interceptor.TransactionAspectSupport.invokeWithinTransaction(TransactionAspectSupport.java:388) + at org.springframework.transaction.interceptor.TransactionInterceptor.invoke(TransactionInterceptor.java:119) + at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(ReflectiveMethodInvocation.java:186) + at org.springframework.aop.framework.CglibAopProxy$CglibMethodInvocation.proceed(CglibAopProxy.java:763) + at org.springframework.aop.framework.CglibAopProxy$DynamicAdvisedInterceptor.intercept(CglibAopProxy.java:708) + at sample.SampleService$$EnhancerBySpringCGLIB$$1cb0cc8c.placeOrder() + at sample.command.PlaceOrderCommand.call(PlaceOrderCommand.java:37) + at sample.command.PlaceOrderCommand.call(PlaceOrderCommand.java:13) + at picocli.CommandLine.executeUserObject(CommandLine.java:2041) + at picocli.CommandLine.access$1500(CommandLine.java:148) + at picocli.CommandLine$RunLast.executeUserObjectOfLastSubcommandWithSameParent(CommandLine.java:2461) + at picocli.CommandLine$RunLast.handle(CommandLine.java:2453) + at picocli.CommandLine$RunLast.handle(CommandLine.java:2415) + at picocli.CommandLine$AbstractParseResultHandler.execute(CommandLine.java:2273) + at picocli.CommandLine$RunLast.execute(CommandLine.java:2417) + at picocli.CommandLine.execute(CommandLine.java:2170) + at sample.SampleApp.run(SampleApp.java:26) + at org.springframework.boot.SpringApplication.callRunner(SpringApplication.java:768) + at org.springframework.boot.SpringApplication.callRunners(SpringApplication.java:752) + at org.springframework.boot.SpringApplication.run(SpringApplication.java:314) + at org.springframework.boot.SpringApplication.run(SpringApplication.java:1303) + at org.springframework.boot.SpringApplication.run(SpringApplication.java:1292) + at sample.SampleApp.main(SampleApp.java:35) +... +``` + +支払いが完了すると、顧客は再度注文できるようになります。 + +```console +./gradlew run --args="Repayment 1 8000" +... +./gradlew run --args="GetCustomerInfo 1" +... +{"customer_id":1,"name":"Yamada Taro","credit_limit":10000,"credit_total":2000} +... +./gradlew run --args="PlaceOrder 1 3:1,4:1" +... +{"order_id":"3ac4a1bf-a724-4f26-b948-9f03281a971e","customer_id":1,"timestamp":1677565028204} +... +``` + +## クリーンアップ + +Cassandra、MySQL、および ScalarDB Cluster を停止するには、次のコマンドを実行します。 + +```console +docker-compose down +``` diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-multi-storage-transaction-sample/images/ERD.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-multi-storage-transaction-sample/images/ERD.png new file mode 100644 index 00000000..02100437 Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-multi-storage-transaction-sample/images/ERD.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-multi-storage-transaction-sample/images/overview.png b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-multi-storage-transaction-sample/images/overview.png new file mode 100644 index 00000000..360b26c6 Binary files /dev/null and b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-samples/spring-data-multi-storage-transaction-sample/images/overview.png differ diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-sql/grammar.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-sql/grammar.mdx new file mode 100644 index 00000000..2e09fad1 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-sql/grammar.mdx @@ -0,0 +1,2346 @@ +--- +tags: + - Enterprise Premium +--- + +# ScalarDB SQL 文法 + +- DDL + - [CREATE NAMESPACE](#create-namespace) + - [CREATE TABLE](#create-table) + - [CREATE INDEX](#create-index) + - [TRUNCATE TABLE](#truncate-table) + - [DROP INDEX](#drop-index) + - [DROP TABLE](#drop-table) + - [DROP NAMESPACE](#drop-namespace) + - [CREATE COORDINATOR TABLES](#create-coordinator-tables) + - [TRUNCATE COORDINATOR TABLES](#truncate-coordinator-tables) + - [DROP COORDINATOR TABLES](#drop-coordinator-tables) + - [ALTER TABLE](#alter-table) +- DML + - [SELECT](#select) + - [INSERT](#insert) + - [UPSERT](#upsert) + - [UPDATE](#update) + - [DELETE](#delete) +- DCL + - [CREATE USER](#create-user) + - [ALTER USER](#alter-user) + - [DROP USER](#drop-user) + - [GRANT](#grant) + - [REVOKE](#revoke) +- Others + - [USE](#use) + - [BEGIN](#begin) + - [START TRANSACTION](#start-transaction) + - [JOIN](#join) + - [PREPARE](#prepare) + - [VALIDATE](#validate) + - [COMMIT](#commit) + - [ROLLBACK](#rollback) + - [ABORT](#abort) + - [SET MODE](#set-mode) + - [SHOW NAMESPACES](#show-namespaces) + - [SHOW TABLES](#show-tables) + - [DESCRIBE](#describe) + - [SUSPEND](#suspend) + - [RESUME](#resume) + - [SHOW USERS](#show-users) + - [SHOW GRANTS](#show-grants) + +## DDL + +### CREATE NAMESPACE + +テーブルは 1 つの名前空間に属しているため、テーブルを作成する前に名前空間を作成する必要があります。`CREATE NAMESPACE` コマンドは名前空間を作成します。 + +#### 文法 + +```sql +CREATE NAMESPACE [IF NOT EXISTS] [WITH creation_options] + +creation_options: