docs: документация по архитектуре, данным и деплою

Конвенции слоёв api и web, работа с БД и миграциями, тесты, деплой
миграций, а также оглавление документации и README шаблона.
This commit is contained in:
arswarog committed 2026-10-27 10:43:49 +03:00
1 parent 9d5478ddeb
commit dbd5762ecf
10 files changed
+1308 -87

No files matched your search

+131
View File
@@ -0,0 +1,131 @@
# Написание миграций
Здесь — как **писать** миграцию. Про то, как список миграций собирается, как они применяются на
деплое и какие есть команды, см. [Миграции базы данных](../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-миграция часто необратима в принципе; в одном файле необратимой
становится вся пара.
Порядок для задачи «добавить колонку и заполнить её»: сначала миграция схемы, затем отдельной
миграцией — бэкфилл данных.