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

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

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

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

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

• утилита TT CLI;

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

  Примечание

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

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

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

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

Запустить кластер 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 true
   end
   
   return {
       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.

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

Подключитесь к узлу кластера с помощью утилиты 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 tarantool-storage-1-msk
docker compose stop tarantool-storage-2-spb

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

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