การเริ่มต้นใช้งาน Spanner Cassandra Adapter

1. บทนำ

Spanner เป็นบริการฐานข้อมูลที่มีการจัดการครบวงจร ปรับขนาดในแนวนอนได้ และมีการกระจายทั่วโลก ซึ่งเหมาะสำหรับภาระงานทั้งแบบเชิงสัมพันธ์และไม่ใช่เชิงสัมพันธ์

อินเทอร์เฟซ Cassandra ของ Spanner ช่วยให้คุณใช้ประโยชน์จากโครงสร้างพื้นฐานที่มีการจัดการครบวงจร ปรับขนาดได้ และมีความพร้อมใช้งานสูงของ Spanner ได้โดยใช้เครื่องมือและไวยากรณ์ของ Cassandra ที่คุ้นเคย

สิ่งที่คุณจะได้เรียนรู้

วิธีตั้งค่าอินสแตนซ์และฐานข้อมูล Spanner
วิธีแปลงสคีมาและโมเดลข้อมูล Cassandra
วิธีส่งออกข้อมูลประวัติจาก Cassandra ไปยัง Spanner เป็นกลุ่ม
วิธีชี้แอปพลิเคชันไปยัง Spanner แทน Cassandra

สิ่งที่คุณต้องมี

โปรเจ็กต์ Google Cloud ที่เชื่อมต่อกับบัญชีสำหรับการเรียกเก็บเงิน
สิทธิ์เข้าถึงเครื่องที่ติดตั้งและกำหนดค่า gcloud CLI หรือใช้ Google Cloud Shell
เว็บเบราว์เซอร์ เช่น Chrome หรือ Firefox

2. การตั้งค่าและข้อกำหนด

สร้างโปรเจ็กต์ GCP

ลงชื่อเข้าใช้ คอนโซล Google Cloud แล้วสร้างโปรเจ็กต์ใหม่หรือใช้โปรเจ็กต์ที่มีอยู่ซ้ำ หากยังไม่มีบัญชี Gmail หรือ Google Workspace คุณต้องสร้างบัญชี

ชื่อโปรเจ็กต์คือชื่อที่แสดงสำหรับผู้เข้าร่วมโปรเจ็กต์นี้ ซึ่งเป็นสตริงอักขระที่ Google APIs ไม่ได้ใช้ คุณอัปเดตได้ทุกเมื่อ
รหัสโปรเจ็กต์จะไม่ซ้ำกันในโปรเจ็กต์ Google Cloud ทั้งหมดและเปลี่ยนแปลงไม่ได้ (เปลี่ยนไม่ได้หลังจากตั้งค่าแล้ว) Cloud Console จะสร้างสตริงที่ไม่ซ้ำกันโดยอัตโนมัติ ซึ่งโดยปกติแล้วคุณไม่จำเป็นต้องสนใจว่าสตริงนั้นคืออะไร ใน Codelab ส่วนใหญ่ คุณจะต้องอ้างอิงรหัสโปรเจ็กต์ (โดยทั่วไปจะระบุเป็น PROJECT_ID) หากไม่ชอบรหัสที่สร้างขึ้น คุณอาจสร้างรหัสแบบสุ่มอีกรหัสหนึ่งได้ หรือคุณอาจลองใช้ชื่อของคุณเองและดูว่ามีชื่อนั้นหรือไม่ คุณจะเปลี่ยนแปลงรหัสนี้หลังจากขั้นตอนนี้ไม่ได้ และรหัสจะคงอยู่ตลอดระยะเวลาของโปรเจ็กต์
โปรดทราบว่ายังมีค่าที่ 3 ซึ่งคือหมายเลขโปรเจ็กต์ที่ API บางตัวใช้ ดูข้อมูลเพิ่มเติมเกี่ยวกับค่าทั้ง 3 นี้ได้ในเอกสารประกอบ

การตั้งค่าการเรียกเก็บเงิน

