CONNECT JDBC Тип таблицы: Доступ к таблицам из другой СУБД

Тип JDBC таблицы должен распространяться со всеми последними версиями MariaDB. Однако, если автоматическая компиляция возможна после установки Java JDK, полное распространение не полностью реализовано в более старых версиях. Распределяемый файл JdbcInterface.jar содержит только обёртку JdbcInterface. Новые версии распространяют JavaWrappers.jar, который содержит все имеющиеся в настоящее время обёртки.

Это потребует:

1. Установка Java SDK на вашей системе.
2. Доступность файлов Java wrapper классов на вашей системе.
3. И, конечно же, наличие JDBC драйверов для использования с соответствующей СУБД.

Пункт 2 был автоматизирован в самых последних версиях MariaDB.

Компиляция из исходного распространения

Даже при установленной Java JDK, CMake иногда не может найти местоположение установки. Например, на Linux пакет Oracle Java JDK может быть установлен в путь, неизвестный функциям поиска CMake, что приводит к сообщению об ошибке, например:

CMake Error at /usr/share/cmake/Modules/FindPackageHandleStandardArgs.cmake:148 (message): 
  Could NOT find Java (missing: Java_JAR_EXECUTABLE Java_JAVAC_EXECUTABLE 
  Java_JAVAH_EXECUTABLE Java_JAVADOC_EXECUTABLE)

В этом случае укажите префикс Java, как подсказку о местоположении пакета. Например, в Ubuntu мне пришлось ввести:

export JAVA_HOME=/usr/lib/jvm/java-8-oracle

После этого компиляция типа CONNECT JDBC была успешно завершена.

Компиляция файлов исходного кода Java

Это исходный код Java wrapper классов, используемых для доступа к JDBC драйверам. В исходном распространении они расположены в каталоге CONNECT исходных файлов.

По умолчанию обёртка JdbcInterface является единственной, распространяемой в бинарном распространении. Она использует стандартный способ получения соединения с драйверами через метод DriverManager.getConnection. Другие обёртки, доступные только с исходным распространением, позволяют подключиться к источнику данных, возможно, реализуя пуллинг. Однако, они должны быть скомпилированы и установлены вручную.

Доступные обёртки:

Обёртка, используемая по умолчанию, задаётся сеансовой переменной connect_java_wrapper и изначально установлена в значение wrappers/JdbcInterface. Обёртка, используемая для таблицы, также может быть указана в списке опций как опция обёртки в операциях «создания таблицы».

Примечание: В соответствии с правилами именования Java, имена классов предваряются именем пакета Java с разделителем «/». Однако, это не обязательно для CONNECT, который добавляет имя пакета, если оно отсутствует.

Обёртка JdbcInterface всегда доступна при наличии Java на вашей машине. Бинарные дистрибутивы имеют эту обёртку, уже скомпилированную как файл JdbcInterface.jar, установленный в каталоге плагина, путь к которому автоматически включается в пути поиска класса JVM. Последние версии также добавляют JavaWrappers.jar, содержащий все эти обёртки. Поэтому не нужно беспокоиться о его пути.

Компиляция обёртки ApacheInterface требует установки пакета Apache common-DBCP2. Другие обёртки следует использовать только с соответствующими JDBC драйверами, которые должны быть доступны при их компиляции.

Установка файла jar в каталог плагина — лучшее место, так как он входит в путь поиска классов. В зависимости от установленного на вашей системе, файлы исходного кода могут быть сокращены соответственно. Для компиляции только файла JdbcInterface.java переменная CMAKE_JAVA_INCLUDE_PATH не требуется. Здесь пути, существующие на моей машине Windows 7, и должны быть локализованы.

Настройка необходимой информации

Перед выполнением любой операции с JDBC драйвером, CONNECT должен инициализировать среду, которая позволит работать с Java. Это будет включать:

1. Динамическую загрузку модуля библиотеки JVM.
2. Создание виртуальной машины Java.
3. Установление связи с классом Java wrapper.
4. Подключение к используемому JDBC драйверу.

Действительно, модуль библиотеки JVM не статически связан с плагином CONNECT. Это позволяет использовать плагин CONNECT, скомпилированный с типом таблицы JDBC, на машине, где Java SDK не установлен. В противном случае, пользователи, не заинтересованные в типе таблицы JDBC, были бы обязаны установить Java SDK на своей машине, чтобы загрузить движок хранения CONNECT.

Местоположение библиотеки JVM

