Версия:

Модули СУБД SQL

Модули СУБД SQL

В данном разделе справочника рассматривается внедрение и использование двух уже созданных модулей: сторонние библиотеки СУБД SQL для MySQL и PostgreSQL.

Для вызова другой СУБД из Tarantool’а нужно: другая СУБД и Tarantool. Модуль, который соединяет другую СУБД может называться коннектором. В модуле есть библиотека общего пользования, которая может называться драйвером.

Tarantool предоставляет модули-коннекторы для СУБД вместе с менеджером модулей для Lua под названием LuaRocks.

Модули Tarantool’а позволяют подключаться к SQL-серверам и выполнять SQL-запросы так же, как это делает клиент MySQL или PostgreSQL. Операторы SQL доступны как Lua-методы. Таким образом, Tarantool может служить Lua-коннектором для MySQL или Lua-коннектором для PostgreSQL, что было бы полезно, даже если бы Tarantool больше ничего не умел. Но конечно же, Tarantool также представляет собой СУБД, поэтому модуль используется для любых операций, таких как копирование и ускорение базы данных, которые максимально эффективно, если приложение может работать как с SQL, так и с Tarantool в пределах одной Lua-процедуры. Методы подключения / выборки / вставки / и т.д. аналогичны методам модуля net.box.

С точки зрения пользователя, модули для MySQL и PostgreSQL очень похожи, поэтому следующие разделы – «Пример для MySQL» и «Пример для PostgreSQL» – слегка избыточны.

Пример для MySQL

В данном примере предполагается, что установлены MySQL 5.5, MySQL 5.6 или MySQL 5.7. Последние версии MariaDB также подойдут, используется коннектор к MariaDB для C. Самым важным пакетом будет пакет для разработчиков клиента MySQL, который обычно называется libmysqlclient-dev. Наиболее важным файлом из этого пакета будет файл libmysqlclient.so или с похожим названием. Можно использовать `` find`` или `` whereis``, чтобы узнать, в каких директориях установлены эти файлы.

Также нужно будет установить библиотеку общего пользования Tarantool’а с драйвером для MySQL, загрузить ее и использовать для подключения к экземпляру MySQL-сервера. После этого можно передавать любой оператор MySQL на экземпляр сервера и получать результаты, включая наборы результатов.

Установка

Проверьте инструкции по загрузке и установке бинарного пакета, которые применимы к среде, где установлен Tarantool. Помимо установки tarantool, установите tarantool-dev. Например, в Ubuntu добавьте строку:

$ sudo apt-get install tarantool-dev

Что касается библиотеки общего пользования с драйвером для MySQL, ее можно установить двумя способами:

Из LuaRocks

Начните с установки luarocks. Убедитесь, что tarantool указан в серверах, как описано на странице сторонних модулей Tarantool’а rocks.tarantool.org. Затем выполните:

luarocks install mysql [MYSQL_LIBDIR = *path*]
                        [MYSQL_INCDIR = *path*]
                        [--local]

Например:

$ luarocks install mysql MYSQL_LIBDIR=/usr/local/mysql/lib

Из GitHub

Перейдите по ссылке github.com/tarantool/mysql. Следуя инструкциям, введите команду:

$ git clone https://github.com/tarantool/mysql.git
 $ cd mysql && cmake . -DCMAKE_BUILD_TYPE=RelWithDebInfo
 $ make
 $ make install

На данном этапе желательно проверить, что после установки появился файл под названием driver.so, а также проверить, что этот файл находится в директории, которую можно найти по запросу require.

Подключение

Начните с выполнения запроса require для драйвера mysql. В дальнейших примерах у него будет имя mysql.

mysql = require('mysql')

Теперь выполните:

*имя_подключения* = mysql.connect(*параметры подключения*)

Параметры подключения включены в таблицу. Доступные параметры:

  • host = имя-хоста – строка, значение по умолчанию = „localhost“
  • port = номер-порта – число, значение по умолчанию = 3306
  • user = имя-пользователя – строка, значение по умолчанию – имя пользователя в операционной системе
  • password = пароль – строка, по умолчанию пустая
  • db = имя-базы-данных – строка, по умолчанию пустая
  • raise = true|false – логическое значение, по умолчанию, false (ложь)

