Приложение для работы с базой данных ГАР в Django

Основные возможности
====================

* Импорт базы ГАР из:
    * архива XML
    * каталога с XML
    * напрямую с сайта http://fias.nalog.ru в формате XML
* Импорт всех существующих справочников и классификаторов ГАР (с возможностью выборочного импорта)
* Возможность хранить данные в отдельной БД

Совместимость
=============

* Гарантируется работа на Django 3.2 и Python 3.9

Описание ключей командной строки (./manage.py gar_load_data)
============================================================


--src <path|filename|url|auto>
    Путь до архива с БД ГАР, каталога, в который предварительно был распакован архив или URL-адрес, с которого требуется скачать импортируемый архив
    Значение `auto` означает автоматическое получение данных с сайта http://fias.nalog.ru

--truncate
    Указывает полностью удалять все данные из таблицы перед импортом в неё

--update
    Обновляет БД ГАР до актуальной версии (после импорта)

--limit
    Устанавливает размер пачки записей, единовременно загружаемой в БД
    Чем больше размер, тем быстрее импорт (в теории), но дольше обработка ошибок, если таковые возникнут
    По-умолчанию: 10000

--tables
    Задаёт список таблиц для импорта через запятую

--update-version-info, --no-update-version-info
    Указывает, обновлять ли список версий БД ГАР
    По-умолчанию: True

--tempdir TEMPDIR
    Путь к каталогу, где будут размещены временные файлы в процессе импорта
    Каталог должен существовать и быть доступен для записи


Установка
=========

1. Установите `m3-gar`::

        pip install m3-gar

2. Добавьте `m3_gar` в `INSTALLED_APPS`.

5. Если вы желаете использовать отдельную БД под данные ГАР, выполните следующее

* Создайте БД и подключите её в `DATABASES`
* Добавьте параметр::

        GAR_DATABASE_ALIAS = 'gar'

где `gar` - алиас БД в `DATABASES`

* Добавьте в список `DATABASE_ROUTERS`::

        m3_gar.routers.GARRouter

* Выполните::


        python manage.py migrate --database=gar

где `gar` - алиас БД в `DATABASES`

5. Выполните::

        python manage.py migrate


Импорт данных
=============

Расшифровка сокращений
----------------------
* T: Table (Таблица) - импортируемая в данный момент таблица
* L: Loaded (Загружено) - количество уже загруженных в таблицу строк
* U: Updated (Обновлено) - количество обновлённых записей
* FN: Filename (Имя файла) - имя файла импортируемой таблицы

Первоначальная загрузка данных
------------------------------
Существует несколько способов импортировать данные в БД ГАР

Полностью автоматический импорт с сайта ФИАС::

        python manage.py gar_load_data --src auto

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

        # Архив с XML-файлами
        python manage.py gar_load_data --src /path/to/gar_xml.zip
        # Каталог с распакованным содержимым архива
        python manage.py gar_load_data --src /path/to/gar_data/

**Но!**
В случае, если в БД уже есть какие-то данные, скрипт выдаст соответствующее сообщение и прекратит работу.
Такое поведение связано с тем, что при импорте из файла, если версия файла не совпадает с версией данных в какой-то таблице в БД ГАР,
данные в этой таблице могут быть удалены полностью и заменены новыми, при этом
ORM Django при наличии связанных таблиц удалит данные так же и оттуда.
Поэтому, если по этой или какой-то иной причине нужно импортировать всю БД ГАР заново, добавьте флаг *--truncate*::

        python manage.py gar_load_data --src /path/to/gar_xml.zip --truncate

Если скачанный файл не актуален, можно добавить к указанной выше команде флаг *--update* - скрипт сразу после импорта обновит БД до актуальной версии.::

        python manage.py gar_load_data --src /path/to/gar_xml.zip --update


Обновление существующей БД
--------------------------
Для обновления БД выполните::

        python manage.py gar_load_data --update

Обновление выполняется только с сайта ФИАС. Обновить базу из файла нельзя.


Обновление схемы данных
=======================

Для обновления схемы данных ГАР предоставлена команда `gar_update_schema`

--url
    URL-адрес, с которого требуется скачать архив со схемами в формате XSD

--path
    Путь до уже скачанного архива

--testmode
    Указывает полностью удалять все данные из таблицы перед импортом в неё


Настройка settings.py
=====================
`GAR_DATABASE_ALIAS` - алиас БД в `DATABASES` для данных ГАР
