(Внимание: Если вы измените обертку внешних данных по умолчанию oracle_fdw, любые изменения будут потеряны при дампе/восстановлении. Создайте новую обертку внешних данных, если хотите, чтобы параметры сохранялись. SQL-скрипт, поставляемый с программным обеспечением, содержит оператор CREATE FOREIGN DATA WRAPPER, который вы можете использовать.)

Пользователю Oracle, очевидно, потребуется привилегия CREATE SESSION и право на выборку из соответствующей таблицы или представления. Обратите внимание, что oracle_fdw обращается к таблице Oracle во время планирования запроса, чтобы получить её определение. Это происходит до проверки разрешений на внешнюю таблицу. Следовательно, вы можете получить ошибку Oracle, если попытаетесь получить доступ к внешней таблице, на которую у вас нет разрешений в PostgreSQL. Это ожидаемое поведение и не является проблемой безопасности.

Для EXPLAIN VERBOSE пользователю также понадобятся привилегии SELECT на V$SQL и V$SQL_PLAN.

oracle_fdw кэширует подключения к Oracle, потому что создание сеанса Oracle для каждого отдельного запроса является дорогостоящим. Все подключения автоматически закрываются при завершении сеанса PostgreSQL.

Функция oracle_close_connections() может быть использована для закрытия всех кэшированных подключений к Oracle. Это может быть полезно для длительных сессий, которые не обращаются к внешним таблицам все время и хотят избежать блокировки ресурсов, необходимых для открытого подключения к Oracle. Вы не можете вызвать эту функцию внутри транзакции, которая изменяет данные Oracle.

Когда вы определяете внешнюю таблицу, столбцы таблицы Oracle сопоставляются со столбцами PostgreSQL в порядке их определения.

oracle_fdw будет включать в запрос Oracle только те столбцы, которые действительно нужны для запроса PostgreSQL.

Таблица PostgreSQL может иметь больше или меньше столбцов, чем таблица Oracle. Если в ней больше столбцов, и эти столбцы используются, вы получите предупреждение, и будут возвращены значения NULL.

Если нужно выполнить UPDATE или DELETE, убедитесь, что key опция установлена для всех столбцов, которые принадлежат первичному ключу таблицы. В противном случае это приведет к ошибкам.

Вы должны определить столбцы PostgreSQL с типами данных, которые oracle_fdw может преобразовать (см. таблицу преобразования ниже). Это ограничение применяется только в том случае, если столбец действительно используется, поэтому вы можете определить “фиктивные” столбцы для непереводимых типов данных, пока вы не обращаетесь к ним (этот трюк работает только с SELECT, но не при изменении внешних данных). Если значение Oracle превышает размер столбца PostgreSQL (например, длину столбца varchar или максимальное значение целого числа), вы получите ошибку времени выполнения.

Эти преобразования автоматически обрабатываются oracle_fdw:

Oracle type              | Possible PostgreSQL types
-------------------------+--------------------------------------------------
CHAR                     | char, varchar, text
NCHAR                    | char, varchar, text
VARCHAR                  | char, varchar, text
VARCHAR2                 | char, varchar, text, json
NVARCHAR2                | char, varchar, text
CLOB                     | char, varchar, text, json
LONG                     | char, varchar, text
RAW                      | uuid, bytea
BLOB                     | bytea
BFILE                    | bytea (read-only)
LONG RAW                 | bytea
NUMBER                   | numeric, float4, float8, char, varchar, text
NUMBER(n,m) with m<=0    | numeric, float4, float8, int2, int4, int8,
                         |    boolean, char, varchar, text
FLOAT                    | numeric, float4, float8, char, varchar, text
BINARY_FLOAT             | numeric, float4, float8, char, varchar, text
BINARY_DOUBLE            | numeric, float4, float8, char, varchar, text
DATE                     | date, timestamp, timestamptz, char, varchar, text
TIMESTAMP                | date, timestamp, timestamptz, char, varchar, text
TIMESTAMP WITH TIME ZONE | date, timestamp, timestamptz, char, varchar, text
TIMESTAMP WITH           | date, timestamp, timestamptz, char, varchar, text
   LOCAL TIME ZONE       |
INTERVAL YEAR TO MONTH   | interval, char, varchar, text
INTERVAL DAY TO SECOND   | interval, char, varchar, text
XMLTYPE                  | xml, char, varchar, text
MDSYS.SDO_GEOMETRY       | geometry (see "PostGIS support" below)

Если NUMBER преобразуется в boolean, 0 означает false, все остальное true.

Вставка или обновление XMLTYPE работает только с значениями, которые не превышают максимальную длину типа данных VARCHAR2 (4000 или 32767, в зависимости от параметра MAX_STRING_SIZE).

