H.7. TDS Foreign data wrapper#

H.7. TDS Foreign data wrapper
H.7. TDS Foreign data wrapper
Назад НаверхПредметный указатель H. Дополнительные внешние модулиНачало Далее

H.7. TDS Foreign data wrapper #

H.7.1. О tds_fdw
H.7.2. Установка на RHEL и клонах (CentOS, Rocky Linux, AlmaLinux, Oracle…)
H.7.3. Установка на Ubuntu
H.7.4. Установка на Debian
H.7.5. Установка на openSUSE
H.7.6. Установка на OSX
H.7.7. Установка на Alpine (и Docker)
H.7.8. Использование
H.7.9. Заметки о наборах символов/кодировке
H.7.10. Зашифрованные соединения с MSSQL
H.7.11. Поддержка
H.7.12. Отладка

Это внешний обработчик данных PostgreSQL, который может подключаться к базам данных, использующим протокол Tabular Data Stream (TDS), таким как базы данных Sybase и сервер Microsoft SQL.

Этот адаптер внешних данных требует библиотеку, которая реализует интерфейс DB-Library, такую как FreeTDS. Это было протестировано с FreeTDS, но не с проприетарными реализациями DB-Library.

Это должно поддерживать Tantor SE 14+.

Текущая версия еще не поддерживает JOIN push-down или операции записи.

Он поддерживает WHERE и pushdown столбцов, когда match_column_names включен.

H.7.1. О tds_fdw #

Версия: 2.0.4

GitHub

Автор: Geoff Montee

H.7.2. Установка на RHEL и клонах (CentOS, Rocky Linux, AlmaLinux, Oracle…) #

Этот раздел описывает, как установить tds_fdw на Rocky Linux 8.9. Дистрибутивы RHEL должны быть аналогичными.

Примечание

Для простоты мы будем использовать yum, так как он работает как псевдоним для dnf на более новых дистрибутивах.

H.7.2.1. Вариант A: yum/dnf (выпущенные версии) #

H.7.2.1.1. tds_fdw #

Команда разработчиков Tantor SE упаковывает tds_fdw, но они не предоставляют FreeTDS.

Сначала установите репозиторий EPEL: 

sudo yum install epel-release

А затем установите tds_fdw: 

sudo yum install tds_fdw11.x86_64

H.7.2.2. Вариант B: Скомпилировать tds_fdw #

H.7.2.2.1. Установите FreeTDS devel и зависимости для сборки #

Обертка внешних данных TDS требует библиотеку, которая реализует интерфейс DB-Library, такую как FreeTDS.

Примечание

Вам необходимо установить репозиторий EPEL, чтобы установить FreeTDS 

sudo yum install epel-release
sudo yum install freetds-devel

Некоторые другие зависимости также необходимы для установки Tantor SE и затем компиляции tds_fdw: 

sudo yum install clang llvm make redhat-rpm-config wget

H.7.2.3. Финальные шаги #

H.7.2.3.1. Установить расширение #
/usr/pgsql-11/bin/psql -U postgres
postgres=# CREATE EXTENSION tds_fdw;

H.7.3. Установка на Ubuntu #

Этот раздел описывает, как установить tds_fdw на Ubuntu 18.04. Другие дистрибутивы Ubuntu должны быть аналогичными.

H.7.3.1. Установите FreeTDS и создайте зависимости #

Оболочка внешних данных TDS требует библиотеки, которая реализует интерфейс DB-Library, такой как FreeTDS. 

sudo apt-get update
sudo apt-get install libsybdb5 freetds-dev freetds-common

Некоторые другие зависимости также необходимы для установки PostgreSQL и последующей компиляции tds_fdw: 

sudo apt-get install gnupg gcc make

H.7.4. Установка на Debian #

Этот раздел описывает, как установить tds_fdw на Debian 10. Другие дистрибутивы Debian должны быть аналогичными.

H.7.4.1. Установите FreeTDS и создайте зависимости #

Оболочка внешних данных TDS требует библиотеки, которая реализует интерфейс DB-Library, такой как FreeTDS. 

sudo apt-get update
sudo apt-get install libsybdb5 freetds-dev freetds-common

Некоторые другие зависимости также необходимы для установки Tantor SE и затем компиляции tds_fdw: 

sudo apt-get install gnupg gcc make

H.7.5. Установка на openSUSE #

