docs: документация по архитектуре, данным и деплою
Конвенции слоёв api и web, работа с БД и миграциями, тесты, деплой миграций, а также оглавление документации и README шаблона.
This commit is contained in:
1 parent
9d5478ddeb
commit
dbd5762ecf
10 files changed
+1308
-87
No files matched your search
@@ -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-миграция часто необратима в принципе; в одном файле необратимой
|
||||
становится вся пара.
|
||||
|
||||
Порядок для задачи «добавить колонку и заполнить её»: сначала миграция схемы, затем отдельной
|
||||
миграцией — бэкфилл данных.
|
||||
Reference in new issue
Block a user