Руководство для разработчика
To develop an application, use the Tarantool Cartridge framework that is installed as part of Tarantool Enterprise Edition.
Ниже приведен список необходимых команд:
Создайте приложение с поддержкой кластеров из шаблона:
$ tt create cartridge --name <app_name> -d /path/to
Разработайте приложение:
$ cd /path/to/<app_name> $ ...
Упакуйте приложение:
$ tt pack [rpm|tgz] /path/to/<app_name>
Разверните приложение:
Для пакета
rpm
:Загрузите пакет на все серверы, выделенные для Tarantool.
Установите пакет:
$ yum install <app_name>-<version>.rpm
Запустите приложение.
$ systemctl start <app_name>
Для архива
tgz
:Загрузите архив на все серверы, выделенные для Tarantool.
Распакуйте архив:
$ tar -xzvf <app_name>-<version>.tar.gz -C /home/<user>/apps
Запустите приложение
$ tarantool init.lua
Более подробную информацию с примерами см. на следующих страницах:
- руководство для начинающих, в котором пошагово разбирается разработка и развертывание простого кластерного приложения с помощью Tarantool Cartridge,
- a detailed manual on creating and managing clustered Tarantool applications using Tarantool Cartridge.
Кроме того, в этом руководстве особое внимание уделяется функциям разработчика, специфичным для Enterprise-версии, которые доступны в дополнение к Tarantool Community Edition в среде Tarantool Cartridge:
- авторизация с использованием LDAP в веб-интерфейсе,
- независимые от среды приложения,
- примеры приложений, которые подходят для Enterprise-версии.
If you run an LDAP server in your organization, you can connect Tarantool
Enterprise to it and let it handle the authorization. In this case, follow the
general recipe
where in the first step add the ldap
module to the .rockspec
file
as a dependency and consider implementing the check_password
function
the following way:
-- auth.lua
-- Require the LDAP module at the start of the file
local ldap = require('ldap')
...
-- Add a function to check the credentials
local function check_password(username, password)
-- Configure the necessary LDAP parameters
local user = string.format("cn=%s,ou=tarantool,dc=glauth,dc=com", username)
-- Connect to the LDAP server
local ld, err = ldap.open("localhost:3893", user, password)
-- Return an authentication success or failure
if not ld then
return false
end
return true
end
...
Tarantool Enterprise позволяет создавать независимые от среды приложения.
Независимое от среды приложение представляет собой сборку следующих компонентов (в одной директории):
- файлы с кодом на Lua,
- исполняемый файл
tarantool
, - подключенные внешние модули (при необходимости).
Запущенное с помощью исполняемого файла tarantool приложение обеспечивает работу сервиса.
Модули – это сторонние библиотеки на Lua, установленные в виртуальную среду (в директории приложения), которая аналогична virtualenv
в Python и bundler в Ruby.
Структура такого приложения остается неизменной как на стадии разработки, так и на стадии производственной эксплуатации. Весь связанный с приложением код находится в одном месте, готов к упаковке и копированию на любой сервер.
После определения пользовательских кластерных ролей и разработки приложения упакуйте его со всеми зависимостями (бинарные файлы модулей) и с исполняемым файлом tarantool
.
Это позволит вам легко загружать, устанавливать и запускать приложение на любом сервере.
Чтобы упаковать приложение, выполните команду:
$ tt pack [rpm|tgz] /path/to/<app_name>
где укажите путь к вашей среде разработки (репозиторию Git, который содержит код приложения), а также один из параметров сборки:
rpm
для сборки RPM-пакета (рекомендуется), илиtgz
для сборки архиваtar + gz
(выберите этот параметр, только если у вас нет прав уровня root на серверах, выделенных для Tarantool Enterprise).
В результате будет создан пакет (или сжатый архив) с именем <имя_приложения>-<версия_тег>-<количество_коммитов>
(например, myapp-1.2.1-12.rpm
), который будет хранить ваше приложение в не зависимом от среды виде.
Далее переходите к развертыванию пакетных (или же архивированных) приложений на серверах.
Чтобы развернуть пакетное приложение, выполните следующие действия на каждом сервере, выделенном для Tarantool Enterprise:
Загрузите локально пакет, созданный на предыдущем шаге.
Установите приложение:
$ yum install <app_name>-<version>.rpm
Запустите один или несколько экземпляров Tarantool с соответствующими сервисами, как описано ниже.
Отдельный экземпляр:
$ systemctl start <app_name>
Это запустит экземпляр сервиса
systemd
с прослушиванием по порту3301
.Несколько экземпляров на одном или нескольких серверах:
$ systemctl start <app_name>@instance_1 $ systemctl start <app_name>@instance_2 ... $ systemctl start <app_name>@instance_<number>
где
<app_name>@instance_<number>
(<имя_приложения>@экземпляр_<число>) – это имя экземпляра сервисаsystemd
с инкрементным числом<number>
(уникальным для каждого экземпляра), которое следует добавить к порту3300
для настройки прослушивания (например,3301
,3302
и т.д.).
In case it is a cluster-aware application, proceed to deploying the cluster.
Чтобы остановить все сервисы на сервере, используйте команду systemctl stop
и укажите имена экземпляров по одному. Например:
$ systemctl stop <app_name>@instance_1 <app_name>@instance_2 ... <app_name>@instance_<N>
Тогда как пакет RPM по умолчанию помещает ваше приложение в /usr/share/tarantool/<имя_приложения>
на вашем сервере, архив tar + gz
не создает какую-либо структуру, помимо директории <имя_приложения>/
, поэтому вы сами несете ответственность за правильность размещения приложения.
Примечание
Для развертывания рекомендуется использовать RPM-пакеты. Развертывайте архивы, только если у вас нет прав уровня root.
Чтобы разместить и развернуть приложение, выполните следующие действия на каждом сервере, выделенном для Tarantool Enterprise:
Загрузите архив, распакуйте его и извлеките содержимое в директорию
/home/<user>/apps
:$ tar -xzvf <app_name>-<version>.tar.gz -C /home/<user>/apps
Запустите экземпляры Tarantool с соответствующими сервисами.
Для управления и конфигурации экземпляров используйте такие средства, как
ansible
,systemd
иsupervisord
.In case it is a cluster-aware application, proceed to deploying the cluster.
Все экземпляры в кластере должны использовать один и тот же код. Это относится ко всем компонентам: пользовательским ролям, приложениям, бинарным файлам модулей, исполняемым файлам tarantool
и tt
(при необходимости).
Обратите внимание на возможную обратную совместимость, которую может принести с собой любой компонент. Это поможет вам выбрать сценарий для обновления в эксплуатационной среде. Имейте в виду, что вы несете ответственность за совместимость кода и обработку конфликтов в случае возникновения несоответствий.
Чтобы обновить любой из компонентов, подготовьте новую версию пакета (архива):
- Обновите необходимые файлы в вашей среде разработки (директории):
- Ваш собственный исходный код: пользовательские роли и / или приложения.
- Бинарные файлы модулей.
- Исполняемые файлы. Замените их на файлы из нового комплекта.
- Increment the version as described in application versioning.
- Повторно упакуйте обновленные файлы, как описано в разделе по упаковке приложений.
- Выберите сценарий обновления, как описано в разделе по обновлению в эксплуатационной среде.
Дистрибутив Enterprise включает в себя примеры приложений в директории examples/
, которые демонстрируют основные функциональные возможности Tarantool.
Примеры приложений:
Приложение кэширования со сквозной записью в PostgreSQL
Пример в pg_writethrough_cache/
показывает, как Tarantool может кэшировать данные, записанные через него в базу данных PostgreSQL для ускорения запросов на чтение.
Для примера приложения требуется развернутая база данных PostgreSQL и следующие модули сторонних библиотек:
$ tt rocks install http
$ tt rocks install pg
$ tt rocks install argparse
Просмотрите код в файлах, чтобы понять, что может делать приложение.
Чтобы запустить приложение для локальной базы данных PostgreSQL, выполните команду:
$ tarantool cachesrv.lua --binary-port 3333 --http-port 8888 --database postgresql://localhost/postgres
Приложение кэширования с отложенной записью в Oracle
Пример в ora-writebehind-cache/
показывает, как Tarantool может кэшировать записи и помещать их в базу данных Oracle для ускорения как записи, так и чтения.
Для примера приложения необходимы:
развернутая база данных Oracle;
инструменты Oracle: Instant Client and SQL Plus, оба версии 12.2;
Примечание
Если Oracle Instant Client выдает ошибки в файлах с расширением .so
(динамические библиотеки Oracle), поместите их в какую-либо директорию и добавьте ее в переменную окружения LD_LIBRARY_PATH
.
Например: export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$PWD/<путь_к_файлам_so>
модули сторонних библиотек, перечисленные в файле rockspec
.
Чтобы установить модули, выполните следующую команду в директории examples/ora_writebehind_cache
:
$ tt rocks make oracle_rb_cache-0.1.0-1.rockspec
Если у вас нет развернутого экземпляра Oracle под рукой, запустите пустой объект в контейнере Docker:
В браузере войдите в Реестр контейнеров Oracle, выберите Database (База данных) и примите «Корпоративные условия и ограничения Oracle».
В директории ora-writebehind-cache/
войдите в репозиторий под учетной записью Oracle, получите данные и запустите образ с помощью подготовленных скриптов
$ docker login container-registry.oracle.com
Login:
Password:
Login Succeeded
$ docker pull container-registry.oracle.com/database/enterprise:12.2.0.1
$ docker run -itd \
-p 1521:1521 \
-p 5500:5500 \
--name oracle \
-v "$(pwd)"/setupdb/configDB.sh:/home/oracle/setup/configDB.sh \
-v "$(pwd)"/setupdb/runUserScripts.sh:/home/oracle/setup/runUserScripts.sh \
-v "$(pwd)"/startupdb:/opt/oracle/scripts/startup \
container-registry.oracle.com/database/enterprise:12.2.0.1
Когда всё будет готово, запустите пример приложения.
Чтобы запустить приложение, выполните следующую команду в директории examples/ora_writebehind_cache
:
$ tarantool init.lua
Данное приложение поддерживает следующие запросы:
Получение данных: GET http://<host>:<http_port>/account/id
;
Добавление: POST http://<host>:<http_port>/account/
со следующими данными:
{"clng_clng_id":1,"asut_asut_id":2,"creation_data":"01-JAN-19","navi_user":"userName"}
Обновление: POST http://<host>:<http_port>/account/id
с теми же данными, что и в запросе на добавление;
Удаление: DELETE http://<host>:<http_port>/account/id
,где id
– это идентификатор учетной записи.
Взгляните на примеры скриптов CURL в директории examples/ora_writebehind_cache/testing
и просмотрите файл README.md
для получения дополнительной информации об их использовании.
Пример в pg_writethrough_cache/
показывает, как Tarantool может кэшировать данные, записанные через него в базу данных PostgreSQL для ускорения запросов на чтение.
Для примера приложения требуется развернутая база данных PostgreSQL и следующие модули сторонних библиотек:
$ tt rocks install http
$ tt rocks install pg
$ tt rocks install argparse
Просмотрите код в файлах, чтобы понять, что может делать приложение.
Чтобы запустить приложение для локальной базы данных PostgreSQL, выполните команду:
$ tarantool cachesrv.lua --binary-port 3333 --http-port 8888 --database postgresql://localhost/postgres
Приложение кэширования с отложенной записью в Oracle
Пример в ora-writebehind-cache/
показывает, как Tarantool может кэшировать записи и помещать их в базу данных Oracle для ускорения как записи, так и чтения.
Для примера приложения необходимы:
развернутая база данных Oracle;
инструменты Oracle: Instant Client and SQL Plus, оба версии 12.2;
Примечание
Если Oracle Instant Client выдает ошибки в файлах с расширением .so
(динамические библиотеки Oracle), поместите их в какую-либо директорию и добавьте ее в переменную окружения LD_LIBRARY_PATH
.
Например: export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$PWD/<путь_к_файлам_so>
модули сторонних библиотек, перечисленные в файле rockspec
.
Чтобы установить модули, выполните следующую команду в директории examples/ora_writebehind_cache
:
$ tt rocks make oracle_rb_cache-0.1.0-1.rockspec
Если у вас нет развернутого экземпляра Oracle под рукой, запустите пустой объект в контейнере Docker:
В браузере войдите в Реестр контейнеров Oracle, выберите Database (База данных) и примите «Корпоративные условия и ограничения Oracle».
В директории ora-writebehind-cache/
войдите в репозиторий под учетной записью Oracle, получите данные и запустите образ с помощью подготовленных скриптов
$ docker login container-registry.oracle.com
Login:
Password:
Login Succeeded
$ docker pull container-registry.oracle.com/database/enterprise:12.2.0.1
$ docker run -itd \
-p 1521:1521 \
-p 5500:5500 \
--name oracle \
-v "$(pwd)"/setupdb/configDB.sh:/home/oracle/setup/configDB.sh \
-v "$(pwd)"/setupdb/runUserScripts.sh:/home/oracle/setup/runUserScripts.sh \
-v "$(pwd)"/startupdb:/opt/oracle/scripts/startup \
container-registry.oracle.com/database/enterprise:12.2.0.1
Когда всё будет готово, запустите пример приложения.
Чтобы запустить приложение, выполните следующую команду в директории examples/ora_writebehind_cache
:
$ tarantool init.lua
Данное приложение поддерживает следующие запросы:
Получение данных: GET http://<host>:<http_port>/account/id
;
Добавление: POST http://<host>:<http_port>/account/
со следующими данными:
{"clng_clng_id":1,"asut_asut_id":2,"creation_data":"01-JAN-19","navi_user":"userName"}
Обновление: POST http://<host>:<http_port>/account/id
с теми же данными, что и в запросе на добавление;
Удаление: DELETE http://<host>:<http_port>/account/id
,где id
– это идентификатор учетной записи.
Взгляните на примеры скриптов CURL в директории examples/ora_writebehind_cache/testing
и просмотрите файл README.md
для получения дополнительной информации об их использовании.
Пример в ora-writebehind-cache/
показывает, как Tarantool может кэшировать записи и помещать их в базу данных Oracle для ускорения как записи, так и чтения.
Для примера приложения необходимы:
развернутая база данных Oracle;
инструменты Oracle: Instant Client and SQL Plus, оба версии 12.2;
Примечание
Если Oracle Instant Client выдает ошибки в файлах с расширением
.so
(динамические библиотеки Oracle), поместите их в какую-либо директорию и добавьте ее в переменную окруженияLD_LIBRARY_PATH
.Например:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$PWD/<путь_к_файлам_so>
модули сторонних библиотек, перечисленные в файле
rockspec
.
Чтобы установить модули, выполните следующую команду в директории examples/ora_writebehind_cache
:
$ tt rocks make oracle_rb_cache-0.1.0-1.rockspec
Если у вас нет развернутого экземпляра Oracle под рукой, запустите пустой объект в контейнере Docker:
В браузере войдите в Реестр контейнеров Oracle, выберите Database (База данных) и примите «Корпоративные условия и ограничения Oracle».
В директории
ora-writebehind-cache/
войдите в репозиторий под учетной записью Oracle, получите данные и запустите образ с помощью подготовленных скриптов$ docker login container-registry.oracle.com Login: Password: Login Succeeded $ docker pull container-registry.oracle.com/database/enterprise:12.2.0.1 $ docker run -itd \ -p 1521:1521 \ -p 5500:5500 \ --name oracle \ -v "$(pwd)"/setupdb/configDB.sh:/home/oracle/setup/configDB.sh \ -v "$(pwd)"/setupdb/runUserScripts.sh:/home/oracle/setup/runUserScripts.sh \ -v "$(pwd)"/startupdb:/opt/oracle/scripts/startup \ container-registry.oracle.com/database/enterprise:12.2.0.1
Когда всё будет готово, запустите пример приложения.
Чтобы запустить приложение, выполните следующую команду в директории examples/ora_writebehind_cache
:
$ tarantool init.lua
Данное приложение поддерживает следующие запросы:
Получение данных:
GET http://<host>:<http_port>/account/id
;Добавление:
POST http://<host>:<http_port>/account/
со следующими данными:{"clng_clng_id":1,"asut_asut_id":2,"creation_data":"01-JAN-19","navi_user":"userName"}
Обновление:
POST http://<host>:<http_port>/account/id
с теми же данными, что и в запросе на добавление;Удаление:
DELETE http://<host>:<http_port>/account/id
,гдеid
– это идентификатор учетной записи.
Взгляните на примеры скриптов CURL в директории examples/ora_writebehind_cache/testing
и просмотрите файл README.md
для получения дополнительной информации об их использовании.