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

Пререквизиты¶

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

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

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

• утилита tt CLI;

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

  Примечание

  Есть два способа получить исходные файлы примера:

  • Архив с полной документацией Tarantool DB, полученный по почте или скачанный в личном кабинете tarantool.io. Пример архива: tarantooldb-documentation-2.0.0.tar.gz. Пример up_with_docker_compose расположен в таком архиве в директории ./doc/examples/up_with_docker_compose/.

  • Отдельный архив up_with_docker_compose.tar.gz, скачанный c сайта Tarantool.

Запуск стенда¶

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

cd ./doc/examples/up_with_docker_compose/

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

make start

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

• кластера Tarantool DB:

  • 2 роутера;

  • 2 набора реплик по 3 хранилища;

  • 1 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 migrations
tt migrations up http://etcd1:2379/tdb --tarantool-cluster-username=admin --tarantool-cluster-password=secret-cluster-cookie

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

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

Запросы к данным c помощью модуля CRUD¶

Чтобы начать работу с базой данных через интерактивную консоль 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 успешно удалена.

Проверка работы кластера при отказах¶

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

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

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

replication:
  failover: election

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

Изменение конфигурации кластера¶

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

Перед изменением конфигурации кластера:

1. Приостановите любые DML-операции (insert, update, delete) во всех компонентах системы.

2. Выполните масштабирование или инициируйте ребалансировку.

3. Дождитесь полного завершения процесса миграции бакетов.

4. На всех роутерах выполните сброс маршрутов:

   vshard.router._route_map_clear()
   

5. Возобновите выполнение DML-операций.

После этого вы можете выполнить изменение конфигурации кластера.

Остановка стенда¶

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

make stop