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

ScalarDB をはじめよう

注記

このページは英語版のページが機械翻訳されたものです。英語版との間に矛盾または不一致がある場合は、英語版を正としてください。

この入門チュートリアルでは、ScalarDB でデータベースを設定する方法について説明し、ScalarDB を使用してクレジットカードでアイテムを注文して支払うことができるサンプルの電子商取引アプリケーションを作成するプロセスを示します。サンプルの電子商取引アプリケーションでは、ユーザーがクレジットラインを使用してアイテムを注文して支払う方法を示します。

警告

サンプルアプリケーションは ScalarDB の使用方法を示すことに重点を置いているため、アプリケーション固有のエラー処理、認証処理、および同様の機能はサンプルアプリケーションに含まれていません。ScalarDB での例外処理の詳細については、例外の処理方法を参照してください。

このサンプルアプリケーションの前提条件​

ScalarDB は Java で記述されているため、環境に次のいずれかの Java Development Kit (JDK) がインストールされている必要があります。

注記

このサンプルアプリケーションは、Eclipse Temurin の OpenJDK でテストされています。ただし、ScalarDB 自体は、さまざまなベンダーの JDK ディストリビューションでテストされています。互換性のある JDK ディストリビューションを含む ScalarDB の要件の詳細については、要件を参照してください。

ScalarDB サンプルリポジトリのクローンを作成する​

Terminal を開き、次のコマンドを実行して ScalarDB サンプルリポジトリのクローンを作成します。

git clone https://github.com/scalar-labs/scalardb-samples

次に、次のコマンドを実行して、サンプルアプリケーションが含まれているディレクトリに移動します。

cd scalardb-samples/scalardb-sample

データベースをセットアップする​

データベースを選択し、指示に従って ScalarDB 用に設定します。

ScalarDB がサポートするデータベースの一覧については、データベースを参照してください。

MySQLをローカルで実行する

scalardb-samples/scalardb-sample ディレクトリの docker-compose.yml ファイルを使用して、Docker Compose で MySQL を実行できます。

MySQL を起動するには、次のコマンドを実行します。

docker compose up -d mysql

ScalarDB を設定する

scalardb-samples/scalardb-sample ディレクトリの database.properties ファイルには、ScalarDB のデータベース設定が含まれています。database.properties ファイル内の MySQL のプロパティのコメントを解除して、設定が次のようになるようにしてください。

# For MySQL
scalar.db.storage=jdbc
scalar.db.contact_points=jdbc:mysql://localhost:3306/
scalar.db.username=root
scalar.db.password=mysql

データベーススキーマをロードする​

アプリケーションでデータベーススキーマ (データを整理する方法) を定義する必要があります。サポートされているデータ型の詳細については、ScalarDB と他のデータベース間のデータ型マッピングを参照してください。

このチュートリアルでは、schema.json というファイルが scalardb-samples/scalardb-sample ディレクトリに既に存在します。スキーマを適用するには、scalardb Releases ページに移動し、使用している ScalarDB のバージョンに一致する ScalarDB Schema Loader を scalardb-samples/scalardb-sample ディレクトリにダウンロードします。

次に、データベースに基づいて、<VERSION> をダウンロードした ScalarDB Schema Loader のバージョンに置き換えて、次のコマンドを実行します。

java -jar scalardb-schema-loader-<VERSION>.jar --config database.properties --schema-file schema.json --coordinator
注記

transaction が true に設定されたテーブルがスキーマ内に存在するため、--coordinator オプションが指定されています。スキーマの設定とロードの詳細については、ScalarDB Schema Loader を参照してください。

スキーマの詳細​

サンプルアプリケーションの schema.json に示されているように、すべてのテーブルは sample 名前空間に作成されます。

  • sample.customers: 顧客情報を管理するテーブル
    • credit_limit: 貸し手が顧客に信用枠から支出を許可する最大金額
    • credit_total: 顧客が信用枠から支出した金額
  • sample.orders: 注文情報を管理するテーブル
  • sample.statements: 注文明細情報を管理するテーブル
  • sample.items: 注文するアイテムの情報を管理するテーブル

スキーマのエンティティ関係図は次のとおりです。

ERD

初期データをロードする​

サンプルアプリケーションを実行する前に、次のコマンドを実行して初期データをロードする必要があります。