Если библиотека JVM (jvm.dll на Windows, libjvm.so на Linux) не расположена в стандартном пути загрузки библиотек, CONNECT не может её найти и должен быть проинформирован о том, где её искать. Это происходит, в частности, на Linux, когда пакет Oracle Javapackage был установлен в частном расположении.

Если переменная JAVA_HOME была экспортирована, как описано выше, CONNECT может иногда найти её, используя эту информацию. В противном случае, её путь поиска может быть добавлен в переменную окружения LD_LIBRARY_PATH. Но всё это сложно, поскольку создание постоянных переменных окружения на Linux затруднено (нужно использовать много разных методов в зависимости от версии Linux и используемой оболочки).

Поэтому CONNECT ввёл новую глобальную переменную connect_jvm_path для хранения этой информации. Она может быть установлена при запуске сервера в качестве командной опции или даже позже, перед первым использованием типа таблицы JDBC. Например:

set global connect_jvm_path="/usr/lib/jvm/java-8-oracle/jre/lib/i386/client"

или

set global connect_jvm_path="/usr/lib/jvm/java-8-oracle/jre/lib/i386/server"

Клиентская библиотека меньше и быстрее для подключения. Серверная библиотека оптимизирована и может использоваться в случае высокой нагрузки.

Обратите внимание, что это может не потребоваться на Windows, так как путь к библиотеке JVM иногда может быть найден в реестре.

После загрузки этой библиотеки, CONNECT может создать необходимую виртуальную машину Java.

Путь поиска классов Java

Это список путей, по которым Java ищет классы. В CONNECT, классы для загрузки будут Java wrapper классами, используемыми для взаимодействия с драйверами, и используемыми JDBC драйверными классами, которые сгруппированы внутри файлов jar. Если необходимо использовать обёртку ApacheInterface, путь поиска также должен включать все три jar файла, используемые пакетом Apache.

Путь к wrapper классам должен указывать на каталог, содержащий подкаталог wrappers. Если был создан файл JdbcInterface.jar, его путь — это каталог, где он находится, и имя файла jar. Непонятно где, так как это будет зависеть от процесса установки. Если вы начинаете с исходного распространения, он может быть в каталоге storage/connect, где находятся исходные файлы CONNECT или куда вы их переместили или скомпилировали файл JdbcInterface.jar.

Для бинарных дистрибутивов ничего делать не нужно, потому что файл jar был установлен в каталог mysql share, путь к которому всегда автоматически включается в путь поиска класса JVM.

Остаются пути всех установленных JDBC драйверов, которые вы хотите использовать. Помните, что их путь должен включать сам файл jar. Некоторые приложения используют переменную окружения CLASSPATH для их хранения. Пути разделены двоеточием (:) на Linux и точкой с запятой (;) на Windows.

Если переменная CLASSPATH действительно существует и доступна внутри MariaDB, всё хорошо. Вы можете проверить это с помощью функции UDF, предоставляемой CONNECT, которая возвращает значения переменных окружения:

create function envar returns string soname 'ha_connect.so';
select envar('CLASSPATH');

Большинство времени это вернёт null или некоторые необходимые файлы отсутствуют. Поэтому CONNECT ввёл глобальную переменную для хранения этой информации. Пути, указанные в этой переменной, будут добавлены и будут иметь приоритет над путями, если таковые есть, переменной окружения CLASSPATH. Как и для пути jvm, эта переменная connect_class_path должна быть указана при запуске сервера, но также может быть установлена перед первым использованием типа таблицы JDBC.

Текущий каталог (sql/data) также помещается CONNECT в начало пути поиска классов.

Вот пример запуска MariaDB при тестировании на Linux:

olivier@olivier-Aspire-8920:~$ sudo /usr/local/mysql/bin/mysqld -u root --console --default-storage-engine=myisam --skip-innodb --connect_jvm_path="/usr/lib/jvm/java-8-oracle/jre/lib/i386/server" --connect_class_path="/home/olivier/mariadb/10.1/storage/connect:/media/olivier/SOURCE/mysql-connector-java-6.0.2/mysql-connector-java-6.0.2-bin.jar"

CONNECT JDBC таблицы

Эти таблицы имеют тип JDBC. Например, предположим, что вы хотите получить доступ к таблице boys, расположенной на внешней локальной или удалённой СУБД, предоставляющей JDBC коннектор:

create table boys (
name char(12),
city char(12),
birth date,
hired date);

Для доступа к этой таблице через JDBC вы можете создать таблицу, например:

create table jboys engine=connect table_type=JDBC tabname=boys
connection='jdbc:mysql://localhost/dbname?user=root';