จากนั้นคุณจะต้องทำตามคู่มือผู้ใช้การจัดการการเรียกเก็บเงินและเปิดใช้การเรียกเก็บเงินใน Cloud Console ผู้ใช้ Google Cloud รายใหม่มีสิทธิ์เข้าร่วมโปรแกรมช่วงทดลองใช้ฟรีมูลค่า$300 USD หากไม่ต้องการให้มีการเรียกเก็บเงินนอกเหนือจากบทแนะนำนี้ คุณสามารถปิดอินสแตนซ์ Spanner เมื่อสิ้นสุด Codelab ได้โดยทำตาม "ขั้นตอนที่ 9 การล้างข้อมูล"

เริ่มต้น Cloud Shell

แม้ว่าคุณจะใช้งาน Google Cloud จากระยะไกลในแล็ปท็อปได้ แต่ใน Codelab นี้คุณจะใช้ Google Cloud Shell ซึ่งเป็นสภาพแวดล้อมบรรทัดคำสั่งที่ทำงานในระบบคลาวด์

จาก คอนโซล Google Cloud ให้คลิกไอคอน Cloud Shell ในแถบเครื่องมือด้านขวาบน

การจัดสรรและเชื่อมต่อกับสภาพแวดล้อมจะใช้เวลาเพียงไม่กี่นาที เมื่อเสร็จแล้ว คุณควรเห็นข้อความคล้ายกับตัวอย่างต่อไปนี้

เครื่องเสมือนนี้มาพร้อมเครื่องมือพัฒนาซอฟต์แวร์ทั้งหมดที่คุณต้องการ โดยมีไดเรกทอรีหลักแบบถาวรขนาด 5 GB และทำงานบน Google Cloud ซึ่งช่วยเพิ่มประสิทธิภาพเครือข่ายและการตรวจสอบสิทธิ์ได้อย่างมาก คุณสามารถทำงานทั้งหมดใน Codelab นี้ได้ภายในเบราว์เซอร์ คุณไม่จำเป็นต้องติดตั้งอะไร

จากนั้นคุณจะติดตั้งใช้งานคลัสเตอร์ Cassandra

3. ทำให้ใช้งานได้คลัสเตอร์ Cassandra (ต้นทาง)

สำหรับ Codelab นี้ เราจะตั้งค่าคลัสเตอร์ Cassandra แบบโหนดเดียวใน Compute Engine

1. สร้าง VM ใน GCE สำหรับ Cassandra

หากต้องการสร้างอินสแตนซ์ ให้ใช้คำสั่ง gcloud compute instances create จาก Cloud Shell ที่จัดสรรไว้ก่อนหน้านี้

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

2. ติดตั้ง Cassandra

ไปที่ VM Instances จากหน้า Navigation menu โดยทำตามวิธีการด้านล่าง ไปที่อินสแตนซ์ VM

ค้นหา VM cassandra-origin แล้วเชื่อมต่อกับ VM โดยใช้ SSH ดังที่แสดง

SSH เข้าสู่อินสแตนซ์ VM

เรียกใช้คำสั่งต่อไปนี้เพื่อติดตั้ง Cassandra ใน VM ที่คุณสร้างและใช้ SSH เข้าถึง

ติดตั้ง Java (ทรัพยากร Dependency ของ Cassandra)

sudo apt-get update
sudo apt-get install -y openjdk-11-jre-headless

เพิ่มที่เก็บ Cassandra

echo "deb [signed-by=/etc/apt/keyrings/apache-cassandra.asc] https://debian.cassandra.apache.org 41x main" | sudo tee -a /etc/apt/sources.list.d/cassandra.sources.list

sudo curl -o /etc/apt/keyrings/apache-cassandra.asc https://downloads.apache.org/cassandra/KEYS

ติดตั้ง Cassandra

sudo apt-get update
sudo apt-get install -y cassandra

ตั้งค่าที่อยู่ที่ใช้ฟังสำหรับบริการ Cassandra

ในที่นี้เราใช้ที่อยู่ IP ภายในของ VM Cassandra เพื่อเพิ่มความปลอดภัย

จดที่อยู่ IP ของเครื่องโฮสต์

คุณจะใช้คำสั่งต่อไปนี้ใน Cloud Shell หรือรับจากหน้า VM Instances ของ Cloud Console ก็ได้

