Spanner Cassandra Adapter を使ってみる

残り 38 分

この Codelab について

最終更新: 5月 21, 2025

作成者: Mayur Kale, Vardhan Thigle

このページは Cloud Translation API によって翻訳されました。

1. はじめに

Spanner は、リレーショナルワークロードと非リレーショナルワークロードの両方に適した、フルマネージド、水平方向にスケーラブルなグローバル分散データベースサービスです。

Spanner の Cassandra インターフェースを使用すると、使い慣れた Cassandra ツールと構文を使用して、Spanner のフルマネージド、スケーラブル、高可用性のインフラストラクチャを活用できます。

学習内容

Spanner のインスタンスとデータベースを設定する方法。
Cassandra のスキーマとデータモデルを変換する方法。
受信データの二重書き込みをデプロイして構成する方法。
Cassandra から Spanner に過去のデータを一括エクスポートする方法。
移行プロセス全体でデータの完全性を確保するためにデータを検証する方法。
Cassandra ではなく Spanner にアプリケーションをポイントする方法。

必要なもの

請求先アカウントに接続されている Google Cloud プロジェクト。
gcloud CLI がインストールされて構成されているマシンにアクセスするか、Google Cloud Shell を使用します。
ウェブブラウザ（Chrome、Firefox など）

GCP プロジェクトを作成する

Google Cloud Console にログインして、プロジェクトを新規作成するか、既存のプロジェクトを再利用します。Gmail アカウントも Google Workspace アカウントもまだお持ちでない場合は、アカウントを作成してください。

プロジェクト名は、このプロジェクトの参加者に表示される名称です。Google API では使用されない文字列です。いつでも更新できます。
プロジェクト ID は、すべての Google Cloud プロジェクトにおいて一意でなければならず、不変です（設定後は変更できません）。Cloud コンソールでは一意の文字列が自動生成されます。通常は、この内容を意識する必要はありません。ほとんどの Codelab では、プロジェクト ID（通常は PROJECT_ID と識別されます）を参照する必要があります。生成された ID が好みではない場合は、ランダムに別の ID を生成できます。または、ご自身で試して、利用可能かどうかを確認することもできます。このステップ以降は変更できず、プロジェクトを通して同じ ID になります。
なお、3 つ目の値として、一部の API が使用するプロジェクト番号があります。これら 3 つの値について詳しくは、こちらのドキュメントをご覧ください。

お支払い情報の設定

次に、請求の管理に関するユーザーガイドに沿って、Cloud コンソールで課金を有効にする必要があります。Google Cloud の新規ユーザーは、300 米ドル分の無料トライアルプログラムをご利用いただけます。このチュートリアルを終了した後に課金が発生しないようにするには、Codelab の最後にある「ステップ 9 クリーンアップ」の手順に沿って Spanner インスタンスをシャットダウンします。

Cloud Shell の起動

Google Cloud はノートパソコンからリモートで操作できますが、この Codelab では、Google Cloud Shell（Cloud 上で動作するコマンドライン環境）を使用します。

Google Cloud Console で、右上のツールバーにある Cloud Shell アイコンをクリックします。

プロビジョニングと環境への接続にはそれほど時間はかかりません。完了すると、次のように表示されます。

この仮想マシンには、必要な開発ツールがすべて用意されています。永続的なホームディレクトリが 5 GB 用意されており、Google Cloud で稼働します。そのため、ネットワークのパフォーマンスと認証機能が大幅に向上しています。この Codelab での作業はすべて、ブラウザ内から実行できます。インストールは不要です。

次のステップ

次に、Cassandra クラスタをデプロイします。

3. Cassandra クラスタをデプロイする（Origin）

この Codelab では、Compute Engine に単一ノード Cassandra クラスタを設定します。

1. Cassandra 用の GCE VM を作成する

インスタンスを作成するには、gcloud compute instances create コマンドを使用します。

gcloud compute instances create cassandra-origin \
--machine-type=e2-medium \
--image-family=ubuntu-2004-lts \
--image-project=ubuntu-os-cloud \
--tags=cassandra-migration \
--boot-disk-size=20GB

2. Cassandra をインストールする

# Install Java (Cassandra dependency)
sudo apt-get update
sudo apt-get install -y openjdk-11-jre-headless

