Notes

CODE-BASED ПОДХОД -->

1. Все миграциии оформляются в виде отдельных class-файлов и оформляются по след. шаблону (наследуемся от базового класса Migration):

[Migration(20200506201231)] //yyyyMMddhhmmss
public class issue_777_Description_Migration: Migration
{
public override void Apply() //Абстрактный метод. Обязателен для определения.
{
//Пишем свой код выполнения sql-скриптов
}

public override void Revert() //Виртуальный метод. можно НЕ переопределять, если откат изменений НЕ нужен.
{
//Опциональный код отката данной миграции
}
}

Примечание:
Путем внедрения новых атрибутов можем эффективно связывать декларативную информацию контекста выполнения миграций с нашим кодом.
Например:
- [Tags("Staging", "Production", "QA", "Development")] - указываем в каком окружении должна выполняться данная миграция.
- [Profile("v3.11")] - определяем версию сборки софта ФИАС, с которой поставляется данная миграция. Инкрементальная версия sql-миграции (aka точечное изменение состояния/структуры БД) и выпускаемая версия софта - не одно и тоже.
- [Owner("Компания", "Автор/Разработчик")] - GNIVC/STG/Rucore
- TransactionBehavior: Transaction-Per-Migration/Transaction-Per-Session/TransactionBehavior.None --> [Migration(20200506201231, TransactionBehavior.None)]. Default - per migration.
p.s.: благо PostgreSQL поддерживает Transactional DDL.

_______________________________________________________________________________
2. Миграции можно выполнить при помощи консольного приложения и через API.

а). Для консольного приложения можем указать дополнительные(необязательные) аргументы:
--list - вывести список доступных миграций, не выполняя их.
--version - целевая версия БД. Значение по умолчанию - '-1' (обновить БД до последней доступной версии)
--timeout - таймаут на выполнение SQL запросов (в секундах).
--verbose - выводить в консоль текст выполняемых SQL запросов.
-? | -h | --help - вывести справку.


б). Используя API сможем запускать по условию проесс миграции при старте/инициализации нашего веб-приложения. Условие можно задать через ASPNETCORE_ENVIRONMENT либо конфиг-ключ.
Это будет особенно полезно после того как внедрим dev/test-окружение с docker-контейнерами.

_______________________________________________________________________________
3. sql-скрипты миграций можно хранить как Embedded Resource либо обособленно на файловой системе. Что касается подхода со "встроенными скриптами" их можно вынести в отдельную class library, а не в рамках console application.
Плюсы Embedded Resource на рассмотрение:
- Можем легко использовать как часть automated deployment
- Можем запускать во время интеграционных тестов, при их наличии.
- Т.к. скрипты будут включены в VS-Solution они будут автоматически подпадать под контроль версий TFS/GitLab.

_______________________________________________________________________________
5. Факт выполнения миграций будет фиксироваться в т.н. реестре миграций. Таблицу создаем в БД fias_admin_log в новой схеме.
Cтруктура таблицы:
- Ид записи (поле installed_rank)
- Уникальная версия sql-миграции (см. атрибут "Migration" выше) (поле sql_migration_version)
- Описание/Имя класса миграции
- Версия ПО ФИАС, с которой поставляется данная миграция (см. атрибут "Profile") (software_version)
- Дата выполнения (поле installed_on)
- Время выполнения (поле execution_time)
- Собственник/Автор (поле owner) (см. атрибут Owner)
- База данных, к которой применена sql-миграция (поле database)

Примечание:
Вопрос. Реестр версий БД будем вести в одной таблице, без разделения на конкретные БД?

_______________________________________________________________________________
6. Дополнительно:
- Внутри проекта migration-сборки можем произвести разделение на подкаталоги GNIVC/STG/RuCore. Либо обозначать факт принадлежности декларативно через атрибут.
- Проект мигратора включаем в основной VS-Solution ФИАС.
- ДАННЫЙ ПОДХОД НЕ ПРЕДУСМАТРИВАЕТ ПОВТОРНОГО НАКАТА ОДНОЙ И ТОЙ ЖЕ МИГРАЦИИ С ПЕРЕЗАПИСЬЮ ПРЕДЫДУЩЕГО ВЫПОЛНЕНИЯ. Без ручного вмешательства конечно же.
- OutOfOrder == true (Allows migrations to be run "out of order". If you already have versions 1 and 3 applied, and now a version 2 is found, it will be applied too instead of being ignored.)