Mulai menggunakan Spanner Cassandra Adapter

1. Pengantar

Spanner adalah layanan database terkelola sepenuhnya, dapat diskalakan secara horizontal, dan didistribusikan secara global yang sangat cocok untuk workload relasional dan non-relasional.

Antarmuka Cassandra Spanner memungkinkan Anda memanfaatkan infrastruktur Spanner yang terkelola sepenuhnya, skalabel, dan sangat tersedia menggunakan alat dan sintaksis Cassandra yang sudah dikenal.

Yang akan Anda pelajari

• Cara menyiapkan instance dan database Spanner.
• Cara mengonversi skema dan model data Cassandra Anda.
• Cara mengekspor data historis Anda secara massal dari Cassandra ke Spanner.
• Cara mengarahkan aplikasi Anda ke Spanner, bukan Cassandra.

Yang Anda butuhkan

• Project Google Cloud yang terhubung ke akun penagihan.
• Akses ke mesin dengan CLI gcloud yang diinstal dan dikonfigurasi, atau gunakan Google Cloud Shell.
• Browser web, seperti Chrome atau Firefox.

2. Penyiapan dan persyaratan

Catatan: Anda dapat melewati langkah ini jika sudah memiliki project GCP dengan penagihan diaktifkan.

Buat project GCP

Login ke Konsol Google Cloud dan buat project baru atau gunakan kembali project yang sudah ada. Jika belum memiliki akun Gmail atau Google Workspace, Anda harus membuatnya.

• Project name adalah nama tampilan untuk peserta project ini. String ini adalah string karakter yang tidak digunakan oleh Google API. Anda dapat memperbaruinya kapan saja.
• Project ID bersifat unik di semua project Google Cloud dan tidak dapat diubah (tidak dapat diubah setelah ditetapkan). Cloud Console otomatis membuat string unik; biasanya Anda tidak mementingkan kata-katanya. Di sebagian besar codelab, Anda harus merujuk Project ID-nya (umumnya diidentifikasi sebagai PROJECT_ID). Jika tidak suka dengan ID yang dibuat, Anda dapat membuat ID acak lainnya. Atau, Anda dapat mencobanya sendiri, dan lihat apakah ID tersebut tersedia. ID tidak dapat diubah setelah langkah ini dan tersedia selama durasi project.
• Sebagai informasi, ada nilai ketiga, Project Number, yang digunakan oleh beberapa API. Pelajari lebih lanjut ketiga nilai ini di dokumentasi.

Perhatian: Project ID bersifat unik secara global dan tidak dapat digunakan orang lain setelah Anda memilihnya. Anda adalah satu-satunya pengguna ID tersebut. Meskipun project sudah dihapus, ID tersebut tidak dapat digunakan lagi

Catatan: Jika menggunakan akun Gmail, Anda dapat menyetel lokasi default ke No organization. Jika Anda menggunakan akun Google Workspace, pilih lokasi yang sesuai untuk organisasi Anda.

Konfigurasi penagihan

Selanjutnya, Anda harus mengikuti panduan pengguna pengelolaan penagihan dan mengaktifkan penagihan di Konsol Cloud. Pengguna baru Google Cloud memenuhi syarat untuk mengikuti program Uji Coba Gratis senilai$300 USD. Agar tidak menimbulkan penagihan di luar tutorial ini, Anda dapat menonaktifkan instance Spanner di akhir codelab dengan mengikuti "Langkah 9 Membersihkan".

Mulai Cloud Shell

Meskipun Google Cloud dapat dioperasikan dari jarak jauh menggunakan laptop Anda, dalam codelab ini, Anda akan menggunakan Google Cloud Shell, lingkungan command line yang berjalan di Cloud.

Dari Konsol Google Cloud, klik ikon Cloud Shell di toolbar kanan atas:

Hanya perlu waktu beberapa saat untuk penyediaan dan terhubung ke lingkungan. Jika sudah selesai, Anda akan melihat tampilan seperti ini:

Mesin virtual ini berisi semua alat pengembangan yang Anda perlukan. Layanan ini menawarkan direktori beranda tetap sebesar 5 GB dan beroperasi di Google Cloud, sehingga sangat meningkatkan performa dan autentikasi jaringan. Semua pekerjaan Anda dalam codelab ini dapat dilakukan di browser. Anda tidak perlu menginstal apa pun.

Berikutnya

Selanjutnya, Anda akan men-deploy cluster Cassandra.

3. Men-deploy cluster Cassandra (Origin)

Catatan: Anda dapat melewati langkah ini jika sudah memiliki cluster Cassandra untuk tujuan pengujian.

Untuk codelab ini, kita akan menyiapkan cluster Cassandra satu node di Compute Engine.

1. Buat VM GCE untuk Cassandra

Untuk membuat instance, gunakan perintah gcloud compute instances create dari cloud shell yang disediakan sebelumnya.

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. Instal Cassandra

Buka VM Instances dari halaman Navigation menu dengan mengikuti petunjuk di bawah: .

Cari VM cassandra-origin dan hubungkan ke VM menggunakan SSH seperti yang ditunjukkan:

.

Jalankan perintah berikut untuk menginstal Cassandra di VM yang telah Anda buat dan akses melalui SSH.

Instal Java (dependensi Cassandra)

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

Tambahkan repositori 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

Instal Cassandra

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

Tetapkan alamat pendengar untuk layanan Cassandra.

Di sini kita menggunakan alamat IP internal VM Cassandra untuk keamanan tambahan.

Catat alamat IP mesin host Anda

Anda dapat menggunakan perintah berikut di cloud shell, atau mendapatkannya dari halaman VM Instances di konsol cloud.

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

ATAU

.

Perbarui alamat di file konfigurasi

Anda dapat menggunakan editor pilihan Anda untuk memperbarui file konfigurasi Cassandra

sudo vim /etc/cassandra/cassandra.yaml

Ubah rpc_address: menjadi alamat IP VM, lalu simpan dan tutup file.

Aktifkan Layanan Cassandra di VM

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

3. Membuat keyspace dan tabel {create-keyspace-and-table}

Kita akan menggunakan contoh tabel "users" dan membuat keyspace bernama "analytics".

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

Di dalam 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;

Biarkan sesi SSH terbuka atau catat alamat IP VM ini (hostname -I).

Berikutnya

Selanjutnya, Anda akan menyiapkan Instance dan Database Cloud Spanner.

4. Buat instance Spanner (Target)

Catatan: Anda dapat melewati langkah ini jika sudah memiliki instance Spanner untuk tujuan pengujian di project Anda. Anda dapat memverifikasinya dengan membuka link konsol ini

Di Spanner, instance adalah cluster sumber daya komputasi dan penyimpanan yang menghosting satu atau beberapa database Spanner. Anda memerlukan setidaknya 1 instance untuk menghosting database Spanner untuk codelab ini.

Memeriksa versi gcloud SDK

Sebelum membuat instance, pastikan gcloud SDK di Google Cloud Shell telah diupdate ke versi yang diperlukan - versi apa pun yang lebih baru dari gcloud SDK 531.0.0. Anda dapat menemukan versi gcloud SDK dengan mengikuti perintah di bawah.

$ gcloud version | grep Google

Berikut contoh outputnya:

Google Cloud SDK 489.0.0

Jika versi yang Anda gunakan lebih lama dari versi 531.0.0 yang diperlukan (489.0.0 dalam contoh sebelumnya), Anda harus mengupgrade Google Cloud SDK dengan menjalankan perintah berikut:

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

Catatan: Perintah sebelumnya mencantumkan paket yang akan diupgrade secara menyeluruh untuk alasan keamanan.

Aktifkan Spanner API

Di dalam Cloud Shell, pastikan project ID Anda sudah disiapkan. Gunakan perintah pertama di bawah untuk menemukan project ID yang saat ini dikonfigurasi. Jika hasilnya tidak sesuai yang diharapkan, perintah kedua di bawah akan menetapkan yang benar.

gcloud config get-value project

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

Konfigurasi region default Anda ke us-central1. Anda dapat mengubahnya ke wilayah lain yang didukung oleh konfigurasi regional Spanner.

gcloud config set compute/region us-central1

Aktifkan Spanner API:

gcloud services enable spanner.googleapis.com

Buat instance Spanner

Di bagian ini, Anda akan membuat instance uji coba gratis atau instance yang disediakan. Selama codelab ini, ID Instance Spanner Cassandra Adapter yang digunakan adalah cassandra-adapter-demo, yang ditetapkan sebagai variabel SPANNER_INSTANCE_ID menggunakan command line export. Jika ingin, Anda dapat memilih nama ID instance Anda sendiri.

Membuat instance Spanner uji coba gratis

Instance uji coba gratis Spanner selama 90 hari tersedia bagi siapa saja yang memiliki Akun Google dan mengaktifkan Penagihan Cloud di projectnya. Anda tidak akan ditagih kecuali jika Anda memilih untuk mengupgrade instance uji coba gratis ke instance berbayar. Spanner Cassandra Adapter didukung di instance uji coba gratis. Jika memenuhi syarat, buat instance uji coba gratis dengan membuka Cloud Shell dan menjalankan perintah ini:

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"

Catatan: Perintah ini menggunakan regional-us-central1 sebagai region. Anda dapat memilih region lain berdasarkan konfigurasi region yang tersedia untuk instance uji coba gratis Spanner. Baca selengkapnya cara membuat instance uji coba gratis di sini.

Output perintah:

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

5. Memigrasikan Skema dan model data Cassandra ke Spanner

Fase awal dan penting dalam mentransisikan data dari database Cassandra ke Spanner melibatkan transformasi skema Cassandra yang ada agar selaras dengan persyaratan struktural dan jenis data Spanner.

Untuk menyederhanakan proses migrasi skema yang kompleks ini, gunakan salah satu dari dua alat open source berharga yang disediakan oleh Spanner:

1. Alat Migrasi Spanner: Alat ini membantu Anda memigrasikan skema dengan terhubung ke database Cassandra yang ada dan memigrasikan skema ke Spanner. Alat ini tersedia sebagai bagian dari gcloud cli.
2. Alat Skema Cassandra Spanner: Alat ini membantu Anda mengonversi DDL yang diekspor dari Cassandra ke Spanner. Anda dapat menggunakan salah satu dari dua alat ini untuk codelab. Dalam codelab ini, kita akan menggunakan Spanner Migration Tool untuk memigrasikan skema.

Alat Migrasi Spanner

Spanner Migration Tool membantu memigrasikan skema dari berbagai sumber data seperti MySQL, Postgres, Cassandra, dll.

Meskipun untuk tujuan codelab ini kita akan menggunakan CLI alat ini, sebaiknya Anda menjelajahi dan menggunakan alat versi berbasis UI, yang juga membantu Anda melakukan modifikasi pada skema Spanner sebelum diterapkan.

Perhatikan bahwa jika spanner-migration-tool dijalankan di Cloud Shell, spanner-migration-tool mungkin tidak memiliki akses ke alamat IP internal VM Cassandra Anda. Oleh karena itu, sebaiknya jalankan perintah yang sama di VM tempat Anda menginstal Cassandra.

Jalankan perintah berikut di VM tempat Anda menginstal Cassandra.

Menginstal Alat Migrasi Spanner

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

Jika Anda mengalami masalah saat menginstal, lihat installing-spanner-migration-tool untuk mengetahui langkah-langkah mendetail.

Memuat Ulang Kredensial Gcloud

gcloud auth login
gcloud auth application-default login

Migrasikan Skema

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}

Verifikasi DDL Spanner

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

Di akhir migrasi skema, output perintah ini akan menjadi:

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

(Opsional) Melihat DDL yang dikonversi

Anda dapat melihat DDL yang dikonversi dan menerapkannya kembali di Spanner (jika Anda memerlukan perubahan tambahan)

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

Output perintah ini adalah

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`)

(Opsional) Melihat laporan konversi

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

Laporan konversi menyoroti masalah yang harus Anda perhatikan. Misalnya, jika ada ketidakcocokan dalam presisi maksimum kolom antara sumber dan Spanner, ketidakcocokan tersebut akan ditandai di sini.

6. Mengekspor data historis secara massal

Untuk melakukan migrasi massal, Anda harus:

1. Sediakan atau gunakan kembali bucket GCS yang ada.
2. Mengupload file konfigurasi Cassandra Driver ke bucket
3. Luncurkan migrasi massal.

Meskipun Anda dapat meluncurkan migrasi massal dari Cloud Shell atau VM yang baru disediakan, sebaiknya gunakan VM untuk codelab ini karena beberapa langkah seperti membuat file konfigurasi akan mempertahankan file di penyimpanan lokal.

Sediakan bucket GCS.

Di akhir langkah ini, Anda akan menyediakan bucket GCS dan mengekspor jalurnya dalam variabel bernama CASSANDRA_BUCKET_NAME. Jika ingin menggunakan kembali bucket yang ada, Anda dapat melanjutkan dengan mengekspor jalur.

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

Membuat dan mengupload file konfigurasi Driver

Di sini, kita mengupload file konfigurasi driver Cassandra yang sangat dasar. Lihat ini untuk mengetahui format lengkap file.

# 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}"

Menjalankan migrasi massal

Berikut adalah contoh perintah untuk menjalankan migrasi massal data Anda ke Spanner. Untuk kasus penggunaan produksi sebenarnya, Anda harus menyesuaikan jenis dan jumlah mesin sesuai dengan skala dan throughput yang diinginkan. Buka README_Sourcedb_to_Spanner.md#cassandra-to-spanner-bulk-migration untuk mengetahui daftar lengkap opsi.

Catatan Jika Anda ingin menjalankan ulang migrasi massal, tetapkan insertOnlyModeForSpannerMutations ke false untuk mengizinkan penimpaan.

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"

Tindakan ini akan menghasilkan output seperti berikut. Perhatikan id yang dihasilkan dan gunakan yang sama untuk mengkueri status tugas 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'

Jalankan perintah di bawah untuk memeriksa status tugas dan tunggu hingga status berubah menjadi JOB_STATE_DONE.

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

Awalnya, tugas akan berada dalam status antrean seperti

currentState: JOB_STATE_QUEUED

Saat tugas diantrekan/dijalankan, sebaiknya Anda membuka halaman Dataflow/Jobs di UI Cloud Console untuk memantau tugas.

Setelah selesai, status tugas akan berubah menjadi:

currentState: JOB_STATE_DONE

7. Mengarahkan aplikasi Anda ke Spanner (Pengalihan)

Setelah memvalidasi akurasi dan integritas data Anda dengan cermat setelah fase migrasi, langkah pentingnya adalah mengalihkan fokus operasional aplikasi Anda dari sistem Cassandra lama ke database Spanner yang baru diisi. Periode transisi penting ini biasanya disebut sebagai "pengalihan".

Fase peralihan menandai saat traffic aplikasi aktif dialihkan dari cluster Cassandra asli dan terhubung langsung ke infrastruktur Spanner yang andal dan skalabel. Transisi ini menunjukkan kemudahan aplikasi dalam memanfaatkan kecanggihan Spanner, terutama saat menggunakan antarmuka Spanner Cassandra.

Dengan antarmuka Spanner Cassandra, proses pengalihan menjadi lebih lancar. Hal ini terutama melibatkan konfigurasi aplikasi klien Anda untuk menggunakan Spanner Cassandra Client native untuk semua interaksi data. Alih-alih berkomunikasi dengan database Cassandra (asal), aplikasi Anda akan mulai membaca dan menulis data secara langsung ke Spanner (target) dengan lancar. Perubahan mendasar dalam konektivitas ini biasanya dicapai melalui penggunaan SpannerCqlSessionBuilder, komponen utama library Spanner Cassandra Client yang memfasilitasi pembuatan koneksi ke instance Spanner Anda. Tindakan ini secara efektif mengalihkan seluruh alur traffic data aplikasi Anda ke Spanner.

Untuk aplikasi Java yang sudah menggunakan library cassandra-java-driver, mengintegrasikan Spanner Cassandra Java Client hanya memerlukan sedikit perubahan pada inisialisasi CqlSession.

Mendapatkan dependensi google-cloud-spanner-cassandra

Untuk mulai menggunakan Spanner Cassandra Client, Anda harus menyertakan dependensinya ke dalam project terlebih dahulu. Artefak google-cloud-spanner-cassandra dipublikasikan di Maven Central, dengan ID grup com.google.cloud. Tambahkan dependensi baru berikut di bagian <dependencies> yang ada di project Java Anda. Berikut adalah contoh sederhana cara menyertakan dependensi 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>

Ubah konfigurasi koneksi untuk terhubung ke Spanner

Setelah menambahkan dependensi yang diperlukan, langkah selanjutnya adalah mengubah konfigurasi koneksi untuk terhubung ke database Spanner.

Aplikasi umum yang berinteraksi dengan cluster Cassandra sering kali menggunakan kode yang mirip dengan berikut untuk membuat koneksi:

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

Untuk mengalihkan koneksi ini ke Spanner, Anda perlu mengubah logika pembuatan CqlSession. Daripada menggunakan CqlSessionBuilder standar secara langsung dari cassandra-java-driver, Anda akan menggunakan SpannerCqlSession.builder() yang disediakan oleh Spanner Cassandra Client. Berikut adalah contoh ilustratif cara mengubah kode koneksi Anda:

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

Catatan: databaseUri adalah parameter penting yang menentukan lokasi persis database Spanner target Anda. Formatnya adalah: projects/<your-gcp-project>/instances/your-spanner-instance>/databases/<your-spanner-database>. Pastikan Anda mengganti placeholder dengan Project ID Google Cloud, nama instance Spanner, dan nama database Spanner yang sebenarnya.

Dengan membuat instance CqlSession menggunakan SpannerCqlSession.builder() dan memberikan databaseUri yang benar, aplikasi Anda kini akan membuat koneksi melalui Spanner Cassandra Client ke database Spanner target Anda. Perubahan penting ini memastikan bahwa semua operasi baca dan tulis berikutnya yang dilakukan oleh aplikasi Anda akan diarahkan ke dan ditayangkan oleh Spanner, sehingga menyelesaikan peralihan awal secara efektif. Pada tahap ini, aplikasi Anda akan terus berfungsi seperti yang diharapkan, dan kini didukung oleh skalabilitas dan keandalan Spanner.

Di Balik Layar: Cara Kerja Klien Cassandra Spanner

Klien Cassandra Spanner bertindak sebagai proxy TCP lokal, yang mencegat byte protokol Cassandra mentah yang dikirim oleh driver atau alat klien. Kemudian, library ini membungkus byte ini beserta metadata yang diperlukan ke dalam pesan gRPC untuk komunikasi dengan Spanner. Respons dari Spanner diterjemahkan kembali ke format wire Cassandra dan dikirim kembali ke driver atau alat asal.

Setelah yakin bahwa Spanner melayani semua traffic dengan benar, Anda dapat:

• Nonaktifkan cluster Cassandra asli.

8. Membersihkan (opsional)

Untuk membersihkan, cukup buka bagian Spanner di Cloud Console dan hapus instance cassandra-adapter-demo yang kita buat di codelab.

Hapus database Cassandra (jika diinstal secara lokal atau dipertahankan)

Jika Anda menginstal Cassandra di luar VM Compute Engine yang dibuat di sini, ikuti langkah-langkah yang sesuai untuk menghapus data atau meng-uninstal Cassandra.

9. Selamat!

Apa langkah selanjutnya?

• Pelajari Spanner lebih lanjut.
• Pelajari lebih lanjut Antarmuka Cassandra.