# Add Cassandra repository
echo "deb [https://debian.cassandra.apache.org](https://debian.cassandra.apache.org) 41x main" | sudo tee -a /etc/apt/sources.list.d/cassandra.sources.list
curl [https://downloads.apache.org/cassandra/KEYS](https://downloads.apache.org/cassandra/KEYS) | sudo apt-key add -

# Install Cassandra
sudo apt-get update
sudo apt-get install -y cassandra

3. キースペースとテーブルを作成する

ここでは、ユーザーテーブルの例を使用して、「analytics」というキースペースを作成します。

cd ~/apache-cassandra
bin/cqlsh <your-localhost-ip? 9042  #starts the cql shell

cqlsh 内:

-- Create keyspace (adjust replication for production)
CREATE KEYSPACE analytics WITH replication = {'class':'SimpleStrategy', 'replication_factor':1};

-- Use the keyspace
USE analytics;

-- Create the users table
CREATE TABLE users (
    id  int PRIMARY KEY,
    active  boolean,
    username  text,
);

-- Exit cqlsh
EXIT;

SSH セッションを開いたままにするか、この VM の IP アドレス（hostname -I）をメモします。

次のステップ

次に、Cloud Spanner インスタンスとデータベースを設定します。

4. Spanner のインスタンスとデータベースを作成する（ターゲット）

Spanner では、インスタンスは、1 つ以上の Spanner データベースをホストするコンピューティングリソースとストレージリソースのクラスタです。この Codelab では、Spanner データベースをホストするインスタンスが 1 つ以上必要になります。

gcloud SDK のバージョンを確認する

インスタンスを作成する前に、Google Cloud Shell の gcloud SDK が必要なバージョン（gcloud SDK 493.0.0）に更新されていることを確認します。gcloud SDK のバージョンは、次のコマンドで確認できます。

$ gcloud version | grep Google

出力例を次に示します。

Google Cloud SDK 489.0.0

使用しているバージョンが、必要な 493.0.0 バージョン（上の例の 489.0.0）より前の場合は、次のコマンドを実行して Google Cloud SDK をアップグレードする必要があります。

sudo apt-get update \
  && sudo apt-get --only-upgrade install google-cloud-cli-anthoscli google-cloud-cli-cloud-run-proxy kubectl google-cloud-cli-skaffold google-cloud-cli-cbt google-cloud-cli-docker-credential-gcr google-cloud-cli-spanner-migration-tool google-cloud-cli-cloud-build-local google-cloud-cli-pubsub-emulator google-cloud-cli-app-engine-python google-cloud-cli-kpt google-cloud-cli-bigtable-emulator google-cloud-cli-datastore-emulator google-cloud-cli-spanner-emulator google-cloud-cli-app-engine-go google-cloud-cli-app-engine-python-extras google-cloud-cli-config-connector google-cloud-cli-package-go-module google-cloud-cli-istioctl google-cloud-cli-anthos-auth google-cloud-cli-gke-gcloud-auth-plugin google-cloud-cli-app-engine-grpc google-cloud-cli-kubectl-oidc google-cloud-cli-terraform-tools google-cloud-cli-nomos google-cloud-cli-local-extract google-cloud-cli-firestore-emulator google-cloud-cli-harbourbridge google-cloud-cli-log-streaming google-cloud-cli-minikube google-cloud-cli-app-engine-java google-cloud-cli-enterprise-certificate-proxy google-cloud-cli

Spanner API を有効にする

Cloud Shell で、プロジェクト ID が設定されていることを確認します。次の最初のコマンドを使用して、現在構成されているプロジェクト ID を確認します。結果が期待どおりでない場合は、次の 2 番目のコマンドで正しい結果を設定します。

gcloud config get-value project

gcloud config set project [YOUR-DESIRED-PROJECT-ID]

デフォルトのリージョンを us-central1 に構成します。これは、Spanner のリージョン構成でサポートされている別のリージョンに変更できます。

gcloud config set compute/region us-central1

Spanner API を有効にします。

gcloud services enable spanner.googleapis.com

Spanner インスタンスを作成する

このセクションでは、無料トライアルインスタンスまたはプロビジョニングされたインスタンスを作成します。この Codelab では、使用される Spanner Cassandra アダプタインスタンス ID は cassandra-adapter-demo です。これは、export コマンドラインを使用して SPANNER_INSTANCE_ID 変数として設定されます。必要に応じて、独自のインスタンス ID 名を選択できます。

無料トライアルの Spanner インスタンスを作成する

Spanner の 90 日間の無料トライアルインスタンスは、プロジェクトで Cloud Billing が有効になっている Google アカウントをお持ちのすべてのユーザーが利用できます。無料トライアルインスタンスを有料インスタンスにアップグレードしない限り、請求されることはありません。Spanner Cassandra Adapter は、無料トライアルインスタンスでサポートされています。対象となる場合は、Cloud Shell を開いて次のコマンドを実行して、無料トライアルインスタンスを作成します。

export SPANNER_INSTANCE_ID=cassandra-adapter-demo
export SPANNER_REGION=regional-us-central1
gcloud spanner instances create $SPANNER_INSTANCE_ID \
  --config=$SPANNER_REGION \
  --instance-type=free-instance \
  --description="Spanner Cassandra Adapter demo"

コマンド出力:

$ gcloud spanner instances create $SPANNER_INSTANCE_ID \
  --config=$SPANNER_REGION \
  --instance-type=free-instance \
  --description="Spanner Cassandra Adapter demo"
Creating instance...done.

データベースを作成する

インスタンスが実行されたら、データベースを作成できます。データベースでスキーマを定義します。また、データベースにアクセスできるユーザーを制御したり、カスタム暗号化を設定したり、オプティマイザーを構成したり、保持期間を設定したりすることもできます。

データベースは、ID が SPANNER_INSTANCE_ID のインスタンスに作成されます。

データベースを作成するには、gcloud コマンドラインツールを使用します。

export SPANNER_DATABASE=analytics
gcloud spanner databases create $SPANNER_DATABASE \
 --instance=$SPANNER_INSTANCE_ID

コマンド出力:

$ gcloud spanner databases create $SPANNER_DATABASE \
 --instance=$SPANNER_INSTANCE_ID
Creating database...done.

5. Cassandra スキーマとデータモデルを Spanner に移行する

Cassandra データベースから Spanner にデータを移行する最初の重要なフェーズでは、Spanner の構造とデータ型の要件に合わせて既存の Cassandra スキーマを変換します。

この複雑なスキーマ移行プロセスを効率化するために、Spanner には Spanner Cassandra スキーマツールという貴重なオープンソースツールが用意されています。

Spanner Cassandra スキーマツール

Spanner Cassandra スキーマツールは、Spanner の評価とスキーマ移行用のスタンドアロンオープンソースツールです。主な機能は、既存の Cassandra スキーマにある定義に基づいて Spanner スキーマを自動的に構築することです。このツールは、Cassandra テーブルの構造、データ型、主キー構成を分析して、同等の Spanner テーブル定義を生成します。これにより、スキーマ変換に通常伴う手動作業を大幅に削減できます。

Cassandra スキーマをエクスポートする

Spanner Cassandra スキーマツールを使用する前に、まず現在の Cassandra クラスタからスキーマを抽出します。これは、cqlsh を介して既存の Cassandra クラスタに接続し、Cassandra からスキーマをエクスポートすることで実現できます。

cqlsh [IP] "-e DESC SCHEMA" > orig_schema.cql

このコマンドでは、[IP] は Cassandra クラスタ内のいずれかのノードの IP アドレスまたはホスト名に置き換える必要があります。コマンドの -e DESC SCHEMA 部分は、Cassandra クラスタのスキーマ全体を記述するように cqlsh に指示します。このコマンドの出力（CREATE KEYSPACE ステートメントと CREATE TABLE ステートメントを含む）は、orig_schema.cql という名前のファイルにリダイレクトされます。

この orig_schema.cql ファイルの内容は、基本的に Cassandra スキーマのテキストブループリントを表します。orig_schema.cql ファイルの内容は次のようになります。

CREATE KEYSPACE analytics WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'}  AND durable_writes = true;

CREATE TABLE analytics.users (
    id int PRIMARY KEY,
    active boolean,
    username text
) WITH additional_write_policy = '99p'
    AND allow_auto_snapshot = true
    AND bloom_filter_fp_chance = 0.01
    AND caching = {'keys': 'ALL', 'rows_per_partition': 'NONE'}
    AND cdc = false
    AND comment = ''
    AND compaction = {'class': 'org.apache.cassandra.db.compaction.SizeTieredCompactionStrategy', 'max_threshold': '32', 'min_threshold': '4'}
    AND compression = {'chunk_length_in_kb': '16', 'class': 'org.apache.cassandra.io.compress.LZ4Compressor'}
    AND memtable = 'default'
    AND crc_check_chance = 1.0
    AND default_time_to_live = 0
    AND extensions = {}
    AND gc_grace_seconds = 864000
    AND incremental_backups = true
    AND max_index_interval = 2048
    AND memtable_flush_period_in_ms = 0
    AND min_index_interval = 128
    AND read_repair = 'BLOCKING'
    AND speculative_retry = '99p';

リポジトリのクローンを作成する

Spanner Cassandra スキーマツールを使用するには、次のステップでツールのソースコードを取得します。これは、GitHub でホストされているリポジトリのクローンを作成することで行います。Cloud Shell で次のコマンドを入力して、GitHub から Spanner Cassandra スキーマツールのクローンを作成します。

git clone https://github.com/cloudspannerecosystem/spanner-cassandra-schema-tool.git

次に、コマンドを実行する「spanner-cassandra-schema-tool」ディレクトリに移動します。

cd spanner-cassandra-schema-tool

依存関係のインストール

Spanner Cassandra スキーマツールは Go プログラミング言語で記述されています。ツールが正しく機能するように、特定の外部 Go モジュール（ライブラリ）に依存しています。ツールを実行する前に、これらの依存関係をダウンロードして管理する必要があります。spanner-cassandra-schema-tool ディレクトリ内で、次のコマンドを実行します。

go mod download

Google Cloud 認証情報を設定する

このツールは、Spanner データベースへの接続の認証情報ソースとしてアプリケーションのデフォルト認証情報（ADC）を使用します。GOOGLE_APPLICATION_CREDENTIALS 環境変数を、サービスアカウントキーファイルのパスに設定します。

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-file.json"

/path/to/your/service-account-file.json は、ダウンロードしたサービスアカウントキーファイルの実際のパスに置き換えます。この環境変数を設定すると、Spanner Cassandra スキーマツールが Google Cloud プロジェクトと Spanner インスタンスで安全に認証できるようになります。

用途

依存関係がインストールされ、Google Cloud 認証情報が構成されたら、Spanner Cassandra スキーマツールを実行して、エクスポートされた Cassandra スキーマファイルから Spanner スキーマを生成できます。ターミナルまたは Cloud Shell で spanner-cassandra-schema-tool ディレクトリに移動し、次の go run コマンドを実行します。

go run schema_converter.go \
    --project $PROJECT_ID \
    --instance $SPANNER_INSTANCE_ID \
    --database $SPANNER_DATABASE \
    --cql orig_schema.cql \
    --dry-run

--dry-run オプションを指定して実行すると、スキーマのみが生成されます。ツールによって生成されたデータ型のマッピングと主キー列を確認して調整します。Spanner データ型が、対応する Cassandra データベース型の範囲、精度、セマンティクスを正確に表していることを確認します。

このツールは、サポートされている Cassandra データ型に記載されているように、Cassandra 型を Spanner 型にマッピングします。

コマンドの出力は次のようになります。

.....

[Converted Spanner statement]
CREATE TABLE users (
 id INT64 NOT NULL OPTIONS (cassandra_type = 'int'),
 active BOOL OPTIONS (cassandra_type = 'boolean'),
 username STRING(MAX) OPTIONS (cassandra_type = 'text'),
) PRIMARY KEY (id)
----------------------------------------------
Writing converted Spanner schema to: schema.txt
Dry run enabled. Skipping schema execution.
Schema conversion completed!

スキーマの適用も Spanner に自動的に適用する場合は、--dry-run オプションなしで CLI を実行する必要があります。

Google Cloud コンソールで、テーブルとメタデータテーブルが Cloud Spanner データベースに存在することを確認します。

6. 受信データの二重書き込みを設定する

[TODO]

7. 過去のデータをまとめてエクスポートする

[TODO]

8. データの検証

[TODO]

9. アプリケーションを Spanner に指すようにする（カットオーバー）

移行フェーズでデータの精度と完全性を慎重に検証したら、アプリケーションのオペレーションの重点をレガシーの Cassandra システムから新しく入力された Google Cloud Spanner データベースに移行することが重要です。この重要な移行期間は、一般に「カットオーバー」と呼ばれます。

カットオーバーフェーズでは、ライブアプリケーショントラフィックが元の Cassandra クラスタからリダイレクトされ、堅牢でスケーラブルな Spanner インフラストラクチャに直接接続されます。この移行は、特に Spanner Cassandra インターフェースを使用する場合、アプリケーションが Spanner の機能を簡単に利用できることを示しています。

Spanner Cassandra インターフェースを使用すると、カットオーバープロセスが効率化されます。主に、すべてのデータ操作にネイティブの Spanner Cassandra クライアントを使用するようにクライアントアプリケーションを構成します。アプリケーションは Cassandra（送信元）データベースと通信する代わりに、Spanner（移行先）に直接データを読み書きし始めます。接続のこの根本的な変化は、通常、SpannerCqlSessionBuilder を使用して実現されます。これは、Spanner インスタンスへの接続を確立しやすくする、Spanner Cassandra クライアントライブラリの主要コンポーネントです。これにより、アプリケーションのデータトラフィックフローの全体が Spanner にリルーティングされます。

すでに cassandra-java-driver ライブラリを使用している Java アプリケーションの場合、Spanner Cassandra Java クライアントを統合するには、CqlSession の初期化を少し変更するだけで済みます。

google-cloud-spanner-cassandra 依存関係の取得

Spanner Cassandra クライアントの使用を開始するには、まずその依存関係をプロジェクトに組み込む必要があります。google-cloud-spanner-cassandra アーティファクトは、Maven Central のグループ ID com.google.cloud で公開されます。Java プロジェクトの既存の <dependencies> セクションに、次の新しい依存関係を追加します。google-cloud-spanner-cassandra 依存関係を含める方法の簡単な例を次に示します。

<!-- native Spanner Cassandra Client -->
<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-spanner-cassandra</artifactId>
    <version>0.2.0</version>
  </dependency>
</dependencies>

Spanner に接続するように接続構成を変更する

必要な依存関係を追加したら、次は Spanner データベースに接続するように接続構成を変更します。

Cassandra クラスタとやり取りする一般的なアプリケーションでは、多くの場合、次のようなコードを使用して接続を確立します。

CqlSession session = CqlSession.builder()
        .addContactPoint(new InetSocketAddress("127.0.0.1", 9042))
        .withLocalDatacenter("datacenter1")
        .withAuthCredentials("username", "password")
        .build();

この接続を Spanner にリダイレクトするには、CqlSession 作成ロジックを変更する必要があります。cassandra-java-driver の標準 CqlSessionBuilder を直接使用するのではなく、Spanner Cassandra クライアントが提供する SpannerCqlSession.builder() を使用します。接続コードを変更する方法の例を次に示します。

String databaseUri = "projects/<your-gcp-project>/instances/<your-spanner-instance>/databases/<your-spanner-database>";

CqlSession session = SpannerCqlSession.builder()
        .setDatabaseUri(databaseUri)
        .addContactPoint(new InetSocketAddress("localhost", 9042))
        .withLocalDatacenter("datacenter1")
        .build();

SpannerCqlSession.builder() を使用して CqlSession をインスタンス化し、正しい databaseUri を指定すると、アプリケーションは Spanner Cassandra クライアントを介してターゲット Spanner データベースへの接続を確立します。この重要な変更により、アプリケーションによって実行される以降の読み取りオペレーションと書き込みオペレーションはすべて Spanner に転送され、Spanner によって処理されるため、最初のカットオーバーが効果的に完了します。これで、アプリケーションは引き続き想定どおりに機能し、Spanner のスケーラビリティと信頼性を利用できるようになります。

仕組み: Spanner Cassandra クライアントの動作

Spanner Cassandra クライアントはローカル TCP プロキシとして機能し、ドライバまたはクライアントツールから送信された未加工の Cassandra プロトコルバイトをインターセプトします。次に、これらのバイトと必要なメタデータを gRPC メッセージにラップして、Spanner との通信を行います。Spanner からのレスポンスは Cassandra ワイヤー形式に変換され、送信元のドライバまたはツールに返されます。

Spanner がすべてのトラフィックを正しく処理していることを確認したら、最終的には次のことができます。

二重書き込みを停止します。
元の Cassandra クラスタを廃止します。

10. クリーンアップ（省略可）

クリーンアップするには、Cloud Console の Spanner セクションに移動して、Codelab で作成した cassandra-adapter-demo インスタンスを削除します。

Cassandra データベースを削除する（ローカルにインストールされている場合、または永続化されている場合）

ここで作成した Compute Engine VM の外部に Cassandra をインストールした場合は、適切な手順に沿ってデータを削除するか、Cassandra をアンインストールします。

11. お疲れさまでした

次のステップ

Cloud Spanner の詳細を確認する。
詳細については、Cassandra インターフェースをご覧ください。

誤りを報告