Имена параметров, за исключением raise, похожи на имена, которые используются в MySQL-клиенте mysql, для получения подробной информации см. руководство по MySQL по ссылке dev.mysql.com/doc/refman/5.6/en/connecting.html. Значение параметра raise следует указать как true, если ошибки должны возникать при обнаружении. Чтобы подключиться по Unix-сокету, а не по TCP, укажите host = 'unix/' и port = имя-сокета.

Пример с использованием таблицы, заключенной в {фигурные скобки}:

conn = mysql.connect({
     host = '127.0.0.1',
     port = 3306,
     user = 'p',
     password = 'p',
     db = 'test',
     raise = true
 })
 -- ИЛИ
 conn = mysql.connect({
     host = 'unix/',
     port = '/var/run/mysqld/mysqld.sock'
 })

Пример с созданием функции, которая определяет параметры в отдельных строках:

tarantool> -- Функция подключения. Использование: conn = mysql_connect()
 tarantool> function mysql_connection()
          >   local p = {}
          >   p.host = 'widgets.com'
          >   p.db = 'test'
          >   conn = mysql.connect(p)
          >   return conn
          > end
 ---
 ...
 tarantool> conn = mysql_connect()
 ---
 ...

Предполагаем, что в дальнейших примерах будет использоваться имя „conn“.

Как проверить связь

Чтобы убедиться, что подключение работает, следует использовать запрос:

*имя-соединение*:ping()

Пример:

tarantool> conn:ping()
 ---
 - true
 ...

Исполнение оператора

Для всех операторов MySQL запрос будет:

*имя-соединения*:execute(*sql-оператор* [, *параметры*])

где sql-statement – это строка, а необязательные параметры – это дополнительные значения, которыми можно заменить любые знаки вопроса («?») в SQL-операторе.

Пример:

tarantool> conn:execute('select table_name from information_schema.tables')
 ---
 - - table_name: ALL_PLUGINS
   - table_name: APPLICABLE_ROLES
   - table_name: CHARACTER_SETS
   <...>
 - 78
 ...

Закрытие соединения

Чтобы закрыть сессию, которую открыли с помощью mysql.connect, используется следующий запрос:

*имя-соединения*:close()

Пример:

tarantool> conn:close()
 ---
 ...

Для получения дополнительной информации, включая примеры редко используемых запросов, см. файл README.md по ссылке github.com/tarantool/mysql.

Пример

Пример выполняется на машине с ОС Ubuntu 12.04 (Precise Pangolin), где Tarantool установлен в поддиректорию /usr, а копия MySQL установлена в ~/mysql-5.5. Экземпляр сервера mysqld уже запущен на localhost 127.0.0.1.

