py.lib.aw_db_tools

Yohn Y. 2024-11-01 Parent:4b0d10bfa023

3:fd7d3b38860e Go to Latest

py.lib.aw_db_tools/docs/db-migrator.md

.. 0.202411.1 . Подгонка под новые веяния SDK . Исправление опечаток.

Download raw file
View source Diff to previous Annotate
History
awgur@0 1 # db_migrator
awgur@0 2
awgur@0 3 ## Окружение
awgur@0 4
awgur@0 5 Для обеспечения миграции должен быть развёрнут каталог с данными миграции и в БД присутствовать отношение, хранящее версию текущей схемы.
awgur@0 6
awgur@0 7 Для организации миграции необходимо создать и поддерживать директорию определённой структуры:
awgur@0 8
awgur@0 9 ```yaml
awgur@0 10 - schema.sql: Файл с начальной схемой данных
awgur@0 11 patch: # Каталог с изменениями
awgur@0 12 - 0.sql
awgur@0 13 - 1.sql
awgur@0 14 # ...
awgur@0 15 ```
awgur@0 16
awgur@0 17 Схема таблицы с версией:
awgur@0 18
awgur@0 19 ```sql
awgur@0 20 CREATE TABLE app_version_info (
awgur@0 21 version integer default -1
awgur@0 22 );
awgur@0 23 ```
awgur@0 24
awgur@0 25 Имя таблицы значения не имеет, так как задаётся при вызове класса миграции. Однако **схема должна** соответствовать.
awgur@0 26
awgur@0 27 В методах принимающих `<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>.
awgur@0 28
awgur@0 29 БД, за версией которой мы следим, естественно должна взаимодействовать посредством простого <tt class="remarkup-monospaced">SQL</tt>. Модуль не выполняет каких-то сложных манипуляций, а простым `<tt class="remarkup-monospaced">SELECT</tt>` запрашивает данные, и исполняет `<tt class="remarkup-monospaced">UPDATE</tt>` при обновлении данных о версии
awgur@0 30
awgur@0 31 #### Структура файла схемы и файлов изменений
awgur@0 32
awgur@0 33 Файл схемы должен состоять из отдельных команд на изменение схемы разделённых маркетом `<tt class="remarkup-monospaced">--</tt>`, который должен идти первым не пробельным символом. По данному маркеру происходит разбиение файла на отдельные команды. После этих символов содержание остальной строки игнорируется, а сама строка в команду не входит.
awgur@0 34
awgur@0 35 Каждая команда исполняется отдельно и после её выполнения происходит <tt class="remarkup-monospaced">commit</tt>. Поэтому необходимо **внимательно** следить за согласованностью данных после применения команды.
awgur@0 36
awgur@0 37 **Имена файлов изменений** должны оканчиваться на <tt class="remarkup-monospaced">.sql</tt> (регистр не важен) и первые символы до точки должны приводится к числу. Данное число будет версией, к торовой данный файл приводит схему.
awgur@0 38
awgur@0 39 То есть имя файла рекомендуется составлять из 3-х компонентов, разделённых точками:
awgur@0 40
awgur@0 41 ```
awgur@0 42 00001.some_comment.sql
awgur@0 43 ```
awgur@0 44
awgur@0 45 **где:**
awgur@0 46
awgur@0 47 - `<tt class="remarkup-monospaced">00001</tt>` - версия, количество нулей роли не играет
awgur@0 48 - `<tt class="remarkup-monospaced">some_comment</tt>` - пояснение к изменению, не является обязательным
awgur@0 49 - `<tt class="remarkup-monospaced">sql</tt>` - расширение файла, относящее его к <tt class="remarkup-monospaced">SQL</tt>.
awgur@0 50
awgur@0 51 ### Документация
awgur@0 52
awgur@0 53 #### Классы
awgur@0 54
awgur@0 55 <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>
awgur@0 56
awgur@0 57 </div></div>#### Методы класса `<tt class="remarkup-monospaced">MigrateManager</tt>`
awgur@0 58
awgur@0 59 ##### Конструктор
awgur@0 60
awgur@0 61 **Параметры:**
awgur@0 62
awgur@0 63 <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>
awgur@0 64
awgur@0 65 **Выполняет:** общие проверки среды, команд на БД не вызывает
awgur@0 66
awgur@0 67 ##### `<tt class="remarkup-monospaced">init_db</tt>`
awgur@0 68
awgur@0 69 **Параметры:**
awgur@0 70
awgur@0 71 <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>
awgur@0 72
awgur@0 73 **Выполняет:** Исполнение на БД команд из файла начальной схемы
awgur@0 74
awgur@0 75 ##### `<tt class="remarkup-monospaced">check</tt>`
awgur@0 76
awgur@0 77 **Параметры:**
awgur@0 78
awgur@0 79 <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>
awgur@0 80
awgur@0 81 **Выполняет:** Проверку версию схемы БД, и исполнение на БД команд из файлов версий выше текущей на БД.
awgur@0 82
awgur@0 83 <p class="callout warning">При отсутствии таблицы модуль просто возбудит исключение, причём это исключение возбудит сама база, поскольку запрошенной таблицы в ней не окажется.</p>