使用 Cassandra Proxy 連線至 Spanner Omni

將 Apache Cassandra Proxy 連線至 Spanner Omni，讓現有的 Cassandra 應用程式使用 Cassandra 查詢語言 (CQL) 與 Spanner Omni 互動。這項整合功能可讓您使用 Spanner Omni 功能，同時維持與 Cassandra 用戶端應用程式的相容性。

如要連線至 Proxy，請按照下列高階步驟操作：

複製 Cassandra-to-Spanner Proxy 存放區。
使用提供的結構定義轉換器指令碼，將 Cassandra 結構定義轉換為 Spanner Omni 結構定義。這項指令碼支援純文字、TLS 和 mTLS 安全模式。
更新 Proxy 介面的設定檔，加入 Spanner Omni 端點和安全性設定，即可設定 Proxy 介面。
建構並執行 Proxy。然後使用 cqlsh 連線，即可開始作業。

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

事前準備

開始前，請先完成下列要求：

設定 Spanner Omni 部署作業並建立資料庫。
設定必要的環境變數，在環境中啟用多工階段。
確認本機電腦已安裝 Go。
請參閱Cassandra-to-Spanner Proxy 的限制，瞭解使用注意事項。
建立您要用於 Proxy 與 Spanner Omni 之間通訊的安全模式 (純文字、TLS 或 mTLS)。

設定環境變數

如要使用 Cassandra Proxy，請設定必要的環境變數，啟用多工連線。Spanner Omni 連線需要多工工作階段，但 Spanner 用戶端程式庫和驅動程式預設會停用這項功能。

請設定下列環境變數：

GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS_FOR_RW=true
GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS_PARTITIONED_OPS=true
GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS=true

複製存放區

複製支援 Proxy 的存放區，並確認電腦上已安裝 Go：

git clone https://github.com/cloudspannerecosystem/cassandra-to-spanner-proxy.git

// Ensure all Go modules are installed
go mod tidy

轉換 Cassandra 結構定義

請預先建立所有 Cassandra 資料表。schema_converter/cql_to_spanner_schema_converter.go 指令碼會將 CQL 檔案中的 Cassandra CREATE TABLE 查詢轉換為 Spanner CREATE TABLE 查詢。

--database DATABASE_ID：在 Spanner Omni 中指定目標資料庫名稱。將 DATABASE_ID 替換成您的資料庫名稱。
--cql PATH_TO_CQL_FILE：指定包含 Cassandra 結構定義的 CQL 檔案路徑。
--endpoint ENDPOINT：指定 Spanner Omni 端點位址。將 ENDPOINT 替換為您的 Spanner Omni 端點。
```
go run schema_converter/cql_to_spanner_schema_converter.go --database DATABASE_ID --cql PATH_TO_CQL_FILE --endpoint ENDPOINT
```
結構定義轉換器支援所有三種 Spanner Omni 安全性模式：純文字、TLS 和 mTLS。每種安全模式都需要額外參數：

如要使用純文字模式，請使用 --usePlainText 旗標：

go run schema_converter/cql_to_spanner_schema_converter.go --database DATABASE_ID --cql PATH_TO_CQL_FILE --endpoint ENDPOINT --usePlainText

如為 TLS 模式，請使用 --caCertificate 旗標，並提供 CA 憑證檔案的路徑：

go run schema_converter/cql_to_spanner_schema_converter.go --database DATABASE_ID --cql PATH_TO_CQL_FILE --endpoint ENDPOINT --caCertificate PATH_TO_CA_CRT

如果是 mTLS 模式，請使用 --caCertificate、--clientCertificate 和 --clientKey 標記，並提供對應路徑：

go run schema_converter/cql_to_spanner_schema_converter.go --database DATABASE_ID --cql PATH_TO_CQL_FILE --endpoint ENDPOINT --caCertificate PATH_TO_CA_CRT --clientCertificate PATH_TO_CLIENT_CERT --clientKey PATH_TO_CLIENT_KEY

如果 TableConfigurations 資料表尚不存在，指令碼也會建立該資料表。這個資料表會追蹤 Cassandra 資料表和資料欄的結構定義中繼資料：

CREATE TABLE IF NOT EXISTS TableConfigurations (
    `KeySpaceName` STRING(MAX),
    `TableName` STRING(MAX),
    `ColumnName` STRING(MAX),
    `ColumnType` STRING(MAX),
    `IsPrimaryKey` BOOL,
    `PK_Precedence` INT64,
) PRIMARY KEY (TableName, ColumnName, KeySpaceName);

設定 Proxy 轉接器

使用結構定義轉換器指令碼建立 Cassandra 資料表後，請設定介面卡，以便對資料表執行作業。如要設定轉接程式，請執行下列操作：

使用可用的設定選項，更新存放區根目錄中的 config.yaml 檔案。在轉接程式設定檔中，您必須定義 Spanner Omni 端點，以及相關的安全模式選項。

# [Optional] endpoint configuration for spanner
endpoint: ENDPOINT

# [Optional] If set to True, will connect to endpoint over plain text
usePlainText: False

# [Optional] CA certificate path for TLS and mTLS configuration
caCertificate: PATH_TO_CA_CRT

# [Optional] client certificate path for mTLS configuration
clientCertificate: PATH_TO_CLIENT_CERT

# [Optional] client key path for mTLS configuration
clientKey: PATH_TO_CLIENT_KEY

下列設定提供執行介面卡的最低設定：

cassandra_to_spanner_configs:
  # [Optional] endpoint configuration for spanner
  endpoint: ENDPOINT

  # Uncomment the options as required by the security mode of the Spanner Omni deployment
  # [Optional] If set to True, will connect to endpoint over plain text
  # usePlainText: False
  # [Optional] CA certificate path for TLS and mTLS configuration
  # caCertificate: /tmp/ca.crt
  # [Optional] client certificate path for mTLS configuration
  # clientCertificate: /tmp/client.crt
  # [Optional] client key path for mTLS configuration
  # clientKey: /tmp/client.key

listeners:
  - name: CLUSTER_NAME
    port: 9042
    spanner:
      databaseId: DATABASE_ID

建構並執行 Proxy

設定 Proxy 配接器後，請使用下列指令建構及執行 Proxy：

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o cassandra-to-spanner-proxy .
./cassandra-to-spanner-proxy

使用下列指令，透過殼層連線至 Proxy：

./cqlsh localhost 9042