Spanner Cassandra Adapter 使用入门

剩余时间：38 分钟

关于此 Codelab

上次更新时间：5月 21, 2025

Mayur Kale, Vardhan Thigle 编写

1. 简介

Spanner 是一项全代管式可横向扩容的全球分布式数据库服务，非常适合处理关系型和非关系型工作负载。

借助 Spanner 的 Cassandra 接口，您可以使用熟悉的 Cassandra 工具和语法，充分利用 Spanner 的全托管式、可伸缩且高度可用的架构。

学习内容

如何设置 Spanner 实例和数据库。
如何转换 Cassandra 架构和数据模型。
如何为传入数据部署和配置双写入。
如何将历史数据从 Cassandra 批量导出到 Spanner。
如何验证数据，以确保整个迁移过程中数据的完整性。
如何将应用指向 Spanner 而非 Cassandra。

所需条件

与结算账号关联的 Google Cloud 项目。
访问安装并配置了 gcloud CLI 的机器，或使用 Google Cloud Shell。
网络浏览器，例如 Chrome 或 Firefox。

创建 GCP 项目

项目名称是此项目参与者的显示名称。它是 Google API 尚未使用的字符串。您可以随时对其进行更新。
项目 ID 在所有 Google Cloud 项目中是唯一的，并且是不可变的（一经设置便无法更改）。Cloud 控制台会自动生成一个唯一字符串；通常情况下，您无需关注该字符串。在大多数 Codelab 中，您都需要引用项目 ID（通常用 PROJECT_ID 标识）。如果您不喜欢生成的 ID，可以再随机生成一个 ID。或者，您也可以尝试自己的项目 ID，看看是否可用。完成此步骤后便无法更改该 ID，并且此 ID 在项目期间会一直保留。
此外，还有第三个值，即部分 API 使用的项目编号，供您参考。如需详细了解所有这三个值，请参阅文档。

结算设置

接下来，您需要按照结算管理用户指南中的说明操作，并在 Cloud 控制台中启用结算功能。Google Cloud 新用户符合参与 300 美元免费试用计划的条件。为避免产生超出本教程范围的结算费用，您可以在本 Codelab 结束后按照“第 9 步清理”关闭 Spanner 实例。

启动 Cloud Shell

虽然可以通过笔记本电脑对 Google Cloud 进行远程操作，但在此 Codelab 中，您将使用 Google Cloud Shell，这是一个在云端运行的命令行环境。

在 Google Cloud 控制台中，点击右上角工具栏中的 Cloud Shell 图标：

预配和连接到环境应该只需要片刻时间。完成后，您应该会看到如下内容：

这个虚拟机已加载了您需要的所有开发工具。它提供了一个持久的 5 GB 主目录，并且在 Google Cloud 中运行，大大增强了网络性能和身份验证功能。您在此 Codelab 中的所有工作都可以在浏览器中完成。您无需安装任何程序。

后续步骤

接下来，您将部署 Cassandra 集群。

3. 部署 Cassandra 集群 (Origin)

在此 Codelab 中，我们将在 Compute Engine 上设置一个单节点 Cassandra 集群。

1. 为 Cassandra 创建 GCE 虚拟机

如需创建实例，请使用 gcloud compute instances create 命令。

gcloud compute instances create cassandra-origin \
--machine-type=e2-medium \
--image-family=ubuntu-2004-lts \
--image-project=ubuntu-os-cloud \
--tags=cassandra-migration \
--boot-disk-size=20GB

2. 安装 Cassandra

# Install Java (Cassandra dependency)
sudo apt-get update
sudo apt-get install -y openjdk-11-jre-headless

