migrations

kaname — миграции

Schema kaname. Число миграций здесь НЕ выписано намеренно: оно росло с каждой задачей, а строка с ним не правилась ни разу — на момент этой правки документ утверждал двадцать четыре при ста семнадцати файлах в каталоге. Перечень получают предикатом, а не памятью:

ls services/iam/internal/migrations/*.sql | wc -l

Номера в каталоге принадлежат трём эрам сразу (0001_initial.sql и далее по возрастанию — ранняя; затем выведенные из номера задачи; затем по метке времени). Смешение законно: переномеровать применённое нельзя.

Форма НОВОЙ миграции — метка времени заведения YYYYMMDDHHMMSS_<имя>.sql (date -u +%Y%m%d%H%M%S). Объявлена она в ОДНОМ месте и здесь НЕ переписывается: docs/architecture/migration-version-namespace.md — там же названо, чем закрыты доводы двух прежних форм. Держит форму гейт internal/repohygiene TestNewMigrationOutranksEveryAppliedOne; он судит ТОЛЬКО добавленные относительно ствола файлы. Создают миграции этого каталога:

• core resource model (operations, users, accounts, projects, service_accounts, groups, group_members, roles, access_bindings)
  • default-roles seed (12 system-ролей с детерминированными id);
• governance расширения (access_bindings_jit_eligibility, _jit_pending, break_glass_*);
• federation / identity (federation_*, scim_*);
• чеканку своих токенов — ключница подписных ключей (token_signing_keys: kid, алгоритм, состояние, публичная половина, ОБЁРНУТАЯ приватная половина, срок; «подписывает ровно один» держит частичный уникальный индекс) и отзыв отчеканенного (minted_token_revocations);
• outbox-cluster (fga_outbox, subject_change_outbox, caep_outbox, audit_outbox).

[!note] Прежнее хранилище подписных ключей здесь названо не было, и это не опечатка редакции Оно существовало, стояло в этом перечне и было СНЯТО миграцией: приватную половину не читал обратно никто, а запись в хранилище удавалась — поэтому оно выглядело исправным всё время своей жизни. Имя снятой таблицы в этом перечне не воспроизводится: в перечне действующих таблиц оно читается как действующая координата. Его текст остался в применённых миграциях и в ведомости дропов — там он свидетельство, и править его нельзя.

Ключница задачи #897 названа ИНАЧЕ намеренно. Совпадение имён сделало бы стража ведомости дропов красным СПРАВЕДЛИВО: он увидел бы воскресшую таблицу, которую сам же считает снятой.

CHECK / FK / UNIQUE / partial UNIQUE / триггеры inline в соответствующих миграциях. Helper-функции: kacho_labels_valid(jsonb), iam_permissions_valid(jsonb), триггер group_members_member_exists_trg.

Squash в единый 0001_initial.sql baseline запланирован в Wave M рефакторинга KAC-193 (после Wave D evgeniy-compliance pass).

Запуск

make migrate-up (требует KANAME_DB_PASSWORD=...).

Запреты

• НЕ редактировать примененную миграцию (workspace CLAUDE.md запрет #5) — только новая миграция, и её номер — метка времени заведения (YYYYMMDDHHMMSS_<имя>.sql), а не следующий по порядку. Здесь стояло «следующий — 0025_*»: номер выписан, ни разу не правился и разошёлся с деревом на порядки (в каталоге живут 0092, 484002, 795001), а инкрементная форма к тому же отвергается гейтом формы. Каталог не пересчитывают глазами — предикат выше.
• Таблица operations объявлена в baseline под схемой kaname. Цели, которая «подтягивала бы общую operations», больше нет: она ничего не делала ни в одном сервисе, а копия common-файла создала бы конфликтующий unqualified public.operations.