使用 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. 修改 CqlSession 建立程式碼，並新增 Spanner Omni 通訊專屬選項。

  2. 將 Spanner Cassandra Java 用戶端新增為專案的依附元件。

    純文字通訊

    以下範例說明如何建立與 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())
    .setExperimentalHostEndpoint("ENDPOINT")
  .setUsePlainText(true)
        .build();

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

session.close();

    TLS 連線

    如要使用 TLS 連線，請務必將 CA 憑證新增至應用程式使用的信任儲存庫，詳情請參閱 Java SDK TLS 指示：

    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())
    .setExperimentalHostEndpoint("ENDPOINT")
  .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())
    .setExperimentalHostEndpoint("ENDPOINT")
  .setUsePlainText(false)
  .useClientCert("PATH_TO_CLIENT_CERT",
          "PATH_TO_CLIENT_KEY_PKCS8")

        .build();

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

session.close();

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"
  experimentalHostEndpoint: "ENDPOINT"
  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 \
-DexperimentalHostEndpoint=ENDPOINT \
-DusePlainText=true \
-jar PATH_TO_ADAPTER_JAR

TLS 連線

如為 TLS 連線，請執行下列指令：

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

mTLS 連線

如要建立 mTLS 連線，請執行下列指令：

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