В этом уроке мы пройдём весь путь от пустой машины до работающего инстанса Tarantool: поставим бинарь, разберёмся с инструментом tt, создадим окружение и запустим первый узел. Цель - не вызубрить команды, а понять, как устроен инстанс и какой поток превращает YAML-файлы и каталоги в живой процесс. После урока структура tt-окружения и порядок установки/запуска должны стать для вас прозрачными.
Главная мысль: в Tarantool 3.x инструмент tt - это единая точка управления. Он умеет ставить сами бинари Tarantool, создавать окружение, запускать, останавливать, подключаться к консоли. Он пришёл на смену старым tarantoolctl и cartridge-cli и объединил их функции.
Механика: что такое инстанс и окружение
Инстанс - это один процесс tarantool, у которого есть: конфигурация (что и как он делает), сетевые порты (бинарный протокол iproto, обычно 3301), управляющий сокет (для консоли), pid-файл и каталог данных. В каталоге данных лежат снапшоты (.snap), журнал упреждающей записи WAL (.xlog), при движке vinyl - его файлы. Снапшот плюс хвост WAL после рестарта восстанавливают состояние базы в памяти - это и есть суть персистентности memtx.
Окружение tt (environment) - это изолированная рабочая папка с файлом tt.yaml в корне. Внутри находится каталог instances.enabled, и каждое приложение - это подкаталог внутри него. Окружение задаёт, где брать бинари, куда писать логи и данные, какие приложения включены. Изоляция означает, что в одной папке у вас одна версия Tarantool и свой набор приложений, в соседней - другая, и они не мешают друг другу.
Поток от файлов к процессу выглядит так. Вы кладёте в instances.enabled/myapp два файла. Первый - instances.yml - перечисляет имена инстансов приложения (просто список с двоеточиями). Второй - config.yaml - это декларативная конфигурация 3.x: топология, кредиты, спейсы, порты. Когда вы пишете tt start myapp, tt читает tt.yaml, находит приложение, по instances.yml понимает, сколько процессов поднять, и под каждое имя запускает tarantool, передавая ему общий config.yaml. Каждый инстанс берёт из конфига свою секцию по имени.
Двойной трек конфигурации. Декларативный config.yaml - это путь 3.x. В классических 1.x/2.x инстанс конфигурировался императивно: init-скрипт на Lua вызывал box.cfg{...} с параметрами (listen, memtx_memory, work_dir). Этот способ работает и в 3.x для одиночных скриптов, но для кластеров официальный путь теперь - YAML. Запомните различие: box.cfg - это код, который что-то делает при выполнении; config.yaml - это данные, которые движок применяет сам.
Раскладка каталогов. tt задаёт пути относительно папки приложения. По умолчанию: данные WAL и снапшоты идут в var/lib, логи в var/log, pid-файлы и управляющий сокет в var/run. Эти значения настраиваются в секции app файла tt.yaml (параметры wal_dir, memtx_dir, vinyl_dir, log_dir, run_dir). Понимание этой раскладки важно: если вы не видите данных после рестарта, первым делом смотрите, в тот ли каталог пишет инстанс.
Структура инстанса и поток установки/запуска через tt
Ключевые команды и код
Шаг 1. Поставить tt и Tarantool. На Linux ставится из пакетного репозитория, на macOS - через Homebrew:
Код: Выделить всё
# Debian/Ubuntu
curl -L https://tarantool.io/release/3/installer.sh | bash
sudo apt install -y tt tarantool
# RHEL/CentOS/Alma
curl -L https://tarantool.io/release/3/installer.sh | bash
sudo yum install -y tt tarantool
# macOS
brew install tarantool/tap/tt
Код: Выделить всё
tt install tarantool 3.3 # поставить конкретную версию
tt install tarantool latest # последнюю
tt search tarantool # посмотреть доступные
Код: Выделить всё
tt init # создаёт tt.yaml и каталоги (instances.enabled и пр.)
mkdir -p instances.enabled/myapp
Код: Выделить всё
instance001: {}
Код: Выделить всё
credentials:
users:
guest:
roles: [super]
iproto:
listen:
- uri: '127.0.0.1:3301'
groups:
group001:
replicasets:
replicaset001:
instances:
instance001: {}
Код: Выделить всё
tt start myapp # поднять процессы
tt status myapp # STATUS/PID/MODE/CONFIG/BOX
tt connect myapp:instance001 # интерактивная консоль
tt stop myapp # остановить
tt logs myapp # посмотреть логи
Код: Выделить всё
box.schema.space.create('bands')
box.space.bands:format({
{ name = 'id', type = 'unsigned' },
{ name = 'band_name', type = 'string' },
{ name = 'year', type = 'unsigned' },
})
box.space.bands:create_index('primary', { parts = { 'id' } })
box.space.bands:create_index('secondary', { parts = { 'band_name' } })
box.space.bands:insert{ 1, 'Roxette', 1986 }
box.space.bands:insert{ 2, 'Scorpions', 1965 }
box.space.bands:select{ 1 }
box.space.bands.index.secondary:select{ 'Scorpions' }
Код: Выделить всё
docker run --name tt1 -p 3301:3301 \
-v $(pwd):/opt/tarantool \
-d tarantool/tarantool:3
Код: Выделить всё
docker exec -it tt1 tt connect myapp:instance001
Самая частая ошибка новичков - запускать tt start не из корня окружения. tt ищет tt.yaml вверх по дереву каталогов; если вы ушли вглубь или, наоборот, запускаете из домашней папки, он либо не найдёт приложение, либо подхватит чужое окружение.
- instances.yml против config.yaml. Их путают. instances.yml - короткий список имён процессов для tt. config.yaml - вся конфигурация движка. Имя инстанса в instances.yml обязано совпадать с именем в секции instances конфига, иначе процесс поднимется, но не найдёт своих настроек.
- tt - это не сам Tarantool. Можно поставить tt и забыть поставить бинарь tarantool (или наоборот). tt status тогда жалуется на отсутствие исполняемого файла. Проверяйте: tarantool --version и tt version - это два разных бинаря.
- Данные исчезли после рестарта в Docker. Без монтирования тома каталог var/lib живёт внутри контейнера и удаляется вместе с ним. Снапшоты и WAL надо выносить на хост через -v.
- guest с правами super. В примерах гость получает роль super - это удобно для обучения, но в продакшене так делать нельзя: это анонимный полный доступ к базе.
- MODE: RW против RO. В tt status колонка MODE показывает, читающий узел или пишущий. На одиночном инстансе ждите RW; если видите RO без видимой причины - смотрите конфигурацию репликации.
- Старый tarantoolctl. В гайдах из интернета часто встречается tarantoolctl start - он устарел. Для 3.x используйте tt.
Поднимите одиночный инстанс по инструкции выше (tt init, два файла, tt start). Затем: подключитесь через tt connect, создайте спейс bands с тремя полями и первичным индексом, вставьте две записи. После этого выполните tt restart myapp и снова подключитесь. Проверьте через box.space.bands:select{}, что данные на месте. Найдите в файловой системе каталог var/lib вашего приложения и убедитесь, что там появились файлы .snap и .xlog - это и есть материальное доказательство персистентности.
Контрольные вопросы
- Чем отличается роль файла instances.yml от config.yaml, и что произойдёт, если имя инстанса в них не совпадёт?
- Какие файлы в каталоге данных отвечают за восстановление состояния базы после рестарта и как именно они дополняют друг друга?
- Почему tt start желательно вызывать из корня окружения, и как tt находит нужное приложение?
- В чём принципиальная разница между конфигурацией через box.cfg{} (трек 1.x/2.x) и через config.yaml (трек 3.x)?