@nfjs/migrate
Advanced tools
Database migration tool
ОГЛАВЛЕНИЕ
Инструмент, позволяющий провести обновление схемы базы данных установленного приложения из исходников, сохраненных разработчиком в соотвествующие папки каждого модуля(пакета) системы.
Находятся в папках ./dbsrc модулей. Для каждой схемы бд создается под-папка ./имясхемы.
!> Важно, что схема может быть только в одном из пакетов приложения. И в данный момент при добавлении новой схемы бд в приложение нужно
вручную создать в необходимом модуле папку с именем схемы и внутри неё под-папки dat, src, mig.
Хранятся в под-папке ./dbsrc/src и дальше по типам объектов
Хранятся в под-папках ./dbsrc/mig/год-месяц. Разбиваются по месяцам для того чтобы папки не были по истечении
времени перегружены количеством файлов. Миграции используются для случаев, когда нужно провести операции, которые
не может сделать библиотека генерации изменений таблиц, команды изменения данных.
Миграции могут быть разделены на блоки строками вида --[block]{"event":"run","when":"before"} в которых описано к
какому типу событию (event) они относятся и когда (when) их выполнять.
!> Нельзя управлять в скрипте миграции глобальной транзакцией — весь процесс обновление проходит в одной транзакции.
Хранятся в под-папках ./dbsrc/dat/имя_таблицы_данных/. Это набор данных таблицы, с которым будет синхронизированы данные в таблице на целевой базе обновления.
Используются как правило три файла для каждой таблицы:
data.json подготовленные и выгруженные по eSch.json схеме данные таблицыiSch.json схема импорта данных из data.json в бд. Применяется при обновлении на целевой базе.eSch.json схема экспорта из бд, где подготавливаются данные к обновлению, в data.json. Используется разработчиком при подготовке исходниковДля
nfc.modulelist-iSch.jsonиeSch.jsonрасположены в модуле инструмента в папке./data_schemas.
Выгрузка и загрузка данных происходит с помощью модуля @nf/ei, подробное описание в readme.md модуля.
Данному инструменту нужны сами данные data.json и iSch.json по ним готовится массив sql вида insert on conflict do update для каждой записи таблицы и зависимых при наличии.
Для этого все схемы iSch.json используют extract часть типа json и load типа execSqlArray.
При старте приложения, в зависимости от настройки модуля @nf/migrate.doMigrate (или соотвествующего параметра командной строки), запускается проверка необходимости применения изменений
в подключенный провайдер с именем default под пользователем, указанном в настройке @nf/migrate.data_providers.default.checkUserName. Для этого
public.nf_migrations и public.nf_objects и если есть, то достается информация из них.onlySchemas, оставляются только указанные.public.nf_migrations.doSilent = false. Для doSilent = true выполняется то же самое,
только не запрашиваются значения переменных от запустившего процесс обновления, а берутся из соответствующих ключей конфига или переменных командной строкиВыполнение блоков миграции для прогона перед сравнением объектов: event = run, when = before.
Например, переименование колонки, сложные настройки таблиц\индексов не поддерживаемые инструментом сравнения
Для файлов исходников, помеченных к применению, запускается генерация блоков скриптов изменений. Блоки:
safedrop безопасное удаление объекта, которое не повлечет потерю данных. В том числе и временные удаления
с последующим созданием обновленной версии объекта для решения проблем с зависимостями объектов друг от друга. Примечание для ключей, ограничений, индексов таблиц - полному удалению подлежат только если имена соответствуют
рекомендациям наименований, остальные не трогаются, чтобы на конкретном стенде можно было добавить индекс по усмотрению
компетентного сотрудника и он не удалился при обновлении.unsafedrop небезопасное, как удаление колонки, сейчас собираются, но не применяются по-умолчанию. Будет отдельный запрос от пользователя на выполнение этих блоков (не рекомендуется)main основные изменения колонок таблиц и полное создание таблиц. Если есть изменение типа колонки, то производится поиск зависимых от этого поля представлений и, если
эти представления не поменяли свой код, то насильно добавляется их пересозданиеfunc создание\пересоздание функцийtrig создание триггеровview создание представлений отсортированных в порядке зависимости друг от другаpkey создание первичных и уникальных ключей. Отдельно чтобы из следующего блока внешние ключи не нужно было упорядочивать по зависимостямend отложенные на конец обновления объекты, ограничения таблиц, внешние ключиПрименение
main, func, trig, view, pkeyendОтметка всех поучаствовавших объектов, миграций, данных в таблицах инструмента
Проверка начальной инициализации приложения (записи в системных справочниках пользователей, ролей) и если всё пусто, то будет запрос на инициализацию с просьбой указать имя первого администратора приложения, его пароль и имя первой роли, которой выдастся минимальный набор привилегий для дальнейшей настройке. Пользователь администратора приложения создается в соотвестии с режим работы провайдера данных default - если в режиме user, то будет создан соотвествующий пользователь в postgresql, с назначенной ролью nfusr, а иначе только запись в nfc.users.
Завершение работы в зависимости от выбранного режима (runType).
В основном файле настроек config.json приложения добавить ключ @nf/migrate
"@nf/migrate": {
"doMigrate": true,
"doSilent": false,
"сheckType": "simple",
"defaultRunType": "r",
"defaultDoUnsafeDrop": false,
"data_providers": {
"default": {
"checkUserName": "nfusr",
"checkUserPassword": "nfusrpass",
"adminUserName": "nfadm",
"adminUserPassword": "nfadmpass",
"superUserName": "postgres",
"superUserPassword": "postgrespass"
}
},
"defaultDoInit": {
"need": true,
"appAdminName": "admin",
"appAdminPassword": "adminpass"
}
},
Также поддерживается режим обновления из командной строки
node index --domigrate=true --migrate-do-silent=false --migrate-run-type=t
| Параметр | Тип | Назначение | Параметр командной строки |
|---|---|---|---|
doMigrate | boolean | Запускать процесса обновлениея бд при старте приложения | domigrate |
doSilent | boolean | Проводить процесс обновления только на значениях по-умолчанию, не запрашивая ничего. Применяется для автоматического обновления | migrate-do-silent |
checkType | string | Способ проверки необходимости выполнения обновления объектов и данныхsimple - проверка по хешам, сохраненным в public.nf_objectsforce - все объекты из исходников сравниваются с бд | migrate-check-type |
defaultRunType | string | Режим запуска при doSilent = truer - выполнение в бдt - тестирование в бдf - вывод полного скрипта обновления в файлv - вывод полного скрипта обновления в консоль | migrate-run-type |
defaultDoUnsafeDrop | boolean | Выполнять блок unsafedrop из сравнения таблиц или нет. Учитывается только при doSilent = true | migrate-do-unsafe-drop |
data_providers.default | Object | Указывается провайдер базы данных, в котором нужно применять обновление | |
.checkUserName | string | Имя пользользователя под которым проверяется необходимость применения обновления | migrate-check-user-name |
.checkUserPassword | string | Пароль пользользователя под которым проверяется необходимость применения обновления | migrate-check-user-password |
.adminUserName | string | Имя пользользователя под которым проводится обновление | migrate-admin-user-name |
.adminUserPassword | string | Пароль пользользователя под которым проводится обновление | migrate-admin-user-password |
onlySchemas | Array | Ограничивающий перечень схем базы данных для которых выполнять обновление | migrate-only-schemas |
grantAllFunction | string | Имя функции для назначения прав на объекты после обновления. По-умолчанию nfc.f_db8grant_all | migrate-grant-all-function |
defaultDoInit | Object | Настройки проведения инициализации платформенного пользователя-администратора, организации и минимально необходимых прав у администратора для дальнейшей настройки системы | |
.need | boolean | Признак необходимости инициализации | migrate-do-init |
.appAdminName | string | Имя пользователя-администратора | migrate-do-init-app-admin-name |
.appAdminPassword | string | Пароль пользователя-администратора | migrate-do-init-app-admin-password |
.appAdminRole | string | Имя первой роли, которой будут даны минимальные права для дальнейшей настройки приложения | migrate-do-init-app-admin-role |
!> При передаче параметров через командную строку параметры типа boolean можно передать в виде строк y,Y,true,t.
А массивы строк в виде строки с разделителем ;
!> Важно. Для обеспечения защиты от случайных обновлений объектов базы данных желательно иметь отличные пароли
проверяющего пользователя checkUserPassword на разных базах.
FAQs
Database migration tool
We found that @nfjs/migrate demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
An emerging npm supply chain attack that infects repos, steals CI secrets, and targets developer AI toolchains for further compromise.
Company News
Socket is proud to join the OpenJS Foundation as a Silver Member, deepening our commitment to the long-term health and security of the JavaScript ecosystem.
Security News
npm now links to Socket's security analysis on every package page. Here's what you'll find when you click through.