# Написание миграций Здесь — как **писать** миграцию. Про то, как список миграций собирается, как они применяются на деплое и какие есть команды, см. [Миграции базы данных](../90-deploy/10-migrations.md). ## DDL пишется через API TypeORM, а не строкой SQL Схема меняется методами `QueryRunner` с объектами `Table` / `TableColumn`. Строка SQL в `queryRunner.query()` — крайняя мера, а не способ по умолчанию. ```ts import { MigrationInterface, QueryRunner, Table } from 'typeorm'; export class AddContests1790000000000 implements MigrationInterface { name = 'AddContests1790000000000'; public async up(queryRunner: QueryRunner): Promise { await queryRunner.createTable( new Table({ name: 'contests', columns: [ { name: 'id', type: 'int', isPrimary: true, isGenerated: true, generationStrategy: 'increment', }, { name: 'title', type: 'varchar', length: '255', isUnique: true }, { name: 'logoId', type: 'varchar', length: '64', isNullable: true }, { name: 'description', type: 'text' }, { name: 'totalBudget', type: 'int' }, { name: 'createdAt', type: 'timestamp', default: 'now()' }, { name: 'updatedAt', type: 'timestamp', default: 'now()' }, ], }), ); } public async down(queryRunner: QueryRunner): Promise { await queryRunner.dropTable('contests'); } } ``` У `createTable` есть второй аргумент `ifNotExist`, и ставить его в `true` не надо: он глушит ровно ту ошибку, ради которой существует [проверка перед коммитом](#проверка-перед-коммитом) — если `down` отработал не полностью и оставил таблицу, повторный `up` с `ifNotExist: true` пройдёт мимо дефекта молча. Дважды одна и та же миграция не применяется и без флага, за этим следит таблица `migrations`. Имя таблицы — строковый литерал: константа `*_TABLE_NAME` из файла сущности в миграциях не используется, см. [Миграции константу не используют](10-persistence.md#миграции-константу-не-используют). ### `migration:generate` — это черновик `typeorm migration:generate` (запуск — в [Как добавить миграцию](../90-deploy/10-migrations.md#как-добавить-миграцию)) всегда выдаёт тело из строк `queryRunner.query(...)`, иначе он не умеет. Генератор полезен тем, что показывает полный список расхождений схемы с сущностями — руками их легко не заметить. Но сгенерированный файл дописывается до конца: DDL переписывается на методы `QueryRunner`, строкой SQL остаётся только то, что под них не подходит. ### Когда допустим `queryRunner.query()` Там, где API TypeORM нужную конструкцию не выражает. Типичные случаи: частичные и функциональные индексы (`WHERE`, `lower(...)`), `ALTER COLUMN TYPE ... USING`, `CREATE INDEX CONCURRENTLY`, `CREATE EXTENSION`, любые запросы к данным. В таком месте ставится комментарий, почему используется строка SQL. ## `down` пишется всегда Обратный метод обязателен для каждой миграции: `db-revert` — штатная команда проекта, и откат должен работать не только на бумаге. Если операция необратима по природе (удаление колонки с данными, добавление значения в enum-тип), у `down` есть два варианта: упасть с ошибкой либо откатить схему с потерей данных. Что из этого уместно, решается при написании конкретной миграции и фиксируется комментарием. Первый вариант — откат запрещён: ```ts export class DropContestDescription1790000001000 implements MigrationInterface { name = 'DropContestDescription1790000001000'; public async up(queryRunner: QueryRunner): Promise { await queryRunner.dropColumn('contests', 'description'); } public async down(): Promise { // откат невозможен: значения удалённой колонки восстановить неоткуда throw new Error('DropContestDescription1790000001000 необратима'); } } ``` Второй — та же миграция, но откат разрешён с потерей данных: ```ts public async down(queryRunner: QueryRunner): Promise { // колонка возвращается пустой: прежние значения теряются await queryRunner.addColumn( 'contests', new TableColumn({ name: 'description', type: 'text', isNullable: true }), ); } ``` ## Проверка перед коммитом Миграция считается проверенной, только если на локальной БД прошёл полный цикл: ```bash yarn nx run api:db-migrate # накатить yarn nx run api:db-revert # откатить yarn nx run api:db-migrate # накатить снова ``` Все три шага должны отработать без ошибок. Второй накат ловит самый частый дефект — `down`, который отработал не полностью и оставил в базе объект, на который потом спотыкается `up`. Исключение — миграция, `down` которой намеренно падает: для неё проверяется только накат. ## Data-миграции — отдельным файлом Изменение схемы и перенос/заполнение данных не смешиваются в одной миграции. Причина: миграция схемы откатывается механически, а data-миграция часто необратима в принципе; в одном файле необратимой становится вся пара. Порядок для задачи «добавить колонку и заполнить её»: сначала миграция схемы, затем отдельной миграцией — бэкфилл данных.