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

ScalarDB Schema Loader

注記

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

ScalarDB には、実装固有のデータモデルとスキーマにマップされる独自のデータモデルとスキーマがあります。 さらに、ScalarDB は、Consensus Commit トランザクションマネージャーを使用するときにトランザクションログとステータスを管理するために、トランザクション ID、レコードバージョン、トランザクションステータスなどの内部メタデータを保存します。

トランザクションのスキーママッピングとメタデータの管理は難しい場合があるため、スキーママッピングやメタデータに関する詳細な知識を必要としないスキーマ作成ツールである ScalarDB Schema Loader を使用できます。

Schema Loader で一般的な CLI オプションを指定するには、次の 2 つのオプションがあります。

  • ScalarDB プロパティファイルとデータベース固有またはストレージ固有のオプションを渡します。
  • ScalarDB プロパティファイルなしでデータベース固有またはストレージ固有のオプションを渡します。(非推奨)
注記

このツールは、テーブルの作成、削除、修復、または変更を行うための基本的なオプションのみをサポートしています。データベースの高度な機能を使用する場合は、このツールでテーブルを作成した後、データベース固有のツールを使用してテーブルを変更する必要があります。

Schema Loader を設定する​

希望する方法を選択して Schema Loader を設定し、指示に従います。

Schema Loader のリリースバージョンは、ScalarDB Releases ページからダウンロードできます。

Schema Loader を実行する​

このセクションでは、Schema Loader を実行する方法について説明します。

利用可能なコマンド​

データベースの Schema Loader を設定する方法を選択します。他のデータベース固有の方法は非推奨であるため、プロパティファイルを使用することをお勧めします。

プロパティファイルを使用する場合、次のコマンドを使用できます。

Usage: java -jar scalardb-schema-loader-<VERSION>.jar [-D] [--coordinator]
       [--no-backup] [--no-scaling] -c=<configPath>
       [--compaction-strategy=<compactionStrategy>] [-f=<schemaFile>]
       [--replication-factor=<replicaFactor>]
       [--replication-strategy=<replicationStrategy>] [--ru=<ru>]
Create/Delete schemas in the storage defined in the config file
  -A, --alter         Alter tables : it will add new columns and create/delete
                        secondary index for existing tables. It compares the
                        provided table schema to the existing schema to decide
                        which columns need to be added and which indexes need
                        to be created or deleted
  -c, --config=<configPath>
                      Path to the config file of ScalarDB
      --compaction-strategy=<compactionStrategy>
                      The compaction strategy, must be LCS, STCS or TWCS
                        (supported in Cassandra)
      --coordinator   Create/delete/repair Coordinator tables
  -D, --delete-all    Delete tables
  -f, --schema-file=<schemaFile>
  -I, --import        Import tables : it will import existing non-ScalarDB
                        tables to ScalarDB.
                      Path to the schema json file
      --no-backup     Disable continuous backup (supported in DynamoDB)
      --no-scaling    Disable auto-scaling (supported in DynamoDB, Cosmos DB)
      --repair-all    Repair namespaces and tables that are in an unknown
                        state: it re-creates namespaces, tables, secondary
                        indexes, and their metadata if necessary.
      --replication-factor=<replicaFactor>
                      The replication factor (supported in Cassandra)
      --replication-strategy=<replicationStrategy>
                      The replication strategy, must be SimpleStrategy or
                        NetworkTopologyStrategy (supported in Cassandra)
      --ru=<ru>       Base resource unit (supported in DynamoDB, Cosmos DB)
      --upgrade       Upgrades the ScalarDB environment to support the latest
                        version of the ScalarDB API. Typically, as indicated in
                        the release notes, you will need to run this command
                        after updating the ScalarDB version that your
                        application environment uses.

サンプルのプロパティファイルについては、database.properties を参照してください。

注記

次のデータベース固有のメソッドは非推奨になりました。代わりに、プロパティファイルを設定するためのコマンドを使用してください。

Usage: java -jar scalardb-schema-loader-<VERSION>.jar --jdbc [-D]
      -f=<schemaFile> -j=<url> -p=<password> -u=<user>
