Spanner への移行: Antigravity CLI で二重書き込みを自動化してサービス停止を最小限に

※この投稿は米国時間 2026 年 9 月 5 日に、Google Cloud blog に投稿されたものの抄訳です。

Google のファイナンス エンジニアリング チームは、レガシー データレイヤーをモダナイズする必要が生じた際、グローバルに分散され、強整合性があり、高可用性機能を備えたマルチモデル データベースである Spanner を選択しました。しかし、本番環境サービスをオフラインにせずに Spanner に移行することは、エンジニアリング上の大きな課題でした。アプリケーションを担当する社内チームとして、数十のデータアクセス オブジェクト（DAO）にわたって二重書き込みロジックを手動で書き換える必要がありましたが、このプロセスは時間がかかり、人的エラーが発生しやすいものでした。さらに、サービスを停止することなくこれを行うには、コードベース内のすべての DAO にわたって、マルチフェーズの二重書き込みアーキテクチャを実装する必要がありました。

この課題を解決するために、別のアプローチを採用しました。ヘッドレス モードの Antigravity CLI を利用した自動リファクタリング パイプラインを構築したのです。これにより、本番環境の準備を進めるなか、ステージング環境で厳格なデータパリティを維持しながら、移行速度を大幅に向上させることができました。

課題: 二重書き込みによる移行の仕組み

財務上の正確性が不可欠な高スループットの本番環境サービスを移行する場合、単純なカットオーバー スクリプトは機能しません。過去のデータのバックフィルと検証がすべて完了するまで、レガシー データストアと Spanner の両方が同じ書き込みを同時に受信することを確認する必要があります。

移行は、次の 3 つのフェーズに分けて実施しました。

• 過去のデータのバックフィル: 参照整合性を維持しながら、既存の過去のレコードを Spanner にコピーします。

• 二重書き込み / 二重読み取りの実装: 移行期間中に、すべての DAO を変更して、プライマリ ストアと Cloud Spanner の両方にミューテーションを並行して書き込みます。

• 自動化された API 検証とパリティ チェック: RPC トラフィックをインターセプトし、すべての書き込みが両方のストアでバイト単位で同等に完了することをエンドツーエンドで検証します。

アーキテクチャ パターンはクリーンですが、Google の規模では、摩擦が生じ始めました。これは、各 DAO に以下が必要なためです。

• 複雑なドメインモデルを Spanner スキーマ列にマッピングする専用の MutationConverter クラス

• 二重書き込みブランチの処理とロールバックまたはエラー報告のロジック

• 疑似時間ソースとテストダブル（FakeTimeSource）を使用して、プライマリと Spanner の両方の書き込みを検証する単体テストのスイート

30 以上の DAO にわたって、同一の高精度なコード変更を手作業で行っていたら、エンジニアリングに数か月を要していたでしょう。

解決策: 標準化されたミューテーション コンバータ パターン

自動化パイプラインがクリーンなコードを確実に生成できることを検証するために、まず、分離された MutationConverter インターフェースを中心に DAO リファクタリング パターンを標準化しました。

中核的な DAO ビジネス ロジック内に未加工の Spanner テーブル名と列割り当てを直接埋め込むのではなく、Spanner スキーマ変換を専用のコンバータ ユニットに分離します。

DAO と Spanner SDK（spanner.Mutation）の間に厳格で決定論的なコントラクトを確立することで、AI コーディング エージェントが推論して確実に生成できる正確なターゲット仕様を作成しました。

Antigravity CLI をヘッドレス モードで使用する理由

IDE のインタラクティブな AI チャット インターフェースは、探索的なコーディングには適していますが、コードベース全体にわたる体系的な複数ファイルのコード更新には適していません。エッジケースを見逃さずに、数十のターゲットに繰り返し可能なリファクタリングを適用する必要がある場合は、自動化されたワークフローが必要です。

この問題に対処するため、Antigravity CLI をヘッドレス モード（-p）で実行するオーケストレーション スクリプト（migration_ui.py）を構築しました。