gcloud compute instances describe cassandra-origin --format="get(networkInterfaces[0].networkIP)" --zone=us-central1-a

หรือ

SSH เข้าสู่อินสแตนซ์ VM

อัปเดตที่อยู่ในไฟล์การกำหนดค่า

คุณสามารถใช้โปรแกรมแก้ไขที่ต้องการเพื่ออัปเดตไฟล์การกำหนดค่า Cassandra

sudo vim /etc/cassandra/cassandra.yaml

เปลี่ยน rpc_address: เป็นที่อยู่ IP ของ VM บันทึกและปิดไฟล์

เปิดใช้บริการ Cassandra ใน VM

sudo systemctl enable cassandra
sudo systemctl stop cassandra
sudo systemctl start cassandra
sudo systemctl status cassandra

3. สร้างคีย์สเปซและตาราง {create-keyspace-and-table}

เราจะใช้ตัวอย่างตาราง "users" และสร้างคีย์สเปซชื่อ "analytics"

export CQLSH_HOST=<IP of the VM added as rpc_address>
/usr/bin/cqlsh

ภายใน 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,
);

-- Insert 5 rows
INSERT INTO users (id, active, username) VALUES (1, true, 'd_knuth');
INSERT INTO users (id, active, username) VALUES (2, true, 'sanjay_ghemawat');
INSERT INTO users (id, active, username) VALUES (3, false, 'gracehopper');
INSERT INTO users (id, active, username) VALUES (4, true, 'brian_kernighan');
INSERT INTO users (id, active, username) VALUES (5, true, 'jeff_dean');
INSERT INTO users (id, active, username) VALUES (6, true, 'jaime_levy');
-- Select all users to verify the inserts.
SELECT * from users;
-- Exit cqlsh
EXIT;

เปิดเซสชัน SSH ไว้หรือจดที่อยู่ IP ของ VM นี้ (hostname -I)

จากนั้นคุณจะตั้งค่าอินสแตนซ์และฐานข้อมูล Cloud Spanner

4. สร้างอินสแตนซ์ Spanner (เป้าหมาย)

ใน Spanner อินสแตนซ์คือคลัสเตอร์ของทรัพยากรการคำนวณและพื้นที่เก็บข้อมูลที่โฮสต์ฐานข้อมูล Spanner อย่างน้อย 1 รายการ คุณจะต้องมีอินสแตนซ์อย่างน้อย 1 รายการเพื่อโฮสต์ฐานข้อมูล Spanner สำหรับ Codelab นี้

ตรวจสอบเวอร์ชัน gcloud SDK

ก่อนสร้างอินสแตนซ์ โปรดตรวจสอบว่าได้อัปเดต gcloud SDK ใน Google Cloud Shell เป็นเวอร์ชันที่จำเป็นแล้ว ซึ่งก็คือเวอร์ชันที่สูงกว่า gcloud SDK 531.0.0 คุณดูเวอร์ชัน gcloud SDK ได้โดยใช้คำสั่งด้านล่าง

$ gcloud version | grep Google

ตัวอย่างเอาต์พุต

Google Cloud SDK 489.0.0

หากเวอร์ชันที่คุณใช้อยู่เก่ากว่าเวอร์ชัน 531.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 แล้ว ใช้คำสั่งแรกด้านล่างเพื่อค้นหารหัสโปรเจ็กต์ที่กำหนดค่าไว้ในปัจจุบัน หากผลลัพธ์ไม่เป็นไปตามที่คาดไว้ คำสั่งที่ 2 ด้านล่างจะตั้งค่าที่ถูกต้อง

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 Adapter ที่ใช้คือ cassandra-adapter-demo ซึ่งตั้งค่าเป็นตัวแปร SPANNER_INSTANCE_ID โดยใช้บรรทัดคำสั่ง export คุณเลือกชื่อรหัสอินสแตนซ์เองได้ (ไม่บังคับ)

สร้างอินสแตนซ์ Spanner แบบทดลองใช้ฟรี