# Add Cassandra repository
echo "deb [https://debian.cassandra.apache.org](https://debian.cassandra.apache.org) 41x main" | sudo tee -a /etc/apt/sources.list.d/cassandra.sources.list
curl [https://downloads.apache.org/cassandra/KEYS](https://downloads.apache.org/cassandra/KEYS) | sudo apt-key add -

# Install Cassandra
sudo apt-get update
sudo apt-get install -y cassandra

3. 创建键空间和表

我们将使用“users”表示例，并创建一个名为“analytics”的键空间。

cd ~/apache-cassandra
bin/cqlsh <your-localhost-ip? 9042  #starts the cql shell

在 cqlsh 中：

-- Create keyspace (adjust replication for production)
CREATE KEYSPACE analytics WITH replication = {'class':'SimpleStrategy', 'replication_factor':1};

-- Use the keyspace
USE analytics;

-- Create the users table
CREATE TABLE users (
    id  int PRIMARY KEY,
    active  boolean,
    username  text,
);

-- Exit cqlsh
EXIT;

让 SSH 会话保持打开状态，或记下此虚拟机的 IP 地址（hostname -I）。

后续步骤

接下来，您将设置 Cloud Spanner 实例和数据库。

4. 创建 Spanner 实例和数据库（目标）

在 Spanner 中，实例是指托管一个或多个 Spanner 数据库的计算和存储资源集群。您需要至少 1 个实例来托管此 Codelab 的 Spanner 数据库。

检查 gcloud SDK 版本

在创建实例之前，请确保 Google Cloud Shell 中的 gcloud SDK 已更新到所需版本 - gcloud SDK 493.0.0。您可以通过以下命令查找 gcloud SDK 版本。

$ gcloud version | grep Google

以下是输出示例：

Google Cloud SDK 489.0.0

如果您使用的版本低于所需的 493.0.0 版本（上例中的 489.0.0），则需要运行以下命令来升级 Google Cloud SDK：

sudo apt-get update \
  && sudo apt-get --only-upgrade install google-cloud-cli-anthoscli google-cloud-cli-cloud-run-proxy kubectl google-cloud-cli-skaffold google-cloud-cli-cbt google-cloud-cli-docker-credential-gcr google-cloud-cli-spanner-migration-tool google-cloud-cli-cloud-build-local google-cloud-cli-pubsub-emulator google-cloud-cli-app-engine-python google-cloud-cli-kpt google-cloud-cli-bigtable-emulator google-cloud-cli-datastore-emulator google-cloud-cli-spanner-emulator google-cloud-cli-app-engine-go google-cloud-cli-app-engine-python-extras google-cloud-cli-config-connector google-cloud-cli-package-go-module google-cloud-cli-istioctl google-cloud-cli-anthos-auth google-cloud-cli-gke-gcloud-auth-plugin google-cloud-cli-app-engine-grpc google-cloud-cli-kubectl-oidc google-cloud-cli-terraform-tools google-cloud-cli-nomos google-cloud-cli-local-extract google-cloud-cli-firestore-emulator google-cloud-cli-harbourbridge google-cloud-cli-log-streaming google-cloud-cli-minikube google-cloud-cli-app-engine-java google-cloud-cli-enterprise-certificate-proxy google-cloud-cli

启用 Spanner API

在 Cloud Shell 中，确保项目 ID 已设置。使用以下第一个命令查找当前配置的项目 ID。如果结果与预期不符，请使用下面的第二个命令设置正确的结果。

gcloud config get-value project

gcloud config set project [YOUR-DESIRED-PROJECT-ID]

将默认区域配置为 us-central1。您可以随意将其更改为 Spanner 区域配置支持的其他区域。

gcloud config set compute/region us-central1

启用 Spanner API：

gcloud services enable spanner.googleapis.com

创建 Spanner 实例

在本部分中，您将创建免费试用实例或预配实例。在本 Codelab 中，使用的 Spanner Cassandra 适配器实例 ID 为 cassandra-adapter-demo，使用 export 命令行设置为 SPANNER_INSTANCE_ID 变量。（可选）您可以选择自己的实例 ID 名称。

创建 Spanner 免费试用实例

拥有 Google 账号且其项目中已启用 Cloud Billing 的任何用户都可以试用 90 天的 Spanner 免费试用实例。除非您选择将免费试用实例升级为付费实例，否则我们不会向您收费。免费试用实例支持 Spanner Cassandra 适配器。如果符合条件，请打开 Cloud Shell 并运行以下命令，创建免费试用实例：

export SPANNER_INSTANCE_ID=cassandra-adapter-demo
export SPANNER_REGION=regional-us-central1
gcloud spanner instances create $SPANNER_INSTANCE_ID \
  --config=$SPANNER_REGION \
  --instance-type=free-instance \
  --description="Spanner Cassandra Adapter demo"

命令输出：

$ gcloud spanner instances create $SPANNER_INSTANCE_ID \
  --config=$SPANNER_REGION \
  --instance-type=free-instance \
  --description="Spanner Cassandra Adapter demo"
Creating instance...done.

创建数据库

实例运行后，您就可以创建数据库了。您可以在数据库中定义架构。您还可以控制哪些人有权访问数据库、设置自定义加密、配置优化器以及设置保留期限。

数据库将在 ID 为 SPANNER_INSTANCE_ID 的实例中创建。

如需创建数据库，请使用 gcloud 命令行工具：

export SPANNER_DATABASE=analytics
gcloud spanner databases create $SPANNER_DATABASE \
 --instance=$SPANNER_INSTANCE_ID

命令输出：

$ gcloud spanner databases create $SPANNER_DATABASE \
 --instance=$SPANNER_INSTANCE_ID
Creating database...done.

5. 将 Cassandra 架构和数据模型迁移到 Spanner

从 Cassandra 数据库将数据转移到 Spanner 的初始阶段至关重要，其中涉及转换现有的 Cassandra 架构，使其符合 Spanner 的结构和数据类型要求。

为了简化这一复杂的架构迁移流程，Spanner 提供了一款名为 Spanner Cassandra 架构工具的实用开源工具。

Spanner Cassandra 架构工具

Spanner Cassandra 架构工具是一款独立的开源工具，用于进行 Spanner 评估和架构迁移。其主要功能是根据现有 Cassandra 架构中找到的定义自动构建 Spanner 架构。该工具通过分析 Cassandra 表结构、数据类型和主键配置，生成等效的 Spanner 表定义，从而显著减少通常在架构转换中涉及的手动工作量。

导出 Cassandra 架构

在使用 Spanner Cassandra 架构工具之前，第一个具体步骤是从当前 Cassandra 集群中提取架构。为此，您可以通过 cqlsh 连接到现有的 Cassandra 集群，然后从 Cassandra 中导出架构：

cqlsh [IP] "-e DESC SCHEMA" > orig_schema.cql

在此命令中，[IP] 应替换为 Cassandra 集群中某个节点的 IP 地址或主机名。命令的 -e DESC SCHEMA 部分会指示 cqlsh 描述 Cassandra 集群的整个架构。然后，此命令的输出（包含 CREATE KEYSPACE 和 CREATE TABLE 语句）会重定向到名为 orig_schema.cql 的文件。

此 orig_schema.cql 文件的内容本质上是 Cassandra 架构的文本蓝图。orig_schema.cql 文件的内容应如下所示：

CREATE KEYSPACE analytics WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'}  AND durable_writes = true;

CREATE TABLE analytics.users (
    id int PRIMARY KEY,
    active boolean,
    username text
) WITH additional_write_policy = '99p'
    AND allow_auto_snapshot = true
    AND bloom_filter_fp_chance = 0.01
    AND caching = {'keys': 'ALL', 'rows_per_partition': 'NONE'}
    AND cdc = false
    AND comment = ''
    AND compaction = {'class': 'org.apache.cassandra.db.compaction.SizeTieredCompactionStrategy', 'max_threshold': '32', 'min_threshold': '4'}
    AND compression = {'chunk_length_in_kb': '16', 'class': 'org.apache.cassandra.io.compress.LZ4Compressor'}
    AND memtable = 'default'
    AND crc_check_chance = 1.0
    AND default_time_to_live = 0
    AND extensions = {}
    AND gc_grace_seconds = 864000
    AND incremental_backups = true
    AND max_index_interval = 2048
    AND memtable_flush_period_in_ms = 0
    AND min_index_interval = 128
    AND read_repair = 'BLOCKING'
    AND speculative_retry = '99p';

克隆代码库

如需使用 Spanner Cassandra 架构工具，下一步是获取该工具的源代码。为此，您需要克隆托管在 GitHub 上的代码库。在 Cloud Shell 中输入以下命令，从 GitHub 克隆 Spanner Cassandra 架构工具：

git clone https://github.com/cloudspannerecosystem/spanner-cassandra-schema-tool.git

然后，将目录更改为您将运行命令的“spanner-cassandra-schema-tool”目录。

cd spanner-cassandra-schema-tool

安装依赖项

Spanner Cassandra 架构工具是使用 Go 编程语言编写的。为确保该工具正常运行，它依赖于某些外部 Go 模块（库）。您需要先下载并管理这些依赖项，然后才能运行该工具。在 spanner-cassandra-schema-tool 目录中，执行以下命令：

go mod download

设置 Google Cloud 凭据

此工具使用应用默认凭据 (ADC) 作为连接到 Spanner 数据库的凭据来源。将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为服务账号密钥文件的路径。

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-file.json"

将 /path/to/your/service-account-file.json 替换为您下载的服务账号密钥文件的实际路径。设置此环境变量可确保 Spanner Cassandra 架构工具能够通过您的 Google Cloud 项目和 Spanner 实例进行安全身份验证。

用法

安装依赖项并配置 Google Cloud 凭据后，您就可以运行 Spanner Cassandra 架构工具，以便根据导出的 Cassandra 架构文件生成 Spanner 架构。在终端或 Cloud Shell 中导航到 spanner-cassandra-schema-tool 目录，然后执行以下 go run 命令：

go run schema_converter.go \
    --project $PROJECT_ID \
    --instance $SPANNER_INSTANCE_ID \
    --database $SPANNER_DATABASE \
    --cql orig_schema.cql \
    --dry-run

使用 --dry-run 选项运行只会生成架构。查看并优化工具生成的数据类型映射和主键列。确保 Spanner 数据类型准确表示相应 Cassandra 数据库类型的范围、精度和语义。

此工具会将 Cassandra 类型映射到 Spanner 类型，如支持的 Cassandra 数据类型中所述。

命令输出如下所示：

.....

[Converted Spanner statement]
CREATE TABLE users (
 id INT64 NOT NULL OPTIONS (cassandra_type = 'int'),
 active BOOL OPTIONS (cassandra_type = 'boolean'),
 username STRING(MAX) OPTIONS (cassandra_type = 'text'),
) PRIMARY KEY (id)
----------------------------------------------
Writing converted Spanner schema to: schema.txt
Dry run enabled. Skipping schema execution.
Schema conversion completed!

如果您还希望将应用架构自动应用于 Spanner，则应在不使用 --dry-run 选项的情况下运行 CLI。

在 Google Cloud 控制台中，验证 Cloud Spanner 数据库中是否存在表和元数据表。

9. 将应用指向 Spanner（切换）

在迁移阶段仔细验证数据的准确性和完整性后，关键步骤是将应用的运维重点从旧版 Cassandra 系统转移到新填充的 Google Cloud Spanner 数据库。这段关键的过渡期通常称为“切换”。

切换阶段是指实时应用流量从原始 Cassandra 集群重定向并直接连接到强大且可伸缩的 Spanner 基础架构的时刻。这一转变证明，应用可以轻松利用 Spanner 的强大功能，尤其是在使用 Spanner Cassandra 接口时。

借助 Spanner Cassandra 接口，您可以简化切换流程。主要涉及配置客户端应用，以便使用原生 Spanner Cassandra 客户端进行所有数据交互。应用将开始直接向 Spanner（目标）读写数据，而不是与 Cassandra（源）数据库通信。这种连接方式的根本转变通常是通过使用 SpannerCqlSessionBuilder 实现的，它是 Spanner Cassandra 客户端库的关键组件，有助于建立与 Spanner 实例的连接。这会有效地将应用的整个数据流量重定向到 Spanner。

对于已在使用 cassandra-java-driver 库的 Java 应用，集成 Spanner Cassandra Java 客户端只需对 CqlSession 初始化进行细微更改。

获取 google-cloud-spanner-cassandra 依赖项

如需开始使用 Spanner Cassandra 客户端，您需要先将其依赖项纳入到您的项目中。google-cloud-spanner-cassandra 工件会发布在 Maven Central 的组 ID com.google.cloud 下。在 Java 项目的现有 <dependencies> 部分下方添加以下新依赖项。下面是一个简化示例，展示了如何添加 google-cloud-spanner-cassandra 依赖项：

<!-- native Spanner Cassandra Client -->
<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-spanner-cassandra</artifactId>
    <version>0.2.0</version>
  </dependency>
</dependencies>

更改连接配置以连接到 Spanner

添加必要的依赖项后，下一步是更改连接配置以连接到 Spanner 数据库。

与 Cassandra 集群交互的典型应用通常会使用类似以下代码来建立连接：

CqlSession session = CqlSession.builder()
        .addContactPoint(new InetSocketAddress("127.0.0.1", 9042))
        .withLocalDatacenter("datacenter1")
        .withAuthCredentials("username", "password")
        .build();

如需将此连接重定向到 Spanner，您需要修改 CqlSession 创建逻辑。您将使用 Spanner Cassandra 客户端提供的 SpannerCqlSession.builder()，而不是直接使用 cassandra-java-driver 中的标准 CqlSessionBuilder。以下示例展示了如何修改连接代码：

String databaseUri = "projects/<your-gcp-project>/instances/<your-spanner-instance>/databases/<your-spanner-database>";

CqlSession session = SpannerCqlSession.builder()
        .setDatabaseUri(databaseUri)
        .addContactPoint(new InetSocketAddress("localhost", 9042))
        .withLocalDatacenter("datacenter1")
        .build();

通过使用 SpannerCqlSession.builder() 实例化 CqlSession 并提供正确的 databaseUri，您的应用现在将通过 Spanner Cassandra 客户端与目标 Spanner 数据库建立连接。这项关键变更可确保应用执行的所有后续读写操作都将转到 Spanner 并由其处理，从而有效完成初始切换。至此，您的应用应该会继续按预期运行，并且现在由 Spanner 的可伸缩性和可靠性提供支持。

运作原理：Spanner Cassandra 客户端的运作方式

Spanner Cassandra 客户端充当本地 TCP 代理，拦截驱动程序或客户端工具发送的原始 Cassandra 协议字节。然后，它会将这些字节以及必要的元数据封装到 gRPC 消息中，以便与 Spanner 进行通信。Spanner 中的响应会转换回 Cassandra 线格格式，然后发送回发起驱动程序或工具。

确信 Spanner 正确处理所有流量后，您最终可以：

停止双重写入。
停用原始 Cassandra 集群。

10. 清理（可选）

如需进行清理，只需进入 Cloud 控制台的 Spanner 部分，然后删除我们在 Codelab 中创建的 cassandra-adapter-demo 实例即可。

删除 Cassandra 数据库（如果本地安装或持久化）

如果您在本教程中创建的 Compute Engine 虚拟机之外安装了 Cassandra，请按照相应步骤移除数据或卸载 Cassandra。

11. 恭喜！

后续操作

详细了解 Cloud Spanner。
详细了解 Cassandra 接口。

报告错误

Spanner Cassandra Adapter 使用入门

Spanner Cassandra Adapter 使用入门

关于此 Codelab

1. 简介

学习内容

所需条件

2. 设置和要求

创建 GCP 项目

结算设置

启动 Cloud Shell

后续步骤

3. 部署 Cassandra 集群 (Origin)

1. 为 Cassandra 创建 GCE 虚拟机

2. 安装 Cassandra

3. 创建键空间和表

后续步骤

4. 创建 Spanner 实例和数据库（目标）

检查 gcloud SDK 版本

启用 Spanner API

创建 Spanner 实例

创建 Spanner 免费试用实例

创建数据库

5. 将 Cassandra 架构和数据模型迁移到 Spanner

Spanner Cassandra 架构工具

导出 Cassandra 架构

克隆代码库

安装依赖项

设置 Google Cloud 凭据

用法

6. 为传入数据设置双写入

7. 批量导出历史数据

8. 验证数据

9. 将应用指向 Spanner（切换）

获取 google-cloud-spanner-cassandra 依赖项

更改连接配置以连接到 Spanner

运作原理：Spanner Cassandra 客户端的运作方式

10. 清理（可选）

删除 Cassandra 数据库（如果本地安装或持久化）

11. 恭喜！

后续操作