Этот раздел описывает, как установить tds_fdw на openSUSE Leap 15.1. Другие дистрибутивы openSUSE и SUSE должны быть аналогичными.

H.7.5.1. Установите FreeTDS и создайте зависимости #

Оболочка внешних данных TDS требует библиотеки, которая реализует интерфейс DB-Library, такой как FreeTDS. 

sudo zypper install freetds-devel

Некоторые другие зависимости также необходимы для установки Tantor SE и затем компиляции tds_fdw: 

sudo zypper install gcc make

H.7.6. Установка на OSX #

Этот раздел описывает, как установить tds_fdw на OSX, используя Homebrew менеджер пакетов для необходимых пакетов.

H.7.6.1. Установите FreeTDS #

Оболочка внешних данных TDS требует библиотеки, которая реализует интерфейс DB-Library, такой как FreeTDS. 

brew install freetds

Note: Если вы устанавливаете FreeTDS из другого источника, например, MacPorts, возможно, вам придется изменить значение TDS_INCLUDE в вызовах make ниже (например, -I/opt/local/include/freetds для MacPorts).

H.7.7. Установка на Alpine (и Docker) #

Этот раздел описывает, как установить tds_fdw на Alpine Linux 3.10.3. Другие дистрибутивы Alpine Linux должны быть аналогичными.

H.7.7.1. Установите FreeTDS и создайте зависимости #

Оболочка внешних данных TDS требует библиотеки, которая реализует интерфейс DB-Library, такой как FreeTDS. 

apk add --update freetds-dev

Некоторые другие зависимости также необходимы для установки Tantor SE и затем компиляции tds_fdw: 

apk add gcc libc-dev make

