dbang! Утилиты для работы с БД

Написанные на Python, утилиты dbang позволяют существенно сэкономить усилия при решении типичных задач, связанных с БД:

• ddiff.py - выполняет запросы к двум БД и формирует отчет о расхождениях;
• dtest.py - выполняет запросы к БД и формирует отчет о найденных проблемах;
• dget.py - выгружает данные из БД в файлы csv, xlsx или html;
• dput.py - загружает данные из файлов csv или xlsx в таблицы БД;
• hedwig.py - на основе файлов создает и отправляет е-мейл.

Утилиты могут работать с СУБД Oracle, PostgreSQL, SQLite и MySQL.

ddiff и dtest предназначены для оценки логической полноты и целостности данных в БД.

dget и dput выгружают и загружают данные из/в БД согласно спецификациям в конфиг-файлах.

Утилиты dbang

• используют конфигурационные файлы из директории cfg,
• пишут лог-файлы в директорию log,
• читают файлы для загрузки в БД из директории in (если не указано иначе в конфиг-файле),
• и сохраняют результаты работы в директории out (если не указано иначе в конфиг-файле).

dbang/
    cfg/
        # config-files
        ...
        ddiff-test.py
        dget-test.py
        dput-test.py
        dtest-test.py
        hedwig-test.py
        sources.py
    in/
        # files to load into DB
        ...
        test.csv
        test.xlsx
    log/
        # utilities' log files
        ...
    out/
        # output files
        ...
        test.txt
        test.html
    ddiff.py
    dget.py
    dput.py
    dtest.py
    hedwig.py

Утилиты запускаются командной строкой

<name>.py <cfg-file> [<spec> | all]

где <cfg-file> - имя конфиг-файла, а <spec> - имя спецификации в конфиг-файле. Если <spec> не указано, то выполняются все спецификации из конфиг-файла.

Запустите утилиты с тестовыми конфиг-файлами и посмотрите результаты в директории out:

ddiff.py ddiff-test
dtest.py dtest-test
dget.py dget-test
dput.py dput-test test_sqlite

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

Подробнее об утилитах dbang см. страничку с документацией на gitgub.

ddiff. Эффективное сравнение данных в разных БД

См. мой пост ddiff. Эффективное сравнение данных в разных БД.

Пример отчета о расхождениях:

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

Подробнее об утилите ddiff см. страничку с документацией на gitgub.

Вы можете настроить запуск утилиты ddiff по расписанию (с помощью crontab в Linux или Планировщика заданий в Windows) с последующей рассылкой сформированного отчета по электронной почте (с помощью утилиты hedwig, см. далее).

dtest. Тестирование качества данных в БД

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

-- убедиться, что точка с запятой отсутствует в названиях

select * 
from items 
where name like '%;%'
;
no rows

-- убедиться, что счетчик позиций в заголовке совпадает с числом позиций

select * 
from header h
where pos_count != (
    select count(*) from positions p where p.header_id = h.header_id
    )
;
no rows

Если запрос не возвращает ничего, это хорошой результат.

Если запрос возвращает одну или больше строк данных, значит, правило нарушено и данные требуется скорректировать.

Утилита dtest выполняет запросы к БД, указанные в спецификациях конфиг-файла, и формирует отчет о результатах тестирования качества данных в файле формата html.

Пример отчета:

Подробнее об утилите dtest см. страничку с документацией на gitgub.

Вы можете настроить запуск утилиты dtest по расписанию (с помощью crontab в Linux или Планировщика заданий в Windows) с последующей рассылкой сформированного отчета по электронной почте (с помощью утилиты hedwig, см. далее).

dget. Выгрузка данных в файлы

Утилита dget выгружает из БД данные в файлы форматов csv, xlsx или html согласно спецификации в конфиг-файле.

Кейс 1. Изо дня в день в ИТ подразделение обращаются из других подразделений с просьбами выгрузить из БД в файл Excel

• все товары категории Обувь сезона весна-лето 23,
• все товары со специальными условиями перевозки,
• новые товары, введенные за последний месяц,
• новые товары, за которые отвечает менеджер Иванова,
• и т.п.

Эти и другие подобные запросы можно удовлетворить одной-единственной выгрузкой товаров, включающей все востребованные атрибуты: категория, сезон, условия перевозки, дата ввода товара, менеджер. Достаточно периодически выгружать данные в файл, доступный заинтересованным лицам.

Специалист, которому нужен список всех товаров категории Обувь сезона весна-лето 2023, просто откроет файл Excel и отфильтрует строки по столбцам "Категория" и "Сезон". И другие пользователи поступят аналогично.

Кейс 2. Выгрузка из БД результатов запроса в формате html для их отправки адресатам в виде таблички в теле электронного письма.

Это могут быть ошибки, зарегистрированные в журнальной таблице за последний час, или периодический отчет, или уведомление о наступлении некоторого события/выполнении условия, которое требует реакции от пользователей. Отправка адресатам письма с данными из html-файла делается с помощью утилиты hedwig, см. далее.

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

Подробнее об утилите dget см. страничку с документацией на gitgub.

dput. Загрузка данных из файлов в БД

Загрузка данных из файла в БД обычно предполагает:

• проверку данных из файла на соответствие требованиям,
• размещение данных в таблицах БД, для которых они предназначены.

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

Утилита dput

• загружает данные из файла csv или xlsx в интерфейсные таблицы ida и ida_lines в БД, указанной в спецификации;
• выполняет запросы к БД из спецификации для проверки соответствия данных, загруженных в ida_lines, требованиям;
• если проверка успешна, выполняет запросы к БД из спецификации для переноса данных из ida_lines в целевые таблицы;
• если проверка не успешна, пишет в лог-файл сообщения об ошибках, сформированные в ходе проверки.

Данные, загружаемые в БД через интерфейсные таблицы ida и ida_lines, по умолчанию не сразу удаляются из этих таблиц. Это может быть полезно в случаях, когда нужно проверить, какие данные были загружены пользователями ранее и/или какие ошибки были найдены при их обработке.

Подробнее об утилите dput см. страничку с документацией на gitgub.

Кроме того, в тестовом конфиг-файле dput-test.py вы найдете комментарии к каждому из параметров спецификации. Познакомьтесь с ними, чтобы составить исчерпывающее представление обо всех параметрах и их назначении.

hedwig. Формирование и отправка е-мейлов

Утилита hedwig умеет формировать элекронные письма и отправлять их адресатам, согласно спецификации в конфиг-файле. Письма могут быть как текстовые (text/plain), так и в формате html (text/html), и могут содержать прикрепленные файлы.

Основное назначение hedwig состоит в отправке по почте файлов, созданных утилитами ddiff, dtest, dput. (Само собой, можно отправлять и файлы, созданные другими средствами.) Если файл уже был отправлен, то повторное выполнение спецификации не приводит к его повторной отправке – hedwig запоминает время модификации отправленного файла и отправит его снова только после его обновления.

Подробнее об утилите hedwig см. страничку с документацией на gitgub.

Настройте запуск утилиты hedwing по расписанию (с помощью crontab в Linux или Планировщика заданий в Windows) для рассылки отчетов о расхождениях (ddiff), отчетов о качестве данных (dtest) или произвольных выгруженных из БД данных (dget).