py.lib.aw_db_tools

     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/db-migrator.md	Tue Feb 27 21:06:11 2024 +0300
     1.3 @@ -0,0 +1,83 @@
     1.4 +# db_migrator
     1.5 +
     1.6 +## Окружение
     1.7 +
     1.8 +Для обеспечения миграции должен быть развёрнут каталог с данными миграции и в БД присутствовать отношение, хранящее версию текущей схемы.
     1.9 +
    1.10 +Для организации миграции необходимо создать и поддерживать директорию определённой структуры:
    1.11 +
    1.12 +```yaml
    1.13 +- schema.sql: Файл с начальной схемой данных
    1.14 +  patch: # Каталог с изменениями
    1.15 +  - 0.sql
    1.16 +  - 1.sql
    1.17 +  # ...
    1.18 +```
    1.19 +
    1.20 +Схема таблицы с версией:
    1.21 +
    1.22 +```sql
    1.23 +CREATE TABLE app_version_info (
    1.24 +   version integer default -1
    1.25 +);
    1.26 +```
    1.27 +
    1.28 +Имя таблицы значения не имеет, так как задаётся при вызове класса миграции. Однако **схема должна** соответствовать.
    1.29 +
    1.30 +В методах принимающих `<tt class="remarkup-monospaced">db</tt>`, ему нужно передавать объект <tt class="remarkup-monospaced">connection</tt> `<tt class="remarkup-monospaced">DB API 2</tt>` стандартный для <tt class="remarkup-monospaced">Python</tt>.
    1.31 +
    1.32 +БД, за версией которой мы следим, естественно должна взаимодействовать посредством простого <tt class="remarkup-monospaced">SQL</tt>. Модуль не выполняет каких-то сложных манипуляций, а простым `<tt class="remarkup-monospaced">SELECT</tt>` запрашивает данные, и исполняет `<tt class="remarkup-monospaced">UPDATE</tt>` при обновлении данных о версии
    1.33 +
    1.34 +#### Структура файла схемы и файлов изменений
    1.35 +
    1.36 +Файл схемы должен состоять из отдельных команд на изменение схемы разделённых маркетом `<tt class="remarkup-monospaced">--</tt>`, который должен идти первым не пробельным символом. По данному маркеру происходит разбиение файла на отдельные команды. После этих символов содержание остальной строки игнорируется, а сама строка в команду не входит.
    1.37 +
    1.38 +Каждая команда исполняется отдельно и после её выполнения происходит <tt class="remarkup-monospaced">commit</tt>. Поэтому необходимо **внимательно** следить за согласованностью данных после применения команды.
    1.39 +
    1.40 +**Имена файлов изменений** должны оканчиваться на <tt class="remarkup-monospaced">.sql</tt> (регистр не важен) и первые символы до точки должны приводится к числу. Данное число будет версией, к торовой данный файл приводит схему.
    1.41 +
    1.42 +То есть имя файла рекомендуется составлять из 3-х компонентов, разделённых точками:
    1.43 +
    1.44 +```
    1.45 +00001.some_comment.sql
    1.46 +```
    1.47 +
    1.48 +**где:**
    1.49 +
    1.50 +- `<tt class="remarkup-monospaced">00001</tt>` - версия, количество нулей роли не играет
    1.51 +- `<tt class="remarkup-monospaced">some_comment</tt>` - пояснение к изменению, не является обязательным
    1.52 +- `<tt class="remarkup-monospaced">sql</tt>` - расширение файла, относящее его к <tt class="remarkup-monospaced">SQL</tt>.
    1.53 +
    1.54 +### Документация
    1.55 +
    1.56 +#### Классы
    1.57 +
    1.58 +<div class="remarkup-table-wrap" id="bkmrk-"></div><div class="remarkup-table-wrap" id="bkmrk-%D0%98%D0%BC%D1%8F-%D0%BA%D0%BB%D0%B0%D1%81%D1%81%D0%B0-%D0%9E%D0%BF%D0%B8%D1%81%D0%B0%D0%BD%D0%B8%D0%B5-"><div class="remarkup-table-wrap"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 21.3818%;"></col><col style="width: 78.5935%;"></col></colgroup><tbody><tr><th class="align-center" style="background-color: rgb(236, 240, 241); vertical-align: bottom;">**Имя класса**</th><th class="align-center" style="background-color: rgb(236, 240, 241); vertical-align: bottom;">**Описание**</th></tr><tr><td>`<tt class="remarkup-monospaced">MigrateManager</tt>`</td><td>Менеджер миграции. Выполняет всю работу</td></tr><tr><td>`<tt class="remarkup-monospaced">MigrateError</tt>`</td><td>Класс собственных исключений модуля</td></tr></tbody></table>
    1.59 +
    1.60 +</div></div>#### Методы класса `<tt class="remarkup-monospaced">MigrateManager</tt>`
    1.61 +
    1.62 +##### Конструктор
    1.63 +
    1.64 +**Параметры:**
    1.65 +
    1.66 +<table border="1" id="bkmrk-control_table-str-o-" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 14.953%;"></col><col style="width: 10.8749%;"></col><col style="width: 4.36944%;"></col><col style="width: 69.6543%;"></col></colgroup><tbody><tr><td>`<tt class="remarkup-monospaced">control_table</tt>`</td><td>`<tt class="remarkup-monospaced">str</tt>`</td><td>`<tt class="remarkup-monospaced">O</tt>`</td><td>Имя таблицы, хранящей версию (схема её дана выше)</td></tr><tr><td>`<tt class="remarkup-monospaced">migrate_env</tt>`</td><td>`<tt class="remarkup-monospaced">str(path)</tt>`</td><td>`<tt class="remarkup-monospaced">O</tt>`</td><td>Каталог с файлами миграции. Структура описана выше</td></tr></tbody></table>
    1.67 +
    1.68 +**Выполняет:** общие проверки среды, команд на БД не вызывает
    1.69 +
    1.70 +##### `<tt class="remarkup-monospaced">init_db</tt>`
    1.71 +
    1.72 +**Параметры:**
    1.73 +
    1.74 +<table border="1" id="bkmrk-db-%D0%9E%D0%B1%D1%8A%D0%B5%D0%BA%D1%82-%D0%91%D0%94-o-%D0%9E%D0%B1%D1%8A%D0%B5%D0%BA" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 7.78547%;"></col><col style="width: 11.6164%;"></col><col style="width: 4.44811%;"></col><col style="width: 76.1253%;"></col></colgroup><tbody><tr><td>`<tt class="remarkup-monospaced">db</tt>`</td><td>`<tt class="remarkup-monospaced">Объект БД</tt>`</td><td>`<tt class="remarkup-monospaced">O</tt>`</td><td>Объект БД, должен соответствовать описанному выше интерфейсу</td></tr></tbody></table>
    1.75 +
    1.76 +**Выполняет:** Исполнение на БД команд из файла начальной схемы
    1.77 +
    1.78 +##### `<tt class="remarkup-monospaced">check</tt>`
    1.79 +
    1.80 +**Параметры:**
    1.81 +
    1.82 +<table border="1" id="bkmrk-db-%D0%9E%D0%B1%D1%8A%D0%B5%D0%BA%D1%82-%D0%91%D0%94-o-%D0%9E%D0%B1%D1%8A%D0%B5%D0%BA-1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 4.81957%;"></col><col style="width: 12.4815%;"></col><col style="width: 4.50132%;"></col><col style="width: 78.0493%;"></col></colgroup><tbody><tr><td>`<tt class="remarkup-monospaced"></tt>db`</td><td>`Объект БД`</td><td>`O`</td><td>Объект БД, должен соответствовать описанному выше интерфейсу</td></tr></tbody></table>
    1.83 +
    1.84 +**Выполняет:** Проверку версию схемы БД, и исполнение на БД команд из файлов версий выше текущей на БД.
    1.85 +
    1.86 +<p class="callout warning">При отсутствии таблицы модуль просто возбудит исключение, причём это исключение возбудит сама база, поскольку запрошенной таблицы в ней не окажется.</p>
    1.87 \ No newline at end of file