В случае, если вы получите fatal error: stdio.h: No such file or directory позже (на make USE_PGXS=1) - установка musl-dev может помочь (https://stackoverflow.com/questions/42366739/gcc-cant-find-stdio-h-in-alpine-linux): 

apk add musl-dev

H.7.8. Использование #

H.7.8.1. Создание Внешнего Сервера #

H.7.8.1.1. Опции #
H.7.8.1.1.1. Параметры внешнего сервера, которые принимаются: #

  • servername

    Требуется: Да

    По умолчанию: 127.0.0.1

    Имя сервера, адрес или имя хоста удаленного сервера.

    Это может быть DSN, как указано в freetds.conf. См. Поиск имени FreeTDS.

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

  • port

    Требуется: Нет

    Порт удаленного сервера. Это необязательно. Вместо указания порта здесь, его можно указать в freetds.conf (если servername является DSN).

  • database

    Требуется: Нет

    База данных для подключения к этому серверу.

  • dbuse

    Требуется: Нет

    По умолчанию: 0

    Эта опция указывает tds_fdw подключаться непосредственно к database, если dbuse равно 0. Если dbuse не равно 0, tds_fdw будет подключаться к базе данных по умолчанию на сервере, а затем выбирать database, вызывая функцию dbuse() из DB-Library.

    Для Azure, dbuse в настоящее время должен быть установлен в 0.

  • language

    Требуется: Нет

    Язык для использования в сообщениях и локаль для использования в форматах дат. FreeTDS может по умолчанию использовать us_english на большинстве систем. Вы, вероятно, также можете изменить это в freetds.conf.

    Для получения информации, связанной с этим для MS SQL Server, см. SET LANGUAGE в MS SQL Server.

    Для получения информации, связанной с Sybase ASE, см. опции входа в Sybase ASE и SET LANGUAGE в Sybase ASE.

  • character_set

    Требуется: Нет

    Клиентская кодировка, используемая для подключения, если вам нужно установить это по какой-либо причине.

    Для версий протокола TDS 7.0+ соединение всегда использует UCS-2, поэтому этот параметр ничего не делает в этих случаях. См. Локализация и TDS 7.0.

  • tds_version

    Требуется: Нет

    Версия протокола TDS для использования с этим сервером. См. Выбор версии протокола TDS и История версий TDS.

  • msg_handler

    Требуется: Нет

    По умолчанию: blackhole

    Функция, используемая для обработчика сообщений TDS. Опции включают «notice» и «blackhole». С опцией «notice» сообщения TDS преобразуются в уведомления Tantor SE. С опцией «blackhole» сообщения TDS игнорируются.

  • fdw_startup_cost

    Требуется: Нет

    Затраты, используемые для представления накладных расходов на использование этого FDW, используемого при планировании запросов.

  • fdw_tuple_cost

    Требуется: Нет

    Затраты, используемые для представления накладных расходов на извлечение строк с этого сервера, используемые в планировании запросов.

  • sqlserver_ansi_mode

    Требуется: Нет

    Эта опция поддерживается только для SQL Server. По умолчанию установлено значение «false». Установка этого параметра в «true» включит следующие серверные настройки после успешного подключения к внешнему серверу: 

    * CONCAT_NULLS_YIELDS_NULL ON
* ANSI_NULLS ON
* ANSI_WARNINGS ON
* QUOTED_IDENTIFIER ON
* ANSI_PADDING ON
* ANSI_NULL_DFLT_ON ON

Эти параметры в сумме сопоставимы с опцией SQL Server ANSI_DEFAULTS. В отличие от этого, sqlserver_ansi_mode в настоящее время не активирует следующие опции:

  • CURSOR_CLOSE_ON_COMMIT

  • IMPLICIT_TRANSACTIONS

Это соответствует поведению родных драйверов ODBC и OLEDB для SQL Server, которые явно устанавливают их в OFF, если не настроено иначе.

H.7.8.1.1.2. Параметры внешней таблицы, принимаемые в определении сервера: #

Некоторые параметры внешней таблицы также могут быть установлены на уровне сервера. К ним относятся:

  • use_remote_estimate

  • row_estimate_method

H.7.8.1.2. Пример #
CREATE SERVER mssql_svr
   FOREIGN DATA WRAPPER tds_fdw
   OPTIONS (servername '127.0.0.1', port '1433', database 'tds_fdw_test', tds_version '7.1');

H.7.8.2. Создание внешней таблицы #

H.7.8.2.1. Опции #
H.7.8.2.1.1. Принимаемые параметры внешней таблицы: #

  • query

    Требуется: Да (взаимоисключающе с table)

    Строка запроса для использования при запросе внешней таблицы.

  • schema_name

    Требуется: Нет

    Схема, в которой находится таблица. Имя схемы также может быть включено в table_name, поэтому это не обязательно.

  • table_name

    Псевдонимы: таблица

    Обязательно: Да (взаимоисключающее с запросом)

    Таблица на удалённом сервере для выполнения запроса.

  • match_column_names

    Требуется: Нет

    Сопоставлять ли локальные столбцы с удаленными столбцами, сравнивая их имена таблиц, или использовать порядок, в котором они появляются в наборе результатов.

  • use_remote_estimate

    Требуется: Нет

    Будем ли мы оценивать размер таблицы, выполняя некоторую операцию на удаленном сервере (как определено row_estimate_method), или будем использовать только локальную оценку, как определено local_tuple_estimate.

  • local_tuple_estimate

    Требуется: Нет

    Локально установленная оценка количества кортежей, которая используется, когда use_remote_estimate отключена.

  • row_estimate_method

    Требуется: Нет

    По умолчанию: execute

    Это может быть одно из следующих значений:

    • execute: Выполнить запрос на удаленном сервере и получить фактическое количество строк в запросе.

    • showplan_all: Это получает оценочное количество строк, используя SET SHOWPLAN_ALL MS SQL Server.

H.7.8.2.1.2. Параметры столбцов внешней таблицы, которые принимаются: #

  • column_name

    Требуется: Нет

    Имя столбца на удаленном сервере. Если это не установлено, предполагается, что удаленное имя столбца совпадает с локальным именем столбца. Если для таблицы параметр match_column_names установлен в 0, то имена столбцов вообще не используются, поэтому это игнорируется.

H.7.8.2.2. Пример #

Использование определения table_name: 

CREATE FOREIGN TABLE mssql_table (
   id integer,
   data varchar)
   SERVER mssql_svr
   OPTIONS (table_name 'dbo.mytable', row_estimate_method 'showplan_all');

Или используя определение schema_name и table_name: 

CREATE FOREIGN TABLE mssql_table (
   id integer,
   data varchar)
   SERVER mssql_svr
   OPTIONS (schema_name 'dbo', table_name 'mytable', row_estimate_method 'showplan_all');

Или используя определение запроса: 

CREATE FOREIGN TABLE mssql_table (
   id integer,
   data varchar)
   SERVER mssql_svr
   OPTIONS (query 'SELECT * FROM dbo.mytable', row_estimate_method 'showplan_all');

Или установка имени удаленной колонки: 

CREATE FOREIGN TABLE mssql_table (
   id integer,
   col2 varchar OPTIONS (column_name 'data'))
   SERVER mssql_svr
   OPTIONS (schema_name 'dbo', table_name 'mytable', row_estimate_method 'showplan_all');

H.7.8.3. Создание отображения пользователя #

H.7.8.3.1. Опции #

Параметры сопоставления пользователя, которые принимаются:

  • username

    Требуется: Да

    Имя пользователя учетной записи на удаленном сервере.

    ВАЖНО: Если вы используете Azure SQL, то ваше имя пользователя для внешнего сервера должно быть в формате username@servername. Если вы используете только имя пользователя, аутентификация не удастся.

  • password

    Требуется: Да

    Пароль учетной записи на удаленном сервере.

H.7.8.3.2. Пример #
CREATE USER MAPPING FOR postgres
   SERVER mssql_svr 
   OPTIONS (username 'sa', password '');

H.7.8.4. Импорт иностранной схемы #

H.7.8.4.1. Опции #
H.7.8.4.1.1. Принимаемые параметры внешней схемы: #

  • import_default

    Требуется: Нет

    По умолчанию: false

    Управляет включением выражений по умолчанию для столбцов в определения внешних таблиц.

  • import_not_null

    Требуется: Нет

    По умолчанию: true

    Управляет включением ограничений NOT NULL столбцов в определения внешних таблиц.

H.7.8.4.2. Пример #
IMPORT FOREIGN SCHEMA dbo
   EXCEPT (mssql_table)
   FROM SERVER mssql_svr
   INTO public
   OPTIONS (import_default 'true');

H.7.8.5. Переменные #

H.7.8.5.1. Доступные переменные #

  • tds_fdw.show_before_row_memory_stats - выводить статистику контекста памяти в журнал Tantor SE перед извлечением каждой строки.

  • tds_fdw.show_after_row_memory_stats - выводить статистику контекста памяти в журнал Tantor SE после извлечения каждой строки.

  • tds_fdw.show_finished_memory_stats - выводить статистику контекста памяти в журнал Tantor SE после завершения запроса.

H.7.8.5.2. Установка переменных #

Чтобы установить переменную, используйте команду SET. т.е.: 

postgres=# SET tds_fdw.show_finished_memory_stats=1;
SET

H.7.8.6. EXPLAIN #

EXPLAIN (VERBOSE) покажет запрос, отправленный на удаленную систему.

H.7.9. Заметки о наборах символов/кодировке #

  1. Если вы получаете ошибку, подобную этой, с MS SQL Server при работе с данными Unicode:

    Примечание

    Уведомление DB-Library: № сообщения: 4004, Состояние сообщения: 1, Сообщение: Данные Unicode в правиле сортировки «только Unicode» или данные ntext не могут быть отправлены клиентам, использующим DB-Library (таким как ISQL) или ODBC версии 3.7 или более ранней., Server: PILLIUM, Процесс: , Строка: 1, Уровень: ОШИБКА 16: Ошибка DB-Library: DB #: 4004, Сообщение DB: Общая ошибка SQL Server: Проверьте сообщения от SQL Server, OS #: -1, Сообщение OS: (null), Уровень: 16

    Возможно, вам придется вручную установить tds version в freetds.conf на 7.0 или выше. См. Файл freetds.conf. и Выбор версии протокола TDS.

  2. Хотя многие более новые версии протокола TDS будут использовать только USC-2 для связи с сервером, FreeTDS преобразует UCS-2 в набор символов клиента по вашему выбору. Чтобы установить набор символов клиента, вы можете установить client charset в freetds.conf. См. Файл freetds.conf и Локализация и TDS 7.0.

H.7.10. Зашифрованные соединения с MSSQL #

Это обрабатывается FreeTDS, поэтому это нужно настроить в freetds.conf. См. Файл freetds.conf и в freetds.conf settings ищите encryption.

H.7.11. Поддержка #

Если вы обнаружите какие-либо ошибки или хотите запросить улучшения, пожалуйста, отправьте свои комментарии на страницу проблем проекта на GitHub.

H.7.12. Отладка #

H.7.12.1. Тестирование скриптов #

Тестирование должно следовать этому рабочему процессу:

  • Сначала создайте MSSQL Server

    1. Создайте сервер (локальный, контейнер, виртуальная машина или azure)

    2. Создайте тестовую базу данных с соответствующим пользователем и правами доступа

    3. Запустите mssql-tests.py на этом сервере.

  • Далее, создайте сервер Tantor SE

    1. Создайте сервер (на вашем компьютере, с помощью docker или VM)

    2. Скомпилируйте и установите расширение tds_fdw

    3. Создайте тестовую базу данных и схему с правильным пользователем и привилегиями доступа

    4. На этой базе данных вам сначала нужно установить tds_fdw: CREATE EXTENSION tds_fdw;

    5. Вы можете запустить postgresql_test.py

H.7.12.2. Отладка #

Может быть интересно создать полную настройку для целей отладки и использовать тесты, чтобы проверить, не произошло ли регресса. Для этого вы можете использовать параметр --debugging при запуске postgresql-tests.py.

Тестовая программа остановится сразу после создания соединения и предоставит вам PID бэкенда, используемый для тестирования. Это позволит вам подключить gdb в другой сессии оболочки (gdb --pid=<PID>). После подключения с помощью gdb, просто установите точки останова там, где нужно, и выполните cont. Затем вы можете нажать любую клавишу в тестовом скрипте оболочки, чтобы начать тестирование.

Также, в случае сбоя теста, --debugging позволит точно определить, где скрипт завершился с ошибкой, используя информацию класса Diagnostics из psycopg2 и предоставит соответствующий SQL, внедренный в Tantor SE.

H.7.12.3. Добавление или изменение тестов #

Существуют две папки, в которые добавляются тесты:

  • tests/mssql содержит тесты для взаимодействия с сервером MSSQL с использованием mssql-tests.py. Такие тесты обычно используются для создания необходимых элементов для самих тестов Tantor SE.

  • tests/postgresql содержит тест для взаимодействия с сервером Tantor SE с использованием postgresql-tests.py. Такие тесты обычно используются для проверки функциональности tds_fdw.

Каждый тест состоит из двух файлов с одинаковым именем и различным расширением в этом формате: 

XXX_description

Например: 000_my_test.json и 000_my_test.sql.

Правило1: XXX используется для задания порядка скриптов.

Правило2: Если скрипт создает элемент или добавляет строку, он должен предполагать, что такой элемент или строка уже существует, и обрабатывать это (например, удаляя таблицу перед ее созданием)

H.7.12.3.1. Файл JSON #

Всегда имеет следующий формат: 

{
    "test_desc" : "<My description>",
    "server" : {
        "version" : {
            "min" : "<Min.Required.Ver>",
            "max" : "<Max.Supported.Ver>"
        }
    }
}

  • test_desc может быть любой произвольной строкой, описывающей тест.

  • min и max являются версиями в формате X.W[.Y[.Z]] для MSSQL и Tantor SE соответственно.

    • min является обязательным, как минимум 7.0.623 для MSSQL (MSSQL 7.0 RTM) и 9.2.0 для Tantor SE.

    • max также является обязательным, но он может быть пустой строкой, если тест поддерживает до самой последней версии MSSQL или Tantor SE.

Вы можете проверить список версий для MSSQL (формат X.Y.Z и X.Y.W.Z), Tantor SE (форматы X.Y.Z и X.Y), чтобы при необходимости скорректировать значения min и max.

Чтобы проверить файл JSON, вы можете использовать скрипт validate-test-json.

H.7.12.3.2. SQL файл #

Это обычный SQL файл для одного или нескольких запросов для MSSQL или Tantor SE.

Существует несколько переменных, которые могут быть использованы и будут размещены тестирующими скриптами.

Для MSSQL скриптов значения берутся из параметров mssql-tests.py:

  • @SCHEMANAME: Имя схемы MSSQL.

Для скриптов Tantor SE значения берутся из параметров postgresql-tests.py:

  • @PSCHEMANAME: Имя схемы Tantor SE

  • @PUSER: Пользователь Tantor SE

  • @MSERVER: MSSQL сервер

  • @MPORT: Порт MSSQL

  • @MUSER: Пользователь MSSQL

  • @MPASSWORD: Пароль MSSQL

  • @MDATABASE: База данных MSSQL

  • @MSCHEMANAME: Имя схемы MSSQL

  • @TDSVERSION: Версия TDS

Назад Наверх Далее
H.6. pgbouncer Начало Предметный указатель I. Внешние проекты