Cassandra Java クライアントを使用して Spanner Omni に接続する

Spanner 用の Cassandra Java クライアントは、Apache Cassandra データベース用に作成されたアプリケーションを Spanner に接続します。クライアントは、Spanner を操作するのと同じ方法で Spanner Omni を操作します。

Spanner は Cassandra v4 ワイヤ プロトコルをネイティブにサポートしているため、Spanner Cassandra Java クライアントは Cassandra ワイヤ プロトコルを Spanner gRPC API に変換します。これにより、コードの変更を最小限に抑えて Cassandra アプリケーションを Spanner に移行できます。

このドキュメントでは、次のいずれかの方法を使用してクライアントを Spanner Omni と統合する方法について説明します。

  • インプロセス依存関係: cassandra-java-driver をすでに使用している Java アプリケーションには、この方法を使用します。このアプローチでは、コードの変更を最小限に抑えるために、クライアントをアプリケーション プロセスに埋め込みます。

  • サイドカー プロキシ: Java 以外のアプリケーションの場合や、cqlsh などの外部 Cassandra ツールを使用する場合は、この方法を使用します。このアプローチでは、クライアントはスタンドアロン プロセスとして実行されます。

詳細については、Spanner ドキュメントの Cassandra インターフェースをご覧ください。

Spanner Cassandra Java クライアントを使用するタイミング

このクライアントは、次のようなシナリオで役立ちます。

  • 最小限のリファクタリングで Spanner を使用する。Java アプリケーションのバックエンドとして Spanner を使用したいが、データアクセスには使い慣れた cassandra-java-driver API を引き続き使用したい。

  • Java 以外の Cassandra ツールを使用します。cqlsh などの標準の Cassandra ツールや、Cassandra ドライバを使用する他の言語で記述されたアプリケーションを使用して Spanner に接続する。

クライアントをインプロセス依存関係として使用する

Spanner Cassandra Java クライアントをプロセス内依存関係として統合することは、Java アプリケーションが Spanner Omni に接続する際の推奨方法です。サイドカー プロキシ方式と比較して、インプロセス構成では、追加のネットワーク ホップと、それに関連するデータのシリアル化と逆シリアル化を回避することで、パフォーマンスが向上します。また、個別のスタンドアロン プロセスを管理する必要がなくなるため、デプロイ アーキテクチャも簡素化されます。

クライアントをインプロセス依存関係として使用するには、次の操作を行います。

  1. Spanner Cassandra Java クライアントを依存関係としてプロジェクトに追加します。

    <dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-spanner-cassandra</artifactId>
  <version>1.2.0</version>
</dependency>

  2. CqlSession 作成コードを変更し、Spanner Omni 通信固有のオプションを追加します。

    書式なしテキスト

    次の例は、Spanner Omni へのプレーン テキスト接続を確立する方法を示しています。

    CqlSession session =
    SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
        .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
        .withConfigLoader(
            DriverConfigLoader.programmaticBuilder()
                .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                .withDuration(
                    DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                    Duration.ofSeconds(5))
                .build())
        .setHost("ENDPOINT")
        .setInstanceType(SpannerCqlSessionBuilder.InstanceType.OMNI)
        .setUsePlainText(true)
        .build();

// Rest of your business logic such as session.Query(SELECT * FROM ...)

session.close();

    TLS

    TLS 接続を使用するには、Java トラストストアを構成するで説明されているように、CA 証明書がアプリケーションで使用されるトラストストアに追加されていることを確認します。

    CqlSession session =
    SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
        .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
        .withConfigLoader(
            DriverConfigLoader.programmaticBuilder()
                .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                .withDuration(
                    DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                    Duration.ofSeconds(5))
                .build())
        .setHost("ENDPOINT")
        .setInstanceType(SpannerCqlSessionBuilder.InstanceType.OMNI)
        .setUsePlainText(false)
        .build();

// Rest of your business logic such as session.Query(SELECT * FROM ...)

session.close();

    mTLS

    mTLS 接続を使用するには、CA 証明書がアプリケーションで使用されるトラストストアに追加され、クライアント鍵が PKCS#8 形式になっていることを確認します。詳細については、Java SDK の mTLS の手順をご覧ください。

    CqlSession session =
    SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
        .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
        .withConfigLoader(
            DriverConfigLoader.programmaticBuilder()
                .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                .withDuration(
                    DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                    Duration.ofSeconds(5))
                .build())
        .setHost("ENDPOINT")
        .setInstanceType(SpannerCqlSessionBuilder.InstanceType.OMNI)
        .setUsePlainText(false)
        .setClientCertPathAndKey(
            "PATH_TO_CLIENT_CERT",
            "PATH_TO_CLIENT_KEY_PKCS8")
        .build();