./gradlew run --args="LoadInitialData"

初期データがロードされた後、次のレコードがテーブルに保存される必要があります。

sample.customers テーブル

customer_idnamecredit_limitcredit_total
1Yamada Taro100000
2Yamada Hanako100000
3Suzuki Ichiro100000

sample.items テーブル

item_idnameprice
1Apple1000
2Orange2000
3Grape2500
4Mango5000
5Melon3000

サンプルアプリケーションでトランザクションを実行し、データを取得する​

次のセクションでは、サンプル電子商取引アプリケーションでトランザクションを実行し、データを取得する方法について説明します。

顧客情報を取得する​

まず、次のコマンドを実行して、ID が 1 である顧客に関する情報を取得します。

./gradlew run --args="GetCustomerInfo 1"

次の出力が表示されます。

...
{"id": 1, "name": "Yamada Taro", "credit_limit": 10000, "credit_total": 0}
...

注文する​

次に、次のコマンドを実行して、顧客 ID 1 にリンゴ 3 個とオレンジ 2 個を注文してもらいます。

注記

このコマンドの注文形式は ./gradlew run --args="PlaceOrder <CUSTOMER_ID> <ITEM_ID>:<COUNT>,<ITEM_ID>:<COUNT>,..." です。

./gradlew run --args="PlaceOrder 1 1:3,2:2"

以下のように、order_id の UUID が異なる、注文が成功したことを示す類似の出力が表示されます。

...
{"order_id": "dea4964a-ff50-4ecf-9201-027981a1566e"}
...

注文の詳細を確認する​

次のコマンドを実行して注文の詳細を確認します。<ORDER_ID_UUID> は、前のコマンドを実行した後に表示される order_id の UUID に置き換えます。

./gradlew run --args="GetOrder <ORDER_ID_UUID>"

order_id と timestamp の UUID が異なる、以下のような出力が表示されます。

...
{"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 個を注文します。

./gradlew run --args="PlaceOrder 1 5:1"

以下のように、order_id の UUID が異なる、注文が成功したことを示す類似の出力が表示されます。

...
{"order_id": "bcc34150-91fa-4bea-83db-d2dbe6f0f30d"}
...

注文履歴を確認する​

次のコマンドを実行して、顧客 ID 1 のすべての注文履歴を取得します。

./gradlew run --args="GetOrders 1"

order_id と timestamp の UUID が異なる以下のような出力が表示されます。これは、顧客 ID 1 のすべての注文履歴をタイムスタンプの降順で表示します。

...
{"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 のクレジット合計を取得します。

./gradlew run --args="GetCustomerInfo 1"

次の出力が表示されます。これは、顧客 ID 1 が credit_total の credit_limit に達しており、これ以上注文できないことを示しています。

...
{"id": 1, "name": "Yamada Taro", "credit_limit": 10000, "credit_total": 10000}
...

次のコマンドを実行して、ブドウ 1 個とマンゴー 1 個を注文してみます。

./gradlew run --args="PlaceOrder 1 3:1,4:1"

次の出力が表示されます。これは、credit_total 金額が credit_limit 金額を超えたために注文が失敗したことを示しています。

...
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 の金額を減らす必要があります。

次のコマンドを実行して支払いを行います。

./gradlew run --args="Repayment 1 8000"

次に、次のコマンドを実行して、顧客 ID 1 の credit_total 金額を確認します。

./gradlew run --args="GetCustomerInfo 1"

次の出力が表示されます。これは、顧客 ID 1 に支払いが適用され、credit_total の金額が減ったことを示しています。

...
{"id": 1, "name": "Yamada Taro", "credit_limit": 10000, "credit_total": 2000}
...

顧客 ID 1 が支払いを済ませたので、次のコマンドを実行してブドウ 1 個とメロン 1 個を注文します。

./gradlew run --args="PlaceOrder 1 3:1,4:1"

以下のように、order_id の UUID が異なる、注文が成功したことを示す類似の出力が表示されます。

...
{"order_id": "8911cab3-1c2b-4322-9386-adb1c024e078"}
...

データベースを停止する​

データベースを停止するには、次のコマンドを実行して Docker コンテナを停止します。

docker compose down

参照​

このチュートリアルで使用される電子商取引アプリケーションのソースコードを確認するには、Sample.java を参照してください。