Опция CONNECTION — это URL, используемый для подключения к удалённому серверу. Его синтаксис зависит от внешней СУБД, и в этом примере используется тот, что подключается как root к локальной базе данных MySQL или MariaDB, используя MySQL JDBC коннектор.

Как и в случае с ODBC, определения столбцов могут быть опущены и будут получены в процессе обнаружения. Ограничения, касающиеся определений столбцов, такие же, как и для ODBC.

Примечание: Имя базы данных, указанное в URL, для многих СУБД соответствует информации о каталоге. Для MySQL и MariaDB это схема (часто называемая базой данных) соединения.

Использование федеративного сервера

В качестве альтернативы, таблица JDBC может указать параметры подключения через федеративный сервер. Например, предположим, что у вас есть таблица, которая обращается к внешней таблице Postgresql, определённой как:

create table juuid engine=connect table_type=JDBC tabname=testuuid
connection='jdbc:postgresql:test?user=postgres&password=pwd';

Вы можете создать федеративный сервер:

create server 'post1' foreign data wrapper 'postgresql' options (
HOST 'localhost',
DATABASE 'test',
USER 'postgres',
PASSWORD 'pwd',
PORT 0,
SOCKET '',
OWNER 'postgres');

Теперь таблица JDBC может быть создана:

create table juuid engine=connect table_type=JDBC connection='post1' tabname=testuuid;

или:

create table juuid engine=connect table_type=JDBC connection='post1/testuuid';

В любом случае, расположение удалённой таблицы может быть изменено на федеративном сервере без необходимости изменения всех таблиц, использующих этот сервер.

JDBC требует URL для установления соединения. CONNECT смог сконструировать этот URL из информации, содержащейся в таком определении федеративного сервера, когда синтаксис URL подобен синтаксису MySQL, MariaDB или Postgresql. Однако другие СУБД, такие как Oracle, используют другой синтаксис URL. В этом случае просто замените информацию HOST требуемым URL в определении федеративного сервера. Например:

create server 'oracle' foreign data wrapper 'oracle' options (
HOST 'jdbc:oracle:thin:@localhost:1521:xe',
DATABASE 'SYSTEM',
USER 'system',
PASSWORD 'manager',
PORT 0,
SOCKET '',
OWNER 'SYSTEM');

Теперь вы можете создать таблицу Oracle примерно так:

create table empor engine=connect table_type=JDBC connection='oracle/HR.EMPLOYEES';

Примечание: Oracle, как и Postgresql, похоже, не понимает параметр DATABASE как схему таблицы, которую необходимо указать в операторе CREATE TABLE.

Подключение к JDBC-драйверу

При установлении соединения с драйвером с помощью обертки JdbcInterface используется параметры, указанные при создании таблиц CONNECT JDBC. В стандартной Java-обертке основной класс драйвера загружается функцией DriverManager.getConnection, которая принимает три аргумента:

URL зависит от подключенной СУБД. Обратитесь к документации конкретного JDBC-драйвера для описания синтаксиса. Пользователя и пароль также можно указать в списке параметров.

Обратите внимание, что имя базы данных в URL может интерпретироваться по-разному в зависимости от СУБД. Для MySQL это схема, в которой находятся таблицы. Однако для Postgresql это каталог, и схема должна быть указана с помощью параметра CONNECT dbname.

Например, таблица, обращаясь к таблице Postgresql через JDBC, может быть создана с помощью оператора CREATE:

create table jt1 engine=connect table_type=JDBC
connection='jdbc:postgresql://localhost/mtr' dbname=public tabname=t1
option_list='User=mtr,Password=mtr'; 

Примечание: В предыдущих версиях JDBC для получения соединения java сначала должна была инициализировать JDBC-драйвер, вызвав метод Class.forName. В этом случае обратитесь к документации драйвера вашей СУБД, чтобы получить имя класса, реализующего интерфейс java.sql.Driver. Это имя можно указать как параметр DRIVER в списке параметров. Однако большинство современных JDBC-драйверов версии 4 и выше самозагружаются и не требуют указания этого параметра.

Класс-обёртка также создаёт необходимые элементы, в частности, класс statement. Некоторые характеристики этого statement будут зависеть от параметров, указанных при создании таблицы:

Размер выборки

Размер выборки определяет количество строк, которые извлекаются драйвером в процессе взаимодействия с СУБД. Значение по умолчанию зависит от JDBC-драйвера. Для некоторых драйверов оно равно 10, но не для MySQL или MariaDB-коннекторов.

