Модули СУБД 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 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. Убедитесь, что 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.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 = {host-name} — строка, значение по умолчанию = 'localhost'
• port = {port-number} — число, значение по умолчанию = 3306
• user = {user-name} — строка, значение по умолчанию — имя пользователя операционной системы
• password = {password} — строка, значение по умолчанию — пустая строка
• db = {database-name} — строка, значение по умолчанию — пустая строка
• 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 = {socket-name}.

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

 
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$ # Check that the include subdirectory exists by looking$ # for .../include/mysql.h. (If this fails, there's a chance$ # that it's in .../include/mysql/mysql.h instead.)$ [ -f $TMDIR/include/mysql.h ] && echo "OK" || echo "Error"OK$ # Check that the library subdirectory exists and has the$ # necessary .so file.$ [ -f $TMDIR/lib/libmysqlclient.so ] && echo "OK" || echo "Error"OK$ # Check that the mysql client can connect using some factory$ # defaults: port = 3306, user = 'root', user password = '',$ # database = 'test'. These can be changed, provided one uses$ # the changed values in all places.$ $TMDIR/bin/mysql --port=3306 -h 127.0.0.1 --user=root \    --password= --database=testWelcome to the MySQL monitor.  Commands end with ; or \g.Your MySQL connection id is 25Server version: 5.5.35 MySQL Community Server (GPL)...Type 'help;' or '\h' for help. Type '\c' to clear ...$ # Insert a row in database test, and quit.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> QUITBye$ # Install luarocks$ sudo apt-get -y install luarocks | grep -E "Setting up|already"Setting up luarocks (2.0.8-2) ...$ # Set up the Tarantool rock list in ~/.luarocks,$ # following instructions at rocks.tarantool.org$ mkdir ~/.luarocks$ echo "rocks_servers = {[[http://rocks.tarantool.org/]]}" >> \    ~/.luarocks/config.lua$ # Ensure that the next "install" will get files from Tarantool$ # master repository. The resultant display is normal for Ubuntu$ # 12.04 precise$ cat /etc/apt/sources.list.d/tarantool.listdeb http://tarantool.org/dist/2.1/ubuntu/ precise maindeb-src http://tarantool.org/dist/2.1/ubuntu/ precise main$ # Install tarantool-dev. The displayed line should show version = 2.1$ sudo apt-get -y install tarantool-dev | grep -E "Setting up|already"Setting up tarantool-dev (2.1.0.222.g48b98bb~precise-1) ...$$ # Use luarocks to install locally, that is, relative to $HOME$ luarocks install mysql MYSQL_LIBDIR=/usr/local/mysql/lib --localInstalling http://rocks.tarantool.org/mysql-scm-1.rockspec...... (more info about building the Tarantool/MySQL driver appears here)mysql scm-1 is now built and installed in ~/.luarocks/$ # Ensure driver.so now has been created in a place$ # tarantool will look at$ find ~/.luarocks -name "driver.so"~/.luarocks/lib/lua/5.1/mysql/driver.so$ # Change directory to a directory which can be used for$ # temporary tests. For this example we assume that the name$ # of this directory is /home/pgulutzan/tarantool_sandbox.$ # (Change "/home/pgulutzan" to whatever is the user's actual$ # home directory for the machine that's used for this test.)$ cd /home/pgulutzan/tarantool_sandbox$ # Start the Tarantool server instance. Do not use a Lua initialization file.$ tarantooltarantool: version 2.1.0-222-g48b98bbtype 'help' for interactive helptarantool>

Настройте 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 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 и убедитесь, что tarantool указан среди upstream-серверов, как описано в инструкциях на rocks.tarantool.org — странице luarocks Tarantool. Теперь выполните следующую команду:

 
luarocks install pg [POSTGRESQL_LIBDIR = *путь*] [POSTGRESQL_INCDIR = *путь*] [–local]``` bashНапример:``` bash$ luarocks install pg POSTGRESQL_LIBDIR=/usr/local/postgresql/lib

Перейдите по ссылке 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 = {host-name} — строка, значение по умолчанию = 'localhost'
• port = {port-number} — число, значение по умолчанию = 5432
• user = {user-name} — строка, значение по умолчанию — имя пользователя операционной системы
• pass = {password} или password = {password} — строка, значение по умолчанию — пустая строка
• db = {database-name} — строка, значение по умолчанию — пустая строка

Имена параметров похожи на имена, которые используются в 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'.

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

 
*connection-name*:ping()

Пример:

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

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

 
*connection-name*:execute(*sql-statement* [, *parameters*])

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

Пример:

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

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

 
*connection-name*: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.

 
$ # Check that the include subdirectory exists$ # by looking for /usr/include/postgresql/libpq-fe-h.$ [ -f /usr/include/postgresql/libpq-fe.h ] && echo "OK" || echo "Error"OK$ # Check that the library subdirectory exists and has the necessary .so file.$ [ -f /usr/lib/x86_64-linux-gnu/libpq.so ] && echo "OK" || echo "Error"OK$ # Check that the psql client can connect using some factory defaults:$ # port = 5432, user = 'postgres', user password = 'postgres',$ # database = 'postgres'. These can be changed, provided one changes$ # them in all places. Insert a row in database postgres, and quit.$ psql -h 127.0.0.1 -p 5432 -U postgres -d postgresPassword 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 TABLEpostgres=# INSERT INTO test VALUES (1,'PostgreSQL row');INSERT 0 1postgres=# \q$$ # Install luarocks$ sudo apt-get -y install luarocks | grep -E "Setting up|already"Setting up luarocks (2.0.8-2) ...$ # Set up the Tarantool rock list in ~/.luarocks,$ # following instructions at rocks.tarantool.org$ mkdir ~/.luarocks$ echo "rocks_servers = {[[http://rocks.tarantool.org/]]}" >> \        ~/.luarocks/config.lua$ # Ensure that the next "install" will get files from Tarantool master$ # repository. The resultant display is normal for Ubuntu 12.04 precise$ cat /etc/apt/sources.list.d/tarantool.listdeb http://tarantool.org/dist/2.0/ubuntu/ precise maindeb-src http://tarantool.org/dist/2.0/ubuntu/ precise main$ # Install tarantool-dev. The displayed line should show version = 2.0$ sudo apt-get -y install tarantool-dev | grep -E "Setting up|already"Setting up tarantool-dev (2.0.4.222.g48b98bb~precise-1) ...$$ # Use luarocks to install locally, that is, relative to $HOME$ luarocks install pg POSTGRESQL_LIBDIR=/usr/lib/x86_64-linux-gnu --localInstalling http://rocks.tarantool.org/pg-scm-1.rockspec...... (more info about building the Tarantool/PostgreSQL driver appears here)pg scm-1 is now built and installed in ~/.luarocks/$ # Ensure driver.so now has been created in a place$ # tarantool will look at$ find ~/.luarocks -name "driver.so"~/.luarocks/lib/lua/5.1/pg/driver.so$ # Change directory to a directory which can be used for$ # temporary tests. For this example we assume that the$ # name of this directory is $HOME/tarantool_sandbox.$ # (Change "$HOME" to whatever is the user's actual$ # home directory for the machine that's used for this test.)cd $HOME/tarantool_sandbox$ # Start the Tarantool server instance. Do not use a Lua initialization file.$ tarantooltarantool: version 2.0.4-412-g803b15ctype 'help' for interactive helptarantool>

Настройте 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-клиента.