อินสแตนซ์ทดลองใช้ฟรีของ Spanner เป็นเวลา 90 วันพร้อมให้บริการแก่ทุกคนที่มีบัญชี Google และเปิดใช้การเรียกเก็บเงินใน Cloud ในโปรเจ็กต์ของตน ระบบจะไม่เรียกเก็บเงินจากคุณ เว้นแต่คุณจะเลือกอัปเกรดอินสแตนซ์ทดลองใช้ฟรีเป็นอินสแตนซ์แบบชำระเงิน อินสแตนซ์ช่วงทดลองใช้ฟรีรองรับ Spanner Cassandra Adapter หากมีสิทธิ์ ให้สร้างอินสแตนซ์ช่วงทดลองใช้ฟรีโดยเปิด 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.

5. ย้ายสคีมาและโมเดลข้อมูล Cassandra ไปยัง Spanner

ระยะเริ่มต้นและสำคัญของการเปลี่ยนข้อมูลจากฐานข้อมูล Cassandra ไปยัง Spanner เกี่ยวข้องกับการแปลงสคีมา Cassandra ที่มีอยู่ให้สอดคล้องกับข้อกำหนดด้านโครงสร้างและประเภทข้อมูลของ Spanner

หากต้องการเพิ่มประสิทธิภาพกระบวนการย้ายข้อมูลสคีมาที่ซับซ้อนนี้ ให้ใช้เครื่องมือโอเพนซอร์สที่มีประโยชน์ 2 รายการที่ Spanner จัดเตรียมไว้ให้

เครื่องมือย้ายข้อมูล Spanner: เครื่องมือนี้ช่วยคุณย้ายข้อมูลสคีมาโดยเชื่อมต่อกับฐานข้อมูล Cassandra ที่มีอยู่และย้ายข้อมูลสคีมาไปยัง Spanner เครื่องมือนี้พร้อมให้บริการใน gcloud cli
เครื่องมือสคีมา Spanner Cassandra: เครื่องมือนี้ช่วยแปลง DDL ที่ส่งออกจาก Cassandra เป็น Spanner คุณสามารถใช้เครื่องมือใดก็ได้จาก 2 เครื่องมือนี้สำหรับ Codelab ใน Codelab นี้ เราจะใช้เครื่องมือย้ายข้อมูล Spanner เพื่อย้ายข้อมูลสคีมา

เครื่องมือย้ายข้อมูล Spanner

เครื่องมือย้ายข้อมูล Spanner ช่วยย้ายข้อมูลสคีมาจากแหล่งข้อมูลต่างๆ เช่น MySQL, Postgres, Cassandra เป็นต้น

แม้ว่าเราจะใช้ CLI ของเครื่องมือนี้เพื่อวัตถุประสงค์ของ Codelab นี้ แต่เราขอแนะนำอย่างยิ่งให้คุณสำรวจและใช้เครื่องมือเวอร์ชันที่ใช้ UI ซึ่งจะช่วยให้คุณแก้ไขสคีมา Spanner ก่อนที่จะนำไปใช้ได้ด้วย

โปรดทราบว่าหากเรียกใช้ spanner-migration-tool ใน Cloud Shell อาจไม่มีสิทธิ์เข้าถึงที่อยู่ IP ภายในของ VM Cassandra ดังนั้น เราขอแนะนำให้เรียกใช้คำสั่งเดียวกันใน VM ที่คุณติดตั้ง Cassandra

เรียกใช้คำสั่งต่อไปนี้ใน VM ที่คุณติดตั้ง Cassandra

ติดตั้งเครื่องมือย้ายข้อมูล Spanner

sudo apt-get update
sudo apt-get install --upgrade google-cloud-sdk-spanner-migration-tool

หากพบปัญหาในการติดตั้ง โปรดดูขั้นตอนโดยละเอียดที่installing-spanner-migration-tool

รีเฟรชข้อมูลเข้าสู่ระบบ gcloud

gcloud auth login
gcloud auth application-default login

ย้ายสคีมา

export CASSANDRA_HOST=`<ip address of the VM used as rpc_address above>`
export PROJECT=`<PROJECT_ID>`
gcloud alpha spanner migrate schema \
  --source=cassandra \
  --source-profile="host=${CASSANDRA_HOST},user=cassandra,password=cassandra,port=9042,keyspace=analytics,datacenter=datacenter1" \
  --target-profile="project=${PROJECT},instance=cassandra-adapter-demo,dbName=analytics" \
  --project=${PROJECT}

