========================= ThunderGateユーザーガイド ========================= この文書では、ThunderGateの利用方法について紹介します。 機能と構成の概要 ================ ThunderGateは、バッチアプリケーションが処理するデータを管理するRDBMSとHadoopクラスター間でデータを転送するツールです。 RDBMSがインストールされているサーバー（データベースノード）とHadoopクラスター上のある特定のサーバー（Hadoopクライアントマシン）間の 二点間でデータを転送します。 ThunderGateと連携したバッチアプリケーションを作成する場合、通常はそれぞれのジョブフローの入力と出力時にそれぞれThunderGateの処理が実行されます。 たとえば、ジョブフローの処理の開始時にThunderGateを利用して、データベースの内容をHadoopクラスター上に展開し（インポート）、 処理の終了時に計算結果をデータベースに書き戻します（エクスポート）。 対応RDBMS --------- ThunderGateが対応するRDBMSは ``MySQL`` [#]_ [#]_ のみとなっています。ThunderGateはインポートとエクスポートに ``MySQL`` に依存した処理を実行することでMySQL向けに最適化されています。 .. [#] https://www.mysql.com/ .. [#] 対応しているバージョンの詳細については、 :doc:`../product/target-platform` を参照してください。 プロセスの概要 -------------- ThunderGateはデータベースノードとHadoopクライアントマシンにそれぞれ配置したモジュールが連携して動作します。ThunderGateの各プロセスは :doc:`YAESS <../yaess/index>` などの外部のワークフローエンジンから起動され、処理の完了とともにプロセスが終了します。 また、ThunderGateは運用時に手動で環境をメンテナンスするためのコマンドラインツールを提供しています。 ThunderGateが提供するプロセスの一覧とその概要を以下に示します。 .. list-table:: ThunderGateのプロセス概要 :widths: 15 25 60 :header-rows: 1 * - プロセス - 実行ノード - 概要 * - ``インポータ`` - データベースノード - RDBMSからデータを取得し、Hadoopクライアントマシン上のエクストラクタの実行を介してHadoopクライアントマシンにデータを送信する * - ``エクストラクタ`` - Hadoopクライアントマシン - インポータから転送されたデータをHadoopファイルシステムに配置する。 * - ``エクスポータ`` - データベースノード - Hadoopクライアントマシン上のコレクタの実行を介してHadoopクライアントマシンからデータを受信し、RDBMSへ登録/更新する * - ``コレクタ`` - Hadoopクライアントマシン - Hadoopファイルシステムのデータを取得し、エクスポータに送信する。 * - ``リカバラ`` - データベースノード - ジョブフローの実行状態に基づいて、必要に応じて処理のロールバックまたはロールフォワードを処理を行う。 * - ``運用ツール群`` - データベースノード - ThunderGateの管理情報やキャッシュデータのメンテナンスを実行する。 .. note:: :doc:`../administration/deployment-architecture` の説明では便宜的に、データベースノードに配置するモジュールを「ThunderGate」または「ThunderGate本体」, Hadoopクライアントマシンに配置するモジュールを「ThunderGate Hadoopブリッジ」 という呼称を使って説明を行っています。 データソースとターゲット ------------------------ ThunderGateが処理の対象とするデータベース群を「データソース」と呼びます。データソースはシステム全体で複数存在することがあります。Asakusa DSLからあるデータソースを特定するための識別子を「ターゲット」と呼びます。 ThunderGateはRDBMSに対してJDBC接続を行うことでデータの転送を行いますが、DSLではRDBMSに対する接続設定を直接指定せずに、入出力を行うターゲットのみを指定します。ジョブフローの実行時にはターゲットからRDBMSの接続設定を引き当て、その接続情報を利用してデータの入出力を行います。 入力のアーキテクチャ ==================== ThunderGateの入力（インポート）には次のような特徴があります。 * 処理対象データに対する排他制御 * 複数データソースに対するデータ入力 * 差分インポート用に入力データをHadoopクラスターにキャッシュ 処理対象データに対する排他制御 ------------------------------ ThunderGateを利用したバッチアプリケーションは、ジョブフローを実行する際に処理対象とするデータ（データベースのテーブル、及びレコード）に対してロックをかけることが出来ます。このロックは以下のような用途を想定しています。 * 同じテーブル、もしくはレコードを参照/更新する複数のバッチアプリケーションが同時に実行される可能性があり、バッチ間の排他制御を行う必要がある場合。 * Webアプリケーションなどのオンラインシステムとデータベースを共有する場合で、バッチアプリケーションとオンラインアプリケーション間の排他制御を行う必要がある場合。 ThunderGateのロックは、対象となるアプリケーションがThunderGate用の `管理テーブル`_ や `管理カラム`_ [#]_ の値を判断して実現する論理的なロック [#]_ です。このため、バッチアプリケーションと連携するオンラインアプリケーションは、ThunderGateが提供するロック機構に従ってアプリケーションのロック戦略を決定し、アプリケーションを実装する必要があるかもしれません。オンラインアプリケーションとの連携については、 `オンラインアプリケーションとの連携`_ にて後述します。 バッチアプリケーションでは、DSLを介してアプリケーションが取得するロック対象のテーブルやその `ロックの種類`_ を指定します。 .. [#] ThunderGateを利用する上で必要となる、バッチアプリケーションの処理対象となるテーブルに付随して定義するテーブルやカラムです。詳しくは後述の `テーブル定義`_ にて解説します。 .. [#] RDBMS自体が持つロック機構を使用したロックではありません。 ロックの種類 ~~~~~~~~~~~~ ThunderGateを利用したアプリケーションが指定できるロックの種類を示します。 .. list-table:: ロックの種類 :widths: 1 9 :header-rows: 1 * - ロック種別 - 概要 * - ``TABLE`` - インポート対象のテーブル全体をロックする。ロックの取得に失敗したらエラーとする。 * - ``ROW`` - インポート対象のレコードのみをロックする。ロックの取得に失敗したらエラーとする。 * - ``ROW_OR_SKIP`` - インポート対象のレコードのみをロックする。ロックの取得に失敗したらそのレコードをインポート対象から除外する。 * - ``CHECK`` - ロックの有無を確認するがロックは取得しない。ロックが行われていたらエラーとする。 * - ``UNUSED`` - あらゆるロック操作を行わない。 ThunderGateを利用したアプリケーションは、ジョブフロー記述のDSLを介して使用するロックの種類を指定します。詳しくは :doc:`with-dsl` を参照してください。 複数データソースに対するデータ入力 ---------------------------------- ThunderGateは原則として、1つのジョブフローで扱うデータソースは1つとしていますが、以下の制約を前提として例外的に1つのジョブフローで複数のデータソースを扱うことが出来ます。 * エクスポート及びロックを行うことが出来るデータソースは1つのみ。 これは、参照と更新を行うトランザクションデータと参照のみを行うマスタデータを異なるデータソースで管理している場合に、この制約の元でデータをインポートすることを想定しています。複数データソースに対するデータ入力はAsakusa DSLが提供する「補助インポータ」と呼ばれるDSLを利用して実現します。 差分インポート用に入力データをHadoopクラスターにキャッシュ ---------------------------------------------------------- ThunderGateは差分インポートを実現するためのキャッシュ機構を提供しています。 ジョブフローのDSLの指定によりキャッシュ機能を有効にすることで、ThunderGateはテーブルのインポートが行われた後にもそのインポートしたデータをHadoopクラスター上に保存（キャッシュ）するようになります。次回に同じテーブルをインポートする際に、ThunderGateは前回インポートしたデータと今回インポートするデータの差分を検出し、変更がない部分については前回保存したデータを最利用します。 このため、変更頻度が低い巨大なテーブルでキャッシュを利用すると、ThunderGateのインポート時間を大幅に削減できます。 キャッシュ機能の使用方法について詳しくは、 :doc:`cache` を参照してください。 出力のアーキテクチャ ==================== ThunderGateの出力（エクスポート）には次のような特徴があります。 * 出力データのマージ更新 * 出力のアトミック処理 * 重複チェック 出力データのマージ更新 ---------------------- ThunderGateは出力データをRDBMSに書き戻す際に、アプリケーション内で新規作成されたデータか、入力データに対する更新データであるかをテーブルのキー [#]_ に基づいて判断し、データの挿入、もしくは更新を自動的に選択するマージ更新を行います。 .. [#] テーブルのキーには後述する `管理カラム`_ のシステムIDを使用します。 .. note:: WindGateではデータの書き戻し時には対象となるテーブルをTRUNCATEした後にINSERTを行い、マージ処理が必要な場合はWindGateの外側で出力データのマージ処理を行うことを想定していますが、ThunderGateでは先述のロック機構と合わせて、連携するオンラインアプリケーションが直接利用するテーブルに対して出力することを想定しています。 出力のアトミック処理 -------------------- 出力のアトミック処理とは、ジョブフローの実行がなにかしらの理由により正常に終了しなかった場合に、データソースの内容をロールバック、もしくはロールフォワードして、データソースが持つデータの不整合を解消する機構です。 ThunderGateはジョブフローの処理途中でエラーが発生した場合、データベースに保持するThunderGate用のシステム情報からジョブフローの進捗状況を判断し、データソースをジョブフロー実行前の状態に戻す（ロールバック）か、データソースをジョブフローが正常に終了する場合と同じ状態になるように処理を進める（ロールフォワード）ことを試みます。 ThunderGateは出力のアトミック処理を実現するために、エクスポート処理の課程でエクスポート対象データを作成し、これを「ステージング領域」 [#]_ に展開し、このステージング領域からエクスポート対象のテーブルに展開します。 リカバリ時にロールバックを行うか、ロールフォワードを行うかは、以下の基準に従って判断されます。 1. エクスポート処理において、ステージング領域からエクスポート対象のテーブルに対して一部のデータの更新/挿入が始まっている場合は、ロールフォワードが試みられる。 2. 上記1以外の場合は、ロールバックが試みられる。 ThunderGateはジョブフローの異常終了時にワークフロー定義に従ってリカバリ処理を自動で実行します。また手動でリカバリを実行するためのコマンドラインインターフェースを提供しています。手動でのリカバリはアプリケーション実行環境の障害などで異常終了も行なわれなかったような状況において利用することを想定しています。 .. [#] ステージング領域はエクスポート処理時に一時的に作成される、エクスポート対象のテーブル構造と同じ構造をもつ「エクスポートテンポラリテーブル」と、エクスポートテンポラリテーブルを管理するシステムテーブルなどから構成されます。 重複チェック ------------ 重複チェックとはエクスポート時に特定のカラムの値が同じである「重複データ」が既にデータベース上にあるかどうかをチェックを行い、そのようなデータを通常のエクスポート対象テーブルに書き戻すかわりにエラー情報用のテーブルに書き戻すという機能です。 この機能は、データベースのキーとは別に業務的に意味のある項目に対してチェックを行う [#]_ もので、これは通常業務ロジックとして扱うような処理になりますが、エクスポートのタイミングで行うことで業務ロジックを効率的に実装することを意図しています。 重複チェックを利用するには、重複チェック用のテーブルを用意し、重複チェック用のロジックをDSLの定義に記述します [#]_ 。 .. [#] 例えば、「受注伝票から出荷伝票を新規に作成するバッチアプリケーションで、作成した出荷伝票データをエクスポートする際に、伝票番号と伝票区分をキー項目として重複チェックを行う」といったように利用することを想定しています。 .. [#] 重複チェックのDSL定義については、 :doc:`with-dsl` を参照してください。 ThunderGateの設定 ================= ThunderGateの各設定ファイルは、 ``$ASAKUSA_HOME/bulkloader/conf`` ディレクトリ配下に配置します。ThunderGateの設定ファイルの一覧を下表に示します。 .. list-table:: ThunderGateの設定ファイル一覧 :widths: 3 4 3 :header-rows: 1 * - 種類 - ノード - 設定ファイル名 * - `JDBC接続設定ファイル`_ - データベースノード - ``<ターゲット名>-jdbc.properties`` * - `データベースノード用ThunderGate設定ファイル`_ - データベースノード - ``bulkloader-conf-db.properties`` * - `Hadoopクライアントマシン用ThunderGate設定ファイル`_ - Hadoopクライアントマシン - ``bulkloader-conf-hc.properties`` * - `環境変数設定スクリプト`_ - データベースノード/Hadoopクライアントマシン - ``env.sh`` * - `ログ設定ファイル`_ - データベースノード/Hadoopクライアントマシン - ``log4j.xml`` 拡張子が ``.properties`` の設定ファイルは、Javaの一般的なプロパティファイルの文法で設定項目を定義しますが、プロパティファイルのすべての項目の値には ``${環境変数名}`` という形式で環境変数を含めることができます。 .. _thundergate-jdbc-configuration-file: JDBC接続設定ファイル -------------------- JDBC接続設定ファイルは、ターゲットに対するJDBC接続設定を定義します。このプロパティファイルは ``$ASAKUSA_HOME/bulkloader/conf`` 配下にターゲット毎に ``<ターゲット名>-jdbc.properties`` という名前で配置します。 .. list-table:: JDBC接続設定ファイル :widths: 3 2 5 :header-rows: 1 * - 名前 - 既定値 - 値 * - ``jdbc.driver`` - - JDBCドライバー名 * - ``jdbc.url`` - - JDBCドライバーURL * - ``jdbc.user`` - - JDBC接続ユーザー名 * - ``jdbc.password`` - - JDBC接続パスワード * - ``database.name`` [#]_ - - RDBMSのデータベース名 * - ``db.parameter`` [#]_ - - JDBC接続プロパティファイルパス .. [#] 通常は設定する必要はありません。レガシーモジュールのテストドライバーが使用する設定ファイルとフォーマットを統一するために設定ファイルのテンプレートに項目が含まれています。レガシーモジュールについては、 :doc:`../application/legacy-module-guide` を参照してください。 .. [#] JDBC接続時に渡すプロパティを記述したプロパティファイルのパスを絶対パスで指定します。チューニングパラメータなどを渡す必要がある場合に使用することを想定しています。 .. _thundergate-db-configuration-file: データベースノード用ThunderGate設定ファイル ------------------------------------------- データベースノード用ThunderGate設定ファイル (``$ASAKUSA_HOME/bulkloader/conf/bulkloader-conf-db.properties``) は、データベースノードで動作するThunderGateのプロセスの動作を設定します。 データベースノード用ThunderGate設定ファイルは、設定の対象によって以下のセクションに分類されます。 .. list-table:: データベースノード用ThunderGate設定ファイルの項目 :widths: 4 6 :header-rows: 1 * - セクション名 - 内容 * - `データベースノード共通設定`_ - データベースノードで動作する各プロセス共通の設定 * - `インポート設定 (データベースノード)`_ - データベースノードで実行されるインポートの動作に関する設定 * - `エクスポート設定 (データベースノード)`_ - データベースノードで実行されるエクスポートの動作に関する設定 * - `管理カラム設定`_ - 業務テーブルに必要な管理カラムの設定 [#]_ * - `重複チェック機能設定`_ - 重複機能に関する設定 以降では、それぞれのセクションに対する設定項目について説明します。 .. [#] 業務テーブルや管理カラムについては、後述の `テーブル定義`_ を参照してください。 データベースノード共通設定 ~~~~~~~~~~~~~~~~~~~~~~~~~~ データベースノードで動作する各プロセス共通の設定を記述します。 .. list-table:: データベースノード共通設定 :widths: 3 2 5 :header-rows: 1 * - 名前 - 既定値 - 値 * - ``log.conf-path`` - ``bulkloader/conf/log4j.xml`` - 各プロセスが使用する ``Log4J`` の設定ファイルパス (絶対パス) * - ``ssh.path`` - - 各プロセスがHadoopクライアントマシンの接続時に使用する ``ssh`` コマンドのパス * - ``hadoop-cluster.host`` - - Hadoopクライアントマシンのホスト名 * - ``hadoop-cluster.user`` - - Hadoopクライアントマシンのログインユーザー名 * - ``hadoop-cluster.env.ASAKUSA_HOME`` - - HadoopクライアントマシンのAsakusa Frameworkのインストールパス * - ``hadoop-cluster.env.HADOOP_CMD`` - - Hadoopクライアントマシンが利用する ``hadoop`` コマンドのパス。 [#]_ .. [#] オプション項目です。HADOOP_CMDが不要なHadoopディストリビューションを使用している場合は設定しないでください。 インポート設定 (データベースノード) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ データベースノードで行われるインポートに関する設定を記述します。 .. list-table:: インポート設定 (データベースノード) :widths: 3 2 5 :header-rows: 1 * - 名前 - 既定値 - 値 * - ``import.tsv-create-dir`` - - インポートデータの中間ファイルを出力するディレクトリ (絶対パス) 。このディレクトリはRDBMSの実行ユーザー,及びThunderGateの実行するユーザーの両ユーザーに対して ``READ`` と ``WRITE`` の権限が必要。 * - ``import.zip-comp-type`` - ``NONE`` - Hadoopクライアントマシンにデータを転送する際に、転送データの圧縮を行うか。 ``NONE``: 圧縮しない, ``COMPRESS``: 圧縮する * - ``import.zip-comp-buf-size`` - 32768 - 転送データの圧縮時に使用するバッファサイズ(byte) * - ``import.retry-count`` - 3 - リトライ可能エラーが発生した場合のリトライ試行回数 * - ``import.retry-interval`` - 10 - リトライ可能エラーが発生した場合のリトライインターバル(秒数) * - ``import.delete-tsv`` - ``DELETE`` - 処理が正常終了した場合、 ``import.tsv-create-dir`` に生成された中間ファイルを削除するか。 ``DELETE``: 削除する, ``KEEP``: 削除しない エクスポート設定 (データベースノード) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ データベースノードで行われるエクスポート処理に関する設定を記述します。 .. list-table:: エクスポート設定 (データベースノード) :widths: 3 2 5 :header-rows: 1 * - 名前 - 既定値 - 値 * - ``export.tsv-create-dir`` - - エクスポートデータの中間ファイルを出力するディレクトリ (絶対パス) 。このディレクトリはRDBMSの実行ユーザー,及びThunderGateの実行するユーザーの両ユーザーに対して ``READ`` と ``WRITE`` の権限が必要。 * - ``export.zip-comp-buf-size`` - 32768 - 転送データの受信時に使用するバッファサイズ(byte) * - ``export.retry-count`` - 3 - リトライ可能エラーが発生した場合のリトライ試行回数 * - ``export.retry-interval`` - 10 - リトライ可能エラーが発生した場合のリトライインターバル(秒数) * - ``export.data-copy-max-count`` - 100000 - エクスポートデータを業務テーブルにコピーする際の、1トランザクションで処理する最大レコード数 * - ``export.delete-tsv`` - ``DELETE`` - 処理が正常終了した場合、 ``export.tsv-create-dir`` に生成された中間ファイルを削除するか。 ``DELETE``: 削除する, ``KEEP``: 削除しない 管理カラム設定 ~~~~~~~~~~~~~~ 管理カラムの設定を記述します。管理カラムについて詳しくは後述の `管理カラム`_ を参照してください。 .. list-table:: 管理カラム設定 :widths: 3 2 5 :header-rows: 1 * - 名前 - 既定値 - 値 * - ``table.sys-column-sid`` - ``SID`` - 業務テーブルのシステムIDのカラム名 * - ``table.sys-column-version-no`` - ``VERSION_NO`` - 業務テーブルのバージョン番号のカラム名 * - ``table.sys-column-rgst-date`` - ``RGST_DATETIME`` - 業務テーブルの登録日時のカラム名 * - ``table.sys-column-updt-date`` - ``UPDT_DATETIME`` - 業務テーブルの更新日時のカラム名 * - ``table.sys-column-temp-sid`` - ``__TEMP_SID`` - エクスポート処理で作成するテンポラリテーブルのシステムSIDのカラム名 重複チェック機能設定 ~~~~~~~~~~~~~~~~~~~~ 重複チェック機能の設定を記述します。 .. list-table:: 重複チェック機能設定 :widths: 3 2 5 :header-rows: 1 * - 名前 - 既定値 - 値 * - ``dupcheck.index.<バッチID>|<フローID>|<テーブル名>`` - - 重複チェック機能で発行されるSQLに対して、 ``force index`` 句を追加し、ここで使用するインデックス名を指定。プロパティキーの ``<バッチID>``, ``<フローID>``, ``<テーブル名>`` にそれぞれ対象となるバッチID、フローID、テーブル名の値に置き換えて設定する。 .. _thundergate-hc-configuration-file: Hadoopクライアントマシン用ThunderGate設定ファイル ------------------------------------------------- Hadoopクライアントマシン用ThunderGate設定ファイル (``$ASAKUSA_HOME/bulkloader/conf/bulkloader-conf-hc.properties``) は、Hadoopクライアントマシンで動作するThunderGateのプロセスの動作を設定します。 Hadoopクライアントマシン用ThunderGate設定ファイルは、設定の対象によって以下のセクションに分類されます。 .. list-table:: Hadoopクライアントマシン用ThunderGate設定ファイルの項目 :widths: 4 6 :header-rows: 1 * - セクション名 - 内容 * - `Hadoopクライアントマシン共通設定`_ - Hadoopクライアントマシンで動作する各プロセス共通の設定 * - `インポート設定 (Hadoopクライアントマシン)`_ - Hadoopクライアントマシンで行われるインポートの動作に関する設定 * - `エクスポート設定 (Hadoopクライアントマシン)`_ - Hadoopクライアントマシンで行われるエクスポートの動作に関する設定 Hadoopクライアントマシン共通設定 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Hadoopクライアントマシンで動作する各プロセス共通の設定を記述します。 .. list-table:: Hadoopクライアントマシン共通設定 :widths: 3 2 5 :header-rows: 1 * - 名前 - 既定値 - 値 * - ``log.conf-path`` - ``bulkloader/conf/log4j.xml`` - 各プロセスが使用する ``Log4J`` の設定ファイルパス (絶対パス) * - ``base-path`` - - Hadoopのワーキングディレクトリパスを完全URI [#]_ で指定。このプロパティを設定しない場合、Hadoopの設定に従ったワーキングディレクトリが使用される。 .. [#] 完全URIとはファイルシステム、ホスト、パスを指定した形式です。例えば ``hdfs://localhost/tmp/asakusa`` などです。 インポート設定 (Hadoopクライアントマシン) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Hadoopクライアントマシンで行われるインポートに関する設定を記述します。 .. list-table:: インポート設定 (Hadoopクライアントマシン) :widths: 3 2 5 :header-rows: 1 * - 名前 - 既定値 - 値 * - ``import.cache-build-max-parallel`` - - キャッシュ機能のキャッシュ構築処理時に関する最大並列処理数 [#]_ .. attention:: Asakusa Framework ``0.7.0`` より、設定 ``import.seq-comp-type`` は利用できなくなりました。 転送時の圧縮はフレームワークが規定する内部の形式を利用するようになります。 .. [#] キャッシュ処理については、 :doc:`cache` を参照してください。 エクスポート設定 (Hadoopクライアントマシン) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Hadoopクライアントマシンで行われるエクスポート処理に関する設定を記述します。 .. list-table:: エクスポート設定 (Hadoopクライアントマシン) :widths: 3 2 5 :header-rows: 1 * - 名前 - 既定値 - 値 * - ``export.zip-comp-type`` - ``NONE`` - データベースノードにデータを転送する際に、転送データの圧縮を行うか。 ``NONE``: 圧縮しない, ``COMPRESS``: 圧縮する * - ``export.tsv-max-size`` - 16777216 - データベースノードにデータを転送する際の1ファイルの最大サイズ (byte) 。この値より大きなファイルをデータベースノードに転送する場合、ファイルが分割されて転送される。 環境変数設定スクリプト ---------------------- ThunderGateの実行に特別な環境変数を利用する場合、 ``$ASAKUSA_HOME/bulkloader/conf/env.sh`` 内でエクスポートして定義できます。 ThunderGateをAsakusa Frameworkのバッチから利用する場合、以下の環境変数が必要です。 .. list-table:: ThunderGateの実行に必要な環境変数 :widths: 10 60 :header-rows: 1 * - 名前 - 備考 * - ``JAVA_HOME`` - JAVAのインストール先パス * - ``ASAKUSA_HOME`` - Asakusa Frameworkのインストール先パス 特別な理由がない限り、 ``ASAKUSA_HOME`` はThunderGateを実行する前 [#]_ にあらかじめ定義しておいてください。 ``$ASAKUSA_HOME/bulkloader/conf/env.sh`` では、その他必要な環境変数を定義するようにしてください。 その他、以下の環境変数を利用可能です。 .. list-table:: ThunderGateで利用可能な環境変数 :widths: 10 60 :header-rows: 1 * - 名前 - 備考 * - ``HADOOP_CMD`` - 利用する ``hadoop`` コマンドのパス。 * - ``HADOOP_HOME`` - Hadoopのインストール先パス。 * - ``IMPORTER_JAVA_OPTS`` - インポータを実行するJava VMの追加オプション * - ``EXPORTER_JAVA_OPTS`` - エクスポータを実行するJava VMの追加オプション * - ``RECOVERER_JAVA_OPTS`` - リカバラを実行するJava VMの追加オプション * - ``EXTRACTOR_JAVA_OPTS`` - エクストラクタを実行するJava VMの追加オプション * - ``COLLECTOR_JAVA_OPTS`` - コレクタを実行するJava VMの追加オプション なお、ThunderGateの本体は、以下の規約に従って起動します (上にあるものほど優先度が高いです)。 * 環境変数に ``HADOOP_CMD`` が設定されている場合、 ``$HADOOP_CMD`` コマンドを経由して起動します。 * 環境変数に ``HADOOP_HOME`` が設定されている場合、 ``$HADOOP_HOME/bin/hadoop`` コマンドを経由して起動します。 * ``hadoop`` コマンドのパスが通っている場合、 ``hadoop`` コマンドを経由して起動します。 このため、 ``HADOOP_CMD`` と ``HADOOP_HOME`` の両方を指定した場合、 ``HADOOP_CMD`` の設定を優先します。 特別な理由がない限り、 ``$ASAKUSA_HOME/bulkloader/conf/env.sh`` 内で ``HADOOP_CMD`` や ``HADOOP_HOME`` を設定しておくのがよいでしょう。 または、 :doc:`YAESS <../yaess/index>` を利用して外部から環境変数を設定することも可能です。 .. [#] :doc:`YAESS <../yaess/index>` を経由してThunderGateを実行する場合、ThunderGateがデータベース上で利用する環境変数 ``ASAKUSA_HOME`` はYAESS側の設定で行えます。また、Hadoopクライアントマシン上で利用する環境変数は `データベースノード用ThunderGate設定ファイル`_ で設定することができます。 YAESSについて詳しくは :doc:`../yaess/user-guide` を参照してください。 ログ設定ファイル ---------------- ThunderGateは内部のログ表示に ``Log4J`` [#]_ を利用しています。 ログの設定を変更するには、 ``$ASAKUSA_HOME/bulkloader/conf/log4j.xml`` を編集してください。 また、ThunderGateの実行時には以下の値がシステムプロパティとして設定されます。 .. list-table:: ThunderGate実行時のシステムプロパティ :widths: 20 30 :header-rows: 1 * - 名前 - 値 * - ``logfile.basename`` - プロセス名 .. [#] https://logging.apache.org/log4j/1.2/ .. warning:: ThunderGateのHadoopクライアントマシンの設定では、ログを標準出力に出力しないようにしてください。 データベースノードとHadoopクライアントマシンで標準出力を介したデータ転送を行っているため、標準出力に対するログ出力を行うとデータが正しく転送することが出来ません。なお、標準エラー出力を利用することは問題ありません。 テーブル定義 ============ ThunderGateはデータベースのテーブルに対してデータの入出力を行いますが、ThunderGateを利用する場合、ThunderGate特有のテーブル構造を有する必要があります。 まず、ThunderGateのテーブル定義を説明するにあたって必要となる用語を定義します。 `業務テーブル`_ ThunderGateと連携したバッチアプリケーションがデータの入出力を行う対象となる、業務データを保持するテーブルです。 :doc:`start-guide` で説明したサンプルアプリケーションの例では、 売上トランザクション (``SALES_DEATAIL``) や店舗マスタ (``STORE_INFO``) といったようなテーブルが該当します。 `管理カラム`_ ThunderGateが業務テーブルに対する処理を制御するための管理情報を保持するカラムです。ThunderGateがデータ入出力を行う業務テーブルは、一部の例外を除きThunderGateが定める管理カラムを持つ必要があります。 `管理テーブル`_ ThunderGateが業務テーブルに対する処理を制御するための管理情報を保持するテーブルです。ThunderGateがデータ入出力を行う業務テーブルは、一部の例外を除きThunderGateが定める管理テーブルを持つ必要があります。 `重複エラーテーブル`_ ThunderGateの重複チェック機能を利用する場合に利用するテーブルです。重複チェックを実行結果として重複したレコードが登録されます。バッチアプリケーションが重複チェック機能を利用する場合は、DSLの記述に対応した重複エラーテーブルを用意する必要があります。 `システムテーブル`_ ThunderGateが利用する、ThunderGateの動作を制御するテーブルです。バッチアプリケーションからはこのテーブルを利用しませんが、ThunderGateを利用する環境を構築する際に、一部のシステムテーブルに対して業務テーブルの内容に応じたレコードをセットする必要があります。 以下、それぞれのテーブルについて説明します。 業務テーブル ------------ ThunderGateと連携したバッチアプリケーションがデータの入出力を行う対象となる、業務データを保持するテーブルです。ThunderGateを利用する上で、業務テーブルは以下の制約があります。 1. 各業務テーブルは `管理カラム`_ を持ち、主キー制約を `管理カラム`_ 上のシステムIDに対して定義する。 2. 各業務テーブルは対応する `管理テーブル`_ を持つ。 3. 各業務テーブルのストレージエンジンは ``INNODB`` を使用する [#]_ 。 業務テーブルは基本的に上述した `管理カラム`_ と `管理テーブル`_ を定義する必要がありますが、以下の場合については、 `管理カラム`_ と `管理テーブル`_ の定義は不要です。 1. 補助インポート機能でのみデータの入力を行う業務テーブル .. [#] ``INNODB`` 以外のストレージエンジンでは動作検証が行われていません。 業務テーブルに対応するデータモデルクラスの作成 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ThunderGateはテーブルの定義情報からDMDLを生成する「DMDLジェネレータ」を提供しており、これを利用して業務テーブルのDDLスクリプトからAsakusa DSLで利用するデータモデルクラスを生成することが出来ます [#]_ 。 業務テーブルからデータモデルクラスを生成する場合、業務テーブルのDDLスクリプトをプロジェクトの ``src/main/sql/modelgen`` ディレクトリ以下に配置してください。また、スクリプトのファイル名には ``.sql`` の拡張子を付けて保存してください [#]_ 。 プロジェクトに対して Gradleの ``compileDMDL`` タスクを実行すると、業務テーブルに対応するDMDLスクリプト、及びデータモデルクラスが生成されます [#]_ 。 .. [#] DMDLとの連携について詳しくは :doc:`with-dmdl` を参照してください。 .. [#] SQLファイルは複数配置することが出来ます。上記ディレクトリ配下にサブディレクトリを作成し、そこにSQLファイルを配置することも可能です。SQLファイルを複数配置した場合、ディレクトリ名, ファイル名の昇順にSQLが実行されます。 .. [#] データモデルクラスを作成については :doc:`../application/maven-archetype` も参照してください。 管理カラム ---------- 管理カラムはThunderGateが業務テーブルに対する処理を制御するための管理情報を保持するカラムです。ThunderGateがデータ入出力を行う業務テーブルは、一部の例外を除きThunderGateが定める以下の管理カラムを持つ必要があります。 .. list-table:: 管理カラム :widths: 15 15 30 10 30 :header-rows: 1 * - 名前 - カラム名 [#]_ - 必要な制約等 - データ型 - 説明 * - システムID - ``SID`` - 主キー制約, DBによる自動採番 - ``BIGINT`` - レコードを一意に識別するための値 * - バージョン番号 - ``VERSION_NO`` - デフォルト値に ``1`` を設定 - ``BIGINT`` - レコードのバージョン * - 登録日時 - ``RGST_DATETIME`` - - ``DATETIME`` - レコードの登録日時 * - 更新日時 - ``UPDT_DATETIME`` - - ``DATETIME`` - レコードの更新日時 以下に管理カラムを持つ業務テーブルのDDLスクリプト例を示します。 .. code-block:: sql CREATE TABLE SALES_DETAIL( -- 管理カラム SID BIGINT PRIMARY KEY AUTO_INCREMENT, VERSION_NO BIGINT NULL, RGST_DATETIME DATETIME NULL, UPDT_DATETIME DATETIME NULL, -- 業務テーブルのカラム SALES_DATE_TIME DATETIME NOT NULL, STORE_CODE VARCHAR(50) NOT NULL, ... .. [#] 管理カラムのカラム名は `データベースノード用ThunderGate設定ファイル`_ の `管理カラム設定`_ により変更することができます。ここでは標準のカラム名を記載しています。 管理カラムの更新 ~~~~~~~~~~~~~~~~ 管理カラムの値は、ThunderGateと連携するバッチアプリケーションとオンラインアプリケーションの排他制御に利用することを想定しています [#]_ 。 ThunderGateはジョブフローの実行時に、エクスポート対象となる業務テーブルの管理カラムに対して以下の通りに更新を行います。 .. list-table:: 管理カラムの更新 :widths: 2 4 4 :header-rows: 1 * - 名前 - 登録時 - 更新時 * - バージョン番号 - 規定のデフォルト値 ``1`` を設定 - インポート時の値をインクリメント * - 登録日時 - データベースノードのシステム日付を設定 - 更新しない * - 更新日時 - データベースノードのシステム日付を設定 - データベースノードのシステム日付を設定 管理カラムの値はThunderGateによって更新されるため、バッチアプリケーションの演算子によってデータモデル上の管理カラムの値を編集しないようにしてください。 .. warning:: 特にシステムSIDを演算子の中で更新すると、エクスポート処理が意図しない結果になる可能性があるので注意してください。 .. [#] 詳しくは `オンラインアプリケーションとの連携`_ を参照してください。 管理テーブル ------------ 管理テーブルはThunderGateが業務テーブルに対する処理を制御するための管理情報を保持するテーブルです。ThunderGateがデータ入出力を行う業務テーブルは、一部の例外を除きThunderGateが定める以下の管理テーブルを持つ必要があります。 .. list-table:: 管理テーブル :widths: 3 3 4 :header-rows: 1 * - 名前 - テーブル名 - 説明 * - `ロック済みレコードテーブル`_ - ``<業務テーブル名>_RL`` [#]_ - レコードロックの情報を保持する .. [#] 例えば、業務テーブル ``SALES_DETAIL`` に対しては、管理テーブル ``SALES_DETAIL_RL`` というテーブルを作成します。 ロック済みレコードテーブル ~~~~~~~~~~~~~~~~~~~~~~~~~~ ロック済みレコードテーブルは、レコードロックの情報を保持する管理テーブルです。ロック済みレコードテーブルのテーブル定義を以下に示します。 .. list-table:: ロック済みレコードテーブル :widths: 15 15 15 10 30 :header-rows: 1 * - 名前 - カラム名 - 必要な制約等 - データ型 - 説明 * - システムID - ``SID`` - ユニークインデックス - ``BIGINT`` - 業務テーブルの管理カラムのSIDを保持する * - ジョブフローSID - ``JOBFLOW_SID`` - - ``BIGINT`` - ``SID`` に対応する、レコードをロックしている実行ID(ジョブフロー実行ID) [#]_ を特定するためのID [#]_ 。 以下に業務テーブルに対応するロック済みレコードテーブルのDDLスクリプト例を示します。 .. code-block:: sql CREATE TABLE SALES_DETAIL_RL ( SID BIGINT PRIMARY KEY , JOBFLOW_SID BIGINT NULL ) ENGINE=InnoDB; .. [#] 実行IDはジョブフローの実行ごとのIDです。詳しくは :doc:`../yaess/user-guide` の実行IDの説明を参照してください。ThunderGateでは実行IDを「ジョブフロー実行ID」という名前で使用しており、ログメッセージなどにはジョブフロー実行IDというメッセージが出力されます。 YAESSを使用している場合は実行IDの値がジョブフロー実行IDと同一になります。 .. [#] ジョブフローSIDから実行ID（ジョブフロー実行ID）を特定するには、後述する `システムテーブル`_ の1つであるジョブフロー実行テーブル (``RUNNING_JOBFLOWS``) テーブルを参照します。ジョブフロー実行テーブルに対してジョブフローSIDを条件として検索を行うことでこのテーブルのレコードを一意に特定出来ます。詳しくは後述の `ジョブフロー実行テーブル`_ を参照してください。 .. _generate-thundergate-management-table: 管理テーブル用DDLスクリプトの生成 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Gradleプロジェクトテンプレートから作成したプロジェクトでは、先述の `業務テーブルに対応するデータモデルクラスの作成`_ に従って Gradleの ``compileDMDL`` タスクを実行すると、業務テーブルに対応する管理テーブル用DDLスクリプトが ``target/sql`` 配下に生成され [#]_ 、開発環境用のデータベースに対してこのSQLが実行されます。 ThunderGateが要求するテーブルが自動的に作成されるため、テストドライバーを使ったテストがすぐに行える状態になります。また、このDDLスクリプトを利用して運用環境の構築を行うことができます。 .. [#] 生成の対象とする管理テーブルのフィルタリングやDDLスクリプトの出力ディレクトリパス ``build.properties`` によって設定可能です。詳しくは :doc:`../application/maven-archetype` の ビルド定義ファイルの項を参照してください。 重複エラーテーブル ------------------ ThunderGateの重複チェック機能 [#]_ を利用する場合に利用するテーブルです。重複チェックを実行結果として重複したレコードが登録されます。バッチアプリケーションが重複チェック機能を利用する場合は、DSLの記述に対応した重複エラーテーブルを用意する必要があります。 重複エラーテーブルは以下のカラムを持つ必要があります。 .. list-table:: 重複エラーテーブルに必要なカラム :widths: 15 20 20 20 :header-rows: 1 * - 名前 - カラム名 - データ型 - 説明 * - 登録日時 - ``RGST_DATETIME`` [#]_ - ``DATETIME`` - レコードの登録日時 * - 更新日時 - ``UPDT_DATETIME`` [#]_ - ``DATETIME`` - レコードの更新日時 * - エラーコード - 任意のカラム名 [#]_ - ``CHAR`` または ``VARCHAR`` - エラーコード .. [#] 重複チェック機能について、詳しくは :doc:`with-dsl` の :ref:`thundergate-dup-check` を参照してください。 .. [#] 業務テーブルと同じ管理カラム名。設定でカラム名を変更している場合は、それに合わせたカラム名を定義してください。 .. [#] 業務テーブルと同じ管理カラム名。設定でカラム名を変更している場合は、それに合わせたカラム名を定義してください。 .. [#] エラーコードのカラム名はAsakusa DSLのジョブフロー記述に設定したエラーコードのカラム名に合わせて定義してください。 システムテーブル ---------------- ThunderGateが利用する、ThunderGateの動作を制御するテーブルです。バッチアプリケーションからはこのテーブルを利用しませんが、システムThunderGateを利用した環境を構築する際に、一部のシステムテーブルに対して業務テーブルの内容に応じたレコードをセットする必要があります。 また、運用時に実行中のジョブフローのロック状態を確認する際にシステムテーブルを参照することができます。 .. _maintain-lock-table: ロック管理テーブルのメンテナンス ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ システムテーブルのうち、テーブルロック管理テーブル (``IMPORT_TABLE_LOCK``) はThunderGateの処理対象となる業務テーブルのテーブル名をレコードとして保持する必要があります。 このテーブルをメンテナンスするためのSQLスクリプトがAsakusa Frameworkインストールディレクトリ配下の ``$ASAKUSA_HOME/bulkloader/sql/insert_import_table_lock.sql`` に配置されています。このスクリプトを実行することで、テーブルロック管理テーブルに必要なレコードが登録されるようになっています。 開発環境については、Gradleプロジェクトテンプレートから作成したプロジェクトでは、先述の `業務テーブルに対応するデータモデルクラスの作成`_ に従って Gradleの ``compileDMDL`` フェーズを実行すると、このSQLスクリプトが合わせて実行されるため、プロジェクト管理下の業務テーブルの情報については自動的にテーブルロック管理テーブルに反映されるようになっています。 運用環境については、テーブルロック管理テーブルを手動でメンテナンスする必要があります。ThunderGateが処理対象となる業務テーブルが追加になり、運用環境のデータベースに業務テーブルが追加されたタイミングで、合わせてこのSQLスクリプトを実行するようにしてください。 ジョブフロー実行テーブル ~~~~~~~~~~~~~~~~~~~~~~~~ ジョブフロー実行テーブルはThunderGateと連携したバッチアプリケーションのジョブフローの実行状態を管理するテーブルです。後述する `オンラインアプリケーションとの連携`_ で説明する各システムテーブルの情報と合わせてジョブフローの実行状態を確認するために使用します。 ジョブフロー実行テーブルのテーブル定義を以下に示します。 .. list-table:: ジョブフロー実行テーブル :widths: 15 20 10 30 :header-rows: 1 * - 名前 - カラム名 - データ型 - 説明 * - ジョブフローSID - ``JOBFLOW_SID`` - ``BIGINT`` - 実行中のジョブフローのジョブフローSID * - バッチID - ``BATCH_ID`` - ``VARCHAR`` - 実行中のジョブフローのバッチID * - フローID - ``JOBFLOW_ID`` - ``VARCHAR`` - 実行中のジョブフローのフローID * - ターゲット名 - ``TARGET_NAME`` - ``VARCHAR`` - 実行中のジョブフローのターゲット名 * - ジョブフロー実行ID - ``EXECUTION_ID`` - ``VARCHAR`` - 実行中のジョブフローのジョブフロー実行ID * - 終了予定日時 - ``EXPECTED_COMPLETION_DATETIME`` - ``DATETIME`` - 実行中のジョブフローの終了予定時刻 [#]_ .. [#] バージョン |version| では未使用のため、ダミーの値を固定で挿入しています。 アプリケーションの開発 ====================== 以降ではアプリケーションの開発における、ThunderGate特有の部分について紹介します。 なお、以降の機能を利用するには次のライブラリやプラグインが必要です [#]_ 。 .. list-table:: ThunderGateで利用するライブラリ等 :widths: 50 50 :header-rows: 1 * - ライブラリ - 概要 * - ``asakusa-thundergate-vocabulary`` - DSL用のクラス群 * - ``asakusa-thundergate-plugin`` - DSLコンパイラプラグイン * - ``asakusa-thundergate-test-moderator`` - テストドライバープラグイン * - ``asakusa-thundergate-dmdl`` - DMDLコンパイラプラグイン .. [#] アーキタイプ ``asakusa-archetype-thundergate`` から作成したプロジェクトは、これらのライブラリやプラグインがSDKアーティファクトという依存性定義によってデフォルトで利用可能になっています。詳しくは :doc:`../application/maven-archetype` や :doc:`../application/sdk-artifact` を参照してください。 また、またテーブルやビューのDDLスクリプトからDMDLスクリプトを生成する機能を使う場合は、 以下のライブラリも必要です。 .. list-table:: ThunderGateのDDL-DMDL連携機能で利用するライブラリ等 :widths: 50 50 :header-rows: 1 * - ライブラリ - 概要 * - ``asakusa-regacy-test-driver`` - レガシーテストドライバープラグイン データモデルクラスの生成 ------------------------ データモデルクラスを作成するには、データモデルの定義情報を記述後にGradleの ``compileDMDL`` タスクを実行します。 ThunderGateではモデルをDMDLで記述するほかにThunderGate特有の機能として、ThunderGateが入出力に利用するデータベースのテーブル定義情報を記述したDDLスクリプトや、結合や集計を定義した専用のビュー定義情報を記述したDDLスクリプトから対応するDMDLスクリプトを生成出来るようになっています。 DMDLスクリプト [#]_ はプロジェクトの ``src/main/dmdl`` ディレクトリ [#]_ 以下に配置し、スクリプトのファイル名には ``.dmdl`` の拡張子を付けて保存します。 DMDLの記述方法については :doc:`../dmdl/start-guide` などを参考にしてください。 またテーブルやビューのDDLスクリプトからDMDLスクリプトを生成する機能を使う場合、DDLスクリプトはプロジェクトの ``src/main/sql/modelgen`` ディレクトリ以下に配置し、DDLスクリプトのファイル名には ``.sql`` の拡張子を付けて保存します。 DDLスクリプトは Gradleの ``compileDMDL`` タスク実行時に一時的にDMDLスクリプトに変換され [#]_ 、続けて ``src/main/dmdl`` 配下のDMDLと合わせてデータモデルクラスを生成します。 DDLスクリプトの記述方法については :doc:`with-dmdl` を参照してください。 .. [#] ここで説明しているDMDLスクリプトはDDLスクリプトから生成するDMDLスクリプトではなく、DMDLスクリプトを一から記述する場合です。 .. [#] ディレクトリはプロジェクトの設定ファイル ``build.properties`` で変更可能です。 .. [#] 一時的に出力されるDMDLスクリプトは、 ``target/dmdl`` ディレクトリ以下に出力されます。このディレクトリはプロジェクトの設定ファイル ``build.properties`` で変更可能です。 Asakusa DSLの記述 ----------------- ThunderGateを利用する場合でも、Asakusa DSLの基本的な記述方法は同様です。 ThunderGate特有の部分は、ThunderGateとの連携を定義するジョブフロー記述の部分になります。ここではRDBMSのテーブルに対する入出力の抽出条件や使用するロックの種類などを定義します。詳しくは :doc:`with-dsl` を参照してください。 それ以外の部分については、 :doc:`../dsl/start-guide` などを参照してください。 アプリケーションのテスト ------------------------ Asakusa DSLの記述と同様、アプリケーションのテストについても基本的な方法は同じで、テストドライバーを利用することが出来ます。 ThunderGateはRDBMSに対してデータの入出力を行うため、ジョブフローのテストについてはテストドライバー側でテストデータ定義に基づいてRDBMSに対する初期データの投入や結果の取得が行われます。ThunderGateと連携したアプリケーションのテストについて詳しくは :doc:`with-testing` を参照してください。 それ以外の部分については、 :doc:`../testing/start-guide` などを参照してください。 アプリケーションの運用 ====================== 以降ではアプリケーションの運用における、ThunderGate特有の部分について紹介します。 運用環境の構築 -------------- 運用環境の構築についての基本的な内容は、 :doc:`../administration/deployment-guide` 及び :doc:`../administration/deployment-architecture` を参照してください。 ここでは、ThunderGateのデプロイに特有の部分について説明します。 ThunderGate用テンポラリディレクトリの作成 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ データベースノードのマシン上では、ThunderGate用の設定に従って インポータ、エクスポータ処理用のテンポラリテーブルを作成する必要があります。 上述の `データベースノード用ThunderGate設定ファイル`_ に設定した以下のプロパティの値を確認します。 * ``import.tsv-create-dir`` * ``export.tsv-create-dir`` 上記の2プロパティに指定したテンポラリ用ディレクトリを作成します。これらのディレクトリのパーミッションはバッチアプリケーションの実行ユーザーとMySQL実行ユーザーの両ユーザーが読み込み、書き込み可能な権限を設定します。 以下設定例です。 .. code-block:: sh mkdir -p -m 777 /var/tmp/asakusa/importer mkdir -p -m 777 /var/tmp/asakusa/exporter chown -R mysql:mysql /var/tmp/asakusa .. attention:: ``import.tsv-create-dir``, ``export.tsv-create-dir`` のデフォルトの設定は ``/tmp`` 配下に設定されていますが、一部のOSでは ``/tmp`` 配下は再起動時にクリアされるため、必要に応じて設定を変更してください。 バッチアプリケーション用テーブルの作成 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ バッチアプリケーションが使用する業務テーブルと管理テーブルをMySQLに登録します。 業務テーブルや管理テーブルについては先述の `テーブル定義`_ を参照してください。 ロック管理テーブルのレコード登録 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ バッチアプリケーション用のテーブルをMySQLに登録後、ロック管理テーブルに対して業務テーブルのテーブル名を登録します。 ロック管理テーブルとそのメンテナンスについて詳しくは後述の `ロック管理テーブルのメンテナンス`_ を参照してください。 以下手順例です。 .. code-block:: sh cd $ASAKUSA_HOME/bulkloader/sql mysql -u appuser -pappuser -D appdb < insert_import_table_lock.sql なお、アプリケーションの変更に伴い業務テーブルに追加になった場合には、先述の `バッチアプリケーション用テーブルの作成`_ を再度実行するとともに、ロック管理テーブルのレコード登録も再度実行する必要があります。この場合、ロック管理テーブルの古いレコード情報を削除してから、ロック管理テーブルのレコードを再登録してください。以下手順例です。 .. code-block:: sh cd $ASAKUSA_HOME/bulkloader/sql mysql -u appuser -pappuser -D appdb < delete_import_table_lock.sql mysql -u appuser -pappuser -D appdb < insert_import_table_lock.sql トランザクションのメンテナンス ------------------------------ ジョブフローの実行が異常終了した場合などの場合、実行したジョブフローに対してロールバック、もしくはロールフォワードを実行してトランザクションの整合性を保つ必要があります。 リカバラによるトランザクションの整合性維持 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ThunderGateではトランザクションの整合性維持のためにリカバラというツールを提供しています。 リカバラはThunderGateの実行状況をThunderGateのシステムテーブルや管理テーブルから判断し、必要に応じてロールバック、またはロールフォワードを実行します。 ThunderGateと連携したバッチアプリケーションを :doc:`YAESS <../yaess/index>` 経由で実行した場合、リカバラはYAESSの ``finalize`` フェーズで実行されるようになっています。この動作によりジョブフローが異常終了した場合、バッチアプリケーションは自動的にトランザクションの整合性を回復するよう試みます [#]_ 。 ただし、YAESS自体が正常に動作せず上記の異常終了シーケンスが実行されなかった場合など、なにかしらの原因によりリカバラが正常に実行されなかった場合についてはトランザクションが中断された状態になります。このような状態になった場合、手動でトランザクションを修復する必要があります。 .. [#] YAESSのフェーズなどについて詳しくは :doc:`../yaess/user-guide` を参照してください。 手動によるでトランザクション修復 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ThunderGateでは、ジョブフローが異常終了した場合に手動でトランザクションを修復する方法として、以下の2つの方法を提供しています。 1. リカバラを単体のコマンドとして実行する 2. DBクリーナーコマンドを実行する リカバラを単体のコマンドとして実行する ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ リカバラはYAESSなどのワークフローエンジンと連携して自動で実行するほか、手動で実行することも可能にになっています。リカバラを手動で実行するには ``$ASAKUSA_HOME/bulkloader/bin/recoverer.sh`` コマンドを実行します。 以下の形式で指定します。 .. code-block:: sh $ASAKUSA_HOME/bulkloader/bin/recoverer.sh <ターゲット名> <ジョブフロー実行ID> コマンドに指定可能な引数は以下のとおりです。 ``<ターゲット名>`` 対象のデータソースのターゲット ``<ジョブフロー実行ID>`` 対象となるジョブフローのジョブフロー実行ID。この引数を省略した場合、異常終了または中断したと判断されたすべてのジョブフローインスタンスに対してロールバック、またはロールフォワードが試行される。 実行結果はThunderGateのログに出力されるので、内容を確認してください。 DBクリーナーコマンドを実行する ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ なにかしらの原因でThunderGateの管理情報に不整合が発生し、リカバラを実行しても環境が回復しない場合は、ThunderGateのシステムテーブルや管理テーブルを初期化するためのDBクリーナーコマンドを利用することが出来ます。このコマンドを実行すると、以下の処理が行われます。 * ThunderGateのシステムテーブルを初期化 * 業務テーブルに関連する管理カラム、管理テーブルの内容を初期化 * ThunderGateが処理中のテンポラリテーブルが残っていた場合はこれらを全て削除 .. warning:: DBクリーナーはコマンド実行時に中断しているトランザクションが存在した場合でも、その修復を試みないで環境の初期化が行うため、データの一貫性が損なわれる可能性があります。 またコマンド実行時に正常に処理が進行しているジョブフローが存在した場合、DBクリーナーの実行が原因で処理が中断してしまうため、DBクリーナーの利用は注意が必要です。 DBクリーナーは ``$ASAKUSA_HOME/bulkloader/bin/dbcleaner.sh`` コマンドを実行します。 以下の形式で指定します。 .. code-block:: sh $ASAKUSA_HOME/bulkloader/bin/dbcleaner.sh <ターゲット名> コマンドに指定可能な引数は以下のとおりです。 ``<ターゲット名>`` 対象のデータソースのターゲット オンラインアプリケーションとの連携 ================================== ここでは、ThunderGateと連携したバッチアプリケーション (以下「バッチアプリケーション」) とオンラインアプリケーションが同じ業務テーブルに対して処理を行う場合に考慮すべき点を説明します。 ある業務テーブルに対してオンラインアプリケーションが参照または更新を行う際に、データの整合性を確保するためにバッチアプリケーションがその業務テーブル、または業務テーブル中のレコードに対して処理中であるか、または更新済みであるかを確認する必要があるかもしれません。 ThunderGateはオンラインアプリケーションとの連携を行うにあたって、以下の情報を提供します。 1. 業務テーブルに対するテーブルロック 2. 業務テーブルのレコードに対するレコードロック 3. 業務テーブルのレコードに対するバージョン情報 4. 業務テーブルのレコードに対する登録日時と更新日時 以下、それぞれについて説明します。 .. attention:: ThunderGateと連携したバッチアプリケーションが取得できるロックの種類とロック取得方法については、 :doc:`with-dsl` のインポート記述の説明を参照してください。 業務テーブルに対するテーブルロック ---------------------------------- バッチアプリケーションが業務テーブルに対してテーブルロックを取得しているかどうかは、テーブルロックの情報の保持するシステムテーブル「テーブルロック管理テーブル」( ``IMPORT_TABLE_LOCK`` ) を確認します。 テーブルロック管理テーブル ``IMPORT_TABLE_LOCK`` のテーブル定義を以下に示します。 .. list-table:: テーブルロック管理テーブル: ``IMPORT_TABLE_LOCK`` :widths: 2 1 1 1 5 :header-rows: 1 * - 名前 - カラム名 - 制約 - データ型 - 説明 * - テーブル名 - ``TABLE_NAME`` - 主キー - ``VARCHAR`` - ロック対象のテーブル名 * - ジョブフローSID - ``JOBFLOW_SID`` - - ``BIGINT`` - ロック対象のジョブフローSID。 ``NULL`` はロックが取得されていないことを表す。 このテーブルにはあらかじめThunderGateが扱う業務テーブル毎にレコードが登録されています [#]_ 。ジョブフローSIDカラムの初期値は ``NULL`` です。バッチアプリケーションがテーブルロックを取得した場合、該当テーブル名のレコードに対してジョブフローSIDカラムを実行中のジョブフローのジョブフローSIDで更新し、処理が完了したら ``NULL`` で更新してロックを解除します。 オンラインアプリケーションは、テーブル名を条件としてレコードを検索し、取得されたレコードのジョブフローSIDカラムの値を確認することでテーブルロックが行われているかを確認することができます。 .. [#] このため、バッチアプリケーションのアップデートなどにより扱う業務テーブルが増えた場合は、テーブルロック管理テーブルにも合わせてレコードを追加する必要があります。詳しくは先述の `ロック管理テーブルのメンテナンス`_ を参照してください。 業務テーブルに対するレコードロック ---------------------------------- バッチアプリケーションが業務テーブルに対してレコードロックを取得しているかどうかは、以下の2つの方法で確認できます。 1. レコードロックが行われているテーブルの情報を保持するシステムテーブル「レコードロック管理テーブル」( ``IMPORT_RECORD_LOCK`` ) を確認する。 2. レコードロックが行われているレコードの情報を保持する管理テーブル「ロック済みレコードテーブル」( ``<業務テーブル>_RL`` ) を確認する。 テーブル単位でレコードロックを確認したい場合は 1. のレコードロック管理テーブルを、レコード単位でレコードロックを確認したい場合は 2. のロック済みレコードテーブルを確認します。 レコードロック管理テーブル ~~~~~~~~~~~~~~~~~~~~~~~~~~ レコードロック管理テーブル ``IMPORT_RECORD_LOCK`` はレコードロックが行われているテーブルの情報を保持します。レコードロック管理テーブル ``IMPORT_RECORD_LOCK`` のテーブル定義を以下に示します。 .. list-table:: レコードロック管理テーブル: ``IMPORT_RECORD_LOCK`` :widths: 2 1 1 1 5 :header-rows: 1 * - 名前 - カラム名 - 制約 - データ型 - 説明 * - ジョブフローSID - ``JOBFLOW_SID`` - 主キー - ``BIGINT`` - ロック対象のジョブフローSID。 * - テーブル名 - ``TABLE_NAME`` - - ``VARCHAR`` - ロック対象のテーブル名 このテーブルには初期時にはレコードが登録されていません。バッチアプリケーションがテーブルロックを取得した場合、該当テーブル名のテーブルと実行中のジョブフローSIDを持つレコードを登録し、処理が完了したら該当レコードを削除してロックを解除します。 オンラインアプリケーションは、テーブル名を条件としてレコードを検索し、該当のレコードが存在するかを確認することでレコードロックが行われているかを確認することができます。 ロック済みレコードテーブルによるレコードロックの確認 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ロック済みレコードテーブルの定義については、先述の `ロック済みレコードテーブル`_ を確認してください。 このテーブルには初期時にはレコードが登録されていません。バッチアプリケーションがレコードロックを取得した場合、該当レコードのシステムSIDと実行中のジョブフローSIDを持つレコードを登録し、処理が完了したら該当レコードを削除してロックを解除します。 オンラインアプリケーションは、業務テーブルに対応するロック済みレコードからシステムSIDを条件としてレコードを検索し、該当のレコードが存在するかを確認することでレコードロックが行われているかを確認することができます。 バージョン情報によるレコード更新の確認 -------------------------------------- 業務テーブルの `管理カラム`_ に含まれるバージョン番号は、バッチアプリケーションが該当レコードをエクスポートする際に、エクスポート対象の業務テーブルが持つ値に対してインクリメント (値を1加算） [#]_ して更新します。 オンラインアプリケーションはバージョン番号を参照して、オンラインアプリケーションがある時点で参照したデータが更新時にバッチアプリケーションで更新されていないかを確認することができます。 .. attention:: バージョン番号はエクスポート時に業務テーブルのレコードの値が実際に更新されているかいないかに関わらず値がインクリメントされます。 .. [#] インポート時の値ではなく、エクスポート時のレコードの値に対してインクリメントされます。 登録日時と更新日時によるレコード更新の確認 ------------------------------------------ 業務テーブルの `管理カラム`_ に含まれる登録日時と更新日時は、バッチアプリケーションが該当レコードをエクスポートする際に、それぞれの値が更新されます。詳しくは、 `管理カラムの更新`_ を参照してください。 `バージョン情報によるレコード更新の確認`_ と同様に、オンラインアプリケーションはこれらの値を参照して、オンラインアプリケーションがある時点で参照したデータが更新時にバッチアプリケーションで更新されていないかを確認することができます。