Files
it-smi/docs/90-deploy/10-migrations.md
T
arswarog 7d5156d92e
CI / Сборка (push) Failing after 5s
CI / Деплой на стейджинг (push) Skipped
CI / Проверка кода (push) Skipped
CI / Документация (push) Skipped
speckit: внедрение Spec Kit и фиксация архитектуры в конституции JT4D v1.0.0
- Интеграция 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>
2026-11-10 16:44:48 +03:00

30 KiB

Миграции базы данных

Миграции TypeORM применяются автоматически при деплое — и на проде (на каждый тег), и на стейджинге (на каждый push/PR); деплой падает, если миграция не прошла. См. База и переменные .env на стейджинг-хосте.

⚠️ Перед первым прод-деплоем убедитесь, что aigeo_app имеет права на DDL и что таблица migrations согласована со схемой — см. Права на БД. Автоматического бэкапа перед миграцией нет.

Схема БД в рантайме не синхронизируется: synchronize: false, migrationsRun: false. Единственный способ изменить схему — миграция.

Как писать саму миграцию (API QueryRunner, down, data-миграции) — Написание миграций.

Как это устроено

Webpack не умеет runtime-glob: запись migrations: ['*.js'] внутри бандла не работает в принципе. Поэтому список миграций генерируется статически на этапе сборки.

  1. Кодогенерация. tools/buildDataSource.ts сканирует apps/api/src/**/migrations/*.ts (миграции лежат по модулям — apps/api/src/<module>/migrations/), вытаскивает имена экспортируемых классов и пишет apps/api/src/migrations.ts со статическими импортами. Сортировка — по числовому timestamp из имени файла (возрастание) независимо от модуля. Результат прогоняется через Prettier внутри генератора и коммитится в репозиторий.

  2. Единый DataSource. apps/api/src/config/typeorm.config.ts берёт migrations из сгенерированного файла. Один и тот же файл работает локально через typeorm-ts-node-commonjs и в собранном виде внутри контейнера.

  3. Отдельный бандл. 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' или аналогичной).

  4. Шаги в деплое. После подъёма контейнеров — 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-режиме уходил бы в бесконечный цикл пересборок).

Как добавить миграцию

  1. Создать файл в 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. См. Написание миграций.

  2. Перегенерировать список: yarn nx run api:db-migrations-list (или просто yarn nx run api:build).

  3. Закоммитить оба файла — саму миграцию и apps/api/src/migrations.ts.

  4. Проверить локально: 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:

  1. migration:show (в лог), затем migration:run -t each — через docker compose exec -T api …. Отдельного ожидания готовности контейнера нет: живой/healthy HTTP-слой NestJS для typeorm migration:run не нужен, он идёт отдельным процессом через data-source.js. Если контейнер всё же не поднялся (например, при пустых POSTGRES_*), docker compose exec упадёт с понятной ошибкой сам.
  2. docker system prune -f — после миграций, одним вызовом в конце скрипта. Если migration:run упадёт, под set -e prune не выполнится — почистится на следующем деплое.

Ненулевой код валит 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 нет. Порядок:

  1. docker-compose pull → down → up -d.
  2. Сразу после 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 набор может быть применён частично. Порядок разбора:

  1. Определить, до какой миграции дошли. В логе job шаг Применение миграций печатает каждую применённую миграцию с её START TRANSACTION / COMMIT. Последняя успешная строка — граница; следующая за ней миграция и есть упавшая, там же лежит текст ошибки от Postgres.

  2. Сверить с реальным состоянием БД:

    ssh <prod>
    docker exec jt4d_api node_modules/.bin/typeorm migration:show -d data-source.js
    

    [X] — применена, [ ] — нет. Этот вывод — источник истины, а не лог job.

  3. Решить, катить вперёд или чинить.

    • Ошибка разовая (таймаут, блокировка, нехватка прав) — починить причину и повторить migration:run -t each вручную (см. ниже). Уже применённые миграции пропустятся.
    • Ошибка в самой миграции — исправлять кодом: новая миграция поверх либо правка упавшей с последующим передеплоем. Ручные правки схемы мимо миграций оставляют прод и репозиторий в расхождении, и следующий деплой упадёт снова.
  4. Откатить образ, если сервис сломан. Предыдущий тег — это предыдущий тег 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, по одной миграции за вызов) или восстанавливать из ручного дампа.

  5. Проверить результат: /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 не диагностируется ничем: миграция либо молча выполнится повторно, либо будет пропущена навсегда.

Перед первым прод-деплоем

Прод-деплой применяет миграции на каждый тег — поэтому проверки ниже делаются до первого деплоя с миграциями, а не после:

  1. проверить права aigeo_app на DDL: пробный CREATE TABLE _ddl_probe(...) / DROP TABLE из-под него (раздел «Права на БД» выше). Без них деплой упадёт уже на migration:show;
  2. привести таблицу migrations в согласованное состояние — baseline, если схема уже содержит объекты из непримененных миграций (там же). Иначе первая же миграция упадёт на relation already exists, а с -t each набор останется применённым частично;
  3. снять ручной дамп БД — автоматического бэкапа нет (см. выше).

То же самое верно для первого деплоя на стейджинге (раздел «Применение на стейджинге»).