Database Migration И Seeding Rules

Назначение

Документ задает правила изменения схемы PostgreSQL, ClickHouse, Elasticsearch indexes и seed/reference data.

Общие Правила

• Миграция принадлежит только owning service.
• Сервис не меняет таблицы другого сервиса.
• Изменения схемы проходят через Migrator project или documented migration runner.
• Production migration должна быть forward-compatible с предыдущей версией приложения во время rolling deploy.
• Destructive migration требует ADR, backup/rollback plan и approval domain owner-а.

EF/PostgreSQL

Правило	Требование
Naming	yyyyMMddHHmm_<Feature>_<Intent>.
Id columns	uuid/Guid для aggregate roots, typed ids в коде.
Tenant columns	tenant_id обязателен для tenant-scoped data.
Money	numeric(19, 8) или service-specific precision, описанная в finance docs.
Concurrency	mutable aggregates используют version/row version.
JSONB	только typed versioned documents с документацией модели.

Safe Migration Pattern

1. Добавить nullable column/table/index без удаления старого поля.
2. Выполнить backfill отдельной idempotent job/migration step.
3. Выпустить код, который пишет новое и читает backward-compatible.
4. Переключить чтение на новую модель.
5. Удалить старое поле отдельной release wave после проверки.

Migration Types

Тип	Пример	Требования
Additive	новая таблица/nullable колонка/index	Standard review.
Backfill	заполнить новое поле из старого	Idempotent job, checkpoint, metrics.
Transform	изменить формат JSONB/snapshot	Backward-compatible reader, versioned writer.
Destructive	drop column/table, shrink enum	ADR, backup, approval, rollback plan.
Performance	index/materialized view	Explain plan, lock impact, rollout window.

Pre-Migration Checklist

• ownership таблицы/индекса подтвержден;
• migration name описывает feature и intent;
• оценен lock impact и время выполнения;
• есть dry run на актуальной schema;
• есть rollback/forward-fix plan;
• affected API/events/read models documented;
• для financial/security changes есть domain owner approval;
• для production есть maintenance/rolling deploy plan.

Seed Data

Seed делится на:

• ReferenceData: сервисные справочники и статические словари; страны/регионы/города/валюты/языки не сидятся — реплицируются из Talent Handbook в контекст handbook синком (ADR-0063);
• PermissionDefinitions: permission scope definitions из Identity;
• SystemRoles: базовые роли platform/admin/partner;
• ProviderDictionaries: provider-specific mappings без secrets;
• DemoData: только для local/dev, запрещено в production seed.

Seed должен быть идемпотентным: повторный запуск не создает дубликаты и не перетирает tenant-specific изменения без явного owner decision.

Seed Ownership

Seed	Owner	Где Менять
ReferenceData	Сервис-владелец справочника	Только owner service/migrator; гео/валюты/языки — не seed, а синк handbook (ADR-0063).
PermissionDefinitions	Identity service	Permission catalog + Identity migrator.
SystemRoles	Identity service	Role docs + Identity migrator.
ProviderDictionaries	Owning integration service	Provider adapter docs + migrator.
DemoData	Local/dev tooling	Никогда не production migrator.

Seed не должен делать внешний provider call.

Elasticsearch Indexes

• Index schema описывается как typed document model.
• Index version включается в alias strategy: games-v3, alias games-current.
• Reindex job идемпотентен и имеет progress checkpoint.
• Alias switch выполняется атомарно.

ClickHouse

• Facts имеют explicit event/fact version.
• Backfill jobs имеют диапазон времени, checkpoint и reconciliation report.
• Materialized views меняются через additive strategy.
• Freshness SLA описан в analytics docs.

Rollback Strategy

Rollback в production предпочтительно делается forward-fix migration. Direct down migration допустима только если:

• данные не потеряются;
• миграция не уже использована новой версией приложения;
• rollback проверен на staging;
• есть approval release owner-а.

Для irreversible changes пишется IrreversibleReason и recovery plan.

Tests И Verification

• migration dry run в CI для changed service;
• integration test с Testcontainers для critical schema;
• seed idempotency test;
• backward compatibility test для JSONB reader-а;
• Elasticsearch mapping compatibility test;
• ClickHouse ingestion/backfill smoke test для analytics changes.

Обратные ссылки

Автоссылки: где используется этот документ.

• backend-shared-standards-index.md (1): Backend Shared Standards Index