Oracle NoSQL Database Migratorのワークフロー

NoSQL Data Migratorユーティリティのダウンロード

Oracle NoSQL Database Migratorユーティリティは、Oracle NoSQLのダウンロード・ページからダウンロードできます。マシンにダウンロードして解凍すると、コマンドライン・インタフェースからrunMigratorコマンドにアクセスできます。

ノート:

Oracle NoSQL Database Migratorユーティリティを実行するには、Java 11以降のバージョンが必要です。

ソースとシンクの指定

マイグレータを使用する前に、データ・ソースとシンクを指定する必要があります。たとえば、オンプレミスのOracle NoSQL DatabaseからJSON形式のファイルにNoSQL表を移行する場合、ソースはOracle NoSQL Databaseになり、シンクはJSONファイルになります。「サポートされるソースとシンク」を参照して、指定したソースとシンクがOracle NoSQL Database Migratorでサポートされていることを確認します。これは、ターゲットまたはシンクのNoSQL表のスキーマを決定して作成するための適切なフェーズでもあります。

シンク表スキーマの指定: シンクがオンプレミスまたはクラウドのOracle NoSQL Databaseの場合は、シンク表のスキーマを指定し、ソース・データがターゲット・スキーマと一致することを確認する必要があります。必要に応じて、変換を使用してソース・データをシンク表にマップします。
- デフォルト・スキーマ: NoSQL Database Migratorには、表のスキーマを事前定義する必要なく、デフォルト・スキーマを使用して表を作成するオプションが用意されています。これは、主にJSONソース・ファイルをOracle NoSQL Databaseにロードする場合に役立ちます。
  ソースがMongoDB形式のJSONファイルの場合、表のデフォルト・スキーマは次のようになります。
```
CREATE TABLE IF NOT EXISTS <tablename>(ID STRING, DOCUMENT JSON,PRIMARY KEY(SHARD(ID))
```
  説明:
  
  — tablename = 構成のtable属性に指定された値。
  
  — ID = mongoDBでエクスポートされたJSONソース・ファイルの各ドキュメントの_id値。
  
  — DOCUMENT = mongoDBでエクスポートされたファイル内のドキュメントごとに、_idフィールドを除く内容がDOCUMENT列に集計されます。
  ソースがDynamoDB形式のJSONファイルの場合、表のデフォルト・スキーマは次のようになります。
```
CREATE TABLE IF NOT EXISTS <TABLE_NAME>(DDBPartitionKey_name DDBPartitionKey_type, 
[DDBSortKey_name DDBSortKey_type],DOCUMENT JSON,
PRIMARY KEY(SHARD(DDBPartitionKey_name),[DDBSortKey_name]))
```
  説明:
  
  — TABLE_NAME = 構成内のシンク表に指定された値
  
  — DDBPartitionKey_name = 構成内のパーティション・キーに指定された値
  
  — DDBPartitionKey_type = 構成内のパーティション・キーのデータ型に指定された値
  
  — DDBSortKey_name = 構成内のソート・キーに指定された値(ある場合)
  
  — DDBSortKey_type = 構成内のソート・キーのデータ型に指定された値(ある場合)
  
  — DOCUMENT = NoSQL JSON列に集計されたDynamo DB表アイテムのパーティションおよびソート・キーを除くすべての属性
  
  ソース形式がCSVファイルの場合、ターゲット表ではデフォルトのスキーマはサポートされていません。ソースCSVファイルと同じ数の列とデータ型を含む表定義を持つスキーマ・ファイルを作成できます。スキーマ・ファイルの作成の詳細は、「表スキーマの提供」を参照してください。
  その他すべてのソースでは、デフォルト・スキーマは次のようになります。
```
CREATE TABLE IF NOT EXISTS <tablename> (ID LONG GENERATED ALWAYS AS IDENTITY, DOCUMENT JSON, PRIMARY KEY(ID))
```
  説明:
  
  — tablename = 構成のtable属性に指定された値。
  
  — ID = 自動生成されたLONG値。
  
  — DOCUMENT = ソースによって提供されるJSONレコードがDOCUMENT列に集計されます。
  
  ノート:
  MongoDB形式のJSONファイルで_id値が文字列として指定されていない場合、NoSQL Database Migratorは、デフォルト・スキーマに挿入する前に値を文字列に変換します。