NCLOB в настоящее время не поддерживается, потому что Oracle не может автоматически преобразовать его в кодировку клиента.

Если нужно преобразовать TIMESTAMP WITH LOCAL TIME ZONE в timestamp, рассмотрите возможность установки опции set_timezone на удаленном сервере.

Если вам нужны преобразования, превышающие вышеуказанные, определите соответствующее представление в Oracle или PostgreSQL.

PostgreSQL будет использовать все применимые части предложения WHERE в качестве фильтра для сканирования. Запрос Oracle, который создается oracle_fdw, будет содержать предложение WHERE, соответствующее этим критериям фильтрации, всякий раз, когда такое условие может быть безопасно переведено на Oracle SQL. Эта функция, также известная как передача условий WHERE, может значительно сократить количество строк, извлекаемых из Oracle, и может позволить оптимизатору Oracle выбрать хороший план для доступа к необходимым таблицам.

Аналогично, предложения ORDER BY будут переданы в Oracle, где это возможно. Обратите внимание, что никакое условие ORDER BY, которое сортирует по строке символов, не будет передано, так как порядок сортировки в PostgreSQL и Oracle не может быть гарантированно одинаковым.

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

Выражения now(), transaction_timestamp(), current_timestamp, current_date и localtimestamp будут переведены правильно.

Вывод EXPLAIN покажет используемый запрос Oracle, так что вы сможете увидеть, какие условия были переведены на Oracle и как.

Начиная с PostgreSQL 9.6, oracle_fdw может передавать соединения на сервер Oracle, то есть соединение между двумя внешними таблицами приведет к одному запросу Oracle, который выполняет соединение на стороне Oracle.

Есть некоторые ограничения, когда это может произойти:

Важно, чтобы статистика таблиц для обеих внешних таблиц была собрана с помощью ANALYZE, чтобы PostgreSQL мог определить наилучшую стратегию соединения.

oracle_fdw поддерживает INSERT, UPDATE и DELETE на внешних таблицах. Это разрешено по умолчанию (также в базах данных, обновленных с более раннего выпуска PostgreSQL) и может быть отключено путем установки опции таблицы readonly.

Для работы команд UPDATE и DELETE столбцы, соответствующие столбцам первичного ключа таблицы Oracle, должны иметь установленную опцию столбца key. Эти столбцы используются для идентификации строки внешней таблицы, поэтому убедитесь, что опция установлена на всех столбцах, которые принадлежат первичному ключу.

Если вы пропустите столбец внешней таблицы при выполнении INSERT, этот столбец будет установлен в значение, определенное в предложении DEFAULT на внешней таблице PostgreSQL (или NULL, если предложение DEFAULT отсутствует). Предложения DEFAULT на соответствующих столбцах Oracle не используются. Если внешняя таблица PostgreSQL не включает все столбцы таблицы Oracle, предложения DEFAULT Oracle будут использоваться для столбцов, не включенных в определение внешней таблицы.

Клаузула RETURNING в операциях INSERT, UPDATE и DELETE поддерживается, за исключением столбцов с типами данных Oracle LONG и LONG RAW (Oracle не поддерживает эти типы данных в клаузуле RETURNING).

Триггеры на внешних таблицах поддерживаются, начиная с PostgreSQL 9.4. Триггеры, определенные с AFTER и FOR EACH ROW, требуют, чтобы внешняя таблица не имела столбцов с типом данных Oracle LONG или LONG RAW. Это связано с тем, что такие триггеры используют упомянутую выше клаузулу RETURNING.

Хотя изменение внешних данных работает, производительность не особенно хорошая, особенно когда затрагивается много строк, потому что (из-за того, как работают обертки внешних данных) каждая строка должна обрабатываться индивидуально.

Транзакции пересылаются в Oracle, поэтому BEGIN, COMMIT, ROLLBACK и SAVEPOINT работают как ожидалось. Подготовленные операторы, включающие Oracle, не поддерживаются. См. раздел Внутреннее устройство для подробностей.

Поскольку oracle_fdw по умолчанию использует сериализованные транзакции, возможно, что операторы изменения данных приведут к ошибке сериализации:

ORA-08177: can't serialize access for this transaction

Это может произойти, если параллельные транзакции изменяют таблицу, и вероятность этого увеличивается в долгосрочных транзакциях. Такие ошибки можно определить по их SQLSTATE (40001). Приложение, использующее oracle_fdw, должно повторить транзакции, которые завершились с этой ошибкой.

Возможно использовать другой уровень изоляции транзакций, см. Параметры внешнего сервера для обсуждения.

