ScalarDB Admin API & Schema Loader

Published in

Scalar Engineering (JA)

9 min readJan 30, 2023

ScalarDB は、リレーショナルデータベースや NoSQL データベースなどの複数のデータベース上にある、データベースに依存しないユニバーサルトランザクションマネージャーです。 ScalarDBは、トランザクションログ（WAL before/afterイメージなど）をアプリケーション管理レコードで管理することで、基盤となるデータベースの機能に依存することなくトランザクションを実現できます。

このアプローチはデータベースに依存せずに適切に実現するのに優れていますが、アプリケーション開発者は ScalarDB 固有のスキーマを作成する必要があります。つまり、ScalarDBのトランザクションログのためテーブルに列を追加する必要があり、間違いやすく面倒な手順となっています。この問題を軽減するために、Admin APIとAdmin APIのラッパーであるSchema Loaderを提供しています。

本記事では、それらの概要と詳細について説明します。

Admin APIの概要

Admin APIは、データベーススキーマの作成、削除、変更など、データベーススキーマの管理に関連するいくつかのメソッドを提供します。

この概要では、ネームスペースとテーブルの作成と削除の方法を簡単に説明します。詳細については、Admin API の説明書を参照してください。

Transaction Managerと同じ設定ファイルを使用してAdminオブジェクトのインスタンスを取得できます。

TransactionFactory transactionFactory =
   TransactionFactory.create("<Path to ScalarDB config properties>");
DistributedTransactionAdmin admin = transactionFactory.getTransactionAdmin();

テーブルを作成する前に、「sample」というネームスペースを作ります。

admin.createNamespace("sample")

次に、「customer_id」、「name」、「credit_limit」、「credit_total」の4つのカラムを持つ「customers」テーブルを作成します。「customer_id 」の列はパーティション・キーです。

TableMetadata customersTableMetadata =
   TableMetadata.newBuilder()
       .addPartitionKey("customer_id")
       .addColumn("customer_id", DataType.INT)
       .addColumn("name", DataType.TEXT)
       .addColumn("credi_limit", DataType.INT)
       .addColumn("credit_total", DataType.INT)
       .build();
admin.createTable("sample", "customers", customersTableMetadata);

また、トランザクションAPIがトランザクションの状態を管理するCoordinatorテーブルを作成する必要があります。

admin.createCoordinatorTables();

これからトランザクションAPIを使って「customers」テーブルの使用は可能です。

ScalarDB 環境を削除するには、ネームスペースとテーブルを次のコマンドで削除できます。

admin.dropTable("sample", "customers");
admin.dropNamespace("sample");

最後に、Coordinatorテーブルも削除する必要があります。

admin.dropCoordinatorTables();

Schema Loaderの概要

Schema Loader はJavaで開発されているCLIであり，内部的にはAdmin APIを使用しています。データベースのスキーマの作成、削除、および変更に関連するコマンドを提供します。

Admin APIとSchema Loaderの典型的な使い分けとしては、前者がテストやデバッグに適しているのに対し、後者は運用中のアプリケーションのスキーマを作成したり削除したりするのに、より実用的であると言えます。Admin APIは、より多くの制御と豊富な機能を提供し、Schema Loaderは、スキーマの一括作成と削除のほとんどのユースケースにおいて使用することができます。

ここでは、ネームスペースとテーブルの作成と削除の方法を簡単に紹介します。もっと詳しく知りたい場合は、Schema Loaderのドキュメントを参照してください。

まず、前節と同じテーブルのスキーマを記述した JSON ファイルを作成する必要があります。このサンプルでは、スキーマ・ファイルは一つのテーブルを含んでいますが、任意の数のテーブルも定義することができます。

{
 "sample.customers": {
   "transaction": true,
   "partition-key": [
     "customer_id"
   ],
   "columns": {
     "customer_id": "INT",
     "name": "TEXT",
     "credit_limit": "INT",
     "credit_total": "INT"
   }
 }
}

次に、スキーマを作成します。スキーマ・ファイルに存在するネームスペースとテーブル、そしてCoordinatorテーブルがまだ存在しない場合は作成されます。

java -jar scalardb-schema-loader-3.8.0.jar -f <Path to JSON schema file> -c <Path to ScalarDB config properties> --coordinator

この手順以降トランザクションAPIを使って「customers」テーブルの使用が可能となります。

ScalarDB のスキーマを削除するには、先ほどのコマンドに「-D」オプションを追加する必要があります。「customers」テーブルとそのネームスペース、Coordinatorテーブルが削除されます。

java -jar scalardb-schema-loader-3.8.0.jar -f <Path to JSON schema file> -c <Path to ScalarDB config properties> --coordinator -D

Admin APIの役割

Admin APIでテーブルを作成すると、Admin APIはバックエンドのストレージにテーブルを作成し、さらに次の2つの処理を実行します。

トランザクションのメタデータ（トランザクションIDやステータスなど）の列を追加します
作成したテーブルのメタデータを別テーブルに登録します

トランザクションのメタデータ

トランザクションメタデータは、トランザクションを管理するためのScalarDB固有の内部メタデータであり、データベースシステムにおけるWAL（write-ahead log）に相当します。

例えば、MySQLをバックエンドのストレージとして使用した場合、Admin APIは以下のトランザクションメタデータ列（緑色のフォント）を「sample.customers」テーブルに追加します（前節で定義したスキーマを参考してください）。

トランザクションメタデータ列 (緑色のフォント)を追加した「customers 」テーブルのスキーマ

Coordinator テーブル

ScalarDBでは、実行中や過去のトランザクションのステータスを記録するために、Coordinatorテーブルという専用のテーブルを使用します。このテーブルスキーマの管理もAdmin APIが担当する要素です。

テーブルメタデータ

「テーブルメタデータ」は、ユーザーのテーブルのスキーマを管理するための ScalarDB 固有の内部メタデータです。ScalarDB は、保存されたテーブルメタデータを頼りに、与えられたネームスペースやテーブルが存在するかどうかを追跡します。また、これらはクエリの内容を検証するためにも使用されます。対象となるテーブルのメタデータが存在するかどうかを調べ、各列名、タイプ、クエリが「scalardb.metadata」データベース内の内容と一致するかどうかを検証します。

テーブルのメタデータは、クエリやトランザクション処理で頻繁に読み込まれるため。テーブルメタデータをキャッシュすることで、クエリの効率を向上させます。

各ユーザーテーブルの列は、「scalardb.metadata」データベースにエントリーを持つことになります。「sample.customers」テーブルの全エントリーは以下となります。

ScalarDBメタデータテーブルの「customers 」テーブルのエントリー

まとめ

本記事では、ScalarDBのユーザースキーマを管理するために用いられるAdmin APIとSchema Loaderを紹介しました。そして、両者を用いてデータベーススキーマを作成・削除する方法を簡単に紹介しました。また、Admin APIが作成した各テーブルにメタデータ列を追加することや、WAL（write-ahead logging）プロトコルの一部としてCoordinatorテーブルを使用してトランザクションを管理することについても詳しく説明しました。最後に、Admin API はクエリの検証のために、ユーザーのスキーマのテーブルメタデータを保存することを紹介しました。