表スキーマの提供: NoSQL Database Migratorでは、ソースはschemaInfo属性を使用して表データのスキーマ定義を提供できます。schemaInfo属性は、まだ暗黙的スキーマが定義されていないすべてのデータ・ソースで使用できます。シンク・データ・ストアでは、次のオプションのいずれかを選択できます。
- NoSQL Database Migratorで定義されたデフォルトのスキーマを使用します。
- ソース提供のスキーマを使用します。
- 独自のスキーマを定義して、ソース提供のスキーマをオーバーライドします。たとえば、ソース・スキーマから別のスキーマにデータを変換する場合は、ソース提供のスキーマをオーバーライドし、NoSQL Database Migratorツールの変換機能を使用する必要があります。
図source_sink_schema_example.pngの説明

たとえば、表スキーマ・ファイルmytable_schema.ddlには、表DDL文を含めることができます。NoSQL Database Migratorツールは、移行を開始する前にこの表スキーマ・ファイルを実行します。マイグレータ・ツールでは、スキーマ・ファイルの1行に1つのDDL文のみをサポートします。たとえば、次のようになります。
```
CREATE TABLE IF NOT EXISTS(id INTEGER, name STRING, age INTEGER, PRIMARY KEY(SHARD(ID)))
```
シンク表の作成: シンク表スキーマの指定後は、管理CLIまたはシンク構成ファイルのschemaInfo属性を使用してシンク表を作成します。シンク構成テンプレートを参照してください。

ノート:
ソースがCSVファイルの場合は、ターゲット表のスキーマに対するDDLコマンドを使用してファイルを作成します。シンク構成ファイルのschemaInfo.schemaPathパラメータにファイル・パスを指定します。

表の行のTTLメタデータの移行

NoSQL表の移行の実行時に、表の行のTTLメタデータを実際のデータとともに含めるように選択できます。NoSQL Database Migratorには、表の行のTTLメタデータのエクスポートおよびインポートをサポートする構成パラメータが用意されています。さらに、このツールにはインポート操作中に表の行の相対的な有効期限を選択するオプションもあります。オプションで、includeTTLパラメータを使用してTTLメタデータをエクスポートまたはインポートできます。

ノート:

表の行のTTLメタデータ移行のサポートは、Oracle NoSQL DatabaseおよびOracle NoSQL Database Cloud Serviceのみ使用できます。

TTLメタデータのエクスポート

表がエクスポートされると、有効な有効期限を持つ表の行のTTLデータがエクスポートされます。行が失効しない場合、有効期限値は常に0であるため、この行はエクスポートされたデータに明示的に含まれません。TTL情報は、エクスポートされた各行の_metadata JSONオブジェクトに含まれています。NoSQL Database Migratorは、各行の有効期限を、UNIXエポック(1970年1月1日)以降のミリ秒数としてエクスポートします。たとえば、次のようになります。

//Row 1
{
    "id" : 1,
    "name" : "xyz",
    "age" : 45,
    "_metadata" : {
        "expiration" : 1629709200000   //Row Expiration time in milliseconds
    }
}

//Row 2
{
    "id" : 2,
    "name" : "abc",
    "age" : 52,
    "_metadata" : {
        "expiration" : 1629709400000   //Row Expiration time in milliseconds
    }
}

//Row 3 No Metadata for below row as it will not expire
{
    "id" : 3,
    "name" : "def",
    "age" : 15
}

TTLメタデータのインポート

オプションで、構成パラメータincludeTTLを使用してTTLメタデータをインポートできます。インポート操作では、TTLメタデータを含む表の行を移行する際に次のユースケースが処理されます。これらのユースケースは、includeTTL構成パラメータが指定されている場合にのみ適用されます。

ユースケース2および3では、インポート操作のデフォルトの参照時間は、NoSQL Database Migratorツールが実行されているマシンのSystem.currentTimeMillis()から取得された現在の時間(ミリ秒)です。ただし、有効期限を延長し、延長しなければすぐに期限切れになる行をインポートする場合は、ttlRelativeDate構成パラメータを使用してカスタム参照時間を設定することもできます。

