使用 Cassandra 代理连接到 Spanner Omni

将 Apache Cassandra 代理连接到 Spanner Omni，让现有 Cassandra 应用使用 Cassandra 查询语言 (CQL) 与 Spanner Omni 进行互动。通过此集成，您可以使用 Spanner Omni 功能，同时保持与 Cassandra 客户端应用的兼容性。

如需连接代理，请按照以下大致步骤操作：

  1. 克隆 Cassandra 到 Spanner 代理代码库。

  2. 使用提供的架构转换器脚本将 Cassandra 架构定义转换为 Spanner Omni 架构，该脚本支持纯文本、TLS 和 mTLS 安全模式。

  3. 通过使用 Spanner Omni 端点和安全设置更新代理适配器的配置文件来配置代理适配器。

  4. 构建并运行代理。然后，使用 cqlsh 连接到代理以开始操作。

如需了解详情，请参阅 Spanner 文档中的 Cassandra 接口。

准备工作

在开始之前，请满足以下要求：

  • 配置 Spanner Omni 部署并创建数据库。

  • 通过设置所需的 环境变量，在您的环境中启用多路复用会话。

  • 确保在本地机器上安装 Go。

  • 阅读 Cassandra 到 Spanner 代理的限制 ，了解使用注意事项。

  • 确定您要用于代理与 Spanner Omni 之间通信的安全模式（纯文本、TLS 或 mTLS）。

设置环境变量

如需使用 Cassandra 代理，您必须通过设置所需的环境变量来启用多路复用会话。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

克隆代码库

克隆支持代理的代码库，并确保您的机器上安装了 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);

配置代理适配器

使用架构转换器脚本创建 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

构建并运行代理

配置代理适配器后，使用以下命令构建并运行代理：

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

使用 shell 和以下命令连接到代理：

./cqlsh localhost 9042