EXPLAIN в PostgreSQL покажет запрос, который фактически отправляется в Oracle. EXPLAIN VERBOSE покажет план выполнения Oracle (это не будет работать с сервером Oracle 9i или старше, см. Проблемы).

Вы можете использовать ANALYZE для сбора статистики по внешней таблице. Это поддерживается oracle_fdw.

Без статистики PostgreSQL не имеет способа оценить количество строк для запросов к внешней таблице, что может привести к выбору неэффективных планов выполнения.

PostgreSQL не будет автоматически собирать статистику для внешних таблиц с помощью демона autovacuum, как это делается для обычных таблиц, поэтому особенно важно запускать ANALYZE для внешних таблиц после их создания и всякий раз, когда удаленная таблица значительно изменилась.

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

Тип данных geometry доступен только при установке PostGIS.

Единственные поддерживаемые типы геометрии: POINT, LINE, POLYGON, MULTIPOINT, MULTILINE и MULTIPOLYGON в двух и трех измерениях. Пустые геометрии PostGIS не поддерживаются, так как у них нет эквивалента в Oracle Spatial.

Значения NULL для Oracle SRID будут преобразованы в 0 и наоборот. Для других преобразований между Oracle SRID и PostGIS SRID создайте файл srid.map в каталоге share PostgreSQL. Каждая строка этого файла должна содержать Oracle SRID и соответствующий PostGIS SRID, разделенные пробелом. Держите файл небольшим для хорошей производительности.

Начиная с PostgreSQL 9.5, поддерживается команда IMPORT FOREIGN SCHEMA для массового импорта определений таблиц для всех таблиц в схеме Oracle. В дополнение к документации по IMPORT FOREIGN SCHEMA, рассмотрите следующее:

Обратите внимание, что IMPORT FOREIGN SCHEMA не работает с сервером Oracle 8i; см. раздел Проблемы для получения подробной информации.

Убедитесь, что общая библиотека oracle_fdw установлена в библиотечный каталог PostgreSQL и что oracle_fdw.control и SQL файлы находятся в каталоге расширений PostgreSQL.

Поскольку общая библиотека клиента Oracle, вероятно, не находится в стандартном пути библиотек, вы должны убедиться, что сервер PostgreSQL сможет её найти. Как это сделать, зависит от операционной системы; в Linux вы можете установить LD_LIBRARY_PATH или использовать /etc/ld.so.conf.

Убедитесь, что все необходимые переменные окружения Oracle установлены в окружении процесса сервера PostgreSQL (ORACLE_HOME, если вы не используете Instant Client, TNS_ADMIN, если у вас есть конфигурационные файлы и т.д.)

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

CREATE EXTENSION oracle_fdw;

Это определит необходимые функции и создаст обертку для внешних данных.

Для обновления с версии oracle_fdw до 1.0.0, используйте

ALTER EXTENSION oracle_fdw UPDATE;

Обратите внимание, что версия расширения, отображаемая командой psql \dx или системным каталогом pg_available_extensions, не является установленной версией oracle_fdw. Чтобы получить версию oracle_fdw, используйте функцию oracle_diag.

Если вы не разрабатываете oracle_fdw или не хотите тестировать его функциональность на экзотической платформе, вам не нужно этого делать.

Для того чтобы регрессионные тесты работали, у вас должен быть запущен кластер PostgreSQL и сервер Oracle (версии 10.2 или выше с Locator или Spatial), а бинарные файлы oracle_fdw должны быть установлены. Регрессионные тесты создадут базу данных под названием contrib_regression и выполнят ряд тестов. Для успешного выполнения регрессионных тестов PostGIS, бинарные файлы PostGIS должны быть установлены.

База данных Oracle должна быть подготовлена следующим образом: - Должен существовать пользователь scott с паролем tiger (если вы не хотите редактировать скрипты регрессионного тестирования). Пользователю необходимы системные привилегии CREATE SESSION, CREATE TABLE, CREATE VIEW и CREATE MATERIALIZED VIEW, а также достаточная квота на его таблицы по умолчанию, а также привилегии SELECT на V$SQL и V$SQL_PLAN.

Установите окружение для сервера PostgreSQL так, чтобы он мог установить соединение с Oracle без строки подключения: Если сервер Oracle находится на той же машине, установите переменные окружения ORACLE_SID и ORACLE_HOME соответствующим образом, для удаленного сервера установите переменную окружения TWO_TASK (или LOCAL на Windows) на строку подключения.

Регрессионные тесты выполняются следующим образом:

$ make installcheck

Тесты на регрессию поддерживаются в актуальном состоянии с последней версией разработки PostgreSQL. Если вы запускаете их с более старыми версиями PostgreSQL, вы можете ожидать незначительные различия, такие как измененные сообщения об ошибках или другой формат вывода psql.

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