Create/Delete JDBC schemas
  -A, --alter         Alter tables : it will add new columns and create/delete
                        secondary index for existing tables. It compares the
                        provided table schema to the existing schema to decide
                        which columns need to be added and which indexes need
                        to be created or deleted
  -D, --delete-all       Delete tables
  -f, --schema-file=<schemaFile>
                        Path to the schema json file
  -j, --jdbc-url=<url>   JDBC URL
  -p, --password=<password>
                        JDBC password
      --repair-all       Repair tables : it repairs the table metadata of
                          existing tables
  -u, --user=<user>      JDBC user

名前空間とテーブルを作成する​

プロパティファイルを使用して名前空間とテーブルを作成するには、山括弧内の内容を説明に従って置き換えて、次のコマンドを実行します。

java -jar scalardb-schema-loader-<VERSION>.jar --config <PATH_TO_SCALARDB_PROPERTIES_FILE> -f <PATH_TO_SCHEMA_FILE> [--coordinator]

--coordinator が指定されている場合は、Coordinator テーブルが作成されます。

注記

次のデータベース固有の CLI 引数は非推奨になりました。代わりに、プロパティファイルを設定するための CLI 引数を使用してください。

java -jar scalardb-schema-loader-<VERSION>.jar --jdbc -j <JDBC_URL> -u <USER> -p <PASSWORD> -f <PATH_TO_SCHEMA_FILE>

テーブルの変更​

コマンドを使用して、既存のテーブルに新しい列を追加したり、セカンダリインデックスを作成または削除したりできます。このコマンドは、指定されたテーブルスキーマを既存のスキーマと比較し、追加する必要がある列と作成または削除する必要があるインデックスを決定します。

既存のテーブルに新しい列を追加したり、セカンダリインデックスを作成または削除したりするには、次のコマンドを実行し、山括弧内の内容を説明に従って置き換えます。

java -jar scalardb-schema-loader-<VERSION>.jar --config <PATH_TO_SCALARDB_PROPERTIES_FILE> -f <PATH_TO_SCHEMA_FILE> --alter
注記

次のデータベース固有の CLI 引数は非推奨になりました。代わりに、プロパティファイルを設定するための CLI 引数を使用してください。

java -jar scalardb-schema-loader-<VERSION>.jar --jdbc -j <JDBC_URL> -u <USER> -p <PASSWORD> -f <PATH_TO_SCHEMA_FILE> --alter

テーブルの削除​

プロパティファイルを使用してテーブルを削除できます。テーブルを削除するには、次のコマンドを実行し、山括弧内の内容を説明に従って置き換えます。

java -jar scalardb-schema-loader-<VERSION>.jar --config <PATH_TO_SCALARDB_PROPERTIES_FILE> -f <PATH_TO_SCHEMA_FILE> [--coordinator] -D

--coordinator が指定されている場合は、Coordinator テーブルも削除されます。

注記

次のデータベース固有の CLI 引数は非推奨になりました。代わりに、プロパティファイルを設定するための CLI 引数を使用してください。

java -jar scalardb-schema-loader-<VERSION>.jar --jdbc -j <JDBC_URL> -u <USER> -p <PASSWORD> -f <PATH_TO_SCHEMA_FILE> -D

名前空間とテーブルを修復する​

プロパティファイルを使用して、名前空間とテーブルを修復できます。名前空間とテーブルを修復する理由は、名前空間またはテーブルが基盤となるストレージに存在するが、その ScalarDB メタデータが存在しない、またはその逆など、それらが不明な状態になる可能性があるためです。名前空間、テーブル、セカンダリインデックス、およびそれらのメタデータを修復するには、必要に応じてそれらを再作成する必要があります。それらを修復するには、次のコマンドを実行し、説明されているように山括弧内の内容を置き換えます。

java -jar scalardb-schema-loader-<VERSION>.jar --config <PATH_TO_SCALARDB_PROPERTIES_FILE> -f <PATH_TO_SCHEMA_FILE> [--coordinator] --repair-all
警告

このコマンドを実行する前に、スキーマ設定が最後に適用されたものと同じであることを確認する必要があります。

--coordinator が指定されている場合は、Coordinator テーブルも修復されます。また、Cosmos DB for NoSQL を使用している場合は、このコマンドを実行すると、各テーブルにアタッチされているストアドプロシージャも修復されます。

注記

次のデータベース固有の CLI 引数は非推奨になりました。代わりに、プロパティファイルを設定するための CLI 引数を使用してください。

java -jar scalardb-schema-loader-<VERSION>.jar --jdbc -j <JDBC_URL> -u <USER> -p <PASSWORD> -f <PATH_TO_SCHEMA_FILE> --repair-all