ยืนยัน DDL ของ Spanner

gcloud spanner databases ddl describe analytics --instance=cassandra-adapter-demo

เมื่อสิ้นสุดการย้ายข้อมูลสคีมา เอาต์พุตของคำสั่งนี้ควรเป็นดังนี้

CREATE TABLE users (
  active BOOL OPTIONS (
    cassandra_type = 'boolean'
  ),
  id INT64 NOT NULL OPTIONS (
    cassandra_type = 'int'
  ),
  username STRING(MAX) OPTIONS (
    cassandra_type = 'text'
  ),
) PRIMARY KEY(id);

(ไม่บังคับ) ดู DDL ที่แปลงแล้ว

คุณสามารถดู DDL ที่แปลงแล้วและนำไปใช้ใหม่ใน Spanner ได้ (หากต้องการเปลี่ยนแปลงเพิ่มเติม)

cat `ls -t cassandra_*schema.ddl.txt  | head -n 1`

เอาต์พุตของคำสั่งนี้จะเป็นดังนี้

CREATE TABLE `users` (
        `active` BOOL OPTIONS (cassandra_type = 'boolean'),
        `id` INT64 NOT NULL  OPTIONS (cassandra_type = 'int'),
        `username` STRING(MAX) OPTIONS (cassandra_type = 'text'),
) PRIMARY KEY (`id`)

(ไม่บังคับ) ดูรายงาน Conversion

cat `ls -t cassandra_*report.txt  | head -n 1`

รายงาน Conversion จะไฮไลต์ปัญหาที่คุณควรทราบ เช่น หากความแม่นยำสูงสุดของคอลัมน์ระหว่างแหล่งที่มากับ Spanner ไม่ตรงกัน ระบบจะไฮไลต์ที่นี่

6. ส่งออกข้อมูลประวัติแบบเป็นกลุ่ม

หากต้องการย้ายข้อมูลหลายรายการพร้อมกัน คุณจะต้องดำเนินการต่อไปนี้

จัดสรรหรือนำ Bucket ของ GCS ที่มีอยู่มาใช้ซ้ำ
อัปโหลดไฟล์การกำหนดค่า Cassandra Driver ไปยัง Bucket
เปิดตัวการย้ายข้อมูลแบบกลุ่ม

แม้ว่าคุณจะเปิดใช้การย้ายข้อมูลแบบเป็นกลุ่มจาก Cloud Shell หรือ VM ที่จัดสรรใหม่ได้ แต่เราขอแนะนำให้ใช้ VM สำหรับ Codelab นี้ เนื่องจากขั้นตอนบางอย่าง เช่น การสร้างไฟล์การกำหนดค่า จะเก็บไฟล์ไว้ในพื้นที่เก็บข้อมูลในเครื่อง

จัดสรร Bucket ของ GCS

เมื่อสิ้นสุดขั้นตอนนี้ คุณควรจัดสรร Bucket ของ GCS และส่งออกเส้นทางในตัวแปรชื่อ CASSANDRA_BUCKET_NAME หากต้องการใช้ที่เก็บข้อมูลที่มีอยู่ซ้ำ คุณก็เพียงแค่ส่งออกเส้นทาง

if [ -z ${CASSANDRA_BUCKET_NAME} ]; then
  export CASSANDRA_BUCKET_NAME="gs://cassandra-demo-$(date +%Y-%m-%d-%H-%M-%S)-$(head /dev/urandom | tr -dc a-z | head -c 20)"
  gcloud storage buckets create "${CASSANDRA_BUCKET_NAME}"
else
  echo "using existing bucket ${CASSANDRA_BUCKET_NAME}"
fi

สร้างและอัปโหลดไฟล์การกำหนดค่าไดรเวอร์

ในที่นี้ เราจะอัปโหลดไฟล์การกำหนดค่าไดรเวอร์ Cassandra พื้นฐาน โปรดดูรูปแบบไฟล์ทั้งหมดที่นี่