ユースケース1: インポートする表の行にTTLメタデータ情報がありません。
外部ソースから生成された、または以前のバージョンの移行を使用してエクスポートされたJSONソース・ファイルをインポートする場合、インポートする行にはTTL情報がありません。ただし、includeTTL構成パラメータはtrueと等しいため、マイグレータは表の行にTTL=0を設定します。つまり、インポートする表の行は失効しません。
ユースケース2: 表の行がインポートされると、ソース表の行のTTL値が参照時間に対して失効します。
表の行をファイルにエクスポートし、これを表の行の有効期限後にインポートしようとすると、表の行は無視され、ストアに書き込まれません。
ユースケース3: 表の行がインポートされると、ソース表の行のTTL値が参照時間に対して失効しません。
表の行をファイルにエクスポートし、これを表の行の有効期限より前にインポートしようとすると、表の行がTTL値でインポートされます。ただし、TimeToLiveクラスの整数時間と日の期間の制約のため、表の行の新しいTTL値はエクスポートされたTTL値と等しくない場合があります。たとえば、次のようになります。
エクスポートされた表の行
```
{
  "id" : 8,
  "name" : "xyz",
  "_metadata" : {
    "expiration" : 1629709200000 //Monday, August 23, 2021 9:00:00 AM in UTC
  }
}
```
インポート中の参照時間は1629707962582で、2021年8月23日月曜日午前8:39:22.582です。
インポートされた表の行
```
{
  "id" : 8,
  "name" : "xyz",
  "_metadata" : {
    "ttl" :  1629712800000 //Monday, August 23, 2021 10:00:00 AM UTC
  }
}
```

runMigratorコマンドの実行

runMigrator実行可能ファイルは、抽出されたNoSQL Database Migratorファイルで使用できます。runMigratorコマンドを正常に実行するには、システムにJava 8以上のバージョンおよびbashをインストールする必要があります。

runMigratorコマンドは、次の2つの方法で実行できます。

次のように、runMigratorコマンドのランタイム・オプションを使用して構成ファイルを作成します。
```
[~]$ ./runMigrator
configuration file is not provided. Do you want to generate configuration? (y/n)                                                                              
 
[n]: y
...
...
```
- runMigratorユーティリティを起動すると、一連のランタイム・オプションが提供され、各オプションの選択内容に基づいて構成ファイルが作成されます。
- ユーティリティによって構成ファイルが作成された後は、同じ実行で移行アクティビティを続行するか、将来の移行のために構成ファイルを保存できます。
- 生成された構成ファイルでの移行アクティビティの続行または延期に関係なく、将来の要件を満たすようにファイルを編集またはカスタマイズできます。カスタマイズした構成ファイルは、後で移行に使用できます。
-cまたは--configオプションを使用して、手動で作成した構成ファイル(JSON形式)を実行時パラメータとして渡します。-cまたは--configオプションを指定してrunMigratorコマンドを実行する前に、構成ファイルを手動で作成する必要があります。ソースとシンクの構成パラメータのヘルプは、ソースとシンクを参照してください。
```
[~]$ ./runMigrator -c </path/to/the/configuration/json/file>
```

Migratorの進捗状況のロギング

NoSQL Database Migratorツールには、トレース、デバッグおよび進行状況のメッセージを標準出力またはファイルに出力できるオプションが用意されています。このオプションは、特に表またはデータ・セットが大規模な場合に、移行操作の進捗状況を追跡するために役立ちます。

ログ・レベル

NoSQL Database Migratorツールを使用してロギング動作を制御するには、--log-levelまたは-l run timeパラメータをrunMigratorコマンドに渡します。書き込むログ情報の量を指定するには、適切なログ・レベルの値を渡します。

$./runMigrator --log-level <loglevel>

次に例を示します。

$./runMigrator --log-level debug

表7-1 NoSQL Database Migratorでサポートされるログ・レベル

ログ・レベル	説明
warning	エラーおよび警告を出力します。
info (デフォルト)	ソースの検証、シンクの検証、表の作成、移行されたデータ・レコードの数など、データ移行の進捗状況ステータスを出力します。
debug	追加のデバッグ情報を出力します。
all	すべてを出力します。このレベルはロギングのすべてのレベルをオンにします。

ログ・ファイル:
--log-fileまたは-fパラメータを使用して、ログ・ファイルの名前を指定できます。--log-fileがランタイム・パラメータとしてrunMigratorコマンドに渡された場合、NoSQL Database Migratorはすべてのログ・メッセージをファイルに、それ以外の場合は標準出力に書き込みます。
```
$./runMigrator --log-file <log file name>
```
次に例を示します。
```
$./runMigrator --log-file nosql_migrator.log
```