$ export TMDIR=~/mysql-5.5
 $ # Проверьте, что создана поддиректория include, путем поиска
 $ # .../include/mysql.h. (Если нет, то можно проверить
 $ # .../include/mysql/mysql.h.)
 $ [ -f $TMDIR/include/mysql.h ] && echo "OK" || echo "Error"
 OK

 $ # Проверьте, что создана поддиректория library, а в ней
 $ # необходимый файл .so.
 $ [ -f $TMDIR/lib/libmysqlclient.so ] && echo "OK" || echo "Error"
 OK

 $ # Проверьте, что mysql-клиент может подключиться, с помощью настроек
 $ # по умолчанию: порт = 3306, пользователь = 'root', пароль пользователя = '',
 $ # база данных = 'test'. Эти настройки можно изменить, используя
 $ # измененные значения.
 $ $TMDIR/bin/mysql --port=3306 -h 127.0.0.1 --user=root \
     --password= --database=test
 Welcome to the MySQL monitor.  Commands end with ; or \g.
 Your MySQL connection id is 25
 Server version: 5.5.35 MySQL Community Server (GPL)
 ...
 Type 'help;' or '\h' for help. Type '\c' to clear ...

 $ # Вставьте строку в базу данных test и завершите работу.
 mysql> CREATE TABLE IF NOT EXISTS test (s1 INT, s2 VARCHAR(50));
 Query OK, 0 rows affected (0.13 sec)
 mysql> INSERT INTO test.test VALUES (1,'MySQL row');
 Query OK, 1 row affected (0.02 sec)
 mysql> QUIT
 Bye

 $ # Установите luarocks
 $ sudo apt-get -y install luarocks | grep -E "Setting up|already"
 Setting up luarocks (2.0.8-2) ...

 $ # Настройте список сторонних модулей Tarantool'а в ~/.luarocks,
 $ # следуя инструкциям по ссылке rocks.tarantool.org
 $ mkdir ~/.luarocks
 $ echo "rocks_servers = {[[http://rocks.tarantool.org/]]}" >> \
     ~/.luarocks/config.lua

 $ # Убедитесь, что при следующей установке будут использованы файлы из главного
 $ # хранилища Tarantool'а. Получаем результат, нормальный для Ubuntu
 $ # 12.04 Precise Pangolin
 $ cat /etc/apt/sources.list.d/tarantool.list
 deb http://tarantool.org/dist/1.7/ubuntu/ precise main
 deb-src http://tarantool.org/dist/1.7/ubuntu/ precise main

 $ # Установите tarantool-dev. Строка на экране должна показать версию 1.6
 $ sudo apt-get -y install tarantool-dev | grep -E "Setting up|already"
 Setting up tarantool-dev (1.6.6.222.g48b98bb~precise-1) ...
 $

 $ # Используйте luarocks для локальной установки, то есть в $HOME
 $ luarocks install mysql MYSQL_LIBDIR=/usr/local/mysql/lib --local
 Installing http://rocks.tarantool.org/mysql-scm-1.rockspec...
 ... (здесь будет еще информация о сборке драйвера Tarantool/MySQL)
 mysql scm-1 is now built and installed in ~/.luarocks/

 $ # Убедитесь, что driver.so создан в месте,
 $ # где Tarantool будет искать его
 $ find ~/.luarocks -name "driver.so"
 ~/.luarocks/lib/lua/5.1/mysql/driver.so

 $ # Измените директорию на директорию, которую можно использовать для
 $ # временного тестирования. В данном примере предполагаем, что имя
 $ # этой директории будет /home/pgulutzan/tarantool_sandbox.
 $ # (Измените "/home/pgulutzan" на фактическую корневую директорию
 $ # пользователя машины, используемой для тестирования.)
 $ cd /home/pgulutzan/tarantool_sandbox

 $ # Запустите экземпляр Tarantool-сервера. Не используйте файл инициализации Lua.

 $ tarantool
 tarantool: version 1.7.0-222-g48b98bb
 type 'help' for interactive help
 tarantool>

Настройте Tarantool и загрузите модуль mysql. Убедитесь, что Tarantool не выбрасывает ошибку в ответ на вызов «require()».

tarantool> box.cfg{}
 ...
 tarantool> mysql = require('mysql')
 ---
 ...

Создайте Lua-функцию, которая подключится к экземпляру MySQL-сервера (используя значения по умолчанию для параметров порта, пользователя и пароля), выберите одну строку и выведите ее на экран. Описание используемых здесь типов операторов вы можете найти в практикуме по Lua в руководстве пользователя Tarantool’а.

tarantool> function mysql_select ()
          >   local conn = mysql.connect({
          >     host = '127.0.0.1',
          >     port = 3306,
          >     user = 'root',
          >     db = 'test'
          >   })
          >   local test = conn:execute('SELECT * FROM test WHERE s1 = 1')
          >   local row = ''
          >   for i, card in pairs(test) do
          >       row = row .. card.s2 .. ' '
          >       end
          >   conn:close()
          >   return row
          > end
 ---
 ...
 tarantool> mysql_select()
 ---
 - 'MySQL row '
 ...

Просмотрите результат. В нем есть строка «MySQL row». Это и есть строка, которая была вставлена в базу данных MySQL. А сейчас она выделена с помощью Tarantool-клиента.

Пример для PostgreSQL

В данном примере предполагается, что установлены PostgreSQL 8 или PostgreSQL 9. Более поздние версии также должны сработать. Самым важным пакетом будет пакет для разработчиков клиента PostgreSQL, который обычно называется libpq-dev. На Ubuntu его можно установить следующим образом:

$ sudo apt-get install libpq-dev

Однако, не все платформы одинаковы, поэтому в данном примере предполагается, что пользователь должен проверить наличие нужных PostgreSQL-файлов, а также явным образом прописать, где они находятся, для сборки драйвера Tarantool/PostgreSQL. Для поиска директорий, где установлены PostgreSQL-файлы, можно воспользоваться командами find или whereis.

Также нужно будет установить библиотеку общего пользования Tarantool’а с драйвером для PostgreSQL, загрузить ее и использовать для подключения к экземпляру PostgreSQL-сервера. После этого можно передавать любой оператор PostgreSQL на экземпляр сервера и получать результаты.

Установка

Проверьте инструкции по загрузке и установке бинарного пакета, которые применимы к среде, где установлен Tarantool. Помимо установки tarantool, установите tarantool-dev. Например, в Ubuntu добавьте строку:

$ sudo apt-get install tarantool-dev

Что касается библиотеки общего пользования с драйвером для PostgreSQL, ее можно установить двумя способами:

Из LuaRocks

Начните с установки luarocks. Убедитесь, что tarantool указан в серверах, как описано на странице сторонних модулей Tarantool’а rocks.tarantool.org. Затем выполните:

luarocks install pg [POSTGRESQL_LIBDIR = *path*]
                     [POSTGRESQL_INCDIR = *path*]
                     [--local]

Например:

$ luarocks install pg POSTGRESQL_LIBDIR=/usr/local/postgresql/lib

Из GitHub

Перейдите по ссылке github.com/tarantool/pg. Следуя инструкциям, введите команду:

$ git clone https://github.com/tarantool/pg.git
 $ cd pg && cmake . -DCMAKE_BUILD_TYPE=RelWithDebInfo
 $ make
 $ make install

На данном этапе желательно проверить, что после установки появился файл под названием driver.so, а также проверить, что этот файл находится в директории, которую можно найти по запросу require.

Подключение

Начните с выполнения запроса require для драйвера pg. В дальнейших примерах у него будет имя pg.

pg = require('pg')

Теперь выполните:

*имя_подключения* = pg.connect(*параметры подключения*)

Параметры подключения включены в таблицу. Доступные параметры:

  • host = имя-хоста – строка, значение по умолчанию = „localhost“
  • port = номер-порта – число, значение по умолчанию = 5432
  • user = имя-пользователя – строка, значение по умолчанию – имя пользователя в операционной системе
  • pass = пароль или password = пароль – строка, по умолчанию пустая
  • db = имя-базы-данных – строка, по умолчанию пустая

Имена параметров похожи на имена, которые используются в PostgreSQL.

Пример с использованием таблицы, заключенной в {фигурные скобки}:

conn = pg.connect({
     host = '127.0.0.1',
     port = 5432,
     user = 'p',
     password = 'p',
     db = 'test'
 })

Пример с созданием функции, которая определяет параметры в отдельных строках:

tarantool> function pg_connect()
          >   local p = {}
          >   p.host = 'widgets.com'
          >   p.db = 'test'
          >   p.user = 'postgres'
          >   p.password = 'postgres'
          >   local conn = pg.connect(p)
          >   return conn
          > end
 ---
 ...
 tarantool> conn = pg_connect()
 ---
 ...

Предполагаем, что в дальнейших примерах будет использоваться имя „conn“.

Как проверить связь

Чтобы убедиться, что подключение работает, следует использовать запрос:

*имя-соединение*:ping()

Пример:

tarantool> conn:ping()
 ---
 - true
 ...

Исполнение оператора

Для всех операторов PostgreSQL запрос будет:

*имя-соединения*:execute(*sql-оператор* [, *параметры*])

где sql-statement – это строка, а необязательные параметры – это дополнительные значения, которыми можно заменить любые знаки вопроса («?») в SQL-операторе.

Пример:

tarantool> conn:execute('select tablename from pg_tables')
 ---
 - - tablename: pg_statistic
   - tablename: pg_type
   - tablename: pg_authid
   <...>
 ...

Закрытие соединения

Чтобы закрыть сессию, которую открыли с помощью pg.connect, используется следующий запрос:

*имя-соединения*:close()

Пример:

tarantool> conn:close()
 ---
 ...

Для получения дополнительной информации, включая примеры редко используемых запросов, см. файл README.md по ссылке github.com/tarantool/pg.

Пример

Пример выполняется на машине с ОС Ubuntu 12.04 (Precise Pangolin), где Tarantool установлен в поддиректорию /usr, а копия PostgreSQL установлена в /usr. Экземпляр сервера PostgreSQL уже запущен на localhost 127.0.0.1.

