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

6.2 KiB

Сущности, таблицы и колонки

Расположение сущностей

Все TypeORM-сущности модуля лежат в подпапке entities/ в корне модуля:

apps/api/src/contests/
├── dto/
├── entities/
│   └── contest.entity.ts
├── contests.controller.ts
├── contests.module.ts
└── contests.service.ts
  • Правило без исключений: даже если сущность в модуле одна, она всё равно в entities/. Иначе при добавлении второй сущности пришлось бы переносить первую и править все её импорты.
  • Имя файла — <сущность>.entity.ts в kebab-case (project-member.entity.ts).
  • Один файл — одна сущность.

Имя таблицы — единая точка правды

Рядом с сущностью, в том же файле, объявляется экспортируемая константа с именем таблицы, и @Entity использует её:

export const CONTESTS_TABLE_NAME = 'contests';

@Entity({ name: CONTESTS_TABLE_NAME })
export class Contest {
    // ...
}
  • Константа именуется <СУЩНОСТЬ>_TABLE_NAME в SCREAMING_SNAKE_CASE.
  • Значение — snake_case, множественное число (contests, project_members).
  • @Entity() без явного name не используется: имя таблицы не должно выводиться из имени класса — переименование класса тогда молча меняет схему.

Константа — единая точка правды об имени таблицы для кода приложения: @Entity, DAL, raw-SQL, алиасы createQueryBuilder, утилиты очистки в тестах. Строковый литерал с именем таблицы за пределами объявления константы в коде приложения не пишется.

Миграции константу не используют

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

Пример из репозитория: коммит b710c1b9 удалил модуль подписок вместе с файлом subscriptions/subscription-plan.entity.ts — а миграции 1774000000000-add-subscription-plans.ts и 1788825600000-drop-subscriptions-and-metrics-limits.ts никуда не делись и по-прежнему создают и удаляют таблицу subscription_plans. Импортируй они константу из удалённого файла — сборка встала бы целиком: миграции попадают в бандл data-source.js статическими импортами.

Обратная сторона того же правила: значение константы менять можно, миграции на него не смотрят. Переименование таблицы — это новое значение константы плюс миграция с двумя литералами:

await queryRunner.renameTable('contests', 'brand_contests');

Имена колонок

Колонки — camelCase (logoId, totalBudget, createdAt), в отличие от snake_case у таблиц. Это не разнобой, а следствие дефолтной стратегии именования TypeORM: имя колонки выводится из имени свойства как есть, и в @Column() его не дублируют. С таблицей так нельзя — её имя выводилось бы из имени класса, — поэтому она и задаётся явно.

Практическое следствие: Postgres приводит неэкранированный идентификатор к нижнему регистру, так что в raw-SQL такая колонка пишется только в двойных кавычках:

ALTER TABLE "contests" DROP COLUMN IF EXISTS "totalBudget";

Nullable-колонки — явный type

Если тип свойства — объединение с null, тип колонки задаётся в декораторе явно:

@Column({ type: 'varchar', nullable: true })
banReason: string | null;

@Column({ type: 'timestamp', nullable: true })
emailVerificationTokenExpires: Date | null;

Без type TypeORM выводит тип колонки из метаданных декоратора (design:type), а для объединения string | null TypeScript отдаёт Object — вывести из него тип колонки нельзя, и приложение падает на старте с ColumnTypeUndefinedError ещё до первого запроса. Ошибка вылезает только при реальном поднятии контекста: юнит-тесты сервиса метаданные сущностей не строят и остаются зелёными.

Само объявление string | null при этом предпочтительнее, чем string у nullable-колонки: тип сущности должен отражать то, что лежит в базе, иначе «пустое» значение приходится проверять вопреки типу. Схему явный type не меняет — varchar без длины это то же character varying, что и в миграции, — так что переход на | null у уже существующей колонки миграции не требует.

Как писать сами миграции — Написание миграций.