Коннекторы MySQL/MariaDB извлекают все строки, возвращаемые одним запросом, и сохраняют их в кэше памяти. Это обычно хорошо в большинстве случаев, но не при извлечении большого набора результатов, что может привести к ошибке исчерпания памяти.

Чтобы избежать этого, при работе с большой таблицей и ожидании больших наборов результатов, вы должны указать параметр BLOCK_SIZE в значение 1 (единственно допустимое значение). Однако проблема остаётся:

Предположим, вы выполняете запрос, такой как:

select id, name, phone from jbig limit 10;

Не зная условия ограничения, CONNECT отправляет запросу в удаленную СУБД:

SELECT id, name, phone FROM big;

В этом запросе big может быть огромной таблицей с миллионами строк. При правильном указании размера блока в 1 при создании таблицы, обёртка просто считывает 10 первых строк и останавливается. Однако при закрытии statement эти драйверы MySQL/MariaDB всё ещё должны извлечь все строки, возвращенные запросом. Вот почему класс обёртка при закрытии statement также отменяет запрос, чтобы остановить это дополнительное чтение.

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

Подключение к источнику данных

Это предпочтительный способ подключения в java, поскольку источник данных может поддерживать пул соединений, которые можно повторно использовать при необходимости. Это делает установление соединений намного быстрее, как только оно было выполнено в первый раз.

CONNECT предоставляет дополнительные обёртки, файлы которых находятся в каталоге исходного кода CONNECT. Используемую обёртку можно указать в глобальной переменной connect_java_wrapper, которая по умолчанию имеет значение «JdbcInterface».

Её также можно указать для таблицы в списке параметров, установив параметр wrapper в его имя. Например:

create table jboys 
engine=CONNECT table_type=JDBC tabname='boys'
connection='jdbc:mariadb://localhost/connect?user=root&useSSL=false'
option_list='Wrapper=MariadbInterface,Scrollable=1';

Их можно использовать вместо стандартного JdbcInterface и использовать созданные источники данных.

Apache использует источники данных, реализованные пакетом Apache-commons-dbcp2, и может использоваться со всеми драйверами, в том числе с теми, которые не реализуют источники данных. Однако пакет Apache должен быть установлен, и его три необходимых jar-файла должны быть доступны через путь к классам.

1. commons-dbcp2-2.1.1.jar
2. commons-pool2-2.4.2.jar
3. commons-logging-1.2.jar

Примечание: номера версий могут отличаться в вашей установке.

Другие используют источники данных, предоставленные соответствующим JDBC-драйвером. В настоящее время существуют четыре обёртки, которые можно использовать с mysql-6.0.2, mariadb, oracle и postgresql.

В отличие от пути к классам, используемая обёртка может быть изменена даже после создания машины JVM.

Случайный доступ к таблицам JDBC

Можно использовать те же методы, что и для таблиц ODBC, с таблицами JDBC.

Обратите внимание, что в случае коннекторов MySQL или MariaDB, поскольку они внутренне считывают весь набор результатов в памяти, использование параметра MEMORY было бы пустой тратой памяти. Гораздо лучше указать использование курсора со скроллингом при необходимости.

Другие операции с таблицами JDBC

За исключением способа указания строки подключения и типа таблицы, установленного на JDBC, все операции с таблицами ODBC выполняются с таблицами JDBC таким же образом. Обратитесь к главе ODBC, чтобы узнать о:

• Доступе к указанным представлениям (SRCDEF)
• Операциях изменения данных.
• Отправке команд в источник данных.
• Информации о каталоге JDBC.

Примечание: некоторые JDBC-драйверы завершаются ошибкой, когда глобальная переменная time_zone является неоднозначной, что иногда случается, когда она установлена на SYSTEM. В этом случае сбросьте её на неопределённое значение, например:

set global time_zone = '+2:00';

Ограничения, специфичные для JDBC

Подключение через внешние источники данных (например, с использованием Tomcat) пока не поддерживается.

Другие ограничения такие же, как и для типа таблицы ODBC.

Обработка типа данных UUID

PostgreSQL имеет собственный тип данных UUID, внутренне хранящийся как BIN(16). Это не тип данных SQL или MariaDB. Лучше всего обработать его с помощью своего текстового представления.

UUID будет преобразован в CHAR(36) при установке определений столбцов с помощью обнаружения. Локально столбец UUID PostgreSQL будет обрабатываться как столбец CHAR или VARCHAR. Пример:

Используя таблицу PostgreSQL testuuid в базе данных text:

 Table « public.testuuid »
 Column | Type | Default
--------+------+--------------------
 id     | uuid | uuid_generate_v4()
 msg    | text | 

Определения столбцов можно запросить:

create or replace table juuidcol engine=connect table_type=JDBC tabname=testuuid catfunc=columns
connection='jdbc:postgresql:test?user=postgres&password=pwd';

select table_name "Table", column_name "Column", data_type "Type", 
  type_name "Name", column_size "Size" 
 from juuidcol;

Этот запрос возвращает:

Примечание: PostgreSQL, когда размер столбца не определён, возвращает 2147483647, что неприемлемо для MariaDB. CONNECT изменяет это на значение переменной сессии connect_conv_size. Также для столбцов TEXT возвращаемый тип данных равен 12 (SQL_VARCHAR) вместо -1 (SQL_TEXT).

Доступ к этой таблице через JDBC:

CREATE TABLE juuid ENGINE=connect TABLE_TYPE=JDBC TABNAME=testuuid
CONNECTION='jdbc:postgresql:test?user=postgres&password=pwd';

она будет создана обнаружением как:

CREATE TABLE `juuid` (
  `id` char(36) DEFAULT NULL,
  `msg` varchar(8192) DEFAULT NULL
) ENGINE=CONNECT DEFAULT CHARSET=latin1 CONNECTION='jdbc:postgresql:test?user=postgres&password=pwd' `TABLE_TYPE`='JDBC' `TABNAME`='testuuid';

Примечание: 8192 здесь – значение _connect_conv_size_.

Заполним её:

insert into juuid(msg) values('First');
insert into juuid(msg) values('Second');
select * from juuid;

Результат:

Здесь значения столбца id взяты из DEFAULT столбца PostgreSQL, который был указан как uuid_generate_v4().

Его можно задать в MariaDB. Например:

insert into juuid
  values('2f835fb8-73b0-42f3-a1d3-8a532b38feca','inserted');
insert into juuid values(NULL,'null');
insert into juuid values('','random');
select * from juuid;

Результат:

Первый вставленный элемент указывает корректное текстовое представление UUID. Второй устанавливает значение NULL. Третий (пустая строка) генерирует случайный UUID Java. Команды UPDATE подчиняются тому же определению.

Эти команды работают:

select * from juuid where id = '2f835fb8-73b0-42f3-a1d3-8a532b38feca';
delete from juuid where id = '2f835fb8-73b0-42f3-a1d3-8a532b38feca';

Однако эта команда терпит неудачу:

select * from juuid where id like '%42f3%';

Возвращая:

1296: Получена ошибка 174 'ExecuteQuery: org.postgresql.util.PSQLException: ОШИБКА: оператор не существует: uuid ~ unknown hint: нет оператора, соответствующего имени данных и типам аргументов.

потому что функция CONNECT cond_push добавила условие WHERE к запросу, отправленному в PostgreSQL:

SELECT id, msg FROM testuuid WHERE id LIKE '%42f3%'

и оператор LIKE не применяется к UUID в PostgreSQL.

Для решения этой проблемы была добавлена новая переменная сессии в CONNECT: connect_cond_push. Она позволяет указать, включена ли функция cond_push для CONNECT и по умолчанию равна 1 (включена). В этом случае вы можете выполнить:

set connect_cond_push=0;

В результате, условие WHERE будет выполнено только MariaDB, и запрос больше не будет терпит неудачу.

Выполнение тестов JDBC

Существуют четыре теста, но они отключены, потому что требуют некоторой работы по их локализации в соответствии с операционной системой и доступными пакетами java и JDBC-драйверами и СУБД.

Два из них, jdbc.test и jdbc_new.test, обращаются к MariaDB через JDBC-драйверы, которые содержатся в fat jar-файле, являющимся частью теста. Они должны быть выполнимы в Windows без каких-либо действий; просто добавьте параметр –enable-disabled при запуске тестов.

Однако на Linux эти тесты могут не найти библиотеку JVM. Перед их выполнением необходимо установить переменную среды JAVA_HOME, указав путь к установке java, или установить LD_LIBRARY_PATH, содержащий путь к библиотеке JVM.

Решение проблемы с mariadb-dump

В некоторых случаях или на некоторых платформах, когда CONNECT настроен для использования типов таблиц JDBC, это приводит к тому, что mariadb-dump с параметром --all-databases терпит неудачу.

Об этом сообщил Роберт Дайас, который обнаружил причину — см. обсуждение на MDEV-11238.