Skip to content

0.7.0 (2023-05-15)

🎉 onETL теперь с открытым исходным кодом 🎉

Это была долгая дорога, но мы наконец-то преодолели её!

Критические изменения

  • Изменен способ установки.

TL;DR Что нужно изменить, чтобы восстановить предыдущее поведение

Простой способ:

onETL < 0.7.0 onETL >= 0.7.0
pip install onetl pip install onetl[files,kerberos]

Правильный способ - перечислить коннекторы, которые должны быть установлены:

pip install onetl[hdfs,ftp,kerberos]  # кроме подключений к БД

Подробности

В onetl<0.7 установка пакета выглядит так:

До
pip install onetl

Но это включает в себя все зависимости для всех коннекторов, даже если пользователь их не использует. Это вызывало некоторые проблемы, например, пользователю приходилось устанавливать библиотеки Kerberos, чтобы иметь возможность установить onETL, даже если он использует только S3 (без поддержки Kerberos).

Начиная с версии 0.7.0 процесс установки был изменен:

После
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
pip install onetl  # минимальная установка, только ядро onETL
# нет extras для подключений к БД, потому что они используют Java пакеты, которые устанавливаются во время выполнения

pip install onetl[ftp,ftps,hdfs,sftp,s3,webdav]  # установить зависимости для указанных файловых подключений
pip install onetl[files]  # установить зависимости для всех файловых подключений

pip install onetl[kerberos]  # Поддержка аутентификации Kerberos
pip install onetl[spark]  # установить PySpark для использования подключений к БД

pip install onetl[spark,kerberos,files]  # все файловые подключения + Kerberos + PySpark
pip install onetl[all]  # алиас для предыдущего случая

Для каждого extras есть соответствующие элементы документации.

Кроме того, onETL проверяет, что некоторые требования отсутствуют, и выдает исключение с рекомендацией, как их установить:

исключение при импорте подключения Clickhouse
Cannot import module "pyspark".

Since onETL v0.7.0 you should install package as follows:
    pip install onetl[spark]

or inject PySpark to sys.path in some other way BEFORE creating MongoDB instance.
исключение при импорте подключения FTP
Cannot import module "ftputil".

Since onETL v0.7.0 you should install package as follows:
    pip install onetl[ftp]

or
    pip install onetl[files]
  • Добавлен новый аргумент cluster для подключений Hive и HDFS.

Полное имя Hive (используемое в HWM) содержит имя кластера. Но в onETL<0.7.0 имя кластера имело не изменяемое значение rnd-dwh, что не подходило некоторым пользователям.

Полное имя соединения HDFS содержит имя хоста (активной namenode кластера Hadoop), но его значение может меняться со временем, что приводит к созданию нового HWM.

Начиная с onETL 0.7.0, оба подключения Hive и HDFS имеют атрибут cluster, в котором можно установить определенное имя кластера. Для Hive это обязательно, для HDFS это можно опустить (используя хост в качестве запасного варианта).

Но передача имени кластера каждый раз может привести к ошибкам.

Теперь Hive и HDFS имеют вложенный класс с именем slots с методами:

  • normalize_cluster_name
  • get_known_clusters
  • get_current_cluster
  • normalize_namenode_host (только HDFS)
  • get_cluster_namenodes (только HDFS)
  • get_webhdfs_port (только HDFS)
  • is_namenode_active (только HDFS)

И новый метод HDFS.get_current / Hive.get_current.

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

См. документацию по slots.

  • Обновление драйверов JDBC соединений.

  • Greenplum 2.1.3 → 2.1.4.

  • MSSQL 10.2.1.jre8 → 12.2.0.jre8. Минимальная поддерживаемая версия MSSQL теперь 2014 вместо 2021.
  • MySQL 8.0.30 → 8.0.33:
    • Переименован пакет mysql:mysql-connector-java → com.mysql:mysql-connector-j.
    • Переименован класс драйвера com.mysql.jdbc.Driver → com.mysql.cj.jdbc.Driver.
  • Oracle 21.6.0.0.1 → 23.2.0.0.
  • Postgres 42.4.0 → 42.6.0.
  • Teradata 17.20.00.08 → 17.20.00.15:
    • Переименован пакет com.teradata.jdbc:terajdbc4 → com.teradata.jdbc:terajdbc.
    • Драйвер Teradata теперь опубликован в Maven.

См. #31.

Функциональность

  • Добавлено подключение MongoDB.

Используется официальный MongoDB connector for Spark v10. Поддерживается только Spark 3.2+.

Есть некоторые различия между MongoDB и другими БД-источниками:

  • Метод mongodb.pipeline применяется вместо mongodb.sql.
  • Нет методов mongodb.fetch и mongodb.execute.
  • Типы DBReader.hint и DBReader.where отличаются от типов для БД, поддерживающих SQL:
where = {
    "col1": {
        "$eq": 10,
    },
}

hint = {
    "col1": 1,
}
  • Поскольку MongoDB не имеет схем для коллекций и Spark не может создавать dataframe с динамической схемой, была введена новая опция DBReader.df_schema. Она обязательна для MongoDB, но необязательна для других источников.
  • В настоящее время DBReader нельзя использовать с MongoDB и hwm выражения, например, hwm_column=("mycolumn", {"$cast": {"col1": "date"}})

Поскольку в MongoDB нет таблиц, в основных классах были переименованы некоторые опции:

  • DBReader(table=...) → DBReader(source=...)
  • DBWriter(table=...) → DBWriter(target=...)

Старые имена также можно использовать, они не устарели (#30).

  • Добавлена опция для отключения некоторых плагинов во время импорта.

Ранее, если какой-либо плагин не работал во время импорта, единственным способом импортировать onETL было отключить все плагины с помощью переменной окружения.

Теперь есть несколько переменных с разным поведением:

  • ONETL_PLUGINS_ENABLED=false - отключить автоматический импорт всех плагинов. Ранее она называлась ONETL_ENABLE_PLUGINS.
  • ONETL_PLUGINS_BLACKLIST=plugin-name,another-plugin - установить список плагинов, которые НЕ должны импортироваться автоматически.
  • ONETL_PLUGINS_WHITELIST=plugin-name,another-plugin - установить список плагинов, которые должны импортироваться ТОЛЬКО автоматически.

Ещё мы улучшили сообщение об исключении с рекомендацией, как отключить неработающий плагин:

пример сообщения об ошибке
Error while importing plugin 'mtspark' from package 'mtspark' v4.0.0.

Statement:
    import mtspark.onetl

Check if plugin is compatible with current onETL version 0.7.0.

You can disable loading this plugin by setting environment variable:
    ONETL_PLUGINS_BLACKLIST='mtspark,failing-plugin'

You can also define a whitelist of packages which can be loaded by onETL:
    ONETL_PLUGINS_WHITELIST='not-failing-plugin1,not-failing-plugin2'

Please take into account that plugin name may differ from package or module name.
See package metadata for more details

Улучшения

  • Добавлена совместимость с Python 3.11 и PySpark 3.4.0.

Файловые подключения работали нормально, но jdbc.fetch и jdbc.execute не работали. Исправлено в #28.

  • Добавлена проверка отсутствующих пакетов Java.

Ранее, если подключение к БД пыталось использовать какой-либо Java-класс, который не был загружен в версию Spark, возникало исключение с длинным stacktrace. Большинство пользователей не могли интерпретировать эту информацию.

Теперь onETL показывает следующее сообщение об ошибке:

пример сообщения об ошибке
|Spark| Cannot import Java class 'com.mongodb.spark.sql.connector.MongoTableProvider'.

It looks like you've created Spark session without this option:
    SparkSession.builder.config("spark.jars.packages", MongoDB.package_spark_3_2)

Please call `spark.stop()`, restart the interpreter,
and then create new SparkSession with proper options.

  • Улучшения документации.

  • Изменена тема сайта документации - используется furo вместо темы по умолчанию ReadTheDocs.

    Новая тема поддерживает широкие экраны и темный режим. См. #10.

  • Теперь каждый класс подключения имеет таблицу совместимости для Spark + Java + Python.

  • Добавлена глобальная таблица совместимости для Spark + Java + Python + Scala.

Исправление ошибок

  • Исправлено несколько проблем с SFTP.

  • Если файл конфигурации SSH ~/.ssh/config содержит некоторые параметры, не распознаваемые Paramiko (неизвестный синтаксис, неизвестное имя параметра), предыдущие версии будут выбрасывать исключение до исправления или удаления этого файла. Начиная с версии 0.7.0 исключение заменено предупреждением.

  • Если пользователь передал host_key_check=False, но сервер изменил SSH ключи, предыдущие версии выдавали исключение до принятия нового люча. Начиная с версии 0.7.0 исключение заменено предупреждением, если значение параметра равно False.

    Исправлено в #19.

  • Исправлено несколько проблем с S3.

Была ошибка в подключении к S3, которая не позволяла обрабатывать файлы в корне бакета - они были невидимы для коннектора. Исправлено в #29.