使用 Cassandra Java 用戶端連線至 Spanner Omni

適用於 Spanner 的 Cassandra Java 用戶端可將為 Apache Cassandra 資料庫編寫的應用程式，連線至 Spanner。用戶端與 Spanner Omni 的運作方式，與 Spanner 相同。

由於 Spanner 原生支援 Cassandra v4 連線通訊協定，因此 Spanner Cassandra Java 用戶端會將 Cassandra 連線通訊協定轉譯為 Spanner gRPC API。這樣一來，您就能將 Cassandra 應用程式遷移至 Spanner，且程式碼變更幅度極小。

本文說明如何使用下列其中一種方法，將用戶端與 Spanner Omni 整合：

  • 程序內依附元件：如果 Java 應用程式已使用 cassandra-java-driver，請使用這個方法。這種做法會在應用程式程序中嵌入用戶端，因此只需要小幅修改程式碼。

  • Sidecar Proxy：如果應用程式不是以 Java 撰寫，或是使用外部 Cassandra 工具 (例如 cqlsh)，請採用這個方法。這種做法會將用戶端做為獨立程序執行。

詳情請參閱 Spanner 說明文件中的「Cassandra 介面」。

Spanner Cassandra Java 用戶端的適用情況

這個用戶端適用於下列情況：

  • 以最少的重構作業使用 Spanner。您想使用 Spanner 做為 Java 應用程式的後端，但偏好繼續使用熟悉的 cassandra-java-driver API 存取資料。

  • 使用非 Java 的 Cassandra 工具。您想使用標準 Cassandra 工具 (例如 cqlsh) 連線至 Spanner，或是使用以其他語言編寫的應用程式 (這些應用程式使用 Cassandra 驅動程式)。

將用戶端做為程序內依附元件使用

將 Spanner Cassandra Java 用戶端整合為程序內依附元件，是 Java 應用程式連線至 Spanner Omni 的建議方法。與 Sidecar Proxy 方法相比，由於避免了額外的網路躍點，以及相關的資料序列化和還原序列化，因此程序內設定可提供更優異的效能。此外，您也不必管理個別的獨立程序，因此部署架構也會變得更簡單。

如要將用戶端做為程序內依附元件使用，請按照下列步驟操作：

  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 格式)。

Sidecar Proxy 或獨立程序

將 Spanner Cassandra Java 用戶端部署為 Sidecar Proxy，是適用於非 Java 應用程式和工具 (例如 cqlsh) 的有效選項，可使用標準 Cassandra 驅動程式連線至 Spanner Omni。這個方法會將用戶端做為獨立的 TCP Proxy 執行，攔截 Cassandra 連線通訊協定流量，並將其轉換為 gRPC，以便與 Spanner Omni 通訊。

您可以透過 YAML 設定檔或指定系統屬性，執行 Sidecar Proxy。

使用 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

使用系統屬性

如果是單一接聽程式或較簡單的部署作業，您可以將 Sidecar Proxy 做為獨立程序執行，並使用 Java 系統屬性設定。

下列範例說明如何針對各項支援的安全設定，以獨立程序的形式執行 Sidecar Proxy：

純文字

如要以純文字通訊執行，請執行下列指令：

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 格式)。