Руководство для начинающих

В этом руководстве вы познакомитесь с основными возможностями Tarantool DataBase. В примере вы создаете шардированный спейс через миграции, выполняете запросы к нему с помощью модуля CRUD, а затем проверяете работу кластера при остановке узла.

Запустить кластер для выполнения примера можно, используя любой способ развертывания:

• инсталлятор Ansible Tarantool Enterprise;
• Docker Compose;
• утилиту tt CLI.

В руководстве для развертывания используется Docker Compose.

Руководство включает следующие шаги:

• Пререквизиты
• Запуск стенда
• Создание спейса
• Запросы к данным c помощью модуля CRUD
• Поиск кортежей в TCM
• Проверка работы кластера при отказах
• Остановка стенда

Для выполнения примера требуются:

• установленные Docker-образы Tarantool DB, Prometheus и Grafana;

• приложение Docker Compose;

• утилита tt CLI;

• исходные файлы примера up_with_docker_compose.

Перейдите в директорию примера up_with_docker_compose:

 
cd ./docs/docs/ru/assets/examples/up_with_docker_compose/

Запустите кластер Tarantool DB:

 
make start

Команда развернет стенд, состоящий из:

• кластера Tarantool DB:
  • 2 роутера;
  • 2 набора реплик по 3 хранилища;
  • веб-интерфейса Tarantool Cluster Manager (TCM);
• кластера etcd из 3 узлов;
• средств мониторинга (Prometheus, Grafana).

После запуска должны работать все контейнеры, кроме init_host.

В качестве веб-интерфейса кластера Tarantool DB используется Tarantool Cluster Manager, или TCM. Tarantool Cluster Manager — это инструмент для настройки и отслеживания кластеров Tarantool EE и управления ими. Подробная информация о TCM приведена в документации Tarantool.

TCM станет доступен после запуска стенда по адресу http://localhost:8081. Общее описание вкладок TCM приведено в разделе Обзор веб-интерфейса.

Чтобы войти в TCM, откройте в браузере адрес http://localhost:8081. Логин и пароль для входа:

• Username: admin
• Password: secret

Пароль для входа указан в конфигурации TCM в файле tcm.yml (см. опцию TCM security.bootstrap-password):

 
security:  bootstrap-password: secret

Если секция security не указана в файле, пароль будет сгенерирован автоматически. Чтобы получить сгенерированный пароль, используйте такую команду:

 
docker compose logs tcm-1 | grep "super admin"

В TCM откройте вкладку Stateboard. После применения настроек кластер будет выглядеть так:

После запуска с кластером Tarantool DB можно работать через веб-интерфейс TCM, коннекторы или консоль tt CLI.

Пользовательские объекты, например спейсы, создаются в базе данных с помощью миграций. В примере во время запуска стенда создан спейс bands. Спейс имеет такой формат:

 
local space_bands = box.schema.space.create('bands', {    if_not_exists = true,    format = {        { name = 'id', type = 'integer' },        { name = 'bucket_id', type = 'unsigned' },        { name = 'band_name', type = 'string' },        { name = 'year', type = 'integer' },    },})space_bands:create_index('primary_key', { parts = {'id'}, if_not_exists = true})space_bands:create_index('bucket_id', { parts = {'bucket_id'}, unique = false, if_not_exists = true})helpers.register_sharding_key(space_bands.name, {'id'})

Код создания спейса описан в файле migrations/scenario/002_create_space_bands.lua. Чтобы применить этот код, используются команды tt CLI:

 
tt migrations publish http://etcd1:2379/tdb migrationstt migrations up http://etcd1:2379/tdb --tarantool-cluster-username=admin --tarantool-cluster-password=secret-cluster-cookie

Узнать больше о командах tt migrations можно в документации Tarantool.

Содержимое спейса на каждом узле кластера можно просмотреть в TCM во вкладке Tuples.

Чтобы начать работу с базой данных через интерактивную консоль Tarantool, нужно подключиться к узлу кластера. Сделать это можно двумя способами:

• в веб-интерфейсе TCM;

• в терминале с помощью утилиты tt CLI:

   
  tt connect admin:secret-cluster-cookie@localhost:3301

Подключитесь к роутеру, используя первый способ — через TCM. Для этого:

1. Перейдите на вкладку Stateboard.
2. Нажмите на набор реплик router-msk.
3. Выберите узел router-msk и в открывшемся окне перейдите на вкладку Terminal:

Во вкладке Terminal добавьте в спейс bands несколько кортежей:

 
crud.insert_object('bands', {id = 1, band_name = 'Roxette', year = 1986})crud.insert_object('bands', {id = 2, band_name = 'Scorpions', year = 1965})crud.insert_object('bands', {id = 3, band_name = 'Ace of Base', year = 1987})crud.insert_object('bands', {id = 4, band_name = 'The Beatles', year = 1960})

