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

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

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

• установленный Docker-образ Tarantool DB;

• приложение 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
...

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

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

make stop