Skip to content

Latest commit

 

History

History
161 lines (116 loc) · 11.3 KB

README.ru.md

File metadata and controls

161 lines (116 loc) · 11.3 KB
Raw

Утилиты командной строки dbang, v0.2

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

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

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

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

Утилиты dbang

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

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

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

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

Чтобы познакомиться с опциями той или иной утилиты, запустите ее с опцией --help.

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

ddiff.py ddiff-test-sqlite
dtest.py dtest-test
dget.py dget-test
dput.py dput-test-sqlite all

При запуске dput нужно обязательно указать спецификацию, и опционально – имя загружаемого файла с расширением .csv, .xlsx или .json. По умолчанию имя файла для загрузки берется из спецификации, и файл ищется в директории in, если в конфиг-файле не указано иначе.

Прежде чем запустить hedwig.py с тестовым конфиг-файлом hedwig-test.py, присвойте правильные значения переменной MAIL_SERVER и словарным (dict) элементам to в конфиг-файле. После этого выполните команду

hedwig.py hedwig-test

и проверьте входящую почту.

Тестовые конфиг-файлы используют sqlite БД, описанную в файле cfg/sources.py как источник данных с именем "sqlite-source". Для выполнения тестовых конфиг-файлов с другими СУБД отредактируйте параметры подключения для источников "oracle-source", "postgres-source" или "mysql-source" и используйте выбранный источник в конфиг-файле.

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

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

Источники данных

Источники данных, или БД, с которыми работают утилиты, определяются в файле cfg/sources.py в словаре (dict) sources.

Пример:

import os
import sys

sources = {
    "sqlite-source": {
        "database": "sqlite",
        "con_string": os.path.join(os.path.dirname(os.path.realpath(sys.argv[0])), f'.dbang.db')
    },
    "postgres-source": {
        "database": "postgres",
        "con_string": "postgresql://username:password@host/database"
        "setup": ["set timezone=\'Asia/Vladivostok\'"]
    },
    "oracle-source": {
        "database": "oracle",
        "con_string": "username/password@host:1521/ORA",
        "con_kwargs": {"encoding": "UTF-8"},
        "setup": ["ALTER SESSION SET TIME_ZONE = '+10:00'"]
    },
    "mysql-source": {
        "database": "mysql",
        "con_string": "",
        "con_kwargs": {'host': 'host', 'database': 'database', 'user': 'username', 'password': 'password'},
        "setup": ["create table if not exists test_table (id int, name varchar(50))"],
        "upset": ["drop table if exists test_table"]
    },
}

Каждый источник данных описывается параметрами:

  • "database" - вид СУБД, одно из: "sqlite", "postgres", "oracle", "mysql", используется для выбора Python модуля для работы с БД;
  • "con_string" - строка присоединения к БД, используется при вызове функции <модуль>.connect();
  • "con_kwargs" - необязательный словарь (dict) именованных аргументов, используется при вызове функции <модуль>.connect();
  • "setup" - необязательный список (list) строк с предложениями SQL, которые однократно выполняются сразу после установления соединения с БД;
  • "upset" - необязательный список (list) строк с предложениями SQL, которые однократно выполняются перед закрытием соединения с БД.

Структура конфиг-файлов

Конфиг-файлы улитит dbang, за исключением hedwig, имеют следующую структуру:

import os
import sys

from sources import sources

#
# MANDATORY constants used by the utility
#
OUT_DIR = os.path.join(os.path.dirname(os.path.realpath(sys.argv[0])), 'out')

#
# Optional constants used in specs below
#
# ...

specs = {
    "<spec_1>": {
        "source": "<source_1>",
        ...
    },
    "<spec_2>": {
        "source": "<source_2>",
        ...
    },
}

sources['source_1']['setup'] = sources['source_1'].get('setup', []) + [
    "<SQL statement>"
]

sources['source_2']['setup'] = sources['source_2'].get('setup', []) + [
    "<SQL statement>"
]

В конфиг-файлах для hedwig не импортируются и не используются определения источников данных из sources. В остальном стуркутра конфиг-файлов такая же.

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

За блоком обязательных констант идет (опционально) блок пользовательских констант. Если в спецификациях приходится неоднократно использовать одни и те же выражения, то удобно определить их как константы и использовать в спецификацих имена констант вместо выражений.

Словарь (dict) specs содержит спецификации, которые сами являются словарями. Перечень параметров в спецификациях разных утилит и комментарии к ним см. в тестовых конфиг-файлах.

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

Как работают утилиты