テーブルのインポート​

--import オプションとインポート固有のスキーマファイルを使用して、JDBC データベース内の既存のテーブルを ScalarDB にインポートできます。詳細については、ScalarDB Schema Loader を使用して既存のテーブルを ScalarDB にインポートするを参照してください。

環境をアップグレードして最新の ScalarDB API をサポートする​

ScalarDB 環境をアップグレードして、最新バージョンの ScalarDB API をサポートすることができます。通常、リリースノートに記載されているように、アプリケーション環境で使用する ScalarDB バージョンを更新した後、このコマンドを実行する必要があります。次のコマンドを実行するときは、説明されているように山括弧内の内容を必ず置き換えてください。

java -jar scalardb-schema-loader-<VERSION>.jar --config <PATH_TO_SCALARDB_PROPERTIES_FILE> --upgrade

サンプルスキーマファイル​

以下はサンプルスキーマです。サンプルスキーマファイルについては、schema_sample.json を参照してください。

{
  "sample_db.sample_table": {
    "transaction": false,
    "partition-key": [
      "c1"
    ],
    "clustering-key": [
      "c4 ASC",
      "c6 DESC"
    ],
    "columns": {
      "c1": "INT",
      "c2": "TEXT",
      "c3": "BLOB",
      "c4": "INT",
      "c5": "BOOLEAN",
      "c6": "INT"
    },
    "secondary-index": [
      "c2",
      "c4"
    ]
  },

  "sample_db.sample_table1": {
    "transaction": true,
    "partition-key": [
      "c1"
    ],
    "clustering-key": [
      "c4"
    ],
    "columns": {
      "c1": "INT",
      "c2": "TEXT",
      "c3": "INT",
      "c4": "INT",
      "c5": "BOOLEAN"
    }
  },

  "sample_db.sample_table2": {
    "transaction": false,
    "partition-key": [
      "c1"
    ],
    "clustering-key": [
      "c4",
      "c3"
    ],
    "columns": {
      "c1": "INT",
      "c2": "TEXT",
      "c3": "INT",
      "c4": "INT",
      "c5": "BOOLEAN"
    }
  }
}

スキーマには、columns、partition-key、clustering-key、secondary-index、および transaction フィールドを含むテーブル定義があります。

  • columns フィールドは、テーブルの列とそのデータ型を定義します。
  • partition-key フィールドは、パーティションキーがどの列で設定されているかを定義します。
  • clustering-key フィールドは、クラスタリングキーがどの列で設定されているかを定義します。
  • secondary-index フィールドは、インデックスが付けられる列を定義します。
  • transaction フィールドは、テーブルがトランザクション用かどうかを示します。
    • transaction フィールドを true に設定するか、transaction フィールドを指定しない場合、このツールは必要に応じてトランザクションメタデータを含むテーブルを作成します。
    • transaction フィールドを false に設定すると、このツールはトランザクションメタデータのないテーブルを作成します (つまり、Storage API を含むテーブルの場合)。

次のように、テーブル定義でデータベースまたはストレージ固有のオプションを指定することもできます。

{
  "sample_db.sample_table3": {
    "partition-key": [
      "c1"
    ],
    "columns": {
      "c1": "INT",
      "c2": "TEXT",
      "c3": "BLOB"
    },
    "compaction-strategy": "LCS",
    "ru": 5000
  }
}

指定できるデータベースまたはストレージ固有のオプションは次のとおりです。

JDBC データベースには使用できるオプションはありません。

Cosmos DB for NoSQL または DynamoDB を使用する場合のパフォーマンスのスケーリング​

Cosmos DB for NoSQL または DynamoDB を使用する場合、リクエストユニット (RU) または自動スケーリングを使用してスケーリングできます。

RU​

--ru オプションを指定すると、Cosmos DB for NoSQL および DynamoDB のスループットをスケーリングできます。このオプションを指定すると、スケーリングはすべてのテーブルまたは各テーブルの ru パラメータに適用されます。

--ru オプションが設定されていない場合、デフォルト値は Cosmos DB for NoSQL の場合は 400、DynamoDB の場合は 10 になります。

注記
  • Schema Loader は、Cosmos DB for NoSQL の要求ユニットと DynamoDB の容量ユニットを RU で抽象化します。そのため、データベースの実装に応じて適切な値を設定してください。
  • Schema Loader は、DynamoDB の読み取り容量ユニットと書き込み容量ユニットの両方に同じ値を設定することに注意してください。

