使用 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 語言編寫，或是使用外部 Cassandra 工具 (例如 cqlsh)，請使用這個方法。這種做法會將用戶端做為獨立程序執行。

如要進一步瞭解 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.SpannerEndpoint = "ENDPOINT"
  opts.InstanceType = spanner.Omni
  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.SpannerEndpoint = "ENDPOINT"
  opts.InstanceType = spanner.Omni
  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.SpannerEndpoint = "ENDPOINT"
  opts.InstanceType = spanner.Omni
  opts.CaCertificate = "PATH_TO_CA_CRT"
  opts.ClientCertificate = "PATH_TO_CLIENT_CERT"
  opts.ClientKey = "PATH_TO_CLIENT_KEY"

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

    更改下列內容：

    • DATABASE_ID：Spanner Omni 資料庫的 ID，例如 test-db。

    • ENDPOINT：Spanner Omni 執行個體的端點，例如 localhost:15000。

    • PATH_TO_CA_CRT：CA 憑證檔案的路徑。

    • PATH_TO_CLIENT_CERT：用戶端憑證檔案的路徑。

    • PATH_TO_CLIENT_KEY：用戶端金鑰檔案的路徑。

將用戶端部署為 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. 執行 cassandra_launcher.go，並加上必要的 -db 旗標和下列 Spanner Omni 專屬旗標：

    純文字

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

    go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -instanceType OMNI -usePlainText

    TLS

    如要透過 TLS 連線執行，請執行下列指令：

    go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -instanceType OMNI -caCertificate PATH_TO_CA_CRT

    mTLS

    如要使用 mTLS 連線執行，請執行下列指令：

    go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -instanceType OMNI -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 -instanceType OMNI -usePlainText

    TLS

    如要透過 TLS 連線執行，請執行下列指令：

    docker run -d -p 9042:9042 gcr.io/cloud-spanner-adapter/cassandra-adapter -db DATABASE_ID -endpoint ENDPOINT -instanceType OMNI -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 -instanceType OMNI -caCertificate PATH_TO_CA_CRT -clientCertificate PATH_TO_CLIENT_CERT -clientKey PATH_TO_CLIENT_KEY