程式碼研究室簡介
1. 簡介
Spanner 是一項全代管、可水平擴充、全球分散式資料庫服務，適合用於關聯和非關聯工作負載。
透過 Spanner 的 Cassandra 介面，您可以使用熟悉的 Cassandra 工具和語法，充分利用 Spanner 的全代管、可擴充且具備高可用性的基礎架構。
課程內容
- 如何設定 Spanner 執行個體和資料庫。
- 如何轉換 Cassandra 結構定義和資料模型。
- 如何部署及設定傳入資料的雙重寫入功能。
- 如何將歷史資料大量匯出，從 Cassandra 匯出至 Spanner。
- 如何驗證資料，確保整個遷移程序的資料完整性。
- 如何將應用程式指向 Spanner 而非 Cassandra。
軟硬體需求
- 已連結至帳單帳戶的 Google Cloud 專案。
- 使用已安裝及設定
gcloudCLI 的機器，或使用 Google Cloud Shell。 - 網路瀏覽器，例如 Chrome 或 Firefox。
2. 設定和需求
建立 GCP 專案
登入 Google Cloud 控制台，然後建立新專案或重複使用現有專案。如果您還沒有 Gmail 或 Google Workspace 帳戶，請務必建立帳戶。
- 「Project name」是這個專案參與者的顯示名稱。這是 Google API 不會使用的字元字串。您隨時可以更新。
- 專案 ID 在所有 Google Cloud 專案中都是不重複的值，且無法變更 (設定後即無法變更)。Cloud 控制台會自動產生唯一字串，您通常不需要理會這個字串。在大多數程式碼研究室中，您需要參照專案 ID (通常會標示為
PROJECT_ID)。如果您不喜歡產生的 ID，可以產生另一個隨機 ID。或者，您也可以自行嘗試，看看是否可用。在這個步驟後就無法變更，且會在專案期間維持不變。 - 提醒您，有些 API 會使用第三個值「專案編號」。如要進一步瞭解這三個值，請參閱說明文件。
帳單設定
接下來，您必須按照帳單管理使用者指南的說明，在 Cloud Console 中啟用帳單功能。Google Cloud 新使用者可享有價值 $300 美元的免費試用期。為避免產生教學課程以外的費用，您可以在程式碼研究室結束時關閉 Spanner 執行個體，方法是按照「步驟 9：清理」操作。
啟動 Cloud Shell
雖然 Google Cloud 可透過筆記型電腦遠端操作，但在本程式碼研究室中，您將使用 Google Cloud Shell，這是在雲端運作的指令列環境。
在 Google Cloud 控制台中，按一下右上方工具列的 Cloud Shell 圖示：
佈建並連線至環境的作業需要一些時間才能完成。完成後，畫面應如下所示：
這個虛擬機器會載入您需要的所有開發工具。提供永久的 5 GB 主目錄，而且在 Google Cloud 中運作，大幅提升網路效能和驗證功能。您可以在瀏覽器中完成本程式碼研究室的所有工作。您不需要安裝任何東西。
下一步
接下來，您將部署 Cassandra 叢集。
3. 部署 Cassandra 叢集 (Origin)
在本程式碼研究室中，我們會在 Compute Engine 上設定單節點 Cassandra 叢集。
1. 為 Cassandra 建立 GCE VM
如要建立執行個體，請使用 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. 建立鍵值空間和資料表
我們將使用使用者資料表範例，並建立名為「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 工作階段，或記下這個 VM 的 IP 位址 (hostname -I)。
下一步
接下來，您將設定 Cloud Spanner 執行個體和資料庫。
4. 建立 Spanner 例項和資料庫 (目標)
在 Spanner 中，執行個體是運算和儲存資源的叢集，可代管一或多個 Spanner 資料庫。您至少需要 1 個執行個體，才能為本程式碼研究室託管 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 執行個體
在本節中，您將建立免費試用執行個體或已佈建的執行個體。在本程式碼研究室中，使用的 Spanner Cassandra 轉接器執行個體 ID 為 cassandra-adapter-demo，並使用 export 指令列設為 SPANNER_INSTANCE_ID 變數。您也可以選擇自行選擇執行個體 ID 名稱。
建立 Spanner 免付費試用執行個體
凡是擁有 Google 帳戶，且專案已啟用 Cloud Billing 的使用者，都可以使用 Spanner 90 天的免費試用執行個體。除非您選擇將免費試用版執行個體升級為付費執行個體，否則我們不會向您收費。免費試用執行個體支援 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 選項。
在 Google Cloud 控制台中確認資料表和中繼資料表是否存在於 Cloud Spanner 資料庫中。
6. 為傳入資料設定雙重寫入
[TODO]
7. 大量匯出歷來資料
[TODO]
8. 驗證資料
[TODO]
9. 將應用程式指向 Spanner (系統截承)
在遷移階段後，仔細驗證資料的準確性和完整性後，關鍵步驟就是將應用程式的營運重點，從舊版 Cassandra 系統轉移至新填入的 Google Cloud Spanner 資料庫。這個關鍵的轉換期通常稱為「轉換」。
轉換階段是指即時應用程式流量從原始 Cassandra 叢集重新導向，並直接連線至可靠且可擴充的 Spanner 基礎架構的時間點。這項轉換作業說明應用程式如何輕鬆運用 Spanner 的強大功能，尤其是在使用 Spanner Cassandra 介面時。
透過 Spanner Cassandra 介面，可簡化轉換程序。這項作業主要涉及設定用戶端應用程式，以便在所有資料互動中使用原生 Spanner Cassandra 用戶端。應用程式將不再與 Cassandra (來源) 資料庫通訊，而是直接開始讀取及寫入資料至 Spanner (目標)。這項連線方式的根本轉變通常是透過使用 SpannerCqlSessionBuilder 來達成，這是 Spanner Cassandra 用戶端程式庫的重要元件，可協助建立與 Spanner 執行個體的連線。這麼做可有效地將應用程式的整個資料流量重新導向至 Spanner。
如果 Java 應用程式已使用 cassandra-java-driver 程式庫，整合 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 Proxy 的角色，攔截由驅動程式或用戶端工具傳送的原始 Cassandra 通訊協定位元組。然後將這些位元組連同必要的中繼資料包裝成 gRPC 訊息，以便與 Spanner 進行通訊。Spanner 的回應會轉譯回 Cassandra 線路格式，並傳回給原始驅動程式或工具。
確認 Spanner 可正確提供所有流量後，您可以最終執行以下操作：
- 停止雙重寫入。
- 停用原始 Cassandra 叢集。
10. 清理 (選用)
如要清理，請前往 Cloud 控制台的 Spanner 專區，刪除我們在程式碼研究室中建立的 cassandra-adapter-demo 執行個體。
刪除 Cassandra 資料庫 (如果已在本機安裝或保留)
如果您是在本頁所建立的 Compute Engine VM 外部安裝 Cassandra，請按照適當步驟移除資料或卸載 Cassandra。