После этого просмотрите содержимое спейса с помощью операции crud.select():

 
crud.select('bands')

Вывод выглядит так:

 
---- metadata: [{'name': 'id', 'type': 'integer'}, {'name': 'bucket_id', 'type': 'unsigned'},    {'name': 'band_name', 'type': 'string'}, {'name': 'year', 'type': 'integer'}]  rows:  - [1, 12477, 'Roxette', 1986]  - [2, 21401, 'Scorpions', 1965]  - [3, 11804, 'Ace of Base', 1987]  - [4, 28161, 'The Beatles', 1960]- null...

Теперь прочитайте запись, у которой id = 1:

 
crud.get('bands', 1)---- rows:  - [1, 12477, 'Roxette', 1986]  metadata: [{'name': 'id', 'type': 'integer'}, {'name': 'bucket_id', 'type': 'unsigned'},    {'name': 'band_name', 'type': 'string'}, {'name': 'year', 'type': 'integer'}]- null...

Теперь обновите запись с id = 3, увеличив значение на единицу:

 
crud.update('bands', 3, {{'+', 'year', 1}})---- rows:  - [3, 11804, 'Ace of Base', 1988]  metadata: [{'name': 'id', 'type': 'integer'}, {'name': 'bucket_id', 'type': 'unsigned'},    {'name': 'band_name', 'type': 'string'}, {'name': 'year', 'type': 'integer'}]- null...

Удалите запись с id = 4:

 
crud.delete('bands', 4)---- rows:  - [4, 28161, 'The Beatles', 1960]  metadata: [{'name': 'id', 'type': 'integer'}, {'name': 'bucket_id', 'type': 'unsigned'},    {'name': 'band_name', 'type': 'string'}, {'name': 'year', 'type': 'integer'}]- null...

Просмотрите еще раз содержимое спейса bands:

 
crud.select('bands')---- metadata: [{'name': 'id', 'type': 'integer'}, {'name': 'bucket_id', 'type': 'unsigned'},    {'name': 'band_name', 'type': 'string'}, {'name': 'year', 'type': 'integer'}]  rows:  - [1, 12477, 'Roxette', 1986]  - [2, 21401, 'Scorpions', 1965]  - [3, 11804, 'Ace of Base', 1988]- null...

Здесь:

• значение year в кортеже с id = 3 увеличилось на 1;
• запись с id = 4 успешно удалена.

Есть несколько способов получить нужные кортежи через веб-интерфейс TCM:

• поиск кортежей по спейсу на вкладке Tuples на основе заданного условия;
• SELECT-запрос с помощью модуля CRUD.

В TCM во вкладке Tuples можно:

• просмотреть содержимое спейса на каждом узле кластера;
• найти все кортежи, которые удовлетворяют условию, заданному в виде выражения с оператором сравнения.

TCM поддерживает следующие операторы сравнения:

• == — равно;
• > — больше чем;
• < — меньше чем;
• >= — больше чем или равно;
• <= — меньше чем или равно.

Условие поиска имеет следующую структуру:

index_name comparator value

Здесь:

• index_name — левая часть выражения. Содержит название индекса;
• comparator — оператор сравнения (>, >=, ==, <=, <). Должен быть отделен пробелами от левой и правой частей выражения;
• value — правая часть выражения. Содержит строковое, численное или булево значение. Строковое значение при этом должно быть заключено в двойные кавычки ("").

Примеры

Пример поиска ниже возвращает кортежи с ID больше 1:

id > 1

В примере ниже поиск возвращает кортежи, в которых индекс band_name равен значению Roxette:

band_name == "Roxette"

В примере ниже задано множественное условие поиска. Поиск вернет все группы с с ID больше 2, созданные в 1980 году или раньше.

id > 2; year <= 1980; 

Модуль CRUD поддерживает запросы на выборку (SELECT) с множественными условиями, кластер при этом рассматривается как единый спейс. Условия могут содержать имена полей и имена индексов. Рекомендуемым первым условием является TREE-индекс, он позволяет уменьшить число сканируемых кортежей и не выполнять полное сканирование.

Запрос имеет следующую структуру:

 
crud.select(space_name, conditions, opts)

Здесь:

• space_name — название спейса. Тип: string;
• conditions — массив условий для выборки. Тип: table. Каждое условие — это таблица вида {operator, field-identifier, value}:
  • operator — оператор сравнения (>, >=, == или =, <=, <). Тип: string;
  • field-identifier — идентификатор поля. Тип: string. Это может быть имя поля или название индекса;
  • value — искомое значение;