自動スケーリング​

デフォルトでは、Schema Loader はすべてのテーブルに対して RU の自動スケーリングを有効にします。RU は、ワークロードに応じて、指定された RU の 10% から 100% の間でスケーリングされます。たとえば、-r 10000 を指定すると、各テーブルの RU は 1000 から 10000 の間で自動スケーリングされます。

注記

Cosmos DB for NoSQL の自動スケーリングは、このオプションが 4000 以上に設定されている場合にのみ有効になります。

ScalarDB と他のデータベース間のデータ型マッピング​

次の表は、ScalarDB でサポートされているデータ型と、他のデータベースのデータ型へのマッピングを示しています。

ScalarDBCassandraCosmos DB for NoSQLDynamoDBMySQLPostgreSQL/YugabyteDBOracleSQL ServerSQLite
BOOLEANbooleanboolean (JSON)BOOLbooleanbooleannumber(1)bitboolean
INTintnumber (JSON)Nintintnumber(10)intint
BIGINTbigintnumber (JSON)Nbigintbigintnumber(19)bigintbigint
FLOATfloatnumber (JSON)Nrealrealbinary_floatfloat(24)float
DOUBLEdoublenumber (JSON)Ndoubledouble precisionbinary_doublefloatdouble
TEXTtextstring (JSON)Slongtexttextvarchar2(4000)varchar(8000)text
BLOBblobstring (JSON)BlongblobbyteaRAW(2000)varbinary(8000)blob

ただし、JDBC データベースの次のデータ型は、プライマリーキーまたはセカンダリインデックスキーとして使用される場合、異なる方法で変換されます。これは、RDB データ型の制限によるものです。

ScalarDBMySQLPostgreSQL/YugabyteDBOracle
TEXTVARCHAR(64)VARCHAR(10485760)VARCHAR2(64)
BLOBVARBINARY(64)RAW(64)

ScalarDB の BIGINT の値の範囲は、基になるデータベースに関係なく、-2^53 から 2^53 です。

注記

YugabyteDB には、浮動小数点型 (FLOAT および DOUBLE) がプライマリーキー、クラスタリングキー、またはセカンダリインデックスキーとして正しく機能しないという制限があります。

このデータ型マッピングがアプリケーションと一致しない場合は、このツールを使用してテーブルを作成した後、テーブルを変更してデータ型を変更してください。

Consensus Commit の内部メタデータ​

Consensus Commit トランザクションマネージャーは、トランザクションを適切に処理するために、実際のレコードとともに保存されるメタデータ (トランザクション ID、レコードバージョン、トランザクションステータスなど) を管理します。

したがって、アプリケーションに必要な列とともに、メタデータ用の追加列をスキーマに定義する必要があります。さらに、Consensus Commit トランザクションマネージャーを使用する場合、このツールはメタデータを含むテーブルを作成します。

アプリケーションで Schema Loader を使用する​

Maven Central Repository から Schema Loader のバージョンを確認できます。たとえば、Gradle では、build.gradle ファイルに次の依存関係を追加し、<VERSION> を使用する Schema Loader のバージョンに置き換えます。

dependencies {
    implementation 'com.scalar-labs:scalardb-schema-loader:<VERSION>'
}

使用例​

SchemaLoader クラスを使用すると、CLI と同じコマンドを実行できます。

  • スキーマで定義されているテーブルを作成、変更、削除、または修復するには、必要に応じて ScalarDB プロパティファイル、スキーマ、および追加のオプションを渡すことができます。
  • 環境をアップグレードするには、必要に応じて ScalarDB プロパティと追加のオプションを渡すことができます。
