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

Spanner 的 Cassandra Go 用戶端可將為 Apache Cassandra 資料庫編寫的應用程式連線至 Spanner。用戶端與 Spanner Omni 的運作方式，與 Spanner 相同。由於 Spanner 原生支援 Cassandra v4 網路通訊協定，因此這個用戶端可讓使用 gocql 驅動程式的 Go 應用程式，或 cqlsh 等非 Go 應用程式和工具，連線至 Spanner 資料庫。

這個用戶端會做為本機 TCP Proxy。攔截驅動程式或用戶端工具傳送的原始 Cassandra 通訊協定位元組。接著，它會將這些位元組和必要的中繼資料包裝成 gRPC 訊息，與 Spanner Omni 通訊。用戶端會將 Spanner Omni 的回應翻譯回 Cassandra 連線格式，並傳送回原始驅動程式或工具。

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

  • 程序內依附元件：如果 Go 應用程式已使用 gocql 驅動程式，請使用這個方法。這種方法會在應用程式程序中嵌入用戶端，因此程式碼修改幅度最小。

  • Sidecar Proxy：如果應用程式不是以 Go 語言編寫，或是使用 cqlsh 等外部 Cassandra 工具，請使用這個方法。這種做法會將用戶端做為獨立程序執行。

如要進一步瞭解 Apache Cassandra 如何與 Spanner 搭配運作，請參閱 Cassandra 介面。

使用 Spanner Cassandra Go 用戶端的時機

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

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

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

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

Go 應用程式會整合 Spanner Cassandra Go 用戶端，做為程序內依附元件，藉此連線至 Spanner Omni。這種做法會將 Proxy 邏輯直接嵌入應用程式，因此不必使用個別程序，可簡化部署架構。此外，這項設定可避免額外的網路躍點，以及額外的資料序列化和還原序列化，進而提供最佳效能。

如要將用戶端做為程序內依附元件使用，請執行下列操作：

  • 在 Go 應用程式中匯入 Spanner 套件：

    import spanner "github.com/googleapis/go-spanner-cassandra/cassandra/gocql"

  • 修改叢集建立程式碼。請使用 spanner.NewCluster 而非 gocql.NewCluster，並提供下列 Spanner Omni 專屬選項：

    純文字通訊

    以下範例說明如何建立與 Spanner Omni 的純文字連線：

    func main() {
  opts := &spanner.Options{
      // Required: Specify the Spanner database URI
      DatabaseUri: "DATABASE_ID",
  }
  // Optional: Configure Spanner Omni cluster settings as needed
  opts.ExperimentalHost = true
  opts.UsePlainText = true

  cluster := spanner.NewCluster(opts)
  // ...
}

    TLS 連線

    以下範例說明如何建立與 Spanner Omni 的 TLS 連線：

    func main() {
  opts := &spanner.Options{
      // Required: Specify the Spanner database URI
      DatabaseUri: "DATABASE_ID",
  }
  // Optional: Configure Spanner Omni cluster settings as needed
  opts.ExperimentalHost = true
  opts.CaCertificate = "PATH_TO_CA_CRT"

  cluster := spanner.NewCluster(opts)
  // ...
}

    mTLS 連線

    以下範例說明如何建立與 Spanner Omni 的 mTLS 連線：

    func main() {
  opts := &spanner.Options{
      // Required: Specify the Spanner database URI
      DatabaseUri: "DATABASE_ID",
  }
  // Optional: Configure Spanner Omni cluster settings as needed
  opts.ExperimentalHost = true
  opts.CaCertificate = "PATH_TO_CA_CRT"
  opts.ClientCertificate = "PATH_TO_CLIENT_CERT"
  opts.ClientKey = "PATH_TO_CLIENT_KEY"

  cluster := spanner.NewCluster(opts)
  // ...
}

將用戶端部署為 Sidecar Proxy

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

如果您需要使用外部 Cassandra 工具，或避免直接修改應用程式的程式碼，這項設定就非常實用。

您可以透過下列方式執行 Sidecar Proxy：

使用 Go run 指令在本機執行

從原始碼以本機程序形式執行 Sidecar Proxy，有助於開發和測試環境，您可以在這些環境中快速疊代應用程式和 Proxy 設定。

  1. 複製存放區：

    git clone https://github.com/googleapis/go-spanner-cassandra.git

  2. 切換至存放區目錄：

    cd go-spanner-cassandra

  3. 使用必要 -db 旗標和下列 Spanner Omni 專屬旗標執行 cassandra_launcher.go。將 -db 的值替換為 Spanner Omni 資料庫名稱：

  • 如要進行純文字通訊，請執行下列指令：
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -usePlainText
  • 如為 TLS 連線，請執行下列指令：
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT
  • 如要建立 mTLS 連線，請執行下列指令：
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT -clientCertificate PATH_TO_CLIENT_CERT -clientKey PATH_TO_CLIENT_KEY

使用預先建構的 Docker 映像檔執行

建議您使用預建的 Docker 映像檔，以容器化應用程式的形式執行 Sidecar Proxy，因為這樣可提供一致且獨立的執行階段環境。

  1. 從官方登錄檔存放區提取映像檔：

    docker pull gcr.io/cloud-spanner-adapter/cassandra-adapter

  2. 使用必要旗標執行映像檔：

    純文字通訊

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

    docker run -d -p 9042:9042 gcr.io/cloud-spanner-adapter/cassandra-adapter -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -usePlainText

    TLS 連線

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

    docker run -d -p 9042:9042 gcr.io/cloud-spanner-adapter/cassandra-adapter -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT

    mTLS 連線

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

    docker run -d -p 9042:9042 gcr.io/cloud-spanner-adapter/cassandra-adapter -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT -clientCertificate PATH_TO_CLIENT_CERT -clientKey PATH_TO_CLIENT_KEY