• opts — дополнительные параметры. Поддерживаемые параметры:
  • first — максимальное количество возвращаемых элементов. Тип: number. Если указано отрицательное значение, возвращаются элементы, стоящие за значением опции after;
  • after — курсор пагинации на первый элемент. Тип: table;
  • batch_size — количество кортежей, которое будет обработано за один запрос к хранилищу. Тип: number;
  • bucket_id — идентификатор сегмента. Тип: number или cdata;
  • force_map_call — если задано значение true, вызор map выполняется без оптимизаций, даже если указано полное условие равенства первичного ключа. Тип: boolean;
  • timeout — время ожидания выполнения vshard.call в секундах. Тип: number. Если роутер не может определить шард с указанным bucket_id, он будет повторять попытку до истечения времени ожидания;
  • request_timeout — время ожидания в секундах, служит защитой от зависания реплик. Тип: number. Передавать параметры request_timeout и timeout нужно вместе с учетом следующего условия: timeout > request_timeout. Параметр request_timeout определяет, сколько времени может занять одна попытка запроса. По истечении этого времени (когда возникает ошибка TimedOut) роутер повторяет запрос на следующей реплике, если значение таймаута еще не истекло; Может быть задан только при mode = read. Значение по умолчанию совпадает со значением опции timeout, передаваемой пользователем;
  • fields — имена полей для получения подмножества полей. Тип: table;
  • fullscan — если задано значение true, критическая запись в журнале будет пропущена при потенциально длительном select. Тип: boolean;
  • mode — режим доступа. Тип: string. Поддерживаемые значения: read, write. Если задано значение write, запрос на выборку выполняется на мастер-узле. Значение по умолчанию: read;
  • prefer_replica — если задано значение true, предпочитаемой целью для выполнения запроса на выборку будет один из экземпляров реплики. Тип: boolean;
  • balance — если задано значение true, включена балансировка нагрузки. Тип: boolean;
  • vshard_router — имя узла роутера vshard. Тип: string или table;
  • yield_every — количество кортежей, обрабатываемых в хранилище для выполнения yield после завершения обработки. Тип: number. Значение опции должно быть больше 0. Значение по умолчанию: 1000;
  • fetch_latest_metadata — если задано значение true, опция гарантирует актуальность метаданных (формат спейса) в первом возвращаемом значении. Если указано значение false, опция может не учитывать последнюю миграцию формата данных. Тип: boolean. Значение по умолчанию: false.

Пример

Выполнить такой запрос можно в TCM на вкладке Stateboard. Для этого:

1. На вкладке Stateboard выберите набор реплик (в примере это router-msk).
2. Выберите узел роутера (router-msk) и в открывшемся окне перейдите на вкладку Terminal.
3. Во вкладке Terminal получите кортежи с помощью метода crud.select().

 
crud.select('bands', {{'>=', 'year', 1980}}, {first = 10})---- metadata: [{'name': 'id', 'type': 'integer'}, {'name': 'bucket_id', 'type': 'unsigned'},    {'name': 'band_name', 'type': 'string'}, {'name': 'year', 'type': 'integer'}]  rows:  - [1, 12477, 'Roxette', 1986]  - [3, 11804, 'Ace of Base', 1988]...

В примере возвращаются музыкальные группы, которые были образованы в 1980 году или позднее.

Также выполнить запрос crud.select() можно через утилиту tt CLI, пример подключения к роутеру приведен ранее в разделе Запросы к данным c помощью модуля CRUD.

Отказ — это любое событие, которое приводит к недоступности узла кластера. Примеры отказов: потеря связи с узлом, выход из строя оборудования с расположенным на нем узлом.

Этот пример можно выполнить на локально развёрнутом кластере с помощью Docker Compose;

Для имитации отказа вернитесь в локальный терминал и остановите узлы кластера с помощью команды docker compose stop:

 
cd cluster && docker compose stop tarantool-storage-1-mskcd cluster && docker compose stop tarantool-storage-2-spb

Оба узла отмечены в TCM серым цветом — эти экземпляры теперь недоступны. Чтобы открыть список ошибок, нажмите на любой из этих узлов и перейдите в раздел с ошибками. Наборы реплик отмечены красным, так как в них есть нерабочий узел кластера. Если в момент выключения узел был лидером набора реплик, будет выбран новый лидер. Задать это можно в опции конфигурации replication.failover:

 
replication:  failover: election

Чтобы проверить, что остановленные узлы не мешают работе кластера, во вкладке Terminal добавьте несколько новых записей:

 
crud.insert_object('bands', {id = 4, band_name = 'The Beatles', year = 1960})

Посмотрите повторно содержимое таблицы:

 
crud.select('bands')

Ответ выглядит так:

 
---- metadata: [{'name': 'id', 'type': 'integer'}, {'name': 'bucket_id', 'type': 'unsigned'},    {'name': 'band_name', 'type': 'string'}, {'name': 'year', 'type': 'integer'}]  rows:  - [1, 12477, 'Roxette', 1986]  - [2, 21401, 'Scorpions', 1965]  - [3, 11804, 'Ace of Base', 1988]  - [4, 28161, 'The Beatles', 1960]- null...

Остановить стенд можно так:

 
make stop