Конвенции слоёв api и web, работа с БД и миграциями, тесты, деплой миграций, а также оглавление документации и README шаблона.
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-миграция часто необратима в принципе; в одном файле необратимой становится вся пара.
Порядок для задачи «добавить колонку и заполнить её»: сначала миграция схемы, затем отдельной миграцией — бэкфилл данных.