# Configuration for the Cassandra instance and GCS bucket
INSTANCE_NAME="cassandra-origin"
ZONE="us-central1-a"
CASSANDRA_PORT="9042"

# Retrieve the internal IP address of the Cassandra instance
CASSANDRA_IP=$(gcloud compute instances describe "${INSTANCE_NAME}" \
    --format="get(networkInterfaces[0].networkIP)" \
    --zone="${ZONE}")

# Check if the IP was successfully retrieved
if [[ -z "${CASSANDRA_IP}" ]]; then
    echo "Error: Could not retrieve Cassandra instance IP."
    exit 1
fi

# Define the full contact point
CONTACT_POINT="${CASSANDRA_IP}:${CASSANDRA_PORT}"

# Create a temporary file with the specified content
TMP_FILE=$(mktemp)
cat <<EOF > "${TMP_FILE}"
# Reference configuration for the DataStax Java driver for Apache Cassandra®.
# This file is in HOCON format, see https://github.com/typesafehub/config/blob/master/HOCON.md.
datastax-java-driver {
  basic.contact-points = ["${CONTACT_POINT}"]
  basic.session-keyspace = analytics
  basic.load-balancing-policy.local-datacenter = datacenter1
  advanced.auth-provider {
    class = PlainTextAuthProvider
    username = cassandra
    password = cassandra
  }
}
EOF

# Upload the temporary file to the specified GCS bucket
if gsutil cp "${TMP_FILE}" "${CASSANDRA_BUCKET_NAME}/cassandra.conf"; then
    echo "Successfully uploaded ${TMP_FILE} to ${CASSANDRA_BUCKET_NAME}/cassandra.conf"

    # Concatenate (cat) the uploaded file from GCS
    echo "Displaying the content of the uploaded file:"
    gsutil cat "${CASSANDRA_BUCKET_NAME}/cassandra.conf"
else
    echo "Error: Failed to upload file to GCS."
fi

# Clean up the temporary file
rm "${TMP_FILE}"

เรียกใช้การย้ายข้อมูลแบบกลุ่ม

นี่คือตัวอย่างคำสั่งที่ใช้เรียกใช้การย้ายข้อมูลจำนวนมากไปยัง Spanner สำหรับกรณีการใช้งานจริงในเวอร์ชันที่ใช้งานจริง คุณจะต้องปรับประเภทเครื่องและจำนวนตามขนาดและอัตราการส่งข้อมูลที่ต้องการ โปรดไปที่ README_Sourcedb_to_Spanner.md#cassandra-to-spanner-bulk-migration เพื่อดูรายการตัวเลือกทั้งหมด

gcloud dataflow flex-template run "sourcedb-to-spanner-flex-job" \
  --project "`gcloud config get-value project`" \
  --region "us-central1" \
  --max-workers "2" \
  --num-workers "1" \
  --worker-machine-type "e2-standard-8" \
  --template-file-gcs-location "gs://dataflow-templates-us-central1/latest/flex/Sourcedb_to_Spanner_Flex" \
  --additional-experiments="[\"disable_runner_v2\"]" \
  --parameters "sourceDbDialect=CASSANDRA" \
  --parameters "insertOnlyModeForSpannerMutations=true" \
  --parameters "sourceConfigURL=$CASSANDRA_BUCKET_NAME/cassandra.conf" \
  --parameters "instanceId=cassandra-adapter-demo" \
  --parameters "databaseId=analytics" \
  --parameters "projectId=`gcloud config get-value project`" \
  --parameters "outputDirectory=$CASSANDRA_BUCKET_NAME/output" \
  --parameters "batchSizeForSpannerMutations=1"

ซึ่งจะสร้างเอาต์พุตดังต่อไปนี้ จดบันทึก id ที่สร้างขึ้นและใช้รหัสเดียวกันเพื่อค้นหาสถานะของงาน Dataflow

job:
  createTime: '2025-08-08T09:41:09.820267Z'
  currentStateTime: '1970-01-01T00:00:00Z'
  id: 2025-08-08_02_41_09-17637291823018196600
  location: us-central1
  name: sourcedb-to-spanner-flex-job
  projectId: span-cloud-ck-testing-external
  startTime: '2025-08-08T09:41:09.820267Z'

