شروع کار با آداپتور Spanner Cassandra، شروع کار با آداپتور Spanner Cassandra، شروع به کار با آداپتور Spanner Cassandra

شروع با آداپتور Spanner Cassandra

درباره این codelab

آخرین به‌روزرسانی: مه ۲۱, ۲۰۲۵

نویسنده: Mayur Kale, Vardhan Thigle

1. مقدمه

Spanner یک سرویس پایگاه داده کاملاً مدیریت شده، افقی مقیاس پذیر و توزیع شده در سطح جهانی است که برای بارهای کاری رابطه ای و غیر رابطه ای عالی است.

رابط Cassandra Spanner به شما امکان می دهد از زیرساخت های کاملاً مدیریت شده، مقیاس پذیر و بسیار در دسترس Spanner با استفاده از ابزارها و نحو آشنای Cassandra استفاده کنید.

چیزی که یاد خواهید گرفت

• نحوه راه اندازی نمونه و پایگاه داده Spanner.
• چگونه طرحواره و مدل داده کاساندرا خود را تبدیل کنید.
• نحوه استقرار و پیکربندی نوشتن دوگانه برای داده های ورودی.
• نحوه صادرات انبوه داده های تاریخی خود از کاساندرا به Spanner.
• نحوه اعتبارسنجی داده ها برای اطمینان از یکپارچگی داده ها در طول فرآیند مهاجرت.
• چگونه درخواست خود را به جای کاساندرا به Spanner اشاره کنید.

آنچه شما نیاز دارید

• یک پروژه Google Cloud که به یک حساب صورت‌حساب متصل است.
• دسترسی به ماشینی که gcloud CLI آن نصب و پیکربندی شده است یا از Google Cloud Shell استفاده کنید.
• یک مرورگر وب، مانند کروم یا فایرفاکس .

2. راه اندازی و الزامات

توجه: اگر از قبل یک پروژه GCP با فعال بودن صورت‌حساب دارید، می‌توانید از این مرحله رد شوید.

یک پروژه GCP ایجاد کنید

به Google Cloud Console وارد شوید و یک پروژه جدید ایجاد کنید یا از یک موجود استفاده مجدد کنید. اگر قبلاً یک حساب Gmail یا Google Workspace ندارید، باید یک حساب ایجاد کنید .

• نام پروژه نام نمایشی برای شرکت کنندگان این پروژه است. این یک رشته کاراکتری است که توسط API های Google استفاده نمی شود. همیشه می توانید آن را به روز کنید.
• شناسه پروژه در تمام پروژه‌های Google Cloud منحصربه‌فرد است و تغییرناپذیر است (پس از تنظیم نمی‌توان آن را تغییر داد). Cloud Console به طور خودکار یک رشته منحصر به فرد تولید می کند. معمولاً برای شما مهم نیست که چیست. در اکثر کدها، باید شناسه پروژه خود را ارجاع دهید (معمولاً با نام PROJECT_ID شناخته می شود). اگر شناسه تولید شده را دوست ندارید، ممکن است یک شناسه تصادفی دیگر ایجاد کنید. از طرف دیگر، می‌توانید خودتان را امتحان کنید، و ببینید آیا در دسترس است یا خیر. پس از این مرحله نمی توان آن را تغییر داد و در طول مدت پروژه باقی می ماند.
• برای اطلاع شما، یک مقدار سوم وجود دارد، یک شماره پروژه ، که برخی از API ها از آن استفاده می کنند. در مورد هر سه این مقادیر در مستندات بیشتر بیاموزید.

احتیاط: شناسه پروژه در سطح جهانی منحصر به فرد است و پس از انتخاب شما توسط شخص دیگری نمی توان از آن استفاده کرد. شما تنها کاربر آن شناسه هستید. حتی اگر پروژه ای حذف شود، ID نمی تواند دوباره استفاده شود

توجه: اگر از یک حساب جیمیل استفاده می‌کنید، می‌توانید مکان پیش‌فرض را روی بدون سازمان بگذارید. اگر از حساب Google Workspace استفاده می کنید، مکانی را انتخاب کنید که برای سازمان شما منطقی باشد.

تنظیم صورتحساب

در مرحله بعد، باید راهنمای کاربر مدیریت صورت‌حساب را دنبال کنید و صورت‌حساب را در کنسول Cloud فعال کنید. کاربران جدید Google Cloud واجد شرایط برنامه آزمایشی رایگان 300 دلاری هستند. برای جلوگیری از متحمل شدن صورت‌حساب فراتر از این آموزش، می‌توانید با دنبال کردن «مرحله 9 پاک‌سازی»، نمونه Spanner را در انتهای کد لبه خاموش کنید.

Cloud Shell را راه اندازی کنید

در حالی که Google Cloud را می توان از راه دور از لپ تاپ شما کار کرد، در این کد لبه از Google Cloud Shell استفاده خواهید کرد، یک محیط خط فرمان که در Cloud اجرا می شود.

از Google Cloud Console ، روی نماد Cloud Shell در نوار ابزار بالا سمت راست کلیک کنید:

تهیه و اتصال به محیط فقط چند لحظه طول می کشد. وقتی تمام شد، باید چیزی شبیه به این را ببینید:

این ماشین مجازی با تمام ابزارهای توسعه که شما نیاز دارید بارگذاری شده است. این یک فهرست اصلی 5 گیگابایتی دائمی را ارائه می دهد و در Google Cloud اجرا می شود و عملکرد و احراز هویت شبکه را تا حد زیادی افزایش می دهد. تمام کارهای شما در این کد لبه را می توان در یک مرورگر انجام داد. شما نیازی به نصب چیزی ندارید.

بعدی

در مرحله بعد، خوشه Cassandra را مستقر خواهید کرد.

3. استقرار خوشه Cassandra (Origin)

توجه: اگر از قبل یک خوشه Cassandra برای اهداف آزمایشی دارید، می توانید از این مرحله صرف نظر کنید.

برای این کد لبه، ما یک کلاستر تک گره Cassandra را در Compute Engine راه اندازی می کنیم.

1. یک GCE VM برای Cassandra ایجاد کنید

برای ایجاد یک نمونه، از دستور 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. یک فضای کلید و جدول ایجاد کنید

ما از مثال جدول کاربران استفاده می کنیم و یک فضای کلیدی به نام "تحلیل" ایجاد می کنیم.

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 این ماشین مجازی (نام میزبان -I) را یادداشت کنید.

بعدی

در مرحله بعد، یک نمونه Cloud Spanner و پایگاه داده را تنظیم خواهید کرد.

4. ایجاد نمونه و پایگاه داده Spanner (Target)

توجه: اگر قبلاً یک نمونه Spanner برای اهداف آزمایشی در پروژه خود دارید، می توانید از این مرحله صرف نظر کنید. با مراجعه به این لینک کنسول می توانید تأیید کنید

در Spanner، یک نمونه مجموعه ای از منابع محاسباتی و ذخیره سازی است که میزبان یک یا چند پایگاه داده Spanner است. برای میزبانی پایگاه داده Spanner برای این Codelab به حداقل 1 نمونه نیاز دارید.

نسخه gcloud SDK را بررسی کنید

قبل از ایجاد یک نمونه، مطمئن شوید که gcloud SDK در Google Cloud Shell به نسخه مورد نیاز - 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 پروژه شما راه اندازی شده است. از اولین دستور زیر برای پیدا کردن شناسه پروژه پیکربندی شده فعلی استفاده کنید. اگر نتیجه مورد انتظار نیست، دستور دوم زیر دستور درست را تنظیم می کند.

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 مورد استفاده cassandra-adapter-demo است که با استفاده از خط فرمان export به عنوان متغیر SPANNER_INSTANCE_ID تنظیم شده است. به صورت اختیاری، می توانید نام شناسه نمونه خود را انتخاب کنید.

یک نمونه Spanner آزمایشی رایگان ایجاد کنید

یک نمونه آزمایشی رایگان 90 روزه Spanner برای هر کسی که حساب Google دارد و صورت‌حساب Cloud را در پروژه خود فعال کرده باشد، در دسترس است. هزینه ای از شما کسر نمی شود مگر اینکه بخواهید نمونه آزمایشی رایگان خود را به نمونه پولی ارتقا دهید. آداپتور آچار 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"

توجه: این دستور 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.

پایگاه داده را ایجاد کنید

هنگامی که نمونه شما اجرا می شود، می توانید پایگاه داده را ایجاد کنید. پایگاه داده جایی است که شما طرحواره خود را تعریف می کنید. شما همچنین می توانید کنترل کنید که چه کسی به پایگاه داده دسترسی دارد، رمزگذاری سفارشی را تنظیم کنید، بهینه ساز را پیکربندی کنید و دوره نگهداری را تنظیم کنید.

پایگاه داده در نمونه با شناسه 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. طرحواره کاساندرا و مدل داده را به Spanner منتقل کنید

مرحله اولیه و حیاتی انتقال داده ها از پایگاه داده Cassandra به Spanner شامل تغییر طرح واره Cassandra موجود برای همسویی با الزامات ساختاری و نوع داده Spanner است.

برای ساده‌سازی این فرآیند پیچیده انتقال طرحواره، Spanner یک ابزار منبع باز ارزشمند به نام ابزار طرحواره Spanner Cassandra ارائه می‌کند.

ابزار طرحواره آچار کاساندرا

ابزار طرحواره Spanner Cassandra یک ابزار متن باز مستقل برای ارزیابی Spanner و مهاجرت طرحواره است. عملکرد اصلی آن ساخت خودکار یک طرحواره Spanner بر اساس تعاریف موجود در طرحواره کاساندرا موجود است. این ابزار با تجزیه و تحلیل ساختارهای جدول کاساندرا، انواع داده ها و تنظیمات کلید اولیه، تعاریف جدول Spanner معادل را ایجاد می کند و تلاش دستی را که معمولاً در ترجمه طرحواره دخیل است به طور قابل توجهی کاهش می دهد.

صادرات طرح کاساندرا

قبل از استفاده از ابزار طرحواره Spanner Cassandra، اولین گام ملموس این است که طرح را از خوشه Cassandra فعلی خود استخراج کنید. این را می توان با اتصال به خوشه Cassandra موجود از طریق cqlsh و صادرات طرح از Cassandra به دست آورد:

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

در این دستور، [IP] باید با آدرس IP یا نام میزبان یکی از گره های خوشه Cassandra شما جایگزین شود. قسمت -e DESC SCHEMA از دستور به cqlsh دستور می دهد تا کل طرحواره خوشه کاساندرا را توصیف کند. خروجی این دستور که حاوی دستورات CREATE KEYSPACE و CREATE TABLE است، سپس به فایلی با نام orig_schema.cql هدایت می شود.

محتوای این فایل orig_schema.cql اساساً نمایانگر طرح متنی طرحواره کاساندرا شما خواهد بود. محتوای فایل 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';

Repository را شبیه سازی کنید

برای استفاده از ابزار طرحواره Spanner Cassandra، مرحله بعدی شامل به دست آوردن کد منبع ابزار است. این کار با شبیه سازی مخزن میزبانی شده در GitHub انجام می شود. با تایپ دستور زیر در Cloud Shell، ابزار طرحواره Spanner Cassandra را از GitHub کلون کنید:

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

سپس دایرکتوری را به دایرکتوری "spanner-cassandra-schema-tool" تغییر دهید که در آن دستور را اجرا می کنید.

cd spanner-cassandra-schema-tool

Dependencies را نصب کنید

ابزار طرحواره Spanner Cassandra به زبان برنامه نویسی Go نوشته شده است. برای اطمینان از عملکرد صحیح ابزار، به ماژول های Go خارجی خاصی (کتابخانه ها) متکی است. این وابستگی ها باید دانلود و مدیریت شوند تا بتوانید ابزار را اجرا کنید. در پوشه spanner-cassandra-schema-tool ، دستور زیر را اجرا کنید:

go mod download

Google Cloud Credentials را تنظیم کنید

این ابزار از Application Default Credentials (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 را اجرا کنید تا طرح Spanner را از فایل طرحواره Cassandra صادر شده ایجاد کنید. به دایرکتوری spanner-cassandra-schema-tool در ترمینال یا Cloud Shell خود بروید و دستور 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 را به گونه‌های 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 اعمال شود، باید cli را بدون گزینه --dry-run اجرا کنید.

در Google Cloud Console تأیید کنید که جداول و جدول فراداده در پایگاه داده Cloud Spanner وجود دارد.

6. نوشتن دوگانه برای داده های ورودی را تنظیم کنید

[TODO]

7. داده های تاریخی خود را به صورت انبوه صادر کنید

[TODO]

8. داده های خود را اعتبار سنجی کنید

[TODO]

9. برنامه خود را روی Spanner (Cutover) قرار دهید

پس از تأیید دقیق صحت و یکپارچگی داده‌های خود پس از مرحله انتقال، مرحله اساسی انتقال تمرکز عملیاتی برنامه‌تان از سیستم قدیمی کاساندرا به پایگاه داده جدید Google Cloud Spanner است. این دوره انتقال بحرانی معمولاً به عنوان " برش " نامیده می شود.

مرحله قطع، لحظه‌ای را مشخص می‌کند که ترافیک برنامه‌های کاربردی زنده از خوشه اصلی کاساندرا هدایت می‌شود و مستقیماً به زیرساخت قوی و مقیاس‌پذیر Spanner متصل می‌شود. این انتقال نشان می‌دهد که اپلیکیشن‌ها می‌توانند به راحتی از قدرت Spanner استفاده کنند، به‌ویژه زمانی که از رابط Spanner Cassandra استفاده می‌کنند.

با رابط Spanner Cassandra، فرآیند برش ساده می شود. این در درجه اول شامل پیکربندی برنامه های مشتری شما برای استفاده از Spanner Cassandra Client برای تمام تعاملات داده است. به جای برقراری ارتباط با پایگاه داده Cassandra (منبع)، برنامه های شما به طور یکپارچه شروع به خواندن و نوشتن داده ها به طور مستقیم در Spanner (هدف) می کنند. این تغییر اساسی در اتصال معمولاً از طریق استفاده از SpannerCqlSessionBuilder ، یک جزء کلیدی از کتابخانه Spanner Cassandra Client که برقراری اتصالات به نمونه Spanner شما را تسهیل می‌کند، حاصل می‌شود. این به طور موثر کل جریان ترافیک داده برنامه شما را به Spanner تغییر مسیر می دهد.

برای برنامه‌های جاوا که قبلاً از کتابخانه cassandra-java-driver استفاده می‌کنند، ادغام Spanner Cassandra Java Client فقط به تغییرات جزئی در مقدار دهی اولیه CqlSession نیاز دارد.

دریافت وابستگی به google-cloud-spanner-cassandra

برای شروع استفاده از Spanner Cassandra Client، ابتدا باید وابستگی آن را در پروژه خود بگنجانید. مصنوعات google-cloud-spanner-cassandra در Maven central، تحت شناسه گروه com.google.cloud منتشر شده است. وابستگی جدید زیر را در بخش <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 خود را تغییر دهید. به جای استفاده مستقیم از CqlSessionBuilder استاندارد از cassandra-java-driver ، از SpannerCqlSession.builder() ارائه شده توسط Spanner Cassandra Client استفاده خواهید کرد. در اینجا یک مثال گویا از نحوه تغییر کد اتصال خود آورده شده است:

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 صحیح Uri، برنامه شما اکنون از طریق Spanner Cassandra Client به پایگاه داده Spanner مورد نظر شما ارتباط برقرار می کند. این تغییر محوری تضمین می‌کند که تمام عملیات خواندن و نوشتن بعدی که توسط برنامه شما انجام می‌شوند به Spanner هدایت می‌شوند و توسط Spanner ارائه می‌شوند و عملاً برش اولیه را تکمیل می‌کنند. در این مرحله، برنامه شما باید همانطور که انتظار می رفت به کار خود ادامه دهد، که اکنون توسط مقیاس پذیری و قابلیت اطمینان Spanner پشتیبانی می شود.

Under the Hood: How the Spanner Cassandra Client کار می کند

کلاینت Spanner Cassandra به عنوان یک پروکسی tcp محلی عمل می کند و بایت های پروتکل کاساندرا خام ارسال شده توسط درایور یا ابزار کلاینت را رهگیری می کند. سپس این بایت ها را به همراه ابرداده های لازم در پیام های gRPC برای ارتباط با Spanner قرار می دهد. پاسخ‌های Spanner به قالب سیم Cassandra ترجمه می‌شوند و به درایور یا ابزار اصلی ارسال می‌شوند.

هنگامی که مطمئن شدید که Spanner تمام ترافیک را به درستی ارائه می کند، در نهایت می توانید:

• توقف دوگانه می نویسد.
• خوشه اصلی کاساندرا را از رده خارج کنید.

10. تمیز کردن (اختیاری)

برای پاکسازی، کافی است به بخش Spanner در Cloud Console بروید و نمونه cassandra-adapter-demo را که در Codelab ایجاد کردیم حذف کنید.

پایگاه داده Cassandra را حذف کنید (در صورت نصب محلی یا ادامه دار)

اگر Cassandra را خارج از یک ماشین مجازی کامپیوتری که در اینجا ایجاد شده است نصب کرده اید، مراحل مناسب را برای حذف داده ها یا حذف نصب Cassandra دنبال کنید.

11. تبریک می گویم!

بعدش چی؟

• درباره Cloud Spanner بیشتر بیاموزید.
• درباره رابط کاساندرا بیشتر بیاموزید.

شروع با آداپتور Spanner Cassandra

درباره این codelab

آخرین به‌روزرسانی: مه ۲۱, ۲۰۲۵

نویسنده: Mayur Kale, Vardhan Thigle

1. مقدمه

Spanner یک سرویس پایگاه داده کاملاً مدیریت شده، افقی مقیاس پذیر و توزیع شده در سطح جهانی است که برای بارهای کاری رابطه ای و غیر رابطه ای عالی است.

رابط Cassandra Spanner به شما امکان می دهد از زیرساخت های کاملاً مدیریت شده، مقیاس پذیر و بسیار در دسترس Spanner با استفاده از ابزارها و نحو آشنای Cassandra استفاده کنید.

چیزی که یاد خواهید گرفت

• نحوه راه اندازی نمونه و پایگاه داده Spanner.
• چگونه طرحواره و مدل داده کاساندرا خود را تبدیل کنید.
• نحوه استقرار و پیکربندی نوشتن دوگانه برای داده های ورودی.
• نحوه صادرات انبوه داده های تاریخی خود از کاساندرا به Spanner.
• نحوه اعتبارسنجی داده ها برای اطمینان از یکپارچگی داده ها در طول فرآیند مهاجرت.
• چگونه درخواست خود را به جای کاساندرا به Spanner اشاره کنید.

آنچه شما نیاز دارید

• یک پروژه Google Cloud که به یک حساب صورت‌حساب متصل است.
• دسترسی به ماشینی که gcloud CLI آن نصب و پیکربندی شده است یا از Google Cloud Shell استفاده کنید.
• یک مرورگر وب، مانند کروم یا فایرفاکس .

2. راه اندازی و الزامات

توجه: اگر از قبل یک پروژه GCP با فعال بودن صورت‌حساب دارید، می‌توانید از این مرحله رد شوید.

یک پروژه GCP ایجاد کنید

به Google Cloud Console وارد شوید و یک پروژه جدید ایجاد کنید یا از یک موجود استفاده مجدد کنید. اگر قبلاً یک حساب Gmail یا Google Workspace ندارید، باید یک حساب ایجاد کنید .

• نام پروژه نام نمایشی برای شرکت کنندگان این پروژه است. این یک رشته کاراکتری است که توسط API های Google استفاده نمی شود. همیشه می توانید آن را به روز کنید.
• شناسه پروژه در تمام پروژه‌های Google Cloud منحصربه‌فرد است و تغییرناپذیر است (پس از تنظیم نمی‌توان آن را تغییر داد). Cloud Console به طور خودکار یک رشته منحصر به فرد تولید می کند. معمولاً برای شما مهم نیست که چیست. در اکثر کدها، باید شناسه پروژه خود را ارجاع دهید (معمولاً با نام PROJECT_ID شناخته می شود). اگر شناسه تولید شده را دوست ندارید، ممکن است یک شناسه تصادفی دیگر ایجاد کنید. از طرف دیگر، می‌توانید خودتان را امتحان کنید، و ببینید آیا در دسترس است یا خیر. پس از این مرحله نمی توان آن را تغییر داد و در طول مدت پروژه باقی می ماند.
• برای اطلاع شما، یک مقدار سوم وجود دارد، یک شماره پروژه ، که برخی از API ها از آن استفاده می کنند. در مورد هر سه این مقادیر در مستندات بیشتر بیاموزید.

احتیاط: شناسه پروژه در سطح جهانی منحصر به فرد است و پس از انتخاب شما توسط شخص دیگری نمی توان از آن استفاده کرد. شما تنها کاربر آن شناسه هستید. حتی اگر پروژه ای حذف شود، ID نمی تواند دوباره استفاده شود

توجه: اگر از یک حساب جیمیل استفاده می‌کنید، می‌توانید مکان پیش‌فرض را روی بدون سازمان بگذارید. اگر از حساب Google Workspace استفاده می کنید، مکانی را انتخاب کنید که برای سازمان شما منطقی باشد.

تنظیم صورتحساب

در مرحله بعد، باید راهنمای کاربر مدیریت صورت‌حساب را دنبال کنید و صورت‌حساب را در کنسول Cloud فعال کنید. کاربران جدید Google Cloud واجد شرایط برنامه آزمایشی رایگان 300 دلاری هستند. برای جلوگیری از متحمل شدن صورت‌حساب فراتر از این آموزش، می‌توانید با دنبال کردن «مرحله 9 پاک‌سازی»، نمونه Spanner را در انتهای کد لبه خاموش کنید.

Cloud Shell را راه اندازی کنید

در حالی که Google Cloud را می توان از راه دور از لپ تاپ شما کار کرد، در این کد لبه از Google Cloud Shell استفاده خواهید کرد، یک محیط خط فرمان که در Cloud اجرا می شود.

از Google Cloud Console ، روی نماد Cloud Shell در نوار ابزار بالا سمت راست کلیک کنید:

تهیه و اتصال به محیط فقط چند لحظه طول می کشد. وقتی تمام شد، باید چیزی شبیه به این را ببینید:

این ماشین مجازی با تمام ابزارهای توسعه که شما نیاز دارید بارگذاری شده است. این یک فهرست اصلی 5 گیگابایتی دائمی را ارائه می دهد و در Google Cloud اجرا می شود و عملکرد و احراز هویت شبکه را تا حد زیادی افزایش می دهد. تمام کارهای شما در این کد لبه را می توان در یک مرورگر انجام داد. شما نیازی به نصب چیزی ندارید.

بعدی

در مرحله بعد، خوشه Cassandra را مستقر خواهید کرد.

3. استقرار خوشه Cassandra (Origin)

توجه: اگر از قبل یک خوشه Cassandra برای اهداف آزمایشی دارید، می توانید از این مرحله صرف نظر کنید.

برای این کد لبه، ما یک کلاستر تک گره Cassandra را در Compute Engine راه اندازی می کنیم.

1. یک GCE VM برای Cassandra ایجاد کنید

برای ایجاد یک نمونه، از دستور 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. یک فضای کلید و جدول ایجاد کنید

ما از مثال جدول کاربران استفاده می کنیم و یک فضای کلیدی به نام "تحلیل" ایجاد می کنیم.

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 این ماشین مجازی (نام میزبان -I) را یادداشت کنید.

بعدی

در مرحله بعد، یک نمونه Cloud Spanner و پایگاه داده را تنظیم خواهید کرد.

4. ایجاد نمونه و پایگاه داده Spanner (Target)

توجه: اگر قبلاً یک نمونه Spanner برای اهداف آزمایشی در پروژه خود دارید، می توانید از این مرحله صرف نظر کنید. با مراجعه به این لینک کنسول می توانید تأیید کنید

در Spanner، یک نمونه مجموعه ای از منابع محاسباتی و ذخیره سازی است که میزبان یک یا چند پایگاه داده Spanner است. برای میزبانی پایگاه داده Spanner برای این Codelab به حداقل 1 نمونه نیاز دارید.

نسخه gcloud SDK را بررسی کنید

قبل از ایجاد یک نمونه، مطمئن شوید که gcloud SDK در Google Cloud Shell به نسخه مورد نیاز - 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 پروژه شما راه اندازی شده است. از اولین دستور زیر برای پیدا کردن شناسه پروژه پیکربندی شده فعلی استفاده کنید. اگر نتیجه مورد انتظار نیست، دستور دوم زیر دستور درست را تنظیم می کند.

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 مورد استفاده cassandra-adapter-demo است که با استفاده از خط فرمان export به عنوان متغیر SPANNER_INSTANCE_ID تنظیم شده است. به صورت اختیاری، می توانید نام شناسه نمونه خود را انتخاب کنید.

یک نمونه Spanner آزمایشی رایگان ایجاد کنید

یک نمونه آزمایشی رایگان 90 روزه Spanner برای هر کسی که حساب Google دارد و صورت‌حساب Cloud را در پروژه خود فعال کرده باشد، در دسترس است. هزینه ای از شما کسر نمی شود مگر اینکه بخواهید نمونه آزمایشی رایگان خود را به نمونه پولی ارتقا دهید. آداپتور آچار 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"

توجه: این دستور 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.

پایگاه داده را ایجاد کنید

هنگامی که نمونه شما اجرا می شود، می توانید پایگاه داده را ایجاد کنید. پایگاه داده جایی است که شما طرحواره خود را تعریف می کنید. شما همچنین می توانید کنترل کنید که چه کسی به پایگاه داده دسترسی دارد، رمزگذاری سفارشی را تنظیم کنید، بهینه ساز را پیکربندی کنید و دوره نگهداری را تنظیم کنید.

پایگاه داده در نمونه با شناسه 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. طرحواره کاساندرا و مدل داده را به Spanner منتقل کنید

مرحله اولیه و حیاتی انتقال داده ها از پایگاه داده Cassandra به Spanner شامل تغییر طرح واره Cassandra موجود برای همسویی با الزامات ساختاری و نوع داده Spanner است.

برای ساده‌سازی این فرآیند پیچیده انتقال طرحواره، Spanner یک ابزار منبع باز ارزشمند به نام ابزار طرحواره Spanner Cassandra ارائه می‌کند.

ابزار طرحواره آچار کاساندرا

ابزار طرحواره Spanner Cassandra یک ابزار متن باز مستقل برای ارزیابی Spanner و مهاجرت طرحواره است. عملکرد اصلی آن ساخت خودکار یک طرحواره Spanner بر اساس تعاریف موجود در طرحواره کاساندرا موجود است. این ابزار با تجزیه و تحلیل ساختارهای جدول کاساندرا، انواع داده ها و تنظیمات کلید اولیه، تعاریف جدول Spanner معادل را ایجاد می کند و تلاش دستی را که معمولاً در ترجمه طرحواره دخیل است به طور قابل توجهی کاهش می دهد.

صادرات طرح کاساندرا

قبل از استفاده از ابزار طرحواره Spanner Cassandra، اولین گام ملموس این است که طرح را از خوشه Cassandra فعلی خود استخراج کنید. این را می توان با اتصال به خوشه Cassandra موجود از طریق cqlsh و صادرات طرح از Cassandra به دست آورد:

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

در این دستور، [IP] باید با آدرس IP یا نام میزبان یکی از گره های خوشه Cassandra شما جایگزین شود. قسمت -e DESC SCHEMA از دستور به cqlsh دستور می دهد تا کل طرحواره خوشه کاساندرا را توصیف کند. خروجی این دستور که حاوی دستورات CREATE KEYSPACE و CREATE TABLE است، سپس به فایلی با نام orig_schema.cql هدایت می شود.

محتوای این فایل orig_schema.cql اساساً نمایانگر طرح متنی طرحواره کاساندرا شما خواهد بود. محتوای فایل 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';

Repository را شبیه سازی کنید

برای استفاده از ابزار طرحواره Spanner Cassandra، مرحله بعدی شامل به دست آوردن کد منبع ابزار است. این کار با شبیه سازی مخزن میزبانی شده در GitHub انجام می شود. با تایپ دستور زیر در Cloud Shell، ابزار طرحواره Spanner Cassandra را از GitHub کلون کنید:

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

سپس دایرکتوری را به دایرکتوری "spanner-cassandra-schema-tool" تغییر دهید که در آن دستور را اجرا می کنید.

cd spanner-cassandra-schema-tool

Dependencies را نصب کنید

ابزار طرحواره Spanner Cassandra به زبان برنامه نویسی Go نوشته شده است. برای اطمینان از عملکرد صحیح ابزار، به ماژول های Go خارجی خاصی (کتابخانه ها) متکی است. این وابستگی ها باید دانلود و مدیریت شوند تا بتوانید ابزار را اجرا کنید. در پوشه spanner-cassandra-schema-tool ، دستور زیر را اجرا کنید:

go mod download

Google Cloud Credentials را تنظیم کنید

این ابزار از Application Default Credentials (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 را اجرا کنید تا طرح Spanner را از فایل طرحواره Cassandra صادر شده ایجاد کنید. به دایرکتوری spanner-cassandra-schema-tool در ترمینال یا Cloud Shell خود بروید و دستور 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 را به گونه‌های 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 اعمال شود، باید cli را بدون گزینه --dry-run اجرا کنید.

در Google Cloud Console تأیید کنید که جداول و جدول فراداده در پایگاه داده Cloud Spanner وجود دارد.

6. نوشتن دوگانه برای داده های ورودی را تنظیم کنید

[TODO]

7. داده های تاریخی خود را به صورت انبوه صادر کنید

[TODO]

8. داده های خود را اعتبار سنجی کنید

[TODO]

9. برنامه خود را روی Spanner (Cutover) قرار دهید

پس از تأیید دقیق صحت و یکپارچگی داده‌های خود پس از مرحله انتقال، مرحله اساسی انتقال تمرکز عملیاتی برنامه‌تان از سیستم قدیمی کاساندرا به پایگاه داده جدید Google Cloud Spanner است. این دوره انتقال بحرانی معمولاً به عنوان " برش " نامیده می شود.

مرحله قطع، لحظه‌ای را مشخص می‌کند که ترافیک برنامه‌های کاربردی زنده از خوشه اصلی کاساندرا هدایت می‌شود و مستقیماً به زیرساخت قوی و مقیاس‌پذیر Spanner متصل می‌شود. این انتقال نشان می‌دهد که اپلیکیشن‌ها می‌توانند به راحتی از قدرت Spanner استفاده کنند، به‌ویژه زمانی که از رابط Spanner Cassandra استفاده می‌کنند.

با رابط Spanner Cassandra، فرآیند برش ساده می شود. این در درجه اول شامل پیکربندی برنامه های مشتری شما برای استفاده از Spanner Cassandra Client برای تمام تعاملات داده است. به جای برقراری ارتباط با پایگاه داده Cassandra (منبع)، برنامه های شما به طور یکپارچه شروع به خواندن و نوشتن داده ها به طور مستقیم در Spanner (هدف) می کنند. این تغییر اساسی در اتصال معمولاً از طریق استفاده از SpannerCqlSessionBuilder ، یک جزء کلیدی از کتابخانه Spanner Cassandra Client که برقراری اتصالات به نمونه Spanner شما را تسهیل می‌کند، حاصل می‌شود. این به طور موثر کل جریان ترافیک داده برنامه شما را به Spanner تغییر مسیر می دهد.

برای برنامه‌های جاوا که قبلاً از کتابخانه cassandra-java-driver استفاده می‌کنند، ادغام Spanner Cassandra Java Client فقط به تغییرات جزئی در مقدار دهی اولیه CqlSession نیاز دارد.

دریافت وابستگی به google-cloud-spanner-cassandra

برای شروع استفاده از Spanner Cassandra Client، ابتدا باید وابستگی آن را در پروژه خود بگنجانید. مصنوعات google-cloud-spanner-cassandra در Maven central، تحت شناسه گروه com.google.cloud منتشر شده است. وابستگی جدید زیر را در بخش <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 خود را تغییر دهید. به جای استفاده مستقیم از CqlSessionBuilder استاندارد از cassandra-java-driver ، از SpannerCqlSession.builder() ارائه شده توسط Spanner Cassandra Client استفاده خواهید کرد. در اینجا یک مثال گویا از نحوه تغییر کد اتصال خود آورده شده است:

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 صحیح Uri، برنامه شما اکنون از طریق Spanner Cassandra Client به پایگاه داده Spanner مورد نظر شما ارتباط برقرار می کند. این تغییر محوری تضمین می‌کند که تمام عملیات خواندن و نوشتن بعدی که توسط برنامه شما انجام می‌شوند به Spanner هدایت می‌شوند و توسط Spanner ارائه می‌شوند و عملاً برش اولیه را تکمیل می‌کنند. در این مرحله ، برنامه شما باید همانطور که انتظار می رود ، عملکرد خود را ادامه دهد ، که اکنون از مقیاس پذیری و قابلیت اطمینان Spanner استفاده می شود.

زیر کاپوت: چگونه مشتری Cassandra Spanner عملکرد دارد

مشتری Spanner Cassandra به عنوان یک پروکسی محلی TCP عمل می کند و بایت پروتکل Raw Cassandra را که توسط یک درایور یا ابزار مشتری ارسال شده است ، رهگیری می کند. سپس این بایت ها را به همراه ابرداده لازم در پیام های GRPC برای ارتباط با Spanner می پیچد. پاسخ های Spanner دوباره به قالب سیم Cassandra ترجمه شده و به درایور یا ابزار مبدا ارسال می شود.

هنگامی که شما اطمینان دارید که Spanner به طور صحیح به تمام ترافیک خدمت می کند ، در نهایت می توانید:

• نوشتن دوگانه را متوقف کنید.
• خوشه اصلی کاساندرا را از بین ببرید.

10. تمیز کردن (اختیاری)

برای تمیز کردن ، کافی است به بخش Spanner کنسول ابر بروید و نمونه cassandra-adapter-demo را که در CodeLab ایجاد کردیم حذف کنید.

پایگاه داده Cassandra را حذف کنید (در صورت نصب محلی یا ادامه)

اگر Cassandra را در خارج از موتور محاسباتی VM ایجاد کرده اید که در اینجا ایجاد شده است ، مراحل مناسب را برای حذف داده ها یا حذف کاساندرا دنبال کنید.

11. تبریک می گویم!

بعدش چی؟

• درباره Cloud Spanner بیشتر بدانید.
• درباره رابط کاساندرا بیشتر بدانید.

شروع با آداپتور Spanner Cassandra

درباره این codelab

آخرین به‌روزرسانی: مه ۲۱, ۲۰۲۵

نویسنده: Mayur Kale, Vardhan Thigle

1. مقدمه

Spanner یک سرویس پایگاه داده کاملاً مدیریت شده ، افقی مقیاس پذیر و توزیع شده در سطح جهانی است که برای بارهای کاری رابطه ای و غیر مرتبط بسیار عالی است.

رابط کاساندرا Spanner به شما امکان می دهد از زیرساخت های کاملاً مدیریت شده ، مقیاس پذیر و بسیار در دسترس Spanner با استفاده از ابزارهای و نحو آشنا کاساندرا استفاده کنید.

چیزی که یاد خواهید گرفت

• نحوه تنظیم یک نمونه و بانک اطلاعاتی.
• نحوه تبدیل طرحواره و مدل داده کاساندرا.
• نحوه استقرار و پیکربندی نوشتن دوگانه برای داده های دریافتی.
• چگونه می توان داده های تاریخی خود را از Cassandra به Spanner صادر کرد.
• نحوه اعتبار سنجی داده ها برای اطمینان از یکپارچگی داده ها در طول فرآیند مهاجرت.
• چگونه می توان به جای کاساندرا ، درخواست خود را به Spanner اشاره کرد.

آنچه شما نیاز دارید

• یک پروژه Google Cloud که به یک حساب صورتحساب وصل شده است.
• دسترسی به یک دستگاه با gcloud CLI نصب و پیکربندی شده ، یا از Google Cloud Shell استفاده کنید.
• یک مرورگر وب ، مانند Chrome یا Firefox .

2. راه اندازی و الزامات

توجه: اگر در حال حاضر یک پروژه GCP با فعال کردن صورتحساب دارید ، می توانید از این مرحله پرش کنید.

یک پروژه GCP ایجاد کنید

وارد کنسول Google Cloud شوید و یک پروژه جدید ایجاد کنید یا از یک مورد موجود استفاده کنید. اگر قبلاً یک حساب کاربری Gmail یا Google ندارید ، باید یکی را ایجاد کنید .

• نام پروژه نام نمایشگر شرکت کنندگان این پروژه است. این یک رشته کاراکتر است که توسط Google API استفاده نمی شود. همیشه می توانید آن را به روز کنید.
• شناسه پروژه در تمام پروژه های Google Cloud بی نظیر است و تغییر ناپذیر است (پس از تنظیم آن قابل تغییر نیست). کنسول ابر یک رشته منحصر به فرد را ایجاد می کند. معمولاً اهمیتی نمی دهید که چیست. در اکثر CodeLabs ، باید شناسه پروژه خود را (که به طور معمول به عنوان PROJECT_ID مشخص می شود) ارجاع دهید. اگر شناسه تولید شده را دوست ندارید ، ممکن است یک تصادفی دیگر ایجاد کنید. از طرف دیگر ، می توانید خودتان را امتحان کنید و ببینید که آیا در دسترس است یا خیر. بعد از این مرحله قابل تغییر نیست و برای مدت زمان پروژه باقی می ماند.
• برای اطلاعات شما ، یک مقدار سوم ، یک شماره پروژه وجود دارد که برخی از API ها از آن استفاده می کنند. در مورد هر سه این مقادیر در مستندات بیشتر بدانید.

احتیاط: شناسه پروژه در سطح جهانی منحصر به فرد است و پس از انتخاب آن توسط شخص دیگری قابل استفاده نیست. شما تنها کاربر آن شناسه هستید. حتی اگر یک پروژه حذف شود ، از شناسه دیگر قابل استفاده نیست

توجه: اگر از یک حساب Gmail استفاده می کنید ، می توانید مکان پیش فرض تنظیم شده بر روی هیچ سازمانی را ترک کنید. اگر از یک حساب کاربری Google استفاده می کنید ، مکانی را انتخاب کنید که برای سازمان شما معنی داشته باشد.

تنظیم صورتحساب

در مرحله بعد ، باید راهنمای کاربر را مدیریت کنید و صورتحساب را در کنسول ابر فعال کنید. کاربران جدید Google Cloud واجد شرایط برنامه آزمایشی رایگان 300 دلاری USD هستند. برای جلوگیری از صدور صورتحساب فراتر از این آموزش ، می توانید با دنبال کردن "مرحله 9 تمیز کردن" ، نمونه Spanner را در انتهای CodeLab خاموش کنید.

پوسته ابر را شروع کنید

در حالی که Google Cloud می تواند از راه دور از لپ تاپ شما کار کند ، در این CodeLab شما از Google Cloud Shell استفاده می کنید ، یک محیط خط فرمان که در ابر اجرا می شود.

از کنسول Google Cloud ، روی نماد Cloud Shell در نوار ابزار بالا راست کلیک کنید:

فقط باید چند لحظه طول بکشد و به محیط زیست ارتباط برقرار کند. پس از اتمام ، باید چیزی شبیه به این را ببینید:

این دستگاه مجازی با تمام ابزارهای توسعه مورد نیاز شما بارگیری شده است. این یک دایرکتوری خانگی مداوم 5 گیگابایتی را ارائه می دهد ، و در Google Cloud اجرا می شود و عملکرد و احراز هویت شبکه را تا حد زیادی تقویت می کند. تمام کارهای شما در این CodeLab را می توان در یک مرورگر انجام داد. نیازی به نصب چیزی ندارید.

بعدی

بعد ، خوشه کاساندرا را مستقر خواهید کرد.

3. استقرار خوشه کاساندرا (مبدا)

توجه: اگر در حال حاضر یک خوشه Cassandra برای اهداف آزمایش دارید ، می توانید از این مرحله پرش کنید.

برای این CodeLab ، ما یک خوشه کاساندرا تک گره را بر روی موتور محاسباتی تنظیم خواهیم کرد.

1. یک 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. کاساندرا را نصب کنید

# 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 را باز کنید یا آدرس IP این VM (نام میزبان -i) را باز کنید.

بعدی

در مرحله بعد ، شما یک نمونه و بانک اطلاعاتی Cloud Spanner را تنظیم خواهید کرد.

4. یک نمونه و بانک اطلاعاتی Spanner (Target) ایجاد کنید

توجه: اگر در حال حاضر یک نمونه Spanner برای اهداف آزمایش در پروژه خود دارید ، می توانید از این مرحله پرش کنید. با مراجعه به این لینک کنسول می توانید تأیید کنید

در Spanner ، نمونه ای از منابع محاسباتی و ذخیره سازی است که میزبان یک یا چند پایگاه داده Spanner است. برای میزبانی یک پایگاه داده Spanner برای این CodeLab حداقل به 1 نمونه نیاز دارید.

نسخه Gcloud SDK را بررسی کنید

قبل از ایجاد یک نمونه ، اطمینان حاصل کنید که GCLOUD SDK در Google Cloud Shell به نسخه مورد نیاز به روز شده است - 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

توجه: دستور قبلی به دلایل امنیتی بسته های به روز شده را به طور جامع لیست می کند.

API Spanner را فعال کنید

در داخل Cloud Shell ، اطمینان حاصل کنید که شناسه پروژه شما تنظیم شده است. برای یافتن شناسه پروژه پیکربندی شده در حال حاضر از اولین دستور زیر استفاده کنید. اگر نتیجه انتظار نداشته باشد ، دستور دوم زیر را تنظیم می کند.

gcloud config get-value project

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

منطقه پیش فرض خود را به us-central1 پیکربندی کنید. احساس راحتی کنید که این امر را به منطقه دیگری که توسط تنظیمات منطقه ای Spanner پشتیبانی می شود ، تغییر دهید.

gcloud config set compute/region us-central1

API Spanner را فعال کنید:

gcloud services enable spanner.googleapis.com

نمونه Spanner را ایجاد کنید

در این بخش ، شما یک نمونه آزمایشی رایگان یا یک نمونه ارائه شده ایجاد خواهید کرد. در طول این CodeLab ، شناسه نمونه آداپتور Cassandra Spanner استفاده شده cassandra-adapter-demo است که با استفاده از خط فرمان export به عنوان متغیر SPANNER_INSTANCE_ID تنظیم شده است. به صورت اختیاری ، می توانید نام شناسه نمونه خود را انتخاب کنید.

یک نمونه دهانه محاکمه آزاد ایجاد کنید

یک نمونه آزمایشی رایگان 90 روزه Spanner برای هر کسی که دارای حساب Google است که دارای صورتحساب ابر در پروژه خود است ، در دسترس است. شما متهم نیستید مگر اینکه تصمیم بگیرید نمونه آزمایشی رایگان خود را به یک نمونه پرداخت شده ارتقا دهید. آداپتور 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"

توجه: این دستور 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.

پایگاه داده را ایجاد کنید

پس از اجرای نمونه شما ، می توانید پایگاه داده را ایجاد کنید. بانک اطلاعاتی جایی است که طرحواره خود را تعریف می کنید. همچنین می توانید کنترل کنید که چه کسی به پایگاه داده دسترسی دارد ، رمزگذاری سفارشی را تنظیم کرده ، بهینه ساز را پیکربندی کرده و دوره نگهداری را تنظیم می کند.

این پایگاه داده به عنوان مثال با 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. طرح و مدل داده کاساندرا را به Spanner مهاجرت کنید

مرحله اولیه و مهم انتقال داده ها از یک پایگاه داده Cassandra به Spanner شامل تبدیل طرحواره Cassandra موجود برای تراز کردن با الزامات ساختاری و داده های Spanner است.

برای ساده سازی این فرآیند مهاجرت طرحواره پیچیده ، Spanner یک ابزار با ارزش منبع باز را که به عنوان ابزار SPANNER CASSANDRA Schema شناخته شده است ، ارائه می دهد.

ابزار SPANNER CASSANDRA SCHEMA

ابزار SPANNER CASSANDRA SCHEMA ابزاری برای منبع باز مستقل برای ارزیابی Spanner و مهاجرت طرحواره است. عملکرد اصلی آن ساخت خودکار یک طرح اسپانیایی بر اساس تعاریف موجود در یک طرح Cassandra موجود است. این ابزار با تجزیه و تحلیل ساختارهای جدول کاساندرا ، انواع داده ها و تنظیمات اصلی اصلی ، تعاریف جدول Spanner را ایجاد می کند ، و تلاش دستی را که معمولاً در ترجمه طرحواره درگیر است ، به طور قابل توجهی کاهش می دهد.

شمای کاساندرا صادراتی

قبل از استفاده از ابزار SPANNER CASSANDRA SCHEMA ، اولین قدم بتونی استخراج طرحواره از خوشه فعلی کاساندرا است. این امر می تواند با اتصال به خوشه Cassandra موجود از طریق cqlsh و صادرات طرح از Cassandra حاصل شود:

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

در این دستور ، [IP] باید با آدرس IP یا نام میزبان یکی از گره های موجود در خوشه کاساندرا جایگزین شود. بخش -e DESC SCHEMA از فرمان به CQLSH دستور می دهد تا کل طرحواره خوشه کاساندرا را توصیف کند. خروجی این دستور ، که شامل ایجاد کلید ایجاد و ایجاد اظهارات جدول است ، سپس به پرونده ای به نام 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';

Repository را شبیه سازی کنید

برای استفاده از ابزار SPANNER CASSANDRA SCHEMA ، مرحله بعدی شامل به دست آوردن کد منبع ابزار است. این کار با کلون کردن مخزن میزبان GitHub انجام می شود. کلون ابزار SPANNER CASSANDRA Schema از GitHub با تایپ دستور زیر در پوسته ابر:

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

سپس دایرکتوری را به فهرست "Spanner-Cassandra-Schema-Tool" تغییر دهید که در آن فرمان را اجرا خواهید کرد.

cd spanner-cassandra-schema-tool

Dependencies را نصب کنید

ابزار Spanner Cassandra Schema به زبان برنامه نویسی 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 /your/service-account-file.json با مسیر واقعی پرونده کلید حساب کاربری سرویس بارگیری شده خود. تنظیم این متغیر محیط تضمین می کند که ابزار SPANNER CASSANDRA SCHEMA می تواند به طور ایمن با پروژه Google Cloud و نمونه Spanner شما تأیید شود.

استفاده

پس از نصب وابستگی ها و اعتبارنامه های Google Cloud ، شما آماده هستید تا ابزار SPANNER CASSANDRA Schema را برای تولید طرح Spanner از پرونده Schema Cassandra صادر شده اجرا کنید. به فهرست ترمینال یا پوسته 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 مربوطه است.

این ابزار انواع کاساندرا را به انواع 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 اعمال شود ، باید CLI را بدون گزینه --dry-run اجرا کنید.

در کنسول Google Cloud تأیید کنید که جدول و جدول ابرداده در پایگاه داده Cloud Spanner وجود دارد.

6. برای داده های دریافتی نوشتن دوگانه را تنظیم کنید

[TODO]

7. فله داده های تاریخی خود را صادر کنید

[TODO]

8. داده های خود را اعتبار سنجی کنید

[TODO]

9. برنامه خود را به Spanner (برش) اشاره کنید

پس از تأیید دقیق دقت و یکپارچگی داده های خود پس از مرحله مهاجرت ، مرحله مهم انتقال تمرکز عملیاتی برنامه شما از سیستم میراث کاساندرا شما به پایگاه داده تازه جمع آوری Google Cloud Spanner است. این دوره انتقال بحرانی معمولاً به عنوان " قطع " گفته می شود.

فاز برش لحظه ای را نشان می دهد که ترافیک برنامه زنده از خوشه اصلی کاساندرا هدایت می شود و مستقیماً به زیرساخت های Spanner قوی و مقیاس پذیر متصل می شود. این انتقال سهولت را نشان می دهد که برنامه ها می توانند از قدرت Spanner استفاده کنند ، به خصوص هنگام استفاده از رابط Spanner Cassandra.

با رابط Cassandra Spanner ، فرآیند برش ساده می شود. این در درجه اول شامل پیکربندی برنامه های مشتری شما برای استفاده از مشتری بومی Cassandra برای همه تعامل داده ها است. به جای برقراری ارتباط با پایگاه داده Cassandra (Origin) خود ، برنامه های شما یکپارچه شروع به خواندن و نوشتن داده ها به طور مستقیم به Spanner (Target) می کنند. این تغییر اساسی در اتصال به طور معمول از طریق استفاده از SpannerCqlSessionBuilder ، یک مؤلفه اصلی کتابخانه مشتری Cassandra Spanner که باعث ایجاد اتصالات به نمونه Spanner شما می شود ، حاصل می شود. این به طور موثری جریان ترافیک داده های برنامه شما را به Spanner تغییر می دهد.

برای برنامه های جاوا که قبلاً از کتابخانه cassandra-java-driver استفاده می کنند ، ادغام مشتری Cassandra Java Spanner فقط نیاز به تغییرات جزئی در اولیه سازی CqlSession دارد.

گرفتن وابستگی Google-Cloud-Spanner-Cassandra

برای شروع استفاده از مشتری Cassandra Spanner ، ابتدا باید وابستگی آن را در پروژه خود وارد کنید. آثار باستانی google-cloud-spanner-cassandra در Maven Central ، تحت گروه شناسه گروه com.google.cloud منتشر می شود. وابستگی جدید زیر را در بخش موجود <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 است.

یک برنامه معمولی که با یک خوشه کاساندرا در تعامل است ، اغلب از کد مشابه موارد زیر برای برقراری ارتباط استفاده می کند:

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

برای هدایت این اتصال به Spanner ، باید منطق ایجاد CqlSession خود را تغییر دهید. به جای استفاده مستقیم از CqlSessionBuilder استاندارد از cassandra-java-driver ، از SpannerCqlSession.builder() ارائه شده توسط مشتری Cassandra Spanner استفاده خواهید کرد. در اینجا یک مثال مصور از نحوه تغییر کد اتصال خود آورده شده است:

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 یک پارامتر مهم است که مکان دقیق پایگاه داده Target Spanner شما را مشخص می کند. این فرمت را دنبال می کند: projects/<your-gcp-project>/instances/your-spanner-instance>/databases/<your-spanner-database> . اطمینان حاصل کنید که صاحبخانه ها را با شناسه پروژه Google Cloud واقعی خود ، نام نمونه Spanner و نام پایگاه داده Spanner جایگزین می کنید.

با استفاده از CqlSession با استفاده از SpannerCqlSession.builder() و تهیه صحیح databaseUri ، برنامه شما اکنون ارتباطی را از طریق مشتری Cassandra Spanner به پایگاه داده Target Spanner خود برقرار می کند. این تغییر محوری تضمین می کند که تمام عملیات خواندن و نوشتن بعدی که توسط برنامه شما انجام می شود ، توسط Spanner هدایت و خدمت می شود و به طور مؤثر برش اولیه را تکمیل می کند. در این مرحله ، برنامه شما باید همانطور که انتظار می رود ، عملکرد خود را ادامه دهد ، که اکنون از مقیاس پذیری و قابلیت اطمینان Spanner استفاده می شود.

زیر کاپوت: چگونه مشتری Cassandra Spanner عملکرد دارد

مشتری Spanner Cassandra به عنوان یک پروکسی محلی TCP عمل می کند و بایت پروتکل Raw Cassandra را که توسط یک درایور یا ابزار مشتری ارسال شده است ، رهگیری می کند. سپس این بایت ها را به همراه ابرداده لازم در پیام های GRPC برای ارتباط با Spanner می پیچد. پاسخ های Spanner دوباره به قالب سیم Cassandra ترجمه شده و به درایور یا ابزار مبدا ارسال می شود.

هنگامی که شما اطمینان دارید که Spanner به طور صحیح به تمام ترافیک خدمت می کند ، در نهایت می توانید:

• نوشتن دوگانه را متوقف کنید.
• خوشه اصلی کاساندرا را از بین ببرید.

10. تمیز کردن (اختیاری)

برای تمیز کردن ، کافی است به بخش Spanner کنسول ابر بروید و نمونه cassandra-adapter-demo را که در CodeLab ایجاد کردیم حذف کنید.

پایگاه داده Cassandra را حذف کنید (در صورت نصب محلی یا ادامه)

اگر Cassandra را در خارج از موتور محاسباتی VM ایجاد کرده اید که در اینجا ایجاد شده است ، مراحل مناسب را برای حذف داده ها یا حذف کاساندرا دنبال کنید.

11. تبریک می گویم!

بعدش چی؟

• درباره Cloud Spanner بیشتر بدانید.
• درباره رابط کاساندرا بیشتر بدانید.