การเริ่มต้นใช้งาน 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 ที่เปิดใช้การเรียกเก็บเงินอยู่แล้ว

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

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

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

ข้อควรระวัง: รหัสโปรเจ็กต์จะไม่ซ้ำกันทั่วโลก และบุคคลอื่นจะใช้รหัสโปรเจ็กต์ที่คุณเลือกไม่ได้ คุณเป็นผู้ใช้รหัสดังกล่าวเพียงคนเดียว แม้ว่าจะลบโปรเจ็กต์ไปแล้ว แต่ก็ไม่สามารถใช้รหัสนั้นอีก

หมายเหตุ: หากใช้บัญชี Gmail คุณสามารถปล่อยให้ตำแหน่งเริ่มต้นเป็นไม่มีองค์กรได้ หากใช้บัญชี Google Workspace ให้เลือกสถานที่ตั้งที่เหมาะสมกับองค์กร

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

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

เริ่มต้น Cloud Shell

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

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

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

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

ถัดไป

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

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

หมายเหตุ: คุณสามารถข้ามขั้นตอนนี้ได้หากมีคลัสเตอร์ 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 cassandra-origin แล้วเชื่อมต่อกับ VM โดยใช้ SSH ดังที่แสดง

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

ติดตั้ง Java (การอ้างอิง 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

หรือ

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

คุณสามารถใช้เอดิเตอร์ที่ต้องการเพื่ออัปเดตไฟล์การกำหนดค่า 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 อินสแตนซ์คือคลัสเตอร์ของทรัพยากรการคำนวณและพื้นที่เก็บข้อมูลที่โฮสต์ฐานข้อมูล 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"

หมายเหตุ: คำสั่งนี้ใช้ regional-us-central1 เป็นภูมิภาค คุณเลือกภูมิภาคอื่นได้โดยอิงตามการกำหนดค่าภูมิภาคที่พร้อมใช้งานสำหรับอินสแตนซ์ทดลองใช้ Spanner ฟรี อ่านข้อมูลเพิ่มเติมเกี่ยวกับวิธีสร้างอินสแตนซ์ทดลองใช้ฟรีที่นี่

เอาต์พุตของคำสั่ง

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 จัดเตรียมไว้ให้

1. เครื่องมือย้ายข้อมูล Spanner: เครื่องมือนี้ช่วยคุณย้ายข้อมูลสคีมาโดยเชื่อมต่อกับฐานข้อมูล Cassandra ที่มีอยู่และย้ายข้อมูลสคีมาไปยัง Spanner เครื่องมือนี้พร้อมให้บริการใน gcloud cli
2. เครื่องมือสคีมา 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 Migration Tool

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. ส่งออกข้อมูลประวัติแบบเป็นกลุ่ม

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

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

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

จัดสรรที่เก็บข้อมูล GCS

เมื่อสิ้นสุดขั้นตอนนี้ คุณควรจัดสรรที่เก็บข้อมูล 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 เพื่อดูรายการตัวเลือกทั้งหมด

หมายเหตุ หากต้องการเรียกใช้การย้ายข้อมูลแบบกลุ่มอีกครั้ง โปรดตั้งค่า insertOnlyModeForSpannerMutations เป็น false เพื่ออนุญาตการเขียนทับ

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 (การเปลี่ยนระบบ)

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

ระยะการเปลี่ยนระบบเป็นระยะเวลาที่การรับส่งข้อมูลของแอปพลิเคชันที่ใช้งานจริงจะเปลี่ยนเส้นทางออกจากคลัสเตอร์ 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 เท่านั้น

การรับการอ้างอิง google-cloud-spanner-cassandra

หากต้องการเริ่มใช้ไคลเอ็นต์ Spanner Cassandra คุณต้องรวมการอ้างอิงของไคลเอ็นต์ไว้ในโปรเจ็กต์ก่อน 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();

หมายเหตุ: databaseUri เป็นพารามิเตอร์ที่สำคัญซึ่งระบุตำแหน่งที่แน่นอนของฐานข้อมูล Spanner เป้าหมาย โดยมีรูปแบบดังนี้ projects/<your-gcp-project>/instances/your-spanner-instance>/databases/<your-spanner-database> ตรวจสอบว่าคุณได้แทนที่ตัวยึดตำแหน่งด้วยรหัสโปรเจ็กต์ Google Cloud, ชื่ออินสแตนซ์ Spanner และชื่อฐานข้อมูล Spanner จริง

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

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

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

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

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

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

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

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

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

9. ยินดีด้วย

ขั้นตอนถัดไปคือ

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