// Rest of your business logic such as session.Query(SELECT * FROM ...)

  session.close();

    次のように置き換えます。

    • DATABASE_ID: Spanner Omni データベースの ID（例: test-db）。

    • ENDPOINT: Spanner Omni インスタンスのエンドポイント（例: localhost:15000）。

    • PATH_TO_CLIENT_CERT: クライアント証明書ファイルのパス。

    • PATH_TO_CLIENT_KEY_PKCS8: PKCS#8 形式のクライアント秘密鍵ファイルのパス。

サイドカー プロキシまたはスタンドアロン プロセス

Spanner Cassandra Java クライアントをサイドカー プロキシとしてデプロイすることは、cqlsh などの非 Java アプリケーションやツールが標準の Cassandra ドライバを使用して Spanner Omni に接続するための効果的なオプションです。このメソッドは、Cassandra ワイヤ プロトコル トラフィックをインターセプトして Spanner Omni との通信用に gRPC に変換するスタンドアロン TCP プロキシとしてクライアントを実行します。

サイドカー プロキシは、YAML 構成ファイルを使用するか、システム プロパティを指定して実行できます。

YAML 構成ファイルを使用する

本番環境の設定では、YAML ファイルを使用してアダプタを構成することをおすすめします。このメソッドは、複数のリスナーとグローバル設定をサポートしています。

java -DconfigFilePath=PATH_TO_CONFIG_YAML -jar PATH_TO_ADAPTER_JAR

config.yaml の例:

globalClientConfigs:
  enableBuiltInMetrics: false
  healthCheckEndpoint: "127.0.0.1:8080"
  spannerEndpoint: "ENDPOINT"
  instanceType: "omni"
  clientCertPath: "PATH_TO_CLIENT_CERT"
  clientKeyPath: "PATH_TO_CLIENT_KEY_PKCS8"
  usePlainText: "false"

listeners:
  - name: "listener_1"
    host: "127.0.0.1"
    port: 9042
    spanner:
      databaseUri: "DATABASE_ID"
      numGrpcChannels: 4
      maxCommitDelayMillis: 5
  - name: "listener_2"
    host: "127.0.0.2"
    port: 9043
    spanner:
      databaseUri: "DATABASE_ID_2"
      numGrpcChannels: 8

システム プロパティを使用する

単一のリスナーまたはよりシンプルなデプロイの場合、サイドカー プロキシをスタンドアロン プロセスとして実行し、Java システム プロパティを使用して設定を構成できます。

次の例は、サポートされている各セキュリティ構成でサイドカー プロキシをスタンドアロン プロセスとして実行する方法を示しています。

書式なしテキスト

プレーン テキスト通信で実行するには、次のコマンドを実行します。

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DspannerEndpoint=ENDPOINT \
-DinstanceType=omni \
-DusePlainText=true \
-jar PATH_TO_ADAPTER_JAR

TLS

TLS 接続で実行するには、次のコマンドを実行します。

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DspannerEndpoint=ENDPOINT \
-DinstanceType=omni \
-jar PATH_TO_ADAPTER_JAR

mTLS

mTLS 接続で実行するには、次のコマンドを実行します。

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DspannerEndpoint=ENDPOINT \
-DinstanceType=omni \
-DclientCertPath=PATH_TO_CLIENT_CERT \
-DclientKeyPath=PATH_TO_CLIENT_KEY_PKCS8 \
-jar PATH_TO_ADAPTER_JAR

次のように置き換えます。

  • DATABASE_ID: Spanner Omni データベースの ID（例: test-db）。

  • ENDPOINT: Spanner Omni インスタンスのエンドポイント（例: localhost:15000）。

  • PATH_TO_ADAPTER_JAR: Cassandra アダプタ JAR ファイルのパス。

  • PATH_TO_CLIENT_CERT: クライアント証明書ファイルのパス。

  • PATH_TO_CLIENT_KEY_PKCS8: PKCS#8 形式のクライアント秘密鍵ファイルのパス。