SyncCoordinatorDocumentation

DOCUMENTATION / ARCHITECTURE

Architecture

SyncCoordinatorは、Web、Worker、管理DBの3つで構成されます。Webで設定した内容をWorkerが読み取り、業務DB間を同期します。処理状態は管理DBに保存します。

OVERVIEW

全体構成

SyncCoordinatorは業務システムとは別に配置します。Webは設定と管理、Workerは同期処理、管理DBは設定と処理状態の保存を受け持ちます。

業務システム ASQL Server / MySQL / PostgreSQL既存の業務アプリ・テーブル
SynCo
Web設定・管理
Worker同期・通知
管理DB設定・状態
業務システム BSQL Server / MySQL / PostgreSQL既存の業務アプリ・テーブル
Workerは業務DBの変更を読み取り、マッピングと競合ポリシーに従って送信先へ反映します。

コンポーネントの役割

Coordinator Web

管理画面と管理者認証を提供します。接続先、同期ルール、マッピングの編集と、DB配備用SQLの生成・検証を行います。同期処理は実行しません。

Coordinator Worker

管理DBから設定を読み、変更の取得、競合判定、送信先への適用を繰り返します。Webhook配送と管理DBのクリーンアップも行います。

Coordinator 管理DB

接続情報、同期ルール、マッピングを保存します。Checkpoint、Inbox、Snapshot、競合履歴など、再開に必要な状態もここに残します。

SYNC RULES AND MAPPING

同期ルールとマッピング

同期ルールには、送信元、送信先、方向、競合時の扱いを設定します。テーブルや列の違いは、ルールに紐づくマッピングで指定します。

DIRECTION

片方向と双方向

  • 片方向送信元から送信先への変更だけを処理します。
  • 双方向送信元から同期されたレコードが送信先で更新された場合、その変更を最初の送信元へ戻します。
  • ループ防止最初の発生元と適用済みMessage IDを記録し、SyncCoordinator自身が反映した変更を再送しません。

MAPPING

テーブル・列・値の対応

  • テーブルとキー両端のschema、table、レコードを識別するキー列を指定します。
  • 列と型列の対応、NULL可否、文字列長、数値のprecision／scaleを保存します。
  • 値変換コード値の変換、日時の正規化、方向別の固定値を設定できます。

CONFLICTS AND NOTIFICATIONS

競合と通知

競合の処理と外部通知はWorkerが行います。判定結果と通知の配送状態は管理DBに保存され、管理画面から確認できます。

CONFLICT

競合した場合

  1. 競合を検知前回のSnapshot、受信した値、送信先の現在値を比較します。両側で同じ項目が変更され、値が異なる場合を競合として扱います。
  2. ポリシーを適用同期ルールに従い、受信値を採用する、送信先の値を残す、保留する、マージする、のいずれかを選びます。
  3. 必要なら管理画面で解決保留した競合は管理画面に表示します。選択後、Workerが送信先の値を確認し直してから反映します。

NOTIFICATION

通知の流れ

  1. イベントを保存競合検知や同期エラーが発生すると、通知イベントを管理DBのOutboxへ保存します。
  2. Webhookへ送信WorkerがOutboxを読み、登録済みのWebhookへ非同期で送信します。現在の通知先はWebhookです。
  3. 失敗時は再試行Webhookの配送に失敗した場合は間隔を空けて再試行します。通知の失敗で同期処理は停止しません。

BUSINESS DATABASE BOUNDARY

業務DBへの配備

業務DBには、変更検知と重複適用防止に使う補助オブジェクトを追加します。既存のアプリケーションコード、業務テーブル、業務列は変更しません。

DEPLOYED OBJECTS

  • SyncChangeQueue
  • SyncAppliedMessage
  • SyncEntityOrigin
  • SyncDeleteTombstone
  • SyncCoordinatorDeployment
  • 対象テーブルの変更検知Trigger

UNCHANGED

  • 既存の業務アプリケーション
  • 既存の業務テーブル
  • 既存テーブルの業務列

設定の保存時にはDDLを実行しません。生成されたSQLをDBAが確認・実行し、配備内容の検証が終わってから同期ルールを有効にします。

初期データについて：SyncCoordinatorは配備後の変更を同期します。既存データの一括移行や全件比較は行わないため、同期を有効にする前に別の手段で初期データを揃えてください。

STATE AND RELIABILITY

状態管理と再実行

業務データは各業務DBに残し、同期設定と処理状態はCoordinator管理DBに保存します。Worker自身は永続状態を持たないため、停止しても保存済みの位置から処理を再開できます。

保存場所主な状態役割
Coordinator管理DBSystemDefinition、同期ルール、マッピング、Checkpoint、Inbox、Snapshot、競合・監査・運用履歴設定と処理状態の正本です。Workerは再起動後、この状態を読み直して処理を再開します。
業務DB業務レコード、変更Queue、適用済みMessage、Origin、削除Tombstone、配備ハッシュ現在の業務データと、変更検知・重複適用防止に使う補助状態を保持します。

再起動と再送への対応

Checkpoint

送信元ごとに最後に処理したQueueIdを保存します。処理に失敗した場合、その送信元の位置は進めません。

Inbox・処理リース

配送状態をProcessing、Completed、Held、Failedで保存します。処理中に停止した場合は、リース失効後に同じ配送を取得し直します。

冪等な適用

配送ごとに同じIDを生成し、送信先のSyncAppliedMessageへ記録します。同じ配送が再実行されても二重に反映しません。

SyncChangeQueueは変更後の値そのものではなく、「このレコードが変わった」という通知を保持します。再開時には対象レコードを読み直し、その時点の最新状態を同期します。

IMPLEMENTATION DETAILS

実装の詳細

実装と本番配備に関係する補足です。必要な項目を開いて確認してください。

プロジェクトの依存方向

同期処理はCoreに置きます。Webは業務DB Connectorを直接実行しません。WorkerがCoreを呼び出して同期を進めます。

Contracts ← Core ← Infrastructure ← Worker
                      ↑
                      └──────────── Web

ServiceDefaults ← Worker / Web
AppHost ─────────→ Worker / Web / demo resources
設定変更が反映されるタイミング
  1. 周期開始Workerが処理用のscopeを作ります。
  2. 接続先を取得有効なシステム定義と接続情報を管理DBから読みます。
  3. 同期を実行同じ周期の途中では接続先を切り替えません。
  4. 次周期設定変更はWorkerを再起動せず、次の周期から反映されます。
暗号鍵とDB権限
接続情報の保護

業務DBの接続文字列とWebhookの署名鍵は、Data Protectionで暗号化して管理DBへ保存します。

共有Key Ring

WebとWorkerを別ホストに置く場合は、両方から読める共有Key Ringを用意し、ACLで保護します。

最小権限

Workerが通常運用で使う読書き権限と、補助オブジェクトを作成するDDL権限は分けます。

NEXT

次に読む

OverviewWorkflow