$ # Проверьте, что создана поддиректория include, путем поиска
 $ # /usr/include/postgresql/libpq-fe-h.
 $ [ -f /usr/include/postgresql/libpq-fe.h ] && echo "OK" || echo "Error"
 OK

 $ # Проверьте, что создана поддиректория library, а в ней необходимый файл .so.
 $ [ -f /usr/lib/x86_64-linux-gnu/libpq.so ] && echo "OK" || echo "Error"
 OK

 $ # Проверьте, что psql-клиент может подключиться, с помощью настроек по умолчанию:
 $ # порт = 5432, пользователь = 'postgres', пароль пользователя = 'postgres',
 $ # база данных = 'postgres'. Эти настройки можно изменить, используя
 $ # измененные значения. Вставьте строку в базу данных postgres и завершите работу.
 $ psql -h 127.0.0.1 -p 5432 -U postgres -d postgres
 Password for user postgres:
 psql (9.3.10)
 SSL connection (cipher: DHE-RSA-AES256-SHA, bits: 256)
 Type "help" for help.

 postgres=# CREATE TABLE test (s1 INT, s2 VARCHAR(50));
 CREATE TABLE
 postgres=# INSERT INTO test VALUES (1,'PostgreSQL row');
 INSERT 0 1
 postgres=# \q
 $

 $ # Установите luarocks
 $ sudo apt-get -y install luarocks | grep -E "Setting up|already"
 Setting up luarocks (2.0.8-2) ...

 $ # Настройте список сторонних модулей Tarantool'а в ~/.luarocks,
 $ # следуя инструкциям по ссылке rocks.tarantool.org
 $ mkdir ~/.luarocks
 $ echo "rocks_servers = {[[http://rocks.tarantool.org/]]}" >> \
         ~/.luarocks/config.lua

 $ # Убедитесь, что при следующей установке будут использованы файлы из главного
 $ # хранилища Tarantool'а. Получаем результат, нормальный для Ubuntu 12.04 Precise Pangolin
 $ cat /etc/apt/sources.list.d/tarantool.list
 deb http://tarantool.org/dist/1.7/ubuntu/ precise main
 deb-src http://tarantool.org/dist/1.7/ubuntu/ precise main

 $ # Установите tarantool-dev. Строка на экране должна показать версию 1.7
 $ sudo apt-get -y install tarantool-dev | grep -E "Setting up|already"
 Setting up tarantool-dev (1.7.0.222.g48b98bb~precise-1) ...
 $

 $ # Используйте luarocks для локальной установки, то есть в $HOME
 $ luarocks install pg POSTGRESQL_LIBDIR=/usr/lib/x86_64-linux-gnu --local
 Installing http://rocks.tarantool.org/pg-scm-1.rockspec...
 ... (здесь будет еще информация о сборке драйвера Tarantool/PostgreSQL)
 pg scm-1 is now built and installed in ~/.luarocks/

 $ # Убедитесь, что driver.so создан в месте,
 $ # где Tarantool будет искать его
 $ find ~/.luarocks -name "driver.so"
 ~/.luarocks/lib/lua/5.1/pg/driver.so

 $ # Измените директорию на директорию, которую можно использовать для
 $ # временного тестирования. В данном примере предполагаем, что имя
 $ # name этой директории будет $HOME/tarantool_sandbox.
 $ # (Измените "$HOME" на фактическую корневую директорию
 $ # машины, используемой для тестирования.)
 cd $HOME/tarantool_sandbox

 $ # Запустите экземпляр Tarantool-сервера. Не используйте файл инициализации Lua.

 $ tarantool
 tarantool: version 1.7.0-412-g803b15c
 type 'help' for interactive help
 tarantool>

Настройте Tarantool и загрузите модуль pg. Убедитесь, что Tarantool не выбрасывает ошибку в ответ на вызов «require()».

tarantool> box.cfg{}
 ...
 tarantool> pg = require('pg')
 ---
 ...

Создайте Lua-функцию, которая подключится к PostgreSQL-серверу (используя значения по умолчанию для параметров порта, пользователя и пароля), выберите одну строку и выведите ее на экран. Описание используемых здесь типов операторов вы можете найти в практикуме по Lua в руководстве пользователя Tarantool’а.

tarantool> function pg_select ()
          >   local conn = pg.connect({
          >     host = '127.0.0.1',
          >     port = 5432,
          >     user = 'postgres',
          >     password = 'postgres',
          >     db = 'postgres'
          >   })
          >   local test = conn:execute('SELECT * FROM test WHERE s1 = 1')
          >   local row = ''
          >   for i, card in pairs(test) do
          >       row = row .. card.s2 .. ' '
          >       end
          >   conn:close()
          >   return row
          > end
 ---
 ...
 tarantool> pg_select()
 ---
 - 'PostgreSQL row '
 ...

Просмотрите результат. В нем есть строка «PostgreSQL row». Это и есть строка, которая была вставлена в базу данных PostgreSQL. А сейчас она выделена с помощью Tarantool-клиента.