Files
it-smi/docs/50-developing/20-migrations.md
T
arswarog dbd5762ecf docs: документация по архитектуре, данным и деплою
Конвенции слоёв api и web, работа с БД и миграциями, тесты, деплой
миграций, а также оглавление документации и README шаблона.
2026-10-27 10:43:49 +03:00

7.4 KiB

Написание миграций

Здесь — как писать миграцию. Про то, как список миграций собирается, как они применяются на деплое и какие есть команды, см. Миграции базы данных.

DDL пишется через API TypeORM, а не строкой SQL

Схема меняется методами QueryRunner с объектами Table / TableColumn. Строка SQL в queryRunner.query() — крайняя мера, а не способ по умолчанию.

import { MigrationInterface, QueryRunner, Table } from 'typeorm';

export class AddContests1790000000000 implements MigrationInterface {
    name = 'AddContests1790000000000';

    public async up(queryRunner: QueryRunner): Promise<void> {
        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<void> {
        await queryRunner.dropTable('contests');
    }
}

У createTable есть второй аргумент ifNotExist, и ставить его в true не надо: он глушит ровно ту ошибку, ради которой существует проверка перед коммитом — если down отработал не полностью и оставил таблицу, повторный up с ifNotExist: true пройдёт мимо дефекта молча. Дважды одна и та же миграция не применяется и без флага, за этим следит таблица migrations.

Имя таблицы — строковый литерал: константа *_TABLE_NAME из файла сущности в миграциях не используется, см. Миграции константу не используют.

migration:generate — это черновик

typeorm migration:generate (запуск — в Как добавить миграцию) всегда выдаёт тело из строк 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 есть два варианта: упасть с ошибкой либо откатить схему с потерей данных. Что из этого уместно, решается при написании конкретной миграции и фиксируется комментарием.

Первый вариант — откат запрещён:

export class DropContestDescription1790000001000 implements MigrationInterface {
    name = 'DropContestDescription1790000001000';

    public async up(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.dropColumn('contests', 'description');
    }

    public async down(): Promise<void> {
        // откат невозможен: значения удалённой колонки восстановить неоткуда
        throw new Error('DropContestDescription1790000001000 необратима');
    }
}

Второй — та же миграция, но откат разрешён с потерей данных:

public async down(queryRunner: QueryRunner): Promise<void> {
    // колонка возвращается пустой: прежние значения теряются
    await queryRunner.addColumn(
        'contests',
        new TableColumn({ name: 'description', type: 'text', isNullable: true }),
    );
}

Проверка перед коммитом

Миграция считается проверенной, только если на локальной БД прошёл полный цикл:

yarn nx run api:db-migrate   # накатить
yarn nx run api:db-revert    # откатить
yarn nx run api:db-migrate   # накатить снова

Все три шага должны отработать без ошибок. Второй накат ловит самый частый дефект — down, который отработал не полностью и оставил в базе объект, на который потом спотыкается up.

Исключение — миграция, down которой намеренно падает: для неё проверяется только накат.

Data-миграции — отдельным файлом

Изменение схемы и перенос/заполнение данных не смешиваются в одной миграции. Причина: миграция схемы откатывается механически, а data-миграция часто необратима в принципе; в одном файле необратимой становится вся пара.

Порядок для задачи «добавить колонку и заполнить её»: сначала миграция схемы, затем отдельной миграцией — бэкфилл данных.