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

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

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

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

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

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

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

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

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

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

• утилита TT CLI;

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

Запустить кластер Tarantool DB можно с помощью следующей команды:

 
docker compose up -d --build

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

 
[+] Running 11/11 ⠿ Network up_with_docker_compose_tarantooldb_network          Created                                                                              0.1s ⠿ Container up_with_docker_compose-tarantool-storage-1-msk-1  Started                                                                              5.0s ⠿ Container up_with_docker_compose-tarantool-router-spb-1     Started                                                                              3.8s ⠿ Container up_with_docker_compose-tarantool-router-msk-1     Started                                                                              5.2s ⠿ Container up_with_docker_compose-etcd3-1                    Started                                                                              3.7s ⠿ Container up_with_docker_compose-tarantool-storage-1-spb-1  Started                                                                              4.9s ⠿ Container up_with_docker_compose-etcd1-1                    Started                                                                              4.4s ⠿ Container up_with_docker_compose-etcd2-1                    Started                                                                              5.3s ⠿ Container up_with_docker_compose-tarantool-storage-2-spb-1  Started                                                                              5.1s ⠿ Container up_with_docker_compose-tarantool-storage-2-msk-1  Started                                                                              5.1s ⠿ Container up_with_docker_compose-user-host-1                Started                                                                              6.4s

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

Создайте спейс, с которым вы будете работать в дальнейшем. Для этого:

1. Откройте в браузере веб-интерфейс любого из узлов Tarantool DB (http://localhost:8081).

2. Перейдите на вкладку Code.

3. На вкладке Code создайте папку migrations. Внутри папки migrations создайте папку source. Названия этих папок менять нельзя.

4. В папке source создайте файл с любым названием, например create_space_bands.lua. Добавьте в файл следующий код:

    
   local function up()    local utils = require('migrator.utils')    box.schema.space.create('bands', {if_not_exists = true})    box.space.bands:format({        { name = 'id', type = 'integer' },        { name = 'bucket_id', type = 'unsigned' },        { name = 'band_name', type = 'string' },        { name = 'year', type = 'integer' },    })    box.space.bands:create_index('primary_key', { parts = {'id'}, if_not_exists = true})    box.space.bands:create_index('bucket_id', { parts = {'bucket_id'}, unique = false, if_not_exists = true})    utils.register_sharding_key('bands', {'id'})          return trueendreturn {    up = up,}

5. Нажмите кнопку Apply.

6. Запустите миграции с помощью следующей команды:

    
   curl -X POST http://localhost:8081/migrations/up

   Здесь:

   • localhost:8081 — адрес экземпляра.

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

    
   {"applied":["create_space_bands.lua"]}

В результате на всех узлах кластера создан шардированный спейс bands. Содержимое спейса на каждом узле кластера можно просмотреть в веб-интерфейсе во вкладке Space Explorer.

Пример загрузки конфигурации и клиентского кода через API можно найти в разделе Запуск кластера через Docker compose.

Подключитесь к узлу кластера с помощью утилиты tt. Команда tt connect открывает интерактивную консоль Tarantool, позволяющую работать с базой данных:

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

Теперь добавьте в спейс 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;
• через утилиту tt.

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

 
docker compose stop tarantool-storage-1-mskdocker compose stop tarantool-storage-2-spb

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

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

2. Перейдите на вкладку Cluster и нажмите кнопку Failover: disabled в правом верхнем углу. Установите для параметров следующие значения:

   • Failover mode: Stateful;
   • Failover timeout: 5. Время ожидания failover (восстановления после сбоев) в 5 секунд позволит узлу master быстрее переключаться при отказе;
   • State provider: Tarantool (stateboard);
   • Password: passwd.

3. Нажмите кнопку Apply. Если параметры применены успешно, появится зеленое всплывающее уведомление. Кнопка Issues: 0 при этом должна стать неактивной. Если это не так, проверьте введенный пароль или попробуйте ввести пароль ещё раз.

Для имитации отказа остановите несколько узлов кластера с помощью команды tt stop, например хранилища storage-1-msk и storage-2-spb:

 
tt stop tarantooldb:storage-1-msktt stop tarantooldb:storage-2-spb

Теперь оба узла отмечены в веб-интерфейсе как UNREACHABLE (недоступен).

Для имитации отказа можно использовать и другой способ: найти PID этих процессов и выполнить команду kill.

Чтобы проверить, что остановленные узлы не мешают работе кластера, просмотрите ещё раз всё содержимое таблицы:

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

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

 
docker compose down