Если вы используете кодировку базы данных PostgreSQL, которую Oracle не знает (в настоящее время это EUC_CN, EUC_KR, LATIN10, MULE_INTERNAL, WIN874 и SQL_ASCII), символы, не относящиеся к ASCII, не могут быть переведены правильно. В этом случае вы получите предупреждение, и символы будут заменены на символы замены, как описано выше.

Вы можете установить опцию nls_lang внешнего источника данных, чтобы принудительно использовать определенную кодировку Oracle, но полученные символы, скорее всего, будут некорректными и приведут к ошибкам PostgreSQL. Это, вероятно, полезно только для кодировки SQL_ASCII, если вы точно знаете, что делаете. См. раздел Опции.

Библиотека совместного использования клиента Oracle поставляется с собственной реализацией клиента LDAP, соответствующей RFC 1823, поэтому эти функции имеют те же имена, что и у OpenLDAP. Это приведет к конфликту имен, если сервер PostgreSQL был настроен с параметром --with-ldap.

Конфликт имен не будет обнаружен, потому что oracle_fdw загружается во время выполнения, но проблемы возникнут, если кто-то вызовет функцию LDAP. Обычно сначала загружается OpenLDAP, поэтому если Oracle вызывает функцию LDAP (например, если вы используете разрешение имен в каталоге), серверная часть завершится аварийно. Это может привести к сообщениям, подобным следующему (наблюдается на Linux) в журнале сервера PostgreSQL:

../../../libraries/libldap/getentry.c:29: ldap_first_entry:
 Assertion `( (ld)->ld_options.ldo_valid == 0x2 )' failed.

Лучше всего настроить PostgreSQL --without-ldap. Это единственный безопасный способ избежать этой проблемы. Даже если PostgreSQL собран с опцией --with-ldap, он может работать, пока вы не используете функциональность LDAP клиента в Oracle. На некоторых платформах вы можете заставить клиентскую библиотеку Oracle загружаться перед запуском сервера PostgreSQL (LD_PRELOAD на Linux). Тогда должны использоваться функции LDAP от Oracle. В этом случае Oracle может использовать функциональность LDAP, но использование LDAP из PostgreSQL приведет к сбою сервера.

Вы не можете использовать функциональность LDAP как в PostgreSQL, так и в Oracle, точка.

В Oracle 11.2 или выше, вставка первой строки в только что созданную таблицу Oracle с помощью oracle_fdw приведет к ошибке сериализации.

Это связано с функцией Oracle, называемой отложенное создание сегмента, которая откладывает выделение места для новой таблицы до вставки первой строки. Это вызывает сбой сериализации с сериализуемыми транзакциями (см. документ 1285464.1 в базе знаний Oracle).

Это не серьезная проблема; вы можете обойти ее, либо игнорируя первую ошибку, либо создавая таблицу с SEGMENT CREATION IMMEDIATE.

Гораздо более неприятная проблема заключается в том, что параллельные вставки могут иногда вызывать ошибки сериализации, когда страница индекса разделяется одновременно с модифицирующей сериализуемой транзакцией (см. документ Oracle 160593.1).

Oracle утверждает, что это не ошибка, и предложенное решение заключается в повторной попытке выполнения транзакции, которая вызвала ошибку сериализации.

Это список ошибок Oracle, которые влияют или влияли на oracle_fdw.

Ошибка 2728408 может вызвать ORA-8177 невозможно сериализовать доступ для этой транзакции даже если попытка модификации удаленных данных не производится. Это может произойти с сервером Oracle 8.1.7.4 (установите одноразовый патч 2728408) или сервером Oracle 9.2 (установите Patch Set 9.2.0.4 или лучше).

Клиент Oracle 21c, как известно, не работает с колонками CLOB (они отображаются пустыми). Нет окончательного доказательства, что это ошибка Oracle, но другие версии работают нормально.

Следующее сообщение об ошибке (из любого запроса, включающего внешнюю таблицу Oracle) указывает на то, что PostgreSQL не может найти библиотеку клиента Oracle:

ERROR:  Oracle client library (oci.dll) not found
DETAIL:  No Oracle client is installed, or your system is configured incorrectly.
HINT:  Verify that the PATH variable includes the Oracle client.

Убедитесь, что путь к oci.dll находится в переменной окружения PATH пользователя, запускающего сервер PostgreSQL. Если он работает как служба Windows, это системная среда, и после изменения необходимо перезапустить службу.

Если обновление окружения не работает, возможно, вы используете дистрибутив PostgreSQL, который предоставляет свои собственные переменные окружения, скрывая клиент Oracle. См. отчет об ошибке на вопрос на GitHub #160 для получения дополнительной информации.