- Интеграция Spec Kit для pi: команды `/speckit.*`, bash-скрипты и шаблоны в `.specify` - Конституция JT4D v1.0.0 вместо шаблона: принципы WELD для слоёв web и api, публичный API директории - Слои web описаны по методологии WELD и проверяются `eslint-plugin-weld` - Vitest в api запускает `*.test.ts` рядом с `*.spec.ts`, тесты исключены из сборки приложения - `yarn.lock` пересобран через `yarn deduplicate` Нужно зафиксировать архитектуру проекта в конституции JT4D v1.0.0 и подключить Spec Kit, чтобы планировать фичи до написания кода. - `eslint-plugin-weld` настроен только в `apps/web`: схема слоёв API описана конституцией и документацией, но линтером пока не проверяется Reviewed-on: jt4d/jt4d#4 Co-authored-by: Arswarog <arswarog@yandex.ru>
30 KiB
Миграции базы данных
Миграции TypeORM применяются автоматически при деплое — и на проде (на каждый тег), и на
стейджинге (на каждый push/PR); деплой падает, если миграция не прошла. См.
База и переменные .env на стейджинг-хосте.
⚠️ Перед первым прод-деплоем убедитесь, что aigeo_app имеет права на DDL и что таблица
migrations согласована со схемой — см. Права на БД. Автоматического бэкапа перед
миграцией нет.
Схема БД в рантайме не синхронизируется: synchronize: false, migrationsRun: false. Единственный
способ изменить схему — миграция.
Как писать саму миграцию (API QueryRunner, down, data-миграции) —
Написание миграций.
Как это устроено
Webpack не умеет runtime-glob: запись migrations: ['*.js'] внутри бандла не работает в принципе.
Поэтому список миграций генерируется статически на этапе сборки.
-
Кодогенерация.
tools/buildDataSource.tsсканируетapps/api/src/**/migrations/*.ts(миграции лежат по модулям —apps/api/src/<module>/migrations/), вытаскивает имена экспортируемых классов и пишетapps/api/src/migrations.tsсо статическими импортами. Сортировка — по числовому timestamp из имени файла (возрастание) независимо от модуля. Результат прогоняется через Prettier внутри генератора и коммитится в репозиторий. -
Единый DataSource.
apps/api/src/config/typeorm.config.tsберётmigrationsиз сгенерированного файла. Один и тот же файл работает локально черезtypeorm-ts-node-commonjsи в собранном виде внутри контейнера. -
Отдельный бандл.
apps/api/webpack.data-source.config.jsсобираетdata-source.jsв тот жеapps/api/dist, что иmain.js(output.clean: false, иначе затрёт основной бандл). В образе оба файла лежат в/appрядом сnode_modules.⚠️ Попадание
distв образ держится на том, чтоapps/api/.dockerignoreотсутствует: контекст сборки —apps/api, а правило**/distиз корневого.dockerignoreпри наличии локального файла перестало бы игнорироваться (docker берёт.dockerignoreиз корня контекста). Созданиеapps/api/.dockerignoreмолча соберёт образ безmain.jsиdata-source.js. Отдельной CI-проверки этого нет: если файлов не окажется в образе,migration:show/migration:runна деплое упадут с понятной ошибкой (Cannot find module '/app/data-source.js'или аналогичной). -
Шаги в деплое. После подъёма контейнеров —
migration:showв лог, затемmigration:run -t each, на проде и на стейджинге.
Генерация подключена к сборке через dependsOn, отдельно её запускать не нужно:
yarn nx run api:build # db-migrations-list → main.js → data-source.js
yarn nx run api:db-migrations-list # только перегенерация списка
Запись в migrations.ts идемпотентна: если содержимое не изменилось, файл не переписывается (иначе
api:serve в watch-режиме уходил бы в бесконечный цикл пересборок).
Как добавить миграцию
-
Создать файл в
apps/api/src/<module>/migrations/— вручную или черезtypeorm migration:generate. Имя файла обязано начинаться с 13-значного timestamp:1774001000000-fix-subscription-plan-id-default.ts, а имя класса — оканчиваться тем же timestamp (FixSubscriptionPlanIdDefault1774001000000). TypeORM берёт timestamp какparseInt(className.substr(-13))и игнорирует порядок массива вmigrations.ts, поэтому расхождение суффикса класса и префикса файла означает применение не в том порядке. Генератор проверяет это и валит сборку.migration:generateзапускается из корня воркспейса и требует двух переменных окружения — без них ts-node не подхватитexperimentalDecoratorsи TS-алиасы:TS_NODE_PROJECT=apps/api/tsconfig.app.json \ NODE_OPTIONS="-r tsconfig-paths/register" \ yarn typeorm-ts-node-commonjs migration:generate \ apps/api/src/<module>/migrations/add-something \ -d apps/api/src/config/typeorm.config.tsТе же две переменные задаются один раз в
nx.json→targetDefaultsпод ключомdb-{show,migrate,revert,drop}и подмешиваются в эти четыре таргета. Namespace-паттерн важен:db-*захватил бы ещёdb-snapshot/db-restore/db-migrations-list, которые запускаются обычнымts-nodeиз корня и с api-шным tsconfig сломались бы.Вывод генератора — черновик: он всегда пишет тело строками
queryRunner.query(...), а в проекте DDL оформляется методамиQueryRunner. См. Написание миграций. -
Перегенерировать список:
yarn nx run api:db-migrations-list(или простоyarn nx run api:build). -
Закоммитить оба файла — саму миграцию и
apps/api/src/migrations.ts. -
Проверить локально:
yarn nx run api:db-show(миграция должна появиться в списке), затем цикл накат → откат → накат — см. Проверка перед коммитом.
Генератор падает с ненулевым кодом, если: в файле нет export class; в файле больше одного
export class; имя файла не начинается с 13-значного timestamp; суффикс имени класса не совпадает с
префиксом имени файла; два файла дают одинаковое имя класса. Так как он висит на dependsOn у
build, любая из этих ошибок валит сборку. Отсутствие каталогов migrations — не ошибка: список
тогда пустой.
Файлы-спутники (*.d.ts, *.spec.ts, *.test.ts) в директории миграций игнорируются и
генератором, и tools/checkDataSource.ts — последний вызывает readMigrations() генератора, так
что правило фильтрации физически одно.
Локальные команды
| Команда | Что делает |
|---|---|
yarn nx run api:db-migrations-list |
перегенерировать статический список |
yarn nx run api:db-show |
список миграций и их статус |
yarn nx run api:db-migrate |
применить непримененные |
yarn nx run api:db-revert |
откатить последнюю применённую |
yarn nx run api:db-drop |
удалить схему целиком (schema:drop) |
yarn nx run api:db-snapshot |
снять снимок данных в JSON |
yarn nx run api:db-restore |
восстановить данные из снимка |
Все они, кроме db-migrations-list (он работает только с файлами), подключаются к БД из .env
(POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB / POSTGRES_HOST / POSTGRES_PORT).
Отдельную базу можно подставить переменной окружения — dotenv работает с override: false,
поэтому окружение имеет приоритет над .env:
POSTGRES_DB=aigeo_migtest yarn nx run api:db-migrate
Проверки в CI
.gitea/workflows/ci.yaml:
Check migrations list—yarn ts-node tools/buildDataSource.ts --check. Генератор рендерит список, сравнивает с содержимымapps/api/src/migrations.tsи падает при расхождении, ничего не записывая. Сравнение идёт с тем же отформатированным текстом, что и запись, поэтому git в проверке не участвует вовсе.Check data-source(послеyarn build) —yarn ts-node tools/checkDataSource.tsзагружает собранныйapps/api/dist/data-source.js, проверяет, что экспорт ведёт себя какDataSource(initialize()+ объектoptions), и что список классов в бандле посимвольно совпадает с тем, что даётreadMigrations()генератора по файлам на диске (там же валидируются 13-значные timestamp-суффиксы имён классов).
Оба шага идут до сборки docker-образов: битый data-source не попадёт в реестр. Оба
продублированы в .gitea/workflows/production.yaml — теги не проходят через ci.yaml (он
срабатывает на push в master и на PR), поэтому свою копию проверок прод-путь обязан иметь.
⚠️ SQL миграций попадает в логи job
MigrationRunCommand принудительно выставляет logging: ["query", "error", "schema"] поверх
настроек DataSource, отключить это флагом или из typeorm.config.ts нельзя. Каждый выполненный
запрос — вместе со значениями параметров — уходит в лог job деплоя, видимый любому, у кого есть
доступ на чтение репозитория.
Это ограничение принято осознанно: тот же лог — основной инструмент разбора инцидента (см. Runbook, шаг 1). Но из него следует жёсткое правило для авторов миграций:
Data-миграции не должны переносить секреты и персональные данные литералами. Если миграции нужно
изменить пароли, токены, email-адреса и т. п. — делайте это выражениями на стороне SQL
(UPDATE … SET token = encode(gen_random_bytes(32), 'hex')), а не INSERT/UPDATE с готовыми
значениями в тексте миграции. Разовые операции с реальными данными выполняйте вручную через
docker exec (раздел «Ручной запуск миграций на проде»), а не деплоем.
Применение на стейджинге
Job deploy-staging в .gitea/workflows/ci.yaml (запускается на каждом PR и push в master), сразу
после docker compose up -d:
migration:show(в лог), затемmigration:run -t each— черезdocker compose exec -T api …. Отдельного ожидания готовности контейнера нет: живой/healthy HTTP-слой NestJS дляtypeorm migration:runне нужен, он идёт отдельным процессом черезdata-source.js. Если контейнер всё же не поднялся (например, при пустыхPOSTGRES_*),docker compose execупадёт с понятной ошибкой сам.docker system prune -f— после миграций, одним вызовом в конце скрипта. Еслиmigration:runупадёт, подset -eprune не выполнится — почистится на следующем деплое.
Ненулевой код валит job: у шага стоит script_stop: true — действие открывает скрипт строкой
set -e, поэтому упавшая команда завершает его с её кодом выхода, а не продолжает выполнение.
База и переменные .env на стейджинг-хосте
Роль и базу стенда создаёт staging-db-postgres на стейджинг-хосте — шаг deploy-staging в
ci.yaml, до docker compose up:
staging-db-postgres create <org/project> <branch>
Имя роли и БД — <org_project_branch> после нормализации (всё не-алфанумерическое заменяется на
_, длиннее 63 байт — обрезается с хешем). Пароль генерируется при первом создании и
переиспользуется при повторных деплоях ветки. Доступы инструмент пишет в .env каталога деплоя
(~/<repo>_<branch>/): POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, POSTGRES_HOST,
POSTGRES_PORT. Те же имена docker-compose.staging.yml пробрасывает в api, их единственные читают
и приложение (typeorm.config.ts), и typeorm CLI. При удалении ветки или закрытии PR — с вливанием
или без — cleanup.yaml вызывает staging-db-postgres delete: удаляются БД, роль и строки
POSTGRES_* из .env.
В compose переменные объявлены через ${POSTGRES_HOST:-}, то есть не обязательные. Обязательный
синтаксис ${POSTGRES_HOST:?…} здесь применять нельзя: он валит любую подкоманду compose, включая
pull и down, — а полуподнятый стек надо уметь погасить.
concurrency.cancel-in-progress в ci.yaml оставлен true (в отличие от прода). Группа привязана
к ветке, поэтому отменяется только предыдущий прогон той же ветки, а быстрая итерация по PR важнее.
Плата реальна: отмена посреди migration:run -t each оставит базу ветки частично мигрированной
(лечится повторным прогоном job).
Применение на проде
Job deploy-production в .gitea/workflows/production.yaml, шаг Deploy via SSH — тот же
jt4d-lab/ssh-action, что и на стейджинге, плюс workdir: /srv/jt4d и
files: docker-compose.production.yml: компоуз-файл приезжает тем же шагом, отдельного scp нет.
Порядок:
docker-compose pull→down→up -d.- Сразу после
up -d—migration:show(в лог видно, что именно будет применено), затемmigration:run -t each. Последняя команда скрипта, её код выхода уходит черезsshи валит job.
Ожидания готовности контейнера между шагами 1 и 2 нет, и это намеренно:
- postgres поднимается до api — у api стоит
depends_on: postgres: condition: service_healthy, так чтоup -dне вернётся, пока БД не готова; docker execсам падает, если контейнер неrunning, — отдельная проверка того же лишь дублировала бы это раньше по времени и потому менее достоверно (сrestart: unless-stoppedкрешлупящий контейнер периодически бываетrunning);- ждать
healthyне нужно тем более: healthcheck образа (curl /api/health,start-period=15s) поднимает HTTP-слой NestJS, аmigration:runидёт отдельным процессом со своим соединением черезdata-source.js.
Логи приложения при провале смотрятся на хосте: docker logs jt4d_api --tail 50.
⚠️ migration:show — не безобидная команда «только посмотреть»:
showMigrations()вызываетcreateMigrationsTableIfNotExist()(typeorm/migration/MigrationExecutor.js), то есть выполняет настоящийCREATE TABLE "migrations", если таблицы ещё нет;MigrationShowCommandзавершается кодом0только на успешном пути. Вcatchстоитprocess.exit(1)— например, приpermission denied for schema publicуaigeo_app.
Под set -e это означает, что деплой упадёт уже на migration:show, если у aigeo_app нет прав на
DDL, — и упадёт после того, как новый образ ушёл на трафик.
concurrency.group этого workflow — константа production-deploy, а не имя ref. Workflow
запускается по тегам, и группа с тегом в имени давала бы каждому тегу собственную группу: два тега
подряд запустили бы два migration:run -t each параллельно по одной БД, а кросс-процессной
блокировки у TypeORM нет. cancel-in-progress: false — отмена job посреди набора рвёт SSH-сессию и
оставляет БД частично мигрированной.
VERSION и LOG_LEVEL передаются в remote-скрипт через env: шага и вход envs:, а не
подстановкой ${{ … }} в тело скрипта: VERSION приходит из git-тега, а в имени ref допустимы
кавычки, ;, $ и обратные кавычки — шаблонизатор вписал бы их в текст скрипта до запуска шелла.
envs к тому же всегда оборачивает значение в одинарные кавычки. Оба значения валидируются по
белому списку символов (VERSION — в job build, LOG_LEVEL — отдельным шагом перед деплоем).
Почему -t each
Каждая миграция выполняется в своей транзакции, а не весь набор в одной длинной. Это осознанное решение: не держим блокировки на всё время деплоя. Плата — при провале на N-й миграции первые N−1 остаются применёнными, БД оказывается в промежуточном состоянии. Разбор такого состояния ручной.
Почему миграции после up -d, а не до
Осознанное решение. Риск не в нескольких секундах старой схемы, а в том, что при провале миграции
новый образ продолжает обслуживать трафик против старой схемы бесконечно
(restart: unless-stopped). Именно поэтому деплой логирует предыдущий тег образа, а ниже описан
runbook отката.
⚠️ Автоматического бэкапа перед миграцией нет
Деплой не снимает дамп БД перед запуском миграций. Это вынесено в отдельную задачу и на момент написания не реализовано.
Существующий cron-бэкап (apps/api/src/database/backup.service.ts + backup-scheduler.service.ts)
на прод рассчитывать нельзя: в apps/api/Dockerfile нет postgresql-client, а BACKUP_DIR не
смонтирован томом в docker-compose.production.yml.
Практический вывод: если содержимое БД критично, снимите дамп вручную перед запуском прод-деплоя. При разборе инцидента не рассчитывайте на существование свежей резервной копии.
Runbook: миграция упала на проде
Из-за -t each набор может быть применён частично. Порядок разбора:
-
Определить, до какой миграции дошли. В логе job шаг
Применение миграцийпечатает каждую применённую миграцию с еёSTART TRANSACTION/COMMIT. Последняя успешная строка — граница; следующая за ней миграция и есть упавшая, там же лежит текст ошибки от Postgres. -
Сверить с реальным состоянием БД:
ssh <prod> docker exec jt4d_api node_modules/.bin/typeorm migration:show -d data-source.js[X]— применена,[ ]— нет. Этот вывод — источник истины, а не лог job. -
Решить, катить вперёд или чинить.
- Ошибка разовая (таймаут, блокировка, нехватка прав) — починить причину и повторить
migration:run -t eachвручную (см. ниже). Уже применённые миграции пропустятся. - Ошибка в самой миграции — исправлять кодом: новая миграция поверх либо правка упавшей с последующим передеплоем. Ручные правки схемы мимо миграций оставляют прод и репозиторий в расхождении, и следующий деплой упадёт снова.
- Ошибка разовая (таймаут, блокировка, нехватка прав) — починить причину и повторить
-
Откатить образ, если сервис сломан. Предыдущий тег — это предыдущий тег
v*в репозитории (git tag --sort=-creatordate | head); что именно скачано на хост, видно вdocker images git.jt4d.ru/jt4d/jt4d/api:cd /srv/jt4d VERSION=<prev> docker-compose up -d⚠️ Один
VERSIONприменяется сразу кwebиapi. Команда корректна только если оба образа тегированы синхронно (обычный случай — их собирает один прогонproduction.yaml). Если теги разошлись, поднимайте сервисы по одному (VERSION=<prev> docker-compose up -d api).Откат образа не откатывает схему БД — применённые миграции остаются применёнными. Если старый код несовместим с новой схемой, откатывать схему придётся отдельно (
migration:revert, по одной миграции за вызов) или восстанавливать из ручного дампа. -
Проверить результат:
/api/healthиdocker logs jt4d_api --tail 100.
Ручной запуск миграций на проде
Понадобится, если миграции нужно применить вне деплоя (повтор после разбора инцидента, разовая
операция). Порт postgres наружу не проброшен, поэтому всё делается через docker exec внутри
контейнера api — WORKDIR образа /app, там же лежат data-source.js и node_modules:
ssh <prod>
# посмотреть, что применится
docker exec jt4d_api node_modules/.bin/typeorm migration:show -d data-source.js
# применить
docker exec jt4d_api node_modules/.bin/typeorm migration:run -t each -d data-source.js
# откатить последнюю применённую (по одной за вызов)
docker exec jt4d_api node_modules/.bin/typeorm migration:revert -d data-source.js
Перед запуском учтите, что автоматического бэкапа нет (см. выше).
Права на БД
Api ходит в прод-БД под aigeo_app — это не владелец схемы. Первое, обо что упадёт migration:run
в свежем окружении, — нехватка прав на DDL. Проверяется пробным CREATE TABLE _ddl_probe(...) /
DROP TABLE _ddl_probe из-под aigeo_app.
Если схема уже содержит объекты из миграций, а записей в таблице migrations нет, migration:run
попытается создать существующее и упадёт. Такое состояние надо забаселайнить — проставить записи
без выполнения up().
Полный baseline (вся схема уже соответствует всем непримененным миграциям) — штатный флаг
TypeORM --fake / -f (MigrationRunCommand, MigrationExecutor):
docker exec jt4d_api node_modules/.bin/typeorm migration:show -d data-source.js # сначала посмотреть список
docker exec jt4d_api node_modules/.bin/typeorm migration:run --fake -d data-source.js
--fake вставляет записи в таблицу migrations, не выполняя up(). Он применяется ко всему
набору непримененных миграций сразу, выборочно пометить одну нельзя. Поэтому использовать его можно
только когда migration:show показывает [ ] ровно у тех миграций, объекты которых в схеме уже
есть.
Частичный baseline (часть непримененных миграций в схеме есть, часть — нет): --fake не
подходит, записи проставляются вручную по одной:
INSERT INTO migrations (timestamp, name) VALUES (1764100000000, 'AddPublicMetricRequests1764100000000');
name — имя класса точь-в-точь, timestamp — числовой префикс из имени файла (он же обязан
совпадать с 13-значным суффиксом имени класса — это проверяет генератор). Ошибка в name не
диагностируется ничем: миграция либо молча выполнится повторно, либо будет пропущена навсегда.
Перед первым прод-деплоем
Прод-деплой применяет миграции на каждый тег — поэтому проверки ниже делаются до первого деплоя с миграциями, а не после:
- проверить права
aigeo_appна DDL: пробныйCREATE TABLE _ddl_probe(...)/DROP TABLEиз-под него (раздел «Права на БД» выше). Без них деплой упадёт уже наmigration:show; - привести таблицу
migrationsв согласованное состояние — baseline, если схема уже содержит объекты из непримененных миграций (там же). Иначе первая же миграция упадёт наrelation already exists, а с-t eachнабор останется применённым частично; - снять ручной дамп БД — автоматического бэкапа нет (см. выше).
То же самое верно для первого деплоя на стейджинге (раздел «Применение на стейджинге»).