ヘッドレス モードでは、ターミナルのプロンプトに手動で応答しなくても、シェル スクリプト、継続的インテグレーション パイプライン、バックグラウンド自動化ジョブ内で Antigravity を直接実行できます。このアプローチにより、主に 3 つの方法で作業を効率化できました。

• 決定論的なプロンプト アーキテクチャ: プロンプトをバージョン管理されたエンジニアリング アーティファクトとして扱いました。タイムスタンプのシリアル化、null 可能性の変換、ミューテーションの曖昧さ、FakeTimeSource テスト インジェクションなど、Spanner の一般的なエッジケースを処理する正確なルールを、再利用可能なプロンプト テンプレートに直接コード化しました。

• バッチ実行と自動検証: オーケストレーション スクリプトが、ターゲット DAO 名を入力として使用し、既存の単一書き込みソースコードとスキーマを取得して、構造規則とともにヘッドレス Antigravity にフィードします。Antigravity は、新しいコンバータ、リファクタリングされた二重書き込み DAO、対応する単体テストを生成します。その後、スクリプトは blaze test を実行します。linter エラーやテスト アサーションの失敗が発生すると、エラーログが Antigravity に直接フィードバックされ、自己修正が行われます。

• 夜間に大規模に実行: ループは無人で実行されるため、エンジニアは 1 日の終わりに 10 個の DAO をキューに入れることができます。朝までに、パイプラインは人間によるコードレビューの準備が整った 10 個のクリーンな変更リストを生成、テスト、検証します。

クラウド エンジニアにとっての成果と重要なポイント

Spanner の分散データベース プリミティブと Antigravity CLI のヘッドレス自動化を組み合わせることで、エンジニアリング組織全体に明確なメリットがもたらされました。

• 移行作業の大幅な削減: 二重書き込みによる DAO の移行は、以前は広範な手動コーディングとテストが必要でしたが、わずかな時間で完了し、確認されました。

• 信頼性の高いデータ移行: 生成されたすべての DAO が、テスト済みのまったく同じ MutationConverter パターンに準拠し、Spanner テストダブルに対する自動単体テストを受けたため、広範な移行テスト中も高いデータ忠実度を維持できました。

• より価値の高いエンジニアリングに集中: エンジニアは、繰り返しのボイラープレート リファクタリングを回避し、データ モデリング、アーキテクチャの復元力、パフォーマンスの最適化に集中する時間を確保できました。

次回のデータベース移行に役立つ 3 つのヒント

1. まずスキーマ変換を分離する: 移行スクリプトを記述する前に、新しいクラウド データベース SDK の要件を既存のビジネス ロジックから分離する厳密なインターフェース（MutationConverter など）を定義します。AI エージェントは、明確で限定された設計パターンを与えられた場合に、最も効果的に機能します。

2. インタラクティブなチャットからヘッドレス自動化に移行する: 3～4 個以上のファイルにわたって繰り返しリファクタリングを実行する場合は、スクリプト化されたヘッドレス ワークフローにリソースを投入します。プロンプト入力とテスト検証を自動化されたビルドステップとして扱うことで、品質と一貫性を維持できます。

3. ビルドシステムをガードレールとして機能させる: AI 生成ループをビルドおよびテストハーネス（bazel test または go test）に直接接続します。これにより、デベロッパーがコードを確認する前に、モデルがコンパイル エラーとアサーション エラーを修正できます。

使ってみる

金融システムの移行でも、クラウドネイティブ アプリケーションのゼロからの構築でも、Spanner と Antigravity はスケーラブルなソフトウェア開発の基盤となります。

• Cloud Spanner を確認する: Spanner の分散アーキテクチャの詳細については、Google Cloud Spanner のドキュメントをご覧ください。

• デベロッパー向け Gemini を確認する: AI を活用したコーディングとヘッドレス CLI の自動化がエンジニアリング ワークフローにどのように役立つかを、デベロッパー向け Google Cloud AI でご確認ください。

- アプリケーション エンジニア Sachin Mathapati