public class SchemaLoaderSample {
  public static int main(String... args) throws SchemaLoaderException {
    Path configFilePath = Paths.get("database.properties");
    // "sample_schema.json" and "altered_sample_schema.json" can be found in the "/sample" directory.
    Path schemaFilePath = Paths.get("sample_schema.json");
    Path alteredSchemaFilePath = Paths.get("altered_sample_schema.json");
    boolean createCoordinatorTables = true; // whether to create the Coordinator table or not
    boolean deleteCoordinatorTables = true; // whether to delete the Coordinator table or not
    boolean repairCoordinatorTables = true; // whether to repair the Coordinator table or not

    Map<String, String> tableCreationOptions = new HashMap<>();

    tableCreationOptions.put(
        CassandraAdmin.REPLICATION_STRATEGY, ReplicationStrategy.SIMPLE_STRATEGY.toString());
    tableCreationOptions.put(CassandraAdmin.COMPACTION_STRATEGY, CompactionStrategy.LCS.toString());
    tableCreationOptions.put(CassandraAdmin.REPLICATION_FACTOR, "1");

    tableCreationOptions.put(DynamoAdmin.REQUEST_UNIT, "1");
    tableCreationOptions.put(DynamoAdmin.NO_SCALING, "true");
    tableCreationOptions.put(DynamoAdmin.NO_BACKUP, "true");

    Map<String, String> indexCreationOptions = new HashMap<>();
    indexCreationOptions.put(DynamoAdmin.NO_SCALING, "true");

    Map<String, String> reparationOptions = new HashMap<>();
    reparationOptions.put(DynamoAdmin.NO_BACKUP, "true");

    Map<String, String> upgradeOptions = new HashMap<>(tableCreationOptions);

    // Create tables.
    SchemaLoader.load(configFilePath, schemaFilePath, tableCreationOptions, createCoordinatorTables);

    // Alter tables.
    SchemaLoader.alterTables(configFilePath, alteredSchemaFilePath, indexCreationOptions);

    // Repair namespaces and tables.
    SchemaLoader.repairAll(configFilePath, schemaFilePath, reparationOptions, repairCoordinatorTables);

    // Delete tables.
    SchemaLoader.unload(configFilePath, schemaFilePath, deleteCoordinatorTables);

    // Upgrade the environment
    SchemaLoader.upgrade(configFilePath, upgradeOptions);

    return 0;
  }
}

次に示すように、シリアル化されたスキーマ JSON 文字列 (スキーマファイルの生のテキスト) を渡すことによって、スキーマを作成、削除、または修復することもできます。

// Create tables.
SchemaLoader.load(configFilePath, serializedSchemaJson, tableCreationOptions, createCoordinatorTables);

// Alter tables.
SchemaLoader.alterTables(configFilePath, serializedAlteredSchemaFilePath, indexCreationOptions);

// Repair namespaces and tables.
SchemaLoader.repairAll(configFilePath, serializedSchemaJson, reparationOptions, repairCoordinatorTables);

// Delete tables.
SchemaLoader.unload(configFilePath, serializedSchemaJson, deleteCoordinatorTables);

ScalarDB を設定するときに、次に示すように Properties オブジェクトも使用できます。

// Create tables.
SchemaLoader.load(properties, serializedSchemaJson, tableCreationOptions, createCoordinatorTables);

// Alter tables.
SchemaLoader.alterTables(properties, serializedAlteredSchemaFilePath, indexCreationOptions);

// Repair namespaces and tables.
SchemaLoader.repairAll(properties, serializedSchemaJson, reparationOptions, repairCoordinatorTables);

// Delete tables.
SchemaLoader.unload(properties, serializedSchemaJson, deleteCoordinatorTables);

// Upgrade the environment
SchemaLoader.upgrade(properties, upgradeOptions);

Import tables​

サンプルスキーマファイルに示されているのと同様の方法で、--import オプションとインポート固有のスキーマファイルを使用して、既存の JDBC データベーステーブルを ScalarDB にインポートできます。詳細については、ScalarDB Schema Loader を使用して既存のテーブルを ScalarDB にインポートするを参照してください。

警告

運用環境で ScalarDB にテーブルをインポートする場合は、データベーステーブルと ScalarDB メタデータテーブルにトランザクションメタデータ列が追加されるため、慎重に計画する必要があります。この場合、データベースと ScalarDB の間にはいくつかの違いがあり、いくつかの制限もあります。

以下はインポートのサンプルです。

public class SchemaLoaderImportSample {
  public static int main(String... args) throws SchemaLoaderException {
    Path configFilePath = Paths.get("database.properties");
    // "import_sample_schema.json" can be found in the "/sample" directory.
    Path schemaFilePath = Paths.get("import_sample_schema.json");
    Map<String, String> tableImportOptions = new HashMap<>();

    // Import tables.
    // You can also use a Properties object instead of configFilePath and a serialized-schema JSON
    // string instead of schemaFilePath.
    SchemaLoader.importTables(configFilePath, schemaFilePath, tableImportOptions);

    return 0;
  }
}