เรียกใช้คำสั่งด้านล่างเพื่อตรวจสอบสถานะของงานและรอจนกว่าสถานะจะเปลี่ยนเป็น JOB_STATE_DONE

gcloud dataflow jobs describe --region=us-central1 <dataflow job id> | grep "currentState:"

ในตอนแรก งานจะมีสถานะอยู่ในคิว เช่น

currentState: JOB_STATE_QUEUED

ขณะที่งานอยู่ในคิว/กำลังทำงาน เราขอแนะนำให้คุณสำรวจDataflow/Jobsหน้าใน UI ของ Cloud Console เพื่อตรวจสอบงาน

เมื่อดำเนินการเสร็จแล้ว สถานะของงานจะเปลี่ยนเป็น

currentState: JOB_STATE_DONE

7. ชี้แอปพลิเคชันไปยัง Spanner (Cutover)

หลังจากตรวจสอบความถูกต้องและความสมบูรณ์ของข้อมูลอย่างละเอียดตามระยะการย้ายข้อมูลแล้ว ขั้นตอนสำคัญคือการเปลี่ยนโฟกัสการทำงานของแอปพลิเคชันจากระบบ Cassandra เดิมไปยังฐานข้อมูล Spanner ที่ป้อนข้อมูลใหม่ โดยทั่วไปแล้ว ระยะเปลี่ยนผ่านที่สำคัญนี้เรียกว่า "การเปลี่ยนระบบ"

ระยะ Cutover เป็นช่วงเวลาที่การรับส่งข้อมูลแอปพลิเคชันที่ใช้งานจริงจะเปลี่ยนเส้นทางออกจากคลัสเตอร์ Cassandra เดิมและเชื่อมต่อโดยตรงกับโครงสร้างพื้นฐาน Spanner ที่มีประสิทธิภาพและรองรับการปรับขนาดได้ การเปลี่ยนผ่านนี้แสดงให้เห็นถึงความง่ายที่แอปพลิเคชันสามารถใช้ประโยชน์จากประสิทธิภาพของ Spanner ได้ โดยเฉพาะอย่างยิ่งเมื่อใช้ประโยชน์จากอินเทอร์เฟซ Spanner Cassandra

อินเทอร์เฟซ Spanner Cassandra ช่วยให้กระบวนการเปลี่ยนระบบเป็นไปอย่างราบรื่น โดยหลักๆ แล้วคือการกำหนดค่าแอปพลิเคชันไคลเอ็นต์ให้ใช้ไคลเอ็นต์ Spanner Cassandra ดั้งเดิมสำหรับการโต้ตอบข้อมูลทั้งหมด แอปพลิเคชันจะเริ่มอ่านและเขียนข้อมูลไปยัง Spanner (เป้าหมาย) โดยตรงอย่างราบรื่นแทนที่จะสื่อสารกับฐานข้อมูล Cassandra (ต้นทาง) โดยปกติแล้ว การเปลี่ยนแปลงพื้นฐานด้านการเชื่อมต่อนี้จะเกิดขึ้นได้จากการใช้ SpannerCqlSessionBuilder ซึ่งเป็นคอมโพเนนต์หลักของไลบรารีของไคลเอ็นต์ Spanner Cassandra ที่ช่วยให้สร้างการเชื่อมต่อกับอินสแตนซ์ Spanner ได้ ซึ่งจะเปลี่ยนเส้นทางการรับส่งข้อมูลทั้งหมดของแอปพลิเคชันไปยัง Spanner อย่างมีประสิทธิภาพ

สำหรับแอปพลิเคชัน Java ที่ใช้ไลบรารี cassandra-java-driver อยู่แล้ว การผสานรวม Spanner Cassandra Java Client จะต้องมีการเปลี่ยนแปลงเล็กน้อยในการเริ่มต้น CqlSession เท่านั้น

การรับทรัพยากร Dependency google-cloud-spanner-cassandra

หากต้องการเริ่มใช้ไคลเอ็นต์ Spanner Cassandra คุณต้องรวมทรัพยากร Dependency ของไคลเอ็นต์ไว้ในโปรเจ็กต์ก่อน google-cloud-spanner-cassandra อาร์ติแฟกต์ได้รับการเผยแพร่ใน Maven Central ภายใต้รหัสกลุ่ม com.google.cloud เพิ่มทรัพยากร Dependency ใหม่ต่อไปนี้ในส่วน <dependencies> ที่มีอยู่แล้วในโปรเจ็กต์ Java ต่อไปนี้เป็นตัวอย่างแบบย่อของวิธีรวมการอ้างอิง 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ตรรกะการสร้าง คุณจะใช้ SpannerCqlSession.builder() ที่ไคลเอ็นต์ Spanner Cassandra จัดเตรียมให้แทนการใช้ CqlSessionBuilder มาตรฐานจาก cassandra-java-driver โดยตรง ต่อไปนี้เป็นตัวอย่างที่แสดงให้เห็นวิธีแก้ไขโค้ดการเชื่อมต่อ

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();

การสร้างอินสแตนซ์ CqlSession โดยใช้ SpannerCqlSession.builder() และระบุ databaseUri ที่ถูกต้อง ตอนนี้แอปพลิเคชันจะสร้างการเชื่อมต่อผ่านไคลเอ็นต์ Spanner Cassandra กับฐานข้อมูล Spanner เป้าหมาย การเปลี่ยนแปลงที่สำคัญนี้ช่วยให้มั่นใจได้ว่าการอ่านและการเขียนทั้งหมดที่แอปพลิเคชันของคุณดำเนินการในภายหลังจะได้รับการนำทางและให้บริการโดย Spanner ซึ่งเป็นการดำเนินการ Cutover ครั้งแรกให้เสร็จสมบูรณ์อย่างมีประสิทธิภาพ ณ จุดนี้ แอปพลิเคชันของคุณควรทำงานต่อไปได้ตามที่คาดไว้ โดยตอนนี้ขับเคลื่อนด้วยความสามารถในการปรับขนาดและความน่าเชื่อถือของ Spanner

กลไกภายใน: วิธีการทำงานของไคลเอ็นต์ Cassandra ของ Spanner

ไคลเอ็นต์ Spanner Cassandra ทำหน้าที่เป็นพร็อกซี TCP ในเครื่อง โดยจะสกัดกั้นไบต์โปรโตคอล Cassandra ดิบที่ส่งโดยไดรเวอร์หรือเครื่องมือไคลเอ็นต์ จากนั้นจะรวมไบต์เหล่านี้พร้อมกับข้อมูลเมตาที่จำเป็นลงในข้อความ gRPC เพื่อสื่อสารกับ Spanner ระบบจะแปลคำตอบจาก Spanner กลับเป็นรูปแบบการส่งผ่านข้อมูลของ Cassandra และส่งกลับไปยังไดรเวอร์หรือเครื่องมือต้นทาง

เมื่อมั่นใจว่า Spanner ให้บริการการรับส่งข้อมูลทั้งหมดอย่างถูกต้องแล้ว คุณจะทำสิ่งต่อไปนี้ได้

เลิกใช้งานคลัสเตอร์ Cassandra เดิม

8. การล้างข้อมูล (ไม่บังคับ)

หากต้องการล้างข้อมูล เพียงไปที่ส่วน Spanner ของ Cloud Console แล้วลบอินสแตนซ์ cassandra-adapter-demo ที่เราสร้างขึ้นใน Codelab

ลบฐานข้อมูล Cassandra (หากติดตั้งในเครื่องหรือคงอยู่)

หากคุณติดตั้ง Cassandra นอก VM ของ Compute Engine ที่สร้างขึ้นที่นี่ ให้ทำตามขั้นตอนที่เหมาะสมเพื่อนำข้อมูลออกหรือถอนการติดตั้ง Cassandra

9. ยินดีด้วย

ขั้นตอนต่อไปคืออะไร

ดูข้อมูลเพิ่มเติมเกี่ยวกับ Spanner
ดูข้อมูลเพิ่มเติมเกี่ยวกับอินเทอร์เฟซ Cassandra