残留トランザクション状態をパージする

注記

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

ScalarDL Ledger と Auditor を使用する際、各トランザクションはトランザクション状態を生成します。ScalarDL はこの状態を使用してトランザクションを処理し、必要に応じて回復します。トランザクションがこの目的を完全に果たした後、それが残す状態 (残留トランザクション状態) は、ScalarDL の動作にはもはや必要なく、パージできます。ScalarDL はデフォルトではこの状態をパージしないため、時間の経過とともに蓄積してストレージを消費します。このガイドでは、残留トランザクション状態とは何か、いつパージできるか、そして利用可能な1つ以上のパージオプションを使用してどのようにパージするかについて説明します。

残留トランザクション状態は、以下で構成されます。

• Coordinator state レコード: ScalarDB が Ledger 側の Coordinator テーブルで管理するトランザクション状態レコード。
• Request proof: Auditor がビザンチン故障を検知するために各クライアントリクエストについて保存するレコード。

残留トランザクション状態をパージする理由

残留トランザクション状態は、トランザクションが処理され、必要に応じて回復される間、特定の役割を果たすために存在します。

• Coordinator state レコードは、トランザクションの最終結果 (コミットまたはアボート) を決定します。ScalarDL は、途中で発生した障害から回復する場合を含め、トランザクションを一貫して確定するためにこれに依存します。
• Request proof は、正常に完了しなかったトランザクションを ScalarDL が回復し、ビザンチン故障を検知できるようにします。

トランザクションが確定され、回復する必要がなくなると、この状態は役割を果たしたことになり、ScalarDL の動作にはもはや必要ありません。パージによってこれを回収することで、Coordinator テーブルと Auditor の request proof テーブルが際限なく増大しないようにします。ScalarDL はデフォルトではこの状態をパージしないため、時間の経過とともに蓄積してストレージを消費します。

残留トランザクション状態を保持する主な理由は、各トランザクションがどのように確定されたかの記録を残すことです。タイムアウトや接続の失敗などによってリクエストの結果がクライアントに届かなかった場合、そのトランザクションがコミットされたかアボートされたかは Coordinator state レコードに保持されているため、後から結果を判別できます。

運用上、トランザクションの結果を後から判別できる必要がある場合は、自動パージを無効にしたままにし、それらの結果が不要になった時点で手動パージを使用してください。そうでない場合は、ScalarDL に自動的にパージさせることができます。

警告

Request proof をパージすると、リプレイされたリクエストを検知するために ScalarDL が使用する情報も削除されます。中間者がコントラクト実行リクエストを傍受し、その request proof がパージされた後に再実行した場合、ScalarDL はそのリプレイを検知できなくなります。これを防ぐため、クライアント、Ledger、Auditor 間のすべての通信経路を TLS で保護することを強くお勧めします。TLS の設定の詳細については、ScalarDL の設定を参照してください。

前提条件

残留トランザクション状態をパージする前に、以下が満たされていることを確認してください。

• アプリケーションを Ledger と Auditor を通じて実行していること。パージは Ledger のみの構成ではサポートされていません。この環境をまだセットアップしていない場合は、ScalarDL Ledger と Auditor を通じて ScalarDL アプリケーションを実行するを参照してください。
• Ledger と Auditor の両方のスキーマがパージをサポートしていること。スキーマの準備方法については、パージ用のデータベーススキーマの準備を参照してください。

パージ用のデータベーススキーマの準備

パージを使用するには、Ledger と Auditor の両方のスキーマがパージに対応している必要があります。パージをサポートするバージョンの ScalarDL (ScalarDL 3.14.0 以降) で作成されたスキーマは、すでにパージに対応しています。スキーマを準備するには、そのようなバージョンの ScalarDL Schema Loader を使用します。その方法は、新しいスキーマを作成するか、既存のスキーマをアップグレードするかによって異なります。

新規デプロイの場合

ScalarDL Ledger と Auditor を通じて ScalarDL アプリケーションを実行するで説明されているようにスキーマをロードします。Ledger スキーマをロードする際、Ledger の Schema Loader のプロパティファイルに次の内容を追加して write-set ロギングを有効にします。

scalar.db.consensus_commit.coordinator.write_set_logging.enabled=true

Auditor スキーマをロードする際に追加のオプションは必要ありません。

既存デプロイの場合

デプロイがパージをサポートしないバージョンの ScalarDL (ScalarDL 3.14.0 より前のバージョン) でセットアップされている場合は、パージをサポートするバージョンの ScalarDL Schema Loader を使用してスキーマをアップグレードします。以下の手順はその一例を示しています。

1. Ledger の Schema Loader のプロパティファイルに次の内容を追加して、Coordinator テーブルの write-set ロギングを有効にします。

   scalar.db.consensus_commit.coordinator.write_set_logging.enabled=true

2. Ledger のスキーマをアップグレードします。

   docker run --rm \
     -v <PROPERTIES_FILE_PATH>:/scalardl-schema-loader/database.properties \
     ghcr.io/scalar-labs/scalardl-schema-loader:<VERSION> \
     --config database.properties --coordinator --repair-all

3. パージに必要だがまだ存在しない Auditor のテーブルを作成します。

   docker run --rm --env SCHEMA_TYPE=auditor \
     -v <PROPERTIES_FILE_PATH>:/scalardl-schema-loader/database.properties \
     ghcr.io/scalar-labs/scalardl-schema-loader:<VERSION> \
     --config database.properties

   オプションを指定せずに Schema Loader を実行すると、まだ存在しないテーブルのみが作成され、既存のテーブルはそのまま維持されます。

4. Auditor のスキーマをアップグレードします。

   docker run --rm --env SCHEMA_TYPE=auditor \
     -v <PROPERTIES_FILE_PATH>:/scalardl-schema-loader/database.properties \
     ghcr.io/scalar-labs/scalardl-schema-loader:<VERSION> \
     --config database.properties --alter

   この手順は必ず前の手順の後に実行してください。--alter オプションは既存のテーブルにカラムを追加するだけであり、スキーマ内にまだ存在しないテーブルがある場合は失敗します。

スキーマをアップグレードしても、またパージを有効にしても、すでに蓄積されている残留トランザクション状態は削除されません。そのような状態にはパージが必要とする情報が欠けているため、どのパージオプションでも削除できず、cleanup tool でのみ削除できます。したがって、既存のデプロイでは次の順序を推奨します。

1. パージオプションの説明に従って、Ledger と Auditor の両方でパージを有効にし、完了時パージを有効にします。これ以降のトランザクションは残留状態を残さなくなります。完了時パージは各トランザクションの完了時に個別に動作するため、すでに蓄積されている状態の影響を受けません。トランザクションの結果を後から判別できる必要がある場合は、完了時パージを無効にしたままにし、手動パージを使用してください。詳細は残留トランザクション状態をパージする理由を参照してください。
2. cleanup tool を使用して、すでに蓄積されている状態を削除します。
3. 必要に応じて、定期パージを有効にするか、手動パージを実行します。

すでに蓄積されている状態を cleanup tool で削除するまでは、定期パージの有効化や手動パージの実行は推奨されません。どちらも request proof をスキャンする方式であり、1回の実行で処理するレコード数には上限があります。cleanup tool でしか削除できない状態が大量に残っている間は、1回の実行が削除できないレコードだけで埋まり、パージがほとんど、あるいはまったく進みません。Auditor は、1回の実行で参照したレコードの大半がそのようなレコードだった場合に警告をログに出力するため、この状況に気づいて対処できます。

完了時パージはベストエフォートであるため、最初の手順の後もわずかな残留状態が残ることがあります。最後の手順の定期パージがそれを回収します。

備考

現時点で cleanup tool がサポートするバックエンドデータベースは Azure Cosmos DB for NoSQL のみであり、マルチストレージ構成には対応していません。

既存の残留トランザクション状態をパージするために cleanup tool を使用したい場合は、サポートにお問い合わせください。

パージオプション

ScalarDL は、組み合わせて使用できる3つのパージオプションを提供します。いずれかを使用するには、以下のマスタースイッチを両方とも true に設定して、Ledger と Auditor の両方でパージを有効にする必要があります (どちらもデフォルトは false)。

• Ledger の設定内の scalar.dl.ledger.transaction_state_purge.enabled
• Auditor の設定内の scalar.dl.auditor.transaction_state_purge.enabled

パージが無効になっている間、ScalarDL はいかなる状態もパージせず、手動パージのリクエストは拒否されます。どのオプションを使用するかは、このセクションで説明する Auditor の追加設定で選択します。

次の表にオプションをまとめます。

オプション	トリガー方法	有効化する設定	一般的な用途
完了時パージ	自動的に、各トランザクションの完了直後	scalar.dl.auditor.transaction_state_purge.on_completion.enabled	通常運用中に残留状態を最小限に抑える。
定期パージ	自動的に、定期的なバックグラウンドスキャンとして	scalar.dl.auditor.transaction_state_purge.scan.interval_secs (> 0)	完了時パージが削除しなかった状態 (たとえば障害後) を回収する。
手動パージ	オンデマンドで、purge-state コマンドを実行したとき	マスタースイッチのみ (パージが有効な場合はいつでも利用可能)	自動パージが無効な状態で、任意のタイミングで削除する (たとえば、トランザクションの結果を判別する必要がなくなった時点)。

注記

これらの設定は起動時にのみ読み込まれるため、変更を反映するには Ledger と Auditor を再起動する必要があります。

完了時パージ

完了時パージは、各トランザクションの完了 (コミットまたはアボート) 直後、そのロックが解放された後に、そのトランザクションの残留状態を非同期に削除します。これにより、通常運用中に残留状態を最小限に抑えます。

完了時パージを有効にするには、マスタースイッチに加えて、Auditor の設定で scalar.dl.auditor.transaction_state_purge.on_completion.enabled を true に設定します。

完了時パージはベストエフォートです。一部の状態の削除に失敗した場合、その状態は定期パージまたは手動パージによって処理されるまで残ります。

定期パージ

定期パージは、バックグラウンドで request proof を定期的にスキャンし、完了したトランザクションの残留状態をパージします。まだ進行中のトランザクションや完了したばかりのトランザクションの状態を削除しないように、スキャンは短い猶予期間内に完了したトランザクションをスキップします。定期パージは、完了時パージが削除しなかった状態を回収するのに役立ちます。

定期パージを有効にするには、マスタースイッチに加えて、Auditor の設定で scalar.dl.auditor.transaction_state_purge.scan.interval_secs をスキャン間隔 (秒単位、0 より大きい値) に設定します。

scalar.dl.auditor.transaction_state_purge.scan.limit を設定することで、1回のスキャンで処理するレコード数を制限することもできます。

注記

複数の Auditor ノードをデプロイする場合、冗長なスキャンを避けるため、定期パージは一度に1つのノードでのみ実行されます。

既存のデプロイでは、すでに存在する残留トランザクション状態を cleanup tool で削除するまで、定期パージを有効にしないでください。詳細は既存デプロイの場合を参照してください。

手動パージ

手動パージを使用すると、ScalarDL に自動的に削除させる代わりに、任意のタイミングで残留トランザクション状態を削除できます。これは、トランザクションの結果を後から判別できる必要がある場合に適しています。完了時パージと定期パージの両方を無効にしておくことで、状態が自動的に削除されないようにし、状態が不要になった時点で手動パージを実行します。手動パージは定期パージと同じスキャンベースのクリーンアップを実行し、結果のサマリーを返します。

手動パージは、マスタースイッチが有効になっている場合は、完了時パージと定期パージが無効であってもいつでも利用できます。実行するには、scalardl purge-state コマンドを使用します。

scalardl purge-state --properties client.properties

このコマンドは、対象となったトランザクション、パージされたトランザクション、およびスキップされたトランザクションの数を示すサマリーを返します。

{
  "status_code": "OK",
  "output": {
    "total_targets": 5,
    "purged": 4,
    "skipped": 1
  }
}

注記

手動パージには Auditor が有効になっている必要があります。パージが無効な場合、コマンドは拒否されます。

また、手動パージは、スキーマのアップグレード前から存在する残留トランザクション状態を削除できないため、その状態を cleanup tool で削除する前に実行することは推奨されません。詳細は既存デプロイの場合を参照してください。

関連項目

関連する設定とコマンドの詳細については、以下を参照してください。

• ScalarDL の設定
• ScalarDL クライアントコマンドリファレンス