Начало работы с адаптером Spanner Cassandra,Начало работы с адаптером Spanner Cassandra,Начало работы с адаптером Spanner Cassandra

Начало работы с адаптером Spanner Cassandra

О практической работе

Последнее обновление: мая 21, 2025

Авторы: Mayur Kale, Vardhan Thigle

1. Введение

Spanner — это полностью управляемая, горизонтально масштабируемая, глобально распределенная служба базы данных, которая отлично подходит как для реляционных, так и для нереляционных рабочих нагрузок.

Интерфейс Spanner Cassandra позволяет вам воспользоваться преимуществами полностью управляемой, масштабируемой и высокодоступной инфраструктуры 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, вам необходимо ее создать .

• Имя проекта — это отображаемое имя для участников этого проекта. Это строка символов, не используемая API Google. Вы всегда можете ее обновить.
• Идентификатор проекта уникален для всех проектов Google Cloud и неизменяем (его нельзя изменить после установки). Cloud Console автоматически генерирует уникальную строку; обычно вам все равно, что это такое. В большинстве кодовых лабораторий вам нужно будет ссылаться на свой идентификатор проекта (обычно идентифицируемый как PROJECT_ID ). Если вам не нравится сгенерированный идентификатор, вы можете сгенерировать другой случайный идентификатор. В качестве альтернативы вы можете попробовать свой собственный и посмотреть, доступен ли он. Его нельзя изменить после этого шага, и он остается на протяжении всего проекта.
• Для информации, есть третье значение, Project Number , которое используют некоторые API. Узнайте больше обо всех трех этих значениях в документации .

Внимание: ID проекта является глобально уникальным и не может быть использован кем-либо еще после того, как вы его выбрали. Вы являетесь единственным пользователем этого ID. Даже если проект удален, ID не может быть использован снова

Примечание: Если вы используете учетную запись Gmail, вы можете оставить местоположение по умолчанию на No organization . Если вы используете учетную запись Google Workspace, выберите местоположение, которое имеет смысл для вашей организации.

Настройка выставления счетов

Далее вам нужно будет следовать руководству пользователя по управлению выставлением счетов и включить выставление счетов в Cloud Console . Новые пользователи Google Cloud имеют право на бесплатную пробную программу стоимостью 300 долларов США . Чтобы избежать выставления счетов за пределами этого руководства, вы можете закрыть экземпляр Spanner в конце кодовой лаборатории, выполнив «Шаг 9 Очистка».

Запустить Cloud Shell

Хотя Google Cloud можно управлять удаленно с вашего ноутбука, в этой лабораторной работе вы будете использовать Google Cloud Shell — среду командной строки, работающую в облаке.

В Google Cloud Console щелкните значок Cloud Shell на верхней правой панели инструментов:

Подготовка и подключение к среде займет всего несколько минут. Когда все будет готово, вы увидите что-то вроде этого:

Эта виртуальная машина загружена всеми необходимыми вам инструментами разработки. Она предлагает постоянный домашний каталог на 5 ГБ и работает на Google Cloud, что значительно повышает производительность сети и аутентификацию. Вся ваша работа в этой кодовой лаборатории может быть выполнена в браузере. Вам не нужно ничего устанавливать.

Далее

Далее вы развернете кластер Cassandra.

3. Развертывание кластера Cassandra (Origin)

Примечание: этот шаг можно пропустить, если у вас уже есть кластер Cassandra для тестирования.

Для этой кодовой лаборатории мы настроим кластер Cassandra с одним узлом на Compute Engine.

1. Создайте виртуальную машину GCE для 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. Установить Кассандру

# 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. Вам понадобится как минимум 1 экземпляр для размещения базы данных Spanner для этой кодовой лаборатории.

Проверьте версию SDK gcloud

Перед созданием экземпляра убедитесь, что 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

В этом разделе вы создадите либо бесплатный пробный экземпляр , либо подготовленный экземпляр . В этой кодовой лаборатории идентификатор экземпляра адаптера Spanner Cassandra — cassandra-adapter-demo , заданный как переменная SPANNER_INSTANCE_ID с помощью командной строки export . При желании вы можете выбрать собственное имя идентификатора экземпляра.

Создайте бесплатный пробный экземпляр Spanner

Бесплатный 90-дневный пробный экземпляр Spanner доступен любому человеку с учетной записью Google, у которого включен Cloud Billing в проекте. С вас не взимается плата, если вы не решите обновить свой бесплатный пробный экземпляр до платного. Адаптер 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.

Создать базу данных

После запуска вашего экземпляра вы можете создать базу данных. В базе данных вы определяете свою схему. Вы также можете контролировать, кто имеет доступ к базе данных, настраивать пользовательское шифрование, настраивать оптимизатор и устанавливать период хранения.

База данных будет создана в экземпляре с идентификатором SPANNER_INSTANCE_ID .

Чтобы создать базу данных, используйте инструмент командной строки gcloud:

export SPANNER_DATABASE=analytics
gcloud spanner databases create $SPANNER_DATABASE \
 --instance=$SPANNER_INSTANCE_ID

Вывод команды:

$ gcloud spanner databases create $SPANNER_DATABASE \
 --instance=$SPANNER_INSTANCE_ID
Creating database...done.

5. Перенос схемы Cassandra и модели данных в Spanner

Начальный и решающий этап переноса данных из базы данных Cassandra в Spanner включает преобразование существующей схемы Cassandra для приведения ее в соответствие со структурными и типовыми требованиями Spanner.

Для упрощения этого сложного процесса миграции схемы Spanner предоставляет ценный инструмент с открытым исходным кодом, известный как инструмент Spanner Cassandra schema.

Инструмент схемы Spanner Cassandra

Инструмент Spanner Cassandra schema — это автономный инструмент с открытым исходным кодом для оценки и миграции схем Spanner. Его основная функция — автоматическое построение схемы Spanner на основе определений, найденных в существующей схеме Cassandra. Анализируя структуры таблиц Cassandra, типы данных и конфигурации первичных ключей, инструмент генерирует эквивалентные определения таблиц Spanner, что значительно сокращает ручные усилия, обычно необходимые для перевода схем.

Экспортировать схему Cassandra

Перед использованием инструмента Spanner Cassandra schema, первым конкретным шагом является извлечение схемы из текущего кластера Cassandra. Это можно сделать, подключившись к существующему кластеру Cassandra через cqlsh и экспортировав схему из Cassandra:

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

В этой команде [IP] следует заменить на IP-адрес или имя хоста одного из узлов в кластере Cassandra. Часть команды -e DESC SCHEMA предписывает cqlsh описать всю схему кластера Cassandra. Вывод этой команды, содержащий операторы CREATE KEYSPACE и CREATE TABLE, затем перенаправляется в файл с именем orig_schema.cql .

Содержимое этого файла orig_schema.cql по сути будет представлять собой текстовый план вашей схемы Cassandra. Содержимое файла orig_schema.cql должно выглядеть следующим образом:

CREATE KEYSPACE analytics WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'}  AND durable_writes = true;

CREATE TABLE analytics.users (
    id int PRIMARY KEY,
    active boolean,
    username text
) WITH additional_write_policy = '99p'
    AND allow_auto_snapshot = true
    AND bloom_filter_fp_chance = 0.01
    AND caching = {'keys': 'ALL', 'rows_per_partition': 'NONE'}
    AND cdc = false
    AND comment = ''
    AND compaction = {'class': 'org.apache.cassandra.db.compaction.SizeTieredCompactionStrategy', 'max_threshold': '32', 'min_threshold': '4'}
    AND compression = {'chunk_length_in_kb': '16', 'class': 'org.apache.cassandra.io.compress.LZ4Compressor'}
    AND memtable = 'default'
    AND crc_check_chance = 1.0
    AND default_time_to_live = 0
    AND extensions = {}
    AND gc_grace_seconds = 864000
    AND incremental_backups = true
    AND max_index_interval = 2048
    AND memtable_flush_period_in_ms = 0
    AND min_index_interval = 128
    AND read_repair = 'BLOCKING'
    AND speculative_retry = '99p';

Клонировать репозиторий

Чтобы использовать инструмент схемы Spanner Cassandra, следующим шагом будет получение исходного кода инструмента. Это делается путем клонирования репозитория, размещенного на GitHub. Клонируйте инструмент схемы Spanner Cassandra из GitHub, введя следующую команду в Cloud Shell:

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

Затем перейдите в каталог «spanner-cassandra-schema-tool», где вы будете запускать команду.

cd spanner-cassandra-schema-tool

Установить зависимости

Инструмент Spanner Cassandra schema написан на языке программирования Go. Для обеспечения корректной работы инструмента он использует определенные внешние модули Go (библиотеки). Эти зависимости необходимо загрузить и настроить перед запуском инструмента. В каталоге spanner-cassandra-schema-tool выполните следующую команду:

go mod download

Настройте учетные данные Google Cloud

Этот инструмент использует 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 schema для генерации схемы 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.

Этот инструмент сопоставляет типы 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. Настройте двойную запись для входящих данных

[ТОДО]

7. Массовый экспорт ваших исторических данных

[ТОДО]

8. Проверьте свои данные

[ТОДО]

9. Направьте свое приложение в Spanner (Cutover)

После тщательной проверки точности и целостности ваших данных после фазы миграции, ключевым шагом является перенос операционного фокуса вашего приложения с вашей устаревшей системы Cassandra на новую заполненную базу данных Google Cloud Spanner. Этот критический переходный период обычно называют « cutover ».

Фаза переключения отмечает момент, когда трафик живого приложения перенаправляется из исходного кластера Cassandra и напрямую подключается к надежной и масштабируемой инфраструктуре Spanner. Этот переход демонстрирует легкость, с которой приложения могут использовать возможности Spanner, особенно при использовании интерфейса Spanner Cassandra.

С интерфейсом Spanner Cassandra процесс переключения упрощается. Он в первую очередь включает настройку ваших клиентских приложений для использования собственного клиента Spanner Cassandra для всех взаимодействий с данными. Вместо того, чтобы взаимодействовать с вашей базой данных Cassandra (исходной), ваши приложения будут плавно начинать читать и записывать данные непосредственно в Spanner (целевой). Этот фундаментальный сдвиг в подключении обычно достигается с помощью SpannerCqlSessionBuilder , ключевого компонента библиотеки Spanner Cassandra Client, который облегчает установление подключений к вашему экземпляру Spanner. Это эффективно перенаправляет весь поток трафика данных вашего приложения в Spanner.

Для приложений Java, уже использующих библиотеку cassandra-java-driver , интеграция клиента Spanner Cassandra Java Client требует лишь незначительных изменений в инициализации CqlSession .

Получение зависимости google-cloud-spanner-cassandra

Чтобы начать использовать клиент Spanner Cassandra, вам сначала нужно включить его зависимость в свой проект. Артефакты google-cloud-spanner-cassandra опубликованы в Maven central, в группе id com.google.cloud . Добавьте следующую новую зависимость в существующий раздел <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 . Вместо прямого использования стандартного 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 , ваше приложение теперь установит соединение через Spanner Cassandra Client с вашей целевой базой данных Spanner. Это кардинальное изменение гарантирует, что все последующие операции чтения и записи, выполняемые вашим приложением, будут направлены и обслуживаться Spanner, эффективно завершая первоначальное переключение. На этом этапе ваше приложение должно продолжать функционировать, как и ожидалось, теперь подкрепленное масштабируемостью и надежностью Spanner.

Под капотом: как работает клиент Spanner Cassandra

Клиент Spanner Cassandra действует как локальный TCP-прокси, перехватывая необработанные байты протокола Cassandra, отправленные драйвером или клиентским инструментом. Затем он упаковывает эти байты вместе с необходимыми метаданными в сообщения gRPC для связи со Spanner. Ответы от Spanner преобразуются обратно в формат Cassandra wire и отправляются обратно исходному драйверу или инструменту.

Убедившись, что Spanner правильно обрабатывает весь трафик, вы сможете:

• Остановить двойную запись.
• Вывести из эксплуатации исходный кластер Кассандра.

10. Уборка (по желанию)

Чтобы очистить код, просто перейдите в раздел Spanner в Cloud Console и удалите экземпляр cassandra-adapter-demo который мы создали в кодовой лаборатории.

Удалить базу данных Cassandra (если она установлена ​​локально или сохранена)

Если вы установили Cassandra вне созданной здесь виртуальной машины Compute Engine, выполните соответствующие шаги для удаления данных или удаления Cassandra.

11. Поздравляю!

Что дальше?

• Узнайте больше о Cloud Spanner .
• Узнайте больше об интерфейсе Cassandra .