Конвенции слоёв api и web, работа с БД и миграциями, тесты, деплой миграций, а также оглавление документации и README шаблона.
132 lines
7.4 KiB
Markdown
132 lines
7.4 KiB
Markdown
# Написание миграций
|
|
|
|
Здесь — как **писать** миграцию. Про то, как список миграций собирается, как они применяются на
|
|
деплое и какие есть команды, см. [Миграции базы данных](../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<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` из файла сущности в миграциях не
|
|
используется, см.
|
|
[Миграции константу не используют](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<void> {
|
|
await queryRunner.dropColumn('contests', 'description');
|
|
}
|
|
|
|
public async down(): Promise<void> {
|
|
// откат невозможен: значения удалённой колонки восстановить неоткуда
|
|
throw new Error('DropContestDescription1790000001000 необратима');
|
|
}
|
|
}
|
|
```
|
|
|
|
Второй — та же миграция, но откат разрешён с потерей данных:
|
|
|
|
```ts
|
|
public async down(queryRunner: QueryRunner): Promise<void> {
|
|
// колонка возвращается пустой: прежние значения теряются
|
|
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-миграция часто необратима в принципе; в одном файле необратимой
|
|
становится вся пара.
|
|
|
|
Порядок для задачи «добавить колонку и заполнить её»: сначала миграция схемы, затем отдельной
